Please enable JavaScript to view this site.

Altova MapForce 2021 Professional Edition

Customizing MapForce

Catalog Files

Scroll Home Prev Top Next More

MapForce supports a subset of the OASIS XML catalogs mechanism (https://www.oasis-open.org/committees/entity/spec-2001-08-06.html). The catalog mechanism enables MapForce to retrieve commonly used DTDs and XML schemas (as well as stylesheets and other files) from local folders instead of resolving them from a public URI. This increases the overall processing speed, enables you to work offline (that is, not connected to a network), and improves the portability of documents.

 

How catalogs work

Catalogs are commonly used to redirect a public DTD or schema reference to a local URI (typically, a local file path). To achieve this, a catalog file in XML format defines a mapping between the public schema URI and a local URI. Whenever MapForce parses an XML document, it looks for the schema URI (or public or system identifier of a DTD, if applicable) inside the catalog file first. If a mapping is found in the catalog file, then that reference will be used and the schema will be read from a local file. If no mapping is found in the catalog file, then the URI of the XML document will be resolved as is.

 

For example, let's suppose that the following XML file must be processed by MapForce.

 

<?xml version="1.0" encoding="UTF-8"?>
<Articles xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Articles.xsd">
  <Article>
    <Number>1</Number>
    <Name>T-Shirt</Name>
    <SinglePrice>25</SinglePrice>
  </Article>
</Articles>

 

Let's also suppose that a catalog.xml file exists somewhere in a local directory (of which MapForce is aware, as further discussed below), and it contains the following line:

 

<catalog>

 <!--...-->
<uri name="http://www.w3.org/2001/XMLSchema-instance.xsd" uri="files/XMLSchema-instance.xsd"/>
<!--...-->
</catalog>

 

On parsing the XML file, MapForce will detect a match for the schema reference http://www.w3.org/2001/XMLSchema-instance.xsd in the catalog file. Consequently, the schema will be loaded from files/XMLSchema-instance.xsd (which is a local path relative to the catalog file). If no mapping were found in the catalog file, then the schema would be loaded from http://www.w3.org/2001/XMLSchema-instance.

 

Root catalog

When MapForce starts, it loads a file called RootCatalog.xml from the "Program Files" directory. RootCatalog.xml contains a list of catalog files, each in a nextCatalog element. These catalog files are looked up and the URIs in them are resolved by MapForce according to the mappings specified in them.

 

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" xmlns:spy="http://www.altova.com/catalog_ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:entity:xmlns:xml:catalog
Catalog.xsd">
  <nextCatalog catalog="%PersonalFolder%/Altova/%AppAndVersionName%/CustomCatalog.xml"/>

  <!-- Include all catalogs under common schemas folder on the first directory level -->
  <nextCatalog spy:recurseFrom="%AltovaCommonFolder%/Schemas" catalog="catalog.xml" spy:depth="1"/>
  <nextCatalog catalog="CoreCatalog.xml"/>
</catalog>

RootCatalog.xml

In the listing above, notice that the following catalogs are listed for lookup:

 

CustomCatalog.xml is the file in which you can create your own mappings. This file is in the following directory: C:\users\<name>\Documents\Altova\MapForce2021. You can add mappings to CustomCatalog.xml for any custom schema if that is not already addressed by the Altova-configured catalog files (see the next bullets).

Multiple catalog.xml files from the %AltovaCommonFolder%/Schemas directory. Each catalog.xml file is inside the directory of a specific schema (such as SVG, DITA, DocBook, WSDL, and so on), and each maps public and/or system identifiers to URIs that point to locally saved copies of the respective schemas.

CoreCatalog.xml contains certain Altova-specific mappings for locating schemas. This file is in the MapForce "Program Files" directory.

 

Note the following:

 

If you intend to modify the CustomCatalog.xml, use only the Supported elements. Also, make sure not to duplicate the already existing mappings, as this could lead to errors.

The catalog.xml file in the %AltovaCommonFolder%\Schemas\schema folder contains references to DTDs that implement older XML Schema specifications. You should not validate your XML Schema documents against either of these schemas. The older XML schema specifications are included solely to provide MapForce with the ability to efficiently resolve the respective schema URIs should you need to work with such documents.

 

Certain directory paths listed above are expressed with the help of environment variables. For a reference table, see Environment variables.

 

Supported elements

When creating entries in CustomCatalog.xml, use only the elements listed below. Other elements of the OASIS XML catalog specification are not supported.

 

Element

Attributes

Example

public

publicId specifies the public identifier of a resource

uri specifies a URI reference (for example, a relative path to a local file)

<public publicId="-//W3C//DTD XMLSCHEMA 200102//EN" uri="files/XMLSchema.dtd"/>

system

systemId specifies the system identifier of a resource

uri specifies a URI reference (for example, a relative path to a local file)

<system systemId="http://www.w3.org/2009/XMLSchema/datatypes.dtd" uri="files/datatypes.dtd"/>

uri

name specifies a URI reference

uri specifies an alternate URI reference (for example, a relative path to a local file)

<uri name="http://www.w3.org/2009/XMLSchema/XMLSchema.xsd" uri="files/XMLSchema.xsd"/>

rewriteURI

uriStartString specifies the starting part of a URI to rewrite

uri specifies the replacement string (for example, a relative path to a local directory)

<rewriteURI uriStartString='http://www.altova.com/schemas/svg/' rewritePrefix='files/'/>

rewriteSystem

systemIdStartString specifies the starting part of a system identifier to rewrite

rewritePrefix specifies the replacement string (for example, a relative path to a local directory)

<rewriteSystem systemIdStartString='http://www.altova.com/schemas/svg/' rewritePrefix='files/'/>

 

The public, system, and uri elements can also take the xml:base attribute, which is used to specify a base URI with respect to which a relative URI would be resolved. For more information, see the XML Catalogs specification (http://www.oasis-open.org/committees/entity/spec-2001-08-06.html).

 

Environment variables

The table below lists all environment variables supported in the nextCatalog element to specify paths to various system locations on Windows.

 

%AltovaCommonFolder%

Full path to the directory used to store files common to all Altova programs. Depending on the platform of your operating system and that of MapForce (32-bit or 64-bit), the path is either C:\Program Files\Altova\Common2021 or C:\Program Files (x86)\Altova\Common2021.

%DesktopFolder%

Full path to the directory used to store file objects on the desktop. A typical path is C:\Users\Username\Desktop.

%ProgramMenuFolder%

Full path to the directory that contains the user's program groups, which are themselves file-system directories. A typical path is C:\Users\Username\AppData\Roaming\Microsoft\Windows\Start Menu\Programs.

%StartMenuFolder%

Full path to the directory that contains the user's Start menu items. A typical path is C:\Users\Username\AppData\Roaming\Microsoft\Windows\Start Menu.

%StartUpFolder%

Full path to the directory that corresponds to the user's Startup program group. A typical path is C:\Users\Username\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup.

%TemplateFolder%

Full path to the directory that serves as a common repository for document templates. A typical path is C:\Users\username\AppData\Roaming\Microsoft\Windows\Templates.

%AdminToolsFolder%

Full path to the file system directory that stores administrative tools for the current user. A typical path is C:\Users\Username\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Administrative Tools.

%AppDataFolder%

The file-system directory that serves as a common repository for application-specific data. A typical path is C:\Users\username\AppData\Roaming.

%FavoritesFolder%

Full path of the "Favorites" directory of the current user. A typical path is C:\Users\Username\Favorites.

%PersonalFolder%

Full path to the "Personal" directory of the current user. A typical path is C:\Users\Username\Documents.

%SendToFolder%

Full path to the directory that contains Send To menu items. A typical path is C:\Users\username\AppData\Roaming\Microsoft\Windows\SendTo.

%FontsFolder%

Full path to the System Fonts directory. A typical path is C:\Windows\Fonts.

%ProgramFilesFolder%

Full path to the Program Files directory. Typical paths are C:\Program Files and C:\Program Files (x86).

%CommonFilesFolder%

Full path to the Common Files directory. A typical path is C:\Users\Public\Public Documents.

%WindowsFolder%

Full path to the Windows directory  (same as the %WINDIR% environment variable). A typical path is C:\Windows.

%SystemFolder%

Full path to the System folder. A typical path is %WINDIR%\system32

%CommonAppDataFolder%

Full path to the file directory containing application data. A typical path is C:\ProgramData.

%LocalAppDataFolder%

Full path to the file system directory that serves as the data repository for local (non-roaming) applications. A typical path is C:\Users\username\AppData\Local.

%MyPicturesFolder%

Full path to the Pictures directory of the current user. A typical path is C:\Users\Username\Pictures.

© 2015-2021 Altova GmbH