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.

Note: Null characters ('x00') are not valid in XML documents. Any null characters from application data parsed by CICS are seen to signify the end of a string and the value is truncated. When CICS generates application data it does so according to the value of the CHAR-VARYING parameter. For example, if the CHAR-VARYING=NULL option is specified, variable-length strings generated by CICS are ended with a null character.

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.

XML data types can be restricted using facets. Use the length facets (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 to preserve, replace, or collapse:
  • 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.
If the whiteSpace facet is not set, white space is preserved.
For more information about XML schema facets, see the W3C recommendation schema XML Schema Part 2: Datatypes Second Edition https://www.w3.org/TR/xmlschema-2/#facets
The following parameters on the CICS assistants, DFHSC2LS and DFHWS2LS, can be used to alter the way that variable-length data is mapped from the XML schema to the language structure. These parameters are available at mapping level 1.2 or higher.
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.
Setting CHAR-VARYING=YES typically results in the best performance.

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.