DFHJS2LS: JSON schema to high-level language conversion for request-response 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 usually 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 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/ 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 DFHJS2LS 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 DFHJS2LS uses to construct the names of the temporary workspace files.

The default value is JS2LS.

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 work space

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

Advanced data mapping (mapping level 1.2 and higher)

Advanced data mapping (mapping level 2.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-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 comprises two related elements: 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.

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

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 how JSON date-time elements are mapped to the language structure.

PACKED15

The default is that any JSON date-time element is processed as a timestamp and is mapped to CICS ABSTIME format.

STRING

The JSON date-time element is processed as text.

DEFAULT-CHAR-MAXLENGTH={255|value}

Specifies the default array length of character data in characters for mappings where no length is implied in the web service description document, when the mapping level is 1.2 or higher. The value of this parameter can be a positive integer in the range of 1 - 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 JSON schema keyword. Variably repeating content that is mapped inline is placed in the current container with the rest of the generated language structure. The variably repeating content is stored in two parts, as a counter that stores the number of occurrences of the data and as an array that stores each occurrence of the data. The alternative mapping for variably repeating content is container-based mapping, which stores the number of occurrences of the data and the name of the container where the data is placed. Storing the data in a separate container has performance implications that might make inline mapping preferable.

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 - 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 maxOccurs attribute is greater than the value of INLINE-MAXOCCURS-LIMIT, container-based mapping is used; otherwise inline mapping is used.

When deciding whether you want variably repeating lists to be mapped inline, consider the length of a single item of recurring data. If few instances of long length occur, container-based mapping is preferable; if many instances of short length occur, inline mapping is preferable.

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

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. DFHJS2LS 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 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 that DFHJS2LS uses when generating the web service binding file and language structure. 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 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 V5.2 region that has APAR PI67641 applied, or any CICS TS V5.3 or later region.

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

MAPPING-OVERRIDES={SAME-AS-MAPPING-LEVEL|HYPHENS-AS-UNDERSCORES|INTEGER-AS-PIC9|LESS-DUP-NAMES|UNDERSCORES-AS-HYPHENS|NO-ARRAY-NAME-INDEXING}

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.

HYPHENS-AS-UNDERSCORES

For PL/I only. This parameter converts any hyphens in the JSON schema to underscores rather than the character X, to improve the readability of the generated PL/I language structures. For more information, see JSON schema to PL/I mapping.

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:

09 streetName,                                                                                                             
    12 streetName                     CHAR(255) VARYING
   UNALIGNED,                                                                                                              
    12 filler                         BIT (7),                                                                             
    12 attr_nil_streetName_value      BIT (1),

The resulting structure is as follows:

09 streetName,                                                                                                             
    12 streetName_value               CHAR(255) VARYING
   UNALIGNED,                                                                                                              
    12 filler                         BIT (7),                                                                             
    12 attr_nil_streetName_value      BIT (1),

UNDERSCORES-AS-HYPHENS

This option is enabled automatically at Mapping level 4.0.

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.

NO-ARRAY-NAME-INDEXING

For COBOL and Enterprise PL/I only. Ensures that the field names within an array are unique only within the scope of the higher level structure.

MINIMUM-RUNTIME-LEVEL={MINIMUM|1.0|1.1|1.2|2.0|2.1|2.2|3.0|4.0|4.1|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 CICS TS 4.1 region 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 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 TS V5.2 region that has APAR PI67641 applied, or into any CICS TS 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

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.

NAME-TRUNCATION={LEFT|RIGHT}

Specifies whether JSON names are truncated from the left or the right. The CICS web services assistant truncates JSON names to the appropriate length for the high-level language specified; by default names are truncated from the right.

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.

PDSLIB=value

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

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.

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 a CICS PROGRAM resource.

When DFHJS2LS is used to generate a web service binding file that is used in a service provider, you must supply this parameter. It specifies the resource name of the application program that is exposed as a web service.

When DFHJS2LS is used to generate a web service binding file that is used in a service requester, omit this parameter.

REQMEM=value

Specifies a one to six character prefix that DFHJS2LS uses to generate the names of the partitioned data set members that contain the high-level language structures for the web service request, which is the input data to the application program.

DFHJS2LS generates the names of the partitioned data set members by appending a number to the prefix, with a maximum member name length of 8 characters.

RESPMEM=value

Specifies a one to six character prefix that DFHJS2LS uses to generate the names of the partitioned data set members that contain the high-level language structures for the web service response, which is the output data from the application program.

DFHJS2LS generates the names of the partitioned data set members by appending a number to the prefix, with a maximum member name length of 8 characters.

STRUCTURE=(request,response)

For C and C++ only, specifies how the names of the request and response structures are generated.

The generated request and response structures are given names of request01 and response01.

If one or both names are omitted, the structures have the same name as the partitioned data set member names generated from the REQMEM and RESPMEM parameters that you specify.

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 $ @ # _ < >

URI=value

In a service provider, this parameter specifies the relative 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 DFHJS2LS. 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 $ @ #

WIDE-COMP3={FULL|NO|YES}

Controls the maximum size of the packed decimal variable length in the generated COBOL or PL/I language structure.

FULL

For COBOL and PL/I. DFHJS2LS generates a packed decimal field that is large enough to hold all valid values. The maximum size is 31 digits. This is the default.

NO

For COBOL only. 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

For COBOL only. DFHJS2LS supports the maximum size of 31 when generating the COBOL language structure type COMP-3.

Note: The NO and YES options generate fields that are unable to represent all valid values; the FULL option avoids this problem. However, the FULL option does allow some invalid values to be represented in the packed decimal field. For example, if a schema indicates that there are a maximum of five digits and a maximum of two fractional digits, the FULL option will generate a packed decimal field that allows for seven digits, and this allows space for valid values such as 25000 and 999.99, but also provides space for some invalid values such as 9999.99. When you use the FULL option, take care not to generate invalid values in application data.

WSBIND=value

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

Other information

• The user ID under which DFHJS2LS runs 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 WSDL 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 can be increased by using the STDPARM statement, for more information, see z/OS UNIX System Services User Guide.