Privilege ADA, administrator without domains
This statement generates a MAREN catalog entry for a tape which is assigned to a user ID but is not registered in the MAREN catalog.
Format
ADD-RESERVED-VOLUME Alias: ADRV | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
VOLUME =
Tapes to be added to the MAREN catalog.
VOLUME = <vsn>(...)
Archive number.
USER-IDENTIFICATION = <name 1..8>
User ID to which the volume is to be assigned.
ACCOUNT = *NONE / <alphanum-name 1..8>
Account number of the specified user ID.
PROTECTION =
Tape protection attributes.
PROTECTION = *STD
The default values listed below are used.
PROTECTION = *PARAMETERS(...)
Specifies the protection attributes.
PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> /
<integer -2147483648..2147483647> / *SECRET
Password protecting tapes against unauthorized access.
PASSWORD = *NONE
No password is specified.
PASSWORD = *SECRET
Requests a blanked out input field for the password. Entries in this field are not visible on the screen.
This operand value can only be specified in unguided dialog. In guided dialog, the field provided for entering passwords is always blanked out.
USER-ACCESS =
Specifies whether foreign user IDs may access the tape.
USER-ACCESS = *OWNER-ONLY
Access to the tape is possible only under the specified user ID.
USER-ACCESS = *FOREIGN-READ-ONLY
Only read access to the tape is possible under a foreign user ID.
USER-ACCESS = *ALL-USERS
Unrestricted access to the tape is possible under a foreign user ID.
FREE-DATE =
Expiration date of the tape. Up to this date, the tape remains reserved for the given user ID.
FREE-DATE = *STD
The reservation period defined by the MAREN administrator applies.
FREE-DATE = <date>
Date in the format yyyy-mm-dd.
FREE-DATE = <integer 0..32767 days >
Time specification in days. MAREN internally adds this number to the current date to generate the expiration date.
LOCATION =
Location name or symbolic location name.
LOCATION = *STD
The default values listed below are used.
LOCATION = *PARAMETERS(...)
HOME-LOCATION = CENTRAL / <alphanum-name 1..8>
Location name or symbolic location name. Specifies the location where the tape is normally to be stored.
FREE-LOCATION = CENTRAL / <alphanum-name 1..8>
Location name or symbolic location name. Specifies location where the tape is to be relocated when it is transferred to the pool of free tapes after the reservation period has expired.
TEMPORARY-LOCATION = CENTRAL / <alphanum-name 1..8>
Location name or symbolic location name. Specifies the tape’s current location. Archive system locations are not permitted here (does not apply for locations with the operating mode ROBAR-2).
REMARK = *NONE / <c-string 1..24>
Comment text. This catalog entry field is output in response to the MAREN statement SHOW-VOLUME-ATTRIBUTES.
USER-FIELD = *NONE / <c-string 1..54>
Comment text. This catalog entry field may contain any user-specific data, e.g. name, department.
ADMINISTRATOR-FIELD = *NONE / <c-string 1..8 with-low>
Comment text. This field may contain internal information. This catalog entry field cannot be read or changed by the user.
DEVICE-TYPE =
Device type.
DEVICE-TYPE = *STD
The tapes are of the default device type (DEFAULT-DEVICE-TYPE) whose value was specified with the MODIFY-MAREN-PARAMETERS statement.
DEVICE-TYPE = <structured-name 1..8>
Device type. For a list of possible entries (depending on the BS2000 version), see manual “System Installation” [6].
DIRECTORY-NAME =
Determines whether the tape is assigned to a directory.
DIRECTORY-NAME = *NONE
The tape is not assigned to a directory.
DIRECTORY-NAME = <filename 1..54 without-gen-vers>
Name of a directory to which the tape is assigned. If this directory is located under a remote user ID, both the user ID and the catalog ID must be entered. The user's own user ID and standard catalog ID can be omitted.
FILE-NAME = *NONE / <filename 1..41 without-cat-user>
Name of the file located on the tape.
FILE-SEQUENCE = 1 / <integer 1..9999>
File sequence number of a file within a file set (multifile/multivolume set).
VOLUME-SEQUENCE = 1 / <integer 1..255>
File section number within a multivolume file (MV set).
NEW-DOMAIN =
Domain to which the tape is to be assigned.
NEW-DOMAIN = *STD-DOMAIN
The tape is assigned to the standard domain.
NEW-DOMAIN = *OWN
The tape is assigned to the user’s own domain. The user’s own domain is the domain of the system on which the ADA is currently working.
NEW-DOMAIN = <alphanum-name 1..8>
The tape is assigned to the specified domain.
VOLUME = *ALL(...)
The VSNs of the volumes to be added are to be taken from a file of a domain.
INPUT-FILE = <filename 1..54>
Name of a SAM file containing catalog entries in MAREN format. For instance, this may be an output file created using the SHOW-VOLUME-ATTRIBUTES statement.
DOMAIN =
The tapes of the specified domain are selected.
DOMAIN = *BY-INPUT-FILE
The catalog entries are taken from the domain or domains whose names are contained in a SAM file.
DOMAIN = *OWN
The catalog entries of the user’s own domain are selected. The user’s own domain is the domain of the system on which the ADA is currently working.
DOMAIN = *STD-DOMAIN
The catalog entries of the standard domain are selected.
DOMAIN = <alphanum-name 1..8>
The tapes of the specified domain are selected.
NEW-DOMAIN = *STD-DOMAIN / *OWN / *UNCHANGED / <alphanum-name 1..8>
The tapes are assigned to the specified domain.
VOLUME = *BY-TSOSCAT(...)
The archive numbers of the tapes to be added are to be taken from the catalog entries for tape files in the file catalog (TSOSCAT). In this case the MAREN administrator must work under the user ID TSOS.
SELECT =
Criteria for tape selection.
SELECT = *ALL
No restrictions apply to the tapes to be added.
SELECT = *BY-ATTRIBUTES(...)
Only those tapes which fulfill all the following conditions are added.
FROM = *FIRST / <vsn>
Only those tapes whose archive numbers are greater than or equal to the one specified here are added.
FROM = *FIRST
All tapes are added, starting with the lowest available archive number.
TO = *LAST / <vsn>
Only those tapes whose archive numbers are less than or equal to the one specified here are added.
TO = *LAST
All tapes are added up to the highest existing archive number.
PUBLIC-VOLUME-SET =
Specifies the catalog ID of the pubset from whose file catalog for tape files the archive numbers of the tapes to be added to the MAREN catalog are to be taken.
PUBLIC-VOLUME-SET = *ALL
The tapes are taken from the file catalogs of all the available pubsets.
PUBLIC-VOLUME-SET = *HOME
The tapes are only taken from the file catalog of the home pubset.
PUBLIC-VOLUME-SET = <cat-id>
The tapes are taken from the file catalog of the specified pubset.
USER-IDENTIFICATION =
Specifies whether the tapes to be added are to be selected by user ID.
USER-IDENTIFICATION = *ALL
The IDs are not evaluated during selection.
USER-IDENTIFICATION = <name 1..8>
Only tapes from the file entries for tape files under the specified user ID are to be added to the MAREN catalog.
ACCOUNT = *NONE / <alphanum-name 1..8>
Account number for the tapes to be added.
PROTECTION =
Protection attributes for the tapes.
PROTECTION = *STD
The default values listed below are used.
PROTECTION = *PARAMETERS(...)
USER-ACCESS =
Specifies whether foreign user IDs may access the tape.
USER-ACCESS = *OWNER-ONLY
Access to the tapes is possible only under the specified user ID.
USER-ACCESS = *FOREIGN-READ-ONLY
Only read access to the tapes is possible under a foreign user ID.
USER-ACCESS = *ALL-USERS
Unrestricted access to the tapes is possible under a foreign user ID.
FREE-DATE =
Expiration date of the tape. Up to this date, the tape remains reserved for the given user ID. If the date specified here is earlier than the file expiration date in the TSOSCAT entry, the tape expiration date is replaced by the corresponding file expiration date.
FREE-DATE = *STD
The reservation period defined by the MAREN administrator applies.
FREE-DATE = <date>
Date in the format yyyy-mm-dd.
FREE-DATE = <integer 0..32767 days >
Time specification in days. MAREN internally adds this number to the current date to generate the expiration date.
LOCATION =
Location name or symbolic location name.
LOCATION = *STD
The default values listed below are used.
LOCATION = *PARAMETERS(...)
HOME-LOCATION = CENTRAL / <alphanum-name 1..8>
Location name or symbolic location name. Specifies the location where the tape is normally to be stored.
FREE-LOCATION = CENTRAL / <alphanum-name 1..8>
Location name or symbolic location name. Specifies location where the tape is to be relocated when it is transferred to the pool of free tapes after the reservation period has expired.
TEMPORARY-LOCATION = CENTRAL / <alphanum-name 1..8>
Location name or symbolic location name. Specifies the tape’s current location.
ADMINISTRATOR-FIELD = *NONE / <c-string 1..8 with-low>
Comment text. This field may contain internal information. This catalog entry field cannot be read or changed by the user.
DOMAIN = *OWN / *STD-DOMAIN / <alphanum-name 1..8>
The tapes are assigned to the specified domain.
Notes
The tapes have the catalog entry field VOLUME-STATUS = RESERVED. Catalog entries for free tapes can only be created by means of the statements ADD-FREE-VOLUMES and IMPORT-FOREIGN-VOLUME.
The FILE-NAME and DIRECTORY-NAME operands may not be entered simultaneously.
The date on which the user’s own tapes are entered in the MAREN catalog for the first time is stored in the catalog entry field REGISTRATION-DATE. The statement MODIFY-VOLUME-ATTRIBUTES enables the MAREN administrator to update the date. The date is output using the SHOW-/PRINT-VOLUME-ATTRIBUTES statement.
If the specified expiration date is earlier than the current date or the catalog entry already exists, the statement is aborted with an error message and the spin off is triggered.
Notes on adding catalog entries by means of a file:
The values for VOLUME, FILE-SEQUENCE, VOLUME-SEQUENCE, CHECK-COUNT, ACCESS-COUNT, and RESERVATION-COUNT in the catalog entries to be added are checked for syntax errors.
The expiration date is not checked.
Passwords with the contents C'$$$$' are converted to NONE (X'00000000').
Each catalog entry added is acknowledged.
If a catalog entry already exists, the catalog entry from the input file is not added. Instead, the spin off mechanism is triggered and the statement is continued.
The sum total of records read and catalog entries added is logged.
If an archive system location is specified in the TEMPORARY-LOCATION catalog entry field, this is replaced by the value “CENTRAL” (does not apply for storage locations with the operating mode ROBAR-2).
If the assigned input file also contains catalog entries of free and foreign tapes, these are likewise added to the MAREN catalog.
A MAREN catalog must have a FREE-POOL record for all free tape pools that have been allocated tapes. These FREE-POOL records are set up when starting MAREN. Such records are produced during operation when needed. However, this is not guaranteed when expanding the MAREN catalog beyond one file. The MAREN administrator must take care of this, and we recommend the following procedure:
SHOW-MAREN-PARAMETERS allows the creation of a list of FREE-POOL records of the catalog containing the catalog entries having to be transferred to the target catalog via a file.
All FREE-POOL records in this list that are not already in the target catalog are then added to it. This is done with the
MODIFY-MAREN-PARAMETERS FREE-POOL=*PAR(FREE-POOL=<name>,ACTION=*ADD)statement.The catalog entries from the file are added to the target catalog (with the statement ADD-RESERVED-VOLUME).
All FREE-POOL records that were added in the second step although they were superfluous are deleted with the
MODIFY-MAREN-PARAMETERS FREE-POOL=*PAR(FREE-POOL=<name>,ACTION=*REMOVE)statement.
Notes on adding tapes from TSOSCAT entries for tape files:
The operand VOLUME = *BY-TSOSCAT allows a MAREN catalog to be created from all available entries for tape files in TSOSCAT when MAREN is first installed. The operands PUBLIC-VOLUME-SET and USER-IDENTIFICATION allow for selection by catalog or user ID. Because access is permitted to archive entries of foreign user IDs, it makes sense to use this function only under the systems support user ID. Any attempt to execute this statement under a nonprivileged ID will be rejected.
As only the file catalogs of the user’s own system are used for evaluation, this statement must be executed on each system in the MAREN network.
The catalog entries for temporary tape files are ignored, i.e. the tapes contained in such entries are not added to the MAREN catalog.
All tapes added to the MAREN catalog are logged. If any of the tapes found in the TSOSCAT entries are already contained in the MAREN catalog, an attempt to add them again is rejected.
After the statement has been terminated, the number of tapes added to the MAREN catalog is output.
Examples
//add-reserved-volume vol=id0101(user-id=user1,account=hol1,free-date=+100,dev-type=tape-c4,remark='Reserved by ADM')
|
This statement is used to enter a tape with device type TAPE-C4 under the user ID USER1 in the MAREN catalog. A reservation period of 100 days is defined for the tape. The remark field informs the user that the reservation was made by the administrator.
|
The tape with the archive number idx002 is archived under the user ID user2 with the account number acc801. The tape is protected against unauthorized access with the password 'xtst'. The user can access the tape and the catalog entry (e.g. to change the password) if he/she knows the password and enters a corresponding ADD-PASSWORD command.
//add-reserved-volume vol=*all(input-file=list.volume.3)
|
All catalog entries found in the file list.volume.3 are added to the MAREN catalog. Since the catalog already contains two of the catalog entries, only 18 entries out of a total of 20 are added.
//add-reserved-volume vol=*by-tsoscat(select=*by-attr(from=tls001,to=tls001,pub-vol-set=*home,user-id=userxy01),account=mrsy0004,prot=*par(user-access=foreign-read,free-date=2020-12-31),location=*par(home-loc=robtls,free-loc=robtls),adm-field='12345678')
|
All tapes contained in the TSOSCAT entries for tape files under the user ID userxy01 are added to the MAREN catalog and reserved for this user ID.