ADARPL Utility: PLOG Replication Replay

The ADARPL utility, also known as the Replay Utility, provides a mechanism by which you can read an Adabas PLOG and resend replicated data to one or more Event Replicator Servers. This utility reads the sequential (merged) PLOG of an Adabas database and, based on the parameters you specify, sends related data to one or more Event Replicator Servers.

Note:
The version of Event Replicator specified in an ADARPL utility job must match the version of Event Replicator used by the Event Replicator Server. In addition, the Adabas version used by the Event Replicator Server must be greater than or equal to the Adabas version used in an ADARPL utility job.

Replay processing in Event Replicator for Adabas can be run in any of three modes: synchronized, unsynchronized, and replay-only. When you initiate a replay process as an ADARPL batch job without specifying a replay token generated using the Adabas Event Replicator Subsystem, the replay process is run in unsynchronized mode. You can run ADARPL in synchronized and replay-only modes if you specify the replay token for a replay request generated using the Adabas Event Replicator Subsystem or the standalone replay API.

In addition, you can automate ADARPL processing. When you request ADARPL automation, the Event Replicator Server nucleus will automatically generate an ADARPL job stream using parameters specified using the Adabas Event Replicator Subsystem or a standalone replay API. For complete information on automating ADARPL processing, read Automating Replay Processing.

For complete information on when to use replay processing and replay processing modes, read Understanding Replay Modes. For complete information on how to generate a replay token using the Adabas Event Replicator Subsystem, read Initiating a Replay Request Using the Adabas Event Replicator Subsystem. For complete information on how to generate a replay token using the standalone replay API, read Initiating a Replay Request Using the Standalone API.

This document covers the following topics:


Functional Overview

The Replay Utility can recover replication data from the sequential PLOG data sets (after copying and merging them) for the time over which replication processing was interrupted. You must be sure to supply the correct:

  • PLOG information

  • date and time settings

  • file number, subscription, and destination settings

  • target Event Replicator Server information

New data replication and processing for the same database files can be occurring simultaneously, although replication does not need to be active to use the Replay Utility.

When replication has been activated for a database file and the stream of replication data coming into the Event Replicator Server for that file is interrupted for any reason, you can use the Replay Utility. The following processing occurs once the Replay Utility is started:

  1. The Replay Utility reads through all transactions on the specified sequential PLOG, starting with records with the specified start (from) date and time, and ending with records with the stop (to) date and time. Start and stop times are specified in the Replay Utility run.

  2. As records are read, only those for fully completed transactions on the specified database files are processed. However, ADARPL cannot determine the exact time of every update recorded on the PLOG. It tries to accurately process only the data requested by the FROMTIME and TOTIME parameters, subject to the rule that it never processes less protection data than requested, as follows:

    • Replication data is built for all transactions read from the PLOG.

    • Replication data is built only for transactions where both the transaction start and the transaction end (ET) are found on the input PLOG. This ensures that no partial transactions will be sent to the Event Replicator Server during the replay.

    • Replication data for transactions that end (ET) before the FROMDATE/FROMTIME specification are discarded and not sent to the Reptor. This selection is based on the PLOG record timestamp.

    • If FROMDATE/FROMTIME is not specified all replication data is sent to the Event Replicator Server.

    • If TODATE/TOTIME is specified replay processing stops when a PLOG record is read that has a timestamp higher than or equal to TOTIME. At this time partial transactions (any replication data built but not yet committed) are discarded and will not be sent to the Event Replicator Server.

    • If TODATE/TOTIME is not specified ADARPL processing stops after reading the last block of the PLOG. At this time partial transactions (any replication data built but not yet committed) are discarded and will not be sent to the Event Replicator Server.

  3. Transactions selected for processing are sent to the target Event Replicator Servers selected for the run. The target Event Replicator Servers may differ from those specified originally for replication.

  4. If a transaction was sent successfully to the Event Replicator Server before the original failure and its Replay Utility resend flag is turned on, messages are sent to the target application indicating that duplicate data may have been replicated. If a transaction was sent successfully to the Event Replicator Server before the failure and its Replay Utility resend flag is turned off for the record, no warning messages are sent, although duplicate data may still have been replicated. The resend flags are set based on the resend date and times set for Replay Utility run. For more information, read about the Replay Utility syntax.

  5. Specification of RESENDDATE and RESENDTIME are not supported when using a token. When using a token, ADARPL will list the "ADARPL start date/time" which was used to select the PLOG datasets to be allocated to the replay. This information is only for your reference - it does not affect the above transaction selection.

    All date and time parameters are specified in local time. FROMDATE, FROMTIME, TODATE and TOTIME are internally converted to UTC since the time stamps on the PLOG are written in UTC. This conversion is always done based on the current time difference between local time and UTC.

ADARPL Prerequisites

The following prerequisites must be met to effectively use the Replay Utility in batch mode:

  • Verify that the following ADARUN parameters are specified in ADARPL JCL:

    ADARUN PROG=ADARPL,DBID=dbid,SVC=svc,MODE=MULTI

    where dbid is the Adabas database ID on which the files that are being replicated reside and svc is the SVC number to be used for communications with Adabas and the Event Replicator Server. Running the Replay Utility with MODE=SINGLE will default to MODE=MULTI.

  • Verify that the correct PLOG is used for the run and that it is a sequential PLOG, not a dual PLOG. The PLOG is specified with the DD name DDSIIN.

  • Specify valid values for ADARPL parameters, as appropriate. The following information is needed.

    • Determine what the last successful transmission time was for replication. You can obtain this timestamp from the deactivation messages that occur when replication stops.

    • Determine the file numbers, subscriptions, or destinations for which replication data was not received. At least one file number, subscription definition name, or destination definition name must be specified. Multiple files, subscriptions, and destinations may be specified simultaneously.

    • Determine what the resend dates and times for the data should be so that the target Event Replicator Server is warned when duplicate transactions may have been sent.

    • Determine the IDs of the Event Replicator Servers to which you want to send the data. These target IDs may differ from those specified originally for replication.

  • Verify that the target application can handle duplicate records.

  • Either the Adabas database must be active or the DDASSO DD statement must be specified in the JCL, identifying the ASSO data set for the run. The Replay Utility will attempt to issue a call to Adabas to obtain the GCB, FCBs, and FDTs from the nucleus. If this call fails, it will attempt to read this information itself using the ASSO data set specified in the Replay Utility run.

    Note:
    When running ADARPL job using the TOKEN parameter, the Adabas database must be active.

ADARPL Syntax and Parameters

The syntax and parameters vary, depending on whether you want to initiate ADARPL using a token generated by the Adabas Event Replicator Subsystem.

Syntax for Initiating ADARPL Without A Token

The syntax of the ADARPL utility to initiate replay processing without a token is:

ADARPL REPLAY { [FILES=fn1[,fn2]...]  [SUBSCRIPTION=sname[,sname]...]  [DESTINATION=dname[,dname]...]  }
             [FROMDATE=yyyymmdd [FROMTIME=hhmmss]]
             [LRPL=poolsize]
             [NU=numusers]
             [ORIGINDBID=dbid]
             [ORIGINFILES=fn1[, fn2]...]
             [PLOGDBID=dbid]
             [PLOGFILES=fn1[, fn2]...]
             [RESENDDATE=yyyymmdd [RESENDTIME=hhmmss]]
             [RPLDSBI={Y | N}[,{Y | N}]...]
             [RPLKEY=primary-key[,primary-key]...]
             [RPLSORT={YES | NO}
             [RPLTARGETID=id | RPLTARGETS=id1[,id2]...]
             [STATINTERVAL=interval]
             [TODATE=yyyymmdd [TOTIME=hhmmss]]

Syntax for Initiating ADARPL With A Token (Synchronized and Replay-only Replay Modes)

The syntax of the ADARPL utility to initiate replay processing using a token generated from the Adabas Event Replicator Subsystem:

ADARPL REPLAY TOKEN=num
             RPLTARGETID=id
             [LRPL=poolsize]
             [NU=numusers]

Note:
When running ADARPL with the TOKEN parameter, Adabas must be active.

ADARPL Parameters

Each parameter is described in the following table. Not all parameters can be used in the same run.

Parameter Description Required? Default
DESTINATION Specifies one or more valid Event Replicator for Adabas destination definition names.

Note:
The maximum number of values you can specify for this parameter is 1,000.

No -- although at least one DESTINATION. FILE, or SUBSCRIPTION parameter must be specified. none
FILES Specifies one or more valid Adabas file numbers for which replication was turned on. The PLOG records for these files will be replayed and replicated, based on other settings in the Replay Utility run.

Note:
The maximum number of values you can specify for this parameter is 1,000.

No -- although at least one DESTINATION. FILE, or SUBSCRIPTION parameter must be specified. none
FROMDATE Specifies a PLOG record end date in yyyymmdd format. Replay processing will start with transactions in the PLOG that ended at or after this date. No Replay Utility processing starts at the beginning of the PLOG.
FROMTIME Specifies a PLOG record end time in hhmmss format. Replay processing will start with transactions in the PLOG that ended at or after this time. This parameter cannot be specified unless the FROMDATE parameter is specified also. No Replay Utility processing starts at the beginning of the PLOG records for the date specified by the FROMDATE parameter, if any.
LRPL Specifies the size of the replication pool to be used by ADARPL for keeping replication data. Values can also be specified in kilobytes by adding a "K" after the value (for example, 1000K). No 100,000 bytes
NU Specifies the number of User Queue Elements that will be generated during a replay process. This number must be greater than or equal to the maximum number of users that have open transactions simultaneously. No 1000
ORIGINDBID Specifies the Adabas database ID (the URBTDBID) that should be listed in the replicated PLOG transactions sent to the Event Replicator Server during replay. This parameter is particularly useful when the Event Replicator Server receiving the replayed data uses a different series of database numbers in its subscriptions than the Adabas database associated with the PLOG being replayed.

For example, if an Adabas database has a DBID of 10, but the equivalent Event Replicator Server has a DBID of 50 and corresponding subscriptions for DBID 50, you would specify 50 as the value of the ORIGINDBID in the replay run. This would ensure that the replay transactions from database 10 are processed by the subscription for database 50.

No The database ID specified by the ADARUN DBID parameter for the ADARPL run.
ORIGINFILES This parameter can only be specified if the FILES parameter is also specified. It allows you to specify the Adabas file number that should be listed in the replicated PLOG transactions sent to the Event Replicator Server during replay processing. This parameter is particularly useful when the Event Replicator Server receiving the replayed data uses a different series of file numbers in its subscriptions than the Adabas database associated with the PLOG being replayed.

Note:
The maximum number of values you can specify for this parameter is 1,000.

No none
PLOGDBID Specifies an alternate Adabas database ID. The records from the PLOG data set associated with this alternate Adabas database are replayed to the Event Replicator Server using the GCBs and FCB/FDTs from the database specified by the ADARUN DBID parameter. In other words, using this parameter you can run ADARPL with a PLOG from one database and the ADARUN DBID pointing to a different database.

For example, you might want to run ADARPL using a production PLOG in a test environment. In this case, the ADARUN DBID would point to the test database and the PLOGDBID parameter would be set to the production database ID.

No The database ID specified by the ADARUN DBID parameter for the ADARPL run.
PLOGFILES This parameter can only be specified if the FILES parameter is also specified. It allows you to specify alternate PLOG file numbers for the run. The records from the alternate PLOG files are replayed to the Event Replicator Server.

Notes:

  1. This parameter cannot be specified if any of the files listed in the FILES parameter is for a file in an expanded file chain.
  2. The maximum number of values you can specify for this parameter is 1,000.
No none
REPLAY A required keyword for the Replay Utility. Yes none
RESENDDATE Specifies a PLOG record date in yyyymmdd format at which the Replay Utility should turn off its resend flags. Records with dates after the specified RESENDDATE will have their resend flags turned off. No Replay Utility send all transactions with the resend flag turned on.
RESENDTIME Specifies a PLOG record time in hhmmss format at which the Replay Utility should turn off its resend flags. This parameter cannot be specified unless the RESENDDATE parameter is specified also. Records with times after the specified RESENDTIME will have their resend flags turned off. No Replay Utility send all transactions for records prior to the date specified by the RESENDDATE parameter (if any) with the resend flag turned on.
RPLDSBI Specifies whether the collection of before images of data storage should occur for an update command to the file. This parameter can only be specified if either the RPLTARGETID or RPLTARGETS parameter is specified.

Valid values for this parameter are "Y" (the collection of before images of data storage will occur for the file) or "N" (this information is obtained from the FCB).

If this parameter is specified, one setting must be specified for each file in the FILES parameter. Values should be listed in single quotes and separated by commas. To specify the default, simply type a comma for that file's value. In the following example, the second file is using the default (N): RPLDSBI='Y,,Y,Y'

This parameter is only allowed if FILES parameter is specified.

Note:
The maximum number of values you can specify for this parameter is 1,000.

No N
RPLKEY Specifies the primary key for replication. This parameter can only be specified if either the RPLTARGETID or RPLTARGETS parameter is specified.

If this parameter is specified, one setting must be specified for each file in the FILES parameter. Values should be listed in single quotes and separated by commas. To specify a blank RPLKEY in a list, simply type a comma for that file's value. In the following example, the third file in the FILES list has not RPLKEY: RPLKEY='AA,AB,,AG'

This parameter is only allowed if FILES parameter is specified.

Note:
The maximum number of values you can specify for this parameter is 1,000.

No Replay Utility assumes no primary key.
RPLSORT Specifies whether Adabas transaction data sorting should occur or not. Valid values for this parameter are "YES" or NO. For complete information on the affects of using RPLSORT, read about the ADARUN RPLSORT Parameter. No YES
RPLTARGETID Specifies the target ID of the Event Replicator Server to which the Replay Utility transactions should be sent. This parameter is mutually exclusive with the RPLTARGETS parameter; only one of them should be specified in a Replay Utility run.

If more than one file is specified in the FILES parameter, all transactions from these files will be sent to the same Event Replicator Server target. Only one Event Replicator target ID can be specified per file.

Yes, if the SUBSCRIPTION, , or DESTINATION parameters are specified. Otherwise, this parameter is not required. Event Replicator target ID stored in the FCB is used.
RPLTARGETS Specifies the target IDs of the Event Replicator Servers to which Replay Utility transactions should be sent. This parameter is mutually exclusive with the RPLTARGETID parameter; only one of them should be specified in a Replay Utility run.

Only one Event Replicator target ID can be specified per file. One setting must be specified for each file in the FILES parameter. Values should be separated by commas. To use the default, simply type a comma for that file's value. In the following example, the target ID for the third file is obtained from the FCB: RPLTARGETS=23,24,,25

This parameter can be specified only if the SUBSCRIPTION and DESTINATION parameters are not specified.

Note:
The maximum number of values you can specify for this parameter is 1,000.

No Event Replicator target ID stored in the FCB is used.
STATINTERVAL Specifies the interval, in seconds, at which ADARPL should print out DSTAT statistics. Valid values are "0" (zero) or an integer in the range from "60" to "2,147,483,647". A value of "0" indicates that statistics should not be printed. No 0
SUBSCRIPTION Specifies one or more valid Event Replicator for Adabas subscription definition names.

Note:
The maximum number of values you can specify for this parameter is 1,000.

No -- although at least one DESTINATION. FILE, or SUBSCRIPTION parameter must be specified. none
TODATE Specifies a PLOG record end date in yyyymmdd format. Replay processing will stop with transactions in the PLOG that ended before this date. No Replay Utility processing stops at the end of the PLOG.
TOKEN

Specifies the token number of the replay request generated using the Adabas Event Replicator Subsystem. This token number can be found in the Event Replicator Server job log or the message (or other returned data) that was issued by the Adabas Event Replicator Subsystem or the standalone replay API when the replay request was initiated.

For complete information on how to generate a replay token using the Adabas Event Replicator Subsystem, read Initiating a Replay Request Using the Adabas Event Replicator Subsystem. For complete information on how to generate a replay token using the standalone replay API, read Initiating a Replay Request Using the Standalone API.

Valid values are positive integers between 1 and 32767.

Yes, if you want to initiate replay processing using a replay token none
TOTIME Specifies a PLOG record end time in hhmmss format. Replay processing will stop with transactions in the PLOG that ended before this time. This parameter cannot be specified unless the TODATE parameter is specified also. No Replay Utility processing stops at the end of the PLOG records for the date specified by the TODATE parameter, if any.

Commands Useful to ADARPL

The DSTAT command prints statistics about ADARPL processing on request. The interval at which the statistics are printed is governed by the setting of the STATINTERVAL parameter specified when ADARPL was started.

For more information about this command, read DSTAT Command.

ADARPL Examples

This section provides three examples of ADARPL parameter usage.

Example 1 -- Using FILES and RPLTARGETID

ADARPL REPLAY FILES=1,2,3,4
              RPLDSBI='Y,Y,Y,N'
              RPLKEY='AA,AB,,AG'
              RPLTARGETID=25

In this example:

  • File 1: the collection of before images of data storage will occur for this file during replay processing (RPLDSBI=Y), the primary key AA will be used, and the replicated data will be sent to the Event Replicator Server target 25.

  • File 2: the collection of before images of data storage will occur for this file during replay processing (RPLDSBI=Y), the primary key AB will be used, and the replicated data will be sent to the Event Replicator Server target 25.

  • File 3: the collection of before images of data storage will occur for this file during replay processing (RPLDSBI=Y) and the replicated data will be sent to the Event Replicator Server target 25. Its primary key will be blank.

  • File 4: the collection of before images of data storage will not occur for this file during replay processing (RPLDSBI=N), the primary key AG will be used, and the replicated data will be sent to the Event Replicator Server target 25.

Example 2 -- Using FILES and RPLTARGETS

ADARPL REPLAY FILES=1,2,3,4
              RPLTARGETS=23,24,25,26
              RPLDSBI=',,,,'
              RPLKEY=',,,,'
  • File 1: the collection of before images of data storage will not occur for this file during replay processing (RPLDSBI=N is the default) and the replicated data will be sent to the Event Replicator Server target 23. Its primary key will be blank.

  • File 2: the collection of before images of data storage will not occur for this file during replay processing (RPLDSBI=N is the default) and the replicated data will be sent to the Event Replicator Server target 24. Its primary key will be blank.

  • File 3: the collection of before images of data storage will not occur for this file during replay processing (RPLDSBI=N is the default) and the replicated data will be sent to the Event Replicator Server target 25. Its primary key will be blank.

  • File 4: the collection of before images of data storage will not occur for this file during replay processing (RPLDSBI=N is the default) and the replicated data will be sent to the Event Replicator Server target 26. Its primary key will be blank.

Example 3 -- Using FILES Alone

ADARPL REPLAY FILES=31

Replicated data will be recovered for file 31. The target Event Replicator Server IDs and RPLDSBI settings will be obtained from the FCBs. No primary key will be used for the file.

Example 4 -- Using FILES With SUBSCRIPTION and DESTINATION

ADARPL REPLAY FILES=31
	    RPLTARGETID=23
	    SUBSCRIPTION=’SUB01,SUB02’
	    DESTINATION=’DEST02’

Replicated data will be recovered for file 31 and sent to the Event Replicator Server 23. The RPLDSBI settings will be obtained from the FCBs. No primary key will be used for the file. Event Replicator for Adabas processing will process transactions to destination DEST02 and as defined in subscriptions SUB01 and SUB02.

Sample JCL

The following sample JCL could be used to run ADARPL. In this sample, PLOG records from files 1, 4, and 6 of the Adabas database are replayed.

Note:
The ASSO data set is required in the JCL if the Adabas database is inactive.

//ADARPL   JOB
//*
//*  ADARPL: Sample JCL to invoke ADARPL to process completed
//*          transactions starting at the beginning of the PLOG and
//*          ending at the end of the PLOG for files 1, 4, and 6.
//*          The Reptor target IDs, the replication keys and whether
//*          before images of data storage should occur for update
//*          commands to the file, will be read from the FCBs.
//*
//RPL      EXEC  PGM=ADARUN
//STEPLIB  DD  DISP=SHR,DSN=ADABAS.Vvrs.LOAD  <=== Adabas load lib 
//DDASSOR1 DD  DISP=SHR,DSN=EXAMPLE.DBdbid.ASSOR1 <=== Adabas ASSO
//DDSIIN   DD  DISP=SHR,DSN=EXAMPLE.PLOG101   <=== Sequential PLOGs
//         DD  DISP=SHR,DSN=EXAMPLE.PLOG102   <=== (concatenated)
//         DD  DISP=SHR,DSN=EXAMPLE.PLOG103
//DDDRUCK  DD  SYSOUT=X
//DDPRINT  DD  SYSOUT=X
//SYSUDUMP DD  SYSOUT=X
//DDCARD   DD  *
ADARUN PROG=ADARPL,DBID=dbid,SVC=svc,MODE=MULTI,DEVICE=3390
//DDKARTE  DD  *
ADARPL REPLAY FILES=1,4,6
//