The BACKOUT {DPLOG | MPLOG} function removes all the updates applied between two checkpoints contained on the same Adabas dual or multiple protection log data set, respectively.
The BACKOUT {DPLOG | MPLOG} function is not valid for a cluster database. This is disallowed because a merged PLOG is required in order to perform the BACKOUT.
This document covers the following topics:
The following sequence is recommended for executing the BACKOUT DPLOG or MPLOG function:
Issue the operator or Online System command FEOFPL.
Force EOF on the current protection log data set and switch to a new one. The new protection log data set will contain all information required for BACKOUT DPLOG or MPLOG.
Run the user application.
All protection log data written by the nucleus for this application must fit on a single protection log data set. No protection log switch may occur while the application is running. Here, you should assume that the application program has failed, and must be backed out.
Issue again the operator or Online System command FEOFPL.
Close the protection log data set. The closed data set contains all information required for BACKOUT DPLOG or MPLOG.
Run ADARES PLCOPY.
Copy the content of the protection log data set to a sequential data set. This can be done by running ADARES PLCOPY or by using user exit 2 for DPLOG or user exit 12 for MPLOG.
Run ADARES BACKOUT DPLOG or MPLOG.
This backs out the session to the status of step 1.
An interrupted BACKOUT DPLOG or MPLOG run must be reexecuted from the beginning. If the data on the protection log data set that is to be used is unavailable (the nucleus uses this data protection log again), a BACKOUT from the sequential copy must be done.
In general, the parameters FROMCP/TOCP/FROMBLK/TOBLK should not be specified. Software AG recommends that you back out using the entire contents of one protection log data set.
During backout, the nucleus writes new protection log information to the protection log data set currently available. This is the only data set that can be used by the nucleus. In case of a protection log switch during BACKOUT DPLOG or MPLOG, the nucleus waits until the complete data set has been copied with ADARES PLCOPY, and then resumes the backout run.
By default, all files in the specified input data set are included in the BACKOUT processing. You have the option to identify specific files to be included.
CONTINUE allows autobackout of incomplete transaction changes, if any, during file backout. If specified, all changes made by incomplete transactions are backed out of the database data sets specified by the FILE parameter. If the file list contains coupled or expanded component files and CONTINUE is specified, the usual default checking of the list for all coupled and/or remaining component files does not occur; in this case, IGNORECOUPLE or IGNOREEXP does not have to be specified to stop the checking.
Specifying CONTINUE locks the complete database for exclusive use by the BACKOUT function during file backout.
At the end of BACKOUT processing, ADARES automatically backs out all incomplete logical transactions when BACKOUT is specified for the entire database and continues until the end of the input data set is reached. This also occurs if
the FILE parameter and the CONTINUE parameter are both specified; and
the TOCP parameter is not specified.
You can override this process by specifying the NOAUTOBACKOUT parameter.
DPLOG indicates that a dual protection log data set is to be used as input; MPLOG indicates that a multiple protection log data set is to be used as input.
When FILE is specified, CONTINUE locks the complete database for exclusive use by the BACKOUT function.
It allows autobackout of incomplete transaction changes, if any, during file backout. If specified, all changes made by incomplete transactions are backed out of the database data sets specified by the FILE parameter.
If the file list contains coupled or expanded component files and CONTINUE is specified, the usual default checking of the list for all coupled and/or remaining component files does not occur; in this case, IGNORECOUPLE or IGNOREEXP does not have to be specified to stop the checking.
DUALPLD specifies the device type used for the dual protection log data sets; PLOGDEV specified the device type used for the multiple protection log data sets. The default is the device type specified by the ADARUN DEVICE parameter.
EXCLUDE lists the numbers of the files to be excluded from BACKOUT processing; that is, the files that are not to be backed out. Any protection records that pertain to these files are ignored.
The parameter is optional: if not specified, no files are excluded. A file number may be listed only once.
When the FILE parameter is specified, all files specified in the EXCLUDE parameter must also be specified in the FILE parameter.
The EXCLUDE parameter has no bearing on whether the BACKOUT is performed with or without transaction logic.
The EXCLUDE parameter is provided for use in recovery jobs built by the Adabas Recovery Aid (ADARAI).
Excluded files are listed in the extended CPLIST of the ADAREP report.
FILE specifies the files to be included in the backout process. If all files are to be included, this parameter should be omitted. If the specified file is a component file of an Adabas expanded file, all other component files of the expanded file must also be specified here. If a specified file is coupled to other files, the coupled files must also be specified.
Note:
Before beginning, ADARES locks all specified files for the
duration of BACKOUT execution. If the FILE parameter is omitted, the entire
database will be locked. Other users can have read-only access to the specified
files if the UTYPE=EXU parameter is specified or to the database if the
PARALLELREAD parameter is specified.
FROMBLK is the block number containing the FROMCP checkpoint entry. This block number may be obtained from the database status report. FROMBLK can be specified only if FROMCP is specified.
FROMCP specifies the checkpoint before which the backout process is to begin. The checkpoint ID may be obtained from the database status report. If backout processing is to begin at the end of the log, do not specify the FROMCP parameter.
In a cluster environment, the NUCID parameter or a combination of the FROMNUCID and TONUCID parameters may be required to identify the nuclei associated with the checkpoints referenced in this backout run. If the starting checkpoint block (FROMBLK parameter) and ending checkpoint block (TOBLK parameter) are for the same nucleus, use the NUCID parameter; if the starting checkpoint block (FROMBLK) and ending checkpoint block (TOCP) are for different nuclei, use the FROMNUCID and TONUCID parameters.
The FROMNUCID parameter specifies the nucleus ID for the starting nucleus. If you specify the FROMNUCID parameter, a corresponding TONUCID parameter is expected.
IGNORECOUPLE (or CONTINUE) stops the BACKOUT function from checking the FILE list for complete coupled file pairs. If neither CONTINUE nor IGNORECOUPLE are specified and the FILE list specifies a coupled file without specifying its mate, ADARES terminates and issues an error message.
If the FILE list includes any Adabas expanded component files, ADARES BACKOUT normally checks to ensure that all additional component files related to the listed component files are also in the list; if not, ADARES ends the BACKOUT operation and issues an error message. Specifying IGNOREEXP (or CONTINUE) stops the checking for related component files.
MTR=YES activates the multithreaded backout feature; MTR=NO disables it.
When the multithreaded backout feature is active, multiple buffers containing PLOG information are sent to the Adabas nucleus in parallel to improve performance. When the feature is not active, only one buffer is sent to Adabas at a time.
If the nucleus ADARUN parameter MODE=SINGLE, MTR is automatically set to NO. Multiple threads are not available to Adabas running in single user mode.
If the FILE parameter is not specified, or is specified with CONTINUE, the default value for MTR is YES. In these cases, multithreaded backout has exclusive control of the whole database and is generally effective.
Otherwise, the default value is NO. If it only has exclusive control of some files, as is the case when FILE is specified without CONTINUE, multithreaded backout can run in parallel with normal applications accessing different files and has the potential to negatively impact the performance of production applications.
If several consecutive BACKOUT runs are necessary in order to process multiple protection logs resulting from a single Adabas session, an automatic backout should be performed only for the last input log. The NOAUTOBACKOUT parameter should therefore be specified for each BACKOUT run except the run in which the last input log is used.
Notes:
When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.
Note:
When NOUSERABEND is specified, we recommend that it be specified
as the first parameter of the utility function (before all other parameters).
This is necessary to ensure that its parameter error processing occurs
properly.
When MTR=YES, the NPCALLS parameter may be specified to limit the number of parallel calls sent to the Adabas nucleus.
If the FILE parameter is not specified, or is specified with CONTINUE, the default value for NPCALLS is the nucleus ADARUN parameter NT+1 or NC, whichever is smaller.
If the FILE parameter is specified without CONTINUE, the default value is the nucleus ADARUN parameter NT+1 or NC/2, whichever is smaller.
NPCALLS is primarily used to reduce the number of parallel calls allowed by the default value. Fewer parallel calls mean a smaller nucleus workload produced by ADARES. This is especially useful for increasing the resources available to application programs running in parallel with BACKOUT DPLOG FILE.
In a cluster environment, the NUCID parameter or a combination of the FROMNUCID and TONUCID parameters may be required to identify the nuclei associated with the checkpoints referenced in this backout run. If the starting checkpoint block (FROMBLK parameter) and ending checkpoint block (TOBLK parameter) are for the same nucleus, use the NUCID parameter; if the starting checkpoint block (FROMBLK) and ending checkpoint block (TOCP) are for different nuclei, use the FROMNUCID and TONUCID parameters.
The PARALLELREAD parameter provides for concurrent read-only access to the files being processed by ADARES BACKOUT DPLOG both for database-wide and file-oriented functions:
for file-oriented functions, specifying PARALLELREAD causes ADARES to issue an OPEN call with "EXU=file-list" in the record buffer. This allows read-only access to the files for other users while ADARES is active.
when FILE is not specified or when CONTINUE is specified, the PARALLELREAD parameter is effective for a database-wide DPLOG backout. The parameter makes it possible for read-only users to access the database at the same time the database DPLOG is being backed out.
Update commands are rejected.
If parallel access users read records that were updated in the database DPLOG being backed out, they may see record images that are logically wrong in the sense of the application, or response codes such as 113 (ADARSP113) that indicate inconsistencies.
Notes:
When performing a backout operation using a protection log from a database other than that specified by the ADARUN statement's DBID parameter, PLOGDBID specifies the database ID of the alternate protection log. The default is the database ID from the ADARUN-specified database.
The RPLDATA parameter allows you to specify whether or not the nucleus should replicate the protection log data sent to it. Valid values are "YES" and "NO"; the default is "NO".
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.
TOBLK specifies the block number containing the TOCP checkpoint entry. TOBLK can only be specified if TOCP is specified.
TOCP specifies the checkpoint at which the backout process is to stop. Backout processing continues up to the specified checkpoint. If backout processing is to continue until the beginning of the log, do not specify TOCP or NOAUTOBACKOUT.
In a cluster environment, the NUCID parameter or a combination of the FROMNUCID and TONUCID parameters may be required to identify the nuclei associated with the checkpoints referenced in this backout run. If the starting checkpoint block (FROMBLK parameter) and ending checkpoint block (TOBLK parameter) are for the same nucleus, use the NUCID parameter; if the starting checkpoint block (FROMBLK) and ending checkpoint block (TOCP) are for different nuclei, use the FROMNUCID and TONUCID parameters.
The TONUCID parameter specifies the nucleus ID for the ending nucleus. Only specify a TONUCID parameter if a corresponding FROMNUCID parameter is also specified.
ADADBS OPERCOM FEOFPL
User application on files 20 and 21 fails
ADADBS OPERCOM FEOFPL
ADARES BACKOUT DPLOG,FILE=20,21
This example assumes that the PLCOPY function is performed with user exit 2. Whenever a protection log switch occurs, this user exit submits a job to copy the content of the dual protection log to a sequential data set.
Switch to a new PLOG.
Run the user session creating PLOG data on the new PLOG data set.
Close the PLOG data set. User exit 2 submits a job which copies the contents of the PLOG data set just closed.
Perform a BACKOUT from that PLOG for the files 20 and 21 up to the beginning of the PLOG.
