Retrieve Hardware Resource List (QGYRHRL, QgyRtvHdwRscList) 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 category | Input | Binary(4) |
| 5 | Error code | I/O | Char(*) |
Service Program: QGYRHR
Default Public Authority: *USE
Threadsafe: No
The Retrieve Hardware Resource List (OPM, QGYRHRL; ILE, QgyRtvHdwRscList) API retrieves a list of hardware resource names and other hardware resource information fields. The list provides a summary description for each resource in the specified resource category.
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 16 bytes.
- Format name
- INPUT; CHAR(8)
The content and format of the information returned. The possible format names are as follows:
RHRL0100 Summary information for resources in each of the resource categories is returned in this format. For more information, see RHRL0100 Format. RHRL0110 Same as RHRL0100 with the addition of a description text message ID field a status extended field and a reserved field. This format cannot be used with the Local area network resources resource category. For more information, see RHRL0110 Format.
- Resource category
- INPUT; BINARY(4)
The hardware resource category for which information is to be returned. Possible values are as follows:
1 All hardware resources (does not include local area network resources) 2 Communication resources 3 Local work station resources 4 Processor resources 5 Storage device resources 6 Coupled system adapter resources 7 Local area network resources 8 Cryptographic resources 9 Tape and optical resources 10 Tape resources 11 Optical resources Note: When selecting Local area network resources, only information for token-ring resources can be obtained. Information for token-ring resources associated with a particular line description will be returned only if the Work with LAN Adapters (WRKLANADPT) command has been run with that line description specified. It is also necessary for the LAN Manager to have been activated for that line description. The LAN Manager is activated by running the Create Line Description Token-Ring Network (CRTLINTRN) or the Change Line Description Token-Ring Network (CHGLINTRN) command with keyword ACTLANMGR set to *YES. WRKLANADPT must be run again after adding a new token-ring resource in order to be able to retrieve information for that resource.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
RHRL0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of resources returned |
| 12 | C | BINARY(4) | Length of resource entry |
| CHAR(*) | Resource entries | ||
| These fields repeat for each resource. | BINARY(4) | Resource category | |
| BINARY(4) | Family level | ||
| BINARY(4) | Line type | ||
| CHAR(10) | Resource name | ||
| CHAR(4) | Type number | ||
| CHAR(3) | Model number | ||
| CHAR(1) | Status | ||
| CHAR(8) | System to which adapter is connected | ||
| CHAR(12) | Adapter address | ||
| CHAR(50) | Description | ||
| CHAR(24) | Resource kind | ||
RHRL0110 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of resources returned |
| 12 | C | BINARY(4) | Length of resource entry |
| CHAR(*) | Resource entries | ||
| These fields repeat for each resource. | BINARY(4) | Resource category | |
| BINARY(4) | Family level | ||
| BINARY(4) | Line type | ||
| CHAR(10) | Resource name | ||
| CHAR(4) | Type number | ||
| CHAR(3) | Model number | ||
| CHAR(1) | Status | ||
| CHAR(8) | System to which adapter is connected | ||
| CHAR(12) | Adapter address | ||
| CHAR(50) | Description | ||
| CHAR(24) | Resource kind | ||
| CHAR(7) | Description text message ID | ||
| CHAR(1) | Reserved | ||
| BINARY(4) | Status extended | ||
Field Descriptions
Adapter address. The network address of the LAN adapter resource.
Bytes available. The length in bytes of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length in bytes of all data actually returned.
Description. The description of the resource.
Description text message ID. The message from which the text of the Description field is obtained. This message is contained in the QCPFMSG message file. The library in which it is found is determined by *LIBL.
Family level. The relationship between adjacent returned resources. Possible values are positive integers starting with 1, incrementing as needed to match the number of existing family levels. The first three values are as follows:
| 1 | This resource is parent to the next resource if the next resource has a resource family level of 2. |
| 2 | This resource is child to the previous resource that has a resource family level of 1, and is parent to the next resource if the next resource has a resource family level of 3. |
| 3 | This resource is child to the previous resource that has a resource family level of 2, and is grandchild to the previous resource that has a resource family level of 1. It is parent to the next resource if the next resource has a resource family level of 4. |
Length of resource entry. The length, in bytes, of each resource entry.
Line type. The line type of the LAN resource. Possible values are as follows:
| -1 | This field does not apply to this resource. |
| 1 | Token ring. |
| 2 | Fiber distributed data interface (FDDI). |
Model number. The model number of the resource. For self-configuring tape devices, this represents the emulated device model number.
Number of resources returned. The total number of resources for which information is returned by the API.
Reserved. A reserved field.
Resource category. The hardware resource category of the resource for which information is returned. If the input parameter Resource category is set to the number 1 (All hardware resources), the format field value returned here is set to one of the other more specific values. Otherwise, the returned value matches the input value. Possible values are as follows:
| 2 | Communication resources |
| 3 | Local workstation resources |
| 4 | Processor resources |
| 5 | Storage device resources |
| 6 | Coupled system adapter resources |
| 7 | Local area network resources |
| 8 | Cryptographic resources |
| 9 | Tape and optical resources |
| 10 | Tape resources |
| 11 | Optical resources |
Resource entries. The sets of information fields that are retrieved for each resource.
Resource kind. The resource kind field consists of 24 bytes of hexadecimal numbers. It can be divided into three 8-byte fields called Kind 1, Kind 2, and Kind 3. The system uses Kind 1, Kind 2, and Kind 3 to categorize the resource.
Resource name. The name of the resource for which the information in the resource entry applies. The name can be used as input to the Retrieve Hardware Resource Information (QGYRHRI, QgyRtvHdwRscInfo) API.
Status. Whether the resource is operational or not. Possible values are as follows:
| 0 | The status field does not apply to this resource or could not be determined. |
| 1 | Operational. Resource is operational. |
| 2 | Inoperative. Resource is not operational. |
| 3 | Not detected. Presence of resource could not be detected. |
Status extended. The extended hardware status of the resource. Possible values are as follows:
| 0 | Resource is powered off or no power is being supplied to it. |
| 1 | Resource has failed. |
| 2 | Resource is operational. |
| 3 | Resource is operational but errors have been detected. |
| 4 | Resource is not connected. |
| 5 | Resource is operational but performance is degraded. |
| 6 | Resource status is unknown currently. |
| 7 | Resource is currently disabled. |
| 8 | Resource is not installed. |
| 10 | Resource is not operational. |
| 16 | Resource is failed due to a system software error. |
System to which adapter is connected. The system to which the coupled system adapter is connected.
Type number. An identifier that represents the object type of this resource. For self-configuring tape devices, this represents the emulated device type number. Exceptions: Value of *TAP implies that a self-configuring tape device is emulating a device type that contains characters outside the range of 0 to 9 and A to Z.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3CF1 E | Error code parameter not valid. |
| 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. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFA280 E | Resource category &1 is not valid. |
API introduced: V3R7