── VOLUME ─┬─ ADD ───────┬─<volume name>───────────────────────────────►
├─ CHANGE ────┤
├─ DELETE ────┤
├─ DESTROYED ─┤
├─ OFFSITE ───┤
├─ ONSITE ────┤
└─ RECOVERED ─┘
── ( ──<volume attribute list>── ) ────────────────────────────────────┤┌◄───────────────────────── , ─────────────────────────────────────┐ ──┴┬─ /1*\ ─┬─────────────┬─┬─ DISK ───────────────────────────────┬─┴─┤ │ ├─ KIND ── = ─┘ ├─ PACK ───────────────────────────────┤ │ │ └─ TAPE ───────────────────────────────┤ │ └─ KIND ── = ── # ── <string primary> ─────────────────┤ ├─ /1*\ ── SERIALNO ── = ── <serial number list> ───────────────┤ ├─ /1\ ── FAMILYOWNER ── = ─┬─ "" ──────────────────────────────┤ │ ├─ * ───────────────────────────────┤ │ └─ <usercode> ──────────────────────┤ ├─/1\─ GROUP ── = ─┬─ <name constant> ──────────────────────────┤ │ ├─ # ── <string primary> ────────────────────┤ │ └─ "" ───────────────────────────────────────┤ ├─/1\─┬─ GROUPRWX ─┬─ = ─┬─ NO ─────────────────────────────────┤ │ ├─ OTHERRWX ─┤ ├─ RWX ────────────────────────────────┤ │ └─ OWNERRWX ─┘ ├─ RW ─────────────────────────────────┤ │ ├─ RX ─────────────────────────────────┤ │ ├─ WX ─────────────────────────────────┤ │ ├─ R ──────────────────────────────────┤ │ ├─ W ──────────────────────────────────┤ │ ├─ X ──────────────────────────────────┤ │ └─ # ── <string primary> ──────────────┤ ├─ /1\ ─┬─ GROUPR ────────────┬───┬─────────────────────────────┤ │ ├─ GROUPW ────────────┤ └─ = ── <Boolean expression> ─┤ │ ├─ GROUPX ────────────┤ │ │ ├─ OTHERR ────────────┤ │ │ ├─ OTHERW ────────────┤ │ │ ├─ OTHERX ────────────┤ │ │ ├─ OWNERR ────────────┤ │ │ ├─ OWNERW ────────────┤ │ │ ├─ OWNERX ────────────┤ │ │ ├─ SETGROUPCODE ──────┤ │ │ ├─ SETUSERCODE ───────┤ │ │ ├─ USEGUARDFILE ──────┤ │ │ └─ GUARDOWNER ────────┘ │ ├─ /1\ ─── MATCHONLYSERIALNO ─────┬─────────────────────────────┤ │ └─ = ── <Boolean expression> ─┤ ├─ /1\ ─── PERMANENTLYOWNED ──────┬─────────────────────────────┤ │ └─ = ── <Boolean expression> ─┤ ├─ /1\ ─── SECURITYGUARD ── = ─┬ <file title> ──────────────────┤ │ └─ "" ───────────────────────────┤ ├─ /1\ ─── SECURITYLABELS ────────┬─────────────────────────────┤ │ └─ = ── <Boolean expression> ─┤ ├─ /1\ ─── SECURITYMODE ─── = ── <integer expression> ──────────┤ ├─ /1\ ─── SECURITYTYPE ─── = ── <file mnemonic primary> ───────┤ └─ /1\ ─── SECURITYUSE ──── = ── <file mnemonic primary> ───────┘
Explanation
The VOLUME statement applies to cataloging systems and systems with the tape security subsystem activated. It is used to add, modify, or delete a family description in the cataloging volume library or the tape volume directory.
A cataloging volume library or a tape volume directory is a database containing information on volumes, with one entry per volume family. The cataloging feature provides a method for locating where backup files from disk and tape are stored.
| Note: | Only privileged jobs and jobs started from an ODT can issue a VOLUME command. (The VOLUME CHANGE command is the only exception to this rule.) |
The volume name and the file attributes KIND and SERIALNO are required to identify the family. If the volume name is DISK or PACK, the KIND attribute defaults to DISK and can be omitted. When the volume name includes a <string primary>, embedded periods will terminate the volume name unless the entire name is enclosed in quotes.
For tapes with two-level names (for example, LMTAPE/FILE000), the tape name is the first name.
Options
The following options are available in the VOLUME statement.
Creates an entry in the cataloging volume library and/or the tape volume directory. When an entry for a tape volume is created, the system automatically tracks the changing status of the tape volume. It is not necessary to issue a new VOLUME ADD each time the status of the tape volume changes. The order of the serial numbers in the statement coincides with the order of the volumes in the family (reel number).
The volume family does not need to be online when the VOLUME ADD is executed. However, if the volume family is online, the information in the WFL statement is supplemented by other information stored in the entry, such as the volume creation date.
Serial numbers added to the volume library must be unique for tapes and for disks. The VOLUME ADD request is rejected if an entry in the volume library contains a serial number for a volume (disk or tape) that matches a serial number in the list to be added in the VOLUME ADD request. Therefore, the entry with the conflicting serial number must be deleted from the volume library before the VOLUME ADD request can be executed.
When SCRATCH is specified as the volume name in a VOLUME ADD statement for a tape, it indicates that the volume is a scratch tape (a purged tape) or that SCRATCH is the name of the tape volume.
Changes the tape volume directory entry (but not the cataloging volume library entry) for a tape family. Only the attributes SECURITYGUARD, SECURITYTYPE, SECURITYUSE, SECURITYMODE, and the sub attributes of SECURITYMODE can be changed.
The VOLUME CHANGE statement for tape files is similar to the SECURITY statement for disk files.
VOLUME CHANGE can be used by privileged jobs and for non-privileged jobs with tapes owned by the job.
| Note: | If the VOLUME CHANGE statement is used to alter the SECURITYMODE sub attributes of a tape volume (for example, OWNERRWX, GROUPRWX, and so on), then all of the desired attributes must be specified in the CHANGE request similar to what is required on a VOLUME ADD statement. All SECURITYMODE sub attributes that are omitted from the VOLUME CHANGE request revert back to their default values. |
Deletes entries from the cataloging volume library and/or the tape volume directory. The order that serial numbers appear in the statement does not need to be the order of volumes in the family.
The family must not be in use when the VOLUME DELETE is executed.
Changes the entry for one or more tape volumes in the cataloging volume library and/or the tape volume directory, to show that the volumes are no longer usable. The entry for a volume remains in the cataloging volume library and/or the tape volume directory and can be subsequently deleted.
The archive system in the MCP cannot request tape volumes that are marked as destroyed, unless there are no other backup copies of the requested file.
VOLUME DESTROYED does not affect cataloging information. To cancel the destroyed condition, use the VOLUME RECOVERED statement.
Marks the entry for one or more tape volumes in the cataloging volume library and/or the tape volume directory. This will show that the tape, or tapes, are offsite.
The file search mechanism in the MCP will not request tape volumes that are marked as offsite, unless there are no other backup copies of the requested file on tapes that are not marked as offsite or destroyed.
Marks the entry for one or more tape volumes in the volume library and/or volume directory that are no longer offsite.
| Note: | The default value for a volume when a VOLUME ADD is completed is ONSITE. |
The onsite/offsite status is displayed by the PV and TV system commands and the onsite/offsite status is reported by the SYSTEM/LISTVOLUME and SYSTEM/LISTVOLUMELIB utility programs.
Changes the entries for one or more tape volumes in the catalog volume library or the tape volume directory or both to show that the volumes are no longer considered destroyed.
File Attributes
The following file attributes can be specified in the VOLUME statement:
Specifies a group whose members can access the file in the manner defined by the GROUPRWX attribute. Any process executing with a task GROUPCODE or SUPPLEMENTARYGROUPS that matches the GROUP attribute of the file, and that also does not match as the owner of the file, is granted the access permissions defined by the GROUPRWX attribute. If the GROUP attribute is not set, then group access is not granted to any process attempting to access the file.
When set to TRUE, grants group members read-access to the file.
When set to TRUE, grants group members write-access to the file.
Has no effect for tape volumes.
Specifies the manner in which members of the group matching the group attribute of the file are permitted to access the physical file.
Used in conjunction with the USEGUARDFILE attribute to cause the guard file to define access permissions for the owner of the file.
| Note: | The GUARDOWNER attribute has no effect if the USEGUARDFILE attribute is reset. |
When set to TRUE, grants other users (excluding the owner and members of the group) read-access to the file.
When set to TRUE, grants other users (excluding the owner and members of the group) write-access to the file.
Has no effect for tape volumes.
Specifies the manner in which all other users (excluding the owner and members of the group) are permitted to access the physical file.
When set to TRUE, grants the owner read‑access to the file.
When set to TRUE, grants the owner write‑access to the file.
Has no effect for tape volumes.
Specifies the manner in which the owner of the file is permitted to access the physical file.
When set to true, the system stores the security attributes for files in the tape labels on the tape volume.
A VOLUME statement can be used to set the SECURITYLABELS attribute to TRUE or the PERMANENTLYOWNED attribute to TRUE, but not both. The system will reject a VOLUME statement that specifies both SECURITYLABELS=TRUE and PERMANENTLYOWNED = TRUE.
| Note: | Only one serial number can be specified in the serial number list of the SERIALNO attribute when you use either the SECURITYLABELS or the MATCHONLYSERIALNO attribute. |
Specifies the manner in which users are permitted to access the physical file, including the owner of the file.
The SERIALNO attribute for disks and packs works in a special manner.
The VOLUME ADD statement for a disk or pack family should specify the serial number of the disk with the family index number 1. For multipack families, the serial number of the disk with family index 1 should be specified even if the family has more than one base pack. The serial number of the disk with family index 1 should be specified even if that member no longer has a directory or even if that particular disk has disappeared.
| Note: | Do not use more than one serial number in a list for a disk and pack family specification. |
Has no effect for tape volumes.
Has no effect for tape volumes.
When set to TRUE, a guard file in addition to the SECURITYMODE attribute controls access to the physical file. In order for the guard file to control access to the file completely, all of the file's access permission flags OWNERRWX, GROUPRWX, and OTHERRWX should be set to TRUE.
