HWTJGNUV — Get number value (non-REXX)

Call the HWTJGNUV service to obtain the binary representation of a JSON number.

Description

The HWTJGNUV service returns the binary representation of a JSON number. The service returns a number in integer or floating-point format, based on the actual character-based number value represented by the specified entry value handle (entryValueHandle). This service may only be called when the JSON type for the entryValueHandle is HWTJ_NUMBER_TYPE. Consider using HWTJGVAL if no data conversion of a number is required.

If the value contains a decimal point or the scientific notation indicator (e or E), the service converts the value to a floating-point number. Conversely, if the value contains neither a decimal point nor the scientific notation indicator, the service converts the value to an integer number.

Underflow conditions: Converting a floating-point number may result in a number that is too small to be arithmetically represented in the buffer length as specified by the valueBufferLen (precision) parameter. This is known as an underflow condition, and this service will return a value of zero in this case. If this is not an acceptable outcome for the application and the valueBufferLen value can be increased, the application should increase the valueBufferLen value and reissue the request.

As with any floating-point number handling, use caution when performing floating-point conversions on certain types of data, such as currency values, as unexpected results may occur.

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.

Syntax

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

Parameters
CALL HWTJGNUV( ReturnCode, ParserHandle, EntryValueHandle, ValueBufferAddr, ValueBufferLen, ValueDescriptor, DiagArea);

Parameters

The parameters are explained as follows:

ReturnCode

Returned parameter

Type: Integer
Length: 4 bytes

Contains the return code from the service.

ParserHandle

Supplied parameter

Type: Character string
Length: 12 bytes

Specifies the JSON parser instance to be used.

EntryValueHandle

Supplied parameter

Type: Integer
Length: 4 bytes

Specifies a handle representing an entry in a JSON object that has a JSON type of NUMBER.

ValueBufferAddr

Supplied parameter

Type: Pointer
Length: 4 bytes

Specifies the address of an 8-byte buffer where this service will store the converted number. After the service completes, the buffer contains the numeric binary representation of the number represented by the specified entryValueHandle parameter. The valueDescriptor parameter will indicate the format of the binary data pointed to by this parameter. The value could be a positive or negative 8-byte integer or an 8-byte floating-point number in IEEE binary floating-point format.

ValueBufferLen

Supplied parameter

Type: Integer
Length: 4 bytes

Specifies the length (precision) of the buffer as specified by the valueBufferAddr parameter. The length specified here will determine the precision of the number returned by the service. The valid values are:

4: The service will return either a 4-byte signed integer or a 4-byte IEEE floating-point number.
8: The service will return either an 8-byte signed integer or an 8-byte IEEE floating-point number.

ValueDescriptor

Returned parameter

Type: Integer
Length: 4 bytes

A constant that indicates the format of the number being returned. Possible values include integer and floating point.

DiagArea

Returned parameter

Type: Character string
Length: 132 bytes

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'000Dyyyy' 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 HWTJGNUV 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 entryValueHandle parameter is not valid. Action: Check for a probable coding error. Only pass an entryValueHandle parameter that was returned by a prior z/OS JSON parser service call.
105 HWTJ_HANDLE_TYPE_ERROR	Meaning: Program error. The specified entryValueHandle does not represent an entry value with a JSON data type of HWTJ_NUMBER_TYPE. Action: Check for a probable coding error. Correct the mismatched handle and specify an entryValueHandle value that represents a number entry value handle.
801 HWTJ_JGNUV_VALBUFFADDR_INV	Meaning: Program error. The caller specified a value of zero as the address of the valueBufferAddr parameter. Action: Check for a probable coding error. Specify the actual address of the buffer where the returned converted binary representation of the JSON number is to be written. Note: Specifying a bad buffer address other than zero may result in the parser terminating with a `X'0C4'` system ABEND. See the description of the HWTJ_INACCESSIBLE_PARM return code for more information.
802 HWTJ_JGNUV_VALBUFFLEN_INV	Meaning: Program error. The caller specified an invalid value for the length of the output buffer. Action: Check for a probable coding error. Validate that the specified valueBufferLen value is one of the allowed values according to the description of the valueBufferLen parameter. Note: Specifying a bad buffer length other than zero may result in the parser terminating with a `X'0C4'` system ABEND. See the description of the HWTJ_INACCESSIBLE_PARM return code for more information.
803 HWTJ_JGNUV_NUM_OUT_OF_RANGE	Meaning: The number cannot be converted. The attempt to convert the number to a binary representation results in an overflow condition (positive or negative). Action: If a valueBufferLen of 4 was specified, consider increasing the valueBufferLen to 8 and retrying the service. If 8 was already specified, the number is too large for the HWTJGNUV service to convert. Consider issuing HWTJGVAL to obtain the character representation of the number.
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.