Retrieve Hardware Resource Relative (QRZRTVR) API

The Retrieve Hardware Resource Relative (QRZRTVR) API retrieves the resource name of a family member that matches the resource criteria. The user of the API supplies the resource criteria, and the first or next resource name that matches the resource criteria is returned. The resource name can be used with other hardware resource APIs to get more information about a specific hardware resource.

You can use this API to do the following:

• Retrieve the resource name of the parent resource. You can move up the hierarchical path by using the attempt, FIRST.
• Retrieve a resource name of the child resource. You can move down or across the hierarchical path by using either the attempt, FIRST, or the attempt, NEXT.

Example of a Resource Hierarchy

In Example of a Resource Hierarchy, the attempt, FIRST, moves down the child resource hierarchy. For example, if in the resource criteria, Resource A is specified in the search resource name field, the search request of FIRST results in receiving Resource B.

Another search request of FIRST that still uses Resource A results in receiving Resource B. If the search resource name field in the resource criteria is changed to Resource B, the search request of FIRST results in receiving Resource E. If the search resource name field in the resource criteria is changed to Resource E, the search request of FIRST results in an error, CPF0B46 (Materialize failed).

The attempt NEXT travels across the sibling resource structure. If the search resource name field in the resource criteria is Resource A, the search request of FIRST results in receiving Resource B. Another search request of NEXT that still uses Resource A results in receiving Resource C. Another search request using NEXT results in receiving Resource D. Another search request using NEXT results in an error of no resource found.

Once the specified resource is found, the attempt FIRST, using the found resource, moves down to a different level of the child hierarchy, and the attempt NEXT travels across that resource sibling level, and so on.

Retrieve the resource name of the associated package resource. Hardware resources possibly contain both packaging resource data and logical resource data. For each type of data that exists, the resource names are unique. If the logical resource name is known, the package resource name can be obtained through the associated packaging resource hierarchical path.

Retrieve the resource name of the associated logical resource. Hardware resources possibly contain both logical resource data and packaging resource data. For each type of data that exists, the resource names are unique. If the packaging resource name is known, the logical resource name can be obtained through the associated logical resource hierarchical path.

Authorities and Locks

API Public Authority

*EXCLUDE

Required Parameter Group

Resource name

OUTPUT; CHAR(32)

A variable that receives the resource name.

Resource criteria

INPUT; CHAR(*)

The criteria for which the search will be processed. See Format of the Resource Criteria for details of 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

Field Descriptions

Handle. The unique value that is obtained through the Create Handle (QRZCRTH) API. The handle allows repeated calls to obtain more than one resource name that meets the resource criteria. The handle is created through the Create Handle (QRZCRTH) API. The handle is required in conjunction with the first and next search request.

The handle must be set to hexadecimal zeros in conjunction with the first search request when a next search request is not needed. A handle can be used to move across a horizontal level of a hierarchy, but it cannot be used on more than one level.

For example, in Example of a Resource Hierarchy, handle 1, based on the search resource name of A, can be used on a FIRST attempt to receive resource B, and on a NEXT attempt to receive resource C and then resource D.

Handle 1, however, cannot be used on a FIRST attempt to receive resource B, and then on a FIRST attempt to receive resource E. Handle 1 cannot be used on two different levels of the hierarchy (B and E); this results in error message CPF0B34 (the handle is in the wrong state for the operation) being issued. To correct this situation, either use a different handle, or do not use a handle by setting the field to hexadecimal zeros.

The user is responsible for deleting the handle when it is no longer needed. Use the Delete Handle (QRZDLTH) API to delete the handle.

Hierarchical path. Whether the path is for a parent, a child, an associated packaging resource, or an associated logical resource.

Search request. Whether the call is a first attempt or a next attempt to obtain more than one list item resource name that meets the resource criteria.

Search resource name. The resource name to be used as the focal point of a first attempt or any subsequent next attempts.

Error Messages