Syntax, linkage, and programming considerations

Table 1 lists the programming interface files provided by the z/OS JSON parser.

Table 2 lists specific calling formats for languages that can invoke the z/OS JSON parser callable services.

There are three ways for a compiled application to find the z/OS JSON parser callable services:

Linkage stub method

(Recommended) Use the linkable stub routine HWTJCSS from SYS1.CSSLIB to link edit your object code. If you attempt to run the parser on a previous release of z/OS that does not support the z/OS JSON parser, this method results in the service call receiving a return code of X'F03' (HWTJ_UNSUPPORTED_RELEASE).

Load method

Use the LOAD macro to find the address of the z/OS JSON parsing callable service at run time and then CALL the service. If you attempt to run the parser on a previous release of z/OS that does not support the z/OS JSON parser, this method results in the LOAD macro failing to find the requested service.

Direct linkage method

Code the linkage to the z/OS parser services directly. This can be done if the program first confirms that the level of z/OS contains the toolkit. The following example shows the assembler linkage:

L     R14,CVTCSRT-CVT(R14,0)     
L     R14,84(R14,0)              
L     R15,4*HWT_SERV_xxxxx(R14,0)
LR    R14,R0                     
BR    R15

In the example, xxxxx represents the last five letters of the service you want to call. This requires that the HWTJKASM assembler macro be included. If you attempt to run the parser on a previous release of z/OS that does not support the z/OS JSON parser, this method results in the application receiving an abend X'019'.

Callers must ensure that the proper linkage is made to the JSON parsing services. The supplied IDF files for the various high-level languages contain the necessary definitions that ensure that the parameter list passed to the JSON parser has the high-order bit turned on for the last parameter. For example, for C, the linkage must be specified as OS linkage, such as:

#pragma linkage(HWTJxxxx_CALLTYPE,OS)

For PL/I, the entry declaration should have the following options defined:

OPTIONS(LINKAGE(SYSTEM))

Callers must also use the following linkage conventions:

• Register 1 must contain the address of a parameter list that is a list of consecutive words, each containing the address of a parameter to be passed. The last word in this list must have a 1 in the high-order (sign) bit.
• Register 13 must contain the address of an 18-word save area.
• Register 14 must contain the return address.
• Register 15 must contain the entry point address of the service being called.
• If the caller is running in AR ASC mode, access registers 1, 13, 14, and 15 must all be set to zero.
• On return from the service, general and access registers 2 - 14 are restored (registers 0, 1 and 15 are not restored).

Codepage considerations

Input data into the JSON parser may either be in EBCDIC encoding (codepage 1047) or in UTF-8. Any JSON text received by the application in another encoding format must first be converted to one of these supported formats before it can be input to the parser instance via either parse (HWTJPARS) or create (HWTJCREN) service calls.

Recovery considerations

The z/OS JSON parser runs in the address space of the application. In addition, all the storage needed by the parser is obtained in the application’s address space. Because every application has its own programming environment, it is impossible for the parser to predict the recovery environment required by the application; therefore, the parser does not provide its own recovery. It is imperative that a robust application provide recovery to catch any abnormal ends to parser execution.

When the parser is attempting to access application-provided parameters and those parameters are either inaccessible, point to an inaccessible location, or specify a length that goes beyond the available storage that is obtained by the application, an ABEND occurs and the recovery of the application (if established) receives control. To allow for easier debugging of the problem, when the parser is about to access any application-specified values, the returnCode parameter is pre-filled with the HWTJ_INACCESSIBLE_PARM return code and the diagArea reasonDesc value is pre-filled with the specifics of which parameter the z/OS JSON parser is attempting to access. If the parser abnormally ends with an S0C4 ABEND code due to an inaccessible parameter, the recovery routine can consult the returnCode and diagArea values in the callers dynamic storage at the time of the ABEND and see which parameter the parser could not process.

Lastly, if the application catches any abnormal ends (abends) during the z/OS JSON parser execution, subsequent parser calls using the same parser handle can fail with an HWTJ_PARSERHANDLE_INUSE return code. See the action description for this return code for a list of options a program can take when encountering this condition.

The toolkit provides a REXX host command environment, HWTJSON, to allow REXX applications to parse and modify JSON strings, as well as search within a JSON string. REXX applications running in TSO/E, System REXX, z/OS UNIX, or ISV-provided REXX environments are supported.

• To initialize the HWTJSON host command environment in your REXX exec, it can be necessary to invoke the hwtcalls function at the beginning of your application: call hwtcalls on. After this invocation, both the ADDRESS HWTHTTP and ADDRESS HWTJSON host commands will direct API calls to the toolkit.
• To declare all toolkit constants in your REXX exec, use the HWTCONST service as documented in HWTCONST — Initialize predefined variables (REXX).
  Note: There is no REXX IDF (include file) provided by the toolkit.
• The toolkit services allocate task associated resources, which are released at task termination and the termination API calls.
• Handles are not shared among multiple tasks, which can restrict some reentrant REXX environments.
• JSON parser handles can be updated by any of the JSON parser services. The content of these variables should not be modified in any way by the application.
• Verify that all variables have proper content and are exposed if set outside of procedures.
• Variable names specified on toolkit REXX service calls are limited to 40 characters in length.
• REXX does not have unlimited variable content size. In general, a single variable cannot contain more than 16 MB of content. This limits the amount of data that can be sent and received in the JSON parser. If the data required is greater than 16 MB for any of these cases, consider to use one of the high-level languages, which are supported by the toolkit (C/C++, COBOL, PL/I or Assembler).
• The built-in REXX RC variable contains the return code from the REXX HWTJSON host command. This return code indicates the toolkit's acceptance of the supplied REXX HWTJSON host command. The return codes returned in the RC variable are generally unique to the REXX environment. In contrast, the JSON service return code, the variable supplied on the service call itself, is only completed if the RC variable has a value of HWTJ_OK (0) or HWT_REXXParmSyntaxError (1). Possible return codes returned by the toolkit in the RC variable are listed in Table 3.
• The DiagArea for each REXX service call is returned by using stem variables in the form: x.HWTJ_ReasonCode, and x.HWTJ_ReasonDesc where x is the name of the stem variable specified on the parameter list. If no DiagArea information is completed by the toolkit, the value of the DiagArea stem-variable on return is all blanks or nulls.

The z/OS JSON parser provides a sample program in many of the supported programming languages to aid in the creation of applications that use the parser functions. Each sample contains examples of how to use almost all of the JSON parser services available in the toolkit. The samples are shipped in SYS1.SAMPLIB. Table 4 lists the sample files for each programming language.