Retrieve Hardware Resource Information (QGYRHRI, QgyRtvHdwRscInfo) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Resource name | Input | Char(10) |
| 5 | Error code | I/O | Char(*) |
Service Program Name: QGYRHR
Default Public Authority: *USE
Threadsafe: No
The Retrieve Hardware Resource Information (OPM, QGYRHRI; ILE, QgyRtvHdwRscInfo) API retrieves hardware resource information fields that, together with the output from the Retrieve Hardware Resource List (OPM, QGYRHRL; ILE, QgyRtvHdwRscList) API, provides a detailed description of the resource identified by the resource name parameter. This API is meant to be used after obtaining a list of resource names with the Retrieve Hardware Resource List API.
Authorities and Locks
- API Public 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 that is returned. The possible format names are as follows:
RHRI0100 Detailed information for communication hardware resources. For more information, see RHRI0100 Format. RHRI0200 Detailed information for coupled system adapter resources. For more information, see RHRI0200 Format. RHRI0300 Detailed information for local workstation resources. For more information, see RHRI0300 Format. RHRI0400 Detailed information for processor resources. For more information, see RHRI0400 Format. RHRI0410 Detailed information for processor resources. Using this format allows information for the Processor Capacity Card and Interactive Card to be returned. For more information, see RHRI0410 Format. RHRI0500 Detailed information for storage device resources, including tape and optical resources. For more information, see RHRI0500 Format. RHRI0600 Detailed information for cryptographic resources. For more information, see RHRI0600 Format.
- Resource name
- INPUT; CHAR(10)
The name of the hardware resource for which information is to be returned.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
RHRI0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | System bus number |
| 12 | C | BINARY(4) | System board number |
| 16 | 10 | BINARY(4) | System card number |
| 20 | 14 | BINARY(4) | I/O bus address |
| 24 | 18 | BINARY(4) | Adapter address |
| 28 | 1C | BINARY(4) | Port number |
| 32 | 20 | CHAR(10) | Serial number |
| 42 | 2A | CHAR(12) | Part number |
| 54 | 36 | CHAR(4) | Frame ID |
| 58 | 3A | CHAR(5) | Card position |
| 63 | 3F | CHAR(79) | Location code |
| 142 | 8E | CHAR(15) | Expanded serial number |
| 157 | 9D | CHAR(8) | LAN speed |
| 165 | A5 | CHAR(1) | Supports link aggregation |
RHRI0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | System bus number |
| 12 | C | BINARY(4) | System board number |
| 16 | 10 | BINARY(4) | System card number |
| 20 | 14 | CHAR(10) | Serial number |
| 30 | 1E | CHAR(12) | Part number |
| 42 | 2A | CHAR(4) | Frame ID |
| 46 | 2E | CHAR(5) | Card position |
| 51 | 33 | CHAR(79) | Location code |
| 130 | 82 | CHAR(15) | Expanded serial number |
RHRI0300 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | System bus number |
| 12 | C | BINARY(4) | System board number |
| 16 | 10 | BINARY(4) | System card number |
| 20 | 14 | BINARY(4) | I/O bus address |
| 24 | 18 | BINARY(4) | Adapter address |
| 28 | 1C | BINARY(4) | Port number |
| 32 | 20 | BINARY(4) | Device address |
| 36 | 24 | BINARY(4) | Shared session number |
| 40 | 28 | CHAR(10) | Serial number |
| 50 | 32 | CHAR(12) | Part number |
| 62 | 3E | CHAR(4) | Frame ID |
| 66 | 42 | CHAR(5) | Card position |
| 71 | 47 | CHAR(79) | Location code |
| 150 | 96 | CHAR(15) | Expanded serial number |
RHRI0400 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | System bus number |
| 12 | C | BINARY(4) | System board number |
| 16 | 10 | BINARY(4) | System card number |
| 20 | 14 | CHAR(10) | Serial number |
| 30 | 1E | CHAR(12) | Part number |
| 42 | 2A | CHAR(4) | Frame ID |
| 46 | 2E | CHAR(5) | Card position |
| 51 | 33 | CHAR(4) | System processor feature code |
| 55 | 37 | CHAR(79) | Location code |
| 134 | 86 | CHAR(15) | Expanded serial number |
RHRI0410 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | System bus number |
| 12 | C | BINARY(4) | System board number |
| 16 | 10 | BINARY(4) | System card number |
| 20 | 14 | CHAR(10) | Serial number |
| 30 | 1E | CHAR(12) | Part number |
| 42 | 2A | CHAR(4) | Frame ID |
| 46 | 2E | CHAR(5) | Card position |
| 51 | 33 | CHAR(4) | System processor feature code |
| 55 | 37 | CHAR(4) | Processor feature code |
| 59 | 3B | CHAR(4) | Interactive feature code |
| 63 | 3F | CHAR(79) | Location code |
| 142 | 8E | CHAR(15) | Expanded serial number |
RHRI0500 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | System bus number |
| 12 | C | BINARY(4) | System board number |
| 16 | 10 | BINARY(4) | System card number |
| 20 | 14 | BINARY(4) | I/O bus address |
| 24 | 18 | BINARY(4) | Controller address |
| 28 | 1C | BINARY(4) | Device address |
| 32 | 20 | CHAR(5) | Device position |
| 37 | 25 | CHAR(10) | Serial number |
| 47 | 2F | CHAR(12) | Part number |
| 59 | 3B | CHAR(4) | Frame ID |
| 63 | 3F | CHAR(5) | Card position |
| 68 | 44 | CHAR(79) | Location code |
| 147 | 93 | CHAR(15) | Expanded serial number |
RHRI0600 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | System bus number |
| 12 | C | BINARY(4) | System board number |
| 16 | 10 | BINARY(4) | System card number |
| 20 | 14 | BINARY(4) | I/O bus address |
| 24 | 18 | BINARY(4) | Adapter address |
| 28 | 1C | BINARY(4) | Device address |
| 32 | 20 | CHAR(10) | Serial number |
| 42 | 2A | CHAR(12) | Part number |
| 54 | 36 | CHAR(4) | Frame ID |
| 58 | 3A | CHAR(5) | Card position |
| 63 | 3F | CHAR(79) | Location code |
| 142 | 8E | CHAR(15) | Expanded serial number |
Field Descriptions
Adapter address. The adapter address of the resource. A value of -1 means that this field does not apply to the resource.
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.
Card position. The physical location where the device or feature is plugged into the bus. This field will be set to blanks if the value does not apply to the resource.
Controller address. The controller address of the resource. A value of -1 means that this field does not apply to the resource.
Device address. The device address of the resource. A value of -1 means that this field does not apply to the resource.
Device position. The relative device position of the resource. This field will be set to blanks if the value does not apply to the resource.
Expanded serial number. The expanded manufacturing sequence number of designation for the resource.
Frame ID. The identifier of a frame resource. This field will be set to blanks if the value does not apply to the resource.
Interactive feature code. The interactive feature of the system. This feature defines the portion of the processor that can be used to perform interactive work.
I/O bus address. The I/O bus address of the resource. A value of -1 means that this field does not apply to the resource.
LAN speed. The LAN speed for communications ports. A value of all X'FF' means this field does not apply to the resource. Possible values are as follows:
| LAN speed | Returned value |
|---|---|
| 4 Meg | X'0000000000000000' |
| 16 Meg | X'0000000000000001' |
| 4 and 16 Meg | X'0000000000000002' |
| not applicable | X'0000000000000003' |
| 25 Meg | X'0000000000000004' |
| 45 Meg | X'0000000000000005' |
| 100 Meg | X'0000000000000006' |
| 155 Meg | X'0000000000000007' |
| 34 Meg | X'0000000000000008' |
| 10 and 100 Meg | X'0000000000000009' |
| 10 Meg, 100 Meg, and 1Gig | X'000000000000000A' |
| 10 Gig | X'000000000000000B' |
| 1 and 10 Gig | X'000000000000000C' |
Location code. The physical location of the hardware resource in the system. This field is available only if the system supports the location code format and if the value applies for the resource; otherwise will be set to blanks. The location code field is a sequence of 0 or more location labels that when followed in order, lead to the resource location. This is the place someone could go to view, remove, or replace the piece of hardware. Location labels are etched, silk screened, or marked in other ways on hardware. The following location labels might be shown in the location code field (n represents a numerical or alphabetical identifier):
| Utttt.mmm.sssssss | Unit location |
| Pnn | Planar location |
| Cnn | Card location |
| Tnn | Port location |
| Dnn | Device location |
| Vnnn | Virtual planar |
| Wnnnnnnnnnnnnnnnn | Worldwide port name |
| Lnn | Logical path location |
Following are the descriptions of the location labels:
| Unit location | Value of the unit enclosure identifier composed of uppercase alphabetic characters and digits. Commonly this value will be composed of the machine type (tttt), model (mmm) and serial number (sssssss). |
| Planar location | Decimal value of the planar identifier within the unit. |
| Card location | The decimal value of the position of the card within the hardware package. This can be followed by additional card location labels that would identify the decimal value of additional card positions of the resource on the card. |
| Port location | The decimal value of the port location within the resource. |
| Device location | The decimal value of the position of the device within the hardware package. |
| Virtual planar | The decimal value of the position of the virtual planar resource within the hardware package. |
| Worldwide port name | The hexadecimal value of the worldwide port name of the resource within the hardware package. This value is usually present for fibre channel devices. It will be blank for fibre channel adapters. See the Retrieve Resource Information (QRZRRSI) API and key value 169 for fibre channel adapters. |
| Logical path location | The decimal value of the logical path of the resource within the hardware package. This can be followed by additional logical path location labels that would identify the decimal value of additional logical path data of the resource on the hardware package. |
Part number. A manufacturing identifier that represents similar types of hardware. This field will be set to blanks if the value does not apply to the resource.
Port number. The port number of the resource. A value of -1 means that this field does not apply to the resource.
Processor feature code. The processor feature, which corresponds to the processor capacity of the system.
Serial number. The manufacturing sequence number of designation for the resource.
Shared session number. The shared session number of the resource. A value of -1 means that this field does not apply to the resource.
Supports link aggregation. Whether ports can be aggregated to compose an aggregate line. A value of X'01' means link aggregation is supported. A value of X'02' means link aggregation is not supported. A value of X'FF' means this field does not apply to the resource.
System board number. A numerical representation of a section of the bus into which the card is plugged. A value of -1 means that this field does not apply to the resource.
System bus number. A numerical representation of the path connection of the system processor to the card. A value of -1 means that this field does not apply to the resource.
System card number. A numerical representation of the location of the card on the bus. A value of -1 means that this field does not apply to the resource.
System processor feature code. The processor feature code level of the system. A value is returned for this field only if the Kind 3 value of the hardware resource indicates that the resource provides system information (X'0000000000080000'). The Kind 3 value is returned in the "Resource kind" field by the Retrieve Hardware Resource List API.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA290 E | Resource name &1 is not valid. |
| CPF3C1E E | Required parameter &1 omitted. |
| 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: V3R7