DFHJS2LS: JSON schema to high-level language conversion for linkable interface
The DFHJS2LS cataloged procedure generates a high-level language data structure and a JSON binding from a JSON schema. Use DFHJS2LS when you want to create a CICS® program that can parse or create JSON. The job control statements for DFHJS2LS, its symbolic parameters, its input parameters, and their descriptions are listed.
The DFHJS2LS JCL procedure is installed in the dataset HLQ.XDFHINST, where HLQ is the high-level qualifier where CICS is installed.
- DFHLS2JS: High-level language to JSON schema conversion for linkable interface
- DFHJS2LS: JSON schema to high-level language conversion for linkable interface
- DFHLS2JS: High-level language to JSON schema conversion for request-response services
- DFHJS2LS: JSON schema to high-level language conversion for request-response services
- DFHJS2LS: JSON schema to high-level language conversion for RESTful services
Job control statements for DFHJS2LS
- JOB
- Starts the job.
- EXEC
- Specifies the procedure name (DFHJS2LS).
- INPUT.SYSUT1 DD
- Specifies the input. The input parameters are specified in the input stream. However, you can also define them in a data set or in a member of a partitioned data set.
Symbolic parameters
The following symbolic parameters are defined in DFHJS2LS:- JAVADIR=path
- Specifies the name of the Java™ directory
that is used by DFHJS2LS. The value of this parameter is appended
to
/usr/lpp/
giving a complete path name of/usr/lpp/path
. - 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.
- 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 DFHJS2LS uses as a temporary workspace. The user ID under which the job runs must have read and write permission to this directory.
- TMPFILE=tmpprefix
- Specifies a prefix that DFHJS2LS uses to construct the names of the temporary workspace files.
- 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.
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/JS2LS.in
/tmp/JS2LS.out
/tmp/JS2LS.err
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.
Input parameters for DFHJS2LS
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.
- 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
- BUNDLE=value
- Specifies the path and name of the bundle directory on z/OS UNIX. If you specify this value, the JSON assistant generates the JSON binding in the bundle directory and creates a bundle manifest for you. The path information for this parameter overrides any path information for the JSONTRANSFRM parameter.
- 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-MULTIPLIER={1|value}
- Specifies the number of bytes to allow for each character when
the mapping level is 1.2 or later. The value of
this parameter can be a positive integer in the range of 1 - 2,147,483,647.
All nonnumeric character-based mappings, are subject to this multiplier.
Binary, numeric, zoned, and packed decimal fields are not subject
to this multiplier.
This parameter can be useful if, for example, you are planning to use DBCS characters where you might opt for a multiplier of 3 to allow space for potential shift-out and shift-in characters around every double-byte character at run time.
When you set CCSID=1200 (indicating UTF-16), the only valid values for CHAR-MULTIPLIER are 2 or 4. When you use UTF-16, the default value is 2. Use CHAR-MULTIPLIER=2 when you expect application data to contain characters that require 1 UTF-16 encoding unit. Use CHAR-MULTIPLIER=4 when you expect application data to contain characters that require 2 UTF-16 encoding units.Note: Setting CHAR-MULTIPLIER to 1 does not preclude the use of DBCS characters, and setting it to 2 does not preclude the use of UTF-16 surrogate pairs. However, if wide characters are routinely used then some valid values will not fit into the allocated field. If a larger CHAR-MULTIPLIER value is used, it can be possible to store more characters in the allocated field than are valid in the XML. Care must be taken to conform to the appropriate range restrictions. - CHAR-VARYING={NO|NULL|YES}
- Specifies how variable-length character data is mapped when the
mapping level is 1.2 or higher. Variable-length binary data types
are always mapped to either a container or a varying structure. If
you do not specify this parameter, the default mapping depends on
the language specified. You can select these options:
- NO
- Variable-length character data is mapped as fixed-length strings.
- NULL
- Variable-length character data is mapped to null-terminated strings.
- YES
- Variable-length character data is mapped to a CHAR VARYING data type in PL/I. In the COBOL, C, and C++ languages, variable-length character data is mapped to an equivalent representation that consists of two related elements: the data-length and the data.
- CHAR-VARYING-LIMIT={32767|value}
- Specifies the maximum size of binary data and variable-length character data that is mapped to the language structure when the mapping level is 1.2 or higher. If the character or binary data is larger than the value specified in this parameter, it is mapped to a container and the container name is used in the generated language structure. The value can range from 0 to the default 32 767 bytes.
- CHAR-WHITESPACE=COLLAPSE|REPLACE|PRESERVE
-
Specifies how white space in values of type string will be handled by CICS.
- COLLAPSE
- Leading, trailing, and embedded white space is removed and all tabs, new lines, and consecutive spaces are replaced with single space characters.
- REPLACE
- Any tabs or new lines are replaced with the appropriate number of spaces.
- PRESERVE
- Retains any white space in the data value.
If the CHAR-WHITESPACE parameter is not set, white space will be collapsed.Note: This parameter does not apply to fields with a format of date-time, uri, base64Binary or hexBinary, where white space is always collapsed. - 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
- Data 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 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={PACKED15|STRING}
- Specifies that JSON date-time properties are mapped to CICS ABSTIME data format or to
text:
- PACKED15
- JSON date-time properties fields are mapped to CICS ABSTIME format.
- STRING
- JSON date-time properties are mapped to text. This mapping is the same as all previous mappings levels.
- DEFAULT-CHAR-MAXLENGTH={255|value}
- Specifies the default array length of character data in characters for mappings where no length is implied in the JSON schema document, when the mapping level is 1.2 or later. The value of this parameter can be a positive integer in the range of 1 to 2 147 483 647.
- DEFAULT-FRACTION-DIGITS = { 3 | value }
- Specifies the default number of fraction digits to use on a JSON decimal schema type. The default is 3. For COBOL, the valid range is 0-17, or 0-30 if parameter WIDE-COMP3 is being used. For C or PLI, the valid range is 0-30.
- INLINE-MAXOCCURS-LIMIT={1|value}
- Specifies whether inline variable repeating content is used based
on the
maxItems
attribute of the JSON schema keywords.The INLINE-MAXOCCURS-LIMIT parameter is available only at mapping level 2.1 onwards. The value of INLINE-MAXOCCURS-LIMIT can be a positive integer in the range of 0 to 32 767. A value of 0 indicates that inline mapping is not used. A value of 1 ensures that optional elements are mapped inline. If the value of the
maxItems
attribute is greater than the value of INLINE-MAXOCCURS-LIMIT, container-based mapping is used; otherwise, inline mapping is used.If you decide that you want to variably repeat lists to be mapped inline, consider the length of a single item of recurring data. If you have few instances of long length, container-based mapping is preferable; if you have many instances of short length, inline mapping is likely to be preferable.
For more information about variably repeating content, see Variable arrays of elements in DFHJS2LS.
- JSONTRANSFRM=value
- This parameter is mandatory for LINKable mode, but invalid for request-response and RESTful modes. It indicates the name that is used for the JSONTRANSFRM bundle-resource in CICS.
- JSON-SCHEMA=value
- The fully qualified z/OS UNIX name of the file from which the JSON schema is read. If it does not already exist, DFHJS2LS creates the file, but not the directory structure.
- 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
DFHJS2LS writes its activity log and trace information. If it does
not already exist, DFHJS2LS creates the file, but not the directory
structure.
Typically you do not use this file, but it might be requested by the IBM service organization if you encounter problems with DFHJS2LS.
- 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 the most recent
mapping level that is available; for DFHJS2LS, you must use a mapping
level of 3.0 or higher.
- 3.0
- This is the minimum mapping level you can use with DFHJS2LS.
- 4.0
- Use this mapping level with a CICS TS 5.2 region when you want to use UTF-16.
- 4.1
- For truncatable array support, use this mapping level with a CICS TS 5.2 region that has APAR PI67641 applied, or any CICS TS 5.3 or later region.
- MAPPING-OVERRIDES={SAME-AS-MAPPING-LEVEL|INTEGER-AS-PIC9|LESS-DUP-NAMES|UNDERSCORES-AS-HYPHENS}
- Specifies whether the default behavior is overridden for the specified
mapping level when generating language structures.
- SAME-AS-MAPPING-LEVEL
- This parameter generates language structures in the same style as the mapping level. This is the default.
- INTEGER-AS-PIC9
- For COBOL and DFHJS2LS only. This parameter generates language structures which contain integer values from the JSON schema as numerals rather than alphanumeric characters.
- LESS-DUP-NAMES
- This parameter generates non-structural structure field names
with
_value
at the end of the name to enable direct referencing to the field. For example, in the following PLI language structure, when MAPPING-OVERRIDES=LESS-DUP-NAMES is specified, level 12 field streetName is suffixed with_value
:
The resulting structure is as follows:09 streetName, 12 streetName CHAR(255) VARYING UNALIGNED, 12 filler BIT (7), 12 attr_nil_streetName_value BIT (1),
09 streetName, 12 streetName_value CHAR(255) VARYING UNALIGNED, 12 filler BIT (7), 12 attr_nil_streetName_value BIT (1),
- UNDERSCORES-AS-HYPHENS
- For COBOL only. This parameter converts any underscores in the JSON schema to hyphens, rather than the character X, to improve the readability of the generated COBOL language structures. If any field name clashes occur, the fields are numbered to ensure they are unique. For more information, see JSON schema to COBOL mapping.
- MINIMUM-RUNTIME-LEVEL={MINIMUM|3.0|4.0||4.1CURRENT}
- 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 higher 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 V5.2 region 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 CICS V5.2 region that has APAR PI67641 applied, or into any CICS V5.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 JSON binding into a CICS region that has the same runtime environment as the region used to generate the JSON binding.
- OVERWRITE-OUTPUT={NO|YES}
- Controls whether existing CICS BUNDLEs on the file system can be overwritten.
- 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 generated high-level language.
- PDSMEM=value
- Specifies the 1-6 character prefix that DFHJS2LS uses to generate the name of the partitioned data set member that will contain the high-level language structures.
- STRUCTURE={PDSMEM_value|data}
- The name of the top-level data structure in C and C++. The default value is the value of the PDSMEM parameter.
- WIDE-COMP3={NO|YES}
- For COBOL only. Controls the maximum size of the packed decimal
variable length in the COBOL language structure.
- NO
- DFHJS2LS limits the packed decimal variable length to 18 when generating the COBOL language structure type COMP-3. If the packed decimal size is greater than 18, message DFHPI9022W is issued to indicate that the specified type is being restricted to a total of 18 digits.
- YES
- DFHJS2LS supports the maximum size of 31 when generating the COBOL language structure type COMP-3.
//JS2LS JOB 'accounting information',name,MSGCLASS=A
// SET QT=''''
//JAVAPROG EXEC DFHJS2LS,
// 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.1
CHAR-VARYING=NULL
JSONTRANSFRM=EXAMPLE
BUNDLE=/u/exampleapp/bundles/exampleBundle
/*