CATALOG and CATALOGxxxx sections of the DFSDFxxx member

The CATALOG and CATALOGxxxx sections contain options for an IMS catalog. The section headers must be specified as <SECTION=CATALOG> or <SECTION=CATALOGxxxx>. The CATALOG and CATALOGxxxx sections are valid in DB/DC, DBCTL, Start of changeDCCTLEnd of change and batch environments.

Use the CATALOG section header to specify options for the IMS catalog in a single-system environment or in a data sharing environment where a single IMS catalog supports multiple IMS systems. In a data sharing environment, the CATALOG section defines the IMS catalog for all IMS systems, except those IMS systems for which a CATALOGxxxx section is defined.

Use the CATALOGxxxx section header to specify options for an IMS catalog in a data sharing environment where multiple IMS systems share a single DFSDFxxx member, but do not share a single IMS catalog. Specify one CATALOGxxxx section for each IMS system that shares this DFSDFxxx member and that requires a unique IMS catalog. The section header must be specified as <SECTION=CATALOGxxxx>, where xxxx is the IMS ID of the IMS system that the IMS catalog supports.

A DFSDFxxx member can contain any number of CATALOGxxxx sections, but only one CATALOG section.

Unless the Catalog Definition exit routine (DFS3CDX0) is used as an alternative, the CATALOG and CATALOGxxxx sections of the DFSDFxxx member are required by the batch jobs and utilities that use the IMS catalog database. This is an exception to the rule that all sections of the DFSDFxxx member of the IMS.PROCLIB data set are optional for batch jobs. Batch utilities do not use CATALOGXXXX sections. The CATALOGxxxx sections enable users to maintain separate catalog sections in a common DFSDFxxx PROCLIB member where a unique CATALOGxxxx section applies to a specific IMS system. This is so that each IMS in an IMS Plex™ can share the same DFSDFxxx PROCLIB member, and be able to specify different catalog attributes. If a CATALOGxxxx section is not provided, the default CATALOG section is used. Batch utilities only use the CATALOG section.

Important: If you are performing a first-time initialization of the CATALOG, you must populate the CATALOG and then restart IMS to complete the initialization.

Syntax

Read syntax diagramSkip visual syntax diagramCATALOG=NOYESALIAS= xxxxACBMGMT=ACBLIBACCESS=READACCESS=UPDATEACBMGMT=CATALOGACCESS=UPDATEACCESS=READAUTOCREATE=NOYESAUTOIMPORT (CREATE)DATACLAS= xxxxxxxxMGMTCLAS= xxxxxxxxSTORCLAS= xxxxxxxx1IXVOLSER= xxxxxx2SMSVOLCT=1nnSPACEALLOC=(PRIMARY=500nnnn,SECONDARY=50nnnn)RETENTION=(INSTANCES=2nnnnn,DAYS=0nnnnnINSTANCES=2nnnnnDAYS=0nnnnn)GURCACHE=1nnnCATPSBATTACH=YES NO
Notes:
  • 1 STORCLAS is required when IMS creates the catalog data sets automatically, because the data sets are managed by SMS.
  • 2 IXVOLSER is required when IMS creates the catalog data sets automatically and catalog data sets are not managed by SMS.

Parameters

The CATALOG and CATALOGxxxx sections of the DFSDFxxx member of the IMS.PROCLIB data set both use the same parameter list and syntax.

ACBMGMT=
Specifies whether IMS manages the active application control blocks (ACBs) in the IMS catalog or your installation manages the ACBs in ACB libraries (ACBLIBs).
You can specify the following values on the ACBMGMT parameter:
ACBLIB
Specifies that the active ACBs are managed by your installation in ACBLIB data sets.

When ACBLIB is in effect, you are required to use the PSB and DBD generation utilities to define your databases and program views. You are also required to use the ACB Maintenance utility to generate the ACBs into an ACBLIB data set. To activate the ACBs in online IMS systems, you must use the online change process.

The following catalog resource members must be included in the PSB and DBD libraries:
  • DFSCD000
  • DFSCX000
  • DFSCPL00
  • DFSCP000
  • DFSCP001
  • DFSCP002
  • DFSCP003

ACBLIB is the default.

CATALOG
Specifies that the active ACBs are managed by IMS in the IMS directory data sets of the IMS catalog.

Do not specify CATALOG until after you create the IMS directory and load it with the active ACBs by running the IMS Catalog Populate utility (DFS3PU00) with the MANAGEDACBS=SETUP statement.

When CATALOG is in effect, you can define your databases and program views by using either the PSB and DBD generation utilities or by using DDL. If you use the IMS generation utilities, you still need to generate the ACBs and load them into the IMS directory by using IMS utilities. If you use DDL, IMS creates the ACBs for you. In either case, any new and changed ACBs that are not activated automatically can be activated in online IMS systems by issuing the IMS type-2 command IMPORT DEFN SOURCE(CATALOG) command.

Specifying CATALOG changes the default access type of the IMS catalog from READ to UPDATE.

ACCESS=
An optional keyword that specifies the access type of the IMS catalog.
The following values are valid for the ACCESS parameter.
READ
The data in the IMS catalog is read-only.

When ACBMGMT=ACBLIB, READ is the default.

UPDATE
The data in the IMS catalog can be updated.

When ACBMGMT=CATALOG, UPDATE is the default.

Start of change
Note: If neither read or update are specified the catalog retains its previous access.
End of change
ALIAS=xxxx

Specifies a 4-character alphanumeric name prefix that is used to address the catalog database. References to the alias name are dynamically replaced with the internal catalog database and catalog secondary index names (DFSCD000 and DFSCX000) at runtime.

This parameter is required for all environments. If you do not want to use catalog aliasing, use DFSC as the alias prefix.

AUTOCREATE=N|Y|NO|YES
For full-function databases, HALDB databases, and DEDB databases. If you are using DDL CREATE statements to define a new database or program view, use this parameter to perform the following functions:
  • Specifies whether IMS automatically loads the ACBs into the IMS directory, activating the ACBs in the online system.
  • Creates runtime attribute blocks.
  • If specified to create a DEDB database, automatically creates area data sets (ADS).

If CREPGM=Y is specified, the program directory control blocks (PDIRs) in the online systems, and the data sets are also created. The runtime attribute blocks will be exported to the repository only if AUTOEXPORT is in force in the DRD definitions. If this parameter is specified for full-function databases, all actions are performed except the creation of the data sets.

Both AUTOCREATE and AUTOIMPORT(CREATE) can be specified at the same time. If both AUTOIMPORT(CREATE) and AUTOCREATE=YES are specified, only AUTOCREATE=YES is processed.

If both AUTOIMPORT(CREATE) and AUTOCREATE=NO are specified, only AUTOIMPORT(CREATE) is processed.

AUTOIMPORT(CREATE)
For full-function databases, HALDB databases, and DEDB databases. If you are using DDL CREATE statements to define a new database or program view, use this parameter to perform the following functions:
  • Specifies whether IMS automatically loads the ACBs into the IMS directory, activating the ACBs in the online system.
  • Creates runtime attribute blocks.

If CREPGM=Y is specified, the program directory control blocks (PDIRs) in the online systems and the data sets are also created. The runtime attribute blocks will be expected to the repository only if AUTOEXPORT is in force in the DRD definitions. If this parameter is specified for full-function databases, all actions are performed except the creation of the data sets.

Both AUTOCREATE and AUTOIMPORT(CREATE) can be specified at the same time. If both AUTOIMPORT(CREATE) and AUTOCREATE=YES are specified, only AUTOCREATE=YES is processed.

If both AUTOIMPORT(CREATE) and AUTOCREATE=NO are specified, only AUTOIMPORT(CREATE) is processed.

CATALOG=
Specifies whether the IMS catalog is enabled or disabled.
NO
The IMS catalog is disabled. This value is the default and is used if no CATALOG section is specified.
YES
The IMS catalog is enabled.
CATPSBATTACH =
Specifies whether or not 3 catalog PCBs are dynamically attached to the end of the user’s PSB. For more information about cases in which dynamic attach should be used, see Application programming with the IMS catalog.
YES
Dynamic attach of the catalog PCBs to the user’s PSB is enabled. This value is the default.
NO
Dynamic attach of the catalog PCBs to the user’s PSB is disabled.
DATACLAS=xxxxxxxx
Data class for automatically generated, SMS-managed catalog data sets.
GURCACHE=
Specifies the amount of storage, in gigabytes, to allocate in 64-bit memory to cache XML documents that are generated as responses to GUR calls. The valid values are 1 - 999. The default is 1.

Only online IMS regions are supported. DCCTL is not supported.

You are required to review the z/OS® systems 64-bit MEMLIMIT and the IMS JCL to determine if a job's MEMLIMIT is set. If none is set, then the default MEMLIMIT is 2 gigabytes. If additional storage is needed then setting the MEMLIMIT value is required to avoid abending due to an RSM storage shortage.

The storage pool is named GURIN64.

IXVOLSER=xxxxxx
Volume serial number for all primary and secondary catalog indexes.
Important: This parameter is required when IMS creates the catalog data sets automatically and catalog data sets are not managed by SMS.
MGMTCLAS=xxxxxxxx
Management class for automatically generated, SMS-managed catalog data sets.
RETENTION=
This optional statement specifies the default retention criteria for the DBD and PSB records in the IMS catalog. These values are used by the IMS Catalog Record Purge utility (DFS3PU10) to remove outdated or unnecessary DBD and PSB segment instances and records from the catalog database.

You can specify the INSTANCES parameter, the DAYS parameters, or both.

DAYS=nnnnn
Specifies the number of days that the DBD and PSB instances in the IMS catalog must be retained before they can be deleted. When the age of a DBD or PSB instance in a DBD or PSB record exceeds this value, the instance is eligible for deletion by the DFS3PU10 utility.

The keyword accepts a decimal value 0 - 65535. When 0 is specified, the age of a DBD or PSB instance is ignored when the DFS3PU10 utility determines the eligibility of an instance for deletion. The default is 0.

INSTANCES=nnnnn
Specifies the number of DBD and PSB instances that must be retained in DBD and PSB records in the IMS catalog before any instances can be deleted.

For DBD instances, if database versioning is used, this value is the number of instances of the DBD that must be retained for each version of the DBD.

When the number of instances exceeds this value, the DFS3PU10 utility deletes the excess instances. The instances with the oldest ACB generation time stamps are selected for deletion. This value is a decimal value 1 - 65535. The default is 2.

VERSIONS=nnnnn
Obsolete. Use the INSTANCES keyword instead. The VERSIONS keyword is supported for compatibility purposes only.
SMSVOLCT=nn
Number of volumes that are created by the Catalog Populate utility for use by SMS-managed data sets. The valid range for this value is 1-20. The default is 1.
SPACEALLOC=(PRIMARY=nnnn SECONDARY=nnnn)
This value is a percentage that is added to the IMS-computed size of the primary and secondary catalog data sets. The default for the primary data set is 500% and the default for the secondary data set is 50%. You can specify any value 0 - 9999 for both parameters.
STORCLAS=xxxxxxxx
Storage class for automatically generated, SMS-managed catalog data sets. Required for SMS-managed catalog data sets.

Example of the CATALOG section with retention criteria

This specification example retains up to four instances of all DBDs and PSBs in all DBD and PSB records in addition to the active instance for at least one year.

//*****************************************************************/
/* IMS Catalog Section                                            */
/******************************************************************/
<SECTION=CATALOG>
CATALOG=Y                                     /*Enable IMS catalog*/
ALIAS=DFSC                      /*Use standard catalog prefix DFSC*/
RETENTION=(INSTANCES=5,DAYS=365)              /*Retention criteria*/
/******************************************************************/
/*                                                                */
/******************************************************************/

Example of the CATALOG section for an unregistered IMS catalog

//*****************************************************************/
/* IMS Catalog Section                                            */
/******************************************************************/
<SECTION=CATALOG>
CATALOG=Y                                     /*Enable IMS catalog*/
ALIAS=DFSC                      /*Use standard catalog prefix DFSC*/
/******************************************************************/
/* Database Section                                               */
/******************************************************************/
<SECTION=DATABASE>
UNREGCATLG=(DFSCX000,DFSCD000) /*Unregistered IMS catalog DB names*/
/******************************************************************/
/*                                                                */
/******************************************************************/