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	Type	Field
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 records¹

CHAR(1)

Type (object type)²

CHAR(10)

Model number²

CHAR(10)

Serial number²

CHAR(10)

System information¹

CHAR(1)

Bus number²

BINARY(4)

Controller storage¹

CHAR(1)

Controller workstation¹

CHAR(1)

Controller communication¹

CHAR(1)

IOP storage¹

CHAR(1)

IOP workstation¹

CHAR(1)

IOP communication¹

CHAR(1)

Control panel¹ ^{, 4}

CHAR(1)

Service processor¹ ^{, 4}

CHAR(1)

Bus controller¹

CHAR(1)

Memory cards¹ ^{, 4}

CHAR(1)

Console controller¹

CHAR(1)

Console device¹

CHAR(1)

Main processor¹ ^{, 4}

CHAR(1)

System hardware¹

CHAR(1)

IOP SOC¹

CHAR(1)

Electronic-customer-support communications resource³

CHAR(1)

Primary-console-controller¹

CHAR(1)

Cryptographic IOP¹

CHAR(1)

Cryptographic IOA¹

CHAR(1)

Cryptographic device¹

CHAR(1)

Processor capacity card¹

CHAR(1)

Interactive card¹

CHAR(1)

Expanded serial number²

CHAR(15)

Notes:

¹	The field is ignored. Field ignored indicates that data does not have to be supplied. However, the length of data field in the corresponding variable length record needs to be set to the correct length.
²	The field is a required search value.
³	The resource name that is returned is for the first port on the I/O adapter in card position B of the first multifunction IOP on the bus.
⁴	In logical partitions that contain virtual hardware, it is possible that this type of search would find 0 entries to match.

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

[ Back to top | Configuration APIs | APIs by category ]