Start of change

SOAPFAULT ADD

This command adds information to an existing SOAPFAULT object. You can use this command only in a program that is invoked from a CICS-supplied SOAP message handler.

Read syntax diagramSkip visual syntax diagram
SOAPFAULT ADD

>>-SOAPFAULT ADD------------------------------------------------>

                                                       .-NATLANG('en')-------.     
>--+-FAULTSTRING(data-value)--FAULTSTRLEN(data-value)--+---------------------+-+-->
   |                                                   '-NATLANG(data-value)-' |   
   '-SUBCODESTR(data-value)--SUBCODELEN(data-value)----------------------------'   

>--+-----------------------+-----------------------------------><
   '-FROMCCSID(data-value)-'   

This command is threadsafe.

Description

This command adds information to a SOAPFAULT object that was created with an earlier SOAPFAULT CREATE command. The information that can be added comprises:
This command requires information that is held in containers on the channel of the CICS-supplied SOAP message handler. To use this command, you must have access to the channel. Only the following types of programs have this access:
  • Programs that are invoked as SOAP header handlers
  • Programs that are invoked directly from a CICS-supplied SOAP message handler
  • Programs deployed with the CICS Web services assistant that have a channel interface. Programs with a COMMAREA interface do not have access to the channel.
Many of the options on this command apply to SOAP 1.1 and SOAP 1.2 faults, although their behavior is slightly different for each level of SOAP. Other options apply to one SOAP level or the other, but not to both, and if you specify any of them when the message uses a different level of SOAP, the command will raise an INVREQ condition. To help you determine which SOAP level applies to the message, container DFHWS-SOAPLEVEL contains a binary fullword with one of the following values:
1
The request or response is a SOAP 1.1 message.
2
The request or response is a SOAP 1.2 message.
10
The request or response is not a SOAP message.

Options

SUBCODESTR(data-value)
Start of changeSpecifies the contents of a <Subcode> element that is to be added to the SOAPFAULT object. The subcode can be up to 64 characters in length, and must be an XML qualified name (QName). An XML qualified name has the form prefix:name.
  • For SOAP 1.1, this option is ignored.
  • For SOAP 1.2, this option supplies the contents of the <Subcode> element.
End of change
SUBCODELEN(data-value)
specifies the length, as a fullword binary value, of the <Subcode> element specified in the SUBCODESTR option.
FAULTSTRING(data-value)
specifies a human-readable explanation of the fault. The FAULTSTRING can be up to 2056 characters in length.
  • For SOAP 1.1, this option supplies the contents of the <faultstring> element.
  • For SOAP 1.2, this option supplies the contents of the <Reason> element.
FAULTSTRLEN(data-value)
Specifies the length, as a fullword binary value, of the FAULTSTRING option.
FROMCCSID(data-value)
Specifies, as a fullword decimal number, the current Coded Character Set Identifier (CCSID) of the character data to be put into the SOAP fault. If this option is not specified, CICS uses the value which is specified in the LOCALCCSID system initialization parameter. For more information about CCSIDs, and a list of the CCSIDs supported by CICS, see CICS Family: Communicating from CICS on System/390.
NATLANG(data-value)
Specifies an eight character field containing the national language used for the FAULTSTRING. The language is specified using the XML 1.0 language identification. The default value is 'en' (English).
When the language identifier is shorter than eight characters, you must pad it on the right with space characters in the character set specified in the FROMCCSID option (or the CICS LOCALCCSID). For example, if you specify the UTF-8 character set with FROMCCSID(1208), you must pad the NATLANG value with X'20' characters.

Conditions

INVREQ
RESP2 values are:
3
The command was issued outside the environment of a CICS supplied SOAP handler.
12
The contents of the SUBCODESTR is invalid.
LENGERR
RESP2 values are:
6
The FAULTSTRLEN value is invalid.
10
The SUBCODELEN value is invalid.
Start of changeCCSIDERREnd of change
Start of changeRESP2 values are:
13
The CCSID specified on the FROMCCSID option is outside the range of valid CCSID values.
14
The CCSID specified on the FROMCCSID option and the UTF-8 CCSID are an unsupported combination.
End of change
Start of changeNOTFNDEnd of change
Start of changeRESP2 values are:
4
There is no SOAPFAULT to which data can be added.
End of change
End of change