![]() |
![]() |
![]() |
![]() |
![]() |
Oracle SALT supports bi-directional data type mapping between WSDL messages and Oracle Tuxedo typed buffers. For each service invocation, GWWS server converts each message between Oracle Tuxedo typed buffer and SOAP message payload. SOAP message payload is the XML effective data encapsulated within the <soap:body> element. For more information, see Understanding Oracle SALT Message Conversion.For native Oracle Tuxedo services, each Oracle Tuxedo buffer type is described using an XML Schema in the SALT generated WSDL document. Oracle Tuxedo service request/response buffers are represented in regular XML format. For more information, see Tuxedo-to-XML Data Type Mapping for Oracle Tuxedo Services.For external Web services, each WSDL message is mapped as an Oracle Tuxedo FML32 buffer structure. An Oracle Tuxedo application invokes SALT proxy service using FML32 buffers as input/output. For more information see, XML-to-Tuxedo Data Type Mapping for External Web Services.Oracle SALT encloses Oracle Tuxedo buffer content with element <inbuf>, <outbuf> and/or <errbuf> in the SOAP message, the content included within element <inbuf>, <outbuf> and/or <errbuf> is called “Inbound XML Payload”.Table 2‑1 compares an inbound message conversion process and an outbound message conversion process.
Oracle SALT provides a set of rules for describing Oracle Tuxedo typed buffers in an XML document as shown in Table 2‑2. These rules are exported as XML Schema definitions in SALT WSDL documents. This simplifies buffer conversion and does not require previous Oracle Tuxedo buffer type knowledge.
In the SOAP message, the XML element that encapsulates the actual string data, must be defined using xsd:string directly.
• The STRING data type can be specified with a max data length in the Oracle Tuxedo Service Metadata Repository. If defined in Oracle Tuxedo, the corresponding SOAP message also enforces this maximum. The GWWS server validates the actual message byte length against the definition in Oracle Tuxedo Service Metadata Repository. A SOAP fault message is returned if the message byte length exceeds supported maximums. Oracle Tuxedo CARRAY typed buffers store character arrays, any of which can be NULL. CARRAY buffers are used to handle data opaquely and are not self-describing. The CARRAY buffer raw data is carried within a MIME multipart/related message, which is defined in the “SOAP Messages with Attachments’ specification.
•
Note: Oracle Tuxedo CARRAY typed buffers store character arrays, any of which can be NULL. CARRAY buffers are used to handle data opaquely and are not self-describing. The CARRAY data bytes must be encoded with base64Binary before it can be embedded in a SOAP message. Using base64Binary encoding with this opaque data stream saves the original data and makes the embedded data well-formed and readable.In the SOAP message, the XML element that encapsulates the actual CARRAY data, must be defined with xsd:base64Binary directly.
Note: CARRAY data type can be specified with a max byte length. If defined in Oracle Tuxedo, the corresponding SOAP message is enforced with this limitation. The GWWS server validates the actual message byte length against the definition in the Oracle Tuxedo Service Metadata Repository. Oracle Tuxedo MBSTRING typed buffers are used for multibyte character arrays. Oracle Tuxedo MBSTRING buffers consist of the following three elements: The XML Schema built-in type, xsd:string, represents the corresponding type for buffer data stored in a SOAP message.The GWWS server only accepts “UTF-8” encoded XML documents. If the Web service client wants to access Oracle Tuxedo services with MBSTRING buffer, the mbstring payload must be represented as “UTF-8” encoding in the SOAP request message.
Note: The GWWS server transparently passes the “UTF-8” character set string to the Oracle Tuxedo service using MBSTRING Typed buffer format.The actual Oracle Tuxedo services handles the UTF-8 string.For any Oracle Tuxedo response MBSTRING typed buffer (with any encoding character set), The GWWS server automatically transforms the string into “UTF-8” encoding and sends it back to the Web service client. Oracle Tuxedo MBSTRING data type can be specified with a max byte length in the Oracle Tuxedo Service Metadata Repository. The GWWS server checks the byte length of the converted MBSTRING buffer value. The XML Schema built-in type, xsd:anyType, is the corresponding type for XML documents stored in a SOAP message. It allows you to encapsulate any well-formed XML data within the SOAP message.
Note: The Oracle SALT WSDL generator will not have xsd:maxLength restrictions in the generated WSDL document, but the GWWS server will validate the byte length according to the Oracle Tuxedo Service Metadata Repository definition. X_C_TYPE buffer types are equivalent to VIEW buffer types. See VIEW/VIEW32 X_COMMON buffer types are equivalent to VIEW buffer types, but are used for compatibility between COBOL and C programs. Field types should be limited to short, long, and string See VIEW/VIEW32 X_OCTET buffer types are equivalent to CARRAY buffer types
•
•
•
•
•
•
•
• Each VIEW or VIEW32 data type is defined as an XML Schema complex type. Each VIEW field should be one or more sub-elements of the XML Schema complex type. The name of the sub-element is the VIEW field name. The occurrence of the sub-element depends on the count attribute of the VIEW field definition. The value of the sub-element should be in the VIEW field data type corresponding XML Schema type.
• short maps to xsd:short
• int maps to xsd:int
• long maps to xsd:long
• float maps to xsd:float
• double maps to xsd:double
•
• char (defined as char in Oracle Tuxedo Service Metadata Repository definition) maps to xsd:string (with restrictions maxlength=1)
• string maps to xsd:string
• carray maps to xsd:base64Binary
• mbstring maps to xsd:string
•
• Each FML/FML32 field should be one or more sub-elements within the FML/FML32 buffer XML Schema type. The name of the sub-element is the FML field name. The occurrence of the sub-element depends on the count and required count attribute of the FML/FML32 field definition.
• short maps to xsd:short
• int maps to xsd:int
• long maps to xsd:long
• float maps to xsd:float
• double maps to xsd:double
• char (defined as byte in Oracle Tuxedo Service Metadata Repository definition) maps to xsd:byte
• char (defined as char in Oracle Tuxedo Service Metadata Repository definition) maps to xsd:string
• string maps to xsd:string
• carray maps to xsd:base64Binary
• mbstring maps to xsd:string
• view32 maps to tuxtype:view <viewname>
• fml32 maps to tuxtype:fml32 <svcname>_p<SeqNum>To avoid multiple embedded FML32 buffers in an FML32 buffer, a unique sequence number (<SeqNum>) is used to distinguish the embedded FML32 buffers.
Note: ptr is not supported.For limitations and considerations regarding mapping FML/FML32 buffers, refer to ?$paratext>? on page 2‑26.Oracle Tuxedo STRING typed buffers are used to store character strings that end with a NULL character. Oracle Tuxedo STRING typed buffers are self-describing.Listing 2‑1 shows a SOAP message for a TOUPPER Oracle Tuxedo service example that accepts a STRING typed buffer.The XML Schema for <inbuf> is:Oracle Tuxedo CARRAY typed buffers are used to store character arrays, any of which can be NULL. They are used to handle data opaquely and are not self-describing. Oracle Tuxedo CARRAY typed buffers can map to xsd:base64Binary or MIME attachments. The default is xsd:base64Binary.Listing 2‑2 shows the SOAP message for the TOUPPER Oracle Tuxedo service, which accepts a CARRAY typed buffer using base64Binary mapping.The XML Schema for <inbuf> is:Listing 2‑3 shows the SOAP message for the TOUPPER Oracle Tuxedo service, which accepts a CARRAY typed buffer as a MIME attachment.Oracle Tuxedo MBSTRING typed buffers are used for multibyte character arrays. Oracle Tuxedo MBSTRING typed buffers consist of the following three elements:
Note: Listing 2‑4 shows the SOAP message for the MBSERVICE Oracle Tuxedo service, which accepts an MBSTRING typed buffer.Listing 2‑4 SOAP Message for an MBSIRING Buffer<inbuf>こんにちは</infuf>The XML Schema for <inbuf> is:If you use another character conversion engine and Japanese "—" is included in MBSTRING, Oracle Tuxedo server-side MBSTRING auto-conversion cannot convert it back into Shift-JIS or EUC-JP.Listing 2‑5 shows the Stock Quote XML document.Listing 2‑6 shows the SOAP message for the STOCKINQ Oracle Tuxedo service, which accepts an XML typed buffer.Listing 2‑5 Stock Quote XML DocumentListing 2‑6 SOAP Message for an XML BufferThe XML Schema for <inbuf> is:For example, if an Oracle Tuxedo service returns a buffer having a default namespace to the GWWS server as shown in Listing 2‑7, the GWWS server converts the default namespace to a regular name as shown in Listing 2‑8.Listing 2‑7 Default Namespace Before Sending to GWWS ServerListing 2‑9 shows the MYVIEW VIEW definition file.Listing 2‑10 shows the SOAP message for the MYVIEW Oracle Tuxedo service, which accepts a VIEW typed buffer.Listing 2‑9 VIEW Definition File for MYVIEW ServiceListing 2‑10 SOAP Message for a VIEW Typed BufferListing 2‑11 XML Schema for a VIEW Typed Buffer
• You must create an environment for converting XML to and from VIEW/VIEW32. This includes setting up a VIEW directory and system VIEW definition files. These definitions are automatically loaded by the GWWS server.
• The GWWS server provides strong consistency checking between the Oracle Tuxedo Service Metadata Repository VIEW/VIEW32 parameter definition and the VIEW/VIEW32 definition file at start up.
• tmwsdlgen also provides strong consistency checking between the Oracle Tuxedo Service Metadata Repository VIEW/VIEW32 parameter definition and the VIEW/VIEW32 definition file at start up. If an inconsistency is found, the GWWS server will not start. Inconsistency messages are printed in the ULOG file.If the VIEW definition file cannot be loaded, tmwsdlgen attempts to use the Oracle Tuxedo Service Metadata Repository definitions to compose the WSDL document.
• Because dec_t is not supported, if you define VIEW fields with type dec_t, the service cannot be exported as a Web service and an error message is generated when the Oracle SALT configuration file is loading.
• The Oracle Tuxedo primary data type “long” is indefinite between 32-bit and 64-bit scope, depending on the platform. However, the corresponding xsd:long schema type is used to describe 64-bit numeric values.If the GWWS server runs in 32-bit mode, and the Web service client sends xsd:long typed data that exceeds the 32-bit value range, you may get a SOAP fault.Listing 2‑12 shows the SOAP message for the TRANSFER Tuxedo service, which accepts an FML typed buffer.The request fields for service LOGIN are:Listing 2‑12 SOAP Message for an FML Typed BufferListing 2‑13 XML Schema for an FML Typed BufferListing 2‑14 shows the SOAP message for the TRANSFER Oracle Tuxedo service, which accepts an FML32 typed buffer.The request fields for service LOGIN are:Each embedded CUST_INFO includes the following fields:Each embedded ACCOUNT_INFO includes the following fields:Listing 2‑14 SOAP Message for Service with FML32 BufferListing 2‑15 XML Schema for an FML32 BufferThe following considerations apply to converting Oracle Tuxedo FML/FML32 buffers to and from XML.
• You must create an environment for converting XML to and from FML/FML32. This includes an FML field table file directory and system FML field definition files. These definitions are automatically loaded by the GWWS. FML typed buffers can be handled only if the environment is set up correctly.
• FML32 Field type FLD_PTR is not supported.
• The GWWS server provides strong consistency checking between the Oracle Tuxedo Service Metadata Repository FML/FML32 parameter definition and FML/FML32 definition file during start up.If an FML/32 field is found that is not in accordance with the environment setting, or the field table field data type definition is different from the parameter data type definition in the Oracle Tuxedo Service Metadata Repository, the GWWS cannot start. Inconsistency messages are printed in the ULOG file.
• The tmwsdlgen command checks for consistency between the Oracle Tuxedo Service Metadata Repository FML/FML32 parameter definition and FML/FML32 definition file. If inconsistencies are found, it issue a warning and allow inconsistencies.If an FML/32 field is found that is not in accordance with the environment setting, or the field table field data type definition is different from the parameter data type definition in the Oracle Tuxedo Service Metadata Repository, tmwsdlgen attempts to use Oracle Tuxedo Service Metadata Repository definitions to compose the WSDL document.
• Oracle Tuxedo primary data type “long” is indefinite between 32-bit and 64-bit scope according to different platforms. But the corresponding xsd:long schema type is used to describe 64-bit numeric value. The following scenario generates a SOAP fault:The GWWS runs in 32-bit mode, and a Web service client sends a xsd:long typed data which exceeds the 32-bit value range.Oracle Tuxedo X_C_TYPE typed buffers are equivalent, and have a similar WSDL format to, Oracle Tuxedo VIEW typed buffers.They are transparent for SOAP clients. However, even though usage is similar to the Oracle Tuxedo VIEW buffer type, SALT administrators must configure the Oracle Tuxedo Service Metadata Repository for any particular Oracle Tuxedo service that uses this buffer type.
Note: Oracle Tuxedo X_OCTET typed buffers can only map to xsd:base64Binary type. SALT 1.1 does not support MIME attachment binding for Oracle Tuxedo X_OCTET typed buffers.XML Schema built-in type xsd:anyType is the corresponding type for XML documents stored in a SOAP message. While using custom typed buffers, you should define and represent the actual data into an XML format and transfer between the Web service client and Oracle Tuxedo Web service stack. As with XML typed buffers, only a single root XML buffer can be stored in the SOAP body. The GWWS checks this for consistency.Oracle SALT maps each wsdl:message as an Oracle Tuxedo FML32 buffer structure. Oracle SALT defines a set of rules for representing the XML Schema definition using FML32. To invoke external Web Services, customers need to understand the exact FML32 structure that converted from the external Web Service XML Schema definition of the corresponding message.The following sections describe detailed WSDL message to Oracle Tuxedo FML32 buffer mapping rules:Table 2‑3 shows the supported XML Schema Built-In Simple Data Type and the corresponding Oracle Tuxedo FML32 Field Data Type.
In a 32-bit Oracle Tuxedo program, the C primitive type long cannot represent all xsd:long valid value. In a 32-bit Oracle Tuxedo program, the C primitive type unsigned long cannot represent all xsd:long valid value.
<xsd:element name=”flag” type=”xsd:boolean” /> char c_flag;
FBFR32 * request;
...
c_flag = ‘T’; /* Set True for boolean data */
Fadd32( request, flag, (char *)&c_flag, 0);
<xsd:element name=”account” type=”xsd:unsignedInt” /> unsigned long acc;
FBFR32 * request;
...
acc = 102377; /* Value should not exceed value scope of unsigned int*/
Fadd32( request, account, (char *)&acc, 0);
<xsd:element name=”message” type=”xsd:string” />
<xsd:element name=”mem_snapshot” type=”xsd:hexBinary” /> FBFR32 * request;
FLDLEN32 len;
char * buf;
buf = calloc( ... );
...
memcpy(buf, “...”, len); /* copy the original memory */
Fadd32( request, mem_snapshot, buf, len);
<xsd:element name=”IssueDate” type=”xsd:date” /> FBFR32 * request;
char date[32];
...
strcpy(date, “2007-06-04+8:00”); /* Set the date value correctly */
Fadd32( request, IssueDate, date, 0);Table 2‑9 lists the supported XML Schema User Defined Simple Data Type and the corresponding Oracle Tuxedo FML32 Field Data Type.
<xsd:simpleType> derived from built-in primitive simple data types Facets defined with <xsd:restriction> are not enforced at Oracle Tuxedo side. <xsd:complexType> defined with shorthand <xsd:complexContent>, sub-elements composited with sequence or all
<xsd:element name=”Grade” type=”Alphabet” />
<xsd:simpleType name=”Alphabet”>
<xsd:restriction base=”xsd:string”>
<xsd:maxLength value=”1” />
<xsd:pattern value=”[A-Z]” />
</xsd:restriction>
</xsd:simpleType> char grade[2];
FBFR32 * request;
...
grade[0] = ‘A’; grade[1] = ‘\0’;
Fadd32( request, Grade, (char *)grade, 0);
<xsd:element name=”Users” type=”namelist” />
<xsd:simpleType name=”namelist”>
<xsd:list itemType=”xsd:NMTOKEN”>
</xsd:simpleType> char * user[5];
char users[...];
char * mbpacked;
FLDLEN32 mbsize = 1024;
FBFR32 * request;
...
sprintf(users, “<n1:Users xmlns:n1=\”urn:sample.org\”>”);
for ( i = 0 ; i < 5 ; i++ ) {
strcat(users, user[i]);
strcat(users, “ “);
}
strcat(users, “</n1:Users>“);
...
mbpacked = malloc(mbsize);
/* prepare mbstring*/
Fmbpack32(“utf-8”, users, strlen(users), mbpacked, &mbsize, 0);
Fadd32( request, Users, mbpacked, mbsize);Table 2‑12 lists the WSDL message mapping rules defined by Oracle SALT.
Table 2‑12 WSDL Message Mapping Rules <wsdl:input> message <wsdl:output> message Oracle Tuxedo Response Buffer with TPSUCCESS (Output buffer) <wsdl:fault> message Mapped as top level field in the Oracle Tuxedo FML32 buffer. Field type is the equivalent FML32 field type of the message part XML data type. (See Table 2‑3 and Table 2‑9) <faultcode> in SOAP 1.1 fault message <faultstring> in SOAP 1.1 fault message <faultactor> in SOAP 1.1 fault message <Code> in SOAP 1.2 fault message Mapped as a fixed top level FLD_FML32 field (Code) in the Oracle Tuxedo error buffer, which containing two fixed sub FLD_STRING fields (Value and Subcode): <Reason> in SOAP 1.2 fault message Mapped as a fixed top level FLD_FML32 field (Reason) in the Oracle Tuxedo error buffer, which containing zero or more fixed sub FLD_STRING field (Text): <Node> in SOAP 1.2 fault message <Role> in SOAP 1.2 fault message <detail> in SOAP fault message Mapped as a fixed top level FLD_FML32 field in the Oracle Tuxedo error buffer: Each message part defined in <wsdl:fault> Mapped as a sub field of “detail” field in the Oracle Tuxedo FML32 buffer. Field type is the equivalent FML32 field type of the message part XML data type. (See Table 2‑3 and Table 2‑9)