This statement is used for modifying an archive directory. The following modifications are possible:
deleting save files
- deleting and changing retention period of save files
- modifying supplementary information in a save version
- with version backup archives, files can be marked for deletion. The files are then deleted from the archive later during a reorganization.
managing a volume pool
Only the HSMS administrator and the archive owner are authorized to make modifications in the archive directory.
This statement has different formats for nonprivileged users and HSMS administrators. Privileged operands are marked with *P).
Format
MODIFY-ARCHIVE | Alias: MDA | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
*P) Privileged operand
ARCHIVE-NAME =
Archive whose directory is to be modified.
The specified archive must already exist.
Only the HSMS administrator and the archive owner are authorized to make modifications in the archive directory.
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. When using another user’s archive, the HSMS administrator does not require write privileges.
ARCHIVE-NAME = *BY-DIRECTORY-NAME(...)
The specification of the operand value *BY-DIRECTORY-NAME is allowed only, in case a save file needs to be deleted or its retention period needs to be changed and there is no archive definition (e.g. save file which was created with EXPORT-FILES using a directory file).
DIRECTORY-NAME = <filename 1..54 without-gen-vers>
Path name of the directory file.
ARCHIVE-NAME = <filename 1..22 without-cat-gen-vers>
Name of the archive whose directory is to be modified.
ENVIRONMENT =
Determines the HSMS environment in which the specified archive is located.
ENVIRONMENT = *STD
The archive is in the default environment for DMS archives:
For privileged users: *STD is set to the value *SINGLE-FEATURE.
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 = *NODE-STD
The archive is located in the default environment for node archives:
For privileged users: *NODE-STD is set to the value *SINGLE-FEATURE.
For nonprivileged users: *NODE-STD is set to the value of the environment in which the home directory of the user is defined.
ENVIRONMENT = *SINGLE-FEATURE
The archive is in the SF environment.
ENVIRONMENT = *SYSTEM-MANAGED(...)
The archive is in the specified SM pubset environment.
CATALOG-ID = <cat-id>
Catalog ID of the SM pubset to which the HSMS statement applies.
FILES = *UNC HANGED / *MARK-FOR-DELETION(…) / *FORCE-DELETION(…) / *REMOVE-DELETION-MARKS(…)
Only an HSMS administrator can specify actions for the operand.
This option specifies the handling of files within version backup archives. For other types of archives only the option *UNCHANGED must be specified.
FILES = *MARK-FOR-DELETION (…)
This operand is used to mark files for deletion from a version backup archive. The files are then later removed from the archive as part of a reorganization.
Only files that have already been deleted from the processing level are flagged for deletion. This is checked with CHECK-CATALOGED-FILES: if it is recognized that files of the version backup archive no longer exist on the pubsets, the current date is entered as the deletion date in the archive directory. Moreover, the deletion flag can be set with a security deadline achieved (DELETED-BEFORE= *STD).
FILE-NAMES =
Specifies the files are to be marked for deletion from version backup archive. The user can further restrict the selection made here by means of other operands.
FILE-NAMES = *OWN
All files under the user’s own ID in the archive are to be marked for deletion.
FILE-NAMES = *ALL
All files from all pubsets are to be marked for deletion.
FILE-NAMES = *SELECTED
The path names of the files are to be taken from a list that was compiled within the same HSMS run by means of the HSMS statement SELECT-FILE-NAMES.
FILE-NAMES = *FROM-FILE(...)
The path names of the files 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. Only upper-case characters may be used. The list file can be created, for instance, by means of the HSMS statement SELECT-FILE-NAMES or the DMS command SHOW-FILE-ATTRIBUTES.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
FILE-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the files are taken from a PLAM library element (type S). The library element consists of records of variable length and 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.
FILE-NAMES = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the files 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 with the catalog ID which is taken either from the specified environment or from the default catalog ID of the user ID.
The files can alternatively be selected using wildcards. The wildcards are replaced in accordance with the file names listed in the archive directory.
DELETED-BEFORE =
Restricts selection of the files which are being marked for deletion according to the date when they were recognized as deleted from processing level S0.
DELETED-BEFORE=*STD
The minimum time that a file should have been recognized as deleted in order it can be marked for deletion is defined in the archive attribute. If not specified by an administrator: 180 days is the standard value.
DELETED-BEFORE=*LATEST
All selected files which were recognized as deleted from S0 are marked for deletion.
DELETED-BEFORE=<date with-compl>
Only those selected files are marked for deletion, which were recognized as deleted from S0 before the given date.
DELETED-BEFORE = <integer -99999..0 days>
Minimum number of days that a file should have been recognized as deleted in order it can be marked for deletion. Value ‘0’ means file have been recognized as deleted TODAY or any day earlier.
FILES = *FORCE-DELETION(…)
To provide force deletion of all versions of the specified files from version backup archive during the next reorganization, the files are marked respectively. The action is only relevant for files which have not been detected as removed from processing level (i.e. files for which no deletion date was provided in the archive).
Note
In case a BACKUP-FILE-VERSIONS or CHECK-CATALOGED-FILES for the files will follow such a MODIFY-ARCHIVE, the mark will be switched off automatically and thus there is no impact of the MODIFY-ARCHIVE on the following reorganization for the files.
FILE-NAMES =
Specifies the files are to be forced as obsolete and thus removing from the version backup archive during the following reorganization run completely. It means all file versions will be removed irrespectively to the value of number of backup versions stored in the directory.
FILE-NAMES = *OWN
All files under the user’s own ID in the archive are to be marked for deletion.
FILE-NAMES = *ALL
Save versions of all files residing on all pubsets are to be marked for deletion.
FILE-NAMES = *SELECTED
The path names of the files are to be taken from a list that was compiled within the same HSMS run by means of the HSMS statement SELECT-FILE-NAMES.
The files to be processed must be available in the specified environment.
FILE-NAMES = *FROM-FILE(...)
The path names of the files 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. Only upper-case characters may be used. The list file can be created, for instance, by means of the HSMS statement SELECT-FILE-NAMES or the DMS command SHOW-FILE-ATTRIBUTES.
The files to be processed must be available in the specified environment.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
FILE-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the files are taken from a PLAM library element (type S). The library element consists of records of variable length and 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.
FILE-NAMES = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the files 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 with the catalog ID which is taken either from the specified environment or from the default catalog ID of the user ID.
The files can alternatively be selected using wildcards. The wildcards are replaced in accordance with the file names listed in the archive directory.
FILES = *REMOVE-DELETION-MARKS(…)
For selected files the “mark for deletion” marks for recognized as deleted files or “force-deletion” marks for existing files are switched off. In case some of selected files actually was not marked, no changes are done for them. A list of files that have been umarked is written to the report. In case no files corresponds the selection criteria, a warning message is issued.
FILE-NAMES =
The operand provides selection of files.
FILE-NAMES = *OWN
The “mark for deletion” marks are switched off for all files under the user’s own ID in the archive.
FILE-NAMES = *ALL
The “mark for deletion” marks are switched off for all files residing on all pubsets.
FILE-NAMES = *SELECTED
The path names of the files are to be taken from a list that was compiled within the same HSMS run by means of the HSMS statement SELECT-FILE-NAMES.
The files to be processed must be available in the specified environment.
FILE-NAMES = *FROM-FILE(...)
The path names of the files 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. Only upper-case characters may be used. The list file can be created, for instance, by means of the HSMS statement SELECTFILE-NAMES or the DMS command SHOW-FILE-ATTRIBUTES.
The files to be processed must be available in the specified environment.
LIST-FILE-NAME = <filename 1..54 without-gen-vers>
Path name of the list file.
FILE-NAMES = *FROM-LIBRARY-ELEMENT(...)
The path names of the files are taken from a PLAM library element (type S). The library element consists of records of variable length and 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.
FILE-NAMES = list-poss(20): <filename 1..80 without-vers-with-wild> / <partial-filename 2..79 with-wild>
The path names of the files 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 with the catalog ID which is taken either from the specified environment or from the default catalog ID of the user ID.
The files can alternatively be selected using wildcards. The wildcards are replaced in accordance with the file names listed in the archive directory.
SAVE-VERSIONS = *UNCHANGED / *MODIFY-USER-RECORD(...)
Entries for save versions in the archive can be modified.
Only the archive owners, HSMS administrator and the owner of the save version may modify entries for save versions in the archive.
Entries for save versions within version backup archives cannot be modified. Any attempts are rejected.
SAVE-VERSIONS = *MODIFY-USER-RECORD(...)
Not allowed for version backup archives.
The entries for save versions in the archive are modified.
SAVE-VERSION-NAME = *ANY / <name 1..8>
The save version to be modified can be selected via the name assigned to it at creation.The option of selecting save versions that were created by other users is restricted to the HSMS administrator.
Unless otherwise specified, the save versions are selected irrespective of their names.
SAVE-VERSION-DATE =
The save version to be modified can be selected via its creation date.
If a save version was selected via its name, only those save versions having this name are selected via the creation date.
SAVE-VERSION-DATE = *LATEST
Only the most recently created save version in the archive is to be modified.
SAVE-VERSION-DATE = *INTERVAL(...)
You can restrict the save versions to be modified by defining the period within which they have to have been created.
CREATED-BEFORE = *LATEST-DATE / <date with-compl> / <integer -99999..0 days >
Only save versions created on or before the date specified are modified.
CREATED-AFTER = *EARLIEST-DATE / <date with-compl> /<integer -99999..0 days >
Only save versions created on or after the date specified are modified.
SAVE-VERSION-DATE = <date with-compl>(...)
The last save version created on or before the specified date is to be modified.
TIME = 23:59:59 / <time>
The last save version created at or before the specified date and time is modified.
NEW-SV-NAME = *UNCHANGED / <name 1..8>
The name of the save version can be modified.
DESCRIPTOR = *UNCHANGED / <c-string 1..10>
The descriptor can be modified.
USER-INFORMATION = *UNCHANGED / <c-string 1..720>
Comments on the save version can be modified.
FILE-EXPIRATION-DATE = *UNCHANGED / <date with-compl> / <integer 0..99999 days >
The expiration date for the archived files can be modified. The specified date can lie beyond the physical retention period of the save files or backup volume only if permitted by the archive definition.
SAVE-FILES = *UNCHANGED / *DELETE(...) / *RETENTION-PERIOD(...)
The entries for archive save files can be modified.
Only the archive owner and the HSMS administrator are authorized to delete save files from the archive or to extend the retention period.
SAVE-FILES = *DELETE(...)
The specified save files are to be deleted explicitly from the archive. The entries for the save files are deleted from the directory and the save files erased from disk. Tapes containing deleted save files are released.
Unless otherwise specified, only the obsolete save files are deleted, i.e.
- save files whose retention period has expired and which do not contain any save versions whose file expiration date has not yet been reached or
- save files of version backup archives, which do not contain any still “valid” file versions (not OBSOLETE according to the file attribute number of backup versions and not marked for deletion).
Using SHOW-ARCHIVE, the archive owner can request output of the save versions whose file expiration date has not yet been reached.
Using SHOW-ARCHIVE ... SELECT=*FILES (INFORMATION = *VERSION), you can check whether file versions are “valid” (not OBSOLETE according to the file attribute number of backup versions).
Note
In addition to the explicit deletion of save files with release of the volumes, save files and save versions – controlled by the archive attribute AUTOMATIC-DELETION= *OBSOLETE-SAVE-FILES – can also be deleted implicitly: Whenever a backup or copy operation to the archive is initiated by the archive owner obsolete save files in the archive are deleted. The automatic release means that a closed loop is also created for the volumes used. Further information is provided under the AUTOMATIC-DELETION operand of the CREATE-ARCHIVE and MODIFY-ARCHIVE-ATTRIBUTES statements.
SAVE-FILE-ID = *BY-ATTRIBUTES(...)
Serves to select the save files to be deleted using their file attributes as the selection criterion.
Deletion is additionally subject to the specification for the FORCED-DELETE operand.
SAVE-FILE-STATE = *ANY
The save files are to be deleted irrespective of their state.
SAVE-FILE-STATE = *OBSOLETE
Restricts deletion to save files whose retention period has expired and whose save versions have all reached their expiration date.
CREATED-BEFORE = *LATEST-DATE
The save files are to be deleted irrespective of whether they were created before a specific date.
CREATED-BEFORE = <date with-compl> / <integer -99999..0 days >
Selects the files to be deleted according to the specified date: Only save files created on or before the specified date are to be deleted.
SAVE-FILE-ID = list-poss(10): <composed-name 15..15>
Serves to select the save files to be deleted using the save file ID as the selection criterion. The save file ID is specified in the format S.yymmdd.hhmmss
FORCED-DELETE =
Determines whether non-obsolete save files whose retention period has not yet expired or which contain save versions whose file expiration date has not yet been reached can nevertheless also be deleted forcibly.
FORCED-DELETE = *NO
The save files are not to be deleted forcibly. Only save files in the state OBSOLETE will be deleted.
Save files which contain data from currently migrated files will not be deleted from a migration archive.
Save files containing any “valid” file versions (not obsolete according to the file attribute number of backup versions and not marked for deletion) will not be deleted from a version backup archive.
FORCED-DELETE = *YES
The save files are to be deleted forcibly. Volumes containing the save file which are part of the archive-specific volume pool are retained in the directory and are assigned the state FORCED-DELETE.
Volumes with the attribute OWNER=*OPERATOR are removed from the directory together with the save file.
Note for version backup archives: the save files are to be deleted regardless if their save versions contains any not obsolete file versions according to the file attribute number of backup versions.
From HSMS V12.0E, the warning message ARC0824 is issued at the console for each save file deleted with this option.
SAVE-FILES = *RETENTION-PERIOD(...)
Serves to extend the retention period for the specified save files.
SAVE-FILE-ID = *BY-ATTRIBUTES(...)
Serves to select the save files using their file attributes as the selection criterion.
SAVE-FILE-STATE = *ANY
The save files are selected irrespective of their state.
SAVE-FILE-STATE = *OBSOLETE
Restricts selection to save files whose retention period has expired.
CREATED-BEFORE = *LATEST-DATE
The save files are selected irrespective of whether they were created before a specific date.
CREATED-BEFORE = <date with-compl> / <integer -99999..0 days >
Selects the save files to be deleted according to the specified date: only save files created on or before the specified date are selected.
SAVE-FILE-ID = list-poss(10): <composed-name 15..15>
Serves to select the save files using the save file ID as the selection criterion. The save file ID is specified in the format S.yymmdd.hhmmss
RETPD-EXTENSION = <-16383..16383 days >
Number of days by which the current retention period of the selected save files is to be extended or – when a negative value is specified – reduced. The maximum reduction here is up to the current date.
Note for backup archives
By extending or reducing the retention period for a save file it can later occur that the references between the incremental backups in a save file and the full backups in another save file are lost.
Note for migration and version backup archives
It is recommended to have retention period of save files in version backup archives so that it corresponds to how often you will do a reorganization run.
For version backup archives, retention period of a save file created by reorganization will be taken from the archive attributes.
VOLUMES = *UNCHANGED / *ADD(...) / *REMOVE(...)
This operand may only be used by archive owners and HSMS administrators. Serves to modify the archive-specific volume pool.
VOLUMES = *ADD(...)
Volumes are added to the free volume pool of the archive.
Note
If you are using MAREN you can ignore pool management by HSMS and utilize the more flexible management by MAREN. For further information, see the “HSMS Vol. 1” manual [1], section “Volume pool management”.
VOLUMES = list-poss(600): <vsn 1..6>
The specified VSNs are to be added.
DEVICE-TYPE = *STD / <device>
Device type of the volumes, must belong to the “TAPE” class. 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.
VOLUMES = *REMOVE(...)
Serves to remove volumes from the archive-specific free volume pool.
VOLUMES =
The specified volumes are to be removed from the pool.
VOLUMES = *AVAILABLE
All free volumes are to be removed from the pool.
VOLUMES = list-poss(600): <vsn 1..6>
The specified volumes are to be removed provided they have the status AVAILABLE.
DIRECTORY-LOCK = *UNCHANGED / *TEST / *REMOVE(...)
This operand may only be used by archive owners and HSMS administrators.
This operand makes sense only for node or version backup directories. Either displays the logical lock or removes the logical lock.
DIRECTORY-LOCK = *TEST
Outputs the current lock information.
DIRECTORY-LOCK = *REMOVE(...)
Removes a known lock from a node directory.
HOST-NAME = <alphanum-name 1..8>
BCAM name of the host thought to have set the lock.
The directory lock is only removed if the name is entered correctly.
This operand is intended to ensure that the function is not used unintentionally.
TSN = <alphanum-name 1..4>
TSN name of the task thought to have set the lock.
This operand is intended to ensure that the function is not used unintentionally.
DIRECTORY-LOCK = *UNLOCK-VERSION-DIR
Removes the following locks from a version backup directory:
- the lock could not be reset during the abnormal termination of a version backup process
- the lock could not be reset during the abnormal termination of a reorganization process
- the lock from the archive directory that was restored after //REORGANIZE-VERSION-BACKUP with SAVE-DIRECTORY = *YES
REPORT =
Serves to define whether a report is to be output and to determine the scope of this report. The report is output to SYSLST.
REPORT = *SUMMARY
A summary of the results, including any error messages, is to be output.
REPORT = *FULL
A report, including a list of all actions performed, is to be printed.
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 all the actions performed is printed out.
OUTPUT = *MAIL
The report 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 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 all the actions performed is 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.