19 Configuring Tuxedo for Propagating ECID

This topic includes the following sections:

• Overview
  
• Configurations
  
• Tracing ECID with Tuxedo System
  

19.1 Overview

Tuxedo is enhanced to support ECID propagation from its 12c (12.1.1) release. The following figure illustrates, it supports the propagation of ECID across various Tuxedo boundaries.

Figure 19-1 ECID Propagation

With this feature enabled, as the receiving side, Tuxedo will check whether there is an ECID in each request call across boundaries. If yes, the received ECID will be propagated along the whole call path; otherwise, as the boundary node, the domain gateway will try to generate an ECID for this call and propagate it once correctly configured.

For a call initiated by a Tuxedo component, say, a native client, a WS client, or a Jolt client, the client can generate an ECID for it once correctly configured.

Note:

JCA support is not in the scope of this feature.

This section describes following four scenarios of ECID propagation.

• Propagating ECID from Tuxedo to Database
  
• Propagating ECID Between Tuxedo and WLS
  
• Propagating ECID within Tuxedo
  
• Generating ECID by Native/WS/Jolt clients and Domain Gateway
  
• Interoperability
  

19.1.1 Propagating ECID from Tuxedo to Database

Tuxedo supports to propagate the ECID to Oracle DB via Oracle Call Interface (OCI). This is a one-way propagation. Since the OCI/DB never initiates a request call in theory, it’s not necessary to support the propagation in opposite direction (from DB to Tuxedo).

The OCI provides a registration API and a callback function interface. The implementation of the callback function handles the details of propagation. The process is showed as below:

1. When a tuxedo server process is up and with ECID enabled, it will call the registration API to register the implementation of the callback function.
2. OCI invokes the callback function and passes the relative context which can be used to identify the DB connection/session before a roundtrip.
3. The callback implementation gets the associated ECID from Tuxedo context and passes such ECID to Oracle DB.

19.1.2 Propagating ECID Between Tuxedo and WLS

WTC provides interoperability between WLS applications and Tuxedo services. As an interface, WTC takes full responsibility of ECID’s propagation between Tuxedo and WLS.

• For a request call from WLS to Tuxedo, the process is:
  1. WTC sets the ECID into the special field of the message.
  2. WTC sends the message to Tuxedo.
  3. Tuxedo domain gateway gets the ECID from received message.
• For a request call from Tuxedo to WLS, the process is:
  1. Tuxedo domain gateway sends the message with ECID to WTC.
  2. WTC gets the ECID from received message.
  3. WTC sets the ECID for current Execution Context.

ECID can also be propagated between Tuxedo and WLS^* when using Web Services through the SALT gateway (GWWS), either in SOAP or REST mode, and regardless of direction (Tuxedo calling WLS or WLS calling Tuxedo). In this mode, the ECID will be included in an HTTP header in the same manner as WLS^* uses to propagate ECID contexts with other Oracle products.

Note:

^*WLS should be WLS 12c (12.1.3) or higher releases of WLS.

19.1.3 Propagating ECID within Tuxedo

The ECID propagation within Tuxedo (both intra-domain and across domains) utilizes the META_TCM field in the messages. Tuxedo client, server, and domain gateway are all enhanced to support to get or set ECID in META_TCM section of a message.

Inside the Tuxedo, the ECID generation/propagation happens with following three ATMI APIs:

• tpcall
• tpacall
• tpforward

19.1.4 Generating ECID by Native/WS/Jolt clients and Domain Gateway

As boundary components, native/WS/Jolt client and domain gateway can generate the ECID for each request message once configured correctly.

19.1.5 Interoperability

If there is a domain/machine with an Oracle Tuxedo version lower than 12c in the call path, the end-to-end ECID propagation depends on specific user scenarios.

For example, let's consider the following interoperability scenario.

There are three domains: DOM1, DOM2 and DOM3. DOM1 and DOM3 are in Oracle Tuxedo 12c, DOM2 is in Tux11gR1; DOM1 enables both ECID_USERLOG and ECID_CREATE but DOM3 only enables ECID_USERLOG.

On one hand, if client on DOM1 invokes tpcall service1 on DOM2 and then service1 invokes tpcall service2 on DOM3 (allocating a new buffer via tpalloc), ECID will not be found in DOM3's ULOG. Thus, ECID information from DOM1 cannot be kept.

On the other hand, if client on DOM1 invokes tpcall service1 on DOM2 and then service1 invokes tpcall service2 on DOM3 (reusing the buffer with which service1 is invoked), ECID will be found in DOM3's ULOG. Thus, ECID information from DOM1 can be propagated and retrieved by DOM3.

19.2 Configurations

This section covers the following configurations to enable ECID propagation:

• Enabling and Disabling ECID Propagation
  
• Configuring the Server to Propagate ECID via OCI
  

19.2.1 Enabling and Disabling ECID Propagation

In RESOURCES section of UBBCONFIG(5), the OPTIONS field is extended with new flags to enable and specify the behavior for handling the ECID.

Option 'ECID_CREATE': ECID creation functionality is enabled. The boundary nodes (including Native/WS/Jolt client and domain gateway) can generate the ECID.

Option 'ECID_USERLOG': With this option on, if not a null string, the ECID will be appended to the userlog.

If neither of above options is set, the ECID propagation around Tuxedo is enabled by default, but ECID can neither be created nor printed in ULOG in this domain. In such scenario, " tmadmin > psr -v" can be used to get the ECID. The two of above options can also be updated by MIB operation.

19.2.2 Configuring the Server to Propagate ECID via OCI

To perform ECID propagation to Oracle DB via OCI callback functions, the related server must be specified by a “-L” option. For example:

simpserv CLOPT="-A -L default --" SRVGRP=GROUP1 SRVID=2

Once activated with a specified "–L", a server will call the registration API of OCI for ECID propagation.

-LD or -L default

Loads default OCI library, that is, "oci.dll" for WIN32 platform and "libclntsh.so" for other platforms.

-L oci_lib_name

Loads the OCI library with the name specified by oci_lib_name. Such oci_lib_name can be an absolute path or a leaf name, which can be found through the system library path.

19.3 Tracing ECID with Tuxedo System

The userlog is enhanced to print out the ECID of current active call if 'ECID_USERLOG' is configured in UBBCONFIG. For example:

233331.myhost!simpserv.19461.2664420416.0: ECID <004fVWEOfCE6iKO5IjK6yf0004k8000000>: sleep 15

The tmadmin printserver (psr -v) command is enhanced to print out ECID if the server is currently in service. For example:

   Group ID: GROUP1, Server ID: 1
   Machine ID: SITE1
   Process ID: 19461, Request Qaddr: 1009713159, Reply Qaddr: 1009713159
   Server Type: USER
   Prog Name: 
../samples/atmi/simpapp/simpserv

   Queue Name: 00001.00001
      Options: ( none )
   Generation: 1, Max message type: 1073741824
Creation time: Tue Sep 27 23:32:44 2011
      Up time: 0:05:22
Requests done: 2
   Load done: 100
Current Service: TOUPPER,(ecid: 
c9ca469656eb23b5:79482783:132ae1bef3b:-8000-0000000000000010)

See Also:

File Formats, Data Descriptions, MIBs, and System Processes Reference