Version 8.2.4
 —  Adabas Utility Functions for Delta Save  —

ADASAV MERGE

This document covers the following topics:


Consolidating Delta Saves or Updating Full Saves

The ADASAV MERGE function takes as input zero or one full save data set and zero to eight delta save data sets:

DD/DEL1...DD/DELn up to eight consecutive delta save tapes covering a contiguous time span with no gaps. Do not omit a delta save tape.
DD/FULL the optional full save input tape.

The input data sets may originate from SAVE database, SAVE DELTA, or MERGE functions. They must cover a continuous sequence of full and delta save operations. Overlapping delta save numbers in data sets used as input to the merge are allowed.

ADASAV MERGE combines the input data sets into a single data set: either a consolidated delta save tape or an updated full save tape:

DD/SAVE1 the new full or delta save output tape.

The output data set may subsequently be used as input for MERGE, RESTORE, or RESTORE DELTA functions.

If the DRIVES parameter is specified, ADASAV MERGE cuts the full save output into as many pieces as specified by DRIVES:

DD/SAVE1...DD/SAVEn up to eight consecutive partial save tapes comprising together the new full save output tape.

The output data sets created can be used as input to a RESTORE function with the same value of DRIVES.

If only delta save input data sets are specified, the MERGE function creates a new delta save data set that contains every database block from each input save data set. If a block is present on more than one input save data set, its latest occurrence is taken. The result is a "consolidated" delta save data set that contains all changes since the last full save or since the last delta save not included in the MERGE function.

If a full save data set is specified as input, the MERGE function creates a new full save data set that contains the latest image of every used block of the database. This full save data set is equivalent to the database at the time of the last SAVE DELTA execution.

Top of page

Merging Online Saves and DSIM Data Sets

The "online" variation of the MERGE function takes as input a full or delta save data set that originates from an online save operation and the accompanying DSIM data set that was specified for the online save operation:

DD/DSIMR1 interim data set from an online SAVE operation.

An online full or delta save data set with its corresponding DSIM data set can also be specified in a merge with "offline" save data sets. The output save data set from the "online" merge operation is always like an "offline" save data set and may be supplied together with another online save data set for a subsequent MERGE operation.

The DSIM data set is automatically built while ADARES PLCOPY copies the dual or multiple protection logs (PLOGs). Building the DSIM data set is completed when the PLCOPY function encounters the online save operation's SYN2 checkpoint on the PLOG.

If the MERGE function is performed directly after the online save operation, the DSIM data set will normally not be completely built when the MERGE function starts. The DSIM data set will not be ready for merge before the next PLCOPY operation has been performed. The DSIMWAIT parameter tells the MERGE function how long to wait for the DSIM data set to become ready for merge.

Upon completion of the MERGE function, the DSIM data set is reset for use in another online save/merge cycle.

Top of page

Unloading DSIM Data Sets

The "unload" variation of the MERGE function transfers the contents of the DSIM data set

DD/DSIMR1 interim data set from the last online SAVE operation.

-to a sequential delta save data set

DD/SAVE1 delta save data set.

-that can be used in MERGE or RESTORE DELTA operations later on as needed.

The "unload" frees the DSIM data set for the next online SAVE operation.

Unlike the "merge" of the DSIM data set, the "unload" does not process the associated online full or delta save data set again immediately after it is created. Instead, more than one online save data set can be processed later on in a single MERGE or RESTORE DELTA operation by sequencing for each the delta save data set created from its associated DSIM data set.

The DSIM data set is unloaded by running ADASAV MERGE with only the DSIM data set as input. The PATTERN parameter must be omitted or blank, and the DRIVES parameter must not be set to a value greater than one. The DSIMWAIT parameter functions normally.

Whereas the DSIM data set is direct access and contains changed blocks from the database in no particular order, the output data set is sequential and contains the blocks in ascending RABN sequence without duplicates, like any delta save data set.

An unloaded DSIM data set is identified by a flag in the save data set header. The header specifies

The fields mentioned in the header record are filled from the corresponding fields in the DSIM header block.

If the DSIM data set was (re)built by an ADARES COPY execution, the DSID is not known and will be zero. The associated online save is still correctly identified by the positions of its SYN1 and SYN2 checkpoints on the PLOG.

When a DSIM data set is unloaded, the MERGE function still generates a SYNP-0D checkpoint but with an indication that the created save data set is an unloaded DSIM data set.

Top of page

Using Unloaded DSIM Data Sets as "Online" MERGE Input

When an unloaded DSIM data set is supplied as input for a MERGE operation, it must be specified

These rules for specifying unloaded DSIM data sets ensure the correct output: each block is taken from the last input in sequence that contains a block image with the same RABN.

The MERGE function checks whether the online save fits the contents of the DSIM data set. If so, the online save is associated with the DSIM data set. If not, the next input delta save in logical sequence must be a matching unloaded DSIM data set.

Top of page

Concatenated Data Sets in MERGE Input

The full save input to the ADASAV MERGE function must be supplied as a single entity. Full saves that are spread over several data sets (by means of the DRIVES parameter in ADASAV), must be concatenated as follows:

For a MERGE operation, a delta save data set may not be concatenated to another full or delta save data set. If the MERGE operation detects a concatenated data set at the end of any other data set in the logical sequence, it terminates with an error message.

Note:
In cases where the MERGE function can be completed without reading all input save data sets to their end, wrongly concatenated input save data sets may still go undetected and be ignored.

See the JCL examples for the ADASAV MERGE function in section JCL/JCS Requirements and Examples. for more information on data set concatenation on BS2000 and VSE/ESA systems, see the Adabas Utilities documentation.

Top of page

Syntax

graphics/adasavm.png

Top of page

Optional Parameters

DRIVES: Number of Output Data Sets

DRIVES can only be specified if the output save data set is a full save.

The DRIVES parameter specifies the number of output data sets to be created, all of which together build the full save output. The MERGE function cuts the output full save into as many pieces as specified by DRIVES.

Note:
The full save input must always be specified using a single DD/link name (DD/FULL). Concatenation can be used, if necessary. See Concatenated Data Sets in MERGE Input.

The output data sets created can be used as input to a RESTORE function with the same value of DRIVES.

DSIMDEV: DSIM Device Type

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).

DSIMWAIT: DSIM Data Set Wait Time in Seconds

The DSIMWAIT parameter specifies how long the MERGE function should wait for the DSIM data set to become ready for merge.

It can be used if a merge step is to be executed directly after an online save operation but must wait for the ADARES PLCOPY function to copy the nucleus' dual or multiple protection log.

The maximum time to wait is specified in seconds. If the DSIM data set does not become ready for merge during this interval, and one of the input save data sets is an online save data set, the MERGE function fails.

If DSIMWAIT is not specified, the MERGE function will not wait for the DSIM data set to become ready for merge, but instead will begin operation immediately or fail if the DSIM data set is not ready for merge (the default).

NOUSERABEND: Termination without ABEND

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.

PATTERN: Merge Input Pattern

PATTERN is an optional parameter that provides a cross-check between the intended merge input and the actual data sets specified by the job control. PATTERN specifies the count and type of input data sets to the merge operation as single letters "F" (full save tape) or "D" (delta save tape). Only one "F" can be specified in the pattern field, but up to eight "D"s can be entered-one for each existing delta save tape to be merged (additional delta save tapes can be merged in subsequent merge operations with the result of this merge operation).

The pattern starts with an "F" if a full save input is specified, and continues (or starts) with a "D" for every delta save input. For example, PATTERN=FDD specifies that the input comprises one full save data set and two delta save data sets. No special indicator is given for a save data set being online. The pattern string must exactly match the input save data sets specified in the job control.

PERDRIVE: Disk Drives Per Tape Drive

PERDRIVE specifies the number of disk drives to be assigned to a single output tape drive. For example, if the database is contained on seven disk drives and three tape drives are available for MERGE processing, PERDRIVE=3,2,2 would cause the first three disk drives to be written to tape drive 1, the next two disk drives to be written to tape drive 2, and the next two disk drives to be written to tape drive 3. The drive sequence corresponds to the DD/SAVEn or DD/DUALn job control specifications, as described in the section JCL/JCS Requirements and Examples.

The total number of drives specified by PERDRIVE must equal the sum of all Associator (DD/ASSORn) and Data Storage (DD/DATARn) disks; if both Associator and Data Storage are on a single disk, this counts as two separate disks. If the DRIVES parameter is used and the PERDRIVE parameter is omitted, ADASAV determines the most efficient utilization of the tape drives.

TEST: Test Syntax

The TEST parameter tests the operation syntax without actually performing the merge operation. Note that the validity of values cannot be tested; only the syntax of the specified parameters can be tested.

TWOCOPIES: Create Two Copies of Output

TWOCOPIES creates two physical copies of the ADASAV output.

Top of page

Examples

Example 1:


  ADASAV MERGE

  DSIMDEV=8381,DSIMWAIT=300,PATTERN=DD

Two delta save tapes, one created during an online delta save, are to be merged into a single delta save tape. The merge operation will wait up to five minutes (300 seconds) for the DSIM data set to become available. The DSIM data set's device type is 8381.

Example 2:


  ADASAV MERGE PATTERN=FD

  ADASAV          DRIVES=4

  ADASAV          TWOCOPIES

One full save and one delta save data set are to be merged. The full save output is to be distributed over four data sets, making them suitable for a restore using four drives. Two copies of each output data set are to be made.

Example 3:


  ADASAV MERGE PATTERN=F

Only one (online) full save and its corresponding DSIM data set are to be merged. The output is equivalent to an offline full save taken at the end of the online save operation.

Example 4:


  ADASAV MERGE PATTERN='FDDDDDDDD'

A full save and eight delta saves (the maximum number allowed) are to be merged.

Top of page