Run time limitations for code generated by the Web services assistant

At run time, CICS® is capable of transforming almost any valid SOAP message that conforms to the Web service description (WSDL) into the equivalent data structures. However, there are some limitations that you should be aware of when developing a service requester or service provider application using the Web services assistant batch jobs.

Code pages

CICS can support SOAP messages sent to it in any code page if there is an appropriate HTTP or MQ header identifying the code page. CICS converts the SOAP message to UTF-8 to process it in the pipeline, before transforming it to the code page required by the application program. To minimize the performance impact, it is recommended that you use the UTF-8 code page when sending SOAP messages to CICS. CICS always sends SOAP messages in UTF-8.

CICS can only transform SOAP messages if the code page used to convert data between the SOAP message and the application program is EBCDIC. Applications that expect data to be encoded in code pages such as UTF-8, ASCII and ISO8859-1 are unsupported. If you want to use DBCS characters within your data structures and SOAP messages, then you must specify a code page that supports DBCS. The EBCDIC code page that you select must also be supported by both Java™ and z/OS® conversion services. z/OS conversion services must also be configured to support the conversion from the code page of the SOAP message to UTF-8.

To set an appropriate code page, you can either use the LOCALCCSID system initialization parameter or the optional CCSID parameter in the Web services assistant jobs. If you use the CCSID parameter, the value that you specify overrides the LOCALCCSID code page for that particular Web service. If you do not specify the CCSID parameter, the LOCALCCSID code page is used to convert the data and the Web service binding file is encoded in US EBCDIC (Cp037).

Containers

In service provider mode, if you specify that the PGMINT parameter has a value of CHANNEL, then the container that holds your application data must be written to and read from in binary mode. This container is DFHWS-DATA by default. The PUT CONTAINER command must either have the DATATYPE option set to BIT, or you must omit the FROMCCSID option so that BIT remains the default. For example, the following code explicitly states that the data in the container CUSTOMER-RECORD on the current channel should be written in binary mode.
EXEC CICS PUT CONTAINER (CUSTOMER-RECORD)
							FROM (CREC)
							DATATYPE(BIT)

Although the containers themselves are all in BIT mode, any text fields within the language structure that map this data must use an EBCDIC code page - the same code page as you have specified in the LOCALCCSID or CCSID parameter. If you are using DFHWS2LS to generate the Web service binding file, there could be many containers on the channel that hold parts of the complete data structure. If this is the case, then the text fields in each of these containers must be read from and written to using the same code page.

If the application program is populating containers that are going to be converted to SOAP messages, the application is responsible for ensuring that the containers have the correct amount of content. If a container holds less data than expected, CICS issues a conversion error.

If an application program uses the INVOKE WEBSERVICE command, then any containers it passes to CICS could potentially be reused and the data within them replaced. To avoid this, make sure that you have finished with the data when you are passing a channel to CICS that has previously been used for another purpose. If you have a provider mode Web service that is also a requester mode Web service, it is recommended that you use a different channel when using the INVOKE WEBSERVICE command, rather than using the default channel that it was originally attached to. If your application program is using the INVOKE WEBSERVICE command many times, it is recommended that you either use different channels on each call to CICS, or ensure that all the important data from the first request is saved before making the second request.

Conforming with the Web services description

A Web service description could describe some of the possible content of a SOAP message as optional. If this is the case, DFHWS2LS allocates fields within the generated language structure to indicate whether the content is present or not. At run time, CICS populates these fields accordingly. If a field, for example an existence flag or an occurrence field, indicates that the information is not present, the application program should not attempt to process the fields associated with that optional content.

If a SOAP message is missing some of its content when CICS transforms it, the equivalent fields within the data structures are not initialized when passed to the application program.

A Web service description can also specify the white space processing rules to use when reading a SOAP message, and CICS implements these rules at run time.
  • If the value of the xsd:whiteSpace facet is replace, the white space characters such as "tab" and "carriage return" are replaced with spaces.
  • If the value of the xsd:whiteSpace facet is collapse, any leading and trailing white space characters are removed when generating SOAP messages.

SOAP messages

CICS does not support SOAP message content derivation. For example, a SOAP message could use the xsi:type attribute to specify that an element has a particular type, together with an xsi:schemaLocation attribute to specify the location of the schema that describes the element. CICS does not support the capability of dynamically retrieving the schema and transforming the value of the element based on the content of the schema. CICS does support the xsi:nil attribute when the mapping level set in the Web services assistant is 1.1 or higher, but this is the only XML schema instance attribute that is supported.

DFHWS2LS might have to make assumptions about the maximum length or size of some values in the SOAP message. For example, if the XML schema does not specify a maximum length for an xsd:string, then DFHWS2LS assumes that the maximum length is 255 characters and generates a language structure accordingly. You can change this value by using the DEFAULT-CHAR-MAXLENGTH parameter in DFHWS2LS. At run time, if CICS encounters a SOAP message with a value that is larger than the space that has been allocated in the language structure, CICS issues a conversion error.

If CICS is the service provider, a SOAP fault message is returned to the requester. If CICS is the service requester, then an appropriate RESP2 code is returned from the INVOKE WEBSERVICE command.

Some characters have special meanings in XML, such as the < and > characters. If any of these special characters appear within a character array that is processed by CICS at run time, then it is replaced with the equivalent entity. The XML entities that are supported are:
Character XML entity
& &amp;
< &lt;
> &gt;
" &quot;
' &apos;
CICS also supports the canonical forms of the numeric character references used for white space codes:
Character XML entity
Tab &#x9;
Carriage return &#xA;
Line feed &#xD;
Note that this support does not extend to any pipeline handler programs that are invoked.

The null character (x'00') is invalid in any XML document. If a character type field that is provided by the application program contains the null character, CICS truncates the data at that point. This allows you to treat character arrays as null terminated strings. Character type fields generated by DFHWS2LS from base64Binary or hexBinary XML schema data types represent binary data and could contain null characters without truncation.

SOAP fault messages

If CICS is the service provider, and you want the application program to issue a SOAP fault message, use the SOAPFAULT CREATE command. In order to use this API command, you must specify that the Web services assistant PGMINT parameter has a value of CHANNEL. If you do not specify this value, and the application program invokes the SOAPFAULT CREATE command, CICS does not attempt to generate a SOAP response message.