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.
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).
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.
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.
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.
Character | XML entity |
---|---|
& | & |
< | < |
> | > |
" | " |
' | ' |
Character | XML entity |
---|---|
Tab | 	 |
Carriage return | 
 |
Line feed | 
 |
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.
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.