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
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 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 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
- 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/LS2SC.in
- /tmp/LS2SC.out
- /tmp/LS2SC.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 DFHLS2SC
.-DATA-SCREENING=ENABLED--. >>-+-------------+--+-------------------------+-----------------> '-CCSID=value-' '-DATA-SCREENING=DISABLED-' >--+-+-LANG=COBOL----------+-+----LOGFILE=value-----------------> | +-LANG=PLI-ENTERPRISE-+ | | '-LANG=PLI-OTHER------' | '-+-LANG=C---+------------' '-LANG=CPP-' >--+--------------+---------------------------------------------> '-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-----' .-MINIMUM-RUNTIME-LEVEL=MINIMUM-. >--+-------------------------------+--+-----------------+-------> +-MINIMUM-RUNTIME-LEVEL=3.0-----+ '-NAMESPACE=value-' +-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------SCHEMA=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--------. >--+--------------------+----XSDBIND=value--------------------->< +-XMLCP=UTF-8--------+ '-XMLCP=EBCDIC-CP-US-'
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=/path/xsdbinddir* /app1XSDBIND=/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 an xsd:string . Trailing white space in the field is not included in the XML 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 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 behavior 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.
- 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 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 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. 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.
- 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.
