This statement is used for copying a save file and the save versions of a predefined HSMS archive either within the same archive or to another archive. The user can select individual 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, except in the following cases:The time stamp remains unchanged if
copying is performed from an original archive to an assigned shadow archive or vice versa.
copying is performed from any type of archive to a backup archive (except when copying takes place within a backup archive).
When copying into a migration archive, only a single save version is created in the destination save file, even if the original save file contains multiple save versions. As a result, the size of the directory file which is assigned to the migration archive is reduced, as is the subsequent processing time.
When copying within a migration archive, the copy becomes the current carrier of the migrated data (implicit EXCHANGE function). When copying from one migration archive to another, or from a long-term archive to a migration archive, no implicit EXCHANGE takes place.
When copying incremental backups within a backup archive, the CNS entries are also copied to the new save file. The result is that a RESTORE-FILES statement with SAVE-VERSIONS=*LATEST ... produces the same result on the destination archive as on the original archive.
When copying a save version, the time the original save version was created is recorded in its entry in the archive directory. It can be interrogated by means of //SHOW-ARCHIVE..., SELECT=*SAVE-VERSIONS, INFORMATION=*USER-INFORMATION.
When copying without file selection and renaming in the same archive or to the shadow archive all files are copied, regardless of the ID and privilege of the caller. Otherwise a nonprivileged caller can only copy their own files or files of a foreign ID if co-ownership exists.
If the backup archive to which the save file to be copied belongs permits more than one save version per save file (SAVE-FILE-STRUCTURE=*SEVERAL-SVID), the save file copy can be created within the same backup archive. Here only the last save version of the original save file can be copied. This save version must be specified completely in the SAVE-VERSION-DATE with date and time and it must be stored in a new save file.
If copying is from a backup or long-term archive to the assigned shadow archive or from a shadow archive to the associated backup or long-term archive, two cases can be distinguished:
The SFID of the copied save file is not present in the target archive.
In this case a new save file is created in the target archive with the same SFID as that of the copied save file in order to accommodate the duplicated save versions. All duplicated save versions have the same SVID in the target archive as in the original archive.An existing save file is to be continued in the target archive; this is only permitted for save files which can contain several save versions (SAVE-FILE-STRUCTURE=*SEVERAL-SVID).
In this case, the SFID of the output save file must be the same as the SFID of the input save file. In addition, all duplicated save versions must be more recent than all the save versions already contained in the output save file.
From HSMS V12.0D COPY-SAVE-FILE statement allows a reorganization function for long term archives if the copying is done into the same archive. The reorganization means that only save versions which file expiration date has not been reached are copied and afterwards the origin save file is deleted automatically. The function can be activated by specifying: EXPIRATION-AFTER=<date>(INPUT-SAVE-FILE=*DELETE). However, the deletion is not possible and the statement will be rejected in the following cases:
- if files or JVs are selected;
- or if save versions are selected by names or dates;
- or copying is done into another archive.
Within HSMS V12.0A copying save file from version backup archive to any other archive of any type will not be possible and vice versa copying from other archives of any types to a version backup archive will also be rejected. Copying within one and the same version backup archive has no sense as this contradicts with the idea of version backup – to store only different versions of a file.
The COPY-SAVE-FILE requests are entered in the request file of the destination environment. To output the COPY-SAVE-FILE requests, users assigned to another environment must explicitly specify this environment when they issue a SHOW-REQUEST statement.
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-SAVE-FILE | Alias: CSF | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) Privileged operand or operand value
SAVE-FILE-ID =
Save file which is to be copied.
Only the latest save file in a backup archive can be copied within that archive (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 any type of archive to a backup archive, the SFID of the save file copy must be higher than the highest SVID of the target archive (in order to keep the backup consistent).
When copying between a backup archive and the assigned shadow archive, the SFID of the copied save file does not need to be the latest SFID of one of the two archives. The copying is rejected if the target archive already contains a save file with the same SFID, unless the output save file is to be continued.
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.
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 the save versions to 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.
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 should only be used when copying a long-term archive’s save file which might possibly contain a number of save versions (“user requests”) with different logical expiration dates.
EXPIRATION-AFTER = <date with-compl>(...)
Date as absolute specification.
INPUT-SAVE-FILE = *KEEP / *DELETE
Specifies if the input save file should be deleted implicitly after selected save versions are copied. Implicit deletion is only allowed if the specified date is today or a day in the past.
EXPIRATION-AFTER = <integer -99999..99999 days >(...)
Date as relative specification with regard to the current date.
INPUT-SAVE-FILE = *KEEP / *DELETE
Specifies if the input save file should be deleted implicitly after selected save versions are copied. Implicit deletion is only allowed if the specified date is today or a day in the past.
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.
Unless otherwise specified, 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 specify a more precise selection.
CREATED-BEFORE = <date with-compl>(...)
Date as absolute specification.
TIME = 23:59:59 / <time>
Time specification in the form hh:mm:ss
CREATED-BEFORE = <integer -99999..0 days >(...)
Date as relative specification with regard to the current date.
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 being copied into a 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. In the original backup 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.
Unless otherwise specified, 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-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.
The selection can be further restricted by means of the EXCEPT-FILES operand. In BS2000 migration archives, the selection can be further restricted by means of the MIGRATION-STATE operand.
When copying without file selection and renaming in the same archive or to the shadow archive all files (also from foreign IDs) are copied, also for nonprivileged callers. Otherwise nonprivileged callers can only copy their own files or - from explicitly specified foreign IDs - files of which they are co-owners.
SELECT-FILES = *ALL
All files are to be copied.
SELECT-FILES = *NONE
No files are copied.
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. Either BS2000 files or node files may be specified in any one list file, but not both types.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
SELECT-NAMES = *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>
This option is restricted to BS2000 files.
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 catalog ID which is either taken from the specified environment or from 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. In migration archives, the selection can be further restricted by means of the MIGRATION-STATE operand.
If a shadow archive is used for an input or output, you cannot change the contents of the save version. In this case you can only specify the operand value *NONE for EXCEPT-FILES.
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-FILE-NAMES = *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>
This option is restricted to BS2000 files.
The path names of the files to be excluded from copying 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 catalog ID which is either taken from the specified environment or from 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 because only the HSMS administrator is allowed to specify other user IDs. Wildcards are replaced using the file names contained in the archive directory.
NEW-FILE-NAMES =
The files can be renamed while the save files are being copied. The user must ensure that the new path name complies with the BS2000 conventions. It must not be longer than
54 characters in total, i.e. the file name without user and catalog ID should only be
38 characters (because of the extension of the catalog ID). The new file name is made up as follows:
:<cat-id>:$<user-id>.old-filename-without-cat-user.<suffix>
When renaming in backup archives, you must ensure that renaming of incremental backups also necessitates the renaming of the underlying full backups so that the incremental backup procedure functions correctly for restore. A renamed full backup can be produced with //BACKUP-FILES. ..,NEW-FILE-NAMES=...,FROM=*LATEST-BACKUPS-OR-S0.
If a shadow archive is used for an input or output, you cannot change the contents of the save version. In this case you can only specify the operand value *SAME.
NEW-FILE-NAMES = *BY-RULE(...)
The files are to be copied in accordance with a uniform rule.
NEW-CATALOG-ID = *STD / <cat-id>
Copies the files to another catalog ID. The catalog ID must be specified without colons. The user ID must be entered in this catalog.
To keep the contents of the backup and migration archive consistent, the new catalog ID must agree with the destination environment. Depending on the original and destination environment, *STD is set to a value which takes the above rule into account.For more detailed information, please refer to the end of the operand description of this statement.
NEW-USER-ID = *SAME / <name 1..8>
This operand is only available to the HSMS administrator.
Copies the files to another user ID. The user ID must be specified without a leading $ character.
The files are copied under the original user ID by default.
PREFIX = *NONE / <filename 1..8 without-cat-user-gen-vers>
A prefix of up to 8 characters can be added to the file name. It is automatically separated from the file name by a period (partial qualification). Only characters that are also allowed in a file name are permitted.
Unless otherwise specified, files are not given a prefix.
SUFFIX = *NONE / <composed-name 1..8>
A suffix of up to 8 characters can be added to the file name. It is automatically separated from the file name by a period (partial qualification). Only characters that are also allowed in a file name are permitted.
Unless otherwise specified, files are not given a suffix.
NEW-FILE-NAMES = *SAME
The files are copied without being renamed.
MIGRATION-STATE = *ANY / *MIGRATED-FILE
Only those files which are still present in the “migrated” state on S0 are copied, i.e. files which are still valid.
The entry is used to reorganized migration archives.
Unless otherwise specified, all files are copied, regardless of whether they are valid migrated files.
The entry *ANY is ignored if a save file is being copied within the same migration archive.
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.
When copying without JV selection and renaming in the same archive or to the shadow archive all job variables (also from foreign IDs) are copied, also for nonprivileged callers. Otherwise nonprivileged callers can only copy their own job variables or - from explicitly specified foreign IDs - job variables of which they are co-owners.
SELECT-JV = *ALL
All job variables are to be copied.
SELECT-JV = *NONE
No job variables are to be copied.
SELECT-JV = *FROM-FILE(...)
The path names of the job variables 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 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.
NEW-JV-NAMES =
The job variables can be renamed while the save files are being copied.
The user must ensure that the new path name complies with the BS2000 conventions. It must not be longer than 54 characters in total, i.e. the job variable name without user ID and catalog ID should only be 38 characters (because of the extension of the catalog ID). The new job variable name is formed as follows:
:<cat-id>:$<user-id>.<prefix>.old-jvname-without-cat-user.<suffix>
If a shadow archive is used for an input or output, you cannot change the contents of the save version. In this case you can only specify the operand value *SAME.
NEW-JV-NAMES = *SAME
The job variables are copied without being renamed.
NEW-JV-NAMES = *BY-RULE(...)
The job variables are to be copied in accordance with a uniform rule.
NEW-CATALOG-ID = *STD / <cat-id>
Copies the job variables to another catalog ID. The catalog ID must be specified without colons. The user ID must be entered in this catalog.
To keep the contents of the backup and migration archive consistent, the new catalog ID must agree with the destination environment. Depending on the original and destination environment, *STD is set to a value which takes the above rule into account.For more detailed information, please refer to the end of the operand description of this statement.
NEW-USER-ID = *SAME / <name 1..8>
This operand is only available to the HSMS administrator.
Copies the job variables to another user ID. The user ID must be specified without a leading $ character.
The job variables are copied under the original user ID by default.
PREFIX = *NONE / <filename 1..8 without-cat-user-gen-vers>
A prefix of up to 8 characters can be added to the job variable name. It is automatically separated from the job variable name by a period (partial qualification). Only characters that are also allowed in a job variable name are permitted.
Unless otherwise specified, job variables are not given a prefix.
SUFFIX = *NONE / <composed-name 1..8>
A suffix of up to 8 characters can be added to the job variable name. It is automatically separated from the job variable name by a period (partial qualification). Only characters that are also allowed in a job variable name are permitted.
Unless otherwise specified, job variables are not given a suffix.
EXCEPT-JV =
Serves to specify job variables that are to be excluded from copying. The selection of the job variables that are to be excluded applies to all save versions of the save file.
If a shadow archive is used for an input or output, you cannot change the contents of the save version. In this case you can only specify the operand value *NONE for EXCEPT-JV.
EXCEPT-JV = *NONE
No job variable is to be excluded from copying.
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 names must not begin with a hyphen.
The job variables can alternatively be selected by using wildcard syntax.
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 =
Determines the HSMS environment in which the original archive is defined.
ENVIRONMENT = *STD
Meaning for privileged users:
*STD is set to the value *SINGLE-FEATURE.
Meaning for nonprivileged users:
*STD is the environment that is associated with the user’s default pubset (the default pubset is defined in the user catalog).
ENVIRONMENT = *SINGLE-FEATURE
The 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
TO-ARCHIVE-NAME =
Name of the archive to which the save file is to be copied. Copy operations can only be carried out
from one backup archive that permits only one save version per save file (*SINGLE-SVID) to another (also *SINGLE-SVID)
from one backup archive that permits more than one save version per save file (*SEVERAL-SVID) to another (also *SEVERAL-SVID)
from one long-term archive to another
from one migration archive to another
from a migration archive to a long-term archive
from a long-term archive to a migration archive
from a backup archive that permits more than one save version per save file (*SEVERAL-SVID) to a long-term archive
from a backup archive that permits more than one save version per save file (*SEVERAL-SVID) to a migration archive
from a long-term archive to a backup archive that permits more than one save version per save file (*SEVERAL-SVID)
from a migration archive to a backup archive that permits more than one save version per save file (*SEVERAL-SVID)
from a backup or long-term archive to the assigned shadow archive
from a shadow archive to the associated backup or long-term archive
TO-ARCHIVE-NAME = *SAME
The copy operation is carried out within the archive specified in the ARCHIVE-NAME operand.
If the copy operation is performed within a migration archive, the identifying information in the catalog entry is updated for migrated files. This is a prerequisite if a subsequent recall is to succeed in extracting the data from the copy.
TO-ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>
The file is copied to the specified archive. 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=*WRITE).
ENVIRONMENT =
Determines the HSMS environment in which the target archive is defined.
ENVIRONMENT = *SAME
The archive is defined in the same environment as the original archive.
ENVIRONMENT = *STD
Meaning for privileged users: *STD is set to the value *SINGLE-FEATURE.
Meaning for nonprivileged users: *STD is the environment that is associated with the user’s default pubset (the default pubset is defined in the user catalog).
ENVIRONMENT = *SINGLE-FEATURE
The archive is defined in the SF pubset 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-DIRECTORY = *NO / *YES
Determines whether the directory file of the output archive used for this run is also to be written to the output volume as the last file of the run.
If the copied files are renamed during the run (specification in NEW-FILE-NAMES operand), the name of the directory file is not changed.
DEVICE-TYPE = *STD / <c-string 1..8>
Device type of the volume on which the save file to be copied is resident. This operand need not be specified unless the save file was created in an ARCHIVE version < V2.6B. In later ARCHIVE versions, the device type used for saving is recorded in the directory and any differing specification is ignored.
Note
When tape volumes are copied “offline” from an old device type to a new one with the same VSN without adjusting the directory, an optional REP can be used to ensure that the device type specified explicitly has priority over the device type specified in the directory file and consequently that a device type which differs from the directory file is accepted.
SAVE-FILE =
Defines the save file to which the save file copy is to be written.
SAVE-FILE = *NEW(...)
The save file copy 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 expiration date of the original save file.
USER-ACCESS = *OWNER-ONLY
Access to the save file is to be restricted to the archive owner. This implicitly protects the save file against access by other users working without HSMS.
USER-ACCESS = *ALL-USERS
Access to the save file is to be granted to other users as well. If the corresponding directory is shareable and resides under TSOS, each user is simultaneously enabled to restore his or her files using ARCHIVE.
SAVE-FILE = *CONTINUE(...)
The specified save file is to be continued.
With migration and long-term archives, continuation of a save file is permissible only for save files residing on storage level S2.
With backup archives that permit no more than one save version per save file (SAVE-FILE-STRUCTURE=*SINGLE-SVID), continuation of a save file is prohibited.
If copying is performed within the same archive, the input and output save files must not be identical.
If copying is performed within the same backup archive, continuation of the save file is prohibited.
If copying is performed between a backup or long-term archive and the assigned shadow archive (or vice versa), you can only continue a save file if
the archives can contain several save versions per save file (SAVE-FILE-STRUCTURE=*SEVERAL-SVID).
the SFID of the output save file is the same as the SFID of the input save file.
all SVIDs to be duplicated are later than all SVIDs already contained in the output save file.
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. The target location depends on the original archive type.
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.
TO-STORAGE = *S1-STORAGE-LEVEL
Only for backup archives and long-term archives:
The save file is to be copied to the global S1 pubset or special S1 volume set, which must have been defined earlier.
The save file is to be copied according to the following rule:
if the target archive is defined in SF-environment, the save file is copied to the global S1 pubset which must have been defined earlier,
if the target archive is defined in SM-environment, the save file is copied to special S1 volume set or to any HSMS-CONTROLLED volume sets depending on the definition in SM-PUBSETS-PARAMETERS of the SM-pubset.
See also operand TO-ARCHIVE-NAME.
TO-STORAGE = *PRIVATE-DISK(...)
Only for backup archives:
The save file is to be copied to private disk. The private disks to be used can be specified. If more than one private disk is specified, all of them must be of the same device type.
VOLUMES = list-poss(150): <vsn 1..6>
List of volume serial numbers of the disks which will be used in this order for copying the save file.
DEVICE-TYPE = STDDISK / <device>
Device type of the private disks. The default setting STDDISK selects the default device type. Only device types known in the system are accepted. In interactive mode, DEVICE-TYPE=? calls up a list of the available device types.
TO-STORAGE = *PUBLIC-DISK(...)
This operand value is only available to the HSMS administrator and only for backup archives and long-term archives and only in an SF pubset environment.
The save file is to be copied to a pubset.
PUBSET-ID = <cat-id>
Catalog ID of the pubset.
TO-STORAGE = *NET-STORAGE(...)
Only for backup archives and long-term archives:
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 =
Defines parameters 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 “CSF#” and the TSN of the calling user task yyyy as follows: CSF#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 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].
WRITE-CHECKPOINTS = *STD / *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 interrupt (INTERRUPTED state).
Unless otherwise specified, the preset value from the archive definition applies.
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 = *STD / *PARAMETERS(...)
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 operands relevant for copying to tape can be modified as follows:
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 ignores the value of this operand in order to avoid irrational tape processing, for example to avoid unloading a tape several times when rewinding it.
DISK-CONTROL =
Defines the parameters which are relevant for copying to disk.
DISK-CONTROL = *STD
The preset values from the definition of the archive within which copying is to take place apply.
DISK-CONTROL = *PARAMETERS(...)
The operands relevant for copying to disk can be modified as follows:
PRIMARY-ALLOCATION = *STD / <integer 36..50331645 2Kbyte >
Size in PAM pages of the primary allocation for save file creation on disk (see the description of the CREATE-FILE command in the manual “Commands” [5]).
Unless otherwise specified, the preset value from the archive definition applies.
SECONDARY-ALLOCATION = *STD / <integer 0..32767 2Kbyte >
Size in PAM pages of the secondary allocation for save file extension on disk (see the description of the CREATE-FILE command in the manual “Commands” [5]).Unless otherwise specified (*STD), the preset value from the archive definition applies.
Values from 1 through 35 are not permitted.
WRITE-CHECK = *STD / *YES / *NO
Specifies whether a read-after-write check is to be performed after each write operation for error detection purposes. Note that read-after-write checking will result in longer execution times.
Unless otherwise specified, the preset value from the archive definition applies.
DESTROY-BY-DELETE = *STD / *YES / *NO
Specifies whether the storage space released by save file deletion is to be erased by overwriting it with binary zero for data privacy reasons. Note that erasure by overwriting will result in longer execution times for save file deletion.
Unless otherwise specified, the preset value from the archive definition applies.
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.
Notes
For backup and migration archives, the following rules must be observed:
The NEW-CATALOG-ID suboperand must agree with the destination environment to which the save files are copied. This means that the specification NEW-CATALOG-ID=*STD has the following meaning depending on the source and destination environment:
SF
SMy
SF
*STD means: *SAME
*STD means: NEW-CATALOG-ID = y
SMx
The statement is rejected because no SF pubset may be selected.
The catalog ID of an SF pubset must be explicitly specified.*STD means: NEW-CATALOG-ID = y
SF: single-feature environment
SMx: SM pubset with catalog ID x
SMy: SM pubset with catalog ID yThe ARCHIVE-NAME operand must designate an archive that is defined in the same environment as the selected files/job variable, i.e.
if the catalog ID which was taken from the SELECT-FILES/SELECT-JV operand, is the ID of an SM pubset, the source archive must be defined in that SM pubset; otherwise the HSMS statement is rejected.
if the catalog IDs which were taken from the SELECT-FILES/SELECT-JV operand, are the IDs of SF pubsets, the source archive must be defined in the SF pubset environment; otherwise the HSMS statement is rejected.
This catalog ID can be specified explicitly in the SELECT-FILES/SELECT-JV operand or taken from the default values of the user ID. If the HSMS administrator specifies *ALL in these operands, the specification is changed to *ALL-SF-PUBSET and the archive must be defined in the SF pubset environment.
For long-term archives, the NEW-CATALOG-ID suboperand must agree with the destination environment to which the save files are copied. This means that the specification NEW-CATALOG-ID=*STD has the following meaning depending on the source and destination environment:
SF
SMy
SF
*STD means: *SAME
*STD means: NEW-CATALOG-ID = y
SMx
*STD means: *SAME
*STD means: NEW-CATALOG-ID = y
SF: single-feature environment
SMx: SM pubset with catalog ID x
SMy: SM pubset with catalog ID yIt is always the request and ARCHIVE checkpoint file of the destination environment that is accessed because
only in that environment are the default values for the selection of the output volume valid.
this enables write access only to files of the destination environment (the directory, checkpoint and request files are not updated in the source environment).
Example
The HSMS administrator copies a save file to S2; the TSN is 5678
//COPY-SAVE-FILE ARCHIVE-NAME=sys.arc.backup, - // OPERATION-CONTROL=*PAR(EXPRESS-REQUEST=*YES)
All files and job variables of the last save file from the specified backup archive are copied to a new save file on S2 (e.g. in a save run to an S1 pubset not performed during the tape session).
The file is saved to volumes from the volume pool of the archive and to the standard save file of the archive. The save file is given a new time stamp.
The request receives the name CSF#5678.
The request is processed synchronously as an express request.
Depending on the global HSMS parameter OUTPUT a summary report is printed or sent as an email attachment.