HWTJGAEN — Get array entry

Description

The HWTJGAEN service returns the handle of a particular array entry (entryValueHandle) as specified by the index of that array entry (arrayEntryIndex). The returned handle is used on subsequent calls to service calls to inquire about the value of this particular array entry.

Environment

The requirements for the caller are:

Requirement	Details
Minimum authorization:	Supervisor state or problem state, any PSW key.
Dispatchable unit mode:	Task or SRB.
Cross memory mode:	Any PASN, any HASN, any SASN.
AMODE:	31-bit.
ASC mode:	Primary or access register (AR).
Interrupt status:	Enabled for I/O and external interrupts.
Locks:	No locks held.
Control parameters:	Control parameters must be in the primary address space and addressable by the caller.
Linkage:	Standard MVS™ linkage conventions are used.

Programming requirements

See Syntax, linkage, and programming considerations for details about how to call the z/OS® JSON parser services in the various supported programming languages.

REXX programming considerations for the HWTJGAEN service

All information for the HWTJGAEN service applies for REXX requests.

Syntax

Write the call as shown in the following syntax diagram. You must code all parameters in the order shown.

Non-REXX parameters	REXX parameters
CALL HWTJGAEN( ReturnCode, ParserHandle, ObjectHandle, ArrayEntryIndex, EntryValueHandle, DiagArea);	address hwtjson "hwtjgaen", "ReturnCode", "ParserHandle", "ObjectHandle", "ArrayEntryIndex", "EntryValueHandle", "DiagArea."

Parameters

The parameters are explained as follows:

ReturnCode

Returned parameter.

Type: Integer (non-REXX), character representation of an integer (REXX)
Length: 4 bytes (non-REXX)

Contains the return code from the service.

ParserHandle

Supplied parameter.

Type: Character string
Length: 12 bytes (non-REXX)

Specifies the JSON parser instance to be used.

ObjectHandle

Supplied parameter.

Type:Integer (non-REXX), character representation of an integer (REXX)
Length: 4 bytes (non-REXX)

Specifies a particular JSON array object. The objectHandle must have a JSON type of HWTJ_ARRAY_TYPE.

ArrayEntryIndex

Supplied parameter.

Type: Integer (non-REXX), character representation of an integer (REXX)
Length: 4 bytes (non-REXX)

Specifies the index of the n^th entry of the array object specified by objectHandle.

Note: This is a zero-origin index, meaning that the first entry in the array has an index of zero; the n^th entry has an index of (n − 1).

EntryValueHandle

Returned parameter.

Type: Integer (non-REXX), character representation of an integer (REXX)
Length: 4 bytes (non-REXX)

The handle representing the particular entry value selected in the JSON array object.

DiagArea (non-REXX)

DiagArea. (REXX)

Returned parameter.

Type: Character string (non-REXX), stem variable (REXX)
Length: 136 bytes (non-REXX)

A storage area provided by the caller that may contain additional diagnostic information related to the service call. It consists of a 4-byte integer reason code field and a 128-byte character string error text field.

ABEND codes

If the toolkit is unable to properly access the user-supplied parameter list, the call might result in a X'04D' ABEND with a reason code of X'0002yyyy' for one of the following reasons:

yyyy: Reason
0000: The parameters passed by the caller are not in the primary address space.
0001: The number of parameters passed by the caller is incorrect.

Return codes

When the service returns control to the caller, GPR 15 and the returnCode parameter contain a hexadecimal return code, as listed in Table 1.

Table 1. Return codes for the HWTJGAEN service
Hexadecimal return code Equate symbol	Meaning and action
0 HWTJ_OK	Meaning: Successful completion. Action: None.
101 HWTJ_PARSERHANDLE_INV	Meaning: Program error. The parserHandle parameter specified on the service call is not a valid parser handle (one that was returned by the HWTJINIT service). Action: Check for a probable coding error.
102 HWTJ_PARSERHANDLE_INUSE	Meaning: Program error. Two possible reasons can result in this return code: The parser handle is being used by another caller. Only one outstanding z/OS JSON parser service can use the same parser handle. A previous service request using this parser handle resulted in an ABEND, and the parser instance was unable to indicate that its use of the parser handle has completed. Action: Check for a probable coding error. While all z/OS JSON parser service calls are synchronous (blocking), if more than one task, process, or thread is running simultaneously and using the same parser handle, only one will be allowed access. Change the application such that only one thread attempts to use the same parser handle at a time. If the application detected an ABEND while the z/OS JSON parser was invoked, the parser instance associated with the parser handle could be permanently locked. To release the storage associated with the parser work area, issue the HWTJTERM service call with a forceOption of HWTJ_NOFORCE. If this fails with the same return code, issue another HWTJTERM service call with a forceOption of HWTJ_FORCE.
103 HWTJ_INACCESSIBLE_PARM	Meaning: Program error. The application passed an input or output parameter which was inaccessible by the parser. See General programming considerations for details about z/OS JSON parser recovery processing. Action: Check for a probable coding error. Likely, the recovery of the caller detected this return code as a result of the parser abnormally ending with a `X'0C4'` system ABEND. Check the diagArea for an explanation as to which parameter was attempting to be accessed when the parser service call abnormally ended. See General programming considerations for details about actions to consider for this return code.
104 HWTJ_HANDLE_INV	Meaning: Program error. The value specified for the objectHandle parameter is not valid. Action: Check for a probable coding error. Only pass an objectHandle parameter that was returned by a prior z/OS JSON parser service call.
105 HWTJ_HANDLE_TYPE_ERROR	Meaning: Program error. The specified objectHandle does not represent an array object (JSON type of HWTJ_ARRAY_TYPE). Action: Check for a probable coding error. Correct the mismatched handle and specify an objectHandle value that represents an array handle.
107 HWTJ_INDEX_OUT_OF_BOUNDS	Meaning: Program error. The index value specified by the arrayEntryIndex parameter is greater than the number of entries in the array. Action: Check for a probable coding error. Issue the HWTJGNUE (Get number of entries) service to determine the upper bound for the number of array entries. Remember that the number of entries returned is the actual count of entries, but accessing a particular entry uses zero-origin indexing. To iterate through all the elements, the application must start at the first entry (index 0) up to the number of entries, minus 1.
F01 HWTJ_INTERRUPT_STATUS_INV	Meaning: Program error. The calling program is disabled. The system rejects the service request. Action: Check the calling program for a probable coding error.
F02 HWTJ_LOCKS_HELD	Meaning: Program error. The calling program is holding one or more locks. The system rejects the service request. Action: Check the calling program for a probable coding error.
F03 HWTJ_UNSUPPORTED_RELEASE	Meaning: The operating system level does not support this service. The system rejects the service request. Action: Remove the calling program from this system, install it on a system that supports z/OS JSON parser services, and run the calling program again.
FFF HWTJ_UNEXPECTED_ERROR	Meaning: System error. The service encountered an unexpected error. The system rejects the service call. Action: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM® Support Center.