IMS Catalog Populate utility (DFS3PU00)

If any of the data sets for the IMS catalog have not been created, the DFS3PU00 utility creates them automatically. The amount of space that the utility allocates for the data sets is based on the ACB library members and the values that are specified on SPACEALLOC parameter in the catalog section of the DFSDFxxx PROCLIB member.

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

No restrictions that are unique to the DFS3PU00 utility are currently documented.

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.

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.

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=(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.

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

Successful completion of all operations

4

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

8 or greater

Program terminated due to severe errors