This statement restores PLAM elements from an HSMS archive. Element-by-element restoration of PLAM elements requires that when the library file was saved the element structure should also have been saved (with specification SAVE-PLAM-INFO=*YES).This is possible for backups and long-term backups.
The element names of a library stored with element structure are only maintained in the save file, not in the archive’s save directory.
When no element is specified (or ELEMENTS=*LIST-ALL-TO-REPORT is specified explicitly) the statement lists all elements of the save versions selected with their name, version and type for the specified library in the report.
All elements that are to be restored must be specified explicitly with name, version and type. The elements can be renamed. By default the restored elements are written back to the original library. The elements can also be restored to another library. In any case the library must be present and obey the normal DMS rules for access and co-ownership.
You can specify individual save versions from which the elements are to be restored. All elements specified are restored from the same status of the saved library which is specified in this way. If certain elements were not contained in this save status of the library, you must retry with different save versions.
The restart function is not supported for RESTORE-LIBRARY-ELEMENTS requests.
This statement has a different format for nonprivileged users and HSMS administrators. Privileged operands or operand values are marked with *P).
Format
RESTORE-LIBRARY-ELEMENTS | Alias: RLE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) Privileged operand or operand value
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.
LIBRARY = <filename 1..54 without-vers>
Name of the library containing the elements. The nonprivileged user must be owner or co-owner of this library.
TARGET-LIBRARY =
Specifies which library the elements should be restored in.
TARGET-LIBRARY = *SAME
The elements will be restored in the original library.
TARGET-LIBRARY = <filename 1..54 without-vers>
The elements will be restored in a target library, with the name specified. The nonprivileged caller must be owner or co-owner of this library.
ELEMENTS =
Outputs for the specified library either only a list of the elements which are contained in the specified save versions or restores the elements specified explicitly here.
ELEMENTS = *LIST-ALL-TO-REPORT
For the specified library all elements of the selected save versions are output in the report with element name, version and type. Output always takes place with the setting REPORT=*FULL. Other specifications in the REPORT operand are ignored. The save files are read to obtain the element information from the save information (i.e. with tape processing here, too).
ELEMENTS = list-poss(50): *ELEMENT(...)
Determines the elements which are to be restored in the target library. An element is uniquely determined by element name, version and type (see the following operands). If several elements are to be restored, you can either use wildcards in the name parts or specify a maximum of 50 elements in a list. In the list all elements must be fully specified, in other words no wildcards may be used in the name parts.
ELEMENT = <composed-name 1..64 with-underscore with-wild(132)>
Name of the element or elements.
VERSION = *HIGHEST-EXISTING / *ALL / *UPPER-LIMIT /
<composed-name 1..24 with-underscore with wild(52)>
Version of the element or elements
TYPE = <alphanum-name 1..8 with-wild(20)>
Type of the element or elements
NEW-ELEMENT-NAMES =
You can rename the library elements before restoring them to the library. The total length must not exceed 64 characters. The new element name is formed as follows:
<prefix>.old-element-name.<suffix>
NEW-ELEMENT-NAMES = *SAME
The elements are restored under their original names.
NEW-ELEMENT-NAMES = *BY-RULE(...)
The elements are renamed on the basis of a uniform rule.
PREFIX = *NONE / <filename 1..8 without-cat-user-gen-vers>
You can add a prefix of at most 8 characters to the element name. The prefix is automatically separated from the file name by a period. You can only use characters that may also be used in element names.
SUFFIX = *NONE / <composed-name 1..8>
You can append a suffix of at most 8 characters to the element name. The suffix is automatically separated from the file name by a period. You can only use characters that may also be used in element names.
REPLACE-ELEMENTS =
Defines whether existing elements are overwritten on restore.
REPLACE-ELEMENTS = *NO
Existing elements are not overwritten on restore.
REPLACE-ELEMENTS = *YES
Existing elements are overwritten on restore.
ARCHIVE-NAME =
Defines the name of the archive in the specified environment from which the library elements are to be restored.
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.
To use an archive belonging to another nonprivileged user, you must have read permission for the archive in question (USER-ACCESS=*ALL-USERS and ACCESS=*READ) or co-ownership of the archive directory.
ARCHIVE-NAME = *SYSBACKUP
The elements are to be restored from the assigned default system backup archive in the specified environment.
ARCHIVE-NAME = *SYSVERSION
The elements are to be restored from the system version backup archive assigned to the pubset given in LIBRARY in the specified environment.
ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>
The elements 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.
In each case, the last version of the library specified with LIBRARY-NAME is restored from the specified save version
SAVE-VERSIONS=*STD
The effect of the option depends on the archive type.
For archival, backup and migration archives or their shadow 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. In some cases after reorganization it can occur that the most recent version of the file is stored in the save version which has not the highest SVID containing the file. This means the specified files will be restored from the most recent save version according to the original save version date, i.e. the most recent version of the file (it might be not in the most recent save version after reorganization).
SELECT-SAVE-VERSIONS = *ALL
The option is relevant only for backup and archival archives, their shadows and migration archives.
All save versions are used for the restore operation. The specified library is always retrieved from the last save version in which it is present.
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 last save version to be created is used for the restore operation.
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
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.
CREATED-AFTER = *EARLIEST-DATE
In the case of libraries which were marked as “cataloged-not-saved” (CNS) during the last backup, the elements are restored from the most recently created save version – irrespective of its creation date.
CREATED-AFTER = <date with-compl>
In the case of libraries which were marked as “cataloged-not-saved” (CNS) during the last backup, the elements 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.
If you have specified a save version via its name then only save versions with this name are selected if you specify 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.
The option has no sense when restoring from version backup archives and will be rejected with the following message:
HSM0050 NOT SUITABLE RESTORE STRATEGY FOR VERSION BACKUP ARCHIVES
SAVE-VERSION-DATE = *INTERVAL(...)
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.
CREATED-BEFORE = *LATEST-DATE
The save versions are to be selected irrespective of whether they were created before a specific date. An additional time field allows you to make more accurate specifications.
CREATED-BEFORE = <date with-compl>(...)
Restricts selection to save versions created on or before the specified date.
TIME = 23:59:59 / <time>
Time, in the form of hh:mm:ss
CREATED-BEFORE = <integer -99999..0 days >(...)
Restricts selection to save versions created on or before the specified relative date.
TIME = 23:59:59 / <time>
Time, in the form of 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 = <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.
The option is not applicable for version backup archives.
TIME = 23:59:59 / <time>
Selects the last save version created at or before the specified date and time for restoration.
SAVE-VERSION-DATE = *BY-ORIGINAL-DATE(...)
Only for save versions of a version backup archive.
Only original save versions are considered when selecting file versions to be restored.
CREATED-BEFORE = *LATEST-DATE
The original creation date of the save versions considered for selection has no upper limit.
CREATED-BEFORE = <date with-compl>(...) / <integer -99999..0 days > (...)
The original creation date of the save 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 save versions considered for selection has no lower limit.
CREATED-AFTER = <date with-compl> / <integer -99999..0 days >
The original creation date of the save 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 save version whose original creation date matches the date specified in the CREATED-BEFORE operand is selected.
In particular, the specification SAVE-VERSION-DATE = *BY-ORIGINAL-DATE (CREATED-BEFORE = *LATEST-DATE , CREATED-AFTER = *SAME-AS-BEFORE)means restore files with the latest original svid. So, HSMS select the highest original SVID within the whole version backup archive and then choose only those files which have been originally saved within the save version.
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 “RLE#” and the TSN of the calling user task yyyy as follows: RLE#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.
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.
You can define parameters which are relevant for restoring elements from tape.
TAPE-CONTROL = *STD
The preset values from the definition of the archive from which the elements are to be restored apply.
TAPE-CONTROL = *PARAMETERS(...)
The operands relevant to reading 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.
Note
Output always takes place with the setting REPORT=*FULL for ELEMENTS=*LIST-ALL-TO-REPORT. Any other specifications are ignored.
REPORT = *LIBRARY-ONLY
A summary of the result is to be output, including all the information about the library and any error messages.
REPORT = *RESTORED-ELEMENTS
A full report is to be output, including, in addition to the library information, a list of all elements actually restored.
REPORT = *FULL
A full report is to be output, including the library information, a list of the elements actually restored and a list of the elements which, for particular reasons, were not restored.
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.