This statement is used for restoring BS2000 files and job variables from a backup, version backup or long-term archive to the processing level. The files and job variables can be renamed, reorganized and written to different volumes during the restore. It is possible to specify individual save files and save versions from which the files and job variables are to be restored.
This statement has different formats for nonprivileged users and HSMS administrators. Privileged operands or operand values are marked with *P).
Format
RESTORE-FILES | Alias: RSF | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) Privileged operand or operand value
FILE-NAMES =
Specify the files to be restored. Specification of this operand is mandatory. The user can select individual files from the set of files specified here by means of the operands EXCEPT-FILE-NAMES, DIALOG-FILE-SELECT and ORIGINAL-SUPPORT (the latter is restricted to the HSMS administrator).
A file cannot be restored unless the pubset to which it is to be restored is available and the user ID involved has a JOIN entry for this pubset.
If files from more than one pubset are specified and are to be restored from a default system archive, then the same default system archive must be assigned to all these pubsets. Otherwise, the HSMS statement will be rejected. To prevent this you should only specify files from one pubset for each restore request.
All nonprivileged users can also restore files belonging to other user IDs if they are co-owners of these files.
FILE-NAMES = *OWN
All files are restored that are listed in the archive directory and belong to the user’s own ID.
FILE-NAMES = *ALL
All files are restored that are listed in the archive directory.
FILE-NAMES = *NONE
No files are restored.
FILE-NAMES = *SELECTED
The path names of the files to be restored are to be taken from a list that was compiled within the same HSMS run by means of the HSMS statement SELECT-FILE-NAMES.
FILE-NAMES = *FROM-FILE(...)
The path names of the files to be restored are to be taken from a file. The nonprivileged caller must be owner or co-owner of this file. This list file must be a SAM file with variable-length records containing one path name per record. Only upper-case characters may be used. The list file can be created, for instance, by means of the HSMS statement SELECT-FILE-NAMES or the BS2000 command SHOW-FILE-ATTRIBUTES.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
FILE-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the files which are to be restored are taken from a PLAM library element (type S). The library element contains one path name per record. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
FILE-NAMES = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the files to be restored are specified directly. A list of up to 20 names may be specified.
The file names may be specified as fully or partially qualified names, with or without a catalog/user ID. If required, the file name is extended by the user ID of the request and the catalog ID which is either taken from the specified environment or the default catalog ID of the user ID.
The files can alternatively be selected using wildcards. The wildcards are replaced in accordance with the file names listed in the archive directory.
Restore runs are executed more quickly if you use fully qualified file names.
The following applies to file generations: when specifying fully qualified file names, the specification of a generation number (version) is permissible. Only the specified generations will be restored.
EXCEPT-FILE-NAMES =
Serves to specify files that are to be excluded from restoration.
EXCEPT-FILE-NAMES = *NONE
All files specified with the FILE-NAMES operand are to be restored.
EXCEPT-FILE-NAMES = *FROM-FILE(...)
The path names of the files to be excluded from restoration are to be taken from a file. The nonprivileged caller must be owner or co-owner of this file. Only upper-case characters may be used.This list file must be a SAM file with variable-length records containing one path name per record. The list file can be created, for instance, by means of the BS2000 command SHOW-FILE-ATTRIBUTES.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
EXCEPT-FILE-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the files which are not to be restored are taken from a PLAM library element (type S). The library element contains one path name per record. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
EXCEPT-FILE-NAMES = list-poss(20): <filename 1..80 without-vers-with-wild> /
<partial-filename 2..79 with-wild>
The path names of the files to be excluded from restoration are specified directly. A list of up to 20 names may be specified.
The first character of the file names must not be a hyphen. The file names may be specified as fully or partially qualified names, with or without a catalog/user ID. If required, the file name is extended by the user ID of the request and the catalog ID which is either taken from the specified environment or the default catalog ID of the user ID.
The files can also be selected using wildcards. The wildcards are replaced in accordance with the file names listed in the archive directory.
The following applies to file generations: when specifying fully qualified file names, the specification of a generation number (version) is permissible. Only the specified generations will be excluded from restore.
NEW-FILE-NAMES =
The files can be renamed before being restored. The user must ensure that the new path name conforms to the BS2000 conventions governing names. The total length must not exceed 54 characters; this implies that the file name without user ID and catalog ID should not exceed 38 characters (to allow for its extension by the catalog ID). The new file name is formed as follows:
:cat-id:$user-id.<prefix>.old-filename-without-cat-user.<suffix>
NEW-FILE-NAMES = *SAME
The files are to be restored under their original names.
NEW-FILE-NAMES = *BY-RULE(...)
The files are to be renamed using a common rule.
If the value *CATALOG-ONLY is specified in the MIGRATED-FILES operand, only the suboperands NEW-CATALOG-ID and NEW-USER-ID may be specified; the suboperands PREFIX and SUFFIX are in this case not allowed.
NEW-CATALOG-ID = *SAME / <cat-id>
The files may be restored under a different catalog ID, which is specified without a colon. The user ID must have a JOIN entry for this catalog.
Unless otherwise specified, the files are restored under their original catalog ID.
NEW-USER-ID = *SAME / <name 1..8>
The files may be restored under a different user ID, which is specified without a leading “ $ ” character.
Unless otherwise specified, the files are restored under their original user ID.
PREFIX = *NONE / <filename 1..8 without-cat-user-gen-vers>
A prefix of up to 8 characters may be added to the file name, automatically separated from the file name by a period (partial qualification).
The prefix must not contain any letters that are prohibited for file names.
Unless otherwise specified, no prefix is added to the file names.
SUFFIX = *NONE / <composed-name 1..8>
A suffix of up to 8 characters may be added to the file name, automatically separated from the file name by a period (partial qualification).
The suffix must not contain any letters that are prohibited for file names.
Unless otherwise specified, no suffix is added to the file names.
ENVIRONMENT =
Defines the HSMS environment in which this HSMS statement is valid.
ENVIRONMENT = *STD
Meaning for privileged users: *STD is set to the value *SINGLE-FEATURE.
Meaning for nonprivileged users: *STD is the environment that is associated with the user’s default pubset (the default pubset is defined in the user catalog).
ENVIRONMENT = *SINGLE-FEATURE
The HSMS statement relates to an SF environment.
ENVIRONMENT = *SYSTEM-MANAGED(...)
The HSMS statement relates to the specified SM pubset environment.
CATALOG-ID = <cat-id>
Catalog ID of the SM pubset to which the HSMS statement applies.
ORIGINAL-SUPPORT =
This operand is only available to the HSMS administrator.
This operand is only valid in an SF pubset environment.
Serves to select the files to be restored using as the selection criterion the volume on which they were resident before being saved.
ORIGINAL-SUPPORT = *ANY
The files are to be restored irrespective of the volume from which they originate.
ORIGINAL-SUPPORT = *PUBLIC-DISK(...)
Restricts restoration to files originating from public volumes (pubset and possibly assigned Net-Storage).
STORAGE-TYPE =
Selects the storage type for public volumes.
STORAGE-TYPE = *ANY
The files on public volumes are restored irrespective of the storage type. They can come from the disks of a pubset or of a Net-Storage.
STORAGE-TYPE = *PUBLIC-SPACE
Only files which come from the disks of a pubset are restored. Files from a Net-Storage are ignored.
STORAGE-TYPE = *NET-STORAGE(...)
Only files which come from a Net-Storage are restored.
VOLUMES = *ALL / list-poss(150): <vsn 1..6>
Specifies the VSN of one or more Net-Storage volumes from which the files to be restored come. *ALL selects all Net-Storage volumes.
FILE-TYPE =
Selects the file type of Net-Storage files that will be restored.
FILE-TYPE = *ANY
The Net-Storage files are selected irrespective of the file type.
FILE-TYPE = *BS2000
Only Net-Storage files of the type BS2000 are selected.
FILE-TYPE = *NODE-FILE
Only Net-Storage files of the type node file are selected.
ORIGINAL-SUPPORT = *PRIVATE-DISK(...)
Restricts restoration to files originating from private disks.
VOLUMES = list-poss(150): <vsn 1..6>
Volume serial numbers of the private disks.
NEW-SUPPORT =
Serves to define the volumes to which the files are to be restored.
NEW-SUPPORT = *STD
The files from backup archives are restored to the volumes from which they originate. Files from other archive types are written to public volumes. Net-Storage files originally stored on volume of NETVOL type can be restored only on BS2000 V21.0A or higher.
NEW-SUPPORT = *PUBLIC-DISK(...)
The files are to be restored to public volumes (pubset or assigned Net-Storage). Net-Storage volumes of type NETVOL can be used only on BS2000 V21.0A or higher.
STORAGE-TYPE =
Selects the storage type for public volumes.
STORAGE-TYPE = *STD
The files originally stored on public disk are restored to the original storage medium, files originally stored on private disk are restored on public volumes. Net-Storage files originally stored on volume of NETVOL type can be restored only on BS2000 V21.0A or higher.
STORAGE-TYPE = *PUBLIC-SPACE
The files are only written back to disks of the pubset concerned.
STORAGE-TYPE = *NET-STORAGE(...)
The files are only written back to the Net-Storage which is assigned to the pubset concerned.
Irrespectively of the specification, the files under system users (SERVICE, SYSAUDIT, SYSDUMP, SYSGEN, SYSHSMS, SYSMAREN, SYSNAC, SYSOPR, SYSPRIV, SYSROOT, SYSSNAP, SYSSNS, SYSSOPT, SYSSPOOL, SYSUSER) are restored on disks of the pubset concerned.
VOLUME = <vsn 1..6>
Specifies the VSN of the Net-Storage volume to which the files are written back. Net-Storage volumes of type NETVOL are rejected on systems older than BS2000 V21.0A.
If the files to be restored are from the pubset which is not associated with the specified Net-Storage volume, they should be renamed with NEW-FILE-NAMES = *BY-RULE(NEW-CATALOG-ID=<cat-id>) where cat-id is the catid of the pubset associated with the Net-Storage volume.
FILE-TYPE =
Specifies the type in which files will be restored to Net-Storage.
FILE-TYPE = *STD
The files are restored with their original type.
FILE-TYPE = *BS2000
The files are restored with the type BS2000.
FILE-TYPE = *NODE-FILE
The files are restored with the type node file.
NEW-SUPPORT = *PRIVATE-DISK(...)
The files are to be restored to private disks. All disks must be of the same device type.
VOLUMES = list-poss(150): <vsn 1..6>
Volume serial numbers of the private disks.
DEVICE-TYPE = STDDISK / <device>
Device type of the private disks. The default setting STDDISK selects the default device type. Only device types known in the system are accepted. In interactive mode, DEVICE-TYPE=? calls up a list of the available device types.
NEW-SUPPORT = *SYSTEM-MANAGED-PUBSET(...)
The files are written back to an SM pubset (pubset or assigned Net-Storage).
STORAGE-CLASS =
Determines the storage class with which the files are written back.
STORAGE-CLASS = *ORIGINAL
Files backed up from SM pubsets are written back with their original storage class. Files backed up from SF pubsets are written back without a storage class.
STORAGE-CLASS = *STD
The files are written back with the storage class that is the default for users (with the same rules that the DMS uses for /CREATE-FILE STORAGE-CLASS=*STD).
STORAGE-CLASS = *NONE(...)
The files are written back without a storage class.
VOLUME-SET-ID =
In an SM pubset environment, the volume set can be specified to which the files are to be written back.
VOLUME-SET-ID = *BEST-VOLUME-SET
The files to be restored are written back to the volume set that best matches their file attributes. The specification of the best volume set does not take S1 volume sets into account.
VOLUME-SET-ID = *ORIGINAL
This value is only allowed for users who have the privilege to carry out physical allocation and if the files are written back to the same SM pubset.
The files are written back to the same volume set from which they originated.
VOLUME-SET-ID = <cat-id>
When working in an SM pubset environment, a user who has file allocation permission (see user attributes) can specify the catalog ID of a volume set in an SM pubset. The files on this volume set are selected for restoration.
STORAGE-TYPE =
Selects the storage type for shared volumes.
STORAGE-TYPE = *STD
The files are restored on public volumes.
STORAGE-TYPE = *PUBLIC-SPACE
The files are only written back to disks of the pubset concerned.
STORAGE-TYPE = *NET-STORAGE(...)
The files are only written back to the Net-Storage which is assigned to the pubset concerned.
VOLUME = <vsn 1..6>
Specifies the VSN of the Net-Storage volume to which the files are written back. Net-Storage volumes of type NETVOL are rejected on systems older than BS2000 V21.0A.
FILE-TYPE =
Specifies the type in which files will be restored to Net-Storage.
FILE-TYPE = *STD
The files are restored with their original type.
FILE-TYPE = *BS2000
The files are restored with the type BS2000.
FILE-TYPE = *NODE-FILE
The files are restored with the type node file.
MIGRATED-FILES =
This operand is only available to the HSMS administrator.
Specifies the RESTORE procedure for migrated files. Migrated files are files that are saved as “migrated” in the backup or version backup archive.
Only the HSMS administrator has a choice of operand settings. Nonprivileged users may only specify *DATA-AND-CATALOG.
MIGRATED-FILES = *DATA-AND-CATALOG
The migrated files are restored to S0 together with their data. If the backup archive only contains the catalog entry for migrated files, then only the catalog entry is restored. The data is then brought to S0 from the migration archive by performing a RECALL. If the migration archive does not contain the relevant data, the catalog entry is deleted. The system then reports the file as being unable to be restored.
MIGRATED-FILES = *CATALOG-ONLY
Only the catalog entries are restored for all migrated files. The catalog entries are modified so that they reference the latest appropriate data in the migration archive. If the migration archive does not contain any appropriate data for a file, the system indicates an error. The file’s catalog entry is not deleted.
NET-STORAGE-FILES = *DATA-AND-CATALOG / *CATALOG-ONLY
Specifies whether only the catalog entry or also the data should be restored for files on Net-Storage. The default is *DATA-AND-CATALOG, i.e. the data and catalog entry are restored.
This operand makes only sense in connection with Net-Storage files of the type BS2000 originating from NETSTOR volume type. Net-Storage files of the type node file are always restored with data. Net-Storage files originating from NETVOL volume type are always restored with data.
JV-NAMES =
Serves to specify the job variables to be restored. A job variable cannot be restored unless the pubset to which it is to be restored is available and the user ID involved has a JOIN entry on this pubset.
If job variables from more than one pubset are specified and are to be restored from a default system archive, then the same default system archive must be assigned to all these pubsets. Otherwise, the statement will be rejected. To prevent this you should only specify job variables from one pubset for each request.
All nonprivileged users can also restore job variables belonging to other user IDs if they are co-owners of these job variables.
Job variables are not supported in version backup archives.
JV-NAMES = *NONE
No job variables are to be restored.
JV-NAMES = *OWN
All job variables of the user’s own ID residing on any imported pubset are to be restored. The selection is made from the directory.
JV-NAMES = *SELECTED
The path names of the job variables to be restored are taken from a list which is created in the same HSMS run with the HSMS statement SELECT-JV-NAMES.
JV-NAMES = *ALL
All job variables residing on any imported pubset are to be restored. The selection is made from the directory.
JV-NAMES = *FROM-FILE(...)
The path names of the job files to be restored are to be taken from a file. The nonprivileged caller must be owner or co-owner of this file. This list file must be a SAM file with variable-length records containing one path name per record.Only upper-case characters may be used.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
JV-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the job variables which are to be restored are taken from a PLAM library element (type S). The library element contains one path name per record. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
JV-NAMES = list-poss(20): <filename 1..80 without-gen-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the job variables to be restored are specified directly. A list of up to 20 names may be specified.
The job variables can alternatively be selected using wildcards. The wildcards are replaced in accordance with the job variable names listed in the archive directory.
EXCEPT-JV-NAMES =
Serves to specify job variables that are to be excluded from restoration.
EXCEPT-JV-NAMES = *NONE
All job variables specified in the JV-NAMES operand are restored.
EXCEPT-JV-NAMES = *FROM-FILE(...)
The path names of the job variables to be excluded from restoration are to be taken from a file. The nonprivileged caller must be owner or co-owner of this file. This list file must be a SAM file with variable-length records containing one path name per record. Only upper-case characters may be used.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
EXCEPT-JV-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the job variables which are not to be restored are taken from a PLAM library element (type S). The library element contains one path name per record. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
EXCEPT-JV-NAMES = list-poss(20): <filename 1..80 without-vers-with-wild> /
<partial-filename 2..79 with-wild>
The path names of the job variables to be excluded from restoration are specified directly. A list of up to 20 names may be specified. The first character of the job variable names must not be a hyphen.
The job variables can alternatively be selected using wildcards. The wildcards are replaced in accordance with the job variable names listed in the archive directory.
NEW-JV-NAMES = *SAME / *BY-RULE(...)
The job variables can be renamed before being restored.
The job variables can be renamed using NEW-JV-NAMES=*BY-RULE(...) before they are imported. The suboperands and options available are the same as for files (see NEW-FILE-NAMES=*BY-RULE(...)).
RELEASE-UNUSED-SPACE = *NO / *YES
Determines whether or not unused storage space (difference between the last-page pointer and the file size) is to be released after file restoration.
FILE-CONVERSION =
Determines whether files whose PAM key format is different from that of the output volume are to be converted when restored. This operand is ignored for job variables. If *STD or *CONV-FORMAT is specified, PAMINT is called internally.
Only *CONV-FORMAT may be specified for partially saved files.
If a converted file to be restored already exists, it is always reorganized and RELEASE-UNUSED-SPACE is ignored.
FILE-CONVERSION = *STD
During a restore run to an NK disk, files with a PAM key are converted by PAMINT according to the following rules:
K-ISAM files to NK-ISAM files(BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK)
K-SAM-files to NK-SAM files(BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK)
K-UPAM files to NK-UPAM files(BLOCK-CONTROL-INFO=*NO)PAM files whose structure is known (load modules, libraries) are converted accordingly; if the structure of PAM files is unknown and conversion is possible, the PAM key information is lost. A message is displayed if the PAM key contained information.
FILE-CONVERSION = *NO
Files with a PAM key are not converted during a restore run to an NK disk, which means they are not restored.
FILE-CONVERSION = *CONV-FORMAT
During a restore run to an NK disk, files with a PAM key are converted by PAMINT to “CONV format”. The restored file contains all PAM keys at the end of the file in separate blocks.
DATE-AND-PROTECTION =
This operand is only evaluated when restoring from long-term archives. In the event of restoration from backup archives the date and protection attributes are always transferred from the backed-up settings.
Specifies how the date and protection attributes are to be set for files and job variables which have been protected with GUARDS or BASIC-ACL during backup and which are to be assigned new catalog and user IDs.
DATE-AND-PROTECTION = *STD-ATTRIBUTES
The date and protection attributes are set to the defaults. These are as follows:
Date or protection attributes | Overwrite file on hard disk | |
YES | NO | |
Password attributes setting | same as for save file | same as for save file |
USER-ACCESS setting | same as for hard disk | *OWNER-ONLY |
ACCESS setting | same as for hard disk | *WRITE |
BASIC-ACL, GUARDS settings | same as for hard disk | *OFF |
Setting for creation date, expiration date and date of last access | current date | current date |
DATE-AND-PROTECTION = *ORIGINAL-ATTRIBUTES
The data and protection attributes are adopted from the backed up settings.
REPLACE-FILES-AND-JV = *NO / *YES(...)
Determines whether already existing files and job variables are to be overwritten during file restoration. With REPLACE=*NO the names of the files and job variables which are not overwritten are only listed in the full report (REPORT=*FULL).
REPLACE-FILES-AND-JV = *YES(...)
Existing files and job variables are to be overwritten. In addition, the user can specify if and to what extent the file protection attributes, if any, are to be respected:
PROTECTION-RESPECTED = *ALL
Restricts overwriting to files and job variables that are not protected by a password, that permit write access, and whose retention period has expired.
PROTECTION-RESPECTED = *PASSWORDS
Restricts overwriting to files and job variables that are not protected by a password.
PROTECTION-RESPECTED = *NONE
This operand is only available to the HSMS administrator.
All files and job variables are to be overwritten, irrespective of their protection attributes.
REORGANIZE-SPACE = *YES / *NO
Determines whether the existing files are to be erased before the restore operation, which implies file reorganization, or whether the file is to continue to occupy the same extents on the disk. The operand is evaluated with existing files only.
PASSWORDS = *NONE / *SECRET-PROMPT / list-poss(63): <c-string 1..4> /<x-string 1..8> / <integer -2147483648..2147483647>
If files or job variables to be restored are protected by a password or if the save file has a password, the passwords must be specified here. HSMS administrators do not need to specify a password.
If a directory file is used which is protected by passwords, all users must specify the read and write password.
The PASSWORDS operand has the following special characteristics:
The password entered is not logged.
The input field is automatically blanked out in an interactive dialog.
In unguided dialog and foreground procedures, the entry *SECRET or ^ permits concealed input of the password.
ARCHIVE-NAME =
Defines the name of the archive in the specified environment from which the files and job variables are to be restored. If a shadow archive is to be used for the restore, the archive name must be specified explicitly.
If a default system archive is specified, it must already exist and, for restoration from more than one pubset, be unequivocally assigned to these pubsets.
If the archive directory is protected by a password, this password must be entered by means of the ADD-PASSWORD command prior to statement entry. This also applies to HSMS administrators.
So that the nonprivileged user can use the archive of another user, read access must exist for that archive (USER-ACCESS=*ALL-USERS and ACCESS=*READ) or you must have co-ownership of the archive directory.
ARCHIVE-NAME = *SYSBACKUP
The files are to be restored from the assigned default system backup archive in the specified environment.
ARCHIVE-NAME = *SYSARCHIVE
The files are to be restored from the assigned default long-term system archive.
ARCHIVE-NAME = *SYSMIGRATE
The files are to be restored from the specified environment and the assigned default system migration archive.
ARCHIVE-NAME = *SYSVERSION
The files are to be restored from the system version backup archive assigned to the pubset given in FILE-NAMES in the specified environment. It means specification of files from different pubsets will be rejected.
ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>
The files are to be restored from the specified environment and specified archive.
SELECT-SAVE-VERSIONS =
Serves to define the save versions to be used for restoration.
Usually, the most recent version of each of the files specified via FILE-NAMES is selected from all the save versions specified for restoration, unless the user explicitly selects individual versions by means of DIALOG-FILE-SELECT.
Explicit specification of FILE-NAMES=*ALL(*OWN) in conjunction with the default value SELECT-SAVE-VERSIONS=*STD or SELECT-SAVE-VERSIONS=*ALL causes the most recent versions of all files (of the calling user) that were ever saved in the specified archive to be restored.
*STD and *ALL should therefore be specified after careful consideration only (e.g. in combination with the explicit specification of file names) so as to avoid accessing an unnecessarily large number of save versions and volumes.
SELECT-SAVE-VERSIONS=*STD
The effect of the option depends on the archive type.
For archival and backup archives, their shadows and migration archives it has the same effect as *ALL.
For version backup archives, the operand has the same meaning as when specifying SAVE-VERSIONS=*BY-ATTR(SAVE-VERSION-NAME=*ANY, SAVE-VERSION-DATE=*BY-ORIGINAL-DATE(CREATED-BEFORE=*LATEST-DATE ,CREATED-AFTER=*EARLIEST-DATE). In other words, in case of version backup archive the most recent file version will be restored. After a reorganization of a version backup archive, it can happen that older versions of a file are stored in save versions with a newer timestamp. The file versions to be restored are therefore not selected according to the time stamp of the SVIDs, but according to the time stamp of the original backup (*BY-ORIGINAL-DATE).
SELECT-SAVE-VERSIONS = *ALL
The option is relevant only for backup and archival archives, their shadows and migration archives.
All save versions are to be selected for the restore operation. The specified files and job variables are in each case restored from the most recent save version in which they are contained.
In the case of version backup archives the option will be rejected.
SELECT-SAVE-VERSIONS = *LATEST(...)
The option is relevant only for backup and archival archives, their shadows and migration archives.
Only the most recently created save version is to be used for the restore operation.
When restoring from a backup archive, this means that of all the files specified only those will be restored which were actually saved or registered as “cataloged-not-saved” (CNS) during the last backup run.
The option is not applicable for version backup archives.
DAY-INTERVAL = *NO
Only the latest save version created is considered for the restore.
DAY-INTERVAL = *YES
This operand is only available for backed up files.
If more than one save version was created on the same day, you can extend the term “latest save version” to a number of save versions which were created on the same day by specifying DAY-INTERVAL=*YES.
In this case the last save version to be created plus all save versions that were created on the same day as this one are considered for the restore. This is not possible, however, if the save version was created with the HSMS statement ARCHIVE-FILES.
CREATED-AFTER = *EARLIEST-DATE
Files which were marked as “cataloged-not-saved” (CNS) during the last backup are restored from the most recently created save version - irrespective of its creation date.
CREATED-AFTER = <date with-compl>
Files which were marked as “cataloged-not-saved” (CNS) during the last backup are only restored if they were saved in a save version that was created on or after the specified date.
CREATED-AFTER = <integer -99999..0 days >
Serves to restrict the selection to save versions which were created on or after the specified relative date.
SELECT-SAVE-VERSIONS = *BY-ATTRIBUTES(...)
Serves to select the save version to be used for restoration using its attributes as the selection criterion.
SAVE-VERSION-NAME = *ANY / <name 1..8>
Selects the save version to be used for restoration via the name assigned to it at creation.
The option of selecting save versions that were created by other users is restricted to the HSMS administrator.
Unless otherwise specified, the save versions are selected for restoration irrespective of their names.
When restoring from version backup archives, value *ANY is only relevant.
SAVE-VERSION-DATE =
Selects the save version to be used for restoration via its creation date. In combination with explicit specification of a save version name this operand restricts the selection of save versions to those with both the specified name and the creation date.
SAVE-VERSION-DATE = *LATEST
The option is relevant only for backup and archival archives, their shadows and migration archives.
Only the most recently created save version in the archive is to be used for the restore operation. In conjunction with SAVE-VERSION-NAME=*ANY, this specification is equivalent to SELECT-SAVE-VERSIONS=*LATEST.
In the case of version backup archives the option will be rejected.
SAVE-VERSION-DATE = <date with-compl>(...)
The option is relevant only for backup and archival archives, their shadows and migration archives.
Selects the last save version created on or before the specified date for restoration.
In the case of version backup archives the option will be rejected.
TIME = 23:59:59 / <time>
Selects the last save version created at or before the specified date and time for restoration.
SAVE-VERSION-DATE = *INTERVAL(...)
The option relevant only for backup, archival, their shadows and migration archives.
Serves to select the save versions using a time interval as the selection criterion.
The interval includes all save versions created between CREATED-AFTER and CREATED-BEFORE.
Unless otherwise specified, all save versions, starting with the one created first (*EARLIEST-DATE) up to the one created last (*LATEST-DATE), are selected. In conjunction with SAVE-VERSION-NAME=*ANY, this specification is equivalent to SELECT-SAVE-VERSIONS=*ALL and, like SELECT-SAVE-VERSIONS=*ALL, should be used only after careful consideration.
In the case of version backup archives the option will be rejected.
CREATED-BEFORE = *LATEST-DATE
The save versions are to be selected irrespective of whether they were created before a specific date. A more exact specification is possible using the time field.
CREATED-BEFORE = <date with-compl>(...) / <integer -99999..0 days >(...)
Restricts selection to save versions created before the specified date. The date is specified either in absolute terms or relative to the current date. A more exact specification is possible using the time field.
TIME = 23:59:59 / <time>
The time in the format hh:mm:ss.
CREATED-AFTER = *EARLIEST-DATE
The save versions are to be selected irrespective of whether they were created after a specific date.
CREATED-AFTER = <date with-compl>
Restricts selection to save versions created on or after the specified date.
CREATED-AFTER = <integer -99999..0 days >
Restricts selection to save versions created on or after the specified relative date.
SAVE-VERSION-DATE = *BY-ORIGINAL-DATE(...)
Only for save versions of a migration archive, a long-term archive or a version backup archive.
The effect of the operand value depends on the archive type:
- Migration or long-term archive
You can select a save version of a migration or long-term archive via its creation date (see “Copying save files” in the manual “HSMS Volume 1” [1]). The save version with the highest original creation date in the specified time period is determined. If multiple save versions have the same creation date the save version created last is selected. - Version backup archive
After a reorganization of a version backup archive, it can happen that older versions of a file are included in backup versions with a newer timestamp. The file versions to be restored are therefore not selected according to the time stamp of the SVIDs, but according to the time stamp of the original backup (*BY-ORIGINAL-DATE).
- Migration or long-term archive
CREATED-BEFORE = *LATEST-DATE
The original creation date of the backup versions considered for selection has no upper limit.
CREATED-BEFORE = <date with-compl>(...) / <integer -99999..0 days > (...)
The original creation date of the backup versions considered for selection has an upper limit which is defined by the date specified. The date is specified either in absolute terms or relative to the current date. An additional time specification defines the selection more precisely:
TIME = 23:59:59 / <time>
Time in the format hh:mm:ss.
CREATED-AFTER = *EARLIEST-DATE
The original creation date of the backup versions considered for selection has no lower limit.
CREATED-AFTER = <date with-compl> / <integer -99999..0 days >
The original creation date of the backup versions considered for selection has a lower limit which is defined by the current date specified in absolute or relative terms.
CREATED-AFTER = *SAME-AS-BEFORE
Only the backup version whose original creation date matches the date specified in the CREATED-BEFORE operand is selected.
DEVICE-TYPE = *STD / <device>
Device type of the volume containing the save version. This operand need not be specified unless the save version was created in an ARCHIVE version < V2.6B. In later ARCHIVE versions, the device type used for saving is taken from the directory file and any differing specification is ignored.
Only device types known in the system are accepted. In interactive mode, DEVICE-TYPE=? calls up a list of the available device types.
Unless otherwise specified, the preset value from the archive definition applies.
Note
When tape volumes are copied “offline” from an old device type to a new one with the same VSN without adjusting the directory, an optional REP can be used to ensure that the device type specified explicitly has priority over the device type specified in the directory file and consequently that a device type which differs from the directory file is accepted.
DIALOG-FILE-SELECT =
Defines whether the user wishes to conduct a dialog in order to select individual files from the set of files selected for restoration by means of FILE-NAMES and other operands. This option enables the user to check whether the specified save versions do in fact contain the specified files, thereby enabling him to forestall errors before the request is processed asynchronously.
The operand is evaluated in interactive mode only, for batch tasks it is ignored.
DIALOG-FILE-SELECT = *NO
The specified set of files is not to be further reduced.
DIALOG-FILE-SELECT = *YES(...)
The specified set of files is to be output in a screen mask. The user can then mark individual files from the set displayed, thereby selecting them for or excluding them from restoration.
Details on the content of the screen mask are provided in the section "Dialog selection when restoring files" , for restore from version backup archive in the section "Dialog selection when restoring files from version backup archive", for restore from a long-term or migration archive in the section "Dialog selection when restoring files from long-term or migration archive for save version selection based on original dates" .
SHOW-FILE-VERSIONS =
Determines the number of save versions of a file to be displayed on the screen.
Note, for version backup archives SHOW-FILE-VERSIONS = *DIFFERENT and SHOW-FILE-VERSIONS = *ALL will always have the same result, as only different file versions can be saved via //BACKUP-FILE-VERSIONS.
SHOW-FILE-VERSIONS = *LATEST
Only the most recent save version of each of the specified files is to be displayed on the screen.
Note, in case of version backup archive it means latest according to its original save version, so indeed latest version of the file in the selected range of save versions.
SHOW-FILE-VERSIONS = *DIFFERENT
Only those save versions of a file are to be displayed which were produced after the file had in fact been modified (compared to the previous save run), i.e. which have a different version number or CFID (coded file ID).
SHOW-FILE-VERSIONS = *ALL
All save versions of a file are to be displayed.
DIALOG-JV-SELECT =
Determines whether the set of job variables selected for restoration by JV-NAMES and other operands, is to be further restricted in the dialog.
This means that the user can check whether the job variables he specified really are listed in the save versions he specified, before the request is processed asynchronously and possible errors occur.
The operand is only evaluated in the dialog. For batch requests, it is ignored.
DIALOG-JV-SELECT = *NO
The selected set of job variables is not restricted.
DIALOG-JV-SELECT = *YES(...)
The selected set of job variables is output in a screen mask. The user can then mark individual job variables from the set displayed, thereby selecting them for or excluding them from selection.
Details on the content of the screen mask are provided in the section "Dialog selection when restoring job variables", for restore from a long-term or migration archive in the section "Dialog selection when restoring JVs from long-term or migration archive for save version selection based on original dates" .
SHOW-JV-VERSIONS =
Defines how much of various save versions of a job variable are to be output to the screen.
SHOW-JV-VERSIONS = *LATEST
The job variables are output only from the latest save versions that they contain.
SHOW-JV-VERSIONS = *ALL
All save versions of a job variable are output.
OPERATION-CONTROL =
Enables the user to define a number of parameters which are relevant for the execution of the restore run.
OPERATION-CONTROL = *STD
The default values of the operands described below apply.
OPERATION-CONTROL = *PARAMETERS(...)
The operands controlling the restore run can be modified as follows:
REQUEST-NAME = *STD / <name 1..8>
Request name that can be used in the HSMS request management statements (DELETE-REQUESTS, RESTART-REQUESTS and SHOW-REQUESTS) to refer to this request. The name is extended internally by a prefix derived from the user ID (or SYSHSMS for the HSMS administrator) and a suffix in the form of a time stamp. Unless otherwise specified, the request name is formed by the short code “RSF#” and the TSN of the calling user task yyyy as follows: RSF#yyyy.
REQUEST-DESCRIPTOR = *NONE / <text 1..60>
It is possible to enter any text that describes the request in more detail.
This text is displayed at the operator console when the request is started. The text can be output using the HSMS statement SHOW-REQUESTS.
EXPRESS-REQUEST = *NO / *YES
This operand is only available to the HSMS administrator.
Determines whether tape access is to take place during the sessions defined for express requests.
CONTROL-JV = *NONE / <filename 1..54 without-gen-vers>
Specifies the name of a job variable that HSMS supplies with various values corresponding to important actions performed by HSMS/ARCHIVE.
The nonprivileged caller must be owner or co-owner of this job variable. The user issuing the request can query the job variable to obtain an overview of the current processing status. How to use the job variable is described in detail in the “HSMS Vol. 1” manual [1] in the section “Job variable for request monitoring”.
WAIT-FOR-COMPLETION = *NO / *YES
Specifies whether the user wishes to wait until processing of his or her request has been completed (synchronous processing) or whether control is to be returned to the user after the validity of the HSMS statement has been checked (asynchronous processing).
The maximum wait times for batch tasks and interactive tasks are different and are determined by preset global HSMS parameters.
Interactive tasks are permitted to carry out synchronous HSMS statement processing during tape sessions only.
PARALLEL-RUNS = *STD / <integer 1..16>
This operand is only significant if you are working at storage level S2. It specifies the number of save tasks (ARCHIVE subtasks) running in parallel.
There must be two tape devices available for each task.
Unless otherwise specified, the preset value from the archive definition applies.
For further information on parallel processing, see the “HSMS Vol. 1” manual [1].
WRITE-CHECKPOINTS = *STD / *YES / *NO
This operand is only available to the HSMS administrator.
Defines whether any checkpoints are to be written to the ARCHIVE checkpoint file during processing; these checkpoints permit a request to be restarted following an interrupt (INTERRUPTED state).
Unless otherwise specified, the preset value from the archive definition applies.
OPERATOR-INTERACTION = *STD / *NOT-ALLOWED / *ALLOWED
This operand is only available to the HSMS administrator.
Determines whether messages requiring an operator response are to be output at the console (*ALLOWED) or not (*NOT-ALLOWED). If *NOT-ALLOWED applies, HSMS performs default handling (see the description of the PARAM statement in the “ARCHIVE” manual [2]).
Unless otherwise specified, the default value from the archive definition applies.
TAPE-CONTROL =
This operand is only available to the HSMS administrator.
Defines the parameters which are relevant for restoring files from tape.
TAPE-CONTROL = *STD
The preset values from the definition of the archive from which the files are to be restored apply.
TAPE-CONTROL = *PARAMETERS(...)
The operands relevant to restoring from tape can be modified as follows:
UNLOAD-TAPE = *STD / *YES / *NO
Specifies whether or not tapes are to be unloaded after processing.The preset value from the archive definition applies by default.
It is possible that HSMS will ignore the value of this operand to avoid irrational processing of tapes, for example, to avoid unloading a tape several times while rewinding it.
PERFORMANCE-ANALYSIS =
Specifies whether a statistics file is to be produced for each ARCHIVE subtask. ARCHIVE writes a new line to this statistics file:
when it opens a save file ARCHIVE.SAVE.FILE.
when it closes this save file.
whenever it begins saving or restoring a new file.
every 2 seconds while it is saving/restoring.
This gives a detailed overview of the ARCHIVE activities taking place during the save and restore operations.
PERFORMANCE-ANALYSIS = *NO
No statistics file is to be produced.
PERFORMANCE-ANALYSIS = *YES(...)
A statistics file is to be produced for each ARCHIVE subtask.
SEPARATOR = ; / <c-string 1..1>
Character that is inserted between the different fields in the statistics files. This enables programs such as EXCEL or LOTUS to differentiate the different fields.The default value is “ ; ”. This corresponds to the EXCEL default setting.
REPORT =
Serves to define whether a report is to be output for this restore request and to determine the scope of this report.
REPORT = *SUMMARY
A summary of the results of the restore request, including any error messages, is to be output.
REPORT = *RESTORED-FILES
A report is to be output, including a list of all files actually restored.
REPORT = *FULL
A report is to be output, including a list of all files which should have been restored but were not due to certain reasons.
REPORT = *NONE
No report is to be output.
OUTPUT =
Specifies where the report is to be output.
OUTPUT = *STD
The output destination of the report is determined by the default value that is defined by the global HSMS parameter OUTPUT.
OUTPUT = *PRINTER
The report for this restore request is to be printed.
OUTPUT = *NONE
No report is output. Nevertheless the report is available as a pdf file via the SE manager application Backup Monitoring, if the monitoring is activated in the global HSMS parameters.
OUTPUT = *MAIL
The report for this restore request is sent as an email attachment to the address which is entered in the caller’s user entry. If it is not possible to send the report by email, it is printed out.
OUTPUT = *LIBRARY-ELEMENT(...)
The report for this restore request is edited and output to the specified PLAM library element (type P). If this is not possible, the report is printed out.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the element. A type P element is created with a version which contains the user ID plus the date and time.
OUTPUT = <filename 1..54 without-gen-vers>
The report for this restore request is to be edited and written to the specified file.If the file already exists, the following applies:
if it is a non-empty SAM file, it is continued
if not, the report is printed.
For nonprivileged callers the report files must be under the user’s own user ID. If not, co-ownership is a prerequisite.
Dialog selection when restoring files
//RESTORE-FILES ...,DIALOG-FILE-SELECT=*YES,...
RESTORE-FILES : DIALOG-FILE-SELECT SHOW-FILE-VERSIONS = @@@@@@@@@@
#FILES = @@@@@@@@@@
ENVIRONMENT = @@@@@@@@ ARCHIVE-NAME = @@@@@@@@@@@@@@@@@@@@@@
SV-NAME = @@@@@@@@ SV-DATE = @@@@@@@@@ @@@@@@@@ @@@@@@@@
--------------------------------------------------------------------------------
M FILE-NAME VERS S-DATE S-TIME S
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
--------------------------------------------------------------------------------
NEXT-PAGE : (+,-,++,--, E, 'STRING') MARK : (A: ALL, N: NONE)
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Key:
Column | Values | Meaning |
M | Mark column (mark character = file is selected, blank = file is not selected) | |
FILE-NAME | Path name of the file | |
VERS | Version of the file at the time it was saved | |
S-DATE | Date of the save of this file | |
S-TIME | Time of the save of this file in the format | |
S | Indicates whether a file with this name already exists: | |
Y |
| |
N |
|
Note
With files which were saved as CNS in the incremental backup but can no longer be restored because the full backup is missing, the character string “RESTORE FAILS” is output instead of the values for S-Date and S-Time.
Dialog selection when restoring job variables
//RESTORE-FILES ...,DIALOG-JV-SELECT=*YES,...
RESTORE-FILES : DIALOG-JV-SELECT SHOW-JV-VERSIONS = @@@@@@@@@@
#JVS = @@@@@@@@@@
ENVIRONMENT = @@@@@@@@ ARCHIVE-NAME = @@@@@@@@@@@@@@@@@@@@@@
SV-NAME = @@@@@@@@ SV-DATE = @@@@@@@@@ @@@@@@@@ @@@@@@@@
--------------------------------------------------------------------------------
M JV-NAME VERS S-DATE S-TIME S
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @
--------------------------------------------------------------------------------
NEXT-PAGE : (+,-,++,--, E, 'STRING') MARK : (A: ALL, N: NONE)
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Key:
Column | Values | Meaning |
M | Mark column (mark character = job variable is selected, blank = job variable is not selected) | |
JV-NAME | Path name of the job variable | |
VERS | Version of the job variable at the time it was saved | |
S-DATE | Date of the backup of this job variable | |
S-TIME | Time of the backup of this job variable in the format | |
S | Indicates whether a job variable with this name already exists: | |
Y |
| |
N |
|
Dialog selection when restoring files from version backup archive
//RESTORE-FILES ...,DIALOG-FILE-SELECT=*YES,...
RESTORE-FILES : DIALOG-FILE-SELECT SHOW-FILE-VERSIONS = @@@@@@@@@@ #FILES = @@@@@@@@@@ ARCHIVE-NAME = @@@@@@@@@@@@@@@@@@@@@@ ENVIRONMENT = @@@@@@@@@@@@@@ SV-DATE = @@@@@@@@@ @@@@@@@@ @@@@@@@@ SV-NAME = @@@@@@@@ TIME = @@@@@@@@ -------------------------------------------------------------------------------- M FILE-NAME VER O-DATE O-TIME S D @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@ @@@@@@@@ @@@@@@ @ @ -------------------------------------------------------------------------------- NEXT-PAGE : (+,-,++,--, E, 'STRING') MARK : (A: ALL, N: NONE) @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Key:
| Column | Values | Meaning |
|---|---|---|
M | Mark column (mark character = file is selected, blank = file is not selected) | |
FILE-NAME | Path name of the file | |
VER | Version of the file at the time it was saved | |
O-DATE | Date of the original backup of file version to version backup archive | |
O-TIME | Time of the original backup of this file version in the format hhmmss | |
S | Indicates whether a file with this name already exists: | |
Y |
| |
N |
| |
E |
| |
D | Indicates whether the file version is obsolete or whether the file was marked for deletion | |
O |
| |
D |
| |
blank |
|
Note:
If the file version is both obsolete and marked for deletion in D column value ‘D’ will be outputted.
The procedure for selecting files is described in Volume 1 of the “HSMS” manual [1].
Dialog selection when restoring files from a long-term or migration archive for a save version selection based on original dates
//RESTORE-FILES ...,SAVE-VERSION-DATE=*BY-ORIGINAL-DATE, ...,DIALOG-FILE-SELECT=*YES, ...
RESTORE-FILES : DIALOG-FILE-SELECT SHOW-FILE-VERSIONS = @@@@@@@@@@ #FILES = @@@@@@@@@@ ARCHIVE-NAME = @@@@@@@@@@@@@@@@@@@@@@ ENVIRONMENT = @@@@@@@@@@@@@@ SV-DATE = @@@@@@@@@ @@@@@@@@ @@@@@@@@ SV-NAME = @@@@@@@@ TIME = @@@@@@@@ -------------------------------------------------------------------------------- M FILE-NAME VERS O-DATE O-TIME S @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ -------------------------------------------------------------------------------- NEXT-PAGE : (+,-,++,--, E, 'STRING') MARK : (A: ALL, N: NONE) @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Key:
| Column | Values | Meaning |
|---|---|---|
M | Mark column (mark character = file is selected, blank = file is not selected) | |
FILE-NAME | Path name of the file | |
VERS | Version of the file at the time it was saved | |
O-DATE | Date of the original save of this file to long-term or migration type of archive | |
O-TIME | Time of the original save of this file in the format hhmmss | |
S | Indicates whether a file with this name already exists: | |
Y |
| |
N |
|
Dialog selection when restoring JVs from long-term archives for a save version selection based on original dates
//RESTORE-FILES ...,SAVE-VERSION-DATE=*BY-ORIGINAL-DATE, ...,DIALOG-JV-SELECT=*YES, ...
RESTORE-FILES : DIALOG-JV-SELECT SHOW-JV-VERSIONS = @@@@@@@@@@ #JVS = @@@@@@@@@@ ARCHIVE-NAME = @@@@@@@@@@@@@@@@@@@@@@ ENVIRONMENT = @@@@@@@@@@@@@@ SV-DATE = @@@@@@@@@ @@@@@@@@ @@@@@@@@ SV-NAME = @@@@@@@@ TIME = @@@@@@@@ -------------------------------------------------------------------------------- M JV-NAME VERS O-DATE O-TIME S @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@ @@@@@@@@ @@@@@@ @ -------------------------------------------------------------------------------- NEXT-PAGE : (+,-,++,--, E, 'STRING') MARK : (A: ALL, N: NONE) @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Key:
| Column | Values | Meaning |
|---|---|---|
M | Mark column (mark character = job variable is selected, blank = job variable is not selected) | |
JV-NAME | Path name of the job variable | |
VERS | Version of the job variable at the time it was saved | |
O-DATE | Date of the original save of this job variable to long-term archives | |
O-TIME | Time of the original save of this job variable in the format hhmmss | |
S | Indicates whether a job variable with this name already exists: | |
Y |
| |
N |
|
Examples
A nonprivileged user restores an inadvertently deleted file using HSMS default values; the TSN is 2345
//RESTORE-FILES FILE-NAMES=file.1
The file FILE.1 under the user’s ID and the default catalog ID is restored from the default system backup archive (*SYSBACKUP).
The file FILE.1 is restored to the volume (public volume or private disk) from which it was backed up, retaining its original name.
All save versions are searched for the file, but the file is restored only from the most recent save version in which it is contained. In other words: the current state of the file is restored.
The request is given the name RSF#2345.
The request is processed asynchronously.
Depending on the global HSMS parameter OUTPUT a summary report is printed or sent as an email attachment.
The HSMS administrator restores a previously edited archived file from the long-term system archive, using a prefix for another user ID; his TSN is 1EWW
//RESTORE-FILES FILE-NAMES=$test1.file.2, - // NEW-FILE-NAMES=*BY-RULE(NEW-USER-ID=test2,PREFIX=arch), - // ARCHIVE-NAME=*SYSARCHIVE
The file $TEST1.FILE.2 is restored from the default long-term system archive.
The file is renamed as $TEST2.ARCH.FILE.2 and restored under the default catalog ID for TEST2.
The request is given the name RSF#1EWW.
The request is processed asynchronously.
Depending on the global HSMS parameter OUTPUT a summary report is printed or sent as an email attachment.
Examples for version backup archives
The following backups have been processed (with //BACKUP-FILE-VERSIONS):
Monday, 2018-05-07 | SVID1 |
Tuesday, 2018-05-08 | SVID2 |
Wednesday, 2018-05-09 | SVID3 |
Thursday, 2018-05-10 | SVID4 |
The following table shows the existing SVIDs and the versions of the files that are saved in them:
SVID1 | SVID2 | SVID3 | SVID4 | |
|---|---|---|---|---|
File.1 | 1 | 2 | 3 | 4 |
File.2 | 1 | 2 | 3 | |
File.3 | 1 | |||
File.4 | 3 | |||
File.5 | 1 |
The highlighted file versions are obsolete, as NUMBER-OF-BACKUP-VERS=2 was specified for all files.
On Friday, 2018-05-11 the reorganization is processed:
//REORGANIZE-VERSION-BACKUP … SAVE-FILE-ID = *ALL
During the reorganization new SVIDs are created (the SVIDs in brackets are the original SVIDs) :
SVID5 | SVID6 | SVID7 | SVID8 | |
|---|---|---|---|---|
File.1 | 3(SVID3) | 4(SVID4) | ||
File.2 | 2(SVID3) | 3(SVID4) | ||
File.3 | 1(SVID1) | |||
File.4 | 3(SVID2) | |||
File.5 | 1(SVID4) |
On Saturday 2018-05-12 two //BACKUP-FILE-VERSIONS runs have been done at 12:13:14 and 15:16:17 (the SVIDs in brackets are the original SVIDs):
SVID5 | SVID6 | SVID7 | SVID8 | SVID9 | SVID10 | |
|---|---|---|---|---|---|---|
File.1 | 3(SVID3) | 4(SVID4) | 5 | |||
File.2 | 2(SVID3) | 3(SVID4) | 4 | |||
File.3 | 1(SVID1) | 2 | ||||
File.4 | 3(SVID2) | 4 | ||||
File.5 | 1(SVID4) | 2 |
If in a reorganization run not all save files are selected for reorganization the situation may appear that some older file versions are written into a newer SVID. Older SVID or file version pass newer ones.
Suppose the following statement is processed on 2018-05-13:
//REORGANIZE-VERSION-BACKUP ... SAVE-FILE-ID = *BY-ATTRIBUTES(CREATED-BEFORE = 2018-05-11)
During the reorganization run new SVIDs will be created:
SVID9 | SVID10 | SVID11 | SVID12 | SVID13 | |
|---|---|---|---|---|---|
File.1 | 5 | 4(SVID4) | |||
File.2 | 4 | 3(SVID4) | |||
File.3 | 2 | 1(SVID1) | |||
File.4 | 4 | 3(SVID2) | |||
File.5 | 2 | 1(SVID4) |
Restore with default parameters
//RESTORE-FILES ... SELECT-SAVE-VERSIONS=*STD
For version backup archive the most recent file version will be restored (the restored versions are highlighted):
Restore with selection
//RESTORE-FILES ... SELECT-SAVE-VERSIONS=*BY-ATTR(SAVE-VERSION-DATE = *BY-ORIGINAL-DATE(CREATED-BEFORE = 2018-05-16(TIME = 12:00:00), CREATED-AFTER=2018-05-09))
The original SVIDs themselves are considered only. For example, original SVID4 was created on 2018-05-10 and thus corresponds selection criteria, while original SVID1 created on 2018-05-07 does not (despite its copy SVID11 corresponds the range). No file versions restored from SVID4, because there are more recent file versions in SVID9 and SVID10 which also correspond the selection criteria.
The highlighted versions are restored:
SVID9 | SVID10 | SVID11 | SVID12 | SVID13 | |
|---|---|---|---|---|---|
File.1 | 5(SVID10) | 4(SVID4) | |||
File.2 | 4(SVID9) | 3(SVID4) | |||
File.3 | 2(SVID10) | 1(SVID1) | |||
File.4 | 4(SVID9) | 3(SVID2) | |||
File.5 | 2(SVID9) | 1(SVID4) |
//RESTORE-FILES ...SELECT-SAVE-VERSIONS=*BY-ATTR(SAVE-VERSION-DATE = *BY-ORIGINAL-DATE(CREATED-BEFORE = 2018-05-12(TIME = 15:00:00),CREATED-AFTER=2018-05-09))
The original SVIDs themselves are considered only. Original SVID4 was created on 2018-05-10 and thus corresponds to the selection criteria, while original SVID1 created on 2018-05-07 does not. Original SVID10 also does not correspond to the criteria:
SVID9 | SVID10 | SVID11 | SVID12 | SVID13 | |
|---|---|---|---|---|---|
File.1 | 5(SVID10) | 4(SVID4) | |||
File.2 | 4(SVID9) | 3(SVID4) | |||
File.3 | 2(SVID10) | 1(SVID1) | |||
File.4 | 4(SVID9) | 5(SVID10) | 3(SVID2) | ||
File.5 | 2(SVID9) |
//RESTORE-FILES ... SELECT-SAVE-VERSIONS=*BY-ATTR(SAVE-VERSION-DATE=*BY-ORIGINAL-DATE(CREATED-BEFORE=*LATEST-DATE,CREATED-AFTER=*SAME-AS-BEFORE))
In the example, the highest original SVID is SVID10 (SVID11,SVID12,SVID13 are not original for any file). So, the restore of only those files which originally have been saved within SVID10 will be performed:
The highlighted file version are restored.
SVID9 | SVID10 | SVID11 | SVID12 | SVID13 | |
|---|---|---|---|---|---|
File.1 | 5(SVID10) | 4(SVID4) | |||
File.2 | 4(SVID9) | 3(SVID4) | |||
File.3 | 2(SVID10) | 1(SVID1) | |||
File.4 | 4(SVID9) | 5(SVID10) | 3(SVID2) | ||
File.5 | 2(SVID9) |
File.2 and File.5 are not restored, because they have not been saved within the highest original SVID.
//RESTORE-FILES ... SELECT-SAVE-VERSIONS=*BY-ATTR(SAVE-VERSION-DATE=*BY-ORIGINAL-DATE(CREATED-BEFORE=2018-05-12(TIME=15:16:17),CREATED-AFTER=*SAME-AS-BEFORE))
The original save versions (SVIDs) themselves are considered only. Original SVID10 was created on 2018-05-12 at 15:16:17 and thus corresponds to the selection criteria. Only file versions saved in this SVID will be restored (highlighted file versions).
SVID9 | SVID10 | SVID11 | SVID12 | SVID13 | |
|---|---|---|---|---|---|
File.1 | 5(SVID10) | 4(SVID4) | |||
File.2 | 4(SVID9) | 3(SVID4) | |||
File.3 | 2(SVID10) | 1(SVID1) | |||
File.4 | 4(SVID9) | 5(SVID10) | 3(SVID2) | ||
File.5 | 2(SVID9) |
File.2 and File.5 are not restored, because they have not been saved within the original SVID10.