Diagnosing data conversion errors with CICS Web services

Diagnosing The Problem

If you are running CICS TS V3.1 and experience a conversion problem, you should perform the following problem determination steps:

1. Ensure that the WEBSERVICE resource is up to date. Regenerate the WSBind file for the Web service and redeploy it to CICS.
   
   
2. Ensure that the remote partner process has been generated using the same version of the WSDL as used or generated by CICS.
   
   
3. If APAR PK23547 is applied to CICS TS V 3.1 (or CICS TS V3.2 is used) then there will be detailed messages in the MSGUSR log providing information about the problem. Look to see if one of the following messages has been issued: DFHPI1007, DFHPI1008, DFHPI1009, DFHPI1010.
   
   If it has then consider what the message says. It is likely to have identified a specific field within the SOAP message or language structure that it is having problems with. It will also identify the nature of the problem. Look up the user-action associated with the message using the CMAC transaction or the CICS Messages & Codes book for guidance on what to do next.
   
   
4. If you are sure that the WEBSERVICE resource points to an up-to-date WSBind file and if there isn't a detailed message in the CICS log then try the following:
   
   Enable runtime validation for the WEBSERVICE resource using CEMT. This will cause CICS to perform a full validation of the body of the SOAP messages sent to and from CICS to ensure that they are correct with respect to the WSDL. If any problems are detected then CICS will issue message DFHPI1001 to indicate the precise nature of the problem or message DFHPI1002 to indicate that no problems were found. This will help to identify the source of many types of conversion errors and may also identify subtle problems that would not normally cause a conversion error.
   
   Note: WEBSERVICE validation is performed on SOAP messages. If a conversion error occurs whilst CICS is generating a SOAP message from information provided by the application then WEBSERVICE validation will not be performed as the generation process will not have completed.
   
   
5. If you have still not determined the reason for the conversion error then take a CICS trace of the failing Web service and look for the following PI domain exception trace entries:
   
   PI 0F39 - PICC  *EXC* - CONVERSION_ERROR
   PI 0F08 - PIII  *EXC* - CONVERSION_ERROR

If either of these trace points appear then one of the following conversion errors will be indicated, the possible interpretations of which are supplied below. In all cases, the trace point identifies the name of the field associated with the conversion problem and may also identify the problematic value. A PICC conversion error implies that a problem occurred whilst transforming a SOAP message sent to CICS into a commarea. A PIII conversion error implies a problem generating a SOAP message from a commarea supplied by the application program. In the following explanations, the term 'commarea' should be understood to imply 'commarea (or container)'.

Note: the list of possible conversion errors that may occur has grown since CICS TS V3.1 was first released. As of the time of writing, new transformational capabilities have been added at mapping levels 1.1 and 1.2 to CICS TS V3.1 by APARs PK15904 and PK23547. These new capabilities may trigger conversion errors which are not included in the following list. For a complete list of all possible conversion errors and their meanings you should read the explanations of messages DFHPI1007, DFHPI1008, DFHPI1009 and DFHPI1010. Further conversion error codes have been added to CICS TS V3.2.

INPUT_TOO_LONG

• SOAP element that was declared as numeric contains more than 31 digits, or
• a numeric field in the commarea contains a value more than 31 digits in length.

OUTPUT_OVERFLOW

• a SOAP element contains a value that is too long to fit in the associated field of the commarea, or
• a SOAP element contains a numeric value which is outside the permitted range for the associated field in the commarea.
  
  Consider changing the WSDL to explicitly supply a 'maxLength' facet for this field. If a 'maxLength' is specified in the WSDL then CICS will ensure that this much space is set aside in the commarea for the field. If a 'maxLength' facet is not supplied then CICS has to take a guess at what the maximum length should be and may pick an inappropriate value. You could also consider adding a 'whitespace' facet for character based fields and set it to 'collapse'. This will ensure that white space (blanks) are removed from the field. By default white space is preserved.

NEGATIVE_UNSIGNED

• a negative number has been found in a SOAP element that was declared as unsigned, or
• a negative number has been found in a commarea in a field that was declared as unsigned.

NO_FRACTION_DIGITS

• a SOAP element contained a number which contains a decimal point but is not followed by any valid fractional digits.

FRACTION_TOO_LONG

• a SOAP element contained a number with more non-zero fraction digits than the WSDL allows.

INVALID_CHARACTER

• a SOAP element that was declared as boolean contains a value other than 0, 1, true or false, or
• a SOAP element that was declared as hexBinary contains a value that is not in the range 0-9 + a-f + A-F, or
• a SOAP element that was declared as numeric contains a nonnumeric character or
• a SOAP message is not well formed.

ODD_HEX_DIGITS

• a SOAP element that was declared as hexBinary contains an odd number of hexadecimal characters.

INVALID_PACKED_DEC

• a packed decimal field in the commarea contains an illegal value that can't be converted to XML.

INVALID_ZONED_DEC

• a zoned decimal field in the commarea contains an illegal value that can't be converted to XML.

INCOMPLETE_DBCS

• a DBCS sequence in the commarea is missing a shift in (SI) character.