JSON transformer linkable interface containers

The JSON transformer linkable interface is a CICS®-supplied program that can be called to perform data transformations to and from JSON. It can create JSON data from structured application data, or structured application data from JSON data.

You can use the linkable interface to transform JSON from any source, whether over a protocol such as IBM® MQ or from a JSON database, as compared to the JSON web services support, which is HTTP and provider-mode only. For more information about JSON, see Concepts of JSON web services.

To use the JSON transformer linkable interface the application program must LINK to the CICS supplied DFHJSON program, with a channel. Containers are used to pass input data to DFHJSON, and to receive output data from DFHJSON, the details of which are provided in subtopics.

CICS provides two mechanisms for transforming structured application data to and from JSON data, one using a JVM server, the other without. The JVM server approach experiences the advantages of the Java™ platform (such as eligibility for IBM z Systems® Application Assist Processor (zAAP) where available), the non Java approach avoids the need to configure a JVM server. The application selects which is used by using the DFHJSON_JVMSERVR container. The contents identify the JVM server in which to transform the data, the absence of this container indicates that the non Java transformation service is used.

To use this service, you must have a suitable JSONTRANSFRM bundle part that is installed in CICS. These are generated by using the JSON assistants. For more information, see Mapping and transforming application data and JSON.

DFHJSON-JSON container

When you transform application data to JSON: This container contains the JSON created by the transformer corresponding to the application data input.
When you transform JSON to application data: This container contains the JSON provided by the user application to be transformed.

DFHJSON-DATA container

DFHJSON-DATA is a container of DATATYPE(BIT).

When you transform application data to JSON: This container contains the application data that is provided by the user to be transformed into JSON.
When you transform JSON to application data: This container contains the application data that is created by the transformed data corresponding to the JSON input.

DFHJSON-TRANSFRM container

DFHJSON-TRANSFRM is a container of DATATYPE(CHAR). It contains the 16 character name of the JSONTRANSFRM bundle part whose mappings are applied to transform the data.

The JSONTRANSFRM is a bundle part. It is contained in a bundle that is generated by using the JSON assistant.

For more information about how to view bundle parts, see Bundle Parts view in the CICS Explorer product documentation.

Alternatively, you can use the INQUIRE BUNDLEPART command. See INQUIRE BUNDLEPART.

DFHJSON-JVMSERVR container

DFHJSON-JVMSERVR is a container of DATATYPE(CHAR). It contains the eight character name of the JVMSERVER in which the target program is to run.

If the container is not provided, or if the container is present but with a length of zero, then data transformation will be carried out within CICS rather than in a JVM server. If you want to carry out transformation in the CICS supplied Axis2 JVM server, then specify the value DFHAXIS in this container.

DFHJSON-ERROR container

DFHJSON-ERROR is a container of DATATYPE(BIT). Errors that are generated during validation or execution of DFHJSON are returned as a fullword binary value in the DFHJSON-ERROR container. The following errors can be returned by DFHJSON:

1: The DFHJSON-TRANSFRM container was not present.
2: The name of the JSONTRANSFRM provided in the DFHJSON-TRANSFRM container was longer than 16 characters.
3: A container had the wrong data type. DFHJSON-ERRORMSG contains the name of the incorrect container.
4: The name of the JVMSERVER provided in the DFHJSON-JVMSERVR container was longer than eight characters.
11: The JSONTRANSFRM named in DFHJSON-TRANSFRM container was not found.
12: The JSONTRANSFRM named in DFHJSON-TRANSFRM container was not in the ENABLED state.
13: Neither the DFHJSON-DATA or the DFHJSON-JSON container is present, one of these containers must be specified.
14: Both the DFHJSON-DATA and the DFHJSON-JSON containers were present, only one of these containers must be provided.
15: A data transformation error occurred. DFHJSON-ERRORMSG contains details of the error.
16: An error occurred while parsing JSON provided in the DFHJSON-JSON container. DFHJSON-ERRORMSG contains details of the error.
17: An error occurred in the Java portion of the transformer. Contact IBM support for assistance.
20: An unexpected error occurred. Contact IBM support for assistance.
51: The JVM server that is named in the DFHJSON-JVMSERVR container was not found.
52: The JVM server that is named in the DFHJSON-JVMSERVR container was not in the ENABLED state.

DFHJSON-ERRORMSG container

DFHJSON-ERRORMSG is a container of DATATYPE(CHAR). This container is created if an error occurs during processing. It contains a human-readable extra error message for example, the error message from the JSON parser. This message is only populated if extra details are needed.

For more information about error codes, see DFHJSON-ERROR container.