Support for variable-length values and white space
You can customize the way in which variable-length values and white space are handled by using settings on the CICS® assistants and by adding facets directly into the XML schema.
Typically, the CICS XML assistant and the CICS Web services assistant map data strings to fixed-length character arrays; these arrays require padding with spaces or nulls. Mapping variable-length values to fixed-length data arrays can be inefficient and waste storage. If the length of your data is variable, you are recommended to customize the way these mappings are handled.
If you are converting from
a language structure to an XML schema or WSDL document, you are recommended
to specify the whiteSpace
and maxLength
facets
in your XML schema and to set the CHAR-VARYING-LIMIT parameter
on the assistants.
If you are converting from an XML schema or WSDL document to a language structure, you are recommended to set an appropriate value for the CHAR-VARYING parameter on the assistants.
Mapping variable-length values from XML to language structures
Use facets in the XML schema or specify certain parameters on the CICS assistants to customize the way in which mappings between your XML schema or WSDL document and the language structure are handled.
length
, maxLength
,
and minLength
) and the whiteSpace
facet
to customize how variable-length data in your XML is handled.length
- Used to specify that the data is of fixed length.
maxLength
- Used to specify the maximum length for the data type. If this value is not set for a string-based data type, the maximum length is unbounded.
minLength
- Used to specify the minimum length for the data type. If this value is not set for a string-based data type, the minimum length is 0.
whiteSpace
- Used to specify how white space around a data value is handled.
White space includes spaces, tabs, and new lines. The
whiteSpace
facet can be set topreserve
,replace
, orcollapse
:- A value of
preserve
maintains any white space in the data value. - A value of
replace
means that any tabs or new lines are replaced with the appropriate number of spaces. - A value of
collapse
means that leading, trailing, and embedded white space is removed and that all tabs, new lines, and consecutive spaces are replaced with single space characters.
- A value of
- DEFAULT-CHAR-MAXLENGTH
- Specifies the default array length of character data in characters
for mappings where no length is implied in the XML schema or WSDL
document. The value of this parameter can be a positive integer in
the range of 1 - 2 147 483 647.
However, you are recommended to specify the maximum character length that you want DFHSC2LS or DFHWS2LS to use directly in your XML schema or WSDL document with the
maxLength
facet. Specifying the maximum length directly in the XML schema or WSDL document avoids problems associated with having one global default applied to all string-based data types. - CHAR-VARYING-LIMIT
- Specifies the maximum size of variable-length character data that is mapped to the language structure. If the character 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-VARYING
- Specifies how variable-length character data is mapped. If you
do not specify this parameter, the default mapping depends on the
language specified. You can select these options:
- CHAR-VARYING=NO specifies that variable-length character data is mapped as fixed-length strings.
- CHAR-VARYING=NULL specifies that variable-length character data is mapped to null-terminated strings.
- CHAR-VARYING=YES specifies that 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.
Mapping variable-length values from language structures to XML
You can customize the way in which mappings between your language structure and the XML schema, or WSDL document are handled. Set the CHAR-VARYING parameter on DFHLS2SC or DFHLS2WS,to COLLAPSE or NULL to change the way that character arrays are generated.
Setting the CHAR-VARYING=NULL option tells CICS to add a null character at the end of each character array when generating XML.
Setting the CHAR-VARYING=COLLAPSE option tells CICS to automatically remove any trailing spaces from the end of character arrays when generating XML. This option is available only at mapping level 2.1 or higher and CHAR-VARYING=COLLAPSE is the default value at mapping level 2.1 or higher for all languages other than C and C++. When the XML is parsed, all leading, trailing, and embedded white space is removed.