DFHLS2SC: high-level language to XML schema conversion

The DFHLS2SC cataloged procedure generates an XML schema and an XML binding file from a high-level language structure. Use DFHLS2SC when you want to create a CICS® program that can parse or create XML. The job control statements for DFHLS2SC, its symbolic parameters, its input parameters and their descriptions are listed.

Job control statements for DFHLS2SC

JOB: Starts the job.
EXEC: Specifies the procedure name (DFHLS2SC).
INPUT.SYSUT1 DD: Specifies the input. The input parameters are usually specified in the input stream. However, you can define them in a data set or in a member of a partitioned data set.

Symbolic parameters

The following symbolic parameters are defined in DFHLS2SC:

JAVADIR=path: Specifies the name of the Java™ directory that is used by DFHLS2SC. 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 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 JAVADIR 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 DFHLS2SC uses as a temporary work space. 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 DFHLS2SC uses to construct the names of the temporary workspace files.; The default value is SC2WS.
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.; 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

DFHLS2SC creates the following three temporary files at run time:

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

where:

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

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

/tmp/LS2SC.in
/tmp/LS2SC.out
/tmp/LS2SC.err

Important: DFHLS2SC does not lock access to the z/OS UNIX files or the dataset members. Therefore, if two or more instances of DFHLS2SC run concurrently and use the same temporary workspace files, nothing prevents one job from overwriting the workspace files while another job is using them, leading to 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.

Input parameters for DFHLS2SC

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 to 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:
```
XSDBIND=/path/xsdbinddir*
/app1
```
is equivalent to
```
XSDBIND=/path/xsdbinddir/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

BUNDLE=value: Specifies the path and name of the bundle directory on z/OS UNIX. If you specify this value, the XML assistant generates a bundle containing the XSD binding. The path information on this parameter overrides any path information on the XSDBIND parameter.; You can optionally specify an archive file rather than a directory name. The XML assistant supports .zip and .jar archives. However, you must uncompress the archive before trying to install the BUNDLE resource.; If you do not specify this parameter, CICS places the XML schema and binding in the location specified on the XSDBIND 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 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 an xsd: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 an xsd:string and are processed as null-terminated strings. CICS adds a terminating null character when transforming from an XML 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 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 as an xsd:base64binary data type 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.

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 the COBOL language.

ARRAY: Character arrays are mapped to an XML array. This means that every character is mapped as an individual XML element. This is also the behaviour at mapping levels 3.0 and earlier.
STRING: Character arrays are mapped to an XML string. This means that the entire COBOL array is mapped as a single XML 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.

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={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.

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 DFHLS2SC writes its activity log and trace information. DFHLS2SC creates the file, but not the directory structure, if it does not already exist.

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

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 XML binding and language structures. You are recommended to use the most recent mapping level that is available. If you are creating an XML binding for an Atom feed, you must use a mapping level of 3.0.

For details of what is supported at each mapping level, see Mapping levels for the CICS assistants.

MINIMUM-RUNTIME-LEVEL={MINIMUM|3.0|4.0|4.1|CURRENT}

Specifies the minimum CICS runtime environment into which the XML binding can be deployed. If you select a level that does not match the other parameters that you have 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 have specified.
3.0: Specify runtime level 3.0 or above if you want to use the CICS XML 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 binding file into a CICS region that has the runtime environment set to the one used to generate the binding file.

NAMESPACE=value

Specifies the namespace for CICS to use in the generated XML schema. For Atom feeds, CICS provides this namespace in the Atom feed together with the Atom namespace.

If you do not specify this parameter, CICS generates a namespace automatically.

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 DFHLS2SC 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 to be processed.

SCHEMA=value

The fully qualified z/OS UNIX name of the file into which the XML schema is written. The XML schema conforms to the WSDL 2.0 specification. DFHLS2SC creates the file, but not the directory structure, if it does not already exist.

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.

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.

XMLCP={LOCAL|UTF-8|EBCDIC-CP-US}

Specifies the code page that is used to generate the XML binding.

LOCAL: This value is the default. It specifies that the XML is generated using the local code page and no encoding tag is generated in the XML schema.
UTF-8: Specifies that the XML is generated using the UTF-8 code page. An encoding tag is generated in the XML schema. If you specify this option, you must ensure that the encoding remains correct when copying the XML schema between different platforms.
EBCDIC-CP-US: Specifies that the XML is generated using the US EBCDIC code page. An encoding tag is generated in the XML schema.

XSDBIND=value

The fully qualified z/OS UNIX name of the XSD binding. DFHLS2SC creates the file, but not the directory structure, if it does not already exist. If the BUNDLE parameter is specified, exclude the path. The file extension is .xsdbind.