This statement is used for copying a node save file and the save versions of a BS2000-UFS or node S0 save run from a HSMS archive, either within the same archive or to another HSMS archive. Copying of node save files is restricted to the archive owner and the HSMS administrator.
The user can select individual node files and save versions for copying and exclude save versions whose expiration date has been reached.
The new save file created by copying and the save versions managed in it receive a new time stamp. Exception: when a save version is copied from one backup archive to another, the copy receives the same time stamp as the original.
When copying save versions, the original save date is recorded in the archive directory. It can be interrogated by means of SHOW-ARCHIVE..., SELECT=*SAVE-VERSIONS, INFORMATION=*USER-INFORMATION.
When copying without file selection (SELECT-PATHS=*ALL) in the same archive or to the shadow archive all files are copied, regardless of the ID and privilege of the caller.
Implicit deletion of obsolete backups can be set in the archive attribute.
This statement has different formats for nonprivileged users and HSMS administrators. Privileged operands or operand values are marked with *P).
Format
COPY-NODE-SAVE-FILE | Alias: CNF | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) Privileged operand or operand value
SAVE-FILE-ID =
Save file which is to be copied.
When copying within the same backup archive, only the latest save file can be copied (SAVE-FILE-ID=*LATEST). This serves to ensure that the sequence of the save versions reflects the chronological order of the save runs.
When copying from one backup archive to another, the SFID of the save file copy must be higher than the highest SVID of the target archive.
SAVE-FILE-ID = *LATEST
The most recently created save file of the archive is to be copied.
SAVE-FILE-ID = <composed-name 15..15>
The specified save file is to be copied. The save file ID must be specified in the following format: S.yymmdd.hhmmss
SELECT-SAVE-VERSIONS =
Serves to select individual save versions from the save file.
If copying takes place within the same backup archive, you can only copy the last save version (SELECT-SAVE-VERSIONS=*BY-ATTRIBUTES(SAVE-VERSION-DATE= *LATEST-DATE)). This ensures that the sequence of the save versions corresponds to the save sequence.
SELECT-SAVE-VERSIONS = *ALL
All save versions are to be copied.
SELECT-SAVE-VERSIONS = *BY-ATTRIBUTES(...)
Specification of criteria for selecting save versions:
SAVE-VERSION-NAME =
Specifies the names of save versions which can be copied.
SAVE-VERSION-NAME = *ANY
There are no restrictions on the save versions which can be selected.
SAVE-VERSION-NAME = <name 1..8>
Specifies the name of the save version to be copied.
Nonprivileged users can only select save versions they have created themselves. The save version name specified here is supplemented with the LOGON user ID to define the permitted save versions, or with SYSHSMS to specify HSMS administrator requests.
EXPIRATION-AFTER = *EARLIEST-DATE / <date with compl> / <integer -99999..99999 days>
Only save versions whose retention period expires after the date specified are selected.*EARLIEST-DATE means that the expiration date is not used to select save versions.
This operand is meaningful only when copying a save file from a long-term archive that permits a number of save versions (“user requests”) with different logical expiration dates per save file.
SAVE-VERSION-DATE =
Restricts the creation date of the save versions which may be copied.
SAVE-VERSION-DATE = *INTERVAL(...)
The save versions which may be copied can be selected by defining the period within which they have to have been created.
The default setting is that all save versions may be copied.
CREATED-BEFORE = *LATEST-DATE / <date with compl> / <integer -99999..0 days>(...)
Only save versions created on or prior to the date specified are selected. An additional time field allows you to make a more precise selection.
TIME = 23:59:59 / <time>
Time specification in the form hh:mm:ss
CREATED-AFTER = *EARLIEST-DATE / <date with compl> / <integer -99999..0 days>
Only save versions created on or after the date specified are selected.
This operand permits successive duplication of a save file which is continued for a number of days. Each day, only the new save versions are duplicated.
SAVE-VERSION-DATE = *LATEST-DATE
Only the latest save version in the archive (with the specified save version name) is copied.
SAVE-VERSION-DATE = <date with-compl>(...)
The save version from the specified date and time (with the specified save version name) is copied.
A two-digit year number yy is changed to 20yy if yy ≤ 59. It is changed to 19yy if yy > 59.
TIME = 23:59:59 / <time>
Time specification in the form hh:mm:ss
ORIGINAL-DATE =
This operand only applies to save versions from a migration archive or long-term archive. It specifies the save version to be copied by indicating the date of the original migration or archival. Details of the original date are maintained in the copy. With the original save the original date is the same as the date of the save version.
ORIGINAL-DATE = *INTERVAL(...)
The save versions which may be copied can be selected by defining a period in which their original dates must lie.
The default setting is that all save versions may be copied.
BEFORE = *LATEST-DATE / <date with compl> / <integer -99999..0 days>
Only save versions whose original date coincides with or precedes the date specified are selected.
AFTER = *EARLIEST-DATE / <date with compl> / <integer -99999..0 days>
Only save versions whose original date coincides with or succeeds the date specified are selected.
ORIGINAL-DATE = <date with-compl>(...)
The save version whose original date matches the date and time specified is copied.
A two-digit year number yy is changed to 20yy if yy ≤ 59. It is changed to 19yy if yy > 59.
TIME = 23:59:59 / <time>
Time specification in the form hh:mm:ss
SELECT-PATHS =
Serves to specify the node files to be copied from the save file. The file selection made here applies to all save versions of the save file that are to be copied.
SELECT-PATHS = *ALL
All node files are to be copied.
SELECT-PATHS = *SELECTED
The path names of the node files to be copied are to be taken from a list that was compiled within the same HSMS run by means of the HSMS statement SELECT-NODE-FILES.
SELECT-FILES = *FROM-FILE(...)
The path names of the node files to be copied 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.
SELECT-PATHS = *FROM-LIBRARY-ELEMENT(...)
The path names of the node files which are to be copied 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.
SELECT-PATHS = *PATH-NAME(...)
The path name of the node file to be copied is specified directly.
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 copied.
NODE-ID = *BS2000-UFS
The node file resides on the local BS2000-UFS.
NODE-ID = *ALL
The local BS2000-UFS and all existing node S0s 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-PATHS =
Serves to specify node files that are to be excluded from copying. The selection specified here applies to all save versions of the save file that are to be copied.
EXCEPT-PATHS = *NONE
No node files are to be excluded from copying.
EXCEPT-PATHS = *FROM-FILE(...)
The path names of the node files to be excluded from copying 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-PATHS = *FROM-LIBRARY-ELEMENT(...)
The path names of the files which are not to be copied 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-PATHS = *PATH-NAME(...)
The path name of the node file to be excluded from copying is specified directly.
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 copying.
NODE-ID = *BS2000-UFS
The node file resides on the local BS2000-UFS.
NODE-ID = *ALL
The local BS2000-UFS and all existing node S0s 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.
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 inodes will be included. Any node files and directories subordinated to a directory to be processed will be ignored.
NEW-PATH-NAMES =
This operand is only available to the HSMS administrator.
The HSMS administrator can copy the node files under another node S0. When renaming in node backup archives you must bear in mind that when renaming incremental backups it is also necesssary to rename the underlying full backups to ensure that the incremental backup procedure functions correctly when implementing a restore.
NEW-PATH-NAMES = *SAME
The node files are copied using the original node S0.
NEW-PATH-NAMES = *BY-RULE(...)
Node files are renamed using a standard rule.
NEW-NODE-ID = *SAME / *BS2000-UFS / <posix-filename 1..48 without-wild>
You can copy the node files under another node S0.
Unless otherwise specified node files are copied to their original node S0. The explicit specification of a new node S0 is only possible if the original node S0 was specified in thee SELECT-PATHS operand (specification not equal to *ALL or *PATH-NAME(...,NODE-ID=*ALL).
ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>(...)
Name of the archive from which the save file is to be copied. The specified archive must already exist. In the event of a nonprivileged call, the caller must be an owner or, via the directory, co-owner of the archive, or the archive must provide access for all users (USER-ACCESS=*ALL-USERS, ACCESS=*READ).
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.
ENVIRONMENT =
HSMS environment in which the original archive is defined.
ENVIRONMENT = *NODE-STD
The environment is derived from either:
the operand SELECT-PATHS=*PATH-NAME(NODE-ID) or
the list of node IDs which are referenced in the file in the operand SELECT-PATHS=*FROM-FILE(LIST-FILE-NAME) or in the library element of 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 archive is valid in the SF environment.
ENVIRONMENT = *SYSTEM-MANAGED(...)
This 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.
TO-ARCHIVE-NAME =
Determines the archive to which the save file is to be copied.
TO-ARCHIVE-NAME = *SAME
The save file is copied to the archive specified in the ARCHIVE-NAME operand.
TO-ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>(...)
The save file is copied to the archive specified. The specified archive must already exist. In the event of a nonprivileged call, the caller must be an owner, via the directory, co-owner of the archive, or the archive must provide access for all users (USER-ACCESS=*ALL-USERS, ACCESS=*READ).
ENVIRONMENT =
HSMS environment in which the destination archive is defined.
ENVIRONMENT = *SAME
The archive is defined in the same environment as the original archive.
ENVIRONMENT = *SINGLE-FEATURE
The archive is defined in the SF environment.
ENVIRONMENT = *SYSTEM-MANAGED(...)
The archive is defined in the specified SM pubset environment.
CATALOG-ID = <cat-id>
Catalog ID of the SM pubset environment.
SAVE-FILE =
Defines the save file to which the save file copy is to be written.
SAVE-FILE = *NEW(...)
The copy of the save file is to be written to a new save file. The following attributes of this save file can be defined here:
RETENTION-PERIOD = *STD / <integer 0..16383 days> / *FROM-ORIGINAL-SAVE-FILE
(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.
RETENTION-PERIOD = *FROM-ORIGINAL-SAVE-FILE
The new save file is assigned the retention period of the original save file.
SAVE-FILE = *CONTINUE(...)
The specified save file is to be continued.
If copying is performed within the same archive, input and output save file must not be identical.
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 in the following format: S.yymmdd.hhmmss
TO-STORAGE =
Defines the storage level to which the save file is to be copied.
Save files from long-term and migration archives must be copied to S2. Save files from backup archives may be copied to S2, S1 and to private disk.
TO-STORAGE = *S2-STORAGE-LEVEL(...)
The save file is to be copied to storage level S2. The volumes to be used can be specified. If more than one volume is specified, all volumes must be of the same device type.
VOLUMES = *FROM-POOL
The volumes are to be taken from the volume pool of the specified archive, i.e. the pool of the directory or the associated MAREN pool.
VOLUMES = *FROM-OPERATOR
The volumes are to be allocated by the operator on request.
VOLUMES = list-poss(10): <vsn 1..6>
List of volume serial numbers, which will be requested in the specified order.
DEVICE-TYPE = *STD / <device>
Device type of the requested volumes. The device type must belong to the class “TAPE”. 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 (S2-DEVICE-TYPE operand).
LOCATION = *STD / *ANY / <alphanum-name 1..8>
Location used for requesting volumes. This location must be known to MAREN. If the location manager is in use, the location should be properly defined in MARENLM. Otherwise MAREN ignores the specified value.
If MAREN is not in use, you must specify for LOCATION the value *ANY, or *STD if *ANY is the default location of the archive.
LOCATION = *STD
The default location of the archive is used.
LOCATION = *ANY
No location is to be used.
OPERATION-CONTROL =
Enables the user to define certain parameters which are relevant for the execution of the copy run.
OPERATION-CONTROL = *STD
The default values of the operands described below apply.
OPERATION-CONTROL = *PARAMETERS(...)
The operands controlling the copy 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 “CNF#” and the TSN of the calling user task yyyy as follows: CNF#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 statement processing during tape sessions only.
PARALLEL-RUNS = *MAXIMUM / <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.
The default value (*MAXIMUM) implies that the value specified when creating the save file to be copied applies.
For further information on parallel processing, see the “HSMS Vol. 1” manual [1].
OPERATOR-INTERACTION = *STD / *NOT-ALLOWED / *ALLOWED
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 =
Defines the parameters which are relevant for copying to tape.
TAPE-CONTROL = *STD
The preset values from the definition of the archive within which copying is to take place apply.
TAPE-CONTROL = *PARAMETERS(...)
The following operands for copying to tape can be modified:
BLOCKING-FACTOR = *STD / <integer 2..15 2Kbyte> / *MAX
Blocking factor to be used for writing the save file to tape, specified as the number of 2-Kbyte blocks (PAM pages) written to tape in a single input/ output operation. As the higher blocking factor means that the occupancy level of the volume and the tape processing performance improve, values below 15 should not be selected. The default value *STD selects the blocking factor from the archive definition. If this also contains the default value, the default values of the ARCHIVE parameters apply (BLOCK-SIZE-TAPE for tapes, BLOCK-SIZE-T-C for magnetic tape cartridges).
*MAX selects the maximum blocking factor possible in the current BS2000 version. Currently this is the value 128.
UNLOAD-TAPE = *STD / *YES / *NO
Specifies whether or not tapes are to be unloaded after processing. This applies to both input and output tapes. The default value is taken from the archive definition of the target archive.
It is possible that HSMS will ignore the value of this operand in order to avoid irrational tape processing, 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 copy request and to determine the scope of this report.
REPORT = *SUMMARY
A summary of the results of the copy request, including any error messages, is to be output.
REPORT = *FULL
A full report is to be output, including a list of all files cataloged but not saved because they have not been modified since the last save run. When copying without file specification in the same archive or to the shadow archive, the specification is converted to REPORT=*SUMMARY.
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 copy 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 copy 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 copy 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 copy 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 an SM pubset environment the environment catalog ID is added to the file names if there is no catalog ID specified in the report file name.
Example
The HSMS administrator copies the last save version of a node backup archive containing node files to storage level S2.
//COPY-NODE-SAVE-FILE ARCHIVE-NAME=NODE.BACKUP, - // SELECT-SAVE-VERSIONS=*BY-ATTRIBUTES(SAVE-VERSION-DATE=*DATE)
If copying takes place within a backup archive, only the last save version can be copied.
All node files in the latest save file of the archive NODE.BACKUP are copied to a new save file on storage level S2. Backup takes place to volumes from the archive’s volume pool.
Depending on the global HSMS parameter OUTPUT a comprehensive report is printed or sent as an email attachment.