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(*) |
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:
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.
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 TAPE0100 format must be used for the tape device capabilities information. See TAPE0100 Format to view the information returned for this format.
The name of the device description or resource for which the data is returned.
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. |
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. |
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 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 |
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 i5/OS densities and their corresponding bit-map representations for each device class. Note that self-configured tape devices do not follow these i5/OS 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 i5/OS 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 i5/OS. 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, i5/OS 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 | iSeries 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. |
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. |
Top | Backup and Recovery APIs | APIs by category |