Create a consumer Web service deployment descriptor

Consumer Web service deployment descriptors are specialized XML documents that are used to control the activation of consumer Web services.

The deployment descriptor must be named according to the following format:

ddname.xml

where ddname is the 1- to 252-character, unique name of the file to be placed in the /etc/tpf-ws/ directory of the z/TPF file system.

The format for this deployment descriptor is defined in the base/tpf-ws/schema/tpf_ws_dd_vn.xsd XML Schema file (where n is the version number and must be 2 or higher) that is shipped with the z/TPF system. The following elements of the consumer Web service deployment descriptor must appear in the XML document in the same order as they are listed here.

Note: TPF Toolkit provides tooling to help you create the consumer Web service deployment descriptor.

ConsumerDeploymentDescriptor: The namespace universal resource identifier (URI) for this element and for each of the elements that follow must be set to "http://www.ibm.com/xmlns/prod/ztpf/soap". Set this namespace URI by using a default namespace for the XML document or by establishing your own namespace prefix.
xsi:schemaLocation: This attribute must be present on the root element of the deployment descriptor XML document. Set it to the following value to indicate the location of the deployment descriptor schema document in the z/TPF file system: xsi:schemaLocation="http://www.ibm.com/xmlns/prod/ztpf/soap file:/etc/tpf-ws/schema/tpf_ws_dd_vn.xsd", where n is the version number.
ServiceURI: The 1- to 512-character URI for the Web service that is identified by this deployment descriptor. The URI that is specified must match exactly the value that will be specified for the tpf_soapInvokeService C function call.
Stub: Indicates the 4-character name of the Web service stub that is called to build the SOAP request message and to process the SOAP response message. Valid characters include A-Z and 0-9.
SOAPProcessing: Identifies the elements in the Web service deployment descriptor that control the processing of the SOAP consumer handler when a SOAP request or response is being processed for this Web service. The following elements are children of this element: SOAPMessageHandlerChain, VerifySOAPHeaders, and SOAPVersion.
SOAPMessageHandlerChain: Indicates the list of SOAP message handlers that are to be called when a SOAP request is being built for this Web service. The order that the SOAP message handlers are specified is the order in which they will be called when processing the tpf_soapInvokeService C function call. The same SOAP message handlers will be called in the reverse order when processing a SOAP response message. This element is optional. The following element is a child of this element: SOAPMessageHandler.
SOAPMessageHandler: Indicates the SOAP message handler to be called when processing a SOAP request that is sent to this Web service, or a SOAP response that is received from this Web service. The SOAP message handler name specified is the 1- to 32-character, user-specified symbolic name that uniquely identifies the SOAP message handler to be called.

A corresponding SOAP message handler deployment descriptor must exist. The SOAPMessageHandler element can appear multiple times when more than one SOAP message handler is to be called for this Web service. The following attribute can be specified for this element: required.

The required attribute indicates whether SOAP header blocks that are referenced by this SOAP message handler are required to appear in SOAP requests and responses for this Web service. The value that is set will be passed to the SOAP message handler program to perform the actual validation.

true: Indicates that the corresponding SOAP header blocks must be present in SOAP requests and responses for this Web service.
false: Indicates that the corresponding SOAP header blocks are optional in SOAP requests and responses for this Web service.

VerifySOAPHeaders

Indicates whether the z/TPF SOAP runtime should verify the SOAP header blocks that appear in SOAP responses received for this Web service. SOAP header blocks are used to implement SOAP features, which extend the basic SOAP standard.

true

All SOAP header blocks that are present in SOAP responses received for this Web service will be verified. If the z/TPF SOAP runtime detects a SOAP header block that has the mustUnderstand attribute set to "true" (SOAP 1.1 or SOAP 1.2) or "1" (SOAP 1.1), and a corresponding SOAP message handler has not been called to process the SOAP header block, the z/TPF system will treat this SOAP response as not valid and return an error to the calling application.

Note: The z/TPF SOAP runtime will only verify those SOAP header blocks for which it is determined that the z/TPF system plays the required role, as determined by the “actor” attribute (SOAP 1.1) or the “role” attribute (SOAP 1.2) specified on the SOAP header block. The following roles are valid for the z/TPF system:

http://www.w3.org/2003/05/soap-envelope/role/none
http://www.w3.org/2003/05/soap-envelope/role/next
http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver

false

The z/TPF SOAP runtime does not verify any of the SOAP header blocks that are contained in SOAP responses that are received for this Web service. All SOAP message handlers specified in the SOAPMessageHandlerChain are still called by the z/TPF SOAP runtime; however, no verification is performed that all of the necessary SOAP header blocks have been processed. Use this value when there might be SOAP header blocks included in the SOAP responses that are handled by the Web service stub itself, rather than by SOAP message handlers.

SOAPVersion

Indicates the acceptable format of SOAP requests for this Web service. This element is optional, and if not specified, the z/TPF SOAP runtime treats this Web service as if the DEFAULT value had been specified. If the Web service accepts SOAP requests in multiple formats, this element can appear multiple times, unless otherwise stated. If a SOAP response is received for this Web service in an unacceptable format, the z/TPF SOAP runtime will treat this SOAP response as not valid and return an error to the calling application.

DEFAULT: Indicates that SOAP requests are expected to be in the format corresponding to the DEFAULT_SOAP_VERSION value that is set in the tpf/c_usoapeq.h header file. When this value is specified, the SOAPVersion element cannot appear more than once.
SOAP1.1: Indicates that a SOAP response for this Web service is acceptable if it is in SOAP 1.1 format. This value and the BP1.1_SSBP1.1 value cannot both be specified for the same Web service.
SOAP1.2: Indicates that a SOAP response for this Web service is acceptable if it is in SOAP 1.2 format.
BP1.1_SSBP1.1: Indicates that a SOAP request for this Web service is acceptable if it is in SOAP 1.1 format. Also, this instructs the z/TPF SOAP runtime to perform checks on the message to ensure that it is compliant with the Organization for the Advancement of Structured Information Standards (OASIS) Web Services Interoperability (WS-I) Basic Profile 1.1 and the OASIS WS-I Simple Soap Binding Profile 1.1. When a SOAP response is found to be non-compliant, the z/TPF SOAP runtime will treat the SOAP response as not valid and return an error to the calling application. This value and the SOAP1.1 value cannot both be specified for the same Web service.

Operation

Indicates the 1- to 128-character name of a service method that is exposed as part of this Web service. The Operation element is optional, but can appear multiple times if this Web service exposes multiple methods.

Description

Indicates a 1- to 256-character, meaningful description that you have written of the Web service that is identified by this deployment descriptor. This element is optional.

TransportAutoFailover

Indicates whether the SOAP consumer handler should automatically try the next transport method in the chain if a transport-specific error is received from an attempt to call a Web service.

true: Indicates that the next transport in the chain should be tried.
false: Indicates that the tpf_soapInvokeService C function should return to the caller with the transport-specific error and leave it to the application to decide how to proceed.

ProviderCodepage

Optionally indicates the code page of the SOAP provider Web service. If this option is not present, the DEFAULT_SOAP_PROVIDER_CODEPAGE value in tpf/c_usoapeq.h will be used as the default. If this option or the default are set to any of the following code pages, SOAP consumer processing will translate the XML request and response as needed. If the code page is not set to one of the code pages that follow, SOAP provider processing will first call the UWST user exit so that you can translate the XML message and if the translation is not done, will use iconv to translate the message.

IBM-500
IBM-1047
ISO-8859–1
UTF-8
UTF-16BE
UTF-16LE
UTF-EBCDIC. This code page is supported only if the code page specified by the ConsumerCodepage element is UTF-8.

ConsumerCodepage

Optionally indicates the code page of the SOAP consumer application. If this option is not present, the DEFAULT_SOAP_CONSUMER_CODEPAGE value in tpf/c_usoapeq.h will be used as the default. If this option or the default is set to any of the following code pages, SOAP consumer processing will translate the XML request and response as needed. If the code page is not set to one of the code pages that follow, SOAP consumer processing will first call the SOAP consumer translation user exit (tpf_soapTranslationExit) so that you can translate the XML message and if the translation is not done, will use iconv to translate the message.

IBM-500
IBM-1047
ISO-8859–1
UTF-8
UTF-16BE
UTF-16LE
UTF-EBCDIC. This code page is supported only if the code page specified by the ProviderCodepage element is UTF-8.

Note: The UTF-8 and UTF-16BE translations can only be used with the SOAP_XML_DOCUMENT data format on the tpf_soapInvokeService function; otherwise, the B2B scanner will fail when parsing.

TransportChain

Indicates the list of transports that can be used to reach this Web service. The first transport in the chain is considered the default; you can define one or more transports. The following element is a child of this element: Transport.

Transport

Indicates the transport information that can be used to reach this Web service. The first transport in the chain is considered the default. The following elements are children of this element: HTTPTransport, MQTransport, TPFTransport, and UserTransport.

HTTPTransport

Indicates the HTTP transport information that can be used to reach this Web service. The following elements are children of this element: HTTPURL, HTTPHeaderList.

HTTPURL

Indicates the uniform resource locator (URL) to use for the specified HTTP client request; the URL must be less than 1024 characters. The URL is a combination of the protocol (HTTP or HTTPS), the host name, and the request uniform resource identifier (URI).

Optionally, it can also include the user name, password, and port number. For example, https://user:pass@www.url.com:99 uses a secure HTTP connection with a user name of user and a password of pass; it connects to www.url.com over port 99. This is the accepted format of the url parameter:

http[s]://[user[:password]@]host[:port]/[relative uri]

HTTPHeaderList

Indicates a list of HTTP headers that are required for this Web service. This element is optional. The following element is a child of this element: HTTPHeader.

Header: Indicates the name and value of the header, in the form header: value. The length of header: value is from 1 to 1024 characters.

MQTransport

Indicates the IBM® MQ transport information that can be used to reach this Web service. The following elements are children of this element: MQQueueName, MQAsyncReplyQueueName, and MQSyncReplyQueueName.

MQQueueName

Indicates the queue to send the SOAP message to when using the IBM MQ transport to access a Web service.

MQAsyncReplyQueueName

Indicates the queue that the Web service will post the reply message to when using the IBM MQ transport to access a Web service using an asynchronous message exchange pattern (MEP).

MQSyncReplyQueueName

Indicates the queue that the Web service will post the reply message to when using the IBM MQ transport to access a Web service using a synchronous message exchange pattern (MEP).

MQRFH2

Indicates whether the SOAP consumer handler should include a request format header type 2 (MQRFH2) when sending the SOAP request to the Web service provider. When the MQRFH2 header is supported by the Web service provider, it will be set up by the SOAP consumer handler to include information about the Web service to be called. This element is optional. The following element is a child of this element: MQsoapAction.

Note: If a child element is not specified, the SOAP consumer handler will generate an MQRFH2 that specifies only the contentType for the SOAP request.

MQsoapAction: The 1- to 512-character URI that is used by the Web service provider to identify the Web service to which the SOAP request is to be delivered. This element is optional.

TPFTransport

Indicates the z/TPF transport information that can be used to reach this Web service. The following elements are children of this element: TPFLocal and TPFtoTPF.

Note: You can specify either TPFLocal, or the combination of TPFtoTPFHost and TPFtoTPFPort.

TPFLocal

Indicates that the destination Web service resource is on the current z/TPF processor and that the same ECB will be used to call the service.

TPFtoTPF

The following elements are children of this element: TPFtoTPFHost and TPFtoTPFPort.

TPFtoTPFHost: Indicates the hostname or IP address of the z/TPF processor that the Web service resides on.
TPFtoTPFPort: Indicates the port number that will be used to access the z/TPF Web service. This is an integer in the range of 1 to 65535.

UserTransport

Indicates the user transport information that can be used to reach this Web service. The following elements are children of this element: UserProgramName, UserData.

UserProgramName: Indicates the 4-character name of the z/TPF program that is activated when a user-defined transport is to be used.
UserData: Indicates a user-defined string to be passed to the specified user transport program. The length of the string can be from 1 to 1024 characters.