This statement saves node files of a BS2000-UFS (POSIX) and if applicable mounted nodes S0 to a long-term archive. The node files are written to volumes of storage level S2. The files can optionally be deleted from processing level node S0 after archival. Information on tape usage (TAPE-CONTROL) and implicit deletion of obsolete backups can be set in the archive attribute.
Note
Some of the attributes of the processed files and directories will be modified by the ARCHIVE-NODE-FILES statement, as indicated in the table below:
Object | Attribute | |||
Date of last | Date of last | Date of last | Other attributes | |
Files | unmodified | unmodified | modified | unmodified |
Directories | new | unmodified | unmodified | unmodified |
This statement has different formats for nonprivileged users and HSMS administrators. Privileged operands or operand values are marked with *P).
Format
ARCHIVE-NODE-FILES | Alias: ANF | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) Privileged operand or operand value
PATH-NAMES =
Serves to specify the path names of the node files of a BS2000-UFS (POSIX) or node S0 to be archived. Specification of this operand is mandatory.
If node files from more than one node S0 are specified and are to be saved to 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 archival request.
The option of archiving the node files of remote node S0s is restricted to the HSMS administrator.
PATH-NAMES = *OWN
*OWN is equivalent to “ / ” (root), subject to the restriction that the user must be the owner of all the files.
Meaning for the HSMS administrator:
The system is to archive all node files and directories of user ID root which reside on the branch on the central BS2000-UFS that corresponds to the specified environment.
Meaning for the nonprivileged user:
The system is to archive all node files and file directories belonging to the user which reside on the branch on the central BS2000-UFS that corresponds to the specified environment.
PATH-NAMES = *ALL
Meaning for the HSMS administrator:
All node files are to be archived that reside either locally on the central BS2000-UFS or on a connected node S0 and which are located in the specified environment. *ALL is equivalent to “ / ”.
Meaning for the nonprivileged user:
All node files are to be archived that reside on the central BS2000-UFS and are located in the specified environment and to which the user has read access.
*ALL is equivalent to “ / ” (root) subject to the restriction that the user must have read access to all the files.
PATH-NAMES = *SELECTED
The path names of the node files to be archived are to be taken from a list that was compiled within the same HSMS run by means of the HSMS statement SELECT-NODE-FILES.
The path names to be processed must be contained in the specified environment.
PATH-NAMES = *FROM-FILE(...)
The path names of the node files to be archived 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.
The path names to be processed must be contained in the specified environment.
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 archived 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 node file to be archived is specified directly.
The path name may contain wildcards.
PATH = <posix-pathname 1..1023 with-wild>
Path name of the node file.
NODE-ID =
This operand is only available to the HSMS administrator.
Physical location of the node file to be archived.
NODE-ID = *BS2000-UFS
The node file resides on the central BS2000-UFS on the branch which corresponds to the specified environment.
NODE-ID = *ALL
The central BS2000-UFS and all decentral node S0s which are under HSMS control and reside in the specified environment are searched for the node file.
NODE-ID = <posix-filename 1..48 with-wild>
Name of the node S0 on which the node file resides. The node S0 which is defined with //MODIFY-NODE-PARAMETERS is mounted under the directory /HSMS/<node-id> in POSIX, and access takes place via NFS.
EXCEPT-PATH-NAMES =
Serves to specify node files that are to be excluded from archival.
EXCEPT-PATH-NAMES = *NONE
All node files specified with the PATH-NAMES operand are to be archived.
EXCEPT-PATH-NAMES = *FROM-FILE(...)
The path names of the node files which are to not be archived 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 to not be archived 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 archival is specified directly.
The path name may contain wildcards.
The first character of the path name must not be a hyphen.
PATH = <posix-pathname 1..1023 with-wild>
Path name of the node file.
NODE-ID =
This operand is only available to the HSMS administrator.
Physical location of the node file to be excluded from archival.
NODE-ID = *BS2000-UFS
The node file resides on the central BS2000-UFS.
NODE-ID = *ALL
The central BS2000-UFS and all decentral node S0s which are under HSMS control and reside in the specified environment are searched for the node file.
NODE-ID = <posix-filename 1..48 with-wild>
This operand value only exists for compatibility reasons.
ENVIRONMENT =
HSMS environment in which the statement is to be processed.
ENVIRONMENT = *NODE-STD
The environment is derived from either:
the operand PATH-NAMES=*PATH-NAME(NODE-ID) or
the list of node IDs which are referenced in the file using the operand PATH-NAMES=*FROM-FILE(LIST-FILE-NAME) or in the library element with the operand PATH-NAMES=*FROM-LIBRARY-ELEMENT(LIBRARY,ELEMENT).
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 the SINGLE-FEATURE environment; for a nonprivileged user *NODE-STD assumes 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
This statement is valid in the SF environment.
ENVIRONMENT = *SYSTEM-MANAGED(...)
The statement is valid in the specified SM pubset environment.
CATALOG-ID = <cat-id>
The 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 = *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.
SELECTION-BOUNDARY = *SPECIFIED-PATHS
All node files and directories specified with the PATH-NAMES operand will be processed.For directories, only their inode will be included. Any node files and directories subordinated to a directory to be processed will be ignored.
SELECTION-BOUNDARY = *CURRENT-FILE-SYSTEM
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 (for node files both the inode and the data will be included, for directories, only the inode).
The selection will be restricted to the current file system.
SELECTION-BOUNDARY = *ALL-LOCAL-FILE-SYSTEMS
All node files and directories are processed which are specified in the PATH-NAMES operand.
When one of the objects to be processed is a directory, the node files and directories which are located on the subordinate levels of the file tree will also be included.
The selection is limited to the UFS file system.
DELETE-FILES = *NO / *YES(...)
Defines whether the archived node files are to be deleted from the processing level after archival.
DELETE-FILES = *YES(...)
The archived node files are to be deleted from the node S0. The system administrator can restrict the deletion operation by specifying which file protection attributes of the node files are to be respected:
PROTECTION-RESPECTED = *ALL
Deletion is restricted to node files which are not write-protected.
This value is automatically preset for nonprivileged users.
PROTECTION-RESPECTED = *NONE
This operand value is only available to the HSMS administrator.
All node files which belong to the user or are not write-protected are to be deleted.
ARCHIVE-NAME = *SYSNODEARCHIVE / <filename 1..22 without-cat-gen-vers>
Name of the archive to which the node files are to be saved. The specified archive must already exist and be available for use as a long-term archive for node files.
If the archive directory is password-protected, you must enter the password beforehand via the ADD-PASSWORD command. This also applies to HSMS administrators.
To enable the nonprivileged user to use another user’s archive, either the archive must contain write access for all other users (USER-ACCESS=*ALL-USERS and ACCESS=*WRITE) or he/she must be a co-owner of the directory of the archive.
ARCHIVE-NAME = *SYSNODEARCHIVE
The node files are to be saved to the default long-term system archive (SYSNODEARCHIVE).
SAVE-FILE =
Defines the save file to which the archived node files are to be written.
SAVE-FILE = *STD
A standard save file is to be created or continued. The (physical) retention period valid for the save file is defined in the archive definition.
SAVE-FILE = *NEW(...)
The user’s archived node files are to be written to a new save file. A retention period for this save file can be defined here.
RETENTION-PERIOD = *STD / <integer 0..16383 days>
(Physical) retention period in days. During this period, neither the save file nor the save volume may be modified or deleted. Unless otherwise specified, the preset value from the archive definition applies.
SAVE-FILE = *CONTINUE(...)
The specified save file is to be continued. It must reside on storage level S2.
SAVE-FILE-ID = *LATEST
The most recently created save file for this archive is to be continued.
SAVE-FILE-ID = <composed-name 15..15>
The specified save file is to be continued. The save file ID must be specified as follows: S.yymmdd.hhmmss
SAVE-VERSION-NAME = *STD / <name 1..8>
Name of the save version generated by the archival request. This name can be used to refer to the save version for restore operations or in the HSMS statement SHOW-ARCHIVE. The name is extended internally by a prefix derived from the user ID (or, in the case of the HSMS administrator, by SYSHSMS). Any save version is uniquely identified by its name and an internal time stamp.
Unless otherwise specified, the save version is given the name “ARCHIVAL”.
DESCRIPTOR = *NONE / <c-string 1..10>
Brief descriptive text of up to 10 characters which is output in the summary of save versions produced as a result of SHOW-ARCHIVE SELECT=*SAVE-VERSIONS,INFO=*SUMMARY.
Unless otherwise specified, no description is written.
USER-INFORMATION = *NONE / <c-string 1..720>
Comment of up to 720 characters with information about the save version, which is output as a result of SHOW-ARCHIVE SELECT=*SAVE-VERSIONS,INF=*USER-INF.
Unless otherwise specified, no comment is written.
FILE-EXPIRATION-DATE = *STD / <date with-compl> / <integer 0..99999 days>
File expiration date for the archived node files. The specified date must not lie outside the (physical) retention period for the save files or save volumes unless this is permitted by the archive definition.
Unless otherwise specified, the file expiration date coincides with the end of the (physical) retention period defined for the save file or save volume.
OPERATION-CONTROL =
Enables the user to define certain parameters which are relevant to the execution of the archival run.
OPERATION-CONTROL = *STD
The default values of the operands described below apply.
OPERATION-CONTROL = *PARAMETERS(...)
The operands controlling the archiving 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, in the case of the HSMS administrator, by SYSHSMS) and a suffix in the form of a time stamp.
Unless otherwise specified, the request name is formed by the short code “ANF#” and the TSN of the calling user task yyyy as follows: ANF#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 during a complex processing operation, such as the processing of shadow archives.
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 statement processing during tape sessions only.
SHADOW-COPY =
Specifies whether the save version is to be automatically duplicated to a shadow archive which may have been assigned.
SHADOW-COPY = *ALLOWED
If the long-term archive in question has been assigned a shadow archive, the save version is automatically duplicated to this shadow archive after the archival run. Whether a save file is updated in the shadow archive, a new one is created like in the main archive or a new one is always created is specified by the SHADOW-CONTROL archive attribute of the main archive.
SHADOW-COPY = *INHIBITED
The save version is not automatically duplicated to a shadow archive which may have been assigned.
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 archival request and to determine the scope of this report.
REPORT = *SUMMARY
A summary of the results of the archival request, including any error messages, is to be output.
REPORT = *FULL
A full report is to be output, including a list of all archived files.
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 on this archival 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 archival 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 archival 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 archival 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.
In a SM pubset environment the environment catalog ID is added to the file names, if there is no environment catalog ID specified in the report file name.
Example
The HSMS administrator archives the file tree of a workstation.
Perform preparatory activities:
/START-HSMS //CREATE-ARCHIVE - ——————————————————————————————————————————————————— (1) // ARCHIVE-NAME=ARCHIVAL, - // ALLOWED-USAGE=*NODEARCHIVAL, - // DIRECTORY-NAME=ARCHIVAL.DIR, - // RETENTION-PERIOD=30 //MODIFY-ARCHIVE - ——————————————————————————————————————————————————— (2) // ARCHIVE-NAME=ARCHIVAL, - // VOLUMES=*ADD(VOLUMES=(VOLUM1,VOLUM2,...)) //MODIFY-NODE-PARAMETERS - ——————————————————————————————————————————— (3) // NODE-ID=WORKSTA1, - // HSMS-CONTROL=*YES //END
(1) | Sets up the ARCHIVAL archive for the long-term archiving of node files. By default, only the owner of the archive has access to it. The directory file is named ARCHIVAL.DIR. The archived node files cannot be deleted for 30 days. Note In order for the directory file to be usable also by non-privileged users, it must be shareable (USER-ACCESS=*ALL-USERS). |
(2) | Enters volumes in the pool of free volumes of the ARCHIVAL archive. |
(3) | Brings the workstation WORKSTA1 under HSMS control. |
Start archiving:
/START-HSMS //ARCHIVE-NODE-FILES - ——————————————————————————————————————————————— (4) // PATH-NAMES=*PATH-NAME(PATH=/DIR,NODE-ID=WORKSTA1), - // SELECTION-BOUNDARY=*ALL-FILE-SYSTEMS, - // ARCHIVE-NAME=ARCHIVAL, - // OPERATION-CONTROL=*PARAMETERS(REPORT=*FULL,OUTPUT=ARCHLIST) //END
(4) | Archives the directory /DIR of the workstation WORKSTA1. Also archives all the node files and directories located on the subordinate levels of the directory /DIR (SELECTION-BOUNDARY=*ALL-FILE-SYSTEMS). |