IMS Catalog Populate utility (DFS3PU00)

You can also use the DFS3PU00 utility to estimate the required sizes of the IMS catalog data sets without updating the IMS catalog. The utility generates the size estimates by scanning the members in the input ACB libraries.

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.

If dynamic option (DOPT) PSBs are the only resource type in the input ACB libraries, the utility can add the DOPT PSBs without taking the system offline. Some restrictions apply. See the SHARE keyword under Control statements.

If any of the data sets for the IMS catalog have not been created, including those for the IMS directory, the DFS3PU00 utility creates them automatically. The IMS directory, an internal IMS structure, is used to hold the runtime control blocks for the DBD and PSB instances that are flagged as active in the IMS catalog.

The amount of space that the utility allocates for the IMS catalog data sets is based on the members in the input ACB libraries and the values that are specified on SPACEALLOC parameter in the catalog section of the DFSDFxxx PROCLIB member. The amount of space that the utility allocates for the IMS directory data sets, which are PDSE data sets, is also based on the size of the ACB library, but is increased dynamically as needed.

The output of the DFS3PU00 utility includes a report that contains statistics about the record segments that are loaded into the IMS catalog. The report includes information about the number and types of segments, as well as an estimate of the amount of DASD storage that each data set group of the IMS catalog will require. If you need to know how much DASD storage the IMS catalog data sets will use before they are created, you can run the DFS3PU00 utility without populating the IMS catalog to generate only the statistics report. To run the DFS3PU00 utility in analysis-only mode, specify DFSCP000 as the PSB for the utility in the utility JCL.

After the utility evaluates the members in your ACB libraries, it produces a report. This report is the same report that the DFS3PU00 utility produces when it loads the IMS catalog.

The DFS3PU00 utility creates the catalog records from the ACB members in one or more ACB libraries and depending on your database types, the associated DBD and PSB members in DBD libraries and PSB libraries. The records contain metadata for your application programs and databases.

PARM=(DLI,DFS3PU00,DFSCP001,,,,,,,,,,,Y,Y,irlmid,,,,,,,,,,,'DFSDF=001')

As an alternative to running the DFS3PU00 utility, you can populate the IMS catalog by using the ACB Generation and Catalog Populate utility (DFS3UACB). The DFS3UACB utility generates the ACB libraries for your applications and databases and then populates the IMS catalog, both in the same job step.

Subsections:

• Restrictions
• Prerequisites
• Requirements
• Recommendations
• Input and output
• JCL specifications
• Control statements
• IMS Catalog Populate utility statistics report
• Return codes

Restrictions

The IMS Catalog Populate utility (DFS3PU00) cannot be run as a BMP in an ACBMGMT=ACBLIB environment when the MANAGEDACBS=SETUP utility control statement is specified.

Prerequisites

Before the DFS3PU00 utility can load the metadata for new or changed application programs and databases into the IMS catalog, the DBD generation, PSB generation, and ACB generation processes must be complete for the new or changed application programs and databases.

Before you can 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®. For more information, see z/OS: Specifying Extended PDSE Sharing in a Multiple-System Environment.

Requirements

When the IMS.DBDLIB and IMS.PSBLIB data sets are included as input, they must be the DBD and PSB libraries from which the input IMS.ACBLIB data set was built.

If any required members of the PSBLIB or DBDLIB data sets are not found, the utility issues an error message, and the records for the referencing PSBs are not created in the IMS catalog. You can add the missing catalog records later by supplying the necessary PSB or DBD members with the correct ACB library and rerunning the DFS3PU00 utility in update mode by specifying the DFSCP001 PCB in the utility JCL.

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.

When the IMS catalog is registered with DBRC, you are required to create an image copy of the IMS catalog after an initial load of the IMS catalog. When the IMS catalog is not registered with DBRC, IMS cannot require an image copy after an initial load; however, if an image copy is not created after an initial load, the only way to recover the catalog is to reload it.

Recommendations

If you are updating an existing IMS catalog, create an image copy of the IMS catalog data sets when the updates are complete. If the IMS catalog is registered with DBRC, you can use the DBRC command GENJCL.IC to back up the catalog. If you have 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 DFS3PU00 utility always reads input from the ACB library data sets that contain the ACB members for your databases and application programs, and from the DFSDFxxx member of the IMS.PROCLIB data set.

If your databases use logical relationships, the IMS Catalog Populate utility also reads input from the IMS.DBDLIB data set.

If you use GSAM databases and an ACB library member references a GSAM database, the DFS3PU00 utility also reads input from both the IMS.DBDLIB and the IMS.PSBLIB data sets.

Figure 1. IMS Catalog Populate utility input and output

JCL specifications

DFS3PU00 utility JCL statements

The execution parameters for the DFS3PU00 utility must reference the DFSDFxxx member of the IMS.PROCLIB data set, as shown in the following example JCL.

At least one IMS.ACBLIB data set must be specified in the utility JCL by the IMSACB01 DD statement. You can include additional ACBLIB data sets by concatenating them in a single DD statement or by specifying additional IMSACBnn DD statements, as shown in the following example JCL by the IMSACB02 and IMSACB03 DD statements. The additional IMSACBnn ddnames must be consecutively numbered in the last two characters positions.

Duplicate ACB members with duplicate names are handled differently depending on whether the ACB libraries are concatenated on a single DD statement or are referenced individually by separate DD statements. If you use cloned ACB libraries, but duplicate ACB members might be generated individually in any of the libraries, reference each of the cloned ACB libraries in the utility JCL by using a separate DD statement.

When ACB libraries are referenced individually by separate DD statements, the DFS3PU00 utility checks the ACB generation time stamps of ACB members with duplicate names and uses them only if the ACB generation time stamp is different from the previously processed ACB member with the same name. If the time stamps are the same, the ACB member with the duplicate name is ignored.

However, when ACB libraries are concatenated in a single DD statement, the DFS3PU00 utility does not check the ACB generation time stamps of ACB members with duplicate names. If duplicate member names exist across the concatenated ACB libraries, only the first ACB member is used and any subsequent ACB members with a duplicate name are ignored, even if the time stamps are different.

Your DLIBATCH or equivalent procedure should already include IMS DD statements for the PSB and DBD libraries that were used to generate the ACB libraries. The procedure should also include STEPLIB and DFSRESLB DD statements for the IMS.SDFSRESL data set and IEFRDER and IEFRDER2 DD statements for the IMS log data sets.

  //LOADCAT EXEC PGM=DFS3PU00,
  // PARM=(DLI,DFS3PU00,DFSCPL00,,,,,,,,,,,Y,N,,,,,,,,,,,,'DFSDF=001')
  //STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
  //DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
  //IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
  //         DD  DSN=IMS.DBDLIB,DISP=SHR
  //PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
  //SYSABEND DD  SYSOUT=*       Dump data set
  //SYSPRINT DD  SYSOUT=*       Messages, statistics
  //IEFRDER  DD  ...            Log data set
  //DFSVSAMP DD  ...            Buffer pool parameters
  //IMSACB01 DD  ...            First ACBLIB              
  //         DD  ...            Optional concatenated ACBLIB
  //IMSACB02 DD  ...            Optional additional ACBLIBs
  //IMSACB03 DD  ...            ...
  //SYSINP   DD  *              ISRTLIST DUPLIST /*  

  //UPDTCAT EXEC PGM=DFS3PU00,
  //             PARM=(DLI,DFS3PU00,DFSCP001,,,,,,,,,,,Y,N,,,,,,,,,,
  //             ,,'DFSDF=001')                                       
  //STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
  //DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
  //IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
  //         DD  DSN=IMS.DBDLIB,DISP=SHR
  //PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
  //SYSABEND DD  SYSOUT=*       Dump data set
  //SYSPRINT DD  SYSOUT=*       Messages, statistics
  //IEFRDER  DD  ...            Log data set with catalog updates
  //DFSVSAMP DD  ...            Buffer pool parameters
  //IMSACB01 DD  ...            First ACBLIB              
  //         DD  ...            Optional concatenated ACBLIB
  //IMSACB02 DD  ...            Optional additional ACBLIBs
  //IMSACB03 DD  ...            ...

//UPDTCAT EXEC PGM=DFS3PU00,
//     PARM=(DLI,DFS3PU00,DFSCP001,,,,,,,,,,,Y,Y,irlmid,,,,,,,,,
//             ,,'DFSDF=001')
//STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
//DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
//IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
//         DD  DSN=IMS.DBDLIB,DISP=SHR
//PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
//SYSABEND DD  SYSOUT=*       DUMP DATA SET
//SYSPRINT DD  SYSOUT=*       MESSAGES, STATISTICS
//IEFRDER  DD  ...            LOG DATA SET WITH CATALOG UPDATES
//DFSVSAMP DD  ...            BUFFER POOL PARAMETERS
//IMSACB01 DD  ...            FIRST ACBLIB
//         DD  ...            OPTIONAL CONCATENATED ACBLIB
//IMSACB02 DD  ...            OPTIONAL ADDITIONAL ACBLIBS

//UPDTCAT EXEC PGM=DFS3PU00,
  //             PARM=(BMP,DFS3PU00,DFSCP001,,,,,,,,,,,imsid,,,,,,)
  //STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
  //DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
  //IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
  //         DD  DSN=IMS.DBDLIB,DISP=SHR
  //PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
  //SYSABEND DD  SYSOUT=*       Dump data set
  //SYSPRINT DD  SYSOUT=*       Messages, statistics
  //IEFRDER  DD  ...            Log data set with catalog updates
  //DFSVSAMP DD  ...            Buffer pool parameters
  //IMSACB01 DD  ...            First ACBLIB              
  //         DD  ...            Optional concatenated ACBLIB
  //IMSACB02 DD  ...            Optional additional ACBLIBs
  //IMSACB03 DD  ...            ...

DD statements

DFSRESLB DD

Points to an authorized library that contains the IMS SVC modules. For IMS batch, SDFSRESL and any data set that is concatenated to it on the DFSRESLB DD statement must be authorized through the Authorized Program Facility (APF). This DD statement provides an authorized library for the IMS SVC modules, which must be in an authorized library. The JOBLIB or STEPLIB statement does not need to be authorized for IMS batch.

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.

The IMS DD statement is required only if the IMS ACB library members loaded into the IMS catalog reference GSAM or logically related databases.

IMSACB01 DD

Defines an ACB library data set that contains the ACB members that are used to populate the IMS catalog. This DD statement is required.

IMSACBnn DD

Defines additional optional input ACB library data sets. The ddnames of additional ACB libraries must be consecutively numbered in the nn position.

The value of nn is determined by adding 1 to the value of nn from the preceding IMSACBnn ddname. Valid values for nn are from 02 through 99.

For example, after the required IMSACB01 DD statement, subsequent DD statements would be named IMSACB02, IMSACB03, IMSACB04, and so on.

If a break in the consecutive numbering of IMSACBnn ddnames occurs, the ACB library DD statements after the break are ignored.

IMSDBSDS DD

Optionally defines the IMS directory bootstrap data set (BSDS).

Use this DD statement to control the placement and size of the data set. If this statement is provided, the utility does not delete an existing BSDS and then create a new one, but overwrites the content of the existing data set.

The data set name must conform to the same naming convention as for a utility-created BSDS. The data set must be DSORG=PS, RECFM=FB, LRECL=96.

If this statement is omitted, the utility dynamically deletes any preexisting BSDS and dynamically creates a new one.

IMSDnnnn DD

Optionally defines the IMS directory data sets that are used to store the ACBs.

Use this DD statement for each IMS directory data set to control the number of data sets that are used, and the placement and size of each data set. You can provide this DD statement for up to 20 data sets. The number of DD statements that start from IMSD0001 determines how many data sets are used. The utility does not dynamically delete or create any of the directory data sets if IMSD0001 is specified.

You can specify only one data set on each DD statement. Concatenation is not allowed.

The data set name must conform to the same naming convention as for a system-created directory data set. Each data set must be a PDS-E with DSORG=PO, RECFM=U, LRECL=0, BLKSIZE=32760, DSNTYPE=LIBRARY. The data set must be empty when the utility begins processing the data set.

If the IMSD0001 DD is omitted, the utility dynamically deletes any preexisting directory data sets and dynamically creates two new data sets to store the ACBs.

IMSDG001 DD

An optional control statement to define an empty work data set to be used as an IMS.ACBLIB data set for the IMS Catalog Populate utility (DFS3PU00). This data set is used to temporarily hold ACB library members that reference a GSAM database. The DFS3PU00 utility then moves the ACB library members into the IMS directory data sets after it copies the ACB library members from the libraries specified on the IMSACBnn DD statement.

Provide this DD to obtain more control over the placement and size of the temporary data set. If this DD is provided the DFS3PU00 utility does not dynamically create or delete a temporary data set.

This data set has the following attributes:

DSORG

Partitioned data set extended (PDSE)

DSNTYPE

LIBRARY

RECFM

U

LRECL

80

BLKSIZE

32760

If the IMS management of ACBs is not enabled, this statement is omitted.

If the data set is not a PDSE data set, the DFS4549E message is displayed.

If the data set is not empty when the DFS3PU00 utility begins processing, the content of the data set is deleted.

If this DD statement is omitted, the DFS3PU00 utility dynamically creates a temporary data set and deletes it after the utility completes processing.

IMSDSTAG DD

Optionally defines the IMS directory staging data set.

Provide this DD statement to control the placement and size of the data set. If this DD statement is provided, the utility does not dynamically delete or create the staging data set.

When you name the data set, conform to the same naming convention as for the staging data set. The data set must be a PDS-E with DSORG=PO, RECFM=U, LRECL=0, BLKSIZE=32760, DSNTYPE=LIBRARY.

The data set must be empty when the utility begins processing the data set.

If this DD statement is omitted, the utility dynamically deletes any preexisting staging data set and dynamically creates a new one.

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.

STEPLIB DD

Points to IMS.SDFSRESL, which contains the IMS nucleus and required IMS modules. If STEPLIB is unauthorized by having unauthorized libraries that are concatenated to IMS.SDFSRESL, you must include a DFSRESLB DD statement.

SYSABEND DD

Defines the dump data set.

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 description of the control statements that you can specify with the SYSINP DD statement, see 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 sub-parameter 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 LRECL, the utility will always use a record length of 121.

Control statements

IMS Catalog Populate utility statistics report

Each time the DFS3PU00 utility runs it creates a statistics report for the record segments to be loaded or updated in the IMS catalog. When the DFS3PU00 utility runs in read-only mode, the report reflects only the potential statistics if the IMS catalog were loaded or updated from the ACB libraries currently being used as input to the utility.

To run the DFS3PU00 utility in analysis-only mode, specify DFSCP000 as the PSB for the utility in the utility JCL.

The second section in the report shows both the numbers of existing DBD and PSB records that were updated by the utility and the number of existing DBD and PSB records that were not updated because the time stamp of the record matched the time stamp of the corresponding ACB member in the ACB library. This section of the report also shows the number of DBD and PSB segments whose ACBLIB time stamps were already in the catalog and did not need to be inserted again.

The rest of the sections in the report provide the storage estimates.

For the OSAM data sets, the storage sections of the report show the number of blocks of the specified size. For the VSAM KSDSs, which include the indirect list data set (ILDS), the primary index data set, and the secondary index data set, the report shows the number of VSAM records.

These numbers are estimates that reflect the amount of space needed to load the catalog records that are built from the ACB libraries that you provide as input to the DFS3PU00 utility. If you are calculating the amount of storage required for the IMS catalog data sets, provide plenty of additional space in your calculations to allow for expansion.

If you have IMS create the IMS catalog data sets automatically, you can specify additional space as a percentage of the estimates that are provided by the utility on the SPACEALLOC parameter in the IMS catalog section of the DFSDFxxx PROCLIB member. The default value for this parameter is 500%.

   CATALOG DFSCD000                                          
                                                             
   PARTITION DFSCD01
                                          
      NUMBER OF SEGMENTS INSERTED INTO THE CATALOG
                      INSERTED                      AVERAGE  
      SC   SEGMENT    SEGMENTS   DSG   PARENT     SEGS/PARENT
      --   --------   --------   ---   --------   -----------
       1   HEADER        4228     A                          
       2   DBD           2530     A    HEADER         0.6    
       3   CAPXDBD          7     D    DBD            0.0    
       5   DSET          2599     D    DBD            1.0    
       7   AREA           139     D    DBD            0.1    
       9   SEGM         16337     B    DBD            6.5    
      10   CAPXSEGM         1     D    SEGM           0.0    
      12   FLD          16426     C    SEGM           1.0    
      14   MAR          16426     C    FLD            1.0    
      17   LCHILD        2687     B    SEGM           0.2    
      20   XDFLD          134     B    LCHILD         0.0    
      33   PSB           1840     A    HEADER         0.4    
      35   PCB           9190     B    PSB            5.0    
      37   SS           75274     B    PCB            8.2    
      39   SF            1105     B    SS             0.0    
      41   DBDXREF       8886     D    PSB            4.8    
                                                             
                 WITHIN    DUPLICATES                        
                EXISTING       NOT                           
      SEGMENT    HEADER     INSERTED                         
      -------   --------   ----------                        
      DBD           71           0                           
      PSB           72           0                           
                                                             
      ESTIMATED SPACE REQUIREMENT TO HOLD INSERTED SEGMENTS  
        DSG   BLKSIZE   BLOCKS                               
        ---   -------   ------                               
         A      4096       596                               
         B      4096      9343                               
         C      4096      8214                               
         D      4096       236                               
                                                             
        DSG   RECORDS                                        
        ---   -------                                        
         L      8886                                         
         X      4230                                         
                                                             
        SECONDARY                                            
        INDEX        RECORDS                                 
        ---------    -------                                 
        DFSCX000       8886

Return codes

The DFS3PU00 utility returns the following codes:

0

All operations completed successfully.

4

One or more records could not be loaded into the IMS catalog. Warning messages issued.

8

One or more records could not be loaded into the IMS catalog. Error messages issued.

Greater than 8

Program terminated due to severe errors.