Operands
Privilege ADA, administrator without domains
The UPDATE-MAREN-CATALOG statement updates the MAREN catalog in the event of inconsistencies such as a defective or lost catalog or offline logging.
This statement and complete information from the logging files are used to update the MAREN catalog.
If the MAREN catalog is defective or lost, a backup version must first be read in (this may have been created with COPY-VOLUME-CATALOG). The existing MAREN catalog can be processed after offline logging.
The UPDATE-MAREN-CATALOG statement also enables information from a HSMS archive or ARCHIVE directory to be added to the MAREN catalog. In the process, entries for tapes which do not yet exist can be created, and entries for existing tapes can be updated.
Format
UPDATE-MAREN-CATALOG Alias: UPMC | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
INPUT =
Specifies what information is to be added to the MAREN catalog.
INPUT = *BY-LOGGING(...)
The MAREN catalog is to be updated from one or more logging files. The logging files of all systems in the MAREN network must be specified simultaneously in the statement. Only in this way it can be guaranteed that catalog entries which were processed on different systems are updated consistently. This applies in particular when offline logging entries are revised.
The two operands START-DATE and START-TIME are used to specify the time the MAREN catalog is saved or copied and also the time when offline logging is enabled. Then only logging records which were created from this time on are taken into account. By default all logging records of the specified logging file(s) are evaluated.
LOGGING-FILE = list-poss(99): <filename 1..54>
Name of one or more ISAM files containing MAREN logging records. When multiple files are specified, the logging records are sorted automatically while processing is in progress.
START-DATE = 0000-01-01 / <date>
Start date in the format yyyy-mm-dd.
START-TIME = 00:00:00 / <time>
Start time in the format hh[:mm[:ss]], where initial zeros need not be entered for hh, mm and ss.
INPUT = *BY-HSMS(...)
The MAREN catalog is to be updated with the data from an HSMS archive.
ARCHIVE-NAME = <filename 1..22 without-gen-vers>
Name of the HSMS archive.
ENVIRONMENT =
Specifies the HSMS environment in which the archive was defined.
ENVIRONMENT = *STD
The HSMS archive was defined in the standard environment for DMS archives.
ENVIRONMENT = *NODE-STD
The HSMS archive was defined in the standard environment for node archives.
ENVIRONMENT = *SINGLE-FEATURE
The HSMS archive was defined in the SF pubset environment.
ENVIRONMENT = *SYSTEM-MANAGED(...)
The HSMS archive was defined in the specified SM pubset environment.
CATALOG-IDENTIFIER = <cat-id 1..4>
Catalog ID of the SM pubset.
ACTION =
Specifies how the information is to be added to the MAREN catalog.
ACTION = *ADD(...)
The archive numbers which are contained in the HSMS archive are to be added to the MAREN catalog.
USER-IDENTIFICATION = <name 1..8>
User ID to which the tapes are assigned.
FREE-POOL =
Specifies the free tape pool to which the tapes are assigned.
FREE-POOL = *NO
The tapes are assigned to the *NO free tape pool.
FREE-POOL = *GLOBAL
The tapes are assigned to the free tape pool *GENERAL.
FREE-POOL = *TSOS
The tapes are assigned to the free tape pool *TSOS.
FREE-POOL = <filename 1..54 without-gen-vers>
The tapes are assigned to the free tape pool for HSMS/ARCHIVE applications using the directory which must be specified here. If the directory is not located under the home ID, both the user ID and the catalog ID must also be specified.
FREE-POOL = <text 2..32 without-sep>
Name of an existing free tape pool to which the tapes are assigned.
ACCOUNT = *NONE / <alphanum-name 1..8>
Account number for the user ID specified under USER-IDENTIFICATION. When *NONE is specified, no account number is noted in the catalog entry.
FREE-DATE = *STD / <date with-compl> / <integer 0..32767>
Release date. Up to this date, the tape remains reserved for the given user ID. When *STD is specified, the default expiration date entered with MODIFY-MAREN-PARAMETERS is entered. If an integer is entered instead of a date, this number is added to the current date to calculate the release date. If the EXPIRATION-DATE contained in the input file for the relevant archive number is greater than the release date specified or calculated, the FREE-DATE field in the catalog entry is supplied with the value from EXPIRATION-DATE.
HOME-LOCATION = CENTRAL / <alphanum-name 1..8>
Location at which the tape is generally stored. The default value is CENTRAL, i.e. the tape is located in the central archive if it is not currently being processed.
FREE-LOCATION = CENTRAL / <alphanum-name 1..8>
Location at which the tape is stored after it has been released. The default value is CENTRAL, i.e. the tape is located in the central archive as long as it is not reserved.
TEMPORARY-LOCATION = CENTRAL / <alphanum-name 1..8>
Current location of the tape. The default value is CENTRAL, i.e. the tape is currently in the central archive.
INITIALIZATION = *YES / *NO / *ERASE
Specifies whether the tape is to be initialized after release. The default value is *YES, i.e. the tape must be initialized before it is reserved again. *ERASE initializes the tape and erases the tape contents up to the end of the tape.
USER-ACCESS = *OWNER-ONLY / *FOREIGN-READ-ONLY / *ALL-USERS
Specifies whether foreign user IDs have read access only to the tape (FOREIGN-READ-ONLY) or whether they have write access also (ALL-USER). The default value is OWNER-ONLY, i.e. no access is permitted from foreign user IDs.
ACTION = *MODIFY(...)
The archive numbers of the tapes contained in the HSMS archive are to be updated in the MAREN catalog if the catalog entry already exists there.
The specifications for the USER-IDENTIFICATION, FREE-POOL, ACCOUNT, FREE-DATE, HOME-LOCATION, FREE-LOCATION, TEMPORARY-LOCATION, INITIALIZATION and USER-ACCESS operands are added to the catalog if a value other than the default *UNCHANGED is entered. For a description of this operand, see ACTION=*ADD(...).
EXPIRATION-DATE = *FROM-HSMS / *UNCHANGED
Specifies whether the expiration date of a tape from the HSMS archive should be included in the MAREN catalog entry concerned. The expiration date is included only if it is earlier than the expiration date entered in the catalog. If this is the case, the catalog entry will also indicate that the tape must be initialized before it can be reserved again for further use.
INPUT = *BY-ARCHIVE(...)
The MAREN catalog is to be updated with the data from an ARCHIVE directory.
INQUIRE-LIST = <filename 1..54 without-gen-vers>
Name of an ARCHIVE input file with all catalog entries of the ARCHIVE directory. This input file must be created using the ARCHIVE statement INQUIRE.
ACTION =
Specifies how the information is to be added to the MAREN catalog.
ACTION = *ADD(...)
The archive numbers contained in the ARCHIVE directory are to be added to the MAREN catalog.
USER-IDENTIFICATION = <name 1..8>
User ID to which the tapes are assigned.
FREE-POOL =
Specifies the free tape pool to which the tapes are assigned.
FREE-POOL = *NO
The tapes are assigned to the *NO free tape pool.
FREE-POOL = *GLOBAL
The tapes are assigned to the free tape pool *GENERAL.
FREE-POOL = *TSOS
The tapes are assigned to the free tape pool *TSOS.
FREE-POOL = <filename 1..54 without-gen-vers>
The tapes are assigned to the free tape pool for HSMS/ARCHIVE applications using the directory which must be specified here. If the directory is not located under the home ID, both the user ID and the catalog ID must also be specified.
FREE-POOL = <text 2..32 without-sep>
Name of an existing free tape pool to which the tapes are assigned.
ACCOUNT = *NONE / <alphanum-name 1..8>
Account number for the user ID specified under USER-IDENTIFICATION. When *NONE is specified, no account number is noted in the catalog entry.
FREE-DATE = *STD / <date with-compl> / <integer 0..32767>
Release date. Up to this date, the tape remains reserved for the given user ID. When *STD is specified, the default expiration date entered with MODIFY-MAREN-PARAMETERS is entered. If an integer is entered instead of a date, this number is added to the current date to calculate the release date. If the EXPIRATION-DATE contained in the input file for the relevant archive number is greater than the release date specified or calculated, the FREE-DATE field in the catalog entry is supplied with the value from EXPIRATION-DATE.
HOME-LOCATION = CENTRAL / <alphanum-name 1..8>
Location at which the tape is generally stored. The default value is CENTRAL, i.e. the tape is located in the central archive if it is not currently being processed.
FREE-LOCATION = CENTRAL / <alphanum-name 1..8>
Location at which the tape is stored after it has been released. The default value is CENTRAL, i.e. the tape is located in the central archive as long as it is not reserved.
TEMPORARY-LOCATION = CENTRAL / <alphanum-name 1..8>
Current location of the tape. The default value is CENTRAL, i.e. the tape is currently in the central archive.
INITIALIZATION = *YES / *NO / *ERASE
Specifies whether the tape is to be initialized after release. The default value is *YES, i.e. the tape must be initialized before it is reserved again. *ERASE initializes the tape and erases the tape contents up to the end of the tape.
USER-ACCESS = *OWNER-ONLY / *FOREIGN-READ-ONLY / *ALL-USERS
Specifies whether foreign user IDs have read access only to the tape (FOREIGN-READ-ONLY) or whether they have write access also (ALL-USER). The default value is OWNER-ONLY, i.e. no access is permitted from foreign user IDs.
ACTION = *MODIFY(...)
The archive numbers of the tapes contained in the ARCHIVE directory are to be updated in the MAREN catalog if the catalog entry already exists there.
The specifications for the USER-IDENTIFICATION, FREE-POOL, ACCOUNT, FREE-DATE, HOME-LOCATION, FREE-LOCATION, TEMPORARY-LOCATION, INITIALIZATION and USER-ACCESS operands are added to the catalog if a value other than the default *UNCHANGED is entered. For a description of this operand, see ACTION=*ADD(...).
EXPIRATION-DATE = *FROM-ARCHIVE / *UNCHANGED
Specifies whether the expiration date of a tape from the ARCHIVE directory should be included in the MAREN catalog entry concerned. The expiration date is included only if it is earlier than the expiration date entered in the catalog. If this is the case, the catalog entry will also indicate that the tape must be initialized before it can be reserved again for further use.
Catalog update with logging files
As the statement accesses the MAREN catalog directly, it can be executed under any user ID which has direct access to the MAREN catalog.
The MAREN catalog is updated which has been assigned to the MARENCP task via the link name MARENCAT.
The files specified in the LOGGING-FILE operand must have the file and record format defined for the logging files.
Old logging files can also always be processed when the MAREN catalog is updated. To ensure that the MAREN catalog is updated properly, however, all processed logging files must be consistent. No file may be forgotten. Nevertheless, it makes sense to specify the exact time the backup copy of the MAREN catalog was produced or offline logging was switched on in order to prevent superfluous logging records from being included in processing.
At the start of this statement, the MARENADM statement CLOSE-MAREN-FILES is issued implicitly in order to temporarily prevent all user access to the MAREN catalog. Since the CLOSE-MAREN-FILES statement only affects the local system, it must also be entered for all other systems which use the same MAREN catalog. Additionally, all other MARENADM program runs must be terminated if they keep the MAREN catalog open in direct access mode. Once the update is complete, the catalog lock set for the user's own system and for all other systems on which CLOSE-MAREN-FILES was entered must now be lifted by means of the OPEN-MAREN-FILES statement. This can also be done by specifying the HOST-NAME=*ALL operand.
If multiple logging records exist for a catalog entry, only the most recent one is used to update the MAREN catalog. When MAREN is operating with multiple systems, it is consequently necessary that the times on the various systems be set as syncrhonously as possible.
The logging records generated during offline logging are likewise evaluated.
Finally, a message is issued indicating the number of catalog entries updated.
In shared mode, for performance reasons the UPDATE-MAREN-CATALOG statement should only be executed on the system with the MAREN catalog.
If the statement is to be executed by a remote system in the MAREN network which does not have direct access to the MAREN catalog, a connection to the system with the MAREN catalog must be set up beforehand using the SET-RFA-CONNECTION command.
During the update procedure, no new logging records are created.
Updating the catalog from the HSMS archive or ARCHIVE directory
Tape entries from an HSMS archive or an ARCHIVE directory can be entered as new entries in the MAREN catalog or update entries which already exist there. In the case of an HSMS archive, MAREN takes over the entries directly (entry in the ARCHIVE-NAME operand). In the case of an ARCHIVE directory, the entries must be available as a file, in the form of an INQUIRE list which must be created in advance using ARCHIVE (entry in the INQUIRE-LIST operand).
New entry (ACTION=*ADD)
All tapes contained in the specified HSMS archive or in the ARCHIVE directory are added to the MAREN catalog (ACTION=ADD is the default setting). Information for the individual catalog entry fields is taken from the following sources:
HSMS archive or ARCHIVE-INQUIRE list
The following catalog entry fields are occupied from this:
Catalog entry field
Meaning
VOLUME
Tape VSN
DEVICE-TYPE
Device type
CREATION-DATE
File creation date (from SVID if available)
CREATION-TIME
File creation time (from SVID if available)
EXPIRATION-DATE
Reservation period of the tape if SVID contains RETPD, otherwise the same value as CREATION-DATE.
Operand values entered by the user (or their default values)
For the “new entry” function, the USER-IDENTIFICATION operand must be specified together with the name of the HSMS archive or ARCHIVE-INQUIRE list.
If the reservation period of the tape specified in the HSMS archive or ARCHIVE-INQUIRE list as EXPIRATION-DATE is greater than the date specified in the FREE-DATE operand, FREE-DATE is supplied with the value from EXPIRATION-DATE.
Default values of MAREN
The VOLUME-STATUS is set to RESERVED, for instance, and the catalog entry field RESERVATION-DATE is supplied with the current date.
When domains are used, all tapes are added to the user’s own domain.
If a catalog entry already exists for an archive number, MAREN checks the catalog entry fields assigned to individual operands (e.g. USER-ACCESS) to see whether they match the values specified by the user (or the default values):
If all catalog entry fields match the specified operands (or their default values), processing continues with the next archive number. This is designed to ensure that new entry jobs can be restarted if they are aborted (restart capability).
If, however, any of the catalog entry fields differs from the specified operands (or their default values), execution is terminated.
As soon as the catalog entry field which was complained about has been corrected with MODIFY-VOLUME-ATTRIBUTES, this new entry can be continued with UPDATE-MAREN-CATALOG.
MAREN logs each catalog entry which is added and then outputs a totals line.
“Modify” function (ACTION=*MODIFY)
The catalog entries in the MAREN catalog are updated for all tapes contained in the specified HSMS archive or in the ARCHIVE-INQUIRE list.
In the case of operands with the value *UNCHANGED, the corresponding catalog entry field remains unchanged.
Execution is aborted in the following cases:
No catalog entry exists in the MAREN catalog for a given archive number.
The tape has a VOLUME-STATUS other than RESERVED.
An ARCHIVE directory was specified in the FREE-POOL operand and one of the catalog entries contains a different directory name.
MAREN logs each catalog entry which is modified and then outputs a totals line.
Examples
Example 1
The MAREN catalog is updated with the information from the logging file MAREN.LOGGING:
//upd-mar-cat log-file=maren.logging
|
Example 2
In a data center, all three systems are interconnected in shared mode to form a MAREN network. The MAREN catalog has been destroyed as a result of a disk fault. Since the logging files have been set up on other disks, they still exist. Using the backup of the MAREN catalog from the previous day together with the logging files, an updated MAREN catalog is to be created.
After the MARENCP task is started using the MAREN catalog from the day before, the update is initiated:
//upd-mar-cat input=*by-log(log-file=maren.logging.system1,maren.logging.system2,maren.logging.system3)
Example 3
An input file for updating the catalog is to be created from the ARCHIVE directory ARCHIVE.DIR:
/assign-syslst to=lst.inquire.archive.dir |
The name of the file created in this way (here LST.INQUIRE.ARCHIVE.DIR) is specified in the INQUIRE-LIST operand:
/start-marenadm |