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.
SOAPFAULT ADD
>>-SOAPFAULT ADD------------------------------------------------>
.-NATLANG('en')-------.
>--+-FAULTSTRING(data-value)--+-------------------------+--+---------------------+-+-->
| '-FAULTSTRLEN(data-value)-' '-NATLANG(data-value)-' |
'-SUBCODESTR(data-value)--+------------------------+----------------------------'
'-SUBCODELEN(data-value)-'
>--+-----------------------+-----------------------------------><
'-FROMCCSID(data-value)-'
Conditions: CHANNELERR, INVREQ, LENGERR
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:
- A subcode
- A fault string for a particular national language. If the fault
already contains a fault string for the language, then this command
replaces the fault string for that language. In SOAP 1.1, only the
fault string for the original language is used.
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
- SUBCODESTR(data-value)
- Specifies 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).
- For SOAP 1.1, this option is ignored.
- For SOAP 1.2, this option supplies the contents of the <Subcode> element.
- 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
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.
Conditions
- 122 CHANNELERR
- RESP2
values are:
- 3
- The channel where this SOAPFAULT object is being added is read-only.
- 16 INVREQ
- RESP2
values are:
- 3
- The command was issued outside the environment of a CICS-supplied
SOAP handler.
- 7
- No SOAP fault present
- 11
- Invalid subcode
- 22 LENGERR
- RESP2
values are:
- 6
- The FAULTSTRLEN value is invalid
- 10
- The SUBCODELEN value is invalid