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

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