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
. - PATHPREF = prefix
- Specifies an optional prefix that extends the z/OS® UNIX directory path 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 DFHLS2SC uses as a temporary work space. The user ID under which the job runs must have read and write permission to this directory.
- TMPFILE = tmpprefix
- Specifies a prefix that DFHLS2SC uses to construct the names of the temporary workspace files.
- 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
.
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
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* /app1
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.
- 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>
becomesAB<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 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 toCHAR-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
- 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 whether 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 | 4.2|4.3 }
- 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.
- MINIMUM-RUNTIME-LEVEL = { MINIMUM | 3.0 | 4.0 | 4.1 | 4.2 | 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.
- 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 region at CICS TS 5.2 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 region at CICS TS 5.2 with APAR PI67641, or later. With this runtime level, you can use a mapping level of 4.1 or earlier for the MAPPING-LEVEL parameter.
- 4.2
- The generated web service binding file deploys successfully into a region at CICS TS V5.4 with APAR PI86039, or later. With this runtime level, you can use a mapping level of 4.2 or earlier for the MAPPING-LEVEL parameter.
- 4.3
- The generated web service binding file deploys successfully into a region at CICS TS 5.4 with APAR PI88519, or later. With this runtime level, you can use a mapping level of 4.3 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.
- 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.
- 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
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 | PACKEDZERO|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, PACKEDZERO, SPACE and ZERO values can be specified
in a comma separated list.
- NULL
- Implies a null character (0x00).
- PACKEDZERO
- Implies a positive signed packed decimal zero (0x0C), a negative signed packed decimal zero (0x0D), or an unsigned packed decimal zero (0x0F).
- SPACE
- Implies an SBCS EBCDIC space (0x40).
- 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, 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.