The BACKOUT function removes all the updates applied between two specified checkpoints. Both checkpoints must be contained on the sequential protection log input data set.
The BACKOUT function requires that the read backward feature is supported by the tape drive to be used for sequential input.
Note:
An interrupted BACKOUT run must be reexecuted from the
beginning.
You can specify either the log number (PLOGNUM) or the session number (FROMPLOG) of the protection log as a starting point for BACKOUT processing. If you specify a session number, you can also specify a range of sessions to be processed using the TOPLOG parameter.
By default, ADARES processes the database specified by the ADARUN DBID parameter. If BACKOUT processing is required against a different database, use the PLOGDBID parameter to specify the database.
By default, BACKOUT processing continues until the end of the input data set is reached. You can limit the extent of BACKOUT processing using the TOCP parameter.
By default, all files in the specified input data set are included in the BACKOUT processing. You have to option to identify specific files to be included.
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.
This document covers the following topics:
PLOGNUM specifies the log number of the sequential protection log to be used as input for BACKOUT processing. The log number may be obtained from the database status report.
FROMPLOG specifies the session number at which BACKOUT processing is to start. ADARES searches the sequential PLOG input (DD/SIIN) file for the correct starting session. To define the starting point more precisely, specify the FROMCP and FROMBLK parameters.
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.
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.
If all files are to be included in the BACKOUT processing, this parameter should not be specified.
If the specified file is a component file of an Adabas expanded file, then all other component files for the expanded file must also be specified. If a specified file is coupled to other files, these files must also be specified.
FROMBLK specifies the block number containing the FROMCP checkpoint entry. This block number, which may be obtained from the database status report, refers to either PLOGNUM or FROMPLOG. FROMBLK can only be specified if FROMCP is specified.
FROMCP specifies the checkpoint before which the backout process is to begin. The checkpoint identification (name), which may be obtained from the database status report, refers to either PLOGNUM or FROMPLOG.
If backout processing is to begin at the end of the log, this parameter should be omitted.
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 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 regenerate feature; MTR=NO disables it.
When the multithreaded regenerate 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 regenerate 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 regenerate 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 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 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 session backout. The parameter makes it possible for read-only users to access the database at the same time the database session is being backed out.
Update commands are rejected.
If parallel access users read records that were updated in the database session 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. This block number, which can be obtained from the database status report, refers to either PLOGNUM or FROMPLOG, or to TOPLOG, if specified. TOBLK can only be specified if TOCP is specified.
TOCP specifies the checkpoint at which the backout process is to be terminated. If backout processing is to continue until the beginning of the log, do not specify TOCP. The checkpoint identification (name), which can be obtained from the database status report, refers to either TOPLOG, if specified, or to PLOGNUM or FROMPLOG.
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.
TOPLOG specifies the last session to be processed by the specified ADARES function. If ADARES finds a session on the PLOG input (DD/SIIN) file whose session number is outside the inclusive range defined by FROMPLOG/TOPLOG, that session is excluded from ADARES processing. TOPLOG can only be specified if FROMPLOG is also specified. If TOPLOG is not specified, the FROMPLOG session becomes the default. To define the ending point more precisely, specify the TOCP and TOBLK parameters.
ADARES BACKOUT PLOGNUM=3
All files are to be included in backout processing. The protection log number is 3. Backout processing is to begin at the end of the log and is to end at the beginning of the log. At the end of the backout processing, an automatic backout (but moving forward) of incomplete transactions occurs.
ADARES BACKOUT FILE=4,7,PLOGNUM=11,FROMCP=CH18,FROMBLK=1864, ADARES TOCP=CH01,TOBLK=1
The backout is to be limited to files 4 and 7. All updates applied to files 4 and 7 between the taking of checkpoints CH01 and CH18 are to be removed. CH01 is located in block 1 of data protection log 11. Checkpoint CH18 is located in block 1864 of data protection log 11. No automatic backout of incomplete transactions occurs.
