Archive-Related Utilities

Edit online

This section explains the archiving related utilities: DGADARRT, DGADARBT, and DGADBKEY.

DGADARRT

The DGADARRT utility (ARchive Run Task) has the following functions:

  • Notifies IBM® Connect:Direct® of the availability of a statistics file pair for reuse due to the completion of archiving
  • Optionally adds an entry to the directory of archive files
  • By default, removes the oldest record from a full archive directory to make room for the newest record.

You can invoke DGADARRT from within a Process through the RUN TASK statement. Use this utility when submitting a Process at statistics file pair switch time that archives the statistical data using IBM Connect:Direct to copy the statistics to another file. When the copy operation successfully completes, the system can update the directory and send the archive notification.

The program accepts three parameters through the RUN TASK statement.

  • The first parameter is required and is the data set name of the statistics entry-sequenced cluster that is archived.
  • The second parameter is optional, and is the data set name of the archive file.
  • The third parameter is optional, and specifies whether to age the archive directory.

DGADARRT always sends archive notification to the DTF. If you specify STAT.ARCH.CONFIRM=NO and no notification requirement exists, the notification has no effect.

The addition of the entry in the directory of archive files depends on the specification of the second parameter string. If the second parameter is present, then the system updates the directory to contain an entry for the new archive file.

The following is an example of an archive Process. This Process copies a statistics file to a sequential tape file and then invokes DGADARRT to send archive notification to the DTF and update the directory of archive files. IBM Connect:Direct passes the data set name of the statistics file to the Process in the form of the symbolic parameter &EDSN.

DGAPSTAT PROCESS PNODE=primary.node                               -
                 SNODE=secondary.node                             -
                 PRTY=10                                          -
                 STARTT=(TODAY)                                   -
                 &EDSN=
ARC      COPY    FROM (DSN=&EDSN)                                 -
                 TO   (DSN=stat.archive.dsn(+1)                   -
                       DISP=(NEW,CATLG,DELETE)                    -
                 DCB=(DSORG=PS,RECFM=VB,LRECL=2048)               -
                       UNIT=CART -
                       LABEL=(1,SL) )
          IF (ARC EQ 0) THEN
           RUN TASK (PGM=DGADARRT,PARM=("&EDSN", - 
                         "stat.archive.dsn(+0)")) 
          EIF

Whether the archive directory ages off the oldest record to make room for the newest depends on the third parameter, ARCAGE.

ARCAGE=Y - Requests that if the archive directory is full, the oldest record is deleted to make room for the newest. The user receives notification that the record is aged off the archive directory. The amount of time it takes to add a record to the archive directory is insignificant. But the amount of time it takes to age off the oldest record is noticeable and increases with the size of the archive directory, because all of the records in the ESDS must be rewritten. This is the default.

ARCAGE=N - Requests that if the archive directory is full, the utility stops without updating the archive directory.

The following example shows the ARCAGE parameter specified in the DGADARRT utility for use within a Process through the Run Task statement:

DGAPSTAT PROCESS PNODE=primary.node                               -
                 SNODE=secondary.node                             -
                 PRTY=10                                          -
                 STARTT=(TODAY)                                   -
                 &EDSN=
ARC      COPY    FROM (DSN=&EDSN)                                 -
                 TO   (DSN=stat.archive.dsn(+1)                   -
                       DISP=(NEW,CATLG,DELETE)                    -
                 DCB=(DSORG=PS,RECFM=VB,LRECL=2048)               -
                       UNIT=CART -
                       LABEL=(1,SL) )
          IF      (ARC EQ 0) THEN
          RUN TASK (PGM=DGADARRT,PARM=("&EDSN", -
                    "stat.archive.dsn(+0)", -
                    "ARCAGE=Y"))
         EIF

To prevent aging, set ARCAGE=N. As a result, the newest record is discarded, rather than the oldest.

DGADARBT

The DGADARBT utility (ARchive BaTch) has the following two functions:

  • Notifies IBM Connect:Direct that a statistics file pair is archived and is available for reuse
  • Optionally adds an entry to the directory of archive files
  • By default, removes the oldest record from a full archive directory to make room for the newest record.

Execute DGADARBT as a step within a batch job. Use DGADARBT when submitting a job that archives the statistical data by executing IDCAMS or some other utility to COPY the data to another file at statistics file pair switch time. The system can update the directory and send archive notification upon successful completion of the copy operation.

DGADARBT requires that the system allocate the archived statistics file with the data definition name (DDNAME) of STESDS.

DGADARBT always sends archive notification to the DTF. If you specify STAT.ARCH.CONFIRM=NO and no notification requirement exists, then the notification has no effect.

If you want DGADARBT to update the directory of archive files, the system must allocate the following DDNAMEs:

  • STADIR, the directory file
  • STARCH, the archive file

In the following example, the archive Process submits a batch archive job using DGADTSUB to substitute the statistics file data set name into the job stream. The system passes this data set name to the archive Process as the symbolic parameter &EDSN. Refer to the IBM Sterling Connect:Direct for z/OS® User Guide for information about how to use DGADTSUB. The submitted job uses the IDCAMS utility to copy the statistics records to an archive file. If the IDCAMS step is successful, IBM Connect:Direct invokes DGADARBT to both send the archive notification and update the directory.

The following figure is a sample archive Process.

ARCHSTRJ PROCESS PNODE=primary.node                                -
                 SNODE=secondry.node                               -
                 PRTY=10                                           -
                 STARTT=(TODAY)                                    -
                 &EDSN=
         RUN TASK (PGM=DGADTSUB,                                    -
            PARM=("DSN=SYS3.CONNECT.INSTALL.JCL(ARCHJOB),DISP=SHR",-
            "DSNAME &EDSN"))

The following figure is a sample archive job stream.

//ARCHJOB  JOB (ACCT),CLASS=A
//*
//* ---------------------------------------------------------------- *
//*        IDCAMS step to archive the Statistics ESDS:               *
//* ---------------------------------------------------------------- *
//*
//STEP1   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INPUT    DD DISP=SHR,DSN=&DSNAME
//OUTPUT   DD DISP=(NEW,CATLG,DELETE),
//            DSN=stat.archive.dsn(+1),
//            UNIT=CART,
//            LABEL=(1,SL)
//SYSIN    DD *
  REPRO INFILE(INPUT) OUTFILE(OUTPUT)
/*
//*
//* ---------------------------------------------------------------- *
//*        DGADARBT step to notify DTF that ESDS was archived:       *
//* ---------------------------------------------------------------- *
//*
//STEP2   EXEC PGM=DGADARBT,COND=(0,LT,STEP1)
//STEPLIB  DD  DSN=prod.ndmlib,DISP=SHR
//SYSOUT   DD  SYSOUT=*
//STESDS   DD  DISP=SHR,DSN=*.STEP1.INPUT
//STARCH   DD  DISP=SHR,DSN=*.STEP1.OUTPUT
//STADIR   DD  DSN=stat.archdir.dsn,DISP=SHR
//

The DGADARBT utility accepts the same ARCAGE parameter as specified for DGADARRT. It is the first and only OS parameter for this utility.

The following example shows the ARCAGE parameter specified in the DGADARRT utility to run as a step in a batch job:

//ARCHJOB JOB   (ACCT),CLASS=A
//*//
//* ---------------------------------------------------------------- *
//* IDCAMS step to archive the Statistics ESDS: *
//* ---------------------------------------------------------------- *
//*
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INPUT DD DISP=SHR,DSN=&DSNAME
//OUTPUT DD DISP=(NEW,CATLG,DELETE),
// DSN=stat.archive.dsn(+1),
// UNIT=CART,
// LABEL=(1,SL)
//SYSIN DD *
REPRO INFILE(INPUT) OUTFILE(OUTPUT)
/*
//*
//* ---------------------------------------------------------------- *
//* DGADARBT step to notify DTF that ESDS was archived: *
//* ---------------------------------------------------------------- *
//*
//STEP2 EXEC PGM=DGADARBT,COND=(0,LT,STEP1),PARM='ARCAGE=Y'
//STEPLIB DD DSN=prod.ndmlib,DISP=SHR
//SYSOUT DD SYSOUT=*
//STESDS DD DISP=SHR,DSN=*.STEP1.INPUT
//STARCH DD DISP=SHR,DSN=*.STEP1.OUTPUT
//STADIR DD DSN=stat.archdir.dsn,DISP=SHR
//

To prevent aging, set ARCAGE=N. As a result, the newest record is discarded, rather than the oldest.

DGADBKEY

The DGADBKEY utility (Build KEYs) loads a statistics key-sequenced cluster with index information for an associated statistics entry-sequenced cluster. DGADBKEY must execute as a batch job step.

DGADBKEY enables the recreation of index information for archived statistics data so that you can issue a SELECT STATISTICS command. You can also use this utility to rebuild index information for statistics files in the DTF file pair list in certain cases. Refer to Change the File Pair Configuration for additional information.

DGADBKEY requires the allocation of DDNAMEs, ESDSnn and KSDSnn, with the entry-sequenced and key-sequenced clusters respectively. IBM Connect:Direct loads the entry-sequenced cluster with the statistics records for building the index information. The key-sequenced cluster must either be empty, or be defined with the REUSE attribute. DGADBKEY erases any records in the KSDS before writing the new information. The size of the KSDS is about 25% of the size of the associated ESDS. The KSDS must have the characteristics of a statistics key-sequenced cluster. Refer to VSAM Files DASD Requirement and Description in the IBM Sterling Connect:Direct for z/OS Configuration Guide for details about allocating statistics clusters.

The following is an example of a job stream to execute DGADBKEY.

//DGADBKEY JOB (ACCT),CLASS=A
//STEP1    EXEC PGM=DGADBKEY
//STEPLIB  DD  DISP=SHR,DSN=prod.SDGALINK
//ESDS01   DD  DISP=SHR,DSN=stat.esds01
//KSDS01   DD  DISP=SHR,DSN=stat.ksds01
//SYSOUT   DD  SYSOUT=*
//

PARM=CONSOLIDATE allows DGADBKEY to build a KSDS for an ESDS that contains multiple archived statistics datasets. To use this parameter, create a large flat file of archived statistics, loading them in date order from the oldest to the newest. Next, load this file to an ESDS that will hold all the records and create a KSDS for this ESDS. Then execute DGADBKEY using PARM=CONSOLIDATE to build the KSDS file. This file pair is available as an Archived Statistics Dataset.