Create a SOAP fault response message that is returned as
the response to a web service request. The web service application
response is not processed.
SOAPFAULT CREATE
>>-SOAPFAULT CREATE--------------------------------------------->
>--+-FAULTCODE(cvda)----------------------------------------+--->
+-CLIENT-------------------------------------------------+
+-SERVER-------------------------------------------------+
+-SENDER-------------------------------------------------+
+-RECEIVER-----------------------------------------------+
'-FAULTCODESTR(data-value)--+--------------------------+-'
'-FAULTCODELEN(data-value)-'
.-NATLANG('en')-------.
>--FAULTSTRING(data-value)--+-------------------------+--+---------------------+-->
'-FAULTSTRLEN(data-value)-' '-NATLANG(data-value)-'
>--+----------------------------------------------+------------->
'-ROLE(data-value)--+------------------------+-'
'-ROLELENGTH(data-value)-'
>--+-----------------------------------------------------+------>
'-FAULTACTOR(data-value)--+-------------------------+-'
'-FAULTACTLEN(data-value)-'
>--+--------------------------------------------------+--------->
'-DETAIL(data-value)--+--------------------------+-'
'-DETAILLENGTH(data-value)-'
>--+-----------------------+-----------------------------------><
'-FROMCCSID(data-value)-'
Conditions: CCSIDERR, CHANNELERR, INVREQ, LENGERR
This command is threadsafe.
Description
SOAPFAULT CREATE creates
a SOAP fault. If a SOAP fault already exists in the context of the
SOAP message that is being processed by the message handler, the existing
fault is overwritten. This command can be used only in programs attached
from a supplied SOAP handler. Axis2 applications hosted in a Java
pipeline in CICS® cannot make
use of this command.
This command requires information
that is held in containers on the channel of the 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.
- Programs that are using global user exits to monitor web services.
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 raises
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
- DETAIL(data-value)
- Specifies the following contents:
- For SOAP 1.1, this option supplies the contents of the <detail> element
of the SOAP fault.
- For SOAP 1.2, this option supplies the contents of the <Detail> element
of the SOAP fault.
It should contain either one or more valid namespace-qualified
XML elements, or white space. Refer to the appropriate SOAP specifications
for a full description of the valid content of the element.
- The element carries application-specific error information related
to the <Body> element, and is used when the contents
of the <Body> element could not be successfully
processed. For SOAP 1.1, the <detail> element
must be present if the contents of the <Body> element
could not be successfully processed; for SOAP 1.2, the <Detail> element
is optional.
- If the SOAPFAULT CREATE command is issued in a header
handler program, the detail content is carried in a header block for SOAP 1.1.
For SOAP 1.2 the <Detail> element is carried within the SOAP fault.
- DETAILLENGTH(data-value)
- Specifies the length, as a fullword binary value, of the DETAIL option.
- FAULTACTLEN(data-value)
- Specifies the length, as a fullword binary value, of the FAULTACTOR option.
- FAULTACTOR(data-value)
- Specifies the following contents:
- For SOAP 1.1, this option supplies the contents of the <faultactor> element.
- For SOAP 1.2, this option supplies the contents of the <Node> element.
The FAULTACTOR option can be up to 2056 characters
in length, and must be a valid URI (anyURI).
- FAULTCODE(cvda)
- CVDA values are as follows:
- CLIENT
- For SOAP 1.1, the CVDA value of Client should
be specified. However, if you specify Sender for
a SOAP 1.1 fault response message, CICS will
use the CVDA value of Client.
- SENDER
- For SOAP 1.2, the CVDA value of Sender should
be specified. However, if you specify Client for
a SOAP 1.2 fault response message, CICS will
use the CVDA value of Sender.
- SERVER
- For SOAP 1.1, the CVDA value of Server should
be specified. However, if you specify Receiver for
a SOAP 1.1 fault response message, CICS will
use the CVDA value of Server.
- RECEIVER
- For SOAP 1.2, the CVDA value of Receiver should
be specified. However, if you specify Server for
a SOAP 1.2 fault response message, CICS will
use the CVDA value of Receiver.
- FAULTCODELEN(data-value)
- Specifies the length, as a fullword binary value, of the FAULTCODESTR option.
- FAULTCODESTR(data-value)
- Specifies a user-defined SOAP fault code for a SOAP 1.1 message.
The fault code can be up to 64 characters in length, and must be an
XML qualified name (QName). The use of the dot (.)
character to separate fault code values is not supported. For SOAP
1.1, this option supplies the contents of the <faultcode> element.
- If you set this option for a SOAP 1.2 message, an INVREQ condition
occurs.
- FAULTSTRING(data-value)
- Specifies a human-readable explanation of the fault. The FAULTSTRING
value 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 binary 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 that 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 zSeries.
- NATLANG(data-value)
- Specifies an 8 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.
- This option is used only for SOAP 1.2 faults.
- ROLE(data-value)
- Specifies the URI that describes the role of the SOAP node that
generated the fault. The ROLE option can be up to
2056 characters in length, and must be a valid URI (XML type anyURI).
- For SOAP 1.1, this option is ignored.
- For SOAP 1.2, this option supplies the contents of the <Role> element.
- ROLELENGTH(data-value)
- Specifies the length, as a fullword binary value, of the ROLE option.
Conditions
- 123 CCSIDERR
- RESP2
values are:
- 13
- An invalid CCSID has been specified.
- 14
- An unsupported CCSID has been specified.
- 122 CHANNELERR
- RESP2
values are:
- 3
- The channel where this SOAPFAULT object is being created is read-only.
- 16 INVREQ
- RESP2
values are:
- 3
- The command was issued outside the environment of a CICS-supplied
SOAP handler.
- 11
- The FAULTCODE specified is invalid or FAULTCODESTR was
specified for a SOAP 1.2. fault.
- 13
- The DETAIL option does not contain valid namespace-qualified
XML or whitespace.
- 22 LENGERR
- RESP2
values are:
- 5
- The FAULTCODELEN value is invalid
- 6
- The FAULTSTRLEN value is invalid
- 7
- The ROLELENGTH value is invalid
- 8
- The FAULTACTLEN value is invalid
- 9
- The DETAILLENGTH value is invalid