This command creates a SOAP fault. You can use this command only
in a program that is invoked from a CICS-supplied SOAP message handler.

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)-'
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 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
- DETAIL(data-value)
- 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 whitespace. 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> or <Detail> element is
carried in a header block.
- 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)
- 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)
- CLIENT
- SENDER
- For SOAP 1.1 specifies a SOAP Fault code of Client
- For SOAP 1.2 specifies a SOAP Fault code of Sender
- SERVER
- RECEIVER
- For SOAP 1.1 specifies a SOAP Fault code of Server
- For SOAP 1.2 specifies a SOAP Fault code 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. 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.
- For SOAP 1.2, this option supplies the contents of the <Code> element.
- 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.
- 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
- INVREQ
- RESP2
values are:
- 3
- The command was issued outside the environment of a CICS supplied SOAP
handler.
- 11
- The FAULTCODE specified is invalid.
- 13
- The DETAIL option does not contain valid namespace-qualified
XML or whitespace.
- 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