Configuring Multiple Catalogs

To enable multiple user catalogs in Enterprise Server, and to configure in which catalog a particular dataset's details are held, you must set the following two environment variables:

MFUSERCAT_NODE - this variable holds the node specification or pattern of datasets whose details should be stored in a separate catalog.
MFUSERCAT_LOC - this variable specifies the location and name of each user catalog.

Both MFUSERCAT_NODE and MFUSERCAT_LOC are limited to 4096 characters.

Note: If several user catalogs share the same location, the environment variable MFUSERCAT_BASE_LOC can be used to specify where these catalogs are located, and their entries in the MFUSERCAT_LOC list need only specify the unqualified file names of the user catalog, rather than the full path and file name.

Both variables are required, and can hold multiple entries separated by semi-colons. A value specified in MFUSERCAT_NODE must have a corresponding value in MFUSERCAT_LOC. If the two lists do not contain the same number of entries, JES support for the ES region will not initialize successfully. See the Examples of using multiple catalogs section for more details.

If a specified catalog file does not exist, it is created when the system starts up, but if it cannot be created, the JES system will not start. However, if you set the ES_OPEN_CAT_ON_DEMAND environment variable to Y, an attempt to open a user catalog occurs only when it's required. With this variable set, only the main system catalog (if required) will be created and opened when the region starts. If a specified user catalog does not exist, it will not be created, which means that trying to access it will produce an error (such as file not found or otherwise unavailable), but the missing file will not stop the JES system from starting. When that catalog file is required again, the system will attempt to open it. The result in this process is a system that is more resilient to transient file access problems, such as network connections to remote file systems.

Note: An error accessing a catalog file is reported using error code 9908, and displayed in the ESAMC catalog page, where it displays information about any catalog errors, the catalog file that was being accessed, the file status returned, and whether the file exists or not.

For catalog files that have failed to open, you can use the environment variables ES_CAT_RETRY_COUNT and ES_CAT_RETRY_WAIT to set the number of times to retry the open before reporting the above error and how long to wait between retries (in seconds); however, be careful when setting these variables as they could impact the time taken to report an error and therefore will delay processing of the job whilst the checks take place. These variables can be useful if you experience file access problems that only last a second or two (for example, network connection drop-outs), so that it gives the system a chance to recover before aborting.

If a catalog file access error occurs when running a JCL job the job will abend with code S413 and a message will be included in the step or job output (usually message code 243U)

When Enterprise Server performs a catalog search for a specific dataset, it first compares the dataset name to the patterns defined in MFUSERCAT_NODE. If the name matches one of the defined patterns, it looks in the corresponding catalog file (this is usually named catalog.dat, but can be any name) for the information for that dataset. If the dataset is not found in the selected user catalog, the system catalog will then be searched. Similarly, when a request is made to catalog a new dataset, its name will be compared to the patterns defined in MFUSERCAT_NODE, and if a match is found, it will be cataloged in the corresponding user catalog. If no match is found, it will be cataloged in the system catalog.

The ESMAC catalog list function will search all available catalogs for datasets matching the search pattern, without reference to the node list, and display the resulting dataset list in alphabetical order.