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.
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.
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 or DLBL name of the output data set as listed in the JCL for the run. DD and DLBL 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".
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.
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. |
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
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