Use the WSACONTEXT BUILD command
to insert or replace WS-Addressing message addressing properties (MAPs)
in the addressing context.
WSACONTEXT BUILD
>>-WSACONTEXT BUILD--+---------------------+-------------------->
'-CHANNEL(data-value)-'
.-------------------------------------------------------------------------------.
V |
>----+-ACTION(data-value)--------------------------------------------------------+-+-->
+-MESSAGEID(data-value)-----------------------------------------------------+
+-RELATESURI(data-value)--+-------------------------+-----------------------+
| '-RELATESTYPE(data-value)-' |
'-EPRTYPE(cvda)--EPRFIELD(cvda)--EPRFROM(data-value)--EPRLENGTH(data-value)-'
>--+--------------------------+--------------------------------><
+-FROMCCSID(data-value)----+
'-FROMCODEPAGE(data-value)-'
Conditions: CCSIDERR, CHANNELERR, CODEPAGEERR, INVREQ, LENGERR
This command is threadsafe.
Description
Use the
WSACONTEXT BUILD command
for any of the following actions:
- To insert or replace the Action or Message ID MAPs
- To insert or replace the To, From, ReplyTo, or FaultTo endpoint
reference MAPs.
- To insert the RelatesTo MAPs.
You can use the command repeatedly to supply different data
on each call, for example different endpoint references (EPRs). The
MAPs are applied to all outbound SOAP messages created by the INVOKE
SERVICE or INVOKE WEBSERVICE commands
and to response SOAP messages from a service provider.
Options
- ACTION(data-value)
- Specifies an input value containing an Action MAP of the request
or response SOAP message; for example, http://example.ibm.com/namespace/bookingInterface/MakeBooking.
Actions are supplied in the WSDL or are calculated by the Web services
assistant, but can be overridden by this option. The data value must
be 255 characters in length. If the Action MAP is less than 255 characters,
you must pad the data value with trailing blanks.
- CHANNEL(data-value)
- Specifies the name of the channel that holds
the addressing context. The name of the channel can be up to 16 characters
in length. If the channel name is fewer than 16 characters, you must
pad the data value with trailing blanks. If you do not specify this
option, the current channel is implied.
Acceptable characters for
the channel name are A-Z a-z 0-9 $ @ # / % & ? ! : | " = , ; <
> . - and _. Leading and embedded blank characters are not permitted.
The accepted set of characters for channel names includes some characters
that do not have the same representation in all EBCDIC code pages.
It is therefore recommended that, if channels are to be shipped between
regions, the characters used in naming them should be restricted to
A-Z a-z 0-9 & : = , ; < > . - and _.
- This option is required when the WSACONTEXT BUILD command
is used by a Web service requester application and is the channel
name used by subsequent INVOKE SERVICE commands.
- EPRFIELD(cvda)
- Specifies the endpoint reference field. You can use this option
multiple times to build a full endpoint reference.
- ADDRESS
- The Address field of the endpoint reference is specified as a
URI in the EPRFROM option.
- ALL
- A complete endpoint reference, described in XML, is specified
in the EPRFROM option.
- METADATA
- The Metadata section of the endpoint reference, described in XML,
is specified in the EPRFROM option.
- REFPARMS
- The ReferenceParameters section of the endpoint reference, described
in XML, is specified in the EPRFROM option.
- EPRFROM(data-value)
- An input data value that contains a complete or partial endpoint
reference that is to be placed in the addressing context. The EPRFIELD
option describes what part of the endpoint reference is specified
in this option by the application. The endpoint reference can be supplied
by a Web service application that uses the WSAEPR CREATE command
or from another source, such as a service registry.
- If the EPRFROM option contains an address, any special characters
in the address are automatically escaped or unescaped.
The following characters in an address are replaced with
an escape sequence: ", >, <, ', &
|
- EPRLENGTH(data-value)
- A fullword binary input data value used to contain the length
of the supplied EPR.
- EPRTYPE(cvda)
- Specifies the type of EPR that is being built:
- TOEPR
- The destination EPR to which a SOAP message is sent.
- REPLYTOEPR
- An EPR to which a SOAP response message is returned.
- FAULTTOEPR
- An EPR to which a SOAP fault message is returned.
- FROMEPR
- An EPR that represents the sender of the SOAP message.
- FROMCCSID(data-value)
- Specifies the current Coded Character Set Identifier (CCSID) of
the character data to be put into the addressing context, as a fullword
binary number. If you want to specify an IANA name for the code page
or if you want to specify the CCSID as alphanumeric characters, use
the FROMCODEPAGE option instead.
For CICS® Transaction Server for z/OS® applications,
the CCSID is typically an EBCDIC CCSID.
The default CCSID of
the region is specified on the LOCALCCSID system
initialization parameter.
For an explanation of CCSIDs, and
a list of the CCSIDs supported by CICS,
see CICS-supported conversions .
- FROMCODEPAGE(data-value)
- Specifies an IANA-registered alphanumeric charset name or a Coded
Character Set Identifier (CCSID) for the current code page of the
character data to be put into the addressing context, using up to
40 alphanumeric characters including appropriate punctuation. Use
this option instead of the CCSID option if you prefer to use an IANA-registered
charset name, as specified in the Content-Type header for an HTTP
request. CICS converts the
IANA name into a CCSID, and the subsequent data conversion process
is identical. Also use this option if you prefer to specify the CCSID
in alphanumeric characters, rather than as a fullword binary number.
Where
an IANA name exists for a code page and CICS supports
its use, the name is listed with the CCSID in CICS-supported conversions .
- MESSAGEID(data-value)
- Specifies a data value for a URI that uniquely identifies a SOAP
message. The data value must be 255 characters in length. If the URI
is less than 255 characters, you must pad the data area with trailing
blanks.
- RELATESTYPE(data-value)
- Specifies a URI denoting the relationship type between the message
to be sent and another message. The value must be 255 characters long.
If the URI is less than 255 characters, you must pad the data value
with trailing blanks. You are allowed to specify multiple RelatesTo
MAPs. Subsequent calls of the RELATESTYPE and RELATESURI options create
new RelatesTo MAPs.
- If you do not specify a value for this option, the RelatesTo MAP
does not have a type attribute in the SOAP message and defaults to
a value of http://www.w3.org/2005/08/addressing/reply.
- RELATESURI(data-value)
- Specifies a URI denoting the message ID of a message that the
message to be sent is related to. The value must be 255 characters
long. If the URI is less than 255 characters long, you must pad the
data value with trailing blanks.
Conditions
- 123 CCSIDERR
- RESP2
values:
- 1
- The CCSID specified on the FROMCCSID option is outside the range
of valid CCSID values.
- 2
- The CCSID specified on the FROMCCSID option and the CCSID of the
addressing context are an unsupported combination.
- 4
- One or more characters could not be converted. Each unconverted
character has been replaced by a blank in the converted data.
- 5
- There was an internal error in the code page conversion of the
addressing context data.
- 6
- Either the text encoding is not compatible with the specified
CCSID on the FROMCCSID option, or one or more characters are truncated.
- 122 CHANNELERR
- RESP2
values:
- 1
- The name specified for the CHANNEL option contains an illegal
character or combination of characters.
- 2
- The specified channel was not located.
- 125 CODEPAGEERR
- RESP2
values:
- 1
- The code page specified on the FROMCODEPAGE option is not supported.
- 2
- The code page specified on the FROMCODEPAGE option and the CCSID
of the addressing context are an unsupported combination.
- 4
- One or more characters could not be converted. Each unconverted
character has been replaced by a blank in the converted data.
- 5
- There was an internal error in the code page conversion of a container.
- 6
- Either the text encoding is not compatible with the specified
CCSID on the FROMCCSID option, or one or more characters are truncated.
- 16 INVREQ
- The INVREQ RESP2 values and the corresponding messages are shown
below. For this command, if the EIBRESP2 value is > 100, the fullword
EIBRESP2 field is regarded as a structure containing two halfwords.
The low-order halfword always contains the error number. The high-order
halfword contains the offset into the XML data where the parsing error
occurred.
- RESP2
values:
- 4
- The CHANNEL option was not specified. There is no current channel
because the program that issued the command was not passed the name
of a channel.
- 6
- The ACTION field does not contain valid URI characters.
- 7
- The MESSAGEID field does not contain valid URI characters.
- 8
- The RELATESURI field does not contain valid URI characters.
- 9
- The RELATESTYPE field does not contain valid URI characters.
- 10
- The EPRFROM option does not contain valid XML.
- 13
- The EPRFROM option does not contain valid XML. The EPR <Metadata>
might not contain valid XML.
- 14
- The EPRFROM option does not contain valid XML. The EPR <ReferenceParameters>
might not contain valid XML.
- 15
- The EPRFROM option might not contain a valid URI.
- 22 LENGERR
- RESP2 values:
- 20
- This condition occurs when the length of the stored data is greater
than the value specified by the EPRLENGTH option. This condition only
applies to the EPRINTO option and cannot occur with the EPRSET option.
- Default action: ends the task abnormally.