ACB Generation and Catalog Populate utility (DFS3UACB)

Use the ACB Generation and Catalog Populate utility (DFS3UACB) to generate ACB members in an IMS ACBLIB data set, create the corresponding metadata records in the IMS catalog, and, if your IMS system manages ACBs, add the resulting ACBs as pending changes to the staging data set of the IMS catalog, all in a single job step.

In IMS systems that manage ACBs by using the catalog, the generation of ACBs into an ACB library is not required. However, you can still use the DFS3UACB utility to generate ACBs and populate the IMS catalog if you have tools or utilities that have not yet been updated for the IMS management of ACBs.

Populating the IMS catalog in the same job step as the generation of the ACB members ensures that the IMS catalog and your ACB library are consistent with each other.

The DFS3UACB utility calls the ACB Maintenance utility to generate ACB members and then, in the same job step, calls the IMS Catalog Populate utility (DFS3PU00) to populate the IMS catalog with records that correspond to the generated ACB members.

You must specify control statements for the ACB Maintenance utility by using the SYSIN DD statement. If you do not specify control statements for the ACB Maintenance utility, DFS3UACB terminates immediately.

You may provide execution parameters for the ACB Maintenance utility. To do so, provide them as execution parameters in the PARM parameter for the DFS3UACB utility. In these parameters do not specify the POSTCOMP option if the ACBCATWK DD statement is used.

You must specify the execution parameters for the DFS3PU00 utility, including the name of the DFSDFxxx PROCLIB member that supports your IMS catalog, by using the DFS3PPRM DD statement. The DFS3UACB utility passes the execution parameters to the DFS3PU00 utility at the start of the population phase.

If the IMS management of ACBs is enabled, you must specify the MANAGEDACBS= control statement on the SYSINP DD statement to make the generated ACBs available to the online IMS system. Depending on the specification, the DFS3PU00 utility either adds the ACBs to the staging data set of the IMS catalog for later activation or, if the IMS system is offline or you are setting up managed ACBs for the first time, adds them directly to the IMS directory data sets. IMS loads the ACBs from the directory data sets during startup.

The DFS3UACB utility can populate the catalog in load mode or in update mode. When load mode is used, any existing records in the IMS catalog are discarded.

The PSB that you specify in the utility JCL determines which access mode the utility uses to access the IMS catalog. You can specify the following PSBs in the DFS3UACB utility JCL:
  • DFSCPL00, to perform an initial load of the IMS catalog
  • DFSCP001, to insert records into an existing IMS catalog
  • DFSCP000, to estimate the space requirements of the IMS catalog data sets

Subsections:

Restrictions

The DFS3UACB utility runs in a stand-alone region under z/OS® control.

The DFS3UACB utility does not accept JCL parameters that are specified on the PARM= keyword of the EXEC= statement. To specify the execution parameters that are required to populate the IMS catalog, use the DFS3PPRM DD statement instead.

If you are running the DFS3UACB utility against more than one version of IMS in separate LPARs in an IMSplex environment, run the utility in separate jobs. For each job, use the SCHENV parameter to ensure that each job goes to the correct LPAR.

Prerequisites

If you are loading an IMS catalog for the first time, ensure that the IMS catalog is properly configured. The following steps must be complete before running the DFS3UACB utility to load an IMS catalog for the first time:
  • The DBD and PSB load modules for the IMS catalog are in your DBD and PSB libraries.
  • The ACB member for the IMS catalog was generated and is in the active ACB library.
  • The IMS catalog HALDB master database and partitions are defined in either the RECON data set or, if the target IMS catalog is not supported by DBRC, in an IMS catalog partition definition data set.
  • The CATALOG section of the DFSDFxxx PROCLIB member is properly coded.

To use the SHARE option to add DOPT PSBs to an online IMS catalog, extended sharing of PDSE data sets must be enabled in z/OS before the Populate utility first sets up the IMS management of ACBs. For more information, see z/OS: Specifying Extended PDSE Sharing in a Multiple-System Environment.

Requirements

IMS conforms to z/OS rules for data set authorization. If an IMS job step is authorized, all libraries used in that job step must be authorized. To run an IMS batch region as unauthorized, a non-authorized library must be concatenated to IMS.SDFSRESL.

You must specify control statements for the ACB Maintenance utility by using the SYSIN DD statement.

You must specify the execution parameters that the DFS3UACB utility passes to the DFS3PU00 utility by using the DFS3PPRM DD statement.

If the IMS management of ACBs is enabled, you must specify the MANAGEDACBS= control statement on the SYSINP DD statement to make the generated ACBs available to the online IMS system.

Recommendations

If you are updating an existing IMS catalog, consider creating an image copy of the IMS catalog data sets. If the IMS catalog is registered with DBRC, you can use the DBRC command GENJCL.IC to back up the catalog. If you defined the IMS catalog in an IMS Catalog partition definition data set, you must use standard image copy JCL.

The storage requirement is highly dependent on the total number of ACBLIB members because they have to be kept in storage. Consider increasing the job's region size to prevent a GETMAIN failure that will cause abend U1002 reason code 4 to be issued.

Input and output

The DFS3UACB utility uses the following input and output data sets.

Required data sets:
  • IMS.ACBLIB data set. After creating the ACB members in the ACBLIB data set, the utility uses the ACBLIB data set as input when creating the records in the IMS catalog.
  • DBDLIB data set.
  • PSBLIB data set.
  • ACBCATWK data set. The ACBCATWK data set is both an input and output data set. The ACB Maintenance utility uses it as an output data set to record the ACB members that are generated. The DFS3PU00 utility reads the ACBCATWK data set as input to improve performance when populating the IMS catalog.
  • IMS.PROCLIB data set. The DFS3UACB utility reads the DFSDFxxx member in the IMS.PROCLIB data set.
  • SYSIN control statements.
  • An input data set or inline statement that contains execution parameters for the DFS3PU00 utility, which the DFS3UACB utility calls internally to populate the IMS catalog. This data set or inline statement is specified by using a DFS3PPRM DD statement.
  • SYSPRINT messages.
Optional data sets:
  • An input data set of COMPCTL IEBCOPY control statements.

The primary output of the DFS3UACB utility is the ACB library members and the records of the IMS catalog. The utility loads the ACB members into the inactive IMS.ACBLIB data set. The catalog records are stored in the IMS catalog data set (DFSCD000).

Optionally, the DFS3UACB utility can output a list of the generated ACB members to a data set referenced by the ACBCATWK DD statement. Maintaining a list of the generated ACB members greatly improves the performance of the population phase of the DFS3UACB utility.

The DFS3UACB utility also writes messages and statistical information to the SYSPRINT data set.

The DFS3UACB utility outputs to the SYSUT3 and SYSUT4 IEBCOPY utility data sets.

Figure 1. ACBGEN and Catalog Populate utility input and output
The DBDLIB, the PSBLIB are shown as input to the DFS3UACB utility. The ACBLIB, catalog staging data set and IMS catalog are shown as the output targets of the utility.

JCL Specifications - DD statements

ACBCATWK
Defines an optional work data set that contains a list of the ACB members that are written to the ACB library during ACB generation.

The ACBCATWK data set is an output data set for the ACB Maintenance utility and an input data set for the DFS3PU00 utility.

You must specify a single ACBCATWK data set. Multiple data sets are not supported by the utility.

Specify the ACBCATWK data set to improve the performance of the DFS3PU00 utility. The DFS3PU00 utility uses the list of names to determine which records in the IMS catalog need to be inserted or updated. If you do not specify the ACBCATWK data set, the DFS3PU00 utility processes all members in the ACB libraries that are referenced in the IMSACBxx DD statements.

DFSVSAMP
Defines the buffer pool parameters data set.
IEFRDER DD
Defines the primary IMS log data set.
IEFRDER2 DD
Defines the secondary IMS log data set.
IMS DD
Defines the IMS.PSBLIB and IMS.DBDLIB data sets.
IMSACB DD
Defines a single ACB library data set.
Restriction: This data set is modified and cannot be shared with other jobs.
IMSACB01
Defines an ACB library data set that contains the ACB members that are used to populate the IMS catalog. This DD statement is required.
This DD statement must specify the same data set defined in the IMSACB DD statement. To ensure that the same data set is referenced, code this DD statement with an asterisk as the high-level qualifier, as shown in the example: //IMSACB01 DD DSN=*.ACBLIB,DISP=OLD
IMSDSTAG DD
Optionally defines the IMS directory staging data set.
DFS3PPRM
Specifies execution parameters for the DFS3PU00 utility. The execution parameters specified by the DFS3PPRM DD statement include the following values:
  • The PSB for the DFS3PU00 utility to use
  • Whether DBRC is enabled
  • Whether IRLM is enabled
  • The name of the DFSDFxxx PROCLIB member that contains the IMS catalog attributes
If the DFS3PPRM DD statement is omitted, the DFS3UACB utility passes the following default execution parameters to the DFS3PU00 utility:
DLI,DFS3PU00,DFSCP001,,,,,,,,,,,Y,N,,,,,,,,,,,,'DFSDF=CAT'

The preceding default parameters run the DFS3PU00 utility in update mode with DBRC and without IRLM. The default values specify DFSDFCAT as the DFSDFxxx PROCLIB member.

To load an IMS catalog, you must specify the DFSCPL00 PSB in the execution parameters defined on the DFS3PPRM DD statement.

Attention: Specifying the DFSCPL00 PSB in the execution parameters of the DFS3PU00 utility deletes any existing IMS catalog before starting the load process.

If data sharing is enabled for your IMS catalog, you must specify IRLM support in the DFS3PPRM DD statement by specify Y in the IRLM support position and the IRLM ID in the following position.

The following example of the DFS3PPRM DD statement specifies the load PSB DFSCPL00, no IRLM support, and a DFSDFxxx member named DFSDF001:

//DFS3PPRM DD  *
DLI,DFS3PU00,DFSCPL00,,,,,,,,,,,Y,N,,,,,,,,,,,,DFSDF=001

In contrast to the preceding example, the following example of the DFS3PPRM DD statement specifies the update PSB DFSCP001, support by IRLM IRL1, and a DFSDFxxx member named DFSDF002:

//DFS3PPRM DD  *
DLI,DFS3PU00,DFSCP001,,,,,,,,,,,Y,Y,IRL1,,,,,,,,,,,DFSDF=002
PROCLIB DD
Defines the IMS.PROCLIB data set that contains the DFSDFxxx member that defines various attributes of the IMS catalog that are required by the utility.
SYSABEND DD
Defines the dump data set.
SYSIN DD
Defines the input control statement data sets. They can be on a tape volume, direct-access device, card reader, or be routed through the input stream. The input can be blocked as multiples of 80. During execution, this utility can process as many control statements as required.
SYSINP DD
An optional control statement sequential data set with 80-character fixed-length records. Only characters in positions 1 - 72 are read.

The control statement parameters, which are separated by blanks or commas, can be specified on one or more records.

For a desciption of the control statements that you can specify with the SYSINP DD statement, see Catalog population control statements.

SYSPRINT DD
Defines the output message data set.

When the SYSPRINT DD statement refers to a DASD or tape data set, you can control the block size of this data set with the BLKSIZE subparameter of the DCB parameter. If specified, the BLKSIZE value must be an exact multiple of 121 or a system ABEND013-20 can result. Omitting BLKSIZE from a DASD data set causes a system-determined block size to be used. Regardless of what value is specified for the LRECL parameter, the utility always uses a record length of 121.

SYSUT3 DD
Defines a work data set that is required if either PRECOMP or POSTCOMP is specified on the EXEC statement.
SYSUT4 DD
Same function as SYSUT3.

ACB generation control statements

For the ACB generation phase of the DFS3UACB utility, you specify control statements in the utility JCL to specify the actions to take for the ACB members. You can specify BUILD statements and DELETE statements.

For BUILD statements, the DFS3UACB builds the specified ACB members and loads and inserts the corresponding records into the IMS catalog. For DELETE statements, the DFS3UACB utility deletes only the ACB members for the ACB library data set. No records are deleted from the IMS catalog. The removal of records from the IMS catalog is controlled by a retention policy.

The control statements must conform to the following guidelines:
  • A statement is coded as a card image and is contained in columns 1 - 71.
  • The control statement can optionally contain a name, starting in column 1.
  • To continue a statement, enter a non-blank character in column 72 and begin the statement on the next line starting in column 16.
  • The operation field must be preceded and followed by one or more blanks.
  • The parameter is composed of one or more PSB or DBD names and must also be preceded and followed by one or more blanks.
  • Commas, parentheses, and blanks can be used only as delimiting characters.
  • Comments can be written following the last parameter of a control statement, separated from the parameter by one or more blanks.

DFS3UACB utility control syntax: BUILD format

Read syntax diagramSkip visual syntax diagramname BUILD1 PSB=(,psbname)ALLDBD=(, dbdname),BLDPSB=YES,BLDPSB=NOPSB=(,psbname)ALL,DBD=(, dbdname),BLDPSB=YES,BLDPSB=NO2CATRSCS=NOCATRSCS=YES
Notes:
  • 1 There is no first in, first out (FIFO) process for the ACB Maintenance utility SYSIN input control statements. If both the BUILD PSB= and BUILD DBD= parameters are specified in the same application control block (ACB) generation job SYSIN control statement, DBD= operands are passed to the block builder utility program first. DFS0586I is issued if the DBD is not already in the ACBLIB data sets, regardless of where DBD= operands are entered in the SYSIN control statements.
  • 2 If you specify the parameters PSB=ALL and BLDPSB=NO in the same statement, IMS builds all of the PSBs (BLDPSB=NO is ignored). Similarly, if you specify the BLDPSB=NO parameter for one DBD and the BLDPSB=YES parameter on another DBD in the same ACBGEN job, IMS builds all the PSBs that refer to the changed DBDs and ignores the BLDPSB=NO specification. Also, if you specify BLDPSB=NO, no PSBs will be built for all SYSIN ACBGEN control cards.
In the following example, all of the PSBs that are associated with the CUSTOMER and ORDER DBDs are rebuilt, even though BLDPSB=NO is specified for the CUSTOMER DBD:
BUILD DBD=(CUSTOMER),BLDPSB=NO
BUILD DBD=(ORDER),BLDPSB=YES

ACB Maintenance utility syntax: DELETE Format

The DELETE statement removes an ACB member from the ACB library, but does not remove the corresponding record from the IMS catalog.

Read syntax diagramSkip visual syntax diagramname DELETE PSB=(, psbname)DBD=(, dbdname)

ACB Maintenance utility parameters

BUILD
Specifies that blocks are built for the named PSBs, which refer to the named DBDs.
DELETE
Specifies that blocks are deleted from the ACBLIB data set. The named PSBs and all PSBs that refer to the named DBDs are deleted.

Deleting a block from the ACBLIB data set does not delete the corresponding record in the IMS catalog.

PSB=ALL
Specifies that blocks are built for all PSBs that currently reside in IMS.PSBLIB. You use this parameter to create an initial IMS.ACBLIB. When the PSB=ALL parameter is specified, all PSBs and DBDs (and any other modules) are deleted from the ACBLIB data set and their space is available for reuse. Then an ACB generation is executed for every PSB in the PSBLIB data set. Do not use this parameter with a DELETE statement.
Restriction: When you specify the BUILD PSB=ALL parameter on a SYSIN control statement, all PSBs must reside in a single PSBLIB data set. No concatenated PSBLIBs are recognized on the IMS DD statement.
Restriction: Specifying PSB=ALL with CATRSCS=NO (or defaulting to CATRSCS=NO) does not build or update the IMS catalog PSBs and DBDs. If some PSBs or DBDs are not built or updated, message DFS5008W is issued and those PSBs or DBDs are ignored.
PSB=(psbname)
Specifies that blocks are built or deleted for all PSBs that are named on this control statement. As many of this type of control statement as required can be submitted. This parameter adds a new PSB to IMS.ACBLIB or delete a PSB no longer in use. You can omit the parentheses if you supply a single parameter.
DBD=(dbdname)
Specifies that blocks are built or deleted for this DBD and for all PSBs that reference this DBD either directly or indirectly through logical relationships. The DBD to be built must already exist in the IMS.ACBLIB data set. The referencing PSBs must already exist in the IMS.ACBLIB data set. PSBs that are newly added to the IMS.PSBLIB data set must be referenced by PSB operands. Because deleting a PSB does not delete any DBDs referenced by the PSB, this parameter can be used to delete specific DBDs. However, deleting or building a DBD causes every PSB in the IMS.ACBLIB data set that references the named DBD to be rebuilt or deleted based on the request type. You can omit the parentheses if you supply a single parameter.

Example 1: PSB-a references DBD-a and DBD-b. A DBDGEN was done for DBD-a and DBD-b and the updated DBDs are in DBDLIB (but not ACBLIB yet). By specifying DBD-a in an ACB generation, DBD-a is rebuilt in ACBLIB and any referencing PSBs (in this case PSB-a) are also rebuilt. Even though PSB-a has been rebuilt, the ACBLIB is not usable because DBD-b was not specifically rebuilt in ACBLIB. For DBD-b to be rebuilt in ACBLIB, it must be explicitly specified in the ACB generation. Although the referencing PSB is completely updated, the updated DBDs must be explicitly specified in the ACB generation.

Every PSB processed by this program generates a member in the IMS.ACBLIB data set. DBDs referenced by PSBs generate a member the first time the specific DBD is processed or any time a DBD name appears on a control statement. All PSBs that reference the same DBD carry information in their directory entries to connect the PSB to the referenced DBDs.

Logical DBDs do not have members in IMS.ACBLIB and cannot be referenced on BUILD or DELETE control statements.

Example 2: The following examples illustrate uses of the BLDPSB parameter:
  • The DBD named CUSTOMER was changed and all of the PSBs that refer to CUSTOMER need to be rebuilt:
    BUILD DBD=CUSTOMER,BLDPSB=YES
  • The DBDs named ORDER and INVENTORY are changed and all of the PSBs that refer to these DBDs need to be rebuilt:
    BUILD DBD=(ORDER,INVENTORY),BLDPSB=YES

When a DBD is replaced in IMS.DBDLIB, it must also be included in a BUILD DBD control statement. This is the only valid way the DBD can be replaced in IMS.ACBLIB without doing a BUILD PSB=ALL.

If a BUILD PSB is performed that references a modified DBD on DBDLIB, the PSB replaced on ACBLIB will contain the updated version of the DBD. If this BUILD PSB occurs before a BUILD DBD for the changed DBD, ACBLIB will contain PSBs with different versions of the DBD. The PSBs specified in the BUILD PSB will contain the updated DBD, while those not built will reference the old DBD. When a DBD for a PSB on ACBLIB does not match the accessed database, the results will be unpredictable. (For example, U852 abend occurs because segment codes have been added or deleted in the changed DBD). Therefore, when DBDGEN is run for later use, do not build a PSB that refers to the changed DBD unless the database reflects the change.

When a physical DBD is changed and is referenced in a BUILD DBD statement, all physical DBDs that are logically related to the one that was changed (including primary indexes and secondary indexes) must also be referenced in a BUILD DBD statement. However, DBDs that are logically related to these DBDs do not need to be rebuilt.

The following figure illustrates the relationships between some physical databases, where A is the changed DBD. The following relationships exist:

  • B and C are logically related to A.
  • D is logically related to B.
  • E is logically related to C.
  • D and E are not referenced in the BUILD DBD statement because they are not logically related to A.
Figure 2. Example of logically related physical databases
Five cylinders represent physical databases A through D. Lines show that B and C databases are logically related to A, and that D and E databases are logically related to B and C, respectively, but not to A.
BLDPSB=YES | NO
Specifies whether ACBGEN rebuilds all PSBs that reference a changed DBD in the BUILD DBD=(dbdname) statement.
YES
Indicates that ACBGEN rebuilds all PSBs that reference the changed DBD on the BUILD DBD=(dbdname) statement. The default is BLDPSB=YES.
NO
Indicates that ACBGEN does not rebuild PSBs that reference the changed DBD if the changed DBD does not change the physical structure of the database. For Fast Path DEDBs, the PSBs are rebuilt only when the number of segments, the number of fields within the segments of the database, or both are changed. For Fast Path MSDBs, the referencing PSBs are not rebuilt even if the database has physical structure changes.
CATRSCS=YES | NO
Specifies whether ACBGEN builds all PSBs and DBDs of the IMS catalog.
YES
Indicates that ACBGEN builds all IMS catalog PSBs and DBDs.
NO
Indicates that ACBGEN does not build any of the IMS catalog PSBs and DBDs. The default is CATRSCS=NO.

Catalog population control statements

The following control statement parameters, which are separated by blanks or commas, can be specified on one or more records by using the SYSINP DD statement.

DUPLIST
Specifies that the DFS3PU00 utility list each DBD or PSB resource in the input ACB library that is not added to the IMS catalog because it is a duplicate of an instance that is already in the IMS catalog. For each duplicate instance of a resource in the IMS catalog, the utility prints message DFS4436I.

If the MANAGEDACBS= statement is specified and the IMS management of ACBs is enabled, the utility also lists each DBD or PSB resources that is not added to the IMS directory or the staging data set because it is a duplicate of the instance of a resource that is already in the IMS directory.

If the UPDATE parameter is specified on the MANAGEDACBS= statement, the utility prints message DFS4531I for each duplicate instance.

If LATEST is specified or accepted as the default with the UPDATE parameter, the utility also prints message DFS4522I for each instance that is not added to the IMS directory because the instance of the resource in the IMS directory has a later timestamp.

If the STAGE parameter is specified on the MANAGEDACBS= statement, the utility prints message DFS4542I for each resource that is not copied to the staging data set because it is a duplicate instance.

If LATEST is specified or accepted as the default with the STAGE parameter, the utility also prints message DFS4539I for each instance that is not added to the staging data set because the instance of the resource in the IMS directory has a later timestamp.

ERRORMAX=n
Terminate the IMS Catalog Populate utility when more than n messages indicate errors that prevent certain DBDs and PSBs from having their metadata that is written to the IMS catalog. Duplicate instances of metadata do not count toward this limit. If this option is omitted, there is no limit.
RESOURCE_CHKP_FREQ=n
Specifies the number of DBD and PSB resource instances to be inserted between checkpoints. n can be a 1- to 8-digit numeric value of 1 to 99999999. The default value is 100.
SEGMENT_CHKP_FREQ=n
Specifies the number of segments to be inserted between checkpoints. When the number is reached, IMS finishes inserting all of the segments for the resource instance that is currently being processed before issuing the checkpoint. n can be a 1- to 8-digit numeric value of 1 to 99999999. The default value is 1000.
Note: The first checkpoint frequency number to be reached will cause a checkpoint to be taken and the counters will be reset to 0.
ISRTLIST

If the IMS management of ACBs is enabled, the utility also lists each DBD or PSB resources that is either added to the IMS directory or saved to the staging data set for importing into the IMS directory later.

The utility identifies the action taken for each resource by printing the following messages:
DFS4520I
The resource was added to the IMS directory as a new resource.
DFS4521I
This instance of the resource replaced an existing instance of the resource in the IMS directory.
DFS4537I
The resource was copied to the staging data set. When it is imported into the IMS directory later, it will be inserted as a new resource in the IMS directory.
DFS4538I
The resource was copied to the staging data set. When it is imported into the IMS directory later, it will replace an existing instance of the resource in the IMS directory.
MANAGEDACBS=
Use the MANAGEDACBS control statement to perform the following actions:
  • Set up IMS to manage the runtime application control blocks (ACBs) for your databases and program views.
  • Update an IMS system that manages ACBs with new or modified ACBs from an ACB library data set.
  • Save ACBs from an ACB library to a staging data set for later importing into an IMS system that manages ACBs.

The MANAGEDACBS statement can be specified according to the following syntax diagram:

Read syntax diagramSkip visual syntax diagramMANAGEDACBS=SETUP(STAGE,LATEST,UNCOND,DELETE,GSAMPCB,CATRSCS)(UPDATE,LATEST,UNCOND,GSAMPCB,SHARE)

If you use the gsamdbd parameter, the MANAGEDACBS statement can be specified according to the following syntax diagram:

Read syntax diagramSkip visual syntax diagramMANAGEDACBS=SETUP( STAGE ,GSAM= gsamdbd )( UPDATE ,GSAM= gsamdbd )

The parentheses are required only if you specify multiple parameters on the MANAGEDACBS= statement.

The following list describes the parameters that you can specify on the MANAGEDACBS= statement:

SETUP
Creates the IMS directory data sets that are required by IMS to manage application control blocks (ACBs). Any existing instances of the IMS directory data sets are replaced.

Do not specify ACBMGMT=CATALOG in the CATALOG section of the DFSDFxxx PROCLIB member until after you successfully run the utility with MANAGEDACBS=SETUP specified. You must create the IMS directory and load it with the active ACBs before you enable the IMS management of ACBs.

When SETUP is specified, the utility inserts the ACBs that are in the input ACB libraries into the IMS directory data sets.

If the IMS catalog PSB DFSCP001 is specified in the utility JCL, the utility inserts any new or modified DBDs or PSBs into the IMS catalog.

If the IMS catalog PSB DFSCPL00 is specified in the utility JCL, the utility deletes all existing catalog records and reloads the IMS catalog.

When the utility adds an ACB to the IMS directory, it flags the corresponding DBD and PSB instances in the IMS catalog as active.

Do not run the DFS3PU00 utility as a BMP with MANAGEDACBS=SETUP specified.

STAGE

Saves the ACBs from the input ACB libraries to a staging data set. ACBs saved in the staging data set are not activated until you add them to the IMS system by issuing the IMPORT DEFN SOURCE(CATALOG) command.

When STAGE is specified, the IMS catalog PSB DFSCP001 must be specified in the utility JCL.

If the staging data set exists when the MANAGEDACBS=STAGE control statement is specified, the utility uses the existing staging data set. Any ACBs already in the staging data set are preserved. To scratch and re-create the staging data set when you stage new resources, specify MANAGEDACBS=(STAGE,DELETE). When DELETE is specified, any ACBs in the existing data set are lost.

When STAGE is specified, the DFS3PU00 utility copies all ACBs in the ACB libraries that do not already exist in the IMS system into the staging data set. If an ACB in the ACB library already exists in the IMS system, the utility saves it to the staging data set based on whether timestamp of the ACB meets the criteria of the UNCOND or LATEST parameter.

Do not specify STAGE when you do an initial load of the IMS catalog or before you enable the IMS management of ACBs. The STAGE parameter is for staging updates to existing IMS directory data sets only.

If you specify multiple parameters after MANAGEDACBS=, you must enclose them in parentheses. For example, (STAGE,LATEST). If you specify only STAGE, you can omit the parentheses.

CATRSCS
When you use the STAGE option with the CATRSCS option, IMS catalog resources are added to the staging directory data set.
DELETE
If the staging data set is not allocated to any online IMS system, scratch and recreate the staging data set before adding the resources to the staging data set. Any ACBs in the existing staging data set are lost.
GSAMPCB
GSAM resources are included for MANAGEDACBS= running in DLI mode using PSB DFSCP001. When GSAMPCB is specified, the IEFRDER batch log data set is not used by the catalog members information gather task. Only the catalog update task writes to the batch log data set for catalog database changes. GSAMPCB and DELETE are mutually exclusive.
LATEST
If an ACB already exists in the IMS system, do not save an instance of the ACB in an ACB library to the staging data set unless the instance in the ACB library has a later timestamp than the ACB in the IMS system.

This is the default.

UNCOND
If an ACB already exists in the IMS system, save an instance of the ACB in an ACB library to the staging data set unconditionally, unless the timestamp of the ACB in the ACB library is the same as the timestamp of the ACB in the IMS system.
gsamdbd

gsamdbd is the name of changed GSAM database. The specified database record is inserted into the IMS catalog, and the application control block is written to the staging or active directory based on the MANAGEDACBS control statement parameters that you specify.

You can use the gsamdbd variable with the STAGE or UPDATE parameter. However, LATEST, UNCOND, DELETE, SHARE, and GSAMPCB are not supported if you specify the gsamdbd variable.

Because the gsamdbd variable identifies a GSAM resource, the GSAMPCB batch logging rule applies only to the catalog update task that writes to the batch log data set for catalog database changes.

Follow these steps if you want to change GSAM DBDs by using the STAGE parameter and gsamdbd. This process writes only the GSAM DBD to the staging directory.
  1. Change the GSAM DBD source.
  2. Run a DBDGEN to generate the GSAM DBD into DBDLIB.
  3. Run the DFS3PU00 utility with MANAGEDACBS=(STAGE,GSAM=gsamdbd).
    Tip: Only the DBDLIB DD card is required for the DFS3PU00 utility. ACBLIB and PSBLIB are not needed and are ignored if specified.

    The new GSAM DBD instance will be inserted to the catalog, and the application control block will be written to the staging directory.

  4. Run the IMPORT DEFN SOURCE(CATALOG) or IMPORT DEFN SOURCE(CATALOG) NAME(gsamdb) command with or without OPTION(NOCHECK).
UPDATE
Updates existing IMS directory system data sets directly in exclusive mode. The ACBs are not placed in the staging data set.
Recommendation: Shut down all IMS systems that use the IMS directory when you specify the UPDATE parameter. When UPDATE is specified, the IMS Catalog Populate utility requires exclusive access to the IMS directory.

Also, the utility does not notify online IMS systems when it updates the IMS directory. Consequently, any IMS systems that are online when the utility updates the IMS directory must be restarted to load the updated ACBs.

When UPDATE is specified, the DFS3PU00 utility inserts ACBs that are not already in the IMS system into the IMS directory unconditionally. If an ACB exists in the IMS system, the instance of the ACB is replaced depending on the timestamp of the instance in the ACB library and the specification of the UNCOND or LATEST parameter.

Do not specify UPDATE when you do an initial load of the IMS catalog or before you enable the IMS management of ACBs. The UPDATE parameter is for updating existing IMS directory data sets only.

When UPDATE is specified, the IMS catalog PSB DFSCP001 must be specified in the utility JCL.

If you specify multiple parameters after MANAGEDACBS, you must enclose them in parentheses. For example, (UPDATE,LATEST). If you specify only UPDATE, you can omit the parentheses.

By default, the system data set names that are allocated for IMS management of ACBs are derived from the data set name prefix that is specified in the RECON data set when the first partition of the IMS catalog is defined. To override this default, you can specify the SYSDSHLQ= parameter in a TYPE=CATDSHLQ statement in the dynamic allocation (DFSMDA) macro.

LATEST
If an ACB already exists in the IMS system, do not replace it with an instance of the ACB from an ACB library unless the instance in the ACB library has a later timestamp than the ACB in the IMS system.

This is the default.

UNCOND
If an ACB already exists in the IMS system, replace it with an instance of the ACB from an ACB library unconditionally, unless the timestamp of the ACB in the ACB library is the same as the timestamp of the ACB in the IMS system.
SHARE
For dynamic option (DOPT) PSBs only, allocates the required IMS directory data sets in a shared mode so that DOPT PSBs can be added to the IMS catalog without interrupting online processing.

Do not specify SHARE if the utility is loading the IMS catalog, as indicated by the specification of DFSCPL00, the IMS catalog load PSB, in the execution parameters of the utility JCL.

Do not specify SHARE if any resources in the input ACBLIB data sets are not DOPT PSBs.

Before you run the utility with the SHARE option specified, the extended sharing of PDSE data sets must be enabled in your z/OS system. The extended sharing of PDSE data sets is enabled in z/OS by specifying PDSESHARING(EXTENDED) in the IGDSMSxx member in the SYS1.PARMLIB on each system in the sysplex. If extended PDSE sharing is not enabled when SHARE is specified, the utility allocates the required IMS catalog data sets in exclusive mode, which might cause conflicts with other IMS processes and application programs.

For more information about enabling extended PDSE sharing, see z/OS: Specifying Extended PDSE Sharing in a Multiple-System Environment.

GSAMPCB
GSAM resources are included for MANAGEDACBS= running in DLI mode using PSB DFSCP001. When GSAMPCB is specified, the IEFRDER batch log data set is not used by the catalog members information gather task. Only the catalog update task writes to the batch log data set for catalog database changes. GSAMPCB and DELETE are mutually exclusive.
gsamdbd

gsamdbd is the name of changed GSAM database. The specified database record is inserted into the IMS catalog, and the application control block is written to the staging or active directory based on the MANAGEDACBS control statement parameters that you specify.

You can use the gsamdbd variable with the STAGE or UPDATE parameter. However, LATEST, UNCOND, DELETE, SHARE, and GSAMPCB are not supported if you specify the gsamdbd variable.

Because the gsamdbd variable identifies a GSAM resource, the GSAMPCB batch logging rule applies only to the catalog update task that writes to the batch log data set for catalog database changes.

Follow these steps if you want to change GSAM DBDs by using the UPDATE parameter and gsamdbd:
  1. Change the GSAM DBD source.
  2. Run a DBDGEN to generate the GSAM DBD into DBDLIB.
  3. Run the DFS3PU00 utility with MANAGEDACBS=(UPDATE,GSAM=gsamdbd).
    Tip: Only the DBDLIB DD card is required for the DFS3PU00 utility. ACBLIB and PSBLIB are not needed and are ignored if specified.

    The new GSAM DBD instance will be inserted to the catalog, and the application control block will be written to the IMS directory.

NODUPLIST
Do not print a list of resource instances that were not added. This parameter is the default.
NOISRTLIST
Do not print a list of inserted resource instances.

Return codes

The DFS3UACB utility returns the following codes:

0
Successful completion of all operations
4
One or more records were not loaded into the IMS catalog. Warning messages issued.
16
Program terminated due to severe errors

Examples of the DFS3UACB utility JCL

You can find examples of the DFS3UACB utility JCL that you can use for the following scenarios:
  • When you want to load an IMS catalog for the first time.
  • When you want to load the IMS catalog subsequently without deleting the existing catalog data.
  • When you want to update the ACB members and catalog records in an existing IMS catalog.

Example of the DFS3UACB utility JCL statements for load mode

The following is an example of the JCL statements that can be used to generate ACB members and load catalog records into an IMS catalog by using the DFS3UACB utility.

In the example, the PSB DFSCPL00 is specified on the DFS3PPRM DD statement to access the IMS catalog in load mode.
Attention: Running the DFS3UACB utility in load mode deletes any existing records in an IMS catalog.
//ACBPOPLD  JOB 'IMS SYSTEM',CLASS=K,MSGLEVEL=(1,1),REGION=0M
//*
//*******************************************************************
//* DFS3UACB GENERATES ACB MEMBERS IN AN ACB LIBRARY BY CALLING THE  
//* ACB MAINTENANCE UTILITY. IN THE SAME JOB STEP,                   
//* DFS3UACB LOADS RECORDS IN THE IMS CATALOG BY CALLING  
//* THE IMS CATALOG POPULATE UTILITY (DFS3PU00)                      
//*******************************************************************
//*
//ACBCATT EXEC PGM=DFS3UACB,REGION=0M
//*
//STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
//PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
//DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
//SYSPRINT DD  SYSOUT=A
//SYSOUT   DD  SYSOUT=A
//SYSABEND DD  SYSOUT=*
//IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
//         DD  DSN=IMS.DBDLIB,DISP=SHR
//ACBCATWK DD  SPACE=(CYL,(1,1)),UNIT=SYSDA
//*
//*******************************************************************
//* DATASETS USED ONLY BY ACB MAINTENANCE UTILITY
//*******************************************************************
//IMSACB   DD  DSN=IMS.ACBLIB,DISP=OLD
//SYSUT3   DD  UNIT=SYSDA,SPACE=(80,(100,100))
//SYSUT4   DD  UNIT=SYSDA,SPACE=(256,(100,100)),DCB=KEYLEN=30
//*******************************************************************
//* ACBGEN INPUT PARMS TO REBUILD ACBLIB
//*******************************************************************
//SYSIN    DD  *
         BUILD PSB=ALL
/*
//*******************************************************************
//* DATASETS USED ONLY BY IMS CATALOG POPULATE UTILITY 
//*******************************************************************
//IMSACB01 DD  DSN=*.IMSACB,DISP=OLD      DO NOT REPLACE ASTERISK   
//DFSVSAMP DD  .......      BUFFER POOL DEFINITIONS
//IEFRDER  DD  .......      LOG DATASET FOR CATALOG UPDATES
//IEFRDER2 DD  .......      LOG DATASET FOR CATALOG UPDATES
//*******************************************************************
//* LOAD INPUT PARMS FOR IMS CATALOG POPULATE UTILITY
//*******************************************************************
//DFS3PPRM DD  *
DLI,DFS3PU00,DFSCPL00,,,,,,,,,,,Y,N,,,,,,,,,,,,DFSDF=CAT
/*
//

Example of the DFS3UACB utility JCL statements for load mode without deleting existing catalog details

The following is an example of the JCL statements that can be used to generate ACB members and load catalog records into an IMS catalog by using the DFS3UACB utility without deleting the existing catalog details.

In the example, the PSB DFSCPL00 is specified on the DFS3PPRM DD statement to access the IMS catalog in load mode.

//ACBPOPLD  JOB 'IMS SYSTEM',CLASS=K,MSGLEVEL=(1,1),REGION=0M
//*
//*******************************************************************
//* DFS3UACB GENERATES ACB MEMBERS IN AN ACB LIBRARY BY CALLING THE  
//* ACB MAINTENANCE UTILITY. IN THE SAME JOB STEP,                   
//* DFS3UACB LOADS RECORDS IN THE IMS CATALOG BY CALLING  
//* THE IMS CATALOG POPULATE UTILITY (DFS3PU00)                      
//*******************************************************************
//*
//ACBCATT EXEC PGM=DFS3UACB,REGION=0M
//*
//STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
//PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
//DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
//SYSPRINT DD  SYSOUT=A
//SYSOUT   DD  SYSOUT=A
//SYSABEND DD  SYSOUT=*
//IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
//         DD  DSN=IMS.DBDLIB,DISP=SHR
//ACBCATWK DD  SPACE=(CYL,(1,1)),UNIT=SYSDA
//*
//*******************************************************************
//* DATASETS USED ONLY BY ACB MAINTENANCE UTILITY
//*******************************************************************
//IMSACB   DD  DSN=IMS.ACBLIB,DISP=OLD
//SYSUT3   DD  UNIT=SYSDA,SPACE=(80,(100,100))
//SYSUT4   DD  UNIT=SYSDA,SPACE=(256,(100,100)),DCB=KEYLEN=30
//*******************************************************************
//* ACBGEN INPUT PARMS TO REBUILD ACBLIB
//*******************************************************************
//SYSIN    DD  *
         BUILD PSB=ALL,CATRSCS=YES
/*
//*******************************************************************
//* DATASETS USED ONLY BY IMS CATALOG POPULATE UTILITY 
//*******************************************************************
//IMSACB01 DD  DSN=*.IMSACB,DISP=OLD      DO NOT REPLACE ASTERISK   
//DFSVSAMP DD  .......      BUFFER POOL DEFINITIONS
//IEFRDER  DD  .......      LOG DATASET FOR CATALOG UPDATES
//IEFRDER2 DD  .......      LOG DATASET FOR CATALOG UPDATES
//*******************************************************************
//* LOAD INPUT PARMS FOR IMS CATALOG POPULATE UTILITY
//*******************************************************************
//DFS3PPRM DD  *
DLI,DFS3PU00,DFSCPL00,,,,,,,,,,,Y,N,,,,,,,,,,,,DFSDF=CAT
/*
//

Example of the DFS3UACB utility JCL statements for update mode

The following is an example of the JCL statements that can be used to generate ACB members and catalog records for an existing IMS catalog by using the DFS3UACB utility. In the JCL, the PSB DFSCP001 is specified on the DFS3PPRM DD statement to access the IMS catalog in update mode.

//ACBPOPUP  JOB 'IMS SYSTEM',CLASS=K,MSGLEVEL=(1,1),REGION=0M
//*
//*******************************************************************
//* DFS3UACB GENERATES ACB MEMBERS IN AN ACB LIBRARY BY CALLING THE  
//* ACB MAINTENANCE UTILITY. IN THE SAME JOB STEP,                   
//* DFS3UACB INSERTS RECORDS IN THE EXISTING IMS CATALOG BY CALLING  
//* THE IMS CATALOG POPULATE UTILITY (DFS3PU00)                      
//*******************************************************************
//*
//ACBCATT EXEC PGM=DFS3UACB,REGION=0M
//*
//STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
//PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
//DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
//SYSPRINT DD  SYSOUT=A
//SYSOUT   DD  SYSOUT=A
//SYSABEND DD  SYSOUT=*
//IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
//         DD  DSN=IMS.DBDLIB,DISP=SHR
//ACBCATWK DD  SPACE=(CYL,(1,1)),UNIT=SYSDA
//*
//*******************************************************************
//* ACBGEN DATASETS
//*******************************************************************
//IMSACB   DD  DSN=IMS.ACBLIB,DISP=OLD
//SYSUT3   DD  UNIT=SYSDA,SPACE=(80,(100,100))
//SYSUT4   DD  UNIT=SYSDA,SPACE=(256,(100,100)),DCB=KEYLEN=30
//*******************************************************************
//* ACBGEN INPUT PARMS TO UPDATE ACBLIB
//*******************************************************************
//SYSIN    DD  *
         BUILD PSB=psbname (same as needed for ACBGEN) 
/*
//*******************************************************************
//* POPULATE UTILITY DATASETS
//*******************************************************************
//IMSACB01 DD  DSN=*.IMSACB,DISP=OLD      DO NOT REPLACE ASTERISK   
//SYSINP   DD  *              ISRTLIST DUPLIST /*  
//DFSVSAMP DD  .......      BUFFER POOL DEFINITIONS
//IEFRDER  DD  .......      LOG DATASET FOR CATALOG UPDATES
//IEFRDER2 DD  .......      LOG DATASET FOR CATALOG UPDATES
//*******************************************************************
//* UPDATE INPUT PARMS FOR IMS CATALOG POPULATE UTILITY
//*******************************************************************
//DFS3PPRM DD  *
DLI,DFS3PU00,DFSCP001,,,,,,,,,,,Y,Y,irlmidN,,,,,,,,,,,,DFSDF=CAT
/*
//