RESTORE-NODE-FILES Restore node files

This statement is used for restoring node files from a node backup or long-term archive to the processing level. The node files that have been saved from a BS2000-UFS (POSIX) or node S0 can be renamed, reorganized and written to different node S0s during the restore. It is possible to specify individual save files and save versions from which the node files 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-NODE-FILES

Alias: RNF

PATH-NAMES = *OWN / *ALL / *SELECTED / *FROM-FILE(...) / *FROM-LIBRARY-ELEMENT(...) /
						*PATH-NAME(...)
	*FROM-FILE(...)
		|	LIST-FILE-NAME = <filename 1..54 without-gen-vers>
	*FROM-LIBRARY-ELEMENT(...)
		|	LIBRARY = <filename 1..54 without-gen-vers>
		|	,ELEMENT = <composed-name 1..64 with-under>
	*PATH-NAME(...)
		|	PATH = <posix-pathname 1..1023 with-wild>
		|	,NODE-ID*P) = *BS2000-UFS / *ALL / <posix-filename 1..48 with-wild>
,EXCEPT-PATH-NAMES = *NONE / *FROM-FILE(...) / *FROM-LIBRARY-ELEMENT(...) / *PATH-NAME(...)
	*FROM-FILE(...)
		|	LIST-FILE-NAME = <filename 1..54 without-gen-vers>
	*FROM-LIBRARY-ELEMENT(...)
		|	LIBRARY = <filename 1..54 without-gen-vers>
		|	,ELEMENT = <composed-name 1..64 with-under>
	*PATH-NAME(...)
		|	PATH = <posix-pathname 1..1023 with-wild>
		|	,NODE-ID*P) = *BS2000-UFS / *ALL / <posix-filename 1..48 with-wild>
,ENVIRONMENT = *NODE-STD / *SINGLE-FEATURE / *SYSTEM-MANAGED(...)
	*SYSTEM-MANAGED(...)
		|	CATALOG-ID = <cat-id>
,SELECTION-BOUNDARY = *SPECIFIED-PATHS / *ALL-FILE-SYSTEMS
,NEW-PATH-NAMES = *SAME / *BY-RULE(...)
	*BY-RULE(...)
		|	NEW-NODE-ID*P) = *SAME / *BS2000-UFS / <posix-filename 1..48 without-wild>
		|	,CHANGE-PATH = *SAME / *PARAMETERS(...)
		|		*PARAMETERS(...)
		|			|	OLD-PATH = *NONE / <posix-pathname 1..1022 without-wild>
		|			|	,NEW-PATH = *NONE / <posix-pathname 1..1022 without-wild>
		|	,PREFIX = *NONE / <posix-filename 1..254 without-wild>
		|	,SUFFIX = *NONE / <posix-filename 1..254 without-wild>
,REPLACE-FILES = *NO / *YES(...)
	*YES(...)
PROTECTION-RESPECTED = *ALL / *NONE*P)
,ARCHIVE-NAME = *SYSNODEBACKUP / *SYSNODEARCHIVE /
							<filename 1..22 without-cat-gen-vers>
,SELECT-SAVE-VERSIONS = *ALL / *LATEST(...) / *BY-ATTRIBUTES(...)
	*LATEST(...)
		|	DAY-INTERVAL = *NO / *YES
		|	,CREATED-AFTER = *EARLIEST-DATE / <date with-compl> / <integer -99999..0 days>
	*BY-ATTRIBUTES(...)
		|	SAVE-VERSION-NAME = *ANY / <name 1..8>
		|	,SAVE-VERSION-DATE = *LATEST / <date with-compl>(...) / *INTERVAL(...) /
		|								*BY-ORIGINAL-DATE(...)
		|		<date with-compl>(...)
		|			|	TIME = 23:59:59 / <time>
		|		*INTERVAL(...)
		|			|	CREATED-BEFORE = *LATEST-DATE / <date with-compl>(...) /
		|			|						<integer -99999..0 days>(...)
		|			|		<date with-compl>(...)
		|			|			|	TIME = 23:59:59 / <time>
		|			|		<integer -99999..0 days>(...)
		|			|			|	TIME = 23:59:59 / <time>
		|			|	,CREATED-AFTER = *EARLIEST-DATE / <date with-compl> /
		|			|						<integer -99999..0 days>
		|		*BY-ORIGINAL-DATE(...)
		|			|	CREATED-BEFORE = *LATEST-DATE / <date with-compl>(...) /
		|			|						<integer -99999..0 days>(...)
		|			|		<date with-compl>(...)
		|			|			|	TIME = 23:59:59 / <time>
		|			|		<integer -99999..0 days>(...)
		|			|			|	TIME = 23:59:59 / <time>
		|			|	,CREATED-AFTER = *EARLIEST-DATE / *SAME-AS-BEFORE / <date with-compl> /
		|			|						<integer -99999..0 days>
,OPERATION-CONTROL = *STD / *PARAMETERS(...)
	*PARAMETERS(...)
		|	REQUEST-NAME = *STD / <name 1..8>
		|	,REQUEST-DESCRIPTOR = *NONE / <text 1..60>
		|	,EXPRESS-REQUEST*P) = *NO / *YES
		|	,CONTROL-JV= *NONE / <filename 1..54 without-gen-vers>
		|	,WAIT-FOR-COMPLETION = *NO / *YES
		|	,PARALLEL-RUNS = *STD / <integer 1..16>
		|	,PRE-POST-PROCESSING = *NO / *YES
		|	,TAPE-CONTROL*P) = *STD / *PARAMETERS(...)
		|		*PARAMETERS(...)
		|			|	UNLOAD-TAPE = *STD / *YES / *NO
		|	,PERFORMANCE-ANALYSIS = *NO / *YES(...)
		|		*YES(...)
		|			|	SEPARATOR = ; / <c-string 1..1>
		|	,REPORT = *SUMMARY / *RESTORED-FILES / *FULL / *NONE
		|	,OUTPUT = *STD / *PRINTER / *NONE / *MAIL / *LIBRARY-ELEMENT(...) / <filename 1..54 without-gen-vers>
		|		*LIBRARY-ELEMENT(...)
		|			|	LIBRARY = <filename 1..54 without-gen-vers>
		|			|	,ELEMENT = <composed-name 1..64 with-under>

^*P) Privileged operand or operand value

PATH-NAMES =
Serves to specify the path names of the node files to be restored to the BS2000-UFS or node S0. Specification of this operand is mandatory.

The node S0 to which a node file is to be restored must be available for the restoration to be successful.
If node files from more than one node S0 are specified and are to be restored from a default system archive, then the same default system archive must be assigned to all these node S0s. Otherwise, the HSMS statement will be rejected. To prevent this you should only specify files from one node S0 for each restore request.

The option of restoring the node files of other users or node files of remote node S0s is restricted to the HSMS administrator.
More information about path names can be found in the “HSMS Vol. 1” manual [1].

PATH-NAMES = *OWN
*OWN is equivalent to “ / ” (root), subject to the restriction that the user must be the owner of all the node files.

Meaning for the HSMS administrator:
The system restores all node files and directories belonging to the user ID root which reside on the central BS2000-UFS.

Meaning for nonprivileged users:
The system restores all node files and directories belonging to the user which reside on the central BS2000-UFS.
The selection is made from the directory.

PATH-NAMES = *ALL
Meaning for the HSMS administrator:
The system is to restore all node files that reside at save time on the central BS2000-UFS and on a remote node S0 which is currently under HSMS control in the specified environment.
The selection is made from the directory file for node files.

Meaning for the nonprivileged user:
The system is to restore all node files that reside on the central BS2000-UFS in the specified environment and which meet the following conditions:

• If the node files are to be restored from a long-term archive, the nonprivileged user must have read access to the files.

• If the node files are to be restored from a backup archive, the nonprivileged user must be the owner of the files.

Node files belonging other users are restored from a long-term archive only if they no longer exist at the destination. This selection is made from the directory file for node files in the specified environment.
*ALL is equivalent to “ / ” (root), subject to the restrictions listed above.

PATH-NAMES = *SELECTED
The path names of the node 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-NODE-FILES.

PATH-NAMES = *FROM-FILE(...)
The path names of the node 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.

LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.

PATH-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the node files which are to be restored are taken from a PLAM library element (type S). The library element contains one path name per record.

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.

PATH-NAMES = *PATH-NAME(...)
The path name of the file to be restored is specified directly.

The path name may contain wildcards. Wildcards are replaced in accordance with the file names listed in the directory file.

Restore runs are executed more quickly if you use fully qualified file names.

PATH = <posix-pathname 1..1023 with-wild>
Path name of the node file.

NODE-ID =
This operand is only available to the HSMS administrator. Original location of the node file to be restored.

NODE-ID = *BS2000-UFS
The node file resided on the local BS2000-UFS.

NODE-ID = *ALL
The node file is sought on the central BS2000-UFSs and on all decentralized node S0s under HSMS control.

NODE-ID = <posix-filename 1..48 with-wild>
Name of the node S0 on which the node file resides.

EXCEPT-PATH-NAMES =
Serves to specify node files that are to be excluded from restore.

EXCEPT-PATH-NAMES = *NONE
All node files specified with the PATH-NAMES operand are to be restored.

EXCEPT-PATH-NAMES = *FROM-FILE(...)
The path names of the node 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. This list file must be a SAM file with variable-length records containing one path name per record.

LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.

EXCEPT-PATH-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the node 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.

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-PATH-NAMES = *PATH-NAME(...)
The path name of the node file to be excluded from restoration is specified directly. The first character of the path name must not be a hyphen.

The path name may contain wildcards. Wildcards are replaced in accordance with the file names listed in the directory file.

PATH = <posix-pathname 1..1023 with-wild>
Path name of the node file.

NODE-ID =
This operand is only available to the HSMS administrator.
Original location of the node file to be excluded from restoration.

NODE-ID = *BS2000-UFS
The node file resided on the local BS2000-UFS.

NODE-ID = *ALL
The node file is sought on the central BS2000-UFSs and on all decentralized node S0s under HSMS control.

NODE-ID = <posix-filename 1..48 with-wild>
Name of the node S0 which is to be excluded.

ENVIRONMENT =
HSMS environment in which the statement is valid.

ENVIRONMENT = *NODE-STD
The environment is derived from either:

• the operand PATH-NAMES=*PATH-NAME(NODE-ID) or

• the list of node IDs which is referenced in the file using the operand PATH-NAMES=*FROM-FILE(LIST-FILE-NAME).

For a workstation, this is the environment in which the HSMS statement MODIFY-NODE-PARAMETERS is performed.

For a privileged user under BS2000-UFS, it is a SINGLE-FEATURE environment; for a nonprivileged user *NODE-STD takes the value of the environment in which the home directory of the user is defined.

If the affected node files are located in different environments, the statement is rejected with message HSM0530.

ENVIRONMENT = *SINGLE-FEATURE
The statement is valid in the SF environment.

ENVIRONMENT = *SYSTEM-MANAGED(...)
The statement is valid in the SM pubset environment.

CATALOG-ID = <cat-id>
Catalog ID of the SM pubset for which the statement is valid.

SELECTION-BOUNDARY =
Defines which part of the node file tree is used for file name expansion.

SELECTION-BOUNDARY = *SPECIFIED-PATHS
All node files and directories specified with the PATH-NAMES operand will be processed.For directories, only their inodes will be included. Any node files and directories subordinated to a directory to be processed will be ignored.

SELECTION-BOUNDARY = *ALL-FILE-SYSTEMS
All node files and directories specified with the PATH-NAMES operand will be processed.Any node files and directories subordinated to a directory to be processed will be included in the selection. Node files and directories will be selected from all levels of the file tree.

NEW-PATH-NAMES =
The node files can be renamed before being restored. The new path names must satisfy the following requirements:

• The new path name conforms to the UNIX conventions governing names.

• The user entering the restore request has access to this path.

• The total length of the path does not exceed 1024 characters.

NEW-PATH-NAMES = *SAME
The node files are to be restored under their original names.

NEW-PATH-NAMES = *BY-RULE(...)
The node files are to be renamed using a common rule.

NEW-NODE-ID = *SAME / *BS2000-UFS / <posix-filename 1..48 without-wild>
This operand is only available to the HSMS administrator.
The node files may be restored under a different node S0, which is specified without a colon.
Unless otherwise specified, the node files are restored under their original node S0. The explicit specification of a new node S0 is only possible if the original node S0 is specified in the PATH-NAMES operand (specification different to *ALL or *PATH-NAME(...,NODE-ID=*ALL).

CHANGE-PATH =
The node files may be restored under a different path name.

CHANGE-PATH = *SAME
The node files are to be restored under their original path name.

CHANGE-PATH = *PARAMETERS(...)
The restored node files are mounted on the file system under a different path name.

OLD-PATH = *NONE / <posix-pathname 1..1022 without-wild>
Absolute path name to be replaced during the restore.

Specification of *NONE causes the new path name to be prefixed to all node file names found in the archive directory.

NEW-PATH = *SAME / <posix-pathname 1..1022 without-wild>
Absolute path name to replace the old path name during the restore.
Specification of *SAME causes the old path name of the file to be retained.

The specified path name, if any, must exist in the file system and must be available to the user issuing the restore request.

The path names specified for OLD-PATH or NEW-PATH may or may not end with a slash (/). Both path names must match in this respect, i.e. both end with a slash, or both end without a slash.

PREFIX = *NONE / <posix-filename 1..254 without-wild>
The specified prefix is added to the names of the restored node files.

SUFFIX = *NONE / <posix-filename 1..254 without-wild>
The specified suffix is added to the names of the restored node files.

REPLACE-FILES = *NO / *YES(...)
Determines whether existing node files are to be overwritten during the restore.

REPLACE-FILES = *YES(...)
Existing node files are to be overwritten. In addition, the user can specify if and to what extent the file protection attributes of node files, if any, are to be respected:

PROTECTION-RESPECTED = *ALL
Restricts overwriting to node files that permit write access.
This operand value is set automatically for nonprivileged users if node files are to be overwritten at the destination.

PROTECTION-RESPECTED = *NONE
This operand value is only available to the HSMS administrator.
All node files are to be overwritten, irrespective of their protection attributes.

ARCHIVE-NAME =
Name of the archive from which the node files are to be restored.

If a default system archive is specified, it must already exist. For restoration to more than one node S0, the default system archive must be unequivocally assigned to all these node S0s.

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 directory of the archive.

ARCHIVE-NAME = *SYSNODEBACKUP
The node files are to be restored from the default system backup archive assigned to the environment.

ARCHIVE-NAME = *SYSNODEARCHIVE
The node files are to be restored from the default long-term system archive assigned to the environment.

ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>
The node files are to be restored from the specified archive.

SELECT-SAVE-VERSIONS =
Serves to define the save versions to be used for restoration.
The most recent version of each of the node files specified via PATH-NAMES is selected from all the save versions specified for restoration.

SELECT-SAVE-VERSIONS = *ALL
All save versions are to be selected for the restore operation. The specified node files are in each case restored from the most recent save version in which they are contained.

Explicit specification of PATH-NAMES=*ALL(*OWN) in conjunction with the default value SELECT-SAVE-VERSIONS=*ALL causes the most recent versions of all node files that were ever saved in the specified archive to be restored.
*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 = *LATEST(...)
Only the most recently created save version is to be used for the restore operation.
When restoring from a NODEBACKUP archive, this means that of all the node files specified only those will be restored which were actually saved or registered as “cataloged-not-saved” (CNS) during the last backup run.

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-NODE-FILES.

CREATED-AFTER = *EARLIEST-DATE
Files which were marked as “cataloged-not-saved” (CNS) during the last node 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.

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

SAVE-VERSION-DATE = <date with-compl>(...)
Selects the last save version created on or before the specified date for restoration.

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(...)
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 / <date with-compl>(...) / <integer -99999..0 days>(...)
The save versions are to be selected irrespective of whether they were created before a specific date.

CREATED-BEFORE = <date with-compl>(...) / <integer -99999..0 days>(...)
Restricts selection to save versions created on or before the specified date. 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 form 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 the save versions of a migration or long-term archive.
You can select the save versions of a migration or long-term archive via their creation date (see “Copying save files” in the manual “HSMS Volume 1” [1]). The backup 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.

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.

OPERATION-CONTROL =
Allows you to define 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 “RNF#” and the TSN of the calling user task yyyy as follows: RNF#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 one tape device 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].

PRE-POST-PROCESSING =
Indicates whether preprocessing or postprocessing is to be activated on a remote workstation.

PRE-POST-PROCESSING = *NO
No preprocessing or postprocessing is to be activated on a remote workstation, even if this is actually defined on the workstation.

PRE-POST-PROCESSING = *YES
Preprocessing or postprocessing is to be activated on a remote workstation if this is actually defined on the workstation.

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 unless otherwise specified.

It is possible that HSMS ignores 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 full report is to be output, including a list of all node files actually restored.

REPORT = *FULL
A full report is to be output, including a list of all node files which should have been restored but were not due to an error.

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. 

Notes

• The following applies when restoring from a save file created by means of the HSMS statement BACKUP-NODE-FILES with the operand SELECT-FILES=*ALL-FILES(FROM=*LATEST-BACKUPS-OR-S0):

  • An interruption of the restore run (request state INTERRUPTED) may result in some nodes (directories) having attributes that differ from the ones they had at backup time. The nodes have the status “in processing”, their owner is user ID root (user number=0). As a remedy, the restore run has to be restarted; as an alternative, a RESTART-REQUESTS statements can be performed.

  • If only part of a previously saved file tree is restored and the parent directory of this part no longer exists on the processing level at restore time, HSMS has to replace the parent directory. Its attributes are modified and user ID root becomes its owner.

• Some of the attributes of the files and directories will be modified by the RESTORE-NODE-FILES statement, as indicated in the tables below:

  • Attributes after restoring a save version created by means of the HSMS statement BACKUP-NODE-FILES:

    Attribute Object	Date of last access	Date of last modification	Date of last modification of the inode	Other attributes
    Files	as saved	as saved	new	as saved
    Directories	new	new	new	as saved

  • Attributes after restoring a save version created by means of the HSMS statement ARCHIVE-NODE-FILES:

    Attribute Object	Date of last access	Date of last modification	Date of last modification of the inode	Other attributes
    Files	new	new	new	as saved
    Directories	new	new	new	as saved

• The REPLACE-FILES operand is only evaluated in the case of files. Directories are always overwritten irrespective of the value of the REPLACE-FILES operand. 

Example

The HSMS administrator restores selected file trees in the local BS2000-UFS. The file trees were backed up centrally in the example of the section dealing with the BACKUP-NODE-FILES statement.

/START-HSMS
//SELECT-NODE-FILES -   ————————————————————————————————————————————————  (1) 
//   PATH-NAMES=*PATH-NAME(PATH=*,NODE-ID=*BS2000-UFS), -
//   OUTPUT=PATHNAMES.LIST
//END
/START-EDT ————————————————————————————————————————————————————————————  (2) 
@READ 'PATHNAMES.LIST'
   Delete all path names that are not to be restored
@WRITE 'PATHNAMES.LIST'
@HALT
/START-HSMS
//RESTORE-NODE-FILES -   ———————————————————————————————————————————————  (3) 
//   PATH-NAMES=*FROM-FILE(LIST-FILE-NAME=PATHNAMES.LIST), -
//   SELECTION-BOUNDARY=*SPECIFIED-PATHS, -
//   REPLACE-FILES=*YES(PROTECTION-RESPECTED=*NONE), -
//   OPERATION-CONTROL=*PARAMETERS(WAIT-FOR-COMPLETION=*YES)
//END

(1)	First, all the files of the local BS2000-UFS are selected to obtain a complete list of file names. The list of file names is output to the file PATHNAMES.LIST.
(2)	An editor such as EDT is then called to delete the path names which should not be restored from the file PATHNAMES.LIST.
(3)	All the path names still present in the file PATHNAMES.LIST are restored. Any existing files with the same path names are overwritten during the restore.