Tuxedo ATMI Programming for Web Services

Oracle SALT allows you to import external Web Services into Tuxedo Domains. To import external Web services into Tuxedo application, a WSDL file must first be loaded and converted. The Oracle SALT WSDL conversion utility, wsdlcvt, translates each wsdl:operation into a Oracle SALT proxy service. The translated SALT proxy service can be invoked directly through standard Tuxedo ATMI functions.

Oracle SALT proxy service calls are sent to the GWWS server. The request is translated from Tuxedo typed buffers into the SOAP message, and then sent to the corresponding external Web Service. The response from an external Web Service is translated into Tuxedo typed buffers and returned to the Tuxedo application. The GWWS acts as the proxy intermediary.

If an error occurs during the service call, the GWWS server sets the error status using tperrno, which can be retrieved by Tuxedo applications. This enables you to detect and handle the SALT proxy service call error status.

Converting WSDL Model Into Tuxedo Model

Oracle SALT provides a WSDL conversion utility, wsdlcvt, that converts external WSDL files into Tuxedo specific definition files so that you can develop Tuxedo ATMI programs to access services defined in the WSDL file.

WSDL-to-Tuxedo Object Mapping

Oracle SALT converts WSDL object models into Tuxedo models using the following rules:

Only SOAP over HTTP binding are supported, each binding is defined and saved as a WSBinding object in the WSDF file.
Each operation in the SOAP bindings is mapped as one Tuxedo style service, which is also called a SALT proxy service. The operation name is used as the Tuxedo service name and indexed in the Tuxedo Service Metadata Repository.

Note: If the operation name exceeds the Tuxedo service name length limitation (15 characters), you must manually set a unique short Tuxedo service name in the metadata respository and set the <Service> tuxedoRef attribute in the WSDF file.

Note:

For more information, see Oracle SALT Web Service Definition File Reference in the Oracle SALT Reference Guide.

Other Web service external application protocol information is saved in the generated WSDF file (including SOAP protocol version, SOAP message encoding style, accessing endpoints, and so).
XML Schema definitions embedded in the WSDL file are copied and saved in separate .xsd files.
Each wsdl:operation object and its input/output message details are converted as a Tuxedo service definition conforms to Tuxedo Service Metadata Repository input syntax.

Table 4-1 lists detailed mapping relationships between the WSDL file and Tuxedo definition files.

Table 4-1 WSDL Model / Tuxedo Model Mapping Rules
WSDL Object	Tuxedo/SALT Definition File	Tuxedo/SALT Definition Object
/wsdl:binding	SALT Web Service Definition File (WSDF)	/WSBinding
/wsdl:portType	/WSBinding/Servicegroup
/wsdl:binding/soap:binding	/WSBinding/SOAP
/wsdl:portType/operation	Metadata Input File (MIF)	/WSBinding/service
/wsdl:types/xsd:schema	FML32 Field Defintion Table	Field name type

Invoking SALT Proxy Services

The following sections include information on how to invoke the converted SALT proxy service from a Tuxedo application:

Oracle SALT Supported Communication Pattern

Oracle SALT only supports the Tuxedo Request/Response communication patterns for outbound service calls. A Tuxedo application can request the SALT proxy service using the following communication Tuxedo ATMIs:

tpcall(1) / tpacall(1) / tpgetreply(1)

These basic ATMI functions can be called with a Tuxedo typed buffer as input parameter. The return of the call will also carry a Tuxedo typed buffer. All these buffers will conform to the converted outside Web service interface. tpacall/tpgetreply is not related to SOAP async communication.

tpforward(1)

Tuxedo server application can use this function to forward a Tuxedo request to a specified SALT proxy service. The response buffer is sent directly to client application’s response queue as if it’s a traditional native Tuxedo service.

TMQFORWARD enabled queue-based communication.

Tuxedo system server TMQFORWARD can accept queued requests and send them to Oracle SALT proxy services that have the same name as the queue.

Conversational communication
Event-based communication

Tuxedo Outbound Call Programming: Main Steps

When the GWWS is booted and Oracle SALT proxy services are advertised, you can create a Tuxedo application to call them. To develop a program to access SALT proxy services, do the following:

Check the Tuxedo Service Metadata Repository definition to see what the SALT proxy service interface is.
Locate the generated FML32 field table files. Modify the FML32 field table to eliminate conflicting field names and assign a valid base number for the index.

Note:

The wsdlcvt generated FML32 field table files are always used by GWWS. you must make sure the field name is unique at the system level. If two or more fields are associated with the same field name, change the field name. Do not forget to change Tuxedo Service Metadata Repository definition accordingly.

The base number of field index in the generated FML32 field table must be changed from the invalid default value to a correct number to ensure all field index in the table is unique at the entire system level.

Generate FML32 header files with mkfldhdr32(1).
Boot the GWWS with correct FML32 environment variable settings.
Write a skeleton C source file for the client to call the outbound service (refer to Tuxedo documentation and the Tuxedo Service Metadata Repository generated pseudo-code if necessary). You can use tpcall(1) or tpacall(1) for synchronous or asynchronous communication, depending on the requirement.
For FML32 buffers, you need to add each FML32 field (conforming to the corresponding Oracle SALT proxy service input buffer details) defined in the Tuxedo Service Metadata Repository, including FML32 field sequence and occurrence. The client source may include the generated header file to facilitate referencing the field name.
Get input buffer ready, user can handle the returned buffer, which should be of the type defined in Metadata.
Compile the source to generate executable.
Test the executable.

Managing Error Code Returned from GWWS

If the GWWS server encounters an error accessing external Web services, tperrno is set accordingly so the Tuxedo application can diagnose the failure. Table 4-2 lists possible Oracle SALT proxy service tperrno values.

Table 4-2 Error Code Returned From GWWS/Tuxedo Framework
TPERRNO	Possible Failure Reason
TPENOENT	Requested SALT proxy service is not advertised by GWWS
TPESVCERR	The HTTP response message returned from external Web service application is not valid The SOAP response message returned from external Web service application is not well-formed.
TPEPERM	Authentication failure.
TPEITYPE	Message conversion failure when converting Tuxedo request typed buffer into XML payload of the SOAP request message.
TPEOTYPE	Message conversion failure when converting XML payload of the SOAP response message into Tuxedo response typed buffer.
TPEOS	Request is rejected because of system resource limitation
TPETIME	Timeout occurred. This timeout can either be a BBL blocktime, or a SALT outbound call timeout.
TPSVCFAIL	External Web service returns SOAP fault message
TPESYSTEM	GWWS internal errors. Check ULOG for more information.

Handling Fault Messages in a Tuxedo Outbound Application

All rules listed in used to map WSDL input/output message into Tuxedo Metadata inbuf/outbuf definition. WSDL file default message can also be mapped into Tuxedo Metadata errbuf, with some amendments to the rules:

There are two modes for mapping Metadata errbuf into SOAP Fault messages: Tux Mode and XSD Mode.

Tux Mode is used to convert Tuxedo original error buffers returned with TPFAIL. The error buffers are converted into XML payload in the SOAP fault <detail> element.
XSD Mode is used to represent SOAP fault and WSDL file fault messages defined with Tuxedo buffers. The mapping rule includes:

Each service in XSD mode (servicemode=webservice) always has an errbuf in Metadata, with type=FML32.
errbuf is a FML32 buffer. It is a complete descriptionof the SOAP:Fault message that may appear in correspondence (which is different for SOAP 1.1 and 1.2). The errbuf definition content is determined by the SOAP version and WSDL fault message both.
Parameter detail/Detail (1.1/1.2) is an FML32 field that represents thethe wsdl:part defined in a wsdl:fault message (when wsdl:fault is present). Each part is defined as a param(field) in the FML32 field. The mapping rules are the same as for input/output buffer. The difference is that each param requiredcount is 0, which means it may not appear in the SOAP fault message.
Other elements that appear in soap:fault message are always defined as a filed in errbuf, with requiredcount equal to 1 or 0 (depending on whether the element is required or optional).
Each part definition in the Metadata controls converting a <detail> element in the soap fault message into a field in the error buffer.

Meta Parameter	SOAP Version	Type	Required	Memo
faultcode	1.1	string	Yes
faultstring	1.1	string	Yes
faultactor	1.1	string	No
detail	1.1	fml32	No	If no wsdl:fault is defined, this field will contain an XML field.
Code	1.2	fml32	Yes	Contain Value and optional Subcode
Reason	1.2	fml32	Yes	Contains multiple Text
Node	1.2	string	No
Role	1.2	string	No
Detail	1.2	fml32	No	same as detail field

Programming Guide