DFHSC2LS: XML schema to high-level language conversion
The DFHSC2LS cataloged procedure generates a high-level language data structure and an XML binding from an XML schema or WSDL document. Use DFHSC2LS when you want to create a CICS® program that can parse or create XML. This topic lists the job control statements, symbolic parameters, input parameters and their descriptions for DFHSC2LS.
Job control statements for DFHSC2LS
- JOB
- Starts the job.
- EXEC
- Specifies the procedure name (DFHSC2LS).
- 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 DFHSC2LS:
- JAVADIR = path
- Specifies the name of the Java™ directory that is used by DFHSC2LS. 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 PATHPREF parameter.
- TMPDIR = tmpdir
- Specifies the location of a directory in z/OS UNIX that DFHSC2LS 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 DFHSC2LS uses to construct the names of the temporary workspace files.
- The default value is SC2LS.
- 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.
- SERVICE = value
- Use this parameter only when directed to do so by IBM® support.
The temporary work space
- tmpdir / tmpprefix .in
- tmpdir / tmpprefix .out
- tmpdir / tmpprefix .err
- tmpdir is the value specified in the TMPDIR parameter.
- tmpprefix is the value specified in the TMPFILE parameter.
- /tmp/SC2LS.in
- /tmp/SC2LS.out
- /tmp/SC2LS.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 DFHSC2LS
.-DATA-SCREENING=ENABLED--. >>-+-------------+--+-------------------------+-----------------> '-CCSID=value-' '-DATA-SCREENING=DISABLED-' .-ELEMENTS=ALL---. >--+----------------+-------------------------------------------> '-ELEMENTS=value-' >--+-----------------------------------------+------------------> '-HTTPPROXY=-+-domain name-+-:port number-' '-IP address--' >--+--------------------------+--+--------------------------+---> '-HTTPPROXY-USERNAME=value-' '-HTTPPROXY-PASSWORD=value-' >----+-LANG=COBOL----------+----+--------------+----------------> +-LANG=PLI-ENTERPRISE-+ '-BUNDLE=value-' +-LANG=PLI-OTHER------+ +-LANG=C--------------+ '-LANG=CPP------------' >--LOGFILE=value------------------------------------------------> >--+-MAPPING-LEVEL=1.0----------------------------------------------------------+--> +-MAPPING-LEVEL=1.1----------------------------------------------------------+ +-MAPPING-LEVEL=1.2-| Advanced data mapping (mapping level 1.2 and higher) |-+ +-MAPPING-LEVEL=2.0-| Advanced data mapping (mapping level 1.2 and higher) |-+ +-MAPPING-LEVEL=2.1-| Advanced data mapping (mapping level 2.1 and higher) |-+ +-MAPPING-LEVEL=2.2-| Advanced data mapping (mapping level 2.1 and higher) |-+ +-MAPPING-LEVEL=3.0-| Advanced data mapping (mapping level 3.0 and higher) |-+ +-MAPPING-LEVEL=4.0-| Advanced data mapping (mapping level 4.0 and higher) |-+ '-MAPPING-LEVEL=4.1-| Advanced data mapping (mapping level 4.1 and higher) |-' >--+-----------------------------------------------+------------> | .-SAME-AS-MAPPING-LEVEL--. | '-MAPPING-OVERRIDES=-+------------------------+-' +-HYPHENS-AS-UNDERSCORES-+ +-NO-ARRAY-NAME-INDEXING-+ '-UNDERSCORES-AS-HYPHENS-' .-MINIMUM-RUNTIME-LEVEL=MINIMUM-. >--+-------------------------------+----------------------------> +-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-' >----PDSMEM=value----+-SCHEMA=value-+---------------------------> '-WSDL=value---' .-STRUCTURE=PDSMEM_value-. >--+------------------------+--+-------------+------------------> '-STRUCTURE=data---------' '-TYPES=value-' .-XMLCP=LOCAL--------. >--+--------------------+----XSDBIND=value----------------------> +-XMLCP=UTF-8--------+ '-XMLCP=EBCDIC-CP-US-' .-WIDE-COMP3=FULL-. >--+-----------------+----------------------------------------->< +-WIDE-COMP3=NO---+ '-WIDE-COMP3=YES--'
Advanced data mapping (mapping level 1.2 and higher) .-CHAR-VARYING-LIMIT=32767-. |--+-------------------+--+--------------------------+----------> +-CHAR-VARYING=NO---+ '-CHAR-VARYING-LIMIT=value-' +-CHAR-VARYING=NULL-+ '-CHAR-VARYING=YES--' .-CHAR-MULTIPLIER=1-----. >--+-----------------------+------------------------------------> '-CHAR-MULTIPLIER=value-' .-DEFAULT-CHAR-MAXLENGTH=255---. >--+------------------------------+-----------------------------> '-DEFAULT-CHAR-MAXLENGTH=value-' .-DEFAULT-FRACTION-DIGITS=3-----. >--+-------------------------------+----------------------------| '-DEFAULT-FRACTION-DIGITS=value-' Advanced data mapping (mapping level 2.1 and higher) .-INLINE-MAXOCCURS-LIMIT=1-----. |--+------------------------------+-----------------------------| '-INLINE-MAXOCCURS-LIMIT=value-' Advanced data mapping (mapping level 3.0) .-DATETIME=PACKED15-. .-DATA-TRUNCATION=DISABLED-. |--+-------------------+--+--------------------------+----------| '-DATETIME=STRING---' '-DATA-TRUNCATION=ENABLED--'
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:
is equivalent toXSDBIND=xsdbinddir* /app1XSDBIND=xsdbinddir/app1 - A # character in the first character position of the line is a comment character. The line 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
conversion services (see
z/OS Unicode Services User's Guide and Reference
). 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-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.
- 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 xsd:dateTime fields are mapped to
CICS
ABSTIME data format or to text:
- PACKED15
- xsd:dateTime fields are mapped to CICS ABSTIME format.
- STRING
- xsd:dateTime fields 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 XML schema document or WSDL 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 to 2 147 483 647.
- DEFAULT-FRACTION-DIGITS = 3 | value
- Specifies the default number of fraction digits to use on an XML 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 PL/I the valid range is 0-30.
- ELEMENTS = { ALL | value }
- Defines a list of global element local names to enable. The default value of ALL indicates that all global elements are enabled.
- HTTPPROXY = { domain name | IP address } : port number
- If your XML schema or WSDL document contains references to other
XML schema or WSDL files that
are located on the Internet, and the system on which you are running
DFHSC2LS uses a proxy server to
access the Internet, specify either the domain name or IP address and
the port number of the proxy
server. For example:
HTTPPROXY=proxy.example.com:8080In other cases, this parameter is not required.
- HTTPPROXY-USERNAME = value
- Specifies the HTTP proxy user name to be used with HTTPPROXY-PASSWORD if the system on which you are running DFHSC2LS uses an HTTP proxy server to access the Internet, and the HTTP proxy server uses basic authentication. You can use this parameter only when you also specify HTTPPROXY.
- HTTPPROXY-PASSWORD = value
- Specifies the HTTP proxy password to be used with HTTPPROXY-USERNAME if the system on which you are running DFHSC2LS uses an HTTP proxy server to access the Internet, and the HTTP proxy server uses basic authentication. You can use this parameter only when you also specify HTTPPROXY.
- INLINE-MAXOCCURS-LIMIT = { 1 | value }
- Specifies whether inline variable repeating content is used based
on the
maxOccurs
attribute of the XML attribute.
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 maxOccurs attribute is greater than the value of INLINE-MAXOCCURS-LIMIT , container based mapping is used; otherwise, inline mapping is used.
When deciding if you want variably repeating 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 on variably repeating content, see Variable arrays of elements.
- 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 DFHSC2LS writes its activity log and trace
information. DFHSC2LS 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 DFHSC2LS.
- 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; for
DFHSC2LS, you are recommended to use a mapping level of 3.0 or higher.
- 3.0
- The xsd:dateTime data type maps to the CICS ASKTIME format.
- 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.

- For more details of support at each mapping level, see Mapping levels for the CICS assistants.
- MAPPING-OVERRIDES
=
{
SAME-AS-MAPPING-LEVEL
|
HYPHENS-AS-UNDERSCORES
|
NO-ARRAY-NAME-INDEXING
|
UNDERSCORES-AS-HYPHENS
}
- Specifies whether the default mapping behavior is overridden for
the specified mapping level.
The default value is
SAME-AS-MAPPING-LEVEL.
- 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 WSDL
document to underscores, rather
than the character X, to improve the readability of the generated
PL/I language structures. For more
information, see
XML schema to PL/I mapping.

- NO-ARRAY-NAME-INDEXING
- For Enterprise PL/I only. Ensures that the field names within an array are unique only within the scope of the higher level structure.
- UNDERSCORES-AS-HYPHENS
- This option is enabled automatically at Mapping level 4.0.
- For COBOL only. Converts any underscores in the XML document to hyphens instead of the character X. This option improves 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 XML schema to COBOL mapping.
- MINIMUM-RUNTIME-LEVEL
=
{
MINIMUM
|
3.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 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 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 XML binding into a CICS region that has the same runtime environment as the region used to generate the XML binding.
- 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, DFHLS2SC issues message DFHPI9683W 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 generated high-level language.
- PDSMEM = value
- Specifies the 1-6 character prefix that DFHSC2LS uses to generate the name of the partitioned data set member that will contain the high-level language structures.
- DFHSC2LS generates a partitioned data set member for each operation. It generates the member name by appending a 2-digit number to the prefix.
- SCHEMA = value
- The fully qualified z/OS UNIX name of the file from which the XML schema is read. DFHSC2LS creates the file, but not the directory structure, if it does not already exist.
- You can use either an XML schema or a WSDL document as input to DFHSC2LS. You must specify either this parameter or the WSDL parameter, but not both, to indicate from where the input comes.
- 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.
- TYPES = value
- Defines a list of global type local names to enable. A value of ALL indicates that all global types are enabled. By default, global types are not enabled.
- 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. - WSDL = value
- The fully qualified z/OS UNIX name of the WSDL document.
- You can use either an XML schema or a WSDL document as input to DFHSC2LS. You must specify either this parameter or the SCHEMA parameter, but not both, to indicate from where the input comes.
- 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 XML binding. DFHSC2LS creates the file, but not the directory structure, if it does not already exist. The file extension is .xsdbind.
