DFHLS2JS: High-level language to JSON schema conversion for request-response services

The DFHLS2JS procedure generates a JSON schema file from a high-level language data structure. You can use DFHLS2JS when you expose a CICS® application program as a service provider.

The DFHLS2JS JCL procedure is installed in the data set HLQ.XDFHINST, where HLQ is the high-level qualifier where CICS is installed.

Job control statements for DFHLS2JS

JOB: Starts the job.
EXEC: Specifies the procedure name (DFHLS2JS).
INPUT.SYSUT1 DD: Specifies the input. The input parameters are typically specified in the input stream. However, they can be defined in a data set or in a member of a partitioned data set.

Symbolic parameters

The following symbolic parameters are defined in DFHLS2JS:

JAVADIR = path: Specifies the name of the Java™ directory that is used by DFHLS2JS. The value of this parameter is appended to /usr/lpp/ to produce a complete path name of /usr/lpp/ path .; Typically, you do not specify this parameter. The default value is the value that was supplied to the CICS installation job (DFHISTAR) in the JAVADIR parameter.
PATHPREF = prefix: Specifies a prefix that extends the z/OS® UNIX directory path that is used on other parameters, or '' (empty string) if no prefix is used.; Typically, you do not specify this parameter. The default value is the value that was supplied to the CICS installation job (DFHISTAR) in the PATHPREF parameter.
SERVICE = value: Use this parameter only when directed to do so by IBM® Support.
TMPDIR = tmpdir: Specifies the location of a directory in z/OS UNIX that DFHLS2JS uses as a temporary workspace. The user ID used to run the job must have read and write permission to this directory.; The default value is /tmp.
TMPFILE = tmpprefix: Specifies a prefix that DFHLS2JS uses to construct the names of the temporary workspace files.; The default value is LS2JS.
USSDIR = path: Specifies the name of the CICS TS directory in the UNIX System Services file system. The value of this parameter is appended to /usr/lpp/cicsts/ to produce a complete path name of /usr/lpp/cicsts/ path . This must be specified as '.' (period) if the default is used.; Typically, you do not specify this parameter. The default value is the value that was supplied to the CICS installation job (DFHISTAR) in the USSDIR parameter.

The temporary workspace

DFHLS2JS creates the following three temporary files at run time:

tmpdir / tmpprefix .in
tmpdir / tmpprefix .out
tmpdir / tmpprefix .err

where:

tmpdir is the value that is specified in the TMPDIR parameter.
tmpprefix is the value that is specified in the TMPFILE parameter.

The default names for the files, when TMPDIR and TMPFILE are not specified, are as follows:

/tmp/LS2JS.in
/tmp/LS2JS.out
/tmp/LS2JS.err

Important: DFHLS2JS does not lock access to the z/OS UNIX files or the data set members. If two or more instances of DFHLS2JS run concurrently and use the same temporary workspace files, nothing prevents one job from overwriting the workspace files while another job is using them, which might cause unpredictable failures.

Therefore, you are advised to devise a naming convention, and operating procedures, that avoid this situation. For example, you can use the system symbolic parameter SYSUID to generate workspace file names that are unique to an individual user. These temporary files are deleted before the end of the job.

Important: The utility will only run under the default USS shell. If you have configured a different shell (such as the bash shell) to launch, based on your .profile, then the utility will fail to run without issuing any error messages. If you use a different shell you must alter the configuration of your .profile to use the default USS shell before running the utility.

Input parameters for DFHLS2JS

Mapping level 1.2 and higher

Mapping level 2.1 and higher

Mapping level 3.0 and higher

Mapping level 4.0 and higher

Mapping level 4.1 and higher

Parameter use

You can specify the input parameters in any order.
Each parameter must start on a new line.
A parameter, and its continuation character, if you use one, must not extend beyond column 72; columns 73 - 80 must contain blanks.
If a parameter is too long to fit on a single line, use an asterisk (*) character at the end of the line to indicate that the parameter continues on the next line. Everything, including spaces before the asterisk is considered part of the parameter. For example:
```
WSBIND=wsbinddir*
						/app1
```
is equivalent to
```
WSBIND=wsbinddir/app1
```
A # character in the first character position of the line is a comment character. The line is ignored.
A comma in the last character position of the line is an optional line separator, and is ignored.

Parameter descriptions

CCSID = value: Specifies the CCSID that is used at run time to encode character data in the application data structure. The value of this parameter overrides the value of the LOCALCCSID system initialization parameter. The value must be an EBCDIC CCSID that is supported by Java and z/OS Unicode Services User's Guide and Reference . If you do not specify this parameter, the application data structure is encoded by using the CCSID specified in the system initialization parameter.

CHAR-VARYING = { NO | NULL | COLLAPSE | BINARY }

Specifies how character fields in the language structure are mapped when the mapping level is 1.2 or higher. A character field in COBOL is a Picture clause of type X, for example PIC(X) 10 ; a character field in C/C++ is a character array. You can select these options:

NO: Character fields are mapped to a JSON string and are processed as fixed-length fields. The maximum length of the data is equal to the length of the field. NO is the default value for the CHAR-VARYING parameter for COBOL and PL/I at mapping levels 2.0 and earlier.; This value does not apply to Enterprise and Other PL/I language structures.
NULL: Character fields are mapped to a JSON string and are processed as null-terminated strings. CICS adds a terminating null character when transforming from a JSON message. The maximum length of the character string is calculated as one character less than the length indicated in the language structure. NULL is the default value for the CHAR-VARYING parameter for C/C++.; This value does not apply to Enterprise and Other PL/I language structures.
COLLAPSE: Character fields are mapped to a JSON string. Trailing and embedded white space in the field is not included in the JSON message; for example <space>AB<space><space><space>C<space> becomes AB<space>C. The inbound JSON message is parsed to remove all leading, trailing, and embedded white space. COLLAPSE is the default value for the CHAR-VARYING parameter for COBOL and PL/I at mapping level 2.1 onwards.
BINARY: Character fields are mapped to a JSON string containing base64 encoded data and are processed as fixed-length fields. The BINARY value on the CHAR-VARYING parameter is available only at mapping levels 2.1 and onwards.

For more information about handling variable-length values and white space, see Support for variable-length values and white space.

CHAR-OCCURS = { STRING | ARRAY }

Specifies how character arrays in the language structure are mapped when the mapping level is 4.0 or higher. For example, PIC X OCCURS 20 . This parameter is only for use by COBOL language.

ARRAY: Character arrays are mapped to a JSON array. This means that every character is mapped as an individual JSON element. This is also the behaviour at mapping levels 3.0 and earlier.
STRING: Character arrays are mapped to an JSON string. This means that the entire COBOL array is mapped as a single JSON element.

CHAR-USAGE = { NATIONAL | DBCS }

In COBOL, the national data type, PIC N , can be used for UTF-16 or DBCS data. This setting is controlled by the NSYMBOL compiler option. You must set the CHAR-USAGE parameter on the assistant to the same value as the NSYMBOL compiler option to ensure that the data is handled appropriately. This is typically set to CHAR-USAGE=NATIONAL when you use UTF-16.

DBCS: Data from PIC ( n ) fields is treated as DBCS encoded data.
NATIONAL: Data from PIC ( n ) fields is treated as UTF-16 encoded data.

CONTID = value

In a service provider, specifies the name of the container that holds the top-level data structure that is used to represent a JSON message.

The length of the container that CICS passes to the target application program is the greater of the lengths of the request container and the response container.

DATA-SCREENING = { ENABLED | DISABLED }

Specifies whether application supplied data is screened for errors.

ENABLED: Any application-supplied runtime data that is inconsistent with the language structure, is treated as an error, and message DFHPI1010 is issued. An error response is returned to the application.
DISABLED: Values in application-supplied runtime data that are inconsistent with the language structure are replaced by default values. For example, a zero replaces a bad value in a numeric field. Message DFHPI1010 is not issued and a normal response is returned to the application. This feature can be used to avoid INVALID_PACKED_DEC and INVALID_ZONED_DEC error responses that are generated from uninitialized output fields.

DATA-TRUNCATION = { DISABLED | ENABLED }

Specifies whether variable length data is tolerated in a fixed-length field structure:

DISABLED: If the data is less than the fixed length that CICS is expecting, CICS rejects the truncated data and issues an error message.
ENABLED: If the data is less than the fixed length that CICS is expecting, CICS tolerates the truncated data and processes the missing data as null values.

DATETIME = { UNUSED | PACKED15 }

Specifies if potential ABSTIME fields in the high-level language structure are mapped as timestamps:

PACKED15: Packed decimal fields of length 15 (8 bytes) are treated as CICS ABSTIME fields, and mapped as timestamps.
UNUSED: Packed decimal fields of length 15 (8 bytes) are not treated as timestamps.

You can set this parameter at a mapping level of 3.0.

JSON-SCHEMA-CODEPAGE = { LOCAL | UTF-8 | EBCDIC-CP-US }

Specifies the code page that is used to generate the JSON Schema documents.

LOCAL: Specifies that the JSON Schemas are generated using the default code page for the file system.
UTF-8: Specifies that the JSON Schemas are generated using the UTF-8 code page.
EBCDIC-CP-US: Specifies that the JSON Schemas are generated using the US EBCDIC code page.

JSON-SCHEMA-REQUEST = value: This is a mandatory parameter.; The value indicates the UNIX System Services location where the request JSON schema is stored.

JSON-SCHEMA-RESPONSE = value

This is a mandatory parameter.

The value indicates the UNIX System Services location where the response JSON schema is stored.

LANG = COBOL|PLI-ENTERPRISE|PLI-OTHER|C|CPP

Specifies the programming language of the high-level language structure:

COBOL: COBOL
PLI-ENTERPRISE: Enterprise PL/I
PLI-OTHER: A level of PL/I other than Enterprise PL/I
C: C
CPP: C++

LOGFILE = value

The fully qualified z/OS UNIX name of the file into which DFHLS2JS writes its activity log and trace information. DFHLS2JS creates the file, but not the directory structure, if it does not exist.

Typically, you do not use this file, but it might be requested by the IBM service organization if you encounter problems with DFHLS2JS.

MAPPING-LEVEL = { 1.0 | 1.1 | 1.2 | 2.0 | 2.1 | 2.2 | 3.0 | 4.0 | 4.1 | 4.2 | 4.3 }

Specifies the level of mapping that DFHLS2JS uses when you generate the web service binding file and JSON schema. You can select these options:

1.0: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
1.1: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
1.2: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
2.0: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
2.1: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
2.2: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.

3.0: Use this mapping level to generate JSON schema using the full set of options available.
4.0: Use this mapping level with a region at CICS TS 5.2, or later. At this mapping level you can use COBOL OCCURS DEPENDING ON fields and the CHAR-OCCURS parameter.
4.1: For truncatable array support, use this mapping level with a region at CICS TS 5.2 or later.
4.2: No significant changes. Use this mapping level with a region at CICS TS 5.4, or later.
4.3: No significant changes. Use this mapping level with a region at CICS TS 5.4,, or later.

For more information about mapping levels, see Mapping levels for the CICS JSON assistants .

MINIMUM-RUNTIME-LEVEL = { MINIMUM | 1.0 | 1.1 | 1.2 | 2.0 | 2.1 | 2.2 | 3.0 | 4.0 | 4.1 | 4.2 | 4.3 | CURRENT }

Specifies the minimum CICS runtime environment into which the web service binding file can be deployed. If you select a level that does not match the other parameters that you specified, you receive an error message. You can select these options:

MINIMUM: The lowest possible runtime level of CICS is allocated automatically given the parameters that you selected.
1.0: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
1.1: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
1.2: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
2.0: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
2.1: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
2.2: This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.
3.0: The generated web service binding file deploys into a region at CICS TS 4.1 or later.
Note: JSON support is only available from CICS TS 4.2 onwards.
4.0: The generated web service binding file deploys successfully into a region at CICS TS 5.2 or later. With this runtime level, you can use a mapping level of 4.0 or earlier for the MAPPING-LEVEL parameter. You can use any optional parameter at this level.
4.1: The generated web service binding file deploys successfully into a region at CICS TS 5.2, or later. With this runtime level, you can use a mapping level of 4.1 or earlier for the MAPPING-LEVEL parameter.
4.2: The generated web service binding file deploys successfully into a region at CICS TS 5.4, or later. With this runtime level, you can use a mapping level of 4.2 or earlier for the MAPPING-LEVEL parameter.
4.3: The generated web service binding file deploys successfully into a region at CICS TS 5.4, or later. With this runtime level, you can use a mapping level of 4.3 or earlier for the MAPPING-LEVEL parameter.
CURRENT: The generated web service binding file deploys successfully into a CICS region at the same runtime level as the one you are using to generate the web service binding file.

PDSLIB = value

Specifies the name of the partitioned data set that contains the high-level language data structures to be processed. The data set members that are used for the request and response are specified in the REQMEM and RESPMEM parameters.

Restriction: The records in the partitioned data set must have a fixed length of 80 bytes.

PDSCP = value

Specifies the code page that is used in the partitioned data set members that are specified in the REQMEM and RESPMEM parameters, where value is a CCSID number or a Java code page number. If this parameter is not specified, the z/OS UNIX System Services code page is used. For example, you might specify PDSCP = 037.

PGMINT = { CHANNEL | COMMAREA }

For a service provider, specifies how CICS passes data to the target application program:

CHANNEL

CICS uses a channel interface to pass data to the target application program.

In mapping levels earlier than 3.0, the channel can contain only one container, which is used for both input and output. Use the CONTID parameter to specify the name of the container. The default name is DFHWS-DATA.
At mapping level 3.0, the channel can contain multiple containers. Use the REQUEST-CHANNEL and RESPONSE-CHANNEL parameters. Do not specify PDSLIB , REQMEM , or RESPMEM.

COMMAREA

CICS uses a communication area to pass data to the target application program.

When the target application program has processed the request, it must use the same mechanism to return the response. If the request was received in a communication area, then the response must be returned in the communication area; if the request was received in a container, the response must be returned in a container. The length of the communication area or container that CICS passes to the target application program is the greater of the lengths of the request communication area or container and the response communication area or container.

PGMNAME = value

Specifies the name of the CICS PROGRAM resource for the target application program that is exposed as a web service. The CICS web service support links to this program.

REQMEM = value

Specifies the name of the partitioned data set member that contains the high-level language structure for the web service request. For a service provider, the web service request is the input to the application program.

REQUEST-CHANNEL = value

Specifies the name and location of a channel description document. The channel description describes the containers that the web service provider application can use in its interface when it receives a JSON message from a web service requester. The channel description is an XML document that must conform to the CICS supplied channel schema. For more information, see Creating a channel description document.

You can use this parameter at mapping level 3.0 only.

RESPMEM = value

Specifies the name of the partitioned data set member that contains the high-level language structure for the web service response. For a service provider, the web service response is the output from the application program.

RESPONSE-CHANNEL = value

Specifies the name and location of a channel description document. The channel description describes the containers that the web service provider application can use in its interface when it sends a JSON response message to a web service requester. The channel description is an XML document that must conform to the CICS supplied channel schema. For more information, see Creating a channel description document.

You can use this parameter at mapping level 3.0 only.

STRUCTURE = ( request , response )

For C and C++ only, specifies the names of the high-level structures that are contained in the partitioned data set members that are specified in the REQMEM and RESPMEM parameters:

request: Specifies the name of the high-level structure that contains the request when the REQMEM parameter is specified. The default value is DFHREQUEST.; The partitioned data set member must contain a high-level structure with the name that you specify or a structure named DFHREQUEST if you do not specify a name.
response: Specifies the name of the high-level structure that contains the response when the RESPMEM parameter is specified. The default value is DFHRESPONSE.; If you specify a value, the partitioned data set member must contain a high-level structure with the name that you specify or a structure named DFHRESPONSE if you do not specify a name.

SYNCONRETURN = { NO | YES }

Specifies whether the remote web service can issue a sync point.

NO: The remote web service cannot issue a sync point. This value is the default. If the remote web service issues a sync point, it fails with an ADPL abend.
YES: The remote web service can issue a sync point. If you select YES , the remote task is committed as a separate unit of work when control returns from the remote web service. If the remote web service updates a recoverable resource and a failure occurs after it returns, the update to that resource cannot be backed out.

TRANSACTION = name

In a service provider, this parameter specifies the one to four character name of an alias transaction that can start the pipeline. The value of this parameter is used to define the TRANSACTION attribute of the URIMAP resource when it is created automatically by using the PIPELINE scan command.

Acceptable characters: A-Z a-z 0-9 $ @ # _ < >

TRUNCATE-NULL-ARRAYS = { DISABLED | ENABLED }

Specifies how structured arrays are processed at mapping level 4.1 or higher. If enabled, CICS will attempt to recognize empty records within an array (see TRUNCATE-NULL-ARRAY-VALUES for more information about identifying empty records). If five consecutive empty array records are detected, the array is truncated at the first such record when generating XML/JSON. This truncation capability is only enabled for arrays with structured content, arrays of simple primitive fields are not subject to truncation. Truncation of arrays can result in a more concise representation of the data in JSON/XML, but is not without risk. If five consecutive data records are misidentified as uninitialized storage (perhaps because they legitimately contain low values), data loss can be experienced. If TRUNCATE-NULL-ARRAYS is enabled and TRUNCATE-NULL-ARRAY-VALUES is not set, then the default value for TRUNCATE-NULL-ARRAY-VALUES is used.

TRUNCATE-NULL-ARRAY-VALUES = { NULL | PACKEDZERO|SPACE | ZERO }

Specifies which values are treated as empty for TRUNCATE-NULL-ARRAYS processing at mapping level 4.1 or higher. By default, the null value (0x00, or low-values) is treated as empty. If all of the bytes of storage within a record of a structured array contain nulls, then the entire record is considered to be empty. One or more of the NULL, PACKEDZERO, SPACE and ZERO values can be specified in a comma separated list.

NULL: Implies a null character (0x00).
PACKEDZERO: Implies a positive signed packed decimal zero (0x0C), a negative signed packed decimal zero (0x0D), or an unsigned packed decimal zero (0x0F).
SPACE: Implies an SBCS EBCDIC space (0x40).
ZERO: Implies an unsigned zoned decimal zero (0xF0).

Any matching combination of the selected bytes within a structured array record will cause the entire record to be identified as empty.

If TRUNCATE-NULL-ARRAY-VALUES has a value defined, TRUNCATE-NULL-ARRAYS must be enabled.

URI = value

This parameter specifies the relative or absolute URI that a client uses to access the web service. CICS uses the value that is specified when it generates a URIMAP resource from the web service binding file that is created by DFHLS2JS. The parameter specifies the path component of the URI to which the URIMAP definition applies.

USERID = id

In a service provider, this parameter specifies a one to eight character user ID, which can be used by any web client. For an application-generated response or a web service, the alias transaction is attached under this user ID. The value of this parameter is used to define the USERID attribute of the URIMAP resource when it is created automatically by using the PIPELINE scan command.

Acceptable characters: A-Z a-z 0-9 $ @ #

WSBIND = value

The fully qualified z/OS UNIX name of the web service binding file. DFHLS2JS creates the file, but not the directory structure, if it does not exist. The file extension is .wsbind.

Other information

The user ID that DFHLS2JS uses to run must be configured to use UNIX System Services. The user ID must have read permission to the CICS z/OS UNIX file structure and PDS libraries and write permission to the directories specified on the LOGFILE , WSBIND , and JSON Schema parameters.
The user ID must have a sufficiently large storage allocation to run Java.
The JCL has a maximum parameter length of 100 characters. This parameter length can be increased by using the STDPARM statement, for more information, see z/OS UNIX System Services User's Guide.

Example


//LS2JS JOB '
accounting information
',
name,MSGCLASS=A
// SET QT=''''
//JAVAPROG EXEC DFHLS2JS,
// TMPFILE=&amp;QT.&SYSUID.&QT,
//INPUT.SYSUT1 DD *
PDSLIB=CICSHLQ.SDFHSAMP
REQMEM=DFH0XCP4
RESPMEM=DFH0XCP4
JSON-SCHEMA-REQUEST=/u/exampleapp/json/example_request.json
JSON-SCHEMA-RESPONSE=/u/exampleapp/json/example_response.json
LANG=COBOL
LOGFILE=/u/exampleapp/wsbind/example.log
MAPPING-LEVEL=4.0
CHAR-VARYING=COLLAPSE
PGMNAME=DFH0XCMN
URI=http://myserver.example.org:8080/exampleApp/example
PGMINT=COMMAREA
SYNCONRETURN=YES
WSBIND=/u/exampleapp/wsbind/example.wsbind
/*