HWTJTERM — Terminate a parser instance

Description

When the services of a z/OS® JSON parser instance are no longer needed, this service cleans up the resources in use by that parser instance. If this service is not invoked, the memory space allocated by the initialization and other parser services is allocated and ineligible for use by the application, and remains allocated until the job step task of the address space terminates.

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 HWTJTERM service

All information for the HWTJTERM service applies for REXX requests except:

ForceOption is not used

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 HWTJTERM( ReturnCode, ParserHandle, ForceOption, DiagArea);	address hwtjson "hwtjterm", "ReturnCode", "ParserHandle", "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

Returned parameter.

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

Specifies the JSON parser instance to be cleaned up. The parserHandle value was returned on a previous HWTJINIT service call for the particular JSON parser instance.

ForceOption (non-REXX)

Supplied parameter.

Type: Integer
Length: 4 bytes

Controls the behavior of the HWTJTERM service. Sometimes a parser instance can be stuck in an in-use state and cannot be terminated successfully. The in-use state can occur if a prior z/OS JSON parser service call resulted in an ABEND condition. This option allows the caller to force the parser instance to terminate. The valid values are:

HWTJ_NOFORCE

(Recommended) Terminates the parser instance and invalidates its parser handle only if the parser instance is not in an in-use state.

HWTJ_FORCE

Unconditionally terminates the parser instance and invalidates its parser handle, regardless of the in-use status of the parser instance.

Attention: Only use the HWTJ_FORCE option under the following conditions:

No other threads in the address space are using this parser instance
Multiple attempts to terminate the parser instance have resulted in a return code of HWTJ_PARSERHANDLE_INUSE.

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 might 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'000Cyyyy' 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 HWTJTERM 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 specified parserHandle parameter is not a valid parser handle (that is, 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 is 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 calls abnormally ended. See General programming considerations for details about actions to consider for this return code.
701 HWTJ_JTERM_CANNOT_FREE_WORKA	Meaning: System error. The Storage Release service could not release the work area storage as requested by the z/OS JSON parser. Action: Consult the diagArea for the Storage Release failure return code and additional information found in the diagDesc section. If the problem persists, search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM® Support Center.
702 HWTJ_JTERM_FORCEOPTION_INV	Meaning: Program error. The caller specified an invalid forceOption value. Action: Check for a probable coding error. The caller should change the forceOption value to one of the valid values, as described in Parameters.
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.