This document describes the additional functionality and new parameters of ADARES that are introduced by the Delta Save Facility.
The ADARES COPY and PLCOPY functions include additional operations and parameters for Delta Save operation. These additional Delta Save operations of ADARES are available only when the ADARUN parameter DSF=YES is specified in the DDCARD/CARD input.
This document covers the following topics:
The COPY function copies one sequential protection log to another sequential protection log data set. It must be used to copy the sequential protection log of an Adabas nucleus session that has terminated abnormally; only then can the protection log be used for other purposes. Protection logs from several consecutive Adabas sessions may be copied in a single ADARES COPY execution.
The COPY function may be used to copy a sequential protection log from disk to tape before it can be used as input to the ADARES BACKOUT function. ADARES COPY may be used even if subsequent Adabas sessions have created other protection log data sets. ADARES COPY may be executed any number of times for any given input data set.
The COPY function also copies save tapes created by the ADASAV utility. Only one save data set can be copied in a single COPY execution.
When the Delta Save Facility is installed and ADARUN DSF=YES, the COPY function
can also be used to rebuild a DSIM data set that could not be successfully built by PLCOPY executions because an error occurred. For example, the DSIM data set might have been too small to hold all online save information extracted from the protection log. Building a complete DSIM data set is a prerequisite for using the online save data set in subsequent merge operations.
additionally extracts all protection log information relating to an online save operation and writes them to the DSIM data set. This data set can then be supplied to an ADASAV MERGE or RESTORE DELTA function.
The protection log to be processed must cover a single, complete online save operation. The protection log must contain both SYN1 and SYN2 checkpoints. If it covers more than one online save, only the protection log information of the last one is extracted. Any other online save operation may be designated by specifying the block number of the save operation's start checkpoint in the SYN1 parameter. If more than one PLOG was processed during the online save operation, all these PLOGs need to be concatenated.
If the building of the DSIM data set is the only purpose of the COPY operation, the sequential output may be directed to a dummy data set so that no data is actually written. The online save information will nevertheless be extracted from the protection log and written to the DSIM data set.
For ADARES, the DSIM data set must be specified for shared-update use.
Procedures for rebuilding a DSIM data set are outlined in the section Rebuilding the DSIM Data Set.
The size of the DSIM data set. The size can be specified in cylinders, or in blocks (by appending "B" to the number). This parameter is mandatory if ADARUN parameter DSF=YES is specified. Otherwise, do not specify DSIMSIZE.
The Adabas protection log number of the data set to be copied. This number may be obtained from the database status report produced by the ADAREP utility. The output of the COPY function will be assigned the same log number.
If ADARUN parameter DSF=YES is specified, the PLOGNUM parameter also identifies the protection log number of the SYN1 checkpoint where extraction of online save information is to start.
FROMPLOG specifies the session number at which the ADARES COPY function is to start. ADARES searches the input (DDSIIN/SIIN) file for the correct starting session.
The DSIMDEV parameter specifies the device type of the DSIM data set. This parameter is required only if the DSIM device type is different from that specified by the ADARUN DEVICE parameter (which is the default). It is allowed only if the ADARUN parameter DSF=YES is specified.
The NONUC parameter in the ADARES COPY utility function is deactivated effective with Adabas 8.2. You can still specify the parameter, but it is ignored.
When an error is encountered while the function is running, the utility 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.
The OPENOUT parameter indicates that the DD/SIAUS1/2 output data sets are to be opened by ADARES, even if no data is actually to be copied. Without OPENOUT, the sequential output data sets are not opened if ADARES detects an end-of-file condition while attempting to read the first input record; this may cause problems in some operating system environments. With OPENOUT, the output data sets are opened before the first input record is read.
The block number of the SYN1 checkpoint on the protection log (PLOG) to be copied where extraction of online save information is to start. This is the start checkpoint of the online save operation. The SYN1 block number may be obtained from the database status report produced by the ADAREP utility.
If the SYN1 parameter is omitted, extraction of online save information starts at the first SYN1 checkpoint encountered. If the PLOG covers several online save operations, extracting the online save information is started anew at every SYN1 checkpoint that occurs. Therefore, if the SYN1 parameter is not specified, the online save information of the last online save operation recorded in the PLOG is extracted.
The SYN1 parameter is only allowed if ADARUN parameter DSF=YES is specified, and can be specified only with the PLOGNUM parameter.
The TEST parameter tests the operation syntax without actually performing the operation. Note that the validity of values and variables cannot be tested; only the syntax of the specified parameters can be tested.
TOPLOG specifies the last session to be processed by the specified ADARES function. If ADARES finds a session on the PLOG input (DDSIIN/SIIN) file that is greater than the specified TOPLOG session, that session is excluded from ADARES processing. If TOPLOG is not specified, the FROMPLOG session becomes the default.
TWOCOPIES causes two copies of the output to be created.
The UTICPLIST parameter causes ADARES to select and print all utility checkpoints found on the data protection log during the COPY function.
ADARES COPY PLOGNUM=1310 ADARES DSIMSIZE=10 ADARES DSIMDEV=8381
A sequential protection log of the current active session is to be copied. The session number is 1310. Any protection log information relating to an online save operation is to be extracted and written to the DSIM data set. The DSIM data set size is 10 cylinders and the device type is 8381.
The PLCOPY function copies the dual or multiple protection log to a sequential protection log data set. The dual or multiple protection log data set that has the earlier timestamp is copied. Once the PLCOPY function is successfully completed, the copied data set is reset to an empty status. This function can therefore be used only once for any given portion of the protection log of an entire Adabas nucleus session. The PLCOPY function is only applicable if the Adabas nucleus is run with dual or multiple protection logging.
When the Delta Save Facility is installed and ADARUN DSF=YES, the PLCOPY function also extracts all protection log information relating to an online save operation and writes it to the Delta Save images (DSIM) data set. This process is called "building the DSIM data set". The data set can then be supplied to an ADASAV MERGE or RESTORE DELTA function.
Depending on the number of protection log switches during an online save operation, several PLCOPY executions may be necessary to extract all online save information. The DSIM data set remains incomplete between two such PLCOPY operations. It is marked ready for merge only after the SYN2 checkpoint indicating the end of an online save operation is found on the protection log.
If the "build" process is interrupted due to an error condition, subsequent merging and/or restore operations cannot take place; this renders the online save tape almost useless. In this case it is necessary to "rebuild" the DSIM data set using the COPY function.
Procedures for rebuilding a DSIM data set are outlined in the section Rebuilding the DSIM Data Set.
The size of the DSIM data set. The size can be specified in cylinders, or in blocks (by appending "B" to the number). This parameter is mandatory if ADARUN parameter DSF=YES is specified. Otherwise, do not specify DSIMSIZE.
The DSIMDEV parameter specifies the device type of the DSIM data set. This parameter is required only if the DSIM device type is different from that specified by the ADARUN DEVICE parameter (which is the default). It is allowed only if ADARUN parameter DSF=YES is specified.
DUALPLD specifies the device type used for dual protection log data sets; PLOGDEV specifies the device type used for multiple protection log data sets. This parameter is required if the device type used for the dual or multiple protection log data sets is different from that specified with the ADARUN DEVICE parameter.
When an error is encountered while the function is running, the utility 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.
The OPENOUT parameter indicates that the DD/SIAUS1/2 output data sets are to be opened by ADARES, even if no data is actually to be copied. Without OPENOUT, the sequential output data sets are not opened if ADARES detects an end-of-file condition while attempting to read the first input record; this may cause problems in some operating system environments. With OPENOUT, the output data sets are opened before the first input record is read.
The TEST parameter tests the operation syntax without actually performing the operation. Note that the validity of values cannot be tested; only the syntax of the specified parameters can be tested.
TWOCOPIES causes two copies of the output to be created. If TWOCOPIES is not specified, the default is one copy.
The UTICPLIST parameter causes ADARES to select and print all utility checkpoints found on the data protection log during the PLCOPY function.
ADARES PLCOPY ADARES DSIMSIZE=10 ADARES DSIMDEV=8381
The dual or multiple protection log is to be copied. Any protection log information relating to an online save operation is to be extracted and written to the DSIM data set. The DSIM data set size is 10 cylinders and the device type is 8381.
Using the Delta Save Facility, you can perform full or delta save operations online and automatically combine the resulting save data set with all changes to the database that took place during the online save. The result is a quasi-offline save data set, which is equivalent to an offline save taken at the end of the online save operation.
Accumulating database changes during the online save operation depends on the ability of the ADARES PLCOPY function to extract images of changed database blocks from the protection log (PLOG) and write them to the DSIM data set. This process is called "building the DSIM data set". If this process is interrupted due to an error condition, subsequent merging and/or restore operations cannot take place; this renders the online save tape almost useless.
Possible error conditions on the DSIM data set include the following:
The DSIM data set is full: that is, it is too small to hold all images of all database blocks changed during the online save operation;
The status of the DSIM data set is incorrect; the sequence of operations being performed does not conform to the save/copy/merge cycle;
An I/O error occurs on the DSIM data set;
The DSIM data set is accidentally used (altered) by another utility.
If such an error condition occurs, the correct DSIM data set can be
"rebuilt" using the ADARES COPY function. This is called "recover mode" and
requires the following steps:
Determine and correct the cause of the error; for example, allocate and format a new, larger DSIM data set if the current one is too small.
Identify the copied, sequential PLOG data sets that contain all of the online save operation in question; the checkpoint list from the ADAREP database report may be used to determine the save operation's SYN1 checkpoint block number (the SYN1 checkpoint marks the beginning of an online full or delta save operation).
Using the chosen sequential PLOG data sets as input, execute the ADARES COPY function to rebuild the DSIM data set. If sequential PLOG output is not needed, specify a dummy output data set. If the supplied PLOG input covers multiple online saves, identify the correct one by specifying the SYN1-parameter with the checkpoint block number determined in step 2.
After the ADARES COPY function completes successfully, the DSIM data set can be merged with the online save data set and, optionally, other full or delta save data sets.
