Operands

The table lists the TAPEMOD operands.

Table 1. List of operands for TAPEMOD command
Operand Description
VOL volspec Volspec is a space-delimited list of one or more volume specifications. A volume specification can be a single volume identifier or a volume range. For more details on how to specify ranges, refer to TAPEADD
volid Volid is a volume identifier. A volume identifier can be one to six characters. No edit checking is performed on the characters within the volid, but embedded blanks are not valid.
volid1-volid2 Volid1-volid2 is a volume identifier range. A range specification is only valid for numeric values in the right-most part of the volume identifier. If the left-most part contains non-numeric data, all of the following conditions must be met:
  • The non-numeric data must be identical for volid1 and volid2.
  • The identifiers must be of equal length.
  • The numeric portion of volid1 must be less than the numeric portion of volid2.

For example, RA0001-RA0050 and 000001-000050 are valid ranges, but RA0001-RX0050 ("RA" and "RX") and 00001-000050 (one has five digits, the other has six) are not valid ranges.

Minus_sign ( - ) As of PTF UI48913, the minus sign with at least one space on both sides ( - ) is an exclusion operator. Volumes following the minus sign will be excluded from the list of volumes to be processed. A minus sign cannot be the first operator in a volume specification and only a single occurrence is permitted. For example, VOL V00000-V00005 - V00003-V00004 is equivalent to volumes V10001 V10002 V10005. Note that a minus sign connected to a VOLSER on one side with a space on the other side is never valid.
FILE filespec
Specifies a file, filespec, that contains one or more volume serial numbers. The filespec includes:
  • fname, which is the name of the file to be processed, and
  • ftype, which is the type of file to be processed.
When the FILE operand is specified, the file can contain multiple records. Each record in the file can contain multiple, space-delimited volume specifications and, optionally, a single exclusion character followed by volume specifications of any volumes that are to be excluded.

You can use the FM or VADDR option of the TAPCMD command to specify the location of the file.

POOL powner pname Specifies an existing pool. All tapes in the pool are modified as specified.
QRY QEND As of PTF UI48913, allows you to specify TAPEQRY parameters that result in a list of volumes that is processed by the TAPEMOD command. Both QRY and QEND must be specified. The specification can be any valid parameters and operands of the TAPEQRY command except SHORT, LONG, MSG, RDR, and TERSE. All tapes in the result set from the query are processed, unless LIST is specified immediately before the QEND delimiter. In that case, no volumes are processed and information for the volumes that otherwise would have been processed is sent to the requestor. See TAPEQRY for additional information. See "Example of using QRY QEND parameters" below.
LIST As of PTF UI48913, lists the volumes that would otherwise have been processed if LIST had not been specified. When LIST is specified, it must be the last parameter before QEND; otherwise, it will be treated as a TAPEQRY parameter. No processing occurs when LIST is specified. The information returned is in the same format as a TAPEQRY command with SHORT specified.
MEDIA mtype Indicates the media type that will be used for device compatibility checking.
STATUS FREE Sets the use status of a volume to FREE. See "Understanding volume attributes and hold conditions" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
STATUS USED Sets the use status of a volume to USED. See "Understanding volume attributes and hold conditions" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
HSTAT HOLD Sets the user hold value to HOLD. See "Understanding volume attributes and hold conditions" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
HSTAT NOH Sets the user hold value to NOHOLD. See "Understanding volume attributes and hold conditions" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
SSTAT NOH Sets the system hold value to NOHOLD. See "Understanding volume attributes and hold conditions" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
SSTAT hval Clears the hold flag associated with the two-character hold value. See Hold Flag values for SSTAT operand below for more details. See "Understanding volume attributes and hold conditions" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
NODSE Specifies that DSE (data security erase) processing is not required after the volume expires and before the volume is returned to scratch status.
DSE Specifies that DSE (data security erase) processing is required after the tape volume expires and before the volume is returned to scratch status.

It is the responsibility of the site to ensure that the DSE processing occurs and that the DSE flag is cleared once the DSE is completed. The TMDSE utility provided in Tape Manager can be used to perform this processing and clear the flag. For more information on TMDSE, refer to TMDSE.

INT Designates a volume as an INTERNAL volume. This is the default. See "Understanding volume attributes and hold conditions" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
EXT Designates the tape as EXTERNAL or foreign volumes. An external tape must be added directly to a private pool. At that point, it can be mounted for READ/WRITE, but it will never be used as a free (i.e. scratch) tape for the pool.
Note: EXT is not valid with POOL SYS.
EXPDATE yyyymmdd Sets the year, month, and day after which a tape will become a free tape if it is not in HOLD status.
EXPDAYS nnnnn Specifies the number of days, from one to five digits, after which a tape will become a free tape if there are no conditions (such as a user hold) that will cause the expiration process to be bypassed. A value of EXPDAYS -1 can be specified to trigger selection of the volume when the expiration process next runs; otherwise, the value must be a non-negative integer. See "Understanding expiration processing and scratch tapes" in the IBM Tape Manager for z/VM Installation and Administration Guide (SC18-9344) for additional information.
LIB MAN libname Indicates that this is a manually mounted tape. Optionally, you may specify a 1- to 16-character library name to be displayed on mount requests.
LIB ATL libname Indicates that this tape is in an automated tape library (ATL). Optionally, you may specify a 1- to 16-character library name to be used for RMS requests. If a library name is not provided, RMS requests are issued without a library name.
EJECT Specifies that the volume is to be ejected from the ATL and the library type is set to MAN with no library name. If the LIB parameter is also specified, the library type and name are set to the value in the LIB parameter.
EJECT RETAIN Specifies that the volume is to be ejected from the ATL and the library type and name are not to be altered. If the LIB parameter is also specified, the library type and name are set to the value in the LIB parameter.
TEXT <usertext> or TEXT 'usertext' Specifies up to 32 bytes of user data in the volume catalog entry. The field must be delimited by the less-than (<) and greater-than (>) characters or by single quotes (' ').

The text field will be cleared if a TAPEMOD command is used to change the volume use-status from USED to FREE. If a used volume expires, the text field will be retained until the expired volume is next mounted with WRITE access.

TERSE Suppresses the informational messages EUM0010I, EUM0074I, EUM0083I, EUM0084I, EUM0288I, and EUM0291I for the requestor.

Hold Flag values for SSTAT operand

With PTF UI54509, the SSTAT field was modified from a one-byte character field, which was used for mutually exclusive hold values, to a one-byte field of flag bits, where each bit represents an independent hold flag. When any of the bit flags are set, the TAPEQRY output will show an "H" in the SSTAT field.

When the structure of the field was modified, the output of the LONG form of the TAPEQRY command was extended to show the status of the independent hold flags. For code levels that support the independent hold flags, the hold values that are reported with TAPEQRY LONG, and that can be reset to no hold with hval, are listed below:

VF - TMVERIFY flag
The VF flag will be "H" if the volume data was modified by the TMVERIFY utility. Mount requests are allowed. The volume is not an eligible scratch volume.
NV - No Volume flag
The NV flag will be "H" if a TAPEREQ command has been issued with the NOVOL parameter. Mount requests are allowed. The volume is not an eligible scratch volume.
NI - Not in Library flag
The NI flag will be "H" if a scratch request to an automated library received a Not-In-Library response. Mount requests are allowed. The volume is not an eligible scratch volume.
NM - No Match flag
The NM flag will be "H" if the volume was mounted by an automated library for a scratch request and the internal label does not match the VOLSER. Mount requests are allowed. The volume is not an eligible scratch volume.
NL - No Label flag
The NM flag will be "H" if the volume was mounted by an automated library for a scratch request and the volume is unlabeled. Mount requests are allowed. The volume is not an eligible scratch volume.
RO - Read Only flag
The RO flag will be "H" if the volume was mounted by an automated library for a scratch request and the volume is read-only. Mount requests are allowed. The volume is not an eligible scratch volume.
UK - Unknown flag
The UK flag will be "H" if there was a non-specific SSTAT hold prior to the update for flag independent bit flags. Mount requests are allowed. The volume is not an eligible scratch volume.
VC - Volume Category flag
The VC flag will be "H" if an attempt to set the category of the volume to the Volume Category could not be verified. No mounts are allowed and the volume is not an eligible scratch volume.
XH - Expire Hold flag
The XH flag will be "H" if for volumes that are within an Expire Hold period associated the media Scratch Category.

Example of using QRY QEND parameters

The following example demonstrates the use of QRY and QEND to set the User Hold Status to HOLD for all volumes in the SYSTEM BACKUP pool that have a VOLSER which begins with P and have a User Hold Status of NOHOLD. When using QRY and QEND, first use the LIST parameter before the QEND parameter to see what volumes will be affected when the LIST parameter is removed.

TAPEMOD QRY VOL P* POWNER SYSTEM PNAME BACKUP HSTAT NOHOLD QEND HSTAT HOLD

The parameters between QRY and QEND are passed to TAPEQRY, which supports regular expressions such as P* for VOLID. The volumes in the list generated by TAPEQRY are then modified, unless LIST is specified immediately before QEND. In that case, the volumes in the list that would otherwise have been modified are listed and no modifications occur.