DFHLS2JS: High-level language to JSON schema conversion for linkable interface
The DFHLS2JS cataloged procedure generates a JSON schema and a JSON binding file from a high-level language structure. Use DFHLS2JS when you want to create a CICS® program that can parse or create JSON. Descriptions of the job control statements, symbolic parameters, the input parameters for DFHLS2JS, and an example job that uses DFHLS2JS, are provided to help you use this procedure.
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
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/ giving 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 an optional prefix that extends the z/OS® UNIX directory path that is used on other parameters. The default is the empty string.
- 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 under which the job runs 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 z/OS UNIX file system. The value of this parameter is appended to /usr/lpp/cicsts/ giving 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
- tmpdir / tmpprefix .in
- tmpdir / tmpprefix .out
- tmpdir / tmpprefix .err
- tmpdir is the value that is specified in the TMPDIR parameter.
- tmpprefix is the value that is specified in the TMPFILE parameter.
- /tmp/LS2JS.in
- /tmp/LS2JS.out
- /tmp/LS2JS.err
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.
Input parameters for DFHLS2JS
The following syntax diagram shows the available input parameters:>>-+-------------+--+-+-LANG=COBOL----------+-+-----------------> '-CCSID=value-' | +-LANG=PLI-ENTERPRISE-+ | | '-LANG=PLI-OTHER------' | '-+-LANG=C---+------------' '-LANG=CPP-' >----LOGFILE=value----BUNDLE=value------------------------------> >--+-MAPPING-LEVEL=1.0-------------------------------------------------------------------------------------+--> +-MAPPING-LEVEL=1.1-------------------------------------------------------------------------------------+ | .-CHAR-VARYING=NO---. | +-+-MAPPING-LEVEL=1.2-+--+-------------------+----------------------------------------------------------+ | '-MAPPING-LEVEL=2.0-' '-CHAR-VARYING=NULL-' | | .-CHAR-VARYING=NO-------. | '-+-MAPPING-LEVEL=2.1------------------------------------------------------+--+-----------------------+-' +-MAPPING-LEVEL=2.2------------------------------------------------------+ +-CHAR-VARYING=NULL-----+ | .-DATETIME=UNUSED---. .-DATA-TRUNCATION=DISABLED-. | +-CHAR-VARYING=COLLAPSE-+ +-MAPPING-LEVEL=3.0--+-------------------+--+--------------------------+-+ '-CHAR-VARYING=BINARY---' | '-DATETIME=PACKED15-' '-DATA-TRUNCATION=ENABLED--' | | .-CHAR-OCCURS=STRING-. .-CHAR-USAGE=NATIONAL-. | '-+-MAPPING-LEVEL=4.0-+--+--------------------+--+---------------------+-' '-MAPPING-LEVEL=4.1-' '-CHAR-OCCURS=ARRAY--' '-CHAR-USAGE=DBCS-----' >----JSONTRANSFRM=value-----------------------------------------> .-JSON-SCHEMA-CODEPAGE=LOCAL--------. >--+-----------------------------------+------------------------> +-JSON-SCHEMA-CODEPAGE=UTF-8--------+ '-JSON-SCHEMA-CODEPAGE=EBCDIC-CP-US-' .-MINIMUM-RUNTIME-LEVEL=MINIMUM-. >----JSON-SCHEMA=value----+-------------------------------+-----> +-MINIMUM-RUNTIME-LEVEL=3.0-----+ +-MINIMUM-RUNTIME-LEVEL=4.0-----+ +-MINIMUM-RUNTIME-LEVEL=4.1-----+ '-MINIMUM-RUNTIME-LEVEL=CURRENT-' >--+-OVERWRITE-OUTPUT=NO--+--+-------------+--PDSLIB=value------> '-OVERWRITE-OUTPUT=YES-' '-PDSCP=value-' .-STRUCTURE=DFHDATA-. >----PDSMEM=value----+-------------------+----------------------> '-STRUCTURE=data----' .-TRUNCATE-NULL-ARRAYS=DISABLED-. >--+-------------------------------+----------------------------> '-TRUNCATE-NULL-ARRAYS=ENABLED--' .-TRUNCATE-NULL-ARRAY-VALUES=NULL--. >--+----------------------------------+-------------------------> +-TRUNCATE-NULL-ARRAY-VALUES=SPACE-+ '-TRUNCATE-NULL-ARRAY-VALUES=ZERO--' .-XMLCP=LOCAL--------. >--+--------------------+-------------------------------------->< +-XMLCP=UTF-8--------+ '-XMLCP=EBCDIC-CP-US-'
Parameter use
Parameters must conform to the following rules:- 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.
- A number sign (#) 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
- BUNDLE = value
- Specifies the path and name of the bundle directory on z/OS UNIX . If you specify this value, the JSON assistant generates a bundle that contains the JSON binding. The path information for this parameter overrides any path information for the JSONTRANSFRM parameter.
- You can optionally specify an archive file rather than a directory name. The JSON assistant supports .zip and .jar archives. However, you must uncompress the archive before you try to install the BUNDLE resource.
- 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
conversion services. If you do not specify this
parameter, the application data structure is encoded by using the CCSID
specified in the
system initialization parameter.
You can use this parameter with any mapping level.
- 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. This parameter
does not apply to Enterprise and Other PL/I language structures.
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.
- 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 schema. 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++.
- COLLAPSE
- Character fields are mapped to a JSON string. Trailing white space in this field is not included in the JSON schema. 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 greater.
- 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 UTF-16 encoded data.
- NATIONAL
- Data from PIC ( n ) fields is treated as DBCS encoded data.
- DATA-TRUNCATION = { DISABLED | ENABLED }
- Specifies if 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 JSON date-time properties in the high-level language
structure, including
CICS
ABSTIME values, are mapped as time stamps:
- PACKED15
- Any JSON date-time properties are mapped as time stamps.
- UNUSED
- Any JSON date-time properties are not mapped as time stamps. This mapping is the default.
- JSON-SCHEMA = value
-
The fully qualified z/OS UNIX name of the file into which the JSON schema is written.
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.

- JSONTRANSFRM = value
- This parameter is mandatory for LINKable mode, but invalid for request-response mode. It indicates the name that is used for the JSONTRANSFRM bundle resource in CICS.
- LANG = COBOL
- Specifies that the programming language of the high-level language structure is COBOL.
- LANG = PLI-ENTERPRISE
- Specifies that the programming language of the high-level language structure is Enterprise PL/I.
- LANG = PLI-OTHER
- Specifies that the programming language of the high-level language structure is a level of PL/I other than Enterprise PL/I.
- LANG = C
- Specifies that the programming language of the high-level language structure is C.
- LANG = CPP
- Specifies that the programming language of the high-level language structure is C++.
- LOGFILE = value
- The fully qualified
z/OS
UNIX
name of the file into which DFHLS2JS writes its
activity log and trace information. If it does not exist, DFHLS2JS creates
the file, but not
the directory structure.
You might be requested to use this parameter 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 }
- Specifies the level of mapping for the assistant to use when generating the JSON binding and language structures. You must use mapping level 3.0 or higher.
- For more information about mapping levels, see Mapping levels for the CICS JSON assistants .
- MINIMUM-RUNTIME-LEVEL = { MINIMUM | 3.0 | 4.0 | | 4.1 CURRENT }
- Specifies the minimum
CICS
runtime environment into
which the JSON binding can be deployed. If you select a level that does
not match the other
parameters that you specified, you receive an error message. The options
that you can select
are as follows:
- MINIMUM
- The lowest possible runtime level of CICS is allocated automatically based on the parameters that you specified.
- 3.0
- Specify runtime level 3.0 or above if you want to use the CICS JSON assistant and take advantage of advanced data mappings.
- 4.0
- The generated web service binding file deploys successfully into a CICS TS 5.2 or later region. 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
CICS TS 5.2
region that has APAR PI67641
applied, or into any
CICS TS 5.3
or later
region. With this runtime level, you can use a mapping level of 4.1 or
earlier for the MAPPING-LEVEL
parameter.

- CURRENT
- Use this runtime level to deploy the generated binding file into a CICS region that has the runtime environment that is set to the one used to generate the binding file.
- OVERWRITE-OUTPUT = { NO | YES }
- Controls whether existing CICS BUNDLEs on the file system can be overwritten.
-
- NO
- Any existing BUNDLE is not replaced. If an existing BUNDLE is found DFHLS2JS issues error message DFHPI9689E and terminates.
- YES
- Any existing BUNDLE is replaced. If an existing BUNDLE is found then message DFHPI9683W is issued to inform you that the file has been replaced.
- PDSCP = value
- Specifies the code page that is used in the partitioned data set members, where value is a CCSID number or a Java code page number. If you do not specify this parameter, the z/OS UNIX System Services code page is used. For example, you might specify PDSCP=037.
- PDSLIB = value
- Specifies the name of the partitioned data set that contains the
high-level language data
structures to be processed.
Restriction: The records in the partitioned data set must have a fixed length of 80 bytes.
- PDSMEM = value
- Specifies the name of the partitioned data set member that contains the high-level language structures that you want to process.
- STRUCTURE = { DFHDATA | data }
- The name of the top-level data structure in C and C++. The default is DFHDATA.
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
uninitialised 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
|
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, SPACE and ZERO values can
be specified in a comma
separated list, where NULL implies a null character (0x00), SPACE implies
an SBCS EBCDIC Space
(0x40), and 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, then
TRUNCATE-NULL-ARRAYS must be
enabled.
//LS2JS JOB '
accounting information
',
name,MSGCLASS=A
// SET QT=''''
//JAVAPROG EXEC DFHLS2JS,
// TMPFILE=&QT.&SYSUID.&QT
/INPUT.SYSUT1 DD *
PDSLIB=//CICSHLQ.SDFHSAMP
PDSMEM=CPYBK2
JSON-SCHEMA=example.json
LANG=COBOL
LOGFILE=/u/exampleapp/example.log
MAPPING-LEVEL=4.0
JSONTRANSFRM=EXAMPLE
BUNDLE=/u/exampleapp/bundles/exampleBundle
/*
