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:
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:
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.
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.
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.
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.
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.
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.
The syntax and parameters vary, depending on whether you want to initiate ADARPL using a token generated by the Adabas Event Replicator Subsystem.
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]]
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.
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: |
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: |
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: |
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:
|
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): This parameter is only allowed if FILES parameter is specified. Note: |
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:
This parameter is only allowed if FILES parameter is specified. Note: |
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:
This parameter can be specified only if the SUBSCRIPTION and DESTINATION parameters are not specified. Note: |
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: |
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. |
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.
This section provides three examples of ADARPL parameter usage.
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.
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.
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.
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.
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 //