Retrieve Device Status (QTARDSTS) 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 | Resource name | Input | Char(10) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Device Status (QTARDSTS) API retrieves dynamic status information for the specified device and for any currently mounted tape cartridge. The device description must be varied on. The resource that is associated with a specified tape media library device description must currently exist on the system.
Note: If the device status has been changed by a manual operation or by another system sharing the device, the information will not be accurate.
The QTARDSTS API currently supports the following device types:
- Tape (TAP) devices
- Tape media library (TAPMLB) devices
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 RDST0100 format must be used for the tape device status information. See RDST0100 Format to view the information returned for this format.
- Device description
- INPUT; CHAR(10)
The name of the device description for which the data is returned.
- Resource name
- INPUT; CHAR(10)
When the Device description parameter specifies a tape media library device description, this parameter can be used to specify the resource name of a tape device within the tape media library for which data is returned. This parameter must be set to blanks when only the tape media library information is needed, or when the device description is for a tape device.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
RDST0100 Format
The following table shows the information that is returned for the RDST0100 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 current cartridge information |
| 12 | C | BINARY(4) | Number of current cartridge information entries |
| 16 | 10 | BINARY(4) | Length of current cartridge information entry |
| 20 | 14 | BINARY(4) | Offset to device information |
| 24 | 18 | BINARY(4) | Number of device information entries |
| 28 | 1C | BINARY(4) | Length of device information entry |
| 32 | 20 | BINARY(4) | Offset to label information |
| 36 | 24 | BINARY(4) | Number of label information entries |
| 40 | 28 | BINARY(4) | Length of label information entry |
| 44 | 2C | BINARY(4) | Offset to position information |
| 48 | 30 | BINARY(4) | Number of position information entries |
| 52 | 34 | BINARY(4) | Length of position information entry |
| 56 | 38 | BINARY(4) | Offset to tape media library information |
| 60 | 3C | BINARY(4) | Number of tape media library information entries |
| 64 | 40 | BINARY(4) | Length of tape media library information entry |
| CHAR(*) | Current cartridge information | ||
| CHAR(*) | Device information | ||
| CHAR(*) | Label information | ||
| CHAR(*) | Position information | ||
| CHAR(*) | Tape media library information | ||
Current cartridge information
The following table shows the current cartridge information that is returned. This information is only available when a command was previously issued to use the device and one or more of the following conditions are present:
- There is an open tape file for the device.
- The device is in leave processing.
- The device is varied on with assign(*YES).
- The device is a virtual tape device and an Image catalog is loaded.
This information is not returned when the specified device description is a tape media library and no device resource is provided. The information returned may not be accurate if there was an error reported during the previously issued command. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(6) | Volume ID |
| 6 | 6 | CHAR(6) | Cartridge ID |
| 12 | C | CHAR(10) | Current cartridge density |
| 22 | 16 | CHAR(1) | Write protected |
| 23 | 17 | CHAR(10) | Image catalog name |
| 33 | 21 | CHAR(6) | Mounted volume ID |
Device information
The following table shows the device information that is returned. This information is only available when there is an active job using the tape device or the specified device description is a tape media library and a device resource is provided that is owned by the tape media library. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Current command |
| 10 | A | CHAR(26) | Job using the device |
| 36 | 24 | CHAR(1) | Category is mounted |
| 37 | 25 | CHAR(10) | Mounted category name |
| 47 | 2F | CHAR(8) | Mounted category system |
| 55 | 37 | CHAR(6) | Mounted cartridge ID |
| 61 | 3D | CHAR(1) | Cartridge order for category |
| 62 | 3E | CHAR(10) | Target category |
| 72 | 48 | CHAR(8) | Target system |
| 80 | 50 | CHAR(10) | Mount identifier |
 90 |
5A | CHAR(1) | Target category option |
Label information
The following table shows the label information that is returned. This information is only available when there is an open tape file for the tape device or the device is in leave processing. This information is not returned when the specified device description is a tape media library and no device resource is provided. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Label type |
| 1 | 1 | CHAR(1) | Tape encoding |
| 2 | 2 | CHAR(10) | Current file sequence number |
| 12 | C | CHAR(10) | Current multi-volume sequence number |
| 22 | 16 | CHAR(80) | Volume label |
| 102 | 66 | CHAR(80) | Last processed HDR1/TRL1 label |
| 182 | B6 | CHAR(80) | Last processed HDR2/TRL2 label |
Position information
The following table shows the position information that is returned. This information is only available when there is an open tape file for the tape device or the device is in leave processing. This information is not returned when the specified device description is a tape media library and no device resource is provided. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | In leave processing |
| 1 | 1 | CHAR(1) | At logical EOT |
| 2 | 2 | CHAR(1) | At logical BOT |
| 3 | 3 | CHAR(1) | Reserved |
| 4 | 4 | BINARY(4) | Current tape mark count |
Tape media library information
The following table shows the tape media library information that is returned. This information is only available when the specified device description is a tape media library and a command was previously issued to use the tape media library. For more details about the fields in the following table, see Field Descriptions.
Note: For a 3494 tape media library device the tape media library information is only updated when a DSPTAPSTS command is issued.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of used slots |
| 4 | 4 | BINARY(4) | Number of available slots |
| 8 | 8 | BINARY(4) | Number of high capacity slots |
| 12 | C | BINARY(4) | Number of import/export stations |
Field Descriptions
At logical BOT. Whether the media is currently positioned at logical BOT. For standard labeled format tapes this indicator is set whenever the tape is positioned within the first label group. For non-labeled format tapes this indicator is set whenever the tape is positioned within the first file on tape. Possible values follow:
| 0 | The media is not currently positioned at logical BOT. |
| 1 | The media is currently positioned at logical BOT. |
At logical EOT. Whether the media is currently positioned at logical EOT. Possible values follow:
| 0 | The media is not currently positioned at logical EOT. |
| 1 | The media is currently positioned at logical EOT. |
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 currently mounted media. This field will be blank if the tape does not have a bar code label or if it is not in a tape media library with a bar code reader.
Cartridge order for category.When there is a category mounted on the specified resource within a tape media library this field shows the cartridge order. Possible values follow:
| 0 | The cartridges will be mounted in next available (*NEXTAVAIL) order. |
| 1 | The cartridges will be mounted in sequential (*SEQ) order. |
| blank | There is no category mounted. |
Category is mounted. Whether there currently is a category mounted on the device. Possible values follow:
| 0 | There is not a category mounted on the device. |
| 1 | There is a category mounted on the device. |
| blank | The device is not allocated to a tape media library. |
Current cartridge density. The density of the currently mounted media.
Current command. The current command executed against the tape device. If the specific command is not known, one of the following values is returned:
| CPP CMD | A CL command was executed. |
| SAVE CMD | A save command was executed. |
| RST CMD | A restore command was executed. |
| COMMAND | An unknown type of command was executed. |
Current file sequence number. The current sequence number of the file being processed. This field will be blanks if no files have been processed yet.
Current multi-volume sequence number. The current multi-volume sequence number for the mounted media. This field will be blank if no media is mounted or if the tape is a non-labeled tape.
Current tape mark count. The current number of tape marks away from BOT.
Image catalog name.The name of the image catalog loaded on the virtual tape device. When there is no image catalog loaded, the field will be set to blanks.
In leave processing. Whether the last completed tape command used an ending option of *LEAVE. Possible values follow:
| 0 | The media is not currently left in position. |
| 1 | The media is currently left in position. |
Job using the device. The qualified job name of the job currently using the device. This field will be all blanks if there is no active job using the device.
Label type. The label format of the currently mounted tape. Possible values follow:
| 0 | The media uses standard label format. |
| 1 | The media uses non-labeled format. |
Last processed HDR1/TRL1 label. The last processed HDR1 or TRL1 label on the media. This field will be all blanks for a Non-labeled tape, or if no labels have been processed yet.
Last processed HDR2/TRL2 label. The last processed HDR2 or TRL2 label on the media. This field will be all blanks for a Non-labeled tape or if no labels have been processed yet.
Length of current cartridge information entry. When current cartridge information is available this field is set to the length, in bytes, of a single current cartridge information entry. A value of zero is returned if the current cartridge information is not available.
Length of device information entry. When device information is available this field is set to the length, in bytes, of a single device information entry. A value of zero is returned if the device information is not available.
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 label information is not available.
Length of position information entry. When position information is available this field is set to the length, in bytes, of a single position information entry. A value of zero is returned if the position information is not available.
Length of tape media library information entry. When tape media library information is available this field is set to the length, in bytes, of a single tape media library information entry. A value of zero is returned if the tape media library information is not available.
Mounted cartridge ID. For a resource within a tape media library device the cartridge identifier for the cartridge that was last mounted is returned. When the specified device description is a tape device, the field is set to blanks.
Mounted category name. The name of the category mounted on the specified resource within a tape media library. When there is no category mounted, the field is set to blanks.
Mounted category system. The name of the system owning the category mounted on the specified resource within a tape media library. When there is no category mounted or the category is not owned by a specific system, the field is set to blanks.
Mount identifier. The mount identifier assigned to the category mounted on the specified resource within a tape media library. When there is no mount identifier assigned the value *NONE is returned. When there is no category mounted, the field is set to blanks.
Mounted volume ID. The name of the volume which is currently mounted on the virtual tape device. When there is no image catalog loaded or no volume mounted, the field is set to blanks.
Number of available slots. The number of empty storage slots in the tape media library.
Number of current cartridge information entries. If current cartridge information is available, a value of one is returned. A value of zero is returned if the current cartridge information is not available.
Number of device information entries. If device information is available, a value of one is returned. A value of zero is returned if the device information is not available.
Number of high capacity slots. The number of high capacity storage slots in the tape media library.
Number of import/export stations. The number of import/export stations for the tape media library.
Number of label information entries. If label information is available, a value of one is returned. A value of zero is returned if the label information is not available.
Number of position information entries. If position information is available, a value of one is returned. A value of zero is returned if the position information is not available.
Number of tape media library information entries. If tape media library information is available, a value of one is returned. A value of zero is returned if the tape media library information is not available.
Number of used slots. The number of storage slots in the tape media library that are currently being used.
Offset to current cartridge information. The offset, in bytes, to the current cartridge information. A value of zero is returned if the current cartridge information is not available.
Offset to device information. The offset, in bytes, to the current job information. A value of zero is returned if the device information is not available.
Offset to label information. The offset, in bytes, to the label information. A value of zero is returned if the label information is not available.
Offset to position information. The offset, in bytes, to the position information. A value of zero is returned if the position information is not available.
Offset to tape media library information. The offset, in bytes, to the tape media library information. A value of zero is returned if the tape media library information is not available.
Tape Encoding. The encoding scheme being used for the mounted media. Possible values follow:
| 0 | ASCII format tape. |
| 1 | EBCDIC format tape. |
Target category. The category that the cartridges will be changed to after they are used. When there is no category mounted, the field is set to blanks.
Target category option. Specifies when the category will
be changed to the target category. Possible values follow:
| 0 | The target category will be changed when the cartridge is mounted. |
| 1 | The target category will be changed when the cartridge is unloaded. |
| 2 | The target category will be changed when the cartridge reaches the end of volume. |
| blank | There is no category mounted. |
Target system. The name of the system owning the target category. When there is no category mounted, the field is set to blanks.
Volume ID. The Volume identifier for the currently mounted media. This field will be blank for non-labeled tapes or if the tape cannot be read.
Volume label. The volume label for the currently mounted media. This field will be blank for a non-labeled tape or if the tape cannot be read.
Write protected. Whether the mounted media is write protected. Possible values follow:
| 0 | The media is not write protected. |
| 1 | The media is write protected. |
| blank | Write protect status is unknown. |
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. |
| CPF3C3C E | Value for parameter &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF6708 E | Command ended due to error. |
| CPF6721 E | Device &1 not a tape device. |
| CPF672F E | Resource &1 not found. |
| CPF67B0 E | Tape resource &2 not in specified library device. |
| 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: V5R2
[ Back to top | Backup and Recovery APIs | APIs by category ]