OpenFrame/HiDB Utilities

This chapter describes utilities used to reorganize the OpenFrame/HiDB database.

1. Overview

The following is a list of the utility programs used to reorganize the OpenFrame/HiDB (hereafter HiDB) database. Details about each utility are described in each section.

Program Description

DFSURGL0

Takes the data sets generated by the HD Reorganization Unload utility (DFSURGU0) and reloads them to an HDAM, HIDAM or HISAM database.

DFSURGU0

Unloads an HDAM, HIDAM, or HISAM database to a sequential data set (SDS).

2. DFSURGL0

The DFSURGL0 utility reloads the data set created by the HD Reorganization Unload utility (DFSURGU0) to an HDAM, HIDAM or HISAM database.

The DFSURGL0 utility program carries out the following functions:

  • Unloads the data sets produced by the DFSURGU0 utility and reloads them to HDAM, HIDAM, and HISAM databases.

  • Creates work data sets that contain the logical relationship and secondary index information.

  • Produces statistics about the database reload.

The DFSURGL0 utility in HiDB is a counterpart to the DFSURGL0 utility in IBM IMS DB.

2.1. EXEC Statements

The following shows how to specify the EXEC statement.

PGM=DFSRRC00,PARM='ULU,DFSURGL0,dbd-name'
Item Description

PGM

Execution utility of an IMS DB program, DFSRRC00, which is used to execute the DFSURGL0 utility.

PARM

  • ULU,DFSURGL0: executes DFSURGL0 of the utility region.

  • dbd-name: specifies the DBD name of the target database to be reloaded.

2.2. DD Statements

The following describes each DD statement.

Item Description

IMS DD

Specifies the location of the library that contains the DBD specified in the EXEC script. (Required)

database DD

Specifies the data set of the target database to be unloaded. (Required)

The database DD name has to match the DD name described in DBD. In HIDAM databases, the relevant index data sets also need to be specified.

SYSPRINT DD

Displays DFSURGL0 utility messages. (Required)

DFSUINPT DD

Specifies the input data set to be reloaded to the data set produced by the HD Reorganization Unload utility (DFSURGU0). (Required)

Describing the input data set with DUMMY causes pre-formatting of the HDAM and HIDAM database to be executed.

DFSURWF1 DD

Specifies work data sets to be produced if the segments inside the target database to be reloaded have logical relationships.

The data set is used as the input data set to the Prefix Resolution utility (DFSURGL0), and contains the logical relationships and secondary index information created during the reload.

DFSURCDS DD

In HiDB, only the syntax error check is supported.

DFSURLOG DD

Specifies the data set where the database reloading will be logged. (Optional)

Used to identify the cause of a reloading error as the log data set records the segment sequence, name, key value, and status code of the target data set being reloaded.

2.3. Control Statements

No control statements are used for the DFSURGL0. Any IBM mainframe control statements are ignore.

2.4. Statistics

When the database has been successfully reloaded, the SYSPRINT displays the following statistics.

*** HIERARCHICAL DIRECT DB REORG RELOAD ***

          SEGMENT  LEVEL  STATISTICS

        TOTAL SEGMENTS BY SEGMENT TYPE
 ===========================================
 SEGMENT   SEGMENT
 NAME      LEVEL       RELOADED  DIFFERENCE
 -------------------------------------------
 PBM01VAA     1            9628
 PBM01VAD     2            9628
 PBM01VAE     2               0
 PBM01VAB     2           28243
 PBM01VAF     3           28243
 PBM01VAC     3           15586
 PBM01VAG     2               0
 -------------------------------------------
          TOTAL SEGMENTS IN DATABASE
 UNLOADED          RELOADED      DIFFERENCE
    91328             91328
 ===========================================

  • SEGMENT LEVEL STATISTICS

    The following is a list of the SEGMENT LEVEL STATISTICS field items.

    Item Description

    SEGMENT NAME

    Segment name of statistics information in the same category.

    SEGMENT LEVEL

    The hierarchical level of a segment within the database.

    RELOADED

    Total number of segment instances that are reloaded to a database.

    DIFFERENCE

    Difference between the reload count and the unload count. If there is no difference, this field will be left blank.

    If the reload count is greater than the unload count, the field will have a positive value. If the reload count is less than the unload count, the field will have a negative value.

  • TOTAL SEGMENTS IN DATABASE

    The following is a list of the TOTAL SEGMENTS IN DATABASE field items.

    Item Description

    UNLOADED

    Number of segment instances that were unloaded by the HD Reorganization Unload utility (DFSURGU0).

    RELOADED

    Number of segment instances that were reloaded by the HD Reorganization Reload utility (DFSURGL0).

    DIFFERENCE

    Difference between the number of reloads and unloads. If there is no difference, this field will be left blank.

2.5. Examples

The following is an example of reloading the TMAX01.DB1 data set created by DFSURGU0 to the database defined in TMAX01DB DBD using DFSUINPT DD.

//DFSURGL0    JOB   MSGLEVEL=1,MSGCLASS=X,CLASS=A,REGION=4096K
//*******************************************************************
//*    R E L O A D  ( H I D A M )
//*******************************************************************
//STEP020    EXEC   PGM=DFSRRC00,PARM='ULU,DFSURGL0,TMAX01DB'
//STEPLIB      DD   DSN=IMSVS.RESLIB,DISP=SHR
//IMS          DD   DSN=IMS.DBDMOD,DISP=SHR
//SYSPRINT     DD   SYSOUT=*
//DFSUINPT     DD   DSN=TMAX01.DB1,DISP=SHR
//DFSURWF1     DD   DSN=TMAX01.DFSURWF1,UNIT=3380,
//             SPACE=(TRK,(5000,500),RLSE),
//             DCB=(BLKSIZE=1008,LRECL=300,RECFM=VB),
//             DISP=(,CATLG,DELETE)
//DFSURCDS     DD   DSN=TMAX01.DFSURCDS,DISP=SHR
//TMAX01I1     DD   DSN=TMAX01.IX1,DISP=SHR
//TMAX01D1     DD   DSN=TMAX01.DD1,DISP=SHR
//TMAX01D2     DD   DSN=TMAX01.DD2,DISP=SHR

TMAX01I1 DD refers to the index data set, and TMAX01D1 and TMAX01D2 DDs refer to the database data sets. DFSURWF1 DD refers to the TMAX01.DFSURWF1 data set, which contains the logical relationship information. This data set is produced during the reload process and used for the Prefix Resolution utility (DFSURGL0) as its input data set.

2.6. Return Codes

The following are the results of executing DFSURGL0.

  • If program call is successful

    Returns 0.

  • If an error occurs

    SYSPRINT DD displays the relevant error message and returns the error code.

    The following is a list of the DFSURGL0 error codes.

    Code Description

    4

    The target segment to be reloaded does not exist.

    8

    The reload count differs from the unload count.

    16

    Indicates a system error that may have occurred for the following reasons:

    • Initializing OpenFrame system library has failed.

    • Reloading the database has failed.

    • An error occurred in other DFSURGL0 utility programs.

3. DFSURGU0

The DFSURGU0 utility unloads an HDAM, HIDAM or HISAM database to a sequential data set (SDS).

The DFSURGU0 utility program carries out the following functions:

  • Produces data sets unloaded from HDAM, HIDAM, and HISAM databases.

  • Produces statistics about the unloaded data set segments.

The DFSURGU0 utility is a counterpart to the IBM IMS DB’s DFSURGU0 utility.

3.1. EXEC Statements

The following shows how to specify the EXEC statement.

PGM=DFSRRC00,PARM='ULU,DFSURGU0,dbd-name,[formatopt]'
Item Description

PGM

Execution utility of an IMS DB program, DFSRRC00, which is used to execute the DFSURGU0 utility.

PARM

  • ULU, DFSURGU0: executes DFSURGU0 of the utility region.

  • dbd-name: specifies the DBD name of the target database to be unloaded.

  • [formatopt]

    • NOSEGNAME: omits the segment name from the output format.

    • -IXPDTFDV: sets the output format to the data output format of the source DB.

3.2. DD Statements

The following describes each DD statement.

Item Description

IMS DD

Specifies the library that contains the DBD specified in the EXEC script. (Required)

database DD

Specifies the data set of the target database to be unloaded. (Required)

The database DD name has to match the DD name described in DBD. In HIDAM databases, the relevant index data sets also need to be specified.

SYSPRINT DD

Displays the DFSURGU0 utility messages. (Required)

DFSURGU1 DD

Specifies the sequential data set to display after unloading the database. (Required)

For formatting the unload data set, refer to the HiDB migration data format.

3.3. Control Statements

No control statements are used for the DFSURGU0 utility. Any IBM mainframe control statements are ignored.

3.4. Statistics

When the database has been successfully unloaded, the SYSPRINT DD displays the following statistics.

 ******************** HIERARCHICAL DIRECT DB REORG UNLOAD **********************

                     D A T A B A S E    S T A T I S T I C S
 SEGMENT LEVEL STATISTICS                          RECORD LEVEL STATISTICS
 ===============================================================================
 MAXMUM  AVG    MAXIMUM  AVG      SEGMENT  SEGMENT TOTAL SEGMENTS  AVG COUNT PER
 TWINS   TWINS  CHILDREN CHILDREN NAME     LEVEL   BY SEG TYPE     DB RECORD
 -------------------------------------------------------------------------------
       1  1.00      1873  8.48    PBM01VAA       1           9628        1.00
       1  1.00         0  0.00    PBM01VAD       2           9628        1.00
       0  0.00         0  0.00    PBM01VAE       2              0        0.00
     567  2.93        12  1.55    PBM01VAB       2          28243        2.93
       1  1.00         0  0.00    PBM01VAF       3          28243        2.93
      11  0.55         0  0.00    PBM01VAC       3          15586        1.61
 -------------------------------------------------------------------------------
 TOTAL SEGMENTS IN DATABASE=   91328 AVERAGE DATABASE RECORD LENGTH=  2271 BYTES
 ===============================================================================

  • SEGMENT LEVEL STATISTICS

    The following is a list of the SEGMENT LEVEL STATISTICS field items.

    Item Description

    MAXIMUM TWINS

    Maximum number of twin instances allowed under the same parent segment. The value of this field for the root segment is always 1.

    AVG TWINS

    Average number of twin instances under the same parent segment.

    MAXIMUM CHILDREN

    Maximum number of child instances under the same parent segment instance.

    AVG CHILDREN

    Average number of child instances under the same parent segment instance. The lowest level segment has a value of 0 in this file type.

    SEGMENT NAME

    Segment name to which the same statistics can be applied.

    SEGMENT LEVEL

    The hierarchical level of the segment within the database.

  • RECORD LEVEL STATISTICS

    The following is a list of the RECORD LEVEL STATISTICS field items.

    Item Description

    TOTAL SEGMENTS BY SEG TYPE

    Number of all instances that share the same segment type.

    AVG COUNT PER DB RECORD

    Average number of segments of the same type within a record.

3.5. Examples

The following is an example of reading data from a database defined by TMAX01DB DBD and unloading the data to TMAX01.DB1 data set in DFSURGU1 DD.

//DFSURGU0    JOB   MSGLEVEL=1,MSGCLASS=X,CLASS=A,REGION=4096K
//******************************************************************
//*    HD REORGANIZATION UNLOAD UTILITY (DFSURGU0)                 *
//******************************************************************
//STEP010    EXEC   PGM=DFSRRC00,PARM='ULU,DFSURGU0,TMAX01DB'
//STEPLIB      DD   DSN=IMSVS.RESLIB,DISP=SHR
//IMS          DD   DSN=IMS.DBDMOD,DISP=SHR
//SYSPRINT     DD   SYSOUT=*
//TMAX01I1     DD   DSN=TMAX01.IX1,DISP=SHR
//TMAX01D1     DD   DSN=TMAX01.DD1,DISP=SHR
//TMAX01D2     DD   DSN=TMAX01.DD2,DISP=SHR
//DFSURGU1     DD   DSN=TMAX01.DB1,DISP=(,CATLG,DELETE),
//             UNIT=3380,LABEL=(,SL)

TMAX01I1 DD refers to the index data set. TMAX01D1 and TMAX01D2 DDs refer to the database data sets.

3.6. Return Codes

The following are the results of executing DFSURGU0.

  • If program call is successful

    Returns 0.

  • In an error occurs

    SYSPRINT DD displays the relevant error message and returns the error code.

    The following is the DFSURGU0 error code.

    Code Description

    8

    Indicates a system error that may have occurred for the following reasons:

    • Initializing OpenFrame system library has failed.

    • An error occurred in other DFSURGU0 utility programs.