Create Handle (QRZCRTH) API
Required Parameter Group:
1 | Receiver variable | Output | Char(*) |
2 | Length of receiver variable | Input | Binary(4) |
3 | Format name | Input | Char(8) |
4 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Create Handle (QRZCRTH) API creates a handle that is used as a placeholder when possible list items are involved. Use this API to create a handle before calling a hardware resource API that has a handle parameter defined.
- Handle supplied to an API. The handle allows repeated
calls to obtain more than one list item. While retrieving possible list items,
a handle should be supplied when a first call attempt is used that is followed
by subsequent (next) call attempts.
- Handle not supplied to an API. While retrieving information, if an attempt is made only for the first call, a handle may be set to hexadecimal 0. If a subsequent (next) call is attempted by an API to retrieve information, the API is unable to determine if more information meets the supplied criteria unless the initial call is repeated through the use of a handle.
Note: The repeated API calls must have the same criteria and must involve the same API. Handles cannot be shared across different APIs or within the same API with different criteria.
You are required to delete any handles created by the Create Handle (QRZCRTH) API. See Delete Handle (QRZDLTH) API for more information.
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 returned. The possible format name is as follows:
HNDL0100 A handle that is 16 bytes in length is returned. See HNDL0100 Format 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.
HNDL0100 Format
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Bytes returned |
4 | 4 | BINARY(4) | Bytes available |
8 | 8 | CHAR(16) | Handle |
Field Descriptions
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.
Handle. The returned handle value to be used on subsequent API calls when a handle parameter is required.
Error Messages
Message ID | Error Message Text |
---|---|
CPF0B31 E | A handle failed to create. |
CPF24B4 E | Severe error while addressing parameter list. |
CPF3CF1 E | Error code parameter not valid. |
CPF3C19 E | Error occurred with receiver variable specified. |
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. |
API introduced: V3R6