| 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 | Requested cartridge ID | Input | Char(6) |
| 6 | Requested category | Input | Char(18) |
| 7 | Error code | I/O | Char(*) |
The Retrieve Cartridge Information (QTARCTGI) API retrieves a list of the cartridges in a tape library device and their attributes. This API provides a function similar to the Display Tape Cartridge (DSPTAPCTG) command.
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.
Note: With the exception of the first cartridge information entry, only complete cartridge information entries will be returned.
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.
The content and format of the information being returned.
The RCTG0100 format must be used for the cartridge information. See RCTG0100 Format to view the information returned for this format.
The name of the tape library device containing the cartridge(s) for which the data is to be returned.
The cartridge or cartridges for which the data is to be returned. This parameter is used in conjunction with the Requested category parameter to filter the data that is returned. This parameter can contain a specific cartridge identifier, or a generic name of a cartridge identifier. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. A generic name specifies all cartridge identifiers with names that begin with the generic prefix. The following special value is also supported:
The category name and system for which the data is to be returned. This parameter is used in conjunction with the Requested cartridge parameter to filter the data that is returned. The requested category has two parts:
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table shows the information that is returned for the RCTG0100 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 | BINARY(4) | Offset to cartridge information |
| 12 | C | BINARY(4) | Number of cartridge information entries |
| 16 | 10 | BINARY(4) | Length of cartridge information entry |
| CHAR(*) | Cartridge information | ||
The current cartridge attributes. Each cartridge 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(6) | Cartridge ID |
| 6 | 6 | CHAR(6) | Volume ID |
| 12 | C | CHAR(10) | Tape library name |
| 22 | 16 | CHAR(10) | Category |
| 32 | 20 | CHAR(8) | Category system |
| 40 | 28 | CHAR(10) | Density |
| 50 | 32 | CHAR(7) | Change date |
| 57 | 39 | CHAR(6) | Change time |
| 63 | 3F | CHAR(7) | Reference date |
| 70 | 46 | CHAR(6) | Reference time |
| 76 | 4C | CHAR(10) | Location |
| 86 | 56 | CHAR(1) | Location indicator |
| 87 | 57 | CHAR(2) | Volume status |
| 89 | 59 | CHAR(17) | Owner ID |
| 106 | 6A | CHAR(1) | Write protection |
| 107 | 6B | CHAR(1) | Code |
| 108 | 6C | CHAR(1) | Cartridge ID source |
| 109 | 6D | CHAR(1) | Import/Export slot |
| 110 | 6E | CHAR(2) | Media type |
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 cartridge.
Cartridge ID source. The type of cartridge ID. The following values can be returned:
| 0 | The volume identifier is used for the cartridge ID. |
| 1 | The cartridge ID is generated by the system. |
| 2 | The cartridge ID was read from the bar code label on the cartridge. |
Category. The category assigned to the cartridge.
Category system. The name of the system that owns the category assigned to the cartridge.
Change date. The date the cartridge was last used for output operations. The date is returned with the following format - CYYMMDD. If no change date is available the field is set to blanks.
Change time. The time the cartridge was last used for output operations. The time is returned with the following format HHMMSS. If no change time is available the field is set to blanks.
Code. The encoding used for the data on tape. The following values can be returned:
| blank | The encoding is unknown. |
| 0 | ASCII encoding is used. |
| 1 | EBCDIC encoding is used. |
Density. The last known cartridge density. If the density is unknown the field is set to blanks.
Import/Export slot. Whether or not the cartridge is in an Import/Export slot. The following values can be returned:
| 0 | The cartridge is not in an import/export slot. |
| 1 | The cartridge is in an import/export slot. |
Length of cartridge information entry. When cartridge information is available this field is set to the length, in bytes, of a single cartridge information entry. A value of zero is returned if the cartridge information is not available.
Location. The current location of the cartridge. The location will be set to either a slot number (if available) or a tape resource name. The following value may also be returned:
| blanks | Slot number is not available. |
Location indicator. This field indicates what type of location information is returned. Possible values follow:
| 0 | The cartridge is mounted in a tape resource in the tape library. |
| 1 | The cartridge is in a storage slot in the tape library. |
Media type. The media type read from the bar code label on the cartridge. If there is no bar code reader the field is set to blank.
Number of cartridge information entries. The number cartridge information entries returned. A value of zero is returned if the cartridge information is not available.
Offset to cartridge information. The offset, in bytes, to the cartridge information. A value of zero is returned if the cartridge information is not available.
Owner ID. The owner of the cartridge. This information is read from the tape volume labels. The following other values can be returned:
| *NL | The cartridge is a non-labeled tape. |
| *BLANK | The owner ID in the tape labels was blank. |
| blanks | The owner ID is unknown |
Reference date. The date the cartridge was last used. The date is returned with the following format - CYYMMDD. If no reference date is available the field is set to blanks.
Reference time. The time the cartridge was last used. The time is returned with the following format HHMMSS. If no reference time is available the field is set to blanks.
Tape Library name. The name of the tape library containing the cartridge.
Volume ID. The volume identifier for the cartridge read from the tape volume labels. The following other values can be returned:
| *NL | The volume is a non-labeled tape. |
| blanks | The volume ID is unknown |
Volume status. The status of the cartridge. Possible values follow:
| 01 | The cartridge is available. |
| 02 | The cartridge is mounted. |
| 03 | The cartridge is not available. |
| 04 | The cartridge is ejected. |
| 05 | The cartridge is in error state. |
| 06 | The cartridge is inserted. |
| 07 | The cartridge has a duplicate cartridge ID. |
Write Protection. Indicates whether or not the cartridge is write protected. The following values can be returned:
| 0 | The cartridge is not write protected. |
| 1 | The cartridge is write protected. |
| blank | The cartridge write protect status is unknown. |
| 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. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF6708 E | Command ended due to error. |
| CPF6718 E | Cannot allocate device &1. |
| CPF673A E | Device &1 not varied on. |
| CPF6745 E | Device &1 not a media library device. |
| CPF67A1 E | Cartridge &1 not found. |
| CPF67A6 E | Category does not exist. |
| CPF67D2 E | Cartridge does not exist in specified category. |
| 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. |
| Top | Backup and Recovery APIs | APIs by category |