ACB Generation and Catalog Populate utility (DFS3UACB)

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.

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.

Subsections:

• Restrictions
• Prerequisites
• Requirements
• Recommendations
• Input and output
• JCL specifications
• ACB generation control statements
• Catalog population control statements
• Return codes

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

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.

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.

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

JCL specifications

Two examples of the DFS3UACB utility JCL are provided in the following subsections. One example shows the JCL for updating an existing catalog. The second example shows the JCL for loading an IMS catalog. Loading an IMS catalog deletes any existing records in the IMS catalog.

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,N,,,,,,,,,,,,DFSDF=CAT
/*
//                                                               

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.

//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
/*
//

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.

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

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.

DFS3UACB utility control syntax: BUILD format

>>-+------+----------------------------------------------------->
   '-name-'   

                         .-,-------.                                                    
         (1)             V         |                                                    
>--BUILD------+-PSB=-+-(---psbname-+-)-+--------------------------------------------+-><
              |      '-ALL-------------'                                            |   
              |       .-,-------.                                                   |   
              |       V         |   .-,BLDPSB=YES-.                                 |   
              +-DBD=(---dbdname-+-)-+-------------+---------------------------------+   
              |                     '-,BLDPSB=NO--'                                 |   
              |          .-,-------.               .-,-------.                      |   
              |          V         |               V         |   .-,BLDPSB=YES----. |   
              '-PSB=-+-(---psbname-+-)-+--,--DBD=(---dbdname-+-)-+----------------+-'   
                     '-ALL-------------'                         |            (2) |     
                                                                 '-,BLDPSB=NO-----'     

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.

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.

>>-+------+--DELETE--+---------------------+-------------------->
   '-name-'          |       .-,-------.   |   
                     |       V         |   |   
                     '-PSB=(---psbname-+-)-'   

>--+---------------------+-------------------------------------><
   |       .-,-------.   |   
   |       V         |   |   
   '-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.

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

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.

Catalog population control statements

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