CHKTAP (Check Tape)

CHKTAP Command syntax diagram

 

Purpose

The Check Tape (CHKTAP) command searches a volume on the specified device for a unique volume identifier and/or file label. If the correct tape is on the device, the user may process this file on the next tape operation by specifying the same sequence number that was specified in the CHKTAP command. If the correct tape is not found, an escape message is sent, and the tape is rewound regardless of the end option specified. A check for this message in a CL program can direct the logic flow if the correct tape is on the device.

If a volume identifier is specified in the command, the volume identifier of the tape is compared with the volume identifier of the command. If a match is not found on the tape, an escape message is sent. This message contains the volume identifier found on the tape. If the correct volume identifier is found or if no volume identifier is specified in the command, and a sequence number is specified, that sequence number is located on the tape. For a standard labeled tape, the sequence number is determined from the header label of the file. For a tape that is not labeled, the sequence number is determined from the number of tape markers from the beginning-of-tape marker. If the sequence number is not found, an escape message is sent.

If the sequence number specified on the command is found and a label was specified, the file identifier in the header label is compared with the value in the LABEL parameter. The LABEL parameter is valid only for a standard-label tape. If the tape is a standard-label tape and the file label at that sequence number does not match the value in the LABEL parameter, an escape message is sent. This message contains the date the file was created and the file label for the file at that sequence number. If a match is found and a date is not specified in the command, the file is found. If the correct file identifier is found and a date is specified in the command, the date in the header label is compared with that of the command. If a match exists, the correct file is found. If there is not a match, an escape message is sent. This message contains the file label and the date that the file at that sequence number was created.

If SEQNBR (*SEARCH) is specified, a value for the LABEL parameter must be specified. The file label for each file on tape is checked for the LABEL parameter until a match is found. If the file is not found, an escape message is sent.

If the sequence number specified on the command is found and a LABEL parameter was not specified but the CRTDATE parameter was, the date in the header label for the file at the sequence number is compared with the date value in the CRTDATE parameter. If the dates do not match, an escape message is sent. The CRTDATE is valid only for standard label tape.

Note: The values in the command parameters are compared with the values on the tape in the following order:

  1. Volume identifier

  2. Sequence number

  3. File identifier in the header label at the sequence number specified

  4. File creation date in the header label at the sequence number specified

The tape is checked for each parameter only if the parameters before it in the list are found on the tape or were not specified in the command.

 

Required Parameters

DEV
Specifies the name of the device where the volume is being checked. Specify the name of the tape or media library device.

 

Optional Parameters

VOL
Specifies one or more volume identifiers used by the file. More information on this parameter is in Commonly used parameters.

Note: If the device specified is a media library device, then the volume specified should be the cartridge identifier to be mounted and used.

*MOUNTED: The volume currently placed in the device is used. For a media library device, the volume to be used is the next cartridge in the category mounted by the Set Tape Category (SETTAPCGY) command.

volume-identifier: If the device specified in the DEV parameter is a stand-alone tape device, specify the volume identifier of the labeled volume. The volume identifier read from the tape is compared to this value. If the volume identifier specified is not found on the tape, an escape message is sent. If the device specified in the DEV parameter is a library device device description, specify the cartridge identifier of the volume to be used.

SEQNBR
Specifies whether a check is made for a specific sequence number of a data file on the tape. For standard-labeled tapes, this is the sequence number in the file header label. For tapes that are not labeled, this is the sequence number determined from the number of tape markers from the beginning of tape.

*NONE: No check is made for a file on this volume.

*FIRST: A check is made for the first file on this volume.

*NEXT: A check is made for the next file on this volume. If the current sequence number is at the beginning of the volume, this value checks the first file on that volume.

*SEARCH: A data file is searched for that has an identifier that matches the LABEL parameter value. If the last tape operation on the device specified ENDOPT(*LEAVE), the file search begins with the first data file beyond the current tape position. If ENDOPT(*LEAVE) was not used for the last tape operation, or if the tape was manually rewound since an ENDOPT(*LEAVE) operation, the search begins with the first data file on the volume. SEQNBR(*SEARCH) cannot be specified when LABEL(*NONE) is also specified, and cannot be used to check a volume that is not labeled. An escape message is sent if the file is not found. If the sequence number is not found on the tape, an escape message is sent.

file-sequence-number: Specify the sequence number of the file that is used. Valid values range from 1 through 9999.

LABEL
Specifies whether a label identifier is checked. If a label is specified, a sequence number must be specified for the SEQNBR parameter.

*NONE: No check is made for a label identifier on the tape. LABEL(*NONE) and CRTDATE(*NONE) must be specified for a volume that is not labeled.

file-label: Specify the identifier (17 characters maximum) of the data or save/restore file to check. If a label is specified, a sequence number must be specified for the SEQNBR parameter. The file identifier of the file at that sequence number is compared with the label identifier specified by this parameter. If the label does not match, a message is sent.

CRTDATE
Specifies whether the date on which the file was created is checked. If SEQNBR(*NONE) is specified, CRTDATE(*NONE) must also be specified.

*NONE: The date on which the file was created is not checked. CRTDATE(*NONE) and LABEL(*NONE) must be specified for a volume that is not labeled.

file-creation-date: Specify the date that must match the date of the file being checked. The date must be entered in the format specified for the system values QDATFMT and, if separators are used, QDATSEP. If the date of the file being checked does not match the date specified by this parameter, an escape message is sent.

ENDOPT
Specifies the operation that is automatically performed on the tape volume after the operation ends. If more than one volume is included, this parameter applies only to the last tape volume used; all other tape volumes are rewound and unloaded when the end of the tape is reached.

*LEAVE: The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive.

*REWIND: The tape is rewound, but not unloaded.

*UNLOAD: The tape is rewound and unloaded.

Examples for CHKTAP

Example 1: Checking the Volume Identifier 

CHKTAP  DEV(TAPE1)  VOL(TAPEVOL)

This command checks the volume identifier of the volume on the tape device TAPE1. If the volume identifier on the tape is TAPEVOL, the command completes normally and no message is sent. If the volume identifier on the tape is not TAPEVOL, an escape message is sent.

Example 2: Checking for a Specific Sequence Number 

CHKTAP  DEV(TAPE2)  VOL(VOLID)  SEQNBR(5)
  LABEL(FILE5)  CRTDATE('1/9/84')

This command checks the volume on the tape device TAPE2 for a volume identifier of VOLID. If that volume is found, sequence number 5 is located on the tape (it must be a standard-labeled tape). The sequence number in the file label is used to position to sequence number 5. If the sequence number is found and the header label contains both the file identifier FILE5 and the date of 1/9/84, the correct tape and file has been found, and a completion message is sent. The next tape operation can specify sequence number 5 to access this file without positioning the tape. If the specified volume is not found or the tape is not a standard labeled volume, an escape message is sent. If the volume is found and the sequence number is not found, an escape message is sent. If the file label at that sequence number is not FILE5, an escape message is sent. If the date at that sequence number is not 1/9/84, an escape message is sent.

Error messages for CHKTAP

*ESCAPE Messages

CPF6708
Command ended due to error.
CPF6718
Cannot allocate device &1.
CPF6720
Incorrect volume &2 found on device &1.
CPF6721
Device &1 not a tape device.
CPF6728
LABEL(*NONE) CRTDATE(*NONE) required for nonlabeled volume.
CPF6734
File sequence number &3 not found on volume &2.
CPF6735
Label ID &6 not found at &3.
CPF6736
Creation date &6 not found at &3.
CPF6737
Label &4 not found on volume &2.
CPF6745
Device &1 not a media library device.
CPF6751
Load failure occurred on device &4.
CPF6752
SEQNBR(*FIRST) or SEQNBR(*NEXT) is not valid.
CPF6760
Device &1 not ready.
CPF6772
Volume on device &1 cannot be processed.
CPF67E6
Volume &2 is not correct
CPF9814
Device &1 not found.
CPF9825
Not authorized to device &1.