Retrieve Tape Labels (QTARTLBL) API
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Device description | Input | Char(10) |
| 5 | Request qualifiers | Input | Char(*) |
| 6 | Length of request qualifiers | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Tape Labels (QTARTLBL) API retrieves the label information for the files on a tape cartridge. This API provides a function similar to the Display Tape (DSPTAP) command.
Authorities and Locks
- Device Description Authority
- *USE
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The content and format of the information being returned.
The RLBL0100 format must be used for the label information. See RLBL0100 Format to view the information returned for this format.
- Device description
- INPUT; CHAR(10)
The name of the tape device or tape library device containing the cartridge for which the label information is to be returned.
- Request qualifiers
- INPUT; CHAR(*)
The request qualifiers specify which cartridge to use, what labels to return, and what action to perform after the label information is retrieved. The following table shows the information that can be specified. Default values are used for any fields that are not specified. For more details about the fields in the following table, see Field Descriptions.
Offset Type Field Dec Hex 0 0 CHAR(6) Requested volume identifier 6 6 CHAR(17) Requested file label 23 17 CHAR(10) Starting file sequence number 33 21 CHAR(10) Ending file sequence number 43 2B CHAR(1) End option 44 2C CHAR(*) Reserved
- Length of request qualifiers
- INPUT; BINARY(4)
The length, in bytes, of the Request qualifiers provided. The following values are allowed:
0 No request qualifiers are provided. 6 Only the requested volume identifier is specified. 23 The requested volume identifier and the requested file label is specified. 33 The requested volume identifier, requested file label, and starting file sequence number is is specified. 43 The requested volume identifier, requested file label, starting file sequence number, and ending file sequence number is specified. 44 or greater All request qualifiers are specified.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
RLBL0100 Format
The following table shows the information that is returned for the RLBL0100 format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Device name |
| 18 | 12 | CHAR(6) | Cartridge ID |
| 24 | 18 | CHAR(80) | Volume Label |
| 104 | 68 | CHAR(1) | Code |
| 105 | 69 | CHAR(1) | Standard label |
| 106 | 6A | CHAR(1) | Leading tape mark |
| 107 | 6B | CHAR(10) | Density |
| 117 | 75 | CHAR(2) | Reserved |
| 119 | 77 | CHAR(1) | Additional label entries |
| 120 | 78 | BINARY(4) | Offset to label information |
| 124 | 7C | BINARY(4) | Number of label information entries |
| 128 | 80 | BINARY(4) | Length of label information entry |
| CHAR(*) | Label information | ||
Label information
The label information. Each label information entry has the following format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(80) | Label 1 |
| 80 | 50 | CHAR(80) | Label 2 |
| 160 | A0 | CHAR(32) | Logical block ID |
| 192 | C0 | CHAR(10) | Sequence number |
| 202 | CA | CHAR(10) | Multi-volume sequence number |
| 212 | D4 | CHAR(8) | S/36 File type |
For more information regarding IBM® standard volume labels and data set labels 1 and 2, select the appropriate topic below:
- IBM standard volume label (VOL1)
- IBM standard data set label 1 (HDR1/EOV1/EOF1)
- IBM standard data set label 2 (HDR2/EOV2/EOF2)
Field Descriptions
Additional label entries. Indicates if there were labels on tape that were not returned because the return data would have exceeded 16,000,000 Bytes. The following values can be returned:
| 0 | No additional label entries. |
| 1 | There were more label entries to return. |
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Cartridge ID. The cartridge identifier for the media. This field will be blanks if the device is not a tape library device.
Code. The encoding used for the data on tape. The following values can be returned:
| 0 | ASCII encoding is used. |
| 1 | EBCDIC encoding is used. |
| blank | Non-labeled tape. |
Density. The density that is used for the data on the tape.
Device name. The tape device or tape library device that was used.
Ending file sequence number. The ending sequence number for which the labels are to be retrieved. When a numeric value is specified it must be left justified and padded with blanks on the right. The ending sequence number can not be less than the starting file sequence number. The following special values are supported:
| *ONLY | Only the file specified by the starting file sequence number will be retrieved, if it matches the specified file label. This is the default value. |
| *LAST | The labels on tape that match the specifed file label are to be retrieved, starting with the file specified by the Starting file sequence number and ending with the last file sequence number on tape. |
| blank | The ending file sequence number will not be used. This value is only valid when the special value *ALL is specified for the starting file sequence number. |
End option. The operation to perform on the tape volume after the retrieve completes. The following special values are supported:
| 0 | Rewind the tape. This is the default value. |
| 1 | Rewind and unload the tape. |
| 2 | Leave the tape at the current position. |
Label 1. The contents of the first trailer label for the file sequence.
Label 2. The contents of the second trailer label for the file sequence.
Leading tape mark. Indicates if the tape was a leading tape mark tape. The following values can be returned:
| 0 | Not a leading tape mark tape. |
| 1 | Leading tape mark tape. |
Length of label information entry. When label information is available this field is set to the length, in bytes, of a single label information entry. A value of zero is returned if the tape is not a standard labeled tape, if there are no labels on the tape, or if the receiver variable is not large enough to hold any label information entries.
Logical block ID. The logical block identifier for the file sequence.
Multi-volume sequence number. The sequence number for the tape volume.
Number of label information entries. If there is room in the receiver variable for 1 or more complete label information entries, this value is set to the number of complete label information entries returned. The Bytes returned value can be used to determine if any partial label information entries were returned.
If there is room in the receiver variable for only part of the first label information entry, this value is set to 1 and it will be necessary to use the Bytes returned value to determine which label information fields are valid.
A value of zero is returned if the tape is not a standard labeled tape, if there are no labels on the tape, or if the receiver variable is not large enough to hold any label information entries.
Note: A maximum of 72,726 entries can be returned.
Offset to label information. The offset, in bytes, to the label information. A value of zero is returned if the tape is not a standard labeled tape, if there are no labels on the tape, or if the receiver variable is not large enough to hold any label information.
Requested file label. The data file label that is to be retrieved. The data file label is a maximum of 17 characters in length and is case sensitive. The following special value is supported:
| *ALL | All file labels within the specified sequence number range are to be retrieved. This is the default value. |
Note: When a specific file label is requested, the label information will only be returned for the first file found that matches the requested file label.
Requested volume identifier. The tape volume for which the labels are to be retrieved. For a tape library device this field should be set to a cartridge identifier to be mounted and used. The following special value is supported:
| blanks | The currently mounted tape cartridge is used. This is the default value. |
Reserved. An ignored field. This field is set to hexadecimal zeros for output fields and must be set to hexadecimal zeros for input fields.
S/36 File type. The System/36™ file type for the file sequence. The following file types can be returned:
- ARCHIVE
- APARFILE
- COPYFILE
- EXCHANGE
- LIBRFILE
- SAVEFLDR
- SAVELIBR
Sequence number. The file sequence number.
Standard label. Indicates if the tape was a standard labeled tape. The following values can be returned:
| 0 | Non-labeled tape. |
| 1 | Standard labeled tape. |
Starting file sequence number. The starting sequence number for which the labels are to be retrieved. When a numeric value is specified it must be left justified and padded with blanks on the right. The following special values are supported:
| *ALL | All labels on tape are to be retrieved that match
the specified file label.
Note: When this value is used the ending file sequence number must be set to blanks. |
| *FIRST | The labels on tape that match the specified file label are to be retrieved, starting with the first file label. This is the default value. |
Volume label. The volume label read from the tape. This field is set to blanks for a non-labeled tape.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C3C E | Value for parameter &1 is not valid. |
| CPF3C4B E | Value not valid for field &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF4108 E | Media error on volume &8 device &4. |
| CPF4119 E | Device &4 cannot process loaded volume. |
| CPF4120 E | Device &4 or an attached gateway device reported a hardware failure. |
| CPF4121 E | Interface error while using device &4. |
| CPF412C E | Cartridge &6 not found. |
| CPF412D E | Cartridge not available. |
| CPF412F E | Cartridge &6 not available. |
| CPF414C E | Command not allowed. |
| CPF414E E | Library device &5 not ready. |
| CPF414F E | Library device storage slots full. |
| CPF415A E | *MOUNTED not correct. |
| CPF415E E | Resource request timed out on device &4. |
| CPF416A E | No device available. |
| CPF41B3 E | No more volumes to mount from catalog. |
| CPF41B4 E | Virtual tape volume not available. |
| CPF41B5 E | Virtual tape volume not found. |
| CPF6708 E | Command ended due to error. |
| CPF6718 E | Cannot allocate device &1. |
| CPF6720 E | Incorrect volume &2 found on device &1. |
| CPF6721 E | Device &1 not a tape device. |
| CPF6723 E | File not found on volume &2 on device &1. |
| CPF6724 E | File label &5 not found on volume &2. |
| CPF6725 E | Ending file sequence number less than starting sequence number. |
| CPF673A E | Device &3 not varied on. |
| CPF6751 E | Load failure occurred on device &4. |
| CPF6760 E | Device &1 not ready. |
| CPF6772 E | Volume on device &1 cannot be processed. |
| CPF67E6 E | Volume &2 not correct. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9814 E | Device &1 not found. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R3
[ Back to top | Backup and Recovery APIs | APIs by category ]