Retrieve Resource Class Attributes (QRZRRCA) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Request criteria | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: No
The Retrieve Resource Class Attributes (QRZRRCA) API retrieves class-specific information or object-type values for a logical resource. The caller of the API provides the class and subclass, or type and model, or resource name. The caller of the API also indicates what data is requested.
You can use this API to do the following:
- Obtain a valid type number based on the class and subclass specified.
- Determine the supported protocols based either on the resource name or on the type and model.
- Determine if a controller description is required based either on the resource name or on the type and model.
- Determine if a device supports the assign command based either on the resource name or on the type and model.
- Obtain a media format based either on the resource name or on the type and model.
- Obtain a media class based either on the resource name or on the type and model.
- Determine if a device is read-only based either on the resource name or on the type and model.
- Determine the kind of device based either on the resource name or on the type and model.
- Determine the LAN speed based either on the resource name or on the type and model.
- Determine if a device configuration object is applicable based either on the resource name or on the type and model.
- Determine if a device configuration network ID object is applicable based either on the resource name or on the type and model.
- Determine if the device has a bar code reader based either on the resource name or on the type and model.
- Determine if the device supports import and export based either on the resource name or on the type and model.
- Determine the library mode based either on the resource name or on the type and model.
- Determine if the library reports virtual product data (VPD) information based either on the resource name or on the type and model.
- Determine if the library reports an element address based either on the resource name or on the type and model.
Authorities and Locks
- API Public Authority
- *EXCLUDE
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 returned. The possible format names are as follows. Note: If 2 (the next attempt to obtain an element from a possible list of elements) is specified for the search request criteria field, message CPF0B46 (Materialize failed) is issued if you try to read beyond the end of the list elements.
RRCA0100 Returns the type number of the object based on the request criteria. See RRCA0100 Format for details about this format. RRCA0200 Returns the protocol support based on the request criteria. See RRCA0200 Format for details about this format. RRCA0300 Returns a value that indicates whether a controller description is required for the device based on the request criteria. See RRCA0300 Format for details about this format. RRCA0400 Returns a value that indicates whether the device supports the assign command based on the request criteria. See RRCA0400 Format for details about this format. RRCA0500 Returns a value that indicates the media format based on the request criteria. See RRCA0500 Format for details about this format. RRCA0600 Returns a value that indicates the media class based on the request criteria. See RRCA0600 Format for details about this format. RRCA0700 Returns a value that indicates whether the device is read-only based on the request criteria. See RRCA0700 Format for details about this format. RRCA0800 Returns a value that indicates the kind of resource. The three fields can be used separately or together. See RRCA0800 Format for details about this format. RRCA0900 Returns a value that indicates the LAN speed. See RRCA0900 Format for details about this format. RRCA1000 Returns a value that indicates the value of the configurable flag. See RRCA1000 Format for details about this format. RRCA1100 Returns a value that indicates the network ID. See RRCA1100 Format for details about this format. RRCA1200 Returns a value that indicates that the device has a bar code reader. See RRCA1200 Format for details about this format. RRCA1300 Returns a value that indicates whether the device supports import and export operations. See RRCA1300 Format for details about this format. RRCA1400 Returns a value that indicates the library mode. See RRCA1400 Format for details about this format. RRCA1500 Returns a value that indicates whether the library reports vital product data (VPD). See RRCA1500 Format for details about this format. RRCA1600 Returns a value that indicates whether the library reports the address of the elements. See RRCA1600 Format for details about this format.
- Request criteria
- INPUT; CHAR(*)
The criteria for which the retrieval will be processed.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Request Criteria
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Handle |
| 16 | 10 | BINARY(4) | Search request |
| 20 | 14 | BINARY(4) | Key |
| 24 | 18 | BINARY(4) | Request indicator |
| 28 | 1C | CHAR(32) | Request data |
Field Descriptions
Handle. The value of the handle. The handle allows repeated calls to obtain more than one resource name that meets the request criteria. The handle is created through the Create Handle (QRZCRTH) API. The handle is required in conjunction with the first or next search request. The handle must be set to binary zeros in conjunction with the first search request when no next search request is needed. The user is responsible for deleting the handle when it is no longer needed. Use the Delete Handle (QRZDLTH) API to delete the handle.
Key. The key value indicating the type of data to be returned in the receiver variable. The format of these keys is described in the format descriptions RRCA0100 Format through RRCA1600 Format. See Field Descriptions for a description of these keys. Valid keys are:
| 1 | Type |
| 2 | Protocol supported |
| 3 | Controller description required |
| 4 | Assign command supported flag |
| 5 | Media format |
| 6 | Media class |
| 7 | Read-only flag |
| 8 | Resource classification |
| 9 | LAN speed |
| 10 | Configurable flag |
| 11 | Network ID applicable flag |
| 12 | Bar code reader flag |
| 13 | Import and export supported flag |
| 14 | Library mode |
| 15 | Library reports VPD flag |
| 16 | Library reports elements flag |
Request data. The field indicating which class and subclass, or type and model, or resource name to use in the search.
Following is the field structure to be used in the request data for class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Class |
| 4 | 4 | BINARY(4) | Subclass |
| 8 | 8 | CHAR(24) | Reserved |
Following are the valid values to be used for the class field:
| 1 | Tape drive class |
| 2 | Optical class |
| 3 | Workstation |
| 4 | Communications |
| 5 | Diskette |
Following are the valid values to be used for the subclass field:
| 1 | Subclass is for a device. |
| 2 | Subclass is for a controller. |
| 3 | Subclass is for a library. |
| 4 | Subclass is for a port. |
The reserved field must be set to hexadecimal zeros.
Following is the field structure to be used in the request data for type and model.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Type number |
| 10 | A | CHAR(10) | Model number |
| 20 | 14 | CHAR(12) | Reserved |
Type number. An object type number that is left-justified and filled with trailing blanks.
Model number. An object model number that is left-justified and filled with trailing blanks.
Reserved. This must be set to hexadecimal zeros.
Following is the field structure to be used in the request data for resource name.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(32) | Resource name |
Resource name. A 32-character name that is left-justified and filled with trailing blanks.
Request indicator. Whether the retrieval of the resource information is by class and subclass, or type and model, or resource name.
| 1 | Class and subclass |
| 2 | Type and model |
| 3 | Resource name |
Search request. Whether the search request is a first attempt or a next attempt to obtain the elements from a list of elements.
| 1 | The first attempt to obtain an element from a possible list of elements. |
| 2 | The next attempt to obtain an element from a possible list of elements. |
RRCA0100 Format
This format name is valid only when the request indicator is for class and subclass. An error results if this format name is used with type and model or with resource name.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Type |
RRCA0200 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(8) | Protocol supported |
RRCA0300 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Controller description required |
RRCA0400 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Assign command supported flag |
RRCA0500 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(8) | Media format |
RRCA0600 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(8) | Media class |
RRCA0700 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Read-only flag |
RRCA0800 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(8) | Resource classification 1 |
| 16 | 10 | CHAR(8) | Resource classification 2 |
| 24 | 18 | CHAR(8) | Resource classification 3 |
RRCA0900 Format
This format name is only valid when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(8) | LAN speed |
RRCA1000 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Configurable flag |
RRCA1100 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Network ID applicable flag |
RRCA1200 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Bar code reader flag |
RRCA1300 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Import and export supported flag |
RRCA1400 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(1) | Library mode |
RRCA1500 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Library reports VPD flag |
RRCA1600 Format
This format name is valid only when the request indicator is for type and model or for resource name. An error results if this format name is used with class and subclass.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Library reports elements flag |
Field Descriptions
Assign command supported flag. Whether the assign command is supported. Valid values for this field are 0 (No) and 1 (Yes).
Bar code reader flag. Whether the device has a bar code reader. Valid values for this field are 0 (No) and 1 (Yes).
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.
Configurable flag. Whether the resource can be configured. Valid values for this field are 0 (No) and 1 (Yes).
Controller description required. Whether a controller description is required. Valid values for this field are 0 (No) and 1 (Yes).
Import and export supported flag. Whether import and export operations are supported. Valid values for this field are 0 (No) and 1 (Yes).
LAN speed. A value that represents the speed of the local area network (LAN).
| Speed | Returned value |
|---|---|
| 4MB | X'0000000000000000' |
| 16MG | X'0000000000000001' |
| 4MB and 16MB | X'0000000000000002' |
| Not applicable | X'0000000000000003' |
Library mode. A value that represents how the media mover is accessed through a library. Valid values are:
| 0 | Not in a library |
| 1 | In a library where the media mover is on a different resource on this input/output processor (IOP). |
| 2 | In a library where the media mover is accessed through a communications line. |
| 3 | In a library where the device and the media mover are combined in the same resource. |
Library reports elements flag. Whether the library reports the address of the elements. Valid values for this field are 0 (No) and 1 (Yes).
Library reports VPD flag. Whether the library reports vital product data (VPD). Valid values for this field are 0 (No) and 1 (Yes).
Media class. The format of the data on the media.
| Format | Returned value |
|---|---|
| Unknown format | X'0000000000000000' |
| 1600 bpi format | X'0000000000000001' |
| 3200 bpi format | X'0000000000000002' |
| 6250 bpi format | X'000000000000003' |
| 38000 bpi format | X'0000000000000004' |
| 76000 bpi format | X'0000000000000005' |
| Qic24 format | X'0000000000000006' |
| Qic120 format | X'0000000000000007' |
| Qic150 format | X'0000000000000008' |
| Qic320 format | X'0000000000000009' |
| Qic1000 format | X'000000000000000A' |
| Qic2GB format | X'000000000000000B' |
| 2pt3GB format | X'000000000000000C' |
| 2pt5GB format | X'000000000000000D' |
| 3480 format | X'000000000000000E' |
| 3490 format | X'000000000000000F' |
| 2 GB format | X'0000000000000010' |
| 5 GB format | X'0000000000000011' |
| 7 GB format | X'0000000000000012' |
| QIC 525 format | X'0000000000000013' |
| QIC 3040 format | X'0000000000000014' |
| ISO9660 format | X'0000000000000015' |
| HPOFS format | X'0000000000000016' |
| 3590 format | X'0000000000000017' |
| 77 tracks per side; 96 tracks per inch | X'0000000000000018' |
| 77 tracks per side; 48 tracks per inch | X'0000000000000019' |
| FMT3570 | X'000000000000001A' |
| QIC5010 | X'000000000000001B' |
Media format. The type of media on which the data is stored.
| Media type | Returned value |
|---|---|
| Unknown class | X'0000000000000000' |
| 1/2 in. reel tape | X'0000000000000001' |
| 1/2 in. cartridge | X'0000000000000002' |
| 1/4 in. cartridge | X'0000000000000003' |
| 8 mm cartridge | X'0000000000000004' |
| 5-1/4 in. diskette | X'0000000000000005' |
| 8 in. diskette | X'0000000000000006' |
| WORM optical | X'0000000000000007' |
| CD-ROM optical | X'0000000000000008' |
| Magnet-optical | X'0000000000000009' |
| Mini | X'000000000000000A' |
Network ID applicable flag. Whether the resource uses a network ID. Valid values for this field are 0 (No) and 1 (Yes).
Protocol supported. The value for the protocol to be supported.
| Protocol | Value |
|---|---|
| None | X'0000000000000000' |
| SDLC | X'0000000000000001' |
| Bisynchronous | X'0000000000000002' |
| Asynchronous | X'0000000000000003' |
| X.25 | X'0000000000000004' |
| Token ring | X'0000000000000005' |
| X.25 compact disc (CD) | X'0000000000000006' |
| Twinaxial DLC | X'0000000000000007' |
| Open in CD | X'0000000000000008' |
| Ethernet | X'0000000000000009' |
| Lap E | X'000000000000000A' |
| Lap D | X'000000000000000B' |
| Network node | X'000000000000000C' |
| FDDI | X'000000000000000D' |
| Frame relay direct | X'000000000000000E' |
| Fax | X'000000000000000F' |
| SDLC short hold mode | X'0000000000000011' |
Read-only flag. Whether the device is read only. Valid values for this field are 0 (No) and 1 (Yes).
Resource classification 1. The type of hardware that the resource is.
Resource classification 2. The type of controller that the resource is.
Resource classification 3. The type of device that the resource is.
Type. The object type number.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0B3B E | Resource name not found. |
| CPF0B3D E | Format &1 is not valid with request indicator &2. |
| CPF0B33 E | The handle is not valid. |
| CPF0B34 E | The handle is in wrong state for operation. |
| CPF0B35 E | Invalid class. |
| CPF0B36 E | Invalid subclass. |
| CPF0B37 E | Invalid type. |
| CPF0B46 E | Materialize failed. |
| 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. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R6