Syntax, linkage, and programming considerations
The z/OS® JSON parser is available to almost any program running in any address space. Almost all z/OS execution environments are supported as well as a wide variety of programming languages.
Programming interface files provided by the JSON parser
Programming language | Programming interface file |
---|---|
C / C++ | Include file HWTJIC provided in SYS1.SIEAHDRV.H |
COBOL | Copybook file HWTJICOB provided in SYS1.MACLIB |
PL/I | Include file HWTJIPLI provided in SYS1.MACLIB |
Assembler | Include file HWTJIASM provided in SYS1.MACLIB |
REXX | See HWTCONST — Initialize predefined variables (REXX) on how to access all the toolkit constants in REXX |
Calling formats
Programming language | Calling format |
---|---|
C / C++ | Parser_service_name (return_code,parm1,parm2,…) |
COBOL | CALL Parser-service-name
USING return_code,parm1,parm2,… |
PL/I | CALL
Parser_service_name (return_code,parm1,parm2,…) |
Assembler | CALL
Parser_service_name (return_code,parm1,parm2,…) ,VLIST |
REXX | ADDRESS HWTJSON
"Parser_service_name return_code parm1 parm2…" |
Linkage considerations
- 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:
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 abendL R14,CVTCSRT-CVT(R14,0) L R14,84(R14,0) L R15,4*HWT_SERV_xxxxx(R14,0) LR R14,R0 BR R15
X'019'
.
Linkage considerations for high-level language programming
OS
linkage, such as:
#pragma linkage(HWTJxxxx_CALLTYPE,OS)
OPTIONS(LINKAGE(SYSTEM))
Linkage considerations for assembler language programming
- 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).
General programming considerations
- 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.
REXX Programming Considerations
- 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 theADDRESS HWTHTTP
andADDRESS 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.
Table 3 lists the host command return codes for the REXX environment.
Host return code | Meaning and action |
---|---|
0 | Meaning: REXX toolkit host command successful. Action: Consult the toolkit return code on the service call to determine the final result of the request. |
1
HWT_REXXParmSyntaxError |
Meaning: REXX toolkit host command detects the parameter format is not in the proper
form to be accepted. Action: Check for a probable coding error.
|
2
HWT_REXXUnsupportedService |
Meaning: Program error. An unknown toolkit service name was specified on the toolkit
REXX host command. Action: Check for a probable coding error. Specify a valid toolkit service name. For example, HWTJPARS. |
3
HWT_REXXInvalidNumOfParms |
Meaning: Program error. The number of parameters specified on the toolkit REXX host
command for the service name specified does not match the number of parameters
expected. Action: Check for a probable coding error. See the REXX programming considerations of the toolkit service to see the exact calling specifications. Compare the toolkit REXX service call attempted with service call examples in the supplied toolkit REXX programming sample found in SYS1.SAMPLIB. |
4
HWT_REXXStemVarRequired |
Meaning: Program error. The toolkit REXX service specified on the toolkit REXX host
command is missing one or more required stem variables in the positional parameter
list. Action: Check for a probable coding error. See the REXX programming considerations of
the toolkit service to see the exact calling specifications. A stem variable parameter must specify
a period ( |
5
HWT_REXXParmNameTooLong |
Meaning: Program error. One or more variables specified on the toolkit REXX service
call on the toolkit REXX host command is greater than the toolkit maximum REXX variable length
(40). Action: Check for a probable coding error. Reduce the variable name lengths on the toolkit REXX service call to be 40 characters or less in length |
6
HWT_REXXInvalidHostEnv |
Meaning: System error. The toolkit detected 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. |
7
HWT_REXXNoStorageForVar |
Meaning: System error. Insufficient storage is detected by a SET request from the REXX
variable access routine (IRXEXCOM). The system rejects the service call. Action: Ensure that there is sufficient storage available for the toolkit to set REXX variables. If the problem persists, search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center. |
8
HWT_REXXirxexcom1 |
Meaning: System error. The REXX variable access routine (IRXEXCOM) used by the toolkit
detected an invalid entry condition. This error can be caused by invoking the toolkit REXX host
command from a non-REXX application. Action: Ensure to invoke the toolkit REXX host command from a valid REXX exec. If the problem persists, search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center. |
9
HWT_REXXirxexcom28 |
Meaning: System error. The REXX variable access routine (IRXEXCOM) detected a language
processor environment is missing. This error can be caused by invoking the toolkit from an invalid
REXX environment. Action: Ensure that REXX applications invoke the specified toolkit service in a proper REXX environment. TSO/E, System REXX, z/OS UNIX, or ISV-provided REXX environments are supported. If the problem persists, search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center. |
11
HWT_REXXNoStorage |
Meaning: System error. The toolkit could not obtain sufficient storage to satisfy the
request. Action: Ensure there is sufficient memory available for REXX command processing. If the problem persists, search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center. |
13
HWT_REXXInvalidVariable |
Meaning: Program error. The toolkit detected one of the variables passed in the
parameter list is an invalid REXX variable name. Action: Check for a probable coding error. Verify that all variables passed in the parameter list for the specified service have valid names. See the REXX programming considerations and parameters sections for reference. |
14
HWT_REXXDataTooLongForVar |
Meaning: Program error. The REXX variable cannot contain more than 16 megabytes of
data. Action: Check for a possible coding error. If the application requires more than 16 megabytes of data, consider using another supported language. |
32
HWT_REXXUnexpectedError |
Meaning: System error. An unexpected error is detected. The system rejects the service
call. Action: A symptom record has been written to LOGREC to record the problem. Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center. |
z/OS JSON parser programming examples
Programming language | Name of sample in SYS1.SAMPLIB |
---|---|
C / C++ | HWTJXC1, HWTJXC2 |
COBOL | HWTJXCB1, HWTJXCB2 |
PL/I | HWTJXPI1 |
REXX | HWTJXRX1, HWTJXRX2, HWTJXRX3 |