ADARPE Utility: Extract TLOG Records

#### Search Results

Search

# ADARPE Utility: Extract TLOG Records

When File-type destination definitions are used (DTYPE=FILE), the records written to these destinations are written as TLOG records to the command log (CLOG). The ADARPE utility allows you to extract and process data from selected TLOG records in an Adabas command log (CLOG) file, sending the output to a user-selected output file. Records can be selected based on various selection criteria, including subscription name, destination name, and modification type. An output user exit can also be invoked to allow you to reject records prior to writing them to the output file. Finally, you can also specify selection criteria that allow you to control which data from the selected records is written to the output file.

This document describes the ADARPE utility.

- ADARPE Prerequisites

- ADARPE Syntax and Parameters

- ADARPE Output User Exits

- Sample JCL

- ADARPE Parameter Examples

- ADARPE Output Examples

## ADARPE Prerequisites

The input CLOG data set to an ADARPE run must be identified on the DDCLOG JCL statement for the run. The input data set provided must be a sequential CLOG data set created in one of the following ways:

- Directly by Adabas when writing a sequential CLOG.

- By the ADARES CLCOPY utility. For more information about this utility, read your Adabas utilities documentation.

The ADARPE output data sets must be defined with RECFM=FB or RECFM=VB.

## ADARPE Syntax and Parameters

This is the syntax of the ADARPE utility:

Each parameter is described below. These parameters can be used to filter the TLOG records that are extracted from the CLOG. Only records that meet all of the filter criteria set by these parameters are extracted.

> EXTRACT

>   The EXTRACT parameter is a required parameter. It is the main keyword that denotes the start of a set of extraction keywords and must be the first parameter specified for ADARPE. Each subsequent specification of the EXTRACT parameter will result in the definition of a new set of extract criteria.

> DBID

>   Optionally, you can specify a database from which records should be selected for extraction. All records for the specified database ID will be extracted, unless only specific files are requested using the FILE parameter.

>   Up to 100 DBID parameters can be specified in a single run of the ADARPE utility.

> DESTINATIONS

>   Optionally, you can specify one or more destination definition names to be used in filtering which records are extracted. Only records written to the destination names specified in this parameter will be extracted. Valid destination definition names are one to eight alphanumeric characters long. They must be unique within a given set of ADARPE extract parameters.

> FILE

>   This optional parameter can only be specified if the DBID parameter has previously been specified. Using this parameter, you can specify one to 100 file numbers within the database listed in the most recent DBID parameter. All records for these files will be extracted, unless other parameters set additional filter criteria for them.

>   File numbers specified must be unique within a given set of ADARPE extract parameters.

> HEADER

>   Use this optional parameter to indicate whether a header record will be written to the output file. Valid values are "YES" (write the header record) and "NO" (do not write the header record). The default is "YES".

>   The contents of the header (when HEADER=YES) is specified are stored in a URBU record.

> IMAGE

>   Use this optional parameter to identify the types of record images that should be written to the output file for the records that are selected. Valid values are described in the table below:

>   Value | Description
>   --- | ---
>   AI | Only after images of selected records are written to the output file. If no after image exists for a selected record, no payload data for that record is written.
>   BI | Only before images of selected records are written to the output file. If no before image exists for a selected record, no payload data for that record is written.
>   BOTH | Both before and after images of selected records are written to the output file. This is the default.

> MODIFICATIONTYPE

>   Optionally, use this parameter to identify the type of modifications you want to extract. Valid values for this parameter are described in the table below.

>   Value | Description
>   --- | ---
>   ALL | Use this value to indicate that records of all modification types should be written to the output file. This is the default.
>   DELETE | Use this value to indicate that only records of deletions should be written to the output file.
>   INSERT | Use this value to indicate that only records of insertions should be written to the output file.
>   ISTATE | Use this value to indicate that only records of initial-state operations should be written to the output file.
>   UPDATE | Use this value to indicate that only records of update operations should be written to the output file.

> NAME

>   This is a required parameter. Use this parameter to specify a name for a set of ADARPE extract parameters. Valid names can be up to eight characters long.

> OUTPUTEXIT

>   Optionally, use this parameter to specify the name of a user exit you want run to further filter the TLOG records in the CLOG. The ADARPE utility will load this user exit and call after all other parameter filter criteria have been applied to a record, but prior to writing the record to the output file.

>   Note
>   The user exit must be a program you have written and supplied in the JCL for the run.

>   User exit names must be one to eight alphanumeric characters long.

>   For more information about the output user exit, read ADARPE Output User Exits/

> OUTPUTFILE

>   This is a required parameter. Specify the output DD name of the output data set as listed in the JCL for the run. DD names must be one to eight alphanumeric characters long and must be unique within a given ADARPE run. Selected TLOG records from the CLOG are extracted to the file identified by this parameter.

> PAYLOADDATA

>   Optionally, use this parameter to indicate whether the payload data is written to the output file when a record is extracted. Valid values for this parameter are "YES" (extract the payload) and "NO" (do not extract the payload). The default is "YES".

> PAYLOADPREFIX

>   Optionally, use this parameter to indicate whether the URBD (data record) control information element is written to the output file when a record is extracted. Valid values for this parameter are "YES" (extract the URBD) and "NO" (do not extract the URBD). The default is "YES".

> RECORDINFO

>   Optionally, use this parameter to indicate whether the URBR (record) control information element is written to the output file when a record is extracted. Valid values for this parameter are "YES" (extract the URBR) and "NO" (do not extract the URBR). The default is "YES".

> RECORDPREFIX

>   Optionally, use this parameter to indicate whether the URBL (transaction log record) control information element is written to the output file when a record is extracted. Valid values for this parameter are "YES" (extract the URBL) and "NO" (do not extract the URBL). The default is "YES".

> STATE

>   Optionally, use this parameter to indicate whether the URBS (status/response) control information element is written to the output file when a record is extracted. Valid values for this parameter are "YES" (extract the URBS) and "NO" (do not extract the URBS). The default is "YES".

> SUBSCRIPTIONS

>   Optionally, you can specify one or more subscription definition names to be used in filtering which records are extracted. Only records covered by (assigned to) the subscriptions named in this parameter will be extracted. Valid subscription definition names are one to eight alphanumeric characters long. They must be unique within a given set of ADARPE extract parameters.

> TEST

>   The TEST parameter tests the operation syntax without actually performing the operation. Only the syntax of the specified parameters can be tested; not the validity of values and variables.

> TRANSACTIONINFO

>   Optionally, use this parameter to indicate whether the URBT (transaction) control information element is written to the output file when a record is extracted. Valid values for this parameter are "YES" (extract the URBT) and "NO" (do not extract the URBT). The default is "YES".

> TRANSACTIONLEVEL

>   Optionally, use this parameter to indicate the level of consistency the ADARPE utility maintains across sequential CLOGs from different runs of the utility. Valid values for this parameter are "NONE", "RECORD", or "TRAN".

## ADARPE Output User Exits

When an output user exit is specified for the run, it is loaded prior to processing the input sequential CLOGs. If a specified exit does not exist, the ADARPE utility will terminate with an error. Otherwise, the exit will be called prior to the record being written to an output file after the selection processing. The exit will be passed the parameters in a URBZ parameter block. For more information, read about the URBZ DSECT.

The ADARPE user exit call is structured as described by the URBQ DSECT.

## Sample JCL

The following sample JCL could be used to run ADARPE. In this example, three output files are produced, identified by the DD names OUTRPE1, OUTRPE2, and OUTRPE3. A sample job, EXTTLOG, is provided in the MVSJOBS data set.

    //ADARPE    JOB
    //*
    //ADARPE   EXEC PGM=ADARUN
    //STEPLIB  DD DISP=SHR,DSN=ARFvrs.LOAD       <=== ARF library
    //DDCLOG   DD DISP=SHR,DSN=ADABAS.REPTOR.CLOGCOPY
    //MERGIN1  DD DISP=SHR,DSN=EXAMPLE.MERGIN1
    //MERGIN2  DD DISP=SHR,DSN=EXAMPLE.MERGIN2
    //OUTRPE1  DD DSN=EXAMPLE.OUTPUT1,
    //           DISP=(,CATLG),UNIT=DISK,SPACE=(TRK,(1,1))
    //OUTRPE2  DD DSN=EXAMPLE.OUTPUT2,
    //           DISP=(,CATLG),UNIT=DISK,SPACE=(TRK,(1,1))
    //OUTRPE3  DD DSN=EXAMPLE.OUTPUT3,
    //           DISP=(,CATLG),UNIT=DISK,SPACE=(TRK,(1,1))
    //DDDRUCK  DD SYSOUT=X
    //DDPRINT  DD SYSOUT=X
    //SYSUDUMP DD SYSOUT=X
    //DDCARD   DD *
    ADARUN PROGRAM=ADARPE,SVC=xxx,DEVICE=dddd,DB=yyyyy
    /*
    //DDKARTE  DD *
    ADARPE EXTRACT NAME=OUT1
    ADARPE  OUTPUTFILE=OUTRPE1
    ADARPE  DESTINATIONS='AA,BB'
    *
    ADARPE EXTRACT NAME=OUT2
    ADARPE  OUTPUTFILE=OUTRPE2
    ADARPE  DBID=dddd,FILE=ffff
    *
    ADARPE EXTRACT NAME=OUT3
    ADARPE  OUTPUTFILE=OUTRPE3
    ADARPE  SUBSCRIPTIONS='CC,DD'
    *
    /*

The following table describes the DD statements in this JCL in more detail:

DD Statement | Storage | Identifies
--- | --- | ---
DDCLOG | disk | The input TLOG data from the sequential command log (CLOG), created by ADARES CLCOPY or output from a previous ADARPE run.
MERGIN1/MERGIN2 | disk | Intermediate files from and to which intermediate results may be read or written.
DDDRUCK | printer | The ADARPE report, messages, and parameters.
DDPRINT | printer | Pertinent ADARUN messages.
DDCARD | reader | Pertinent ADARUN parameters.
DDKARTE | reader | The ADARPE selection parameters.
OUTRPEn | disk | The sequential output file specified on the OUTPUTFILE parameter.

## ADARPE Parameter Examples

The following example is for extracts named OUT6, OUT4, and OUT3. This run of ADARPE produces three output files OUTRPE1, OUTRPE2, and OUTRPE3.

    ADARPE EXTRACT NAME=OUT6
    ADARPE DBID=1955,FILE=222
    ADARPE OUTPUTFILES='OUTRPE1'
    ADARPE EXTRACT NAME=OUT4
    ADARPE DBID=1955,FILE=224
    ADARPE OUTPUTFILES='OUTRPE2'
    ADARPE EXTRACT NAME=OUT3
    ADARPE DBID=1955,FILE=229
    ADARPE OUTPUTFILES='OUTRPE3'

The following parameters would only test the parameters set for an ADARPE utility run; the ADARPE utility would not actually run. In addition, these series of parameters request that an output user exit named EXIT1 be called during the ADARPE run.

    ADARPE TEST
    ADARPE EXTRACT NAME=OUT6
    ADARPE DBID=1955,FILE=222
    ADARPE OUTPUTFILES='OUTRPE1'
    ADARPE OUTPUTEXIT=EXIT1
    ADARPE TRANSACTIONINFO=NO
    ADARPE EXTRACT NAME=OUT4
    ADARPE DBID=1955,FILE=224
    ADARPE OUTPUTFILES='OUTRPE2'
    ADARPE TRANSACTIONINFO=NO
    ADARPE OUTPUTEXIT=EXIT2
    ADARPE EXTRACT NAME=OUT3
    ADARPE DBID=1955,FILE=229
    ADARPE TRANSACTIONINFO=NO
    ADARPE OUTPUTFILES='OUTRPE3'
    ADARPE OUTPUTEXIT=EXIT1

## ADARPE Output Examples

Here is a sample of the output produced by an ADARPE run. The input file mentioned in the output is a reference to the CLOG file that was read as input to ADARPE.

    A D A R P E   V3.2  SM1   DBID = 01954  Started           2007-07-13  08:25:14

    Parameters:
    -----------

    ADARPE EXTRACT NAME=OUT5
    ADARPE  OUTPUTFILE=OUTRPE1
    ADARPE  TRANSACTIONLEVEL=RECORD

    A D A R P E   V3.2  TLOG Extract Utility Summary          2007-07-13  08:43:11

    Input file statistics
               862 CLOG records were read
               862 TLOG records were read
               277 Destination output data records were read
                88 URBT records were read
                88 URBR records were read
               101 URBD records were read
                 0 URBS records were read

    Intermediate input file statistics
                 4 records were read from intermediate input file MERGIN1
                 1 URBT records were read
                 1 URBR records were read
                 0 URBD records were read
                 0 URBS records were read
                 2 header/trailer records were read

    Intermediate output file statistics
                 2 records were written to intermediate output file MERGIN2
                 0 URBT records were written
                 0 URBR records were written
                 0 URBD records were written
                 0 URBS records were written
                 2 header/trailer records were written

    EXTRACT=OUT5
               279 records selected
                89 URBT records were selected
                89 URBR records were selected
               101 URBD records were selected
                 0 URBS records were selected

               279 records written
                88 URBT records were written
                89 URBR records were written
               101 URBD records were written
                 0 URBS records were written
                 1 URBU records were written

    A D A R P E  Terminated normally                          2007-07-13  08:43:11

The intermediate input and output messages are provided only if TRANSACTIONLEVEL=RECORD or TRAN is specified.

If a user exit (OUTPUTEXIT parameter) supplied in the run, an additional line is printed indicating if any records have been skipped. For example:

    A D A R P E   V3.2  SM1   DBID = 01954  Started           2007-07-13  11:33:40

    Parameters:
    -----------

    ADARPE EXTRACT NAME=OUT3
    ADARPE  OUTPUTFILE=OUTRPE1

    ADARPE EXTRACT NAME=OUT5
    ADARPE  OUTPUTFILE=OUTRPE2
    ADARPE  OUTPUTEXIT=UEXIT2

    A D A R P E   V3.2  TLOG Extract Utility Summary          2007-07-13  11:33:40

    Input file statistics
              1286 CLOG records were read
              1286 TLOG records were read
               385 Destination output data records were read
               124 URBT records were read
               124 URBR records were read
               136 URBD records were read
                 1 URBS records were read

    EXTRACT=OUT3
               385 records selected
               124 URBT records were selected
               124 URBR records were selected
               136 URBD records were selected
                 1 URBS records were selected

               386 records written
               124 URBT records were written
               124 URBR records were written
               136 URBD records were written
                 1 URBS records were written
                 1 URBU records were written

    EXTRACT=OUT5
               385 records selected
               124 URBT records were selected
               124 URBR records were selected
               136 URBD records were selected
                 1 URBS records were selected

               101 records written
               124 URBT records were written
               124 URBR records were written
               136 URBD records were written
                 1 URBS records were written
                 1 URBU records were written
               285 records skipped by userexit UEXIT2

    A D A R P E  Terminated normally                          2007-07-13  11:33:40

### On this page

- ADARPE Prerequisites
- ADARPE Syntax and Parameters
- ADARPE Output User Exits
- Sample JCL
- ADARPE Parameter Examples
- ADARPE Output Examples