With the aid of the SAVE statement, you can save the following data on tape or disk:
catalog entries of files on private volumes
entire files on private or public disks
file blocks which have been modified since the last full save
job variables
Save data created in an earlier SAVE run can be copied to these volumes. The saves produced by SAVE can be read in again in a RESTORE run.
The files and/or job variables to be processed must be specified in FILES and/or JOBVAR statements before you enter the SAVE statement.
S[AVE] |
DIR[ECTORY] = ARCHIVE.DIR[,NEW] / filename[,NEW] / NONE ,S[AVE]-ACL = YES / NO [,CONT[INUE] = svid / [svid,](vsn,...),...] ,RETPD = 0 / days ,ER[ASE] = NO / YES / ALL / ALLP / ALLCNS / ALLPCNS ,NOW = YES / NO[,TIME = sec] |
DIRECTORY =
This specifies whether a directory file is to be used for the SAVE run, and if so which one.The person initiating the run must be authorized to read and write in this directory file. Any necessary passwords must be entered with the /ADD-PASSWORD command.
DIRECTORY = ARCHIVE.DIR / filename
This specifies the name of the directory file to be used in this SAVE run.
The file must already exist and contain entries from ARCHIVE.
DIRECTORY = filename,NEW
A file with this name is to be initialized as a directory file.
NEW must be specified even if the file already exists but is still empty, i.e. contains no entries from ARCHIVE.
DIRECTORY = NONE
No directory file is to be used for this run.
DIRSAVE =
This operand determines whether the directory file is saved to the volume.
DIRSAVE = NO
The directory file is not saved to the volume.
All files which have the same name as the directory file being used are skipped.
When copying a save file to another save file, any file in the input save version with the same name as the directory file will not be copied.
If the directory file is contained in the list of file names to be processed and DIRSAVE=NO is specified, the directory file will not be processed.
DIRSAVE = YES
The directory file is saved to the volume as the last file of this run.
The DIRSAVE operand only applies if files are found which are to be saved.
The entire directory file is saved, regardless of the values of the CHANGED and BACKUP operands in the SAVE statement or the corresponding catalog entries.
A directory file is always resident on a single volume, i.e. there are no continuation volumes within a directory file.
A saved directory file cannot be restored if you specify a directory file with the same name in the RESTORE run.
If the directory file is contained in the list of file names to be processed and DIRSAVE=NO is specified, the directory file will not be processed.
BACKUP = E / D / C / B / A
This allows you to specify the files to be saved on the basis of the BACKUP entry in the file catalog.
Only those files are saved whose BACKUP entry in the file catalog is equal to or less than the BACKUP value in the SAVE statement (A < B < C < D < E).
Files which are not to be backed up should have the BACKUP entry E in the file catalog. But files with the BACKUP entry E can also be saved using SAVE. However, this procedure is not recommended.
This operand is ignored for job variables.
CHANGED =
specifies which files are to be fully, partially or not saved.
CHANGED = YES
Only those files are fully saved which have either not been cataloged in the directory file or which have been cataloged there but have been updated since the last full or incremental save.
Incremental saves from a private disk with the status “write lockout” (PPD) cannot be executed.
CHANGED = YES,LARGE
Of the files marked in the catalog as LARGE only the pages modified since the last full save are saved (partial save). If there has been no change, the file is not saved. If there is no full save available, or no full save appropriate to the last partial save, the file is saved completely.
CHANGED = YES,PAM pages
This has a similar effect to that of CHANGED=YES,LARGE but is only valid for files which occupy more pages than are given by PAM pages. PAM pages must be an integer >=0.
CHANGED = NO
The specified files are always saved completely.
With CHANGED=YES a directory file must be specified. If DIRECTORY=NONE is specified, CHANGED=NO must also be specified.
If too many partial saves are performed between two full saves, ARCHIVE automatically performs a full save.
This operand is ignored when saving job variables.
UNUSED = 0 / days
This allows you to select the files to be saved on the basis of the ACCESS-DATE entry in the file catalog. Files are only saved if they have not been accessed for the period specified. Files that have no ACCESS-DATE entry are not saved.
In the case of a RESTART run, the period is reckoned from the date of the RESTART run.days can be a value from 0 - 36159 (99 years). This operand is ignored for job variables.
CATONLY =
specifies whether only catalog entries of the files are saved.
CATONLY = NO
The files and their catalog entries are saved.
CATONLY = YES
Of the files specified in the FILES statement, only the catalog entries for files located on private volumes are saved.CATONLY=YES presupposes DIRECTORY=NONE, i.e. the latter is assumed even if a directory file is specified.
When job variables are saved, this operand is ignored.
Catalog entries saved with CATONLY=YES are restored with the value of the file size at the time of the save run.
DUPLICATE =
This specifies whether files or job variables that have been entered in several FILES or JOBVAR statements are also saved several times.
DUPLICATE = YES
Files or job variables which exist more than once are to be saved more than once; a warning is issued when this happens.
DUPLICATE = NO
All duplicate files or job variables are to be saved only once, i.e. the first file or job variable specified in the FILES or JOBVAR statement is processed.
DUPLICATE=NO is only permitted if a directory file is specified.
SAVE-ACL =
This determines whether the ACL entries (SECOS up to V3.0) for saved files are also saved.
SAVE-ACL = YES
The ACL entries of the saved files are also saved.
The value of the BLOCK-SIZE operand must be at least 3.
The save files created with SAVE-ACL=YES cannot be read by the software product SIR.
SAVE-ACL = NO
The ACL entries of the saved files are not saved.
CONTINUE =
This operand determines that an existing save version is to be extended.
The last volume of this save version is requested again. The new files or job variables are written after the last file or job variable.
If the user has specified a directory file for the save run to be continued, ARCHIVE does not save files which
have already been saved in a later save version of the specified directory file, or
have already been saved in the save version which is being continued.
ARCHIVE includes files not saved for these reasons in the report. This ensures that
no file is saved more than once under the same svid
a subsequent RESTORE run with FROM=LATEST produces the correct results.
Any extra continuation volumes required for the output must be specified in the TAPES/VOLUME operand.
The first volume, i.e. the one to be continued, may not be specified in the TAPES/VOLUME operand. It should be specified in the CONTINUE operand or it will be found automatically.
The DIRECTORY, CATONLY, SAVE-ACL, BACKUP, CHANGED, COMPRESS, CATID, SVPASS and BLOCK-SIZE operands must be assigned the same values as the corresponding operands of the run to be continued.
If the operands DIRSAVE, DEVICE, ERASE, LIST or SHARE do not have the same values as they had for the first run, the warning ARC0055 is issued.
The RETPD operand is ignored in a CONTINUE run. The new retention period is calculated internally in such a way that the expiration date matches that of the original save.
If tapes or MT cartridges created with an ARCHIVE version < V2.8A do need to be continued for some reason, they have to be previously converted to the new format via tape-to-tape saving (see the FROM operand in the FILES statement).
In runs with DIRECTORY=NONE the user must ensure that files with the same names are not saved in the same save version, since it will otherwise be impossible to predict which of the files will actually be restored in a subsequent RESTORE run.
For save versions on disk, the specification svid,(vsn,...) is mandatory, even in runs without a directory.
The continuation disks are specified in the VOLUME operand. They must be of the same device type.
If no continuation disk is required, the VOLUME specification can be omitted. When the specified disks are full, ARCHIVE aborts the run. Sufficient disks must therefore be specified in advance.
If DIRSAVE=YES is entered together with the CONTINUE operand and the original save run was also performed with DIRSAVE=YES, the message ARC0040 is output for the directory file.
CONTINUE = svid
A directory file must have been specified. The last VSN is taken from the directory file for each parallel run.
CONTINUE = svid,(vsn,...)
If, for this combination of operands, a directory file is also specified, ARCHIVE checks whether the specified volumes belong to this save version (svid):
if this is not the case, ARCHIVE does not execute the save run;
if it is the case, the last volume is requested and continued.
If no directory file is specified, ARCHIVE requests only the last volume and checks whether it belongs to the specified svid. If it does, the save version is continued.
Regardless of whether or not a directory file is used, it is sufficient to specify the VSN of the last volume.
CONTINUE = (vsn,...),...
This combination of operands is permitted only for tapes or MT cartridges.
If only the VSNs are specified and a directory file is used, ARCHIVE checks whether the volumes all belong to the same save version (svid). If any of the volumes does not belong to this svid, ARCHIVE does not perform the save run.
The specification of VSNs or VSN groups has no effect on the allocation of volumes to the subtask. The continuation volumes are allocated to the subtask automatically in this case. The allocation corresponds to that of the original save run.
If no directory file has been specified, no check is carried out.
Regardless of whether or not a directory file has been specified, it is sufficient to specify the VSN of the last volume.
TAPES / VOLUME =
This operand enables the VSNs of the output volumes to be defined.
POOL and OPERATOR are permitted only for tapes and MT cartridges.
POOL only has meaning when together with a directory file; otherwise TAPES=OPERATOR assumed.
TAPES / VOLUME = POOL
The VSNs are taken from the volume pool of the specified directory file in ascending order. If additional volumes are required or if no directory file has been specified, the volumes are requested from the Operating or by MAREN.
After deletion of the save version, the volumes are again AVAILABLE in the pool.
This operand is not permitted when saving to disk.
TAPES / VOLUME = OPERATOR
If MAREN is being used, the volume is made available by MAREN. Otherwise the name of a VSN is requested via message DMS0591 at the console. The specified VSN is entered in the pool with the qualifier “OPERATOR”.
When the save version is deleted, the volumes are removed from the pool.
This operand is not permitted when saving to disk.
TAPES / VOLUME = vsn / (vsn,...)
The volumes are requested in the specified order.
For tapes and MT cartridges:
The specified VSNs are entered in the pool with the qualifier OPERATOR. When the save version is deleted, the volumes are removed from the pool.
Additionally required volumes are assigned by MAREN or by the operating.
For disks:
If the disks specified for saving are insufficient, ARCHIVE aborts the run.
Only the system support is authorized to specify a public disk, and this must be a disk from the home pubset.
vsn may not begin with PO or OP (conflict with the operand values OPERATOR or POOL).
DEVICE = TAPE-C4 / device type
This operand specifies the device type for all the VSNs specified in the TAPES/VOLUME or CONTINUE operand. This also applies to VSNs only specified indirectly, e.g. in CONTINUE=svid.
MAREN-LOCATION=<alphanum-name 1..8>
This operand specifies the MAREN storage location from which free volumes should be taken if no volume is specified in the statement and no volume is available in the ARCHIVE directory pool. The following applies:
If the MAREN software product is not installed or started, the operand has no effect.
If the software product MAREN is installed, the specified MAREN-LOCATION may be overwritten implicitly by MAREN EXITS or a reservation file. In this case the user is not informed about the change. If however the run should be aborted, the MAREN-Parameter OVERRULE-LOCATION = *REJECT needs to be set (from MAREN V12.5A). If MAREN exits and/or a reservation file are used, it is recommended not to specify a MAREN-LOCATION in the SAVE or EXPORT statements.
DRIVES = 1 / integer
This operand specifies the number of parallel runs (up to 16). A number of devices are used in parallel. The value of integer must be equal to or less than the number of devices available.
RETPD = 0 / days
This operand defines a retention period in days for the save version. During this period
the save version in the directory file is protected against being deleted (PURGE),
tapes and MT cartridges are protected against being overwritten and
the save files on disk are protected against being overwritten or deleted.
The maximum permissible retention period is 32767 days, i.e. approx. 90 years.
SHARE =
This operand defines whether the volumes or save files that have been created are given the attribute “shareable”.
SHARE = NO
The volumes or save files created are nonshareable. The saved files and job variables can only be read in again under the user ID under which they were saved.
The user cannot even read in his/her files and job variables from a save file of the system support. Other users cannot access the volumes.
SHARE = YES
The volumes or save files created are shareable. The saved files and job variables under the user's ID can be read in. On the other hand, it is not possible to access files and job variables of other users, not even via LIST. Other users can, however, access the volumes themselves.
The specification is only of significance for the system support. If the system administrator carries out system backup using SHARE=YES, each user can restore his/her files and job variables from the save file.
SVPASS = password
This operand defines a read password for the save file.
When a file or job variable is to be read in again, this password must be specified either in the PASSWORD operand or via the /ADD-PASSWORD command.
PRIMARY = 500 / PAM pages
This operand specifies the number of blocks (2048 byte) for the primary allocation of the save file (file to which the data is saved), when saving to hard disk.PAM pages must be an integer between 32 and 50331645.
When saving to tape or MT cartridge, this operand is ignored.
SECONDARY = 100 / PAM pages
This specifies the number of blocks (2048 Byte) for the secondary allocation of save files when saving to hard disk. PAM pages must be 0 or an integer between 32 and 32767. If the value 0 is assigned and ARCHIVE tries to extend the save file, a DMS error occurs.
When saving to tape or MT cartridge, this operand is ignored.
BLOCK-SIZE =
This operand specifies the maximum number of PAM pages of the saved file that are stored in one ARCHIVE save block. BLOCK-SIZE=16, for example, means that up to 16 PAM pages from the saved file are written into one save block.
The operand name TAPE-BLOCK-SIZE is supported only for reasons of compatibility.
If this parameter is not specified, ARCHIVE uses the setting in the ARCHIVE parameter BLOCK-SIZE-T-C for tape cartridge devices and the setting in the ARCHIVE parameter BLOCK-SIZE-TAPE for long tapes.
BLOCK-SIZE = STD
The compatible block size of 32 kB, which corresponds to BLOCK-SIZE=15, is used.
BLOCK-SIZE = MAX
The maximum block size possible in this BS2000 version and for this device is used, in other words 256 kB for BS2000/OSD V6.0 or higher and TCs of type TAPE-C3 or higher, and otherwise 32 kB. When saving to public disk ARCHIVE determines the BLOCK-SIZE on the basis of the disk’s maximum transfer length.
BLOCK-SIZE = PAM-pages
The permissible value range depends on the save operation; it extends from 2 to 35:
The minimum value is 2 for
SAVE-ACL=NOor 3 forSAVE-ACL=YES.The maximum value is 15 when saving to tape or MT cartridge, 31 when saving to private disk, and 35 when saving to public disk.
For values greater than 31, the user must check their device configuration (with /SHOW-MASTER-CATALOG-ENTRY ...,INFORMATION=*USER) in order to ensure whether such values are permissible.
When saving NK4 disks, only odd values are used; if an even value is specified, a warning is issued and the value is decremented to the next lower odd value.
The default value is 15 for magnetic tape or MT cartridge devices and 31 for hard disk devices. On a hard disk device, values lower than 15 will reduce the performance of ARCHIVE.
COMPRESS =
This operand determines whether the data should be written into the save file in a compressed form.
COMPRESS = NO
The data is not compressed before it is written to the save file.
COMPRESS = YES
The data is written to the save file after software compression.
In the case of device types which automatically execute hardware compression (e.g. TAPE-C4), COMPRESS=NO is assumed.
The save files created via COMPRESS=YES cannot be read by the software product SIR.
CONSISTENCY-CHECK / CONS-CHK =
This operand determines whether check bytes are calculated for a consistency check of the save files.
CONSISTENCY-CHECK = NO
Check bytes are not calculated.
On a subsequent RESTORE or LIST operation, a CONSISTENCY-CHECK=YES entry is ignored.
CONSISTENCY-CHECK = YES
Check bytes are calculated and stored with the save data.
On a subsequent RESTORE or LIST operation, the correct transmission of save data is checked.
ERASE =
This operand determines whether the files and job variables are deleted after a save run.
ERASE = NO
The files and job variables are not deleted after the save run.
ERASE = YES
The saved files and job variables are deleted after the save run if they are not protected by means of a password or a retention period and if modifying access is permissible for them.
ERASE = ALL
As for YES, but those files and job variables which are protected by means of a retention period and for which only read access is permitted are also deleted.
ERASE = ALLP
This operand can only be specified with the TSOS privilege.
As for ALL, but those files and job variables protected by a password are also deleted, without the password having to be specified.
ERASE = ALLCNS
As for ALL, but those files not saved in the current ARCHIVE run (as they were not updated) are also deleted (entry in the directory file: CNS).
ERASE =ALLPCNS
This operand can only be specified with the TSOS privilege.
The effect is as for ALLP, but those files not saved in the current ARCHIVE run (as they were not updated) are also deleted (entry in the directory file: CNS).
File generation groups (FGGs) and file generations are only deleted if the entire FGG was saved in this run.
If the ERASE operand is specified together with CATONLY=YES, only the catalog entry is deleted, not the file.
When copying save data, the ERASE operand is ignored.
NOW =
This operand specifies when the save run is to be performed.
NOW = YES
The SAVE statement is executed immediately.
NOW = NO
The SAVE statement is checked for correct syntax and then written to the queue file ARCHIVE.LATER. This process is given the ARCHIVE identifier L.yymmdd.hhmmss. The identifier is only allocated if no LATER job exists in the same task at the time. If this is not the case, then the process is stored under the existing identifier.
The LATER job can be started by means of a PROCESS statement or deleted by means of a DELETE statement.
NOW = NO,TIME=sec
This specifies the number of CPU seconds available to this process once it is started. This specification corresponds to the CPU-LIMIT operand in the /START-(EXECUTABLE)-PROGRAM command.
PASSWORD = password / (password,...)
If you specify the operand NOW=NO, you must enter here the passwords for
files or job variables to be imported which are protected by read passwords.
the directory file, if it is protected by a write password and is not under TSOS.
the save version, if it has been protected by a password with SVPASS.
magnetic tapes and MT cartridges that are protected by a password (up to 4 characters) under MAREN.
In all other cases, you should specify the passwords with the /ADD-PASSWORD command before calling ARCHIVE.
The systems support staff can process files and job variables without specifying the passwords. The password for the directory file, however, must be specified if the directory file is assigned to another user ID.
LIST =
This specifies the output medium for the report of the SAVE run.
LIST = SYSLST
The report is output to SYSLST.
LIST = SYSOUT
In an interactive task, the report is output to the terminal.
LIST = BOTH
The report is output to both SYSLST and SYSOUT.
LIST = NONE
No report is generated.
Notes to SAVE
In the SAVE run, ARCHIVE checks the MT cartridge entries. If a DMS message appears (e.g. wrong entry), it may not be answered with tsn.IGNORE. Otherwise there is the danger that the volume archive number saved in the directory file will not match the actual one. This will lead to difficulties in a later RESTORE run.