Retrieve Device Capabilities (QTARDCAP) API

  Required Parameter Group:

1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 Format name Input Char(8)
4 Device description or resource name Input Char(10)
5 Device description or resource indicator Input Char(10)
6 Resources to list Input Char(1)
7 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

The Retrieve Device Capabilities (QTARDCAP) API retrieves information that is associated with a specified tape device description or tape resource name. The resource that is specified or associated with the specified device description must currently exist on the system.

The QTARDCAP API currently supports the following device types:


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 TAPE0100 format must be used for the tape device capabilities information. See TAPE0100 Format to view the information returned for this format.

Device description or resource name
INPUT; CHAR(10)

The name of the device description or resource for which the data is returned.

Device description or resource indicator
INPUT; CHAR(10)

Whether the name specified is a device description or a resource name. The possible values follow:

*DEVD The name specified is a device description.
*RSRC The name specified is a resource name.

Resources to list
INPUT; CHAR(1)

Which media library device resources are listed if the device description indicator in the device description or resource indicator parameter is *DEVD. This parameter is blank if the device requested is not a media library device description. If a media library device description is specified, the possible values are as follows:

1 All resources are listed (*ALL).
2 Allocated resources are listed (*ALLOCATED).
3 Unprotected resources are listed (*UNPROTECTED).
4 Deallocated resources are listed (*DEALLOCATED).
5 Both allocated and unprotected resources are listed (*AVAILABLE).
blank The requested input device or resource is not a media library device, not a device description, or the information is not requested.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


TAPE0100 Format

The following table shows the information that is returned for the TAPE0100 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 description or resource name
18 12 CHAR(10) Device description or resource indicator
28 1C CHAR(10) Device resource name
38 26 CHAR(3) Reserved
41 29 CHAR(1) Device relationship to media library device
42 2A CHAR(1) Type of media library device
43 2B CHAR(1) Self-configured tape device
44 2C CHAR(4) Device type
48 30 CHAR(4) Device model
52 34 BINARY(4) Maximum block size
56 38 CHAR(1) Logical-block-ID capability
57 39 CHAR(1) Assign capability
58 3A CHAR(1) Overwrite capability
59 3B CHAR(1) Read-backward capability
60 3C CHAR(1) Cartridge-checking capability
61 3D CHAR(1) Device class
62 3E CHAR(1) Hardware data compression capability
63 3F CHAR(1) Label compaction supported
64 40 BINARY(4) Offset to supported write densities
68 44 BINARY(4) Number of supported write densities
72 48 BINARY(4) Offset to supported read densities
76 4C BINARY(4) Number of supported read densities
80 50 BINARY(4) Offset to supported improved-data-recording-capability (IDRC) densities
84 54 BINARY(4) Number of supported improved-data-recording-capability (IDRC) densities
88 58 BINARY(4) Optimum block size
92 5C CHAR(1) Space to end of data
93 5D CHAR(1) Space backward allowed
94 5E CHAR(1) Media library device with bar-code scanner
95 5F CHAR(1) Improved-data-recording-capability (IDRC) supported
96 60 CHAR(1) Automatic cartridge mechanism supported
97 61 CHAR(2) Bit mapping of all supported improved-data-recording-capability (IDRC) densities
99 63 CHAR(2) Bit mapping of all supported write densities
101 65 CHAR(2) Bit mapping of all supported read densities
103 67 CHAR(2) Bit mapping of the highest supported density
105 69 CHAR(1) Reserved
106 6A CHAR(2) Bit mapping of all supported character densities
108 6C BINARY(4) Offset to supported character densities
112 70 BINARY(4) Number of supported character densities
116 74 BINARY(4) Offset to resource list
120 78 BINARY(4) Number of resources in resource list
124 7C BINARY(4) Offset to resource status list
128 80 BINARY(4) Number of resource status list entries
132 84 CHAR(1) Reserved
133 85 CHAR(1) QTACTLDV API supported
134 86 CHAR(1) Media library device with door
135 87 CHAR(1) Write-once-read-many (WORM) support
136 88 CHAR(1) Virtual device
137 89 CHAR(3) Reserved
140 8C BINARY(4) Offset to density capability entries
144 90 BINARY(4) Number of density capability entries
148 94 BINARY(4) Length of density capability entries
152 98 BINARY(4) Offset to system feature codes
156 9C BINARY(4) Length of system feature codes
160 A0 BINARY(4) Acceptable read error thresholds
164 A4 BINARY(4) Acceptable write error thresholds
168 A8 BINARY(4) Instantaneous performance
172 AC BINARY(4) Offset to slot and station information
176 B0 BINARY(4) Offset to device text
180 B4 BINARY(4) Length of device text
184 B8 BINARY(4) Offset to supported write-once-read-many (WORM) densities
188 BC BINARY(4) Number of supported write-once-read-many (WORM) densities
    ARRAY(*) of CHAR(10) Supported improved-data-recording-capability (IDRC) densities
    ARRAY(*) of CHAR(10) Supported write densities
    ARRAY(*) of CHAR(10) Supported read densities
    ARRAY(*) of CHAR(10) Supported character densities
    ARRAY(*) of CHAR(10) Resource list
    ARRAY(*) of CHAR(15) Resource status list
    ARRAY(*) of CHAR(*) Density capability entries
    CHAR(*) System feature codes
    CHAR(*) Device text
    CHAR(*) Slot and station information
    ARRAY(*) of CHAR(10) Supported write-once-read-many (WORM) densities


Field Descriptions

Acceptable read error thresholds. The average minimum number of kilobytes (1KB = 1000 bytes) read between recovered read errors for the media to be considered acceptable. This information is to determine the reliability of a volume based on the number of errors that the device is reporting against that tape volume. This field is zero for devices that do not report this information.

Acceptable write error thresholds. The average minimum number of kilobytes (1KB = 1000 bytes) written between recovered write errors for the media to be considered acceptable. This information is to determine the reliability of a volume based on the number of errors that the device is reporting against that tape volume. This field is zero for devices that do not report this information.

Automatic cartridge mechanism supported. Whether the device has an automatic cartridge mechanism (loader or facility) known as an ACL (that is, 3490 type stand alone devices typically have an ACL) or an ACF (that is, 3590 B11 devices have an ACF). Possible values follow:

0 The device does not have an automatic cartridge mechanism.
1 The device does have an automatic cartridge mechanism.
blank This field is not valid for a media library device.

Assign capability. Whether the specified device or resource has the capability to assign (reserve) a device to the system. This concept ensures that no other system can use the device because the system could not be successfully assigned (reserved) from the device. This feature fully enables devices that can be shared. Possible values follow:

0 The system cannot assign the device.
1 The system can assign the device.
blank This is not an available value for a media library device.

Bit mapping of all supported character densities. A bit-mapped encoding of densities that correspond to the supported character densities. This field is not available for a media library device. Bit mappings are defined on the device level and may not match the following examples.

The following are the supported IBM® i densities and their corresponding bit-map representations for each device class. Note that self-configured tape devices do not follow these IBM i bit-map representations but are defined in the device specifications. Values for the device class of 1/4-inch cartridge technology follow:

Hexadecimal
Bit Map
Density or Format
'4000'x *QIC24 (8000 bpi)
'2000'x *QIC120 (10000 bpi)
'0800'x *QIC525 (16000 bpi)
'0400'x *QIC1000
'0200'x *QIC2GB
'0100'x *QIC3040
'0080'x *QIC5010

Values for the device class of 1/2-inch cartridge technology follow:

Hexadecimal
Bit Map
Density or Format
'8000'x *FMT3480 (38000 bpi)
'4000'x *FMT3490E
'2000'x *FMT3590
'0800'x *FMT3570
'0400'x *FMT3570E

Values for the device class of 1/2-inch reel technology follow:

Hexadecimal
Bit Map
Density or Format
'8000'x 1600 bpi
'4000'x 3200 bpi
'2000'x 6250 bpi

Values for the device class of 8-mm cartridge technology follow:

Hexadecimal
Bit Map
Density or Format
'8000'x *FMT2GB
'4000'x *FMT5GB
'2000'x *FMT7GB

Bit mapping of highest supported output density. A bit-mapped encoding of the highest supported output density on the device. This field is not available for a media library device. The definition of example bit maps can be found in the bit mapping of all supported character densities field.

Bit mapping of all supported improved-data-recording-capability (IDRC) densities. A bit-mapped encoding of densities that correspond to the supported IDRC densities. This field is not available for a media library device. The definition of example bit maps can be found in the bit mapping of all supported character densities field.

Bit mapping of all supported read densities. A bit-mapped encoding of densities that correspond to the supported read densities. This field is not available for a media library device. The definition of example bit maps can be found in the bit mapping of all supported character densities field.

Bit mapping of all supported write densities. A bit-mapped encoding of densities that correspond to the supported write densities. This field is not available for a media library device. The definition of example bit maps can be found in the bit mapping of all supported character densities field.

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-checking capability. Whether the device communicates valid cartridge densities or formats. This capability allows IBM i to verify cartridge density or formats. Devices that do not support this capability cannot send intelligent messages about the cartridge. When the device is unable to write to the cartridge, a generic error message usually results. It could be as simple as a cartridge not supported by the device. Possible values follow:

0 No device or resource that is requested has special cartridge-density checking capabilities.
1 The device requested has special cartridge-density checking capabilities.
blank This is not an available value for a media library device.

Device class. The class of the device. Possible values follow:

1 1/2-inch reel technology
2 1/2-inch cartridge technology
3 1/4-inch cartridge technology
4 8-mm technology
blank None of the above technologies or media library device

Density capability entries. The list of density capabilities based on density, format, or both. Each entry consists of the following format and has a length that is specified in the length of density capability entry field.

CHAR(10) Density or format
CHAR(2) Bit map representation of density
BINARY(4) Instantaneous performance in megabytes per second for this density or format. One MB per second is returned for each field if the performance number is not reported by the device.
BINARY(4) Maximum block size for this density or format.
BINARY(4) Optimum block size for this density or format.

This format is repeated once for each density or format that is supported by the device. The number of entries in the array is specified in the number of density capability entries field. This field is not available for a media library device.

Device description or resource indicator. Whether the information is retrieved for a device description or a device resource name. This field is left-justified. Possible values follow:

*DEVD The name specified is a device description.
*RSRC The name specified is a device resource name.

Device description or resource name. The device description or resource name of the device.

Device relationship to media library device. The relationship of the device or resource to the media library device. Possible values follow:

0 The device is not a media library resource.
1 The device is a tape resource in a media library resource.
2 The device is a media library resource.

Device model. The device model number.

Device resource name. The resource name if the device information is for a device description.

Device text. The specific text that is reported by the device.

Device type. The device type number.

Hardware data compression capability. Whether hardware data compression (HDC) is supported. This field corresponds to the data compression (DTACPR) parameter on save commands. Possible values follow:

0 No device or resource that is requested has hardware data compression capabilities.
1 The device that is requested has hardware data compression capabilities.
blank This is not an available value for a media library device.

Improved-data-recording-capability (IDRC) supported. Whether the device supports IDRC (or compaction) at any density. If IDRC is supported, see the supported IDRC densities field. Possible values follow:

0 No device or resource that is requested has IDRC capabilities.
1 The device that is requested has IDRC capabilities.
blank This is not an available value for a media library device.

Instantaneous performance. The highest instantaneous performance that is reported by the device. This value can be obtained from the density capability entries list on a density, format, or both. This value is the highest performance number that is specified in the density capability entries list. The value is in megabytes per second. If the device does not report this value, a value of 1 MB per second will be used. This is not an available value for a media library device and is set to zero for media library devices.

Label compaction supported. Whether the device volumes are written with compacted labels. Possible values follow:

0 The device does not generate labels with compaction.
1 The device generates labels with compaction if compaction is requested.

Length of density capability entry. The length, in bytes, of each entry in the density capability entries list. This field should be used in stepping through the array of density capability entries. Additional fields for each density or format in the density capability entries list may be added at any time.

Length of device text. The length, in bytes, of text that is reported by the device. If the device does not report specific text about the device, zero is returned.

Length of system feature codes. The length, in bytes, of the system feature codes entry. This field should be used in determining the system feature codes (type and model) of the device. If the device does not report this information, zero is returned.

Logical-block-ID capability. Whether the device allows fast access capabilities. This allows logical-block-identifier support through a tape management system that is registered with the registration facility and used in combination with the Media and Storage Extensions feature of IBM i. Possible values follow:

0 No device or resource that is requested has fast access by logical-block-identifier capabilities.
1 The device that is requested has fast access by logical-block-identifier capabilities.
blank This is not an available value for a media library device.

Maximum block size. The highest maximum block size that is supported by the device. If you use the maximum block size, tapes may be created that are not compatible with other device types. A tape that is created with a maximum block size can only be duplicated with the Duplicate Tape (DUPTAP) command to devices that support the same block size. This field is not available for a media library device and is set to zero for media library devices.

The maximum block size that a device supports may vary with density. Use the Density capability entries to determine the maximum block size for a specific density.

Media library device with bar-code scanner. Whether the device has a bar-code scanner, which is for a media library device. Possible values follow:

0 The device has no bar-code scanner.
1 The device has a bar-code scanner.
blank This field is only valid for a media library device.

Media library device with door. Whether the media library device has a door that can be opened. Possible values follow:

0 The device does not have a door.
1 The device has a door.
blank This field is only valid for a media library device.

Number of density capability entries. The number of density capability entries in the density capability entries list. This field is not available for a media library device and is set to zero when the input device is a media library device.

Number of resources in resource list. The number of resources that are listed in the resource list. This number is set to zero when the input device is not a media library device description (*DEVD).

Number of resource status list entries. The number of resource status entries for the resource status list. This number is set to zero when the input device is not a media library device description (*DEVD).

Number of supported improved-data-recording-capability (IDRC) densities. The number of supported IDRC (or compaction) densities that are specified in the supported IDRC densities field. This field is not available for a media library device and is set to zero when the input device is a media library device.

Number of supported character densities. The number of supported character densities that are specified in the supported character densities field. This field is not available for a media library device and is set to zero when the input device is a media library device.

Number of supported read densities. The number of supported read densities that are specified in the supported read densities field. This field is not available for a media library device and is set to zero when the input device is a media library device.

Number of supported write densities. The number of supported write densities that are specified in the supported write densities field. This field is not available for a media library device and is set to zero when the input device is a media library device.

Number of supported write-once-read-many (WORM) densities. The number of supported WORM densities that are returned in the supported WORM densities array. This field is not available for a media library device and is set to zero when the input device is a media library device. This field will be set to sero if the device does not report WORM density information.

Offset to density capability entries. The offset, in bytes, to the density capability entries list.

Offset to device text. The offset, in bytes, to the text that is reported by the device.

Offset to resource list. The offset, in bytes, to the resource list.

Offset to resource status list. The offset, in bytes, to the resource status list field.

Offset to slot and station information. The offset, in bytes, to the slot and station information field.

Offset to supported character densities. The offset, in bytes, to the supported character densities field.

Offset to supported improved-data-recording-capabilities (IDRC) densities. The offset, in bytes, to the supported improved-data-recording-capabilities (IDRC) densities field.

Offset to supported read densities. The offset, in bytes, to the supported read densities field.

Offset to supported write densities. The offset, in bytes, to the supported write densities field.

Offset to supported write-once-read-many (WORM) densities. The offset, in bytes, to the supported WORM densities array.

Offset to system feature codes. The offset, in bytes, to the system feature codes (types and models) of the device.

Optimum block size. The highest optimum block size supported by the device.

When USEOPTBLK(*YES) is specified as a parameter for a save operation, performance may be improved. The USEOPTBLK(*YES) parameter may cause tapes to be created that are not compatible with other device types. That is, a tape that is created with an optimum block size can only be duplicated with the Duplicate Tape (DUPTAP) command to devices that support the same block size. This field is not available for a media library device and is set to zero for media library devices.

The optimum block size that a device supports may vary with density. Use the Density capability entries to determine the optimum block size for a specific density.

Overwrite capability. Whether the device or resource that is specified has overwriting capabilities. This capability refers to being able to write a data file over an existing data file sequence on a tape volume. Some technologies only allow appending data to the end of tape or writing files to the beginning of tape. Possible values follow:

0 No device or resource that is requested has overwrite capabilities.
1 The device that is requested has overwrite capabilities.
blank This is not an available value for a media library device.

QTACTLDV API supported. Whether the QTACTLDV API is supported for the device or resource that is specified. Possible values follow:

0 QTACTLDV API is not supported.
1 QTACTLDV API is supported.

Read-backward capability. Whether the device or resource that is specified has read-backward capabilities. Possible values follow:

0 No device or resource that is requested has read-backward capabilities.
1 The device that is requested has read-backward capabilities.
blank This is not an available value for a media library device.

Reserved. An ignored field.

Resource list. The list of tape resources in the media library device.

Note: The data is an array of 10-byte entries. Each entry consists of a 10-byte density that is left-justified and padded with blanks. The number of entries in the array is specified in the number of resources in resource list field. The resource list is not valid when the input device is not a media library device description (*DEVD).

Resource status list. The list of statuses that correspond to resources in the resource list.

Note: The data is an array of 15-byte entries. Each entry consists of a 15-byte status that is left-justified and padded with blanks. The number of entries in the array is specified in the number of resource status list entries field. The resource status list is not valid when the input device is not a media library device description (*DEVD). Possible values follow:

*ALLOCATED The tape resource is allocated to the media library device. The system has assigned the device.
*UNPROTECTED The tape resource is considered unprotected to the media library device. It is available to the media library device, but the system has not assigned the device. The system attempts to assign the resource when the resource is used.
*DEALLOCATED The tape resource is deallocated to the media library device. The resource is not available to the media library device, and the system has not assigned the device.

Self-configured tape device. Whether this resource or device is a self-configured tape device. Possible values follow:

0 The device is not a self-configured tape device.
1 The device is a self-configured tape device.

Slot and station information. This information is available only for a media library device. The information is returned in the following format:

BINARY(4) Total number of storage slots
BINARY(4) Total number of import/export stations

The above numbers are set to zero when the input device is not a media library device description (*DEVD) or when the information is not available.

For a media library device that requires a communication interface, the slot and station information is available only after the media library device description has been varied on.

Space backward allowed. Whether the device supports spacing backward or requires rewinding the device and respacing to the correct file. Possible values follow:

0 No device or resource that is requested has space-backward capabilities.
1 The device that is requested has space-backward capabilities.
blank This is not an available value for a media library device.

Space to end of data. The function that allows quick access to the end of the logical tape when a command specifies SEQNBR(*END), such as the Save Library (SAVLIB) command. This function allows a significant improvement on performance when the tape is positioned at the beginning of the tape and needs to be positioned a long way into the tape. If the device does not support this function, IBM i spaces by the file marks until the end of data is reached. Possible values follow:

0 No device or resource that is requested has space to end of data capabilities.
1 The device that is requested has space to end of data capabilities.
blank This is not an available value for a media library device.

Supported improved-data-recording-capability (IDRC) densities. The list of densities that support IDRC (or compaction) on this device.

Note: The data is an array of 10-byte entries. Each entry consists of a 10-byte density that is left-justified and padded with blanks. The number of entries in the array is specified in the number of supported improved-data-recording-capability (IDRC) densities field. This field is not available for a media library device.

System feature codes. The system feature codes (type and model) that the device reports. The first 4 bytes of the system feature codes field displays which feature codes are available or reported by the device. The 32 bits of the 4 bytes are defined as follows:

Bit 0 System i™ default feature code provided
Bit 1-31 Not used

Each bit that is identified in the 32 bits as defined above is represented with 4 bytes of device type and model in hexadecimal representation. These 4 bytes are repeated for each bit that is turned on in the first 4 bytes of the system feature codes field. The length of this field determines how much information is returned from the device and is contained in the length of system feature codes. The length of this field includes the first 4 bytes of bit definitions. That is, if only bit 0 is on, then the length of the field is 8 bytes, which includes the 4 bytes of bit definition and the 4 bytes of the one system feature code.

Supported character densities. The list of densities that are supported on this device.

Note: The data is an array of 10-byte entries. Each entry consists of a 10-byte density that is left-justified and padded with blanks. The number of entries in the array is specified in the number of supported character densities field. This field is not available for a media library device.

Supported read densities. The list of valid read densities that are supported by this device.

Note: The data is an array of 10-byte entries. Each entry consists of a 10-byte density that is left-justified and padded with blanks. The number of entries in the array is specified in the number of supported read densities field. This field is not available for a media library device.

Supported write densities. The list of valid write densities that are supported by this device.

Note: The data is an array of 10-byte entries. Each entry consists of a 10-byte density that is left-justified and padded with blanks. The number of entries in the array is specified in the number of supported write densities field. This field is not available for a media library device.

Supported write-once-read-many (WORM) densities. The list of valid WORM densities that are supported by this device.

Note: The data is an array of 10-byte entries. Each entry consists of a 10-byte density that is left-justified and padded with blanks. The number of entries in the array is specified in the number of supported WORM densities field. This data is not available for a media library device.

Type of media library device. The media library technology. Possible values follow:

0 The device is not a media library device.
1 Library commands are communicated to the library robotic device.
2 Library commands are communicated to a communications line.
3 Library commands are communicated to the library robotic device and the device.

Virtual device. Whether or not the device is a virtual device. Possible values follow:

0 The device is not a virtual device.
1 The device is a virtual device.

Write-once-read-many (WORM) support. Whether the device supports WORM at any density. If WORM is supported, see the supported WORM densities array. Possible values follow:

0 No device or resource that is requested has WORM capabilities.
1 The device that is requested has WORM capabilities.
blank Indicates this field is not applicable for a media library device.


Error Messages

Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
CPF6707 E Format name &1 not valid.
CPF6708 E Command ended due to error.
CPF6709 E Parameter &3 not correct.
CPF6710 E Specified length not correct.
CPF6721 E Device &1 not a tape device.
CPF672F E Resource &1 not found.
CPF673F E Device &1 does not support &2.
CPF9814 E Device &1 not found.
CPF9825 E Not authorized to device &1.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.


API introduced: V3R7

[ Back to top | Backup and Recovery APIs | APIs by category ]