Search Hardware Resource Entry (QRZSCHE) API
Required Parameter Group:
| 1 | Resource name | Output | Char(32) |
| 2 | Resource criteria | Input | Char(*) |
| 2 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Search Hardware Resource Entry (QRZSCHE) API retrieves the resource name of a hardware resource that matches the request criteria. The user of the API supplies the request criteria with key values. The first or next resource name that matches the request criteria is returned. Each call of this API returns only one resource name. Multiple calls may be necessary to obtain all resource names from a possible list of resource names. Each resource name can be used with other hardware resource APIs to get more information about the specific hardware resource.
Note: Some key values are used as a singular search criterion rather than as part of a more complex search. Searches that use a singular search criterion have very concise results; for example, a search for console controller can return a maximum of one possible resource name.
Some key values can be used in conjunction with other key values to make a search more precise.
You can use this API to do the following:
- Search for a hardware resource by type number
- Search for a hardware resource by model number
- Search for a hardware resource by serial number
- Search for all hardware resources. No special order or hierarchy is used when the resource names are returned.
- Search for the system data
- Search for a hardware resource by bus number
- Search for a controller storage resource
- Search for a controller workstation resource
- Search for a controller communications resource
- Search for an IOP storage resource
- Search for an IOP workstation resource
- Search for an IOP communications resource
- Search for the control panel
- Search for the service processor
- Search for the bus controller
- Search for the memory cards
- Search for the console controller
- Search for the console device
- Search for the main processor
- Search for system hardware
- Search for an input/output processor (IOP) shared object clustering (SOC) resource
- Search for the electronic-customer-support communications resource.
- Search for an IOP cryptographic resource
- Search for a cryptographic adapter
- Search for a cryptographic device
- Search for the processor capacity card
- Search for the interactive card
Note: Some of the search criteria can be used only by themselves.
Authorities and Locks
- API Public Authority
- *USE
Required Parameter Group
- Resource name
- OUTPUT; CHAR(32)
The receiver variable that receives the resource name based on the request criteria. The resource name is a 32-character field that is left-justified and padded with trailing blanks.
- Resource criteria
- INPUT; CHAR(*)
The criteria for which the search is processed. See Format of the Resource Criteria for details about this format.
- 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 Resource Criteria
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of structure |
| 4 | 4 | BINARY(4) | Offset to first variable length record |
| 8 | 8 | BINARY(4) | Number of variable length records |
| 12 | C | CHAR(16) | Handle |
| 28 | 1C | BINARY(4) | Search resource |
| 32 | 20 | BINARY(4) | Search request |
| CHAR(*) | Variable length records | ||
| These fields repeat for each variable length record. | BINARY(4) | Size of variable length record | |
| BINARY(4) | Key | ||
| BINARY(4) | Length of data | ||
| CHAR(*) | Data | ||
Field Descriptions
Data. The following table identifies the data field and the data type for the specified key.
| Key | Field | Type | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| -1 | All records1 | CHAR(1) | ||||||||
| 1 | Type (object type)2 | CHAR(10) | ||||||||
| 2 | Model number2 | CHAR(10) | ||||||||
| 4 | Serial number2 | CHAR(10) | ||||||||
| 6 | System information1 | CHAR(1) | ||||||||
| 7 | Bus number2 | BINARY(4) | ||||||||
| 8 | Controller storage1 | CHAR(1) | ||||||||
| 9 | Controller workstation1 | CHAR(1) | ||||||||
| 10 | Controller communication1 | CHAR(1) | ||||||||
| 11 | IOP storage1 | CHAR(1) | ||||||||
| 12 | IOP workstation1 | CHAR(1) | ||||||||
| 13 | IOP communication1 | CHAR(1) | ||||||||
| 14 | Control panel1 , 4 | CHAR(1) | ||||||||
| 15 | Service processor1 , 4 | CHAR(1) | ||||||||
| 16 | Bus controller1 | CHAR(1) | ||||||||
| 17 | Memory cards1 , 4 | CHAR(1) | ||||||||
| 18 | Console controller1 | CHAR(1) | ||||||||
| 19 | Console device1 | CHAR(1) | ||||||||
| 20 | Main processor1 , 4 | CHAR(1) | ||||||||
| 21 | System hardware1 | CHAR(1) | ||||||||
| 24 | IOP SOC1 | CHAR(1) | ||||||||
| 25 | Electronic-customer-support communications resource3 | CHAR(1) | ||||||||
| 26 | Primary-console-controller1 | CHAR(1) | ||||||||
| 27 | Cryptographic IOP1 | CHAR(1) | ||||||||
| 28 | Cryptographic IOA1 | CHAR(1) | ||||||||
| 29 | Cryptographic device1 | CHAR(1) | ||||||||
| 30 | Processor capacity card1 | CHAR(1) | ||||||||
| 31 | Interactive card1 | CHAR(1) | ||||||||
| 32 | Expanded serial number2 | CHAR(15) | ||||||||
Notes:
|
||||||||||
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/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 identifies the search criteria. Following are the key values that can be used:
| -1 | Search on all hardware resources. This key must not be used with any other key or an error will result. |
| 1 | Type number of a hardware resource. |
| 2 | Model number of a hardware resource. |
| 4 | Serial number of a hardware resource. The serial number must be in the form of xx-nnnnnnn, where xx is the plant of manufacture, dash (required), and nnnnnnn can be a 5-character serial number that is padded on the right with 2 blanks or a fully qualified 7-character serial number. |
| 6 | Resource name of the system. This key must not be used with any other key or an error will result. |
| 7 | Bus number of a hardware resource. |
| 8 | Controller storage hardware resource. |
| 9 | Controller workstation hardware resource. |
| 10 | Controller communications hardware resource. |
| 11 | IOP storage hardware resource. |
| 12 | IOP workstation hardware resource. |
| 13 | IOP communications hardware resource. |
| 14 | Control panel hardware resource. This key must not be used with any other key or an error will result. |
| 15 | Service processor hardware resource. This key must not be used with any other key or an error will result. |
| 16 | Bus controller hardware resource. This key must not be used with any other key or an error will result. |
| 17 | Memory card hardware resource. This key must not be used with any other key or an error will result. |
| 18 | Console controller hardware resource. This key must not be used with any other key or an error will result. |
| 19 | Console device hardware resource. This key must not be used with any other key or an error will result. |
| 20 | Main processor hardware resource. This key must not be used with any other key or an error will result. |
| 21 | System hardware resource. |
| 24 | IOP SOC hardware resource. |
| 25 | Electronic-customer-support communications resource. |
| 26 | Primary-console-controller hardware resource. This key must not be used with any other key or an error will result. |
| 27 | IOP cryptographic hardware resource. |
| 28 | IOA cryptographic hardware resource. |
| 29 | Cryptographic device hardware resource. This key must not be used with any other key or an error will result. |
| 30 | Processor capacity card. This key must not be used with any other key or an error will result. |
| 31 | Interactive card. This key must not be used with any other key or an error will result. |
| 32 | Expanded serial number of a hardware resource. |
Length of data. The number of bytes for the corresponding data field. For each field length, see the Type column of the table in Format of the Resource Criteria.
Length of structure. The total length (in bytes) of the structure provided, which includes this field through the end of the last variable length record.
Number of variable length records. The number of variable length records supplied.
Offset to first variable length record. The value (in bytes) from the beginning of the structure to the offset field of the first variable length record.
Search request. Whether the search request is a first attempt or a next attempt.
| 1 | The first attempt to obtain a resource name from a possible list of resource names. Search for the first list entry. |
| 2 | The next attempt to obtain a resource name from a possible list of resource names. Search for any subsequent list entry if it exists. |
Search resource. Whether to search for the resource name from the logical resource information or the packaging resource information.
| 1 | The logical resource information is searched. The logical resource information is the vital product data (VPD). |
| 2 | The packaging resource information is searched. The packaging resource information is the location data. This value is valid only with key -1, search all hardware resources. In logical partitions that contain virtual hardware, it is possible that this field would find 0 entries to match. |
Size of variable length record. The displacement from the current record to the next variable length record.
Variable length records. Each possible variable length record consists of the size of the variable length record, a key value, the length of the data, and the data.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0B3B E | Resource name not found. |
| CPF0B3C E | Search resource &1 is not valid with key &2. |
| CPF0B3F E | The reserved area is not set to binary zeros. |
| CPF0B33 E | The handle is not valid. |
| CPF0B34 E | The handle is in wrong state for operation. |
| CPF0B38 E | Resource information not valid. |
| CPF0B45 E | Materialize request is not applicable to resource &1. |
| CPF0B46 E | Materialize failed. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C82 E | Key &1 not valid for API &2. |
| 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