This statement is used to copy save files created with the HSMS statement EXPORT-FILES or the EXPORT statement of the software product ARCHIVE.
In addition a special function is offered which converts export backups without directory to backups with directory and Several-SVID format for an HSMS long-term archive in the case of a switchover from ARCHIVE to HSMS operation.
This statement has different formats for nonprivileged users and HSMS administrators. Privileged operands or operand values are marked with *P).
Format
COPY-EXPORT-SAVE-FILE | Alias: CES | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) Privileged operand or operand value
INPUT-SAVE-FILE =
Defines the save file from which the files to be copied are to be retrieved.
INPUT-SAVE-FILE = *BY-VOLUME(...)
The save file from which the files are to be copied is defined by the volume on which they reside.
SAVE-FILE-ID = *NOT-SPECIFIED
The save files on the specified volumes are selected irrespective of their save file ID.
SAVE-FILE-ID = <composed-name 15..15>
The files are copied only from the specified save file. The save file ID must be specified as follows: S.yymmdd.hhmmss
VOLUMES = list-poss(100): <vsn 1..6>
Volume serial number of the volumes containing the save files with the files to be copied.
VOLUMES = *list-poss(16): GROUPED-BY-RUN(...)
Only for copying in more than one parallel run:
A separate *GROUPED-BY-RUN specification must be made for each parallel run. Up to 16 entries can be made.
VOLUMES = list-poss(100): <vsn 1..6>
Volume serial number of the volumes in the individual parallel runs.
DEVICE-TYPE = *STD / <device>
Device type of the backup volumes. Only device types known in the system are accepted. In interactive mode, DEVICE-TYPE=? calls up a list of the available device types.
The default value is the value defined with the S2-DEVICE-TYPE operand of the MODIFY-HSMS-PARAMETERS statement.
INPUT-SAVE-FILE = *FROM-DIRECTORY(...)
The save file from which the files are to be copied is selected from a directory. The nonprivileged caller must be owner or co-owner of this directory.
DIRECTORY-NAME = <filename 1..54 without-gen-vers>
Directory written to the volume during the export run and previously imported in a separate run.
SAVE-FILE-ID = *LATEST
The data is copied from the last save file in the specified directory. *LATEST makes sense only for SINGLE-SVID save structure.
SAVE-FILE-ID = <composed-name 15..15>
The data is copied from the specified save file with SINGLE-SVID structure or from the specified save version in a SEVERAL-SVID environment. The save file ID must be specified as follows: S.yymmdd.hhmmss
DEVICE-TYPE = *STD / <device>
Device type of the volume on which the save version resides. This need be specified only if the save version was created in an ARCHIVE version < V2.6B. In higher ARCHIVE versions, the device type used for backup is indicated in the directory. Only device types known in the system are accepted. In interactive mode, DEVICE-TYPE=? calls up a list of the available device types.
The default value is the value defined with the S2-DEVICE-TYPE operand of the MODIFY-HSMS-PARAMETERS statement.
INPUT-SAVE-FILE = *BY-VOLUME-CATALOG(...)
MAREN V12.5 is required to use this operand.
The input save file is specified with its exact name, and the associated volumes are determined by MAREN. This makes sense for export save files with no directory.
SAVE-FILE-ID = <composed-name 15..15>
Exact name of the input save file in the format: S.yymmdd.hhmmss
INPUT-SAVE-FILE = *BY-PUBLIC-DISK(...)
The save file is selected by the pubset on which it resides.
SAVE-FILE-ID = <composed-name 15..15>
The files are copied only from the specified save file. The save file ID must be specified as follows: S.yymmdd.hhmmss
PUBSET-ID = <cat-id 1..4>
Specifies the catalog ID of the pubset where the save file is located. If the save file is located on Net-Storage this is the pubset to which the Net-Storage volume is assigned.
PASSWORDS = *NONE / *SECRET-PROMPT / list-poss(63): <c-string 1..4> / <x-string 1..8> /
<integer -2147483648..2147483647>
If a password was specified for the save file during an export run (SAVE-FILE-PASSWORD or SVPASS in ARCHIVE), that password must be specified here.
The password must also be specified here if a save file which is password-protected is to be continued.
The PASSWORDS operand has the following special characteristics:
The password entered is not logged.
The input field is automatically blanked out in an interactive dialog.
In unguided dialog and foreground procedures, the entry *SECRET or ^ permits concealed input of the password.
SELECT-FILES =
Serves to specify the 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. For nonprivileged callers, all files (also of foreign IDs) are also copied.
The selection can be restricted by means of the EXCEPT-FILES operand.
SELECT-FILES = *ALL
All files are to be copied from the save file.
SELECT-FILES = *NONE
No files are to be copied from the save file.
SELECT-FILES = *SELECTED
The path names of the 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-FILE-NAMES.
SELECT-FILES = *FROM-FILE(...)
The path names of the 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. The list file can be created, for instance, by means of the HSMS statement SELECT-FILE-NAMES or the BS2000 command SHOW-FILE-ATTRIBUTES.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
SELECT-FILES = *FROM-LIBRARY-ELEMENT(...)
The path names of the files which are to be copied are taken from a PLAM library element (type S). The library element contains one path name per record. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
SELECT-FILES = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the files to be copied are specified directly. A list of up to 20 names may be specified.
The file names may be specified as fully or partially qualified names, with or without a catalog/user ID. If required, the file name is extended by the user ID of the request and the default catalog ID of the user ID.
The files can alternatively be selected using wildcards. Note, however, that only the HSMS administrator may use wildcards for user ID specification. The wildcards are replaced in accordance with the file names listed in the archive directory.
EXCEPT-FILES =
Serves to specify 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-FILES = *NONE
No files are to be excluded from copying.
EXCEPT-FILES = *FROM-FILE(...)
The path names of the 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. The list file can be created, for instance, by means of the BS2000 command SHOW-FILE-ATTRIBUTES.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
EXCEPT-FILES = *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. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
EXCEPT-FILES = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the files to be excluded from backup are specified directly. A list of up to 20 names may be specified.
The first character of the file names must not be a hyphen. The file names may be specified as fully or partially qualified names, with or without a catalog/user ID. If required, the file name is extended by the user ID of the request and the default catalog ID.
The files can alternatively be selected using wildcards. Note, however, that only the HSMS administrator may use wildcards for user ID specification because only he/she is allowed to specify other user IDs. Wildcards are replaced using the file names contained in the archive directory.
SELECT-JV =
Serves to specify the job variables to be copied from the save file. The selection made here applies to all save versions of the save file that are to be copied. With nonprivileged callers, too, all job variables (also from foreign IDs) are copied.
SELECT-JV = *NONE
No job variables are to be copied from the save file.
SELECT-JV = *ALL
All job variables are to be copied from the save file.
SELECT-JV = *FROM-FILE(...)
The path names of the 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-JV = *FROM-LIBRARY-ELEMENT(...)
The path names of the job variables which are to be copied are taken from a PLAM library element (type S). The library element contains one path name per record. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
SELECT-JV = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the job variables to be copied are specified directly. A list of up to 20 names may be specified.
The job variables can alternatively be selected using wildcards.
EXCEPT-JV =
Serves to specify job variables 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.
This operand is meaningful only for copying from a backup archive. Other types of archive do not contain job variables.
EXCEPT-JV = *NONE
All job variables specified in the SELECT-JV operand are to be copied.
EXCEPT-JV = *FROM-FILE(...)
The path names of the job variables 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-JV = *FROM-LIBRARY-ELEMENT(...)
The path names of the job variables which are not to be copied are taken from a PLAM library element (type S). The library element contains one path name per record. Only upper-case letters may be used.
LIBRARY = <filename 1..54 without-gen-vers>
Name of the PLAM library.
ELEMENT = <composed-name 1..64 with-under>
Name of the type-S element. The element of the highest existing version is used.
EXCEPT-JV = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the job variables to be excluded from copying are specified directly.
A list of up to 20 names may be specified. The first character of the job variable names must not be a hyphen.
The job variables can alternatively be selected using wildcards.
OUTPUT-DIRECTORY =
This operand is only available to the HSMS administrator.
Specifies whether an output directory is to be used when the save files are copied. Specifying an output directory enables the HSMS administrator to copy export backups without directory to backups with directory and Several-SVID format for a long-term archive in one step. This function facilitates the switchover from ARCHIVE to HSMS operation.
OUTPUT-DIRECTORY = *NONE
No output directory is specified. Processing is performed without the special copy function being used.
OUTPUT-DIRECTORY = <filename 1..54 without-gen-vers>
The directory of a long-term archive to which the files and job variables exported to the volume are to be saved is specified. The associated long-term archive must be defined in the SF environment.
To specify an output directory the save file from which the files to be imported are to be fetched must be specified via the volume (see the INPUT-SAVE-FILE=*BY-VOLUME(...) operand).
When a save file is updated with OUTPUT-SAVE-FILE=*CONTINUE either the last (*LATEST specification) save file or one specially specified can be updated in the specified directory of the long-term archive. When updating takes place SAVE-FILE-ID=*NOT-SPECIFIED is treated like *LATEST. Volumes specified under *CONTINUE are ignored.
The output directory must always work with CATALOG-ID-MODE=*YES. Specification of CATALOG-ID-MODE=*NO is therefore rejected. If the input save file does not contain a catalog ID (from an export run with CATID-MODE=*NO), the copy operation is rejected with ARC0254. In this case the destination ID can be predefined by a special REP, and the copy operation can be executed without being rejected (more detailed information can be obtained from the field engineer responsible).
As this special copy function converts export tapes without directory to save files of a long-term archive with Several-SVID format files and job variables cannot be selected here using path names. Only the following specifications are permitted: SELECT-FILE=*ALL/*NONE, SELECT-JV=*NONE/*ALL, EXCEPT-FILE=*NONE and EXCEPT-JV=*NONE.
OUTPUT-SAVE-FILE =
Defines the save file to which the exported files are to be written.
OUTPUT-SAVE-FILE = *NEW(...)
The exported files are to be written to a new save file. The following attributes for this save file can be defined here:
RETENTION-PERIOD = 0 / <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.
USER-ACCESS = *ALL-USERS
The save file is created as a shareable file . The data can be imported under a different user ID.
USER-ACCESS = *OWNER-ONLY
The save file is created as a non-shareable file. The data can be imported only under the same user ID.
SAVE-FILE-PASSWORD = *NONE / *SECRET-PROMPT / list-poss(1000):
<c-string 1..4> / <x-string 1..8> / <integer -2147483648..2147483647>
The save file to be created can be assigned a password which must be entered when the file is continued or imported.
The SAVE-FILE-PASSWORD operand has the following special characteristics:
The password entered is not logged.
The input field is automatically blanked out in an interactive dialog.
In unguided dialog and foreground procedures, the entry *SECRET or ^ permits concealed input of the password.
OUTPUT-SAVE-FILE = *CONTINUE(...)
The save file, which can subsequently be defined in greater detail, is continued.
SAVE-FILE-ID = *NOT-SPECIFIED
The save file to be continued is not defined by the SFID but rather by the volume on which it resides.
SAVE-FILE-ID = *LATEST
Only if a directory is used:
the most recently created save file is continued.
SAVE-FILE-ID = <composed-name 15..15>
The specified save file is continued. The save file ID must be specified as follows: S.yymmdd.hhmmss
VOLUMES = *NOT-SPECIFIED
Only if a directory is used:
the volume is taken from the directory.
VOLUMES = list-poss(16): <vsn 1..6>
The most recently written volume is specified.
When creating the save file, a separate volume can be specified for each parallel run.
COMPRESS-FILES = *NO / *YES
Determines whether or not data is compressed before being written to the output volume.
SAVE-DIRECTORY = *NO / *YES
Only relevant for INPUT-SAVE-FILE=*FROM-DIRECTORY.
Determines whether the directory specified with DIRECTORY-NAME is to be written to the output volume as the last file.
TO-STORAGE =
Specifies the destination to which the files are to be copied.
TO-STORAGE = *TAPE(...)
The files are to be copied to tape.
The volumes can be defined in greater detail; if several volumes are specified, they all must be of the same device type.
VOLUMES = *FROM-POOL
Only if a directory is used:
the volumes are taken from the volume pool of the specified archive or the associated MAREN pool.
VOLUMES = *FROM-OPERATOR
The volumes are to be allocated by the operator on request.
VOLUMES = list-poss(100): <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.
The default value is the value defined with the S2-DEVICE-TYPE operand of the MODIFY-HSMS-PARAMETERS statement if OUTPUT-SAVE-FILE=NEW(...) or the device type of the device previously used if OUTPUT-SAVE-FILE=CONTINUE(...).
LOCATION = *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 the value *ANY for LOCATION.
LOCATION = *ANY
No location is to be used.
TO-STORAGE = *PUBLIC-DISK(...)
This operand value is only available to the HSMS administrator. The save file is to be copied to a pubset.
PUBSET-ID = <cat-id>
Catalog ID of the pubset.
TO-STORAGE = *NET-STORAGE(...)
The save file is to be copied to a Net-Storage.
VOLUMES = list-poss(16): <vsn 1..6>
Specifies the Net-Storage volume to which the files are to be copied. The volume specified must be accessible.
More than one Net-Storage volume can also be specified in a list (e.g. when there is more than one save task).
OPERATION-CONTROL =
Enables you to define certain parameters which are relevant to the execution of the backup run.
OPERATION-CONTROL = *STD
The default values of the operands described below apply.
OPERATION-CONTROL = *PARAMETERS(...)
The following parameters which control the backup run can be modified:
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 of the short code “CES#” and the TSN of the calling user task yyyy as follows: CES#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.
CATALOG-ID-MODE = *YES / *NO
Determines whether the data is written to the save file with or without a catalog ID (corresponds to CATID operand in ARCHIVE).
PARALLEL-RUNS = 1 / <integer 1..16>
Number of save tasks (ARCHIVE subtasks) running in parallel.There must be two tape devices available for each task.
Unless otherwise specified, only one save task is running.
For further information on parallel processing see the “HSMS Vol. 1” manual [1].
WRITE-CHECKPOINTS = *YES / *NO
Defines whether any checkpoints are to be written to the ARCHIVE checkpoint file during processing; these checkpoints permit a request to be restarted following an interruption (state INTERRUPTED).
Unless otherwise specified, the preset value from the archive definition applies.
OPERATOR-INTERACTION = *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]).
TAPE-CONTROL =
Defines the parameters which are relevant for export to tape.
TAPE-CONTROL = *STD
The default values described for the operand apply.
TAPE-CONTROL = *PARAMETERS(...)
You can modify the following operands relevant for export to tape:
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.When the default value *STD is selected, 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 = *NO / *YES
Specifies whether or not tapes are to be unloaded after processing.
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 export request and to determine the scope of this report.
REPORT = *SUMMARY
A summary of the results of the export request, including any error messages, is to be output.
REPORT = *FULL
A full report is to be output, including a list of all exported 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 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 export request is to be prepared for printing 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.