The ADASAV SAVE FILES function saves the contents of one or more files to a sequential data set. It saves all blocks that are in use in the file(s).
The SAVE FILES function may be executed with the Adabas nucleus active or inactive. If executed while the Adabas nucleus is
active, the RESTONL function must be used to later restore the file(s).
inactive, the RESTORE function must be used to later restore the file(s).
In both cases, it is possible to restore just one or a few files from all files saved on the SAVE data set.
If the Adabas nucleus is inactive, it cannot be started while the SAVE function is executing, and no utility (such as ADALOD, for example) that makes changes to the file(s) being saved can be run during the save. The SAVE function cannot be executed offline if a nucleus session autorestart is pending, or if another offline utility (such as ADALOD or ADASAV) is currently running on the file(s) to be saved.
If the Adabas nucleus is active during the execution of the save operation, users have full access to the file(s) being saved. They can perform read, find, update, insert, and delete commands. However, utilities that make changes to the files to be saved (such as ADALOD, ADAINV, or ADADBS REFRESH, for example) must not be running and cannot be started while the save function is executing. An online save operation is also not possible if the nucleus is running without protection logging.
In an online save operation, the file(s) to be saved may be changed while ADASAV is performing the save operation. Therefore, the Adabas nucleus writes all changed blocks of the file(s) being saved to the protection log as well. This protection log must be supplied for a subsequent restore operation (that is, a RESTONL function).
The start of an online file save is marked by a SYN4 checkpoint. At the end of the online save, the nucleus synchronizes all currently active transactions. This means that Adabas performs no more update commands for users at ET status but allows the other active users to continue until they reach ET status. This status is then marked by a SYN5 checkpoint. The SYN5 checkpoint thus marks a consistent state of the database where no transactions are in progress. This state is reproduced when files are restored from the SAVE data set later on.
The maximum time required for the transaction synchronization can be limited by the TTSYN parameter.
If the parameter UTYPE=EXU is specified and the Adabas nucleus is active, the save operation is performed like an offline save. ADASAV locks all files to be saved with an EXU-open against concurrent updates. The RESTORE function (rather than RESTONL) must be used for a later restore of the file(s).
Several offline file save operations, or file saves with UTYPE=EXU can be performed on different files in parallel. Only one online file save operation can be active at a time.
Files from databases residing on several disk volumes are saved to several SAVE data sets in parallel when the DRIVES parameter is specified. This mode of operation may significantly reduce the duration of the save. The resulting SAVE data sets, when concatenated in the order of ascending drive number, are equivalent to a single SAVE data set produced without the DRIVES parameter.
The SAVE FILES function does not save files that are in invert, load, refresh, reorder, or restore status. In fact, it removes such files from the file list, prints message ADAU15, and performs the save operation for the remaining files. At the end, ADASAV terminates with return code 4.
This document covers the following topics:
The FILES file list specifies one or more Adabas file numbers or a range
of file numbers to be restored. Ranges of file numbers should be specified
using a dash (-) in the format:
fnfirst-fnlast.
If a specified file is coupled to another file or is a component of an expanded file, and the ADASAV SAVE FILES function is executed
with an active nucleus, ADASAV only accepts a SAVE FILES operation if all component files of an expanded file and all files coupled to the file are specified in the FILES file list.
with an inactive nucleus, the SAVE FILES operation is accepted if any one component file of an expanded file or one of several coupled files is specified. ADASAV then extends the file list automatically.
The BUFNO value allocates fixed buffers for the SAVE operation. A value of 2 or 3 usually provides optimum performance; up to 255 is possible. A value greater than 5, however, provides little advantage and allocates a lot of space. The default is 1 (one buffer per drive).
DRIVES is the number of tape drives to be used for parallel SAVE operation. A maximum of 8 drives can be specified. The default is 1.
INCREMENTAL saves only those files in the FILES list that have been changed since the last ADASAV SAVE operation. If INCREMENTAL is not specified, the SAVE function saves all files in the FILES list.
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.
PASSWORD specifies one password or a list of passwords if one or more files in the FILES file list are password-protected. For more than one password-protected file, the correct passwords must be specified as positional values corresponding to the protected file numbers' positions in the FILES list. Refer to the examples at the end of this section for more information about the PASSWORD parameter. When saving password-protected files, the Adabas nucleus must be active.
PERDRIVE specifies the number of disk drives to be assigned to a single tape drive. For example, if the database is contained on seven disk drives, and three tape drives are available for SAVE 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 DDSAVEn/DDDUALn or SAVEn/DUALn job control specifications, as described at the end of this document.
The total number of drives specified by PERDRIVE must equal the sum of all Associator (ASSO) and DATA disks; if both ASSO and DATA are one a single disk, this counts as two separate disks. If the DRIVES parameter is used and the PERDRIVE parameter is omitted, ADASAV will determine the most efficient utilization of the tape drives.
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.
TTSYN allows the user to decrease the ADARUN TT (maximum transaction time) of the nucleus during the synchronized checkpoint processing of the current ADASAV operation. The value specified is the approximate time in seconds (TT � 1.05 seconds), and must be less than the current ADARUN TT value. If TTSYN is not specified or if TTSYN is greater than the TT value of the nucleus, the nucleus' TT value becomes the default.
Note:
TTSYN is ineffective if UTYPE=EXU.
If the Adabas nucleus is active while ADASAV SAVE is running, a synchronized SYN5 checkpoint is taken at the end of the SAVE operation. This ensures that there is a point in time where all users are at ET status. If a user is not at ET status, no new transactions can be started for other users; they must wait until the SYN5 checkpoint can be taken.
The ADARUN TT value controls the maximum elapsed time permitted for a logical transaction. This is the maximum wait time until the SYN5 checkpoint can be processed. The ADASAV SAVE TTSYN parameter allows the user to decrease the TT value only during the synchronized checkpoint processing. The original TT value becomes effective again when ADASAV ends the SAVE operation.
TWOCOPIES creates two physical copies of the ADASAV output.
ADASAV issues an Adabas open command with a record buffer "EXU=file-list". This enables a file to be saved where an Adabas nucleus is active with no protection log. No updates to the files being saved are permitted while the SAVE function is operating. The corresponding RESTORE file operation does not require a protection log.
ADASAV SAVE FILES=10,15
Files 10 and 15 are to be saved.
ADASAV SAVE FILES=3,4,5, ADASAV PASSWORD='PWD3,,PWD5'
Save files 3, 4, and 5. Files 3 and 5 are password protected and their passwords are PWD3 and PWD5.
