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 dataset. 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 datasets. ADARES COPY may be executed any number of times for any given input dataset.
The COPY function also copies save tapes created by the ADASAV utility. Only one save dataset 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 dataset that could not be successfully built by PLCOPY executions because an error occurred. For example, the DSIM dataset might have been too small to hold all online save information extracted from the protection log. Building a complete DSIM dataset is a prerequisite for using the online save dataset in subsequent merge operations.
additionally extracts all protection log information relating to an online save operation and writes them to the DSIM dataset. This dataset 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.
When copying the protection log for the current nucleus session, the NONUC parameter must be specified.
If the building of the DSIM dataset is the only purpose of the COPY operation, the sequential output may be directed to a dummy dataset so that no data is actually written. The online save information will nevertheless be extracted from the protection log and written to the DSIM dataset.
For ADARES, the DSIM dataset must be specified for shared-update use.
Procedures for rebuilding a DSIM dataset are outlined in the section Rebuilding the DSIM Dataset.
The size of the DSIM dataset. 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 dataset 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 dataset. 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.
In the event that the Adabas nucleus is unable to perform an autorestart, the NONUC parameter may be used to cause the nucleus response code to be ignored. ADARES will then attempt to physically copy the input tape as far as possible.
This parameter should only be specified after all other corrective actions have failed; however, NONUC must be specified when copying the PLOG for the current nucleus session. The output dataset will have a valid EOF mark, even if the input dataset does not.
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 datasets are to be opened by ADARES, even if no data is actually to be copied. Without OPENOUT, the sequential output datasets 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 datasets 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 ADARES NONUC
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 dataset. The DSIM dataset 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 dataset. The dual or multiple protection log dataset that has the earlier timestamp is copied. Once the PLCOPY function is successfully completed, the copied dataset 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) dataset. This process is called "building the DSIM dataset". The dataset 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 dataset 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 dataset using the COPY function.
Procedures for rebuilding a DSIM dataset are outlined in the section Rebuilding the DSIM Dataset.
The size of the DSIM dataset. 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 dataset. 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 datasets; PLOGDEV specifies the device type used for multiple protection log datasets. This parameter is required if the device type used for the dual or multiple protection log datasets 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 datasets are to be opened by ADARES, even if no data is actually to be copied. Without OPENOUT, the sequential output datasets 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 datasets 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 dataset. The DSIM dataset 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 dataset with all changes to the database that took place during the online save. The result is a quasi-offline save dataset, 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 dataset. This process is called "building the DSIM dataset". 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 dataset include the following:
The DSIM dataset 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 dataset 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 dataset;
The DSIM dataset is accidentally used (altered) by another utility.
If such an error condition occurs, the correct DSIM dataset 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 dataset if the current one is too small.
Identify the copied, sequential PLOG datasets 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 datasets as input, execute the ADARES COPY function to rebuild the DSIM dataset. If sequential PLOG output is not needed, specify a dummy output dataset. 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 dataset can be merged with the online save dataset and, optionally, other full or delta save datasets.
