16 Managing Remote Oracle Tuxedo CORBA Client Applications

This topic contains the following sections:

• Introduction to Managing Remote Oracle Tuxedo CORBA Client Applications
  
• CORBA Object Terminology
  
• Remote CORBA Client Overview
  
• Setting Environment Variables for Remote CORBA Clients
  
• Setting the Maximum Number of Remote CORBA Clients
  
• Configuring a Listener for a Remote CORBA Client
  
• Modifying the Configuration File to Support Remote CORBA Clients
  
• Configuring Outbound IIOP for Remote Joint Client/Servers
  
• Using the ISL Command to Configure Outbound IIOP Support
  
• Applying Service Version to Tuxedo Applications
  

16.1 Introduction to Managing Remote Oracle Tuxedo CORBA Client Applications

This chapter explains how to configure connections from remote Oracle Tuxedo CORBA client applications to CORBA objects via the standard Internet Inter-ORB Protocol (IIOP). This chapter is specific to Oracle Tuxedo CORBA servers.

Note:

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated since Tuxedo 8.1 and are no longer supported since Tuxedo 9.x. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, etc. must only be used:

• to help implement/run third party Java ORB libraries, and
• for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

This topic includes the following sections:

16.2 CORBA Object Terminology

The following terms are used in this chapter.

DLL

Dynamic Link Libraries. A DLL is a collection of functions grouped into a load module that is dynamically linked with an executable program at run time for a Windows application.

IIOP

Internet Inter-ORB Protocol (IIOP). IIOP is basically TCP/IP with some COBRA-defined message exchanges that serve as a common backbone protocol.

ISH

IIOP Server Handler. This is a client process running on an application site that acts as a surrogate on behalf of the remote client.

ISL

IIOP Server Listener. This is a server process running on an application site that listens for remote clients requesting connection.

Server

A server hosted on a machine in an Oracle Tuxedo domain. An Oracle Tuxedo CORBA server is built with the Oracle Tuxedo CORBA buildobjserver command. CORBA Servers implement Oracle Tuxedo functionality, such as security, transactions, and object state management. Servers can make invocations on any server, inside or outside an Oracle Tuxedo domain.

Native Client

A client located within an Oracle Tuxedo domain, using the CORBA ORB to make invocations on objects either inside or outside the Oracle Tuxedo domain. A native client’s host contains the Oracle Tuxedo administrative and infrastructure components, such as tmadmin, FactoryFinder, and ISL/ISH. Native clients use the environmental objects to access CORBA objects. You build native C++ clients with the buildobjclient command or native Java clients using the tools provided by the third-party ORB.

Remote Client

A client not located within an Oracle Tuxedo domain. A remote client can use the CORBA ORB to make invocations on objects either inside or outside the Oracle Tuxedo domain. A remote client’s host does not contain Oracle Tuxedo administrative and infrastructure components, such as tmadmin, FactoryFinder, and ISL/ISH; it does contain supporting software (the CORBA ORB) that allows remote clients to invoke objects. Remote clients use the environmental objects to access CORBA objects. You build remote C++ clients with the buildobjclient command or remote Java clients using the tools provided by the third-party ORB.

Native Joint Client/server

A process that has two purposes:

1. execute code acting as the starter for some business actions.
2. execute method code for invocations on objects. A joint client/server located within an Oracle Tuxedo domain. You build native joint C++ client/servers with the buildobjclient command. Java native joint client/servers are not supported.

Note:

The server role of the native joint client/server is considerably less robust than that of a server. It has none of the Oracle Tuxedo CORBA administrative and infrastructure components, such as tmadmin, FactoryFinder, and ISL/ISH (hence none of Oracle Tuxedo’s scalability and reliability attributes), it does not use the Oracle Tuxedo TP Framework, and it requires more direct interaction between the client and the ORB.

Remote Joint Client/server

A process that has two purposes:

1. execute code acting as the starter for some business actions
2. execute method code for invocations on objects. A joint client/server located outside an Oracle Tuxedo domain. The joint client/server does not use the Oracle Tuxedo TP Framework and requires more direct interaction between the Client and the ORB. You build remote joint C++ client/servers with the buildobjclient command or remote Java client/servers using the tools provided by the third-party ORB.

Note:

A joint client/server is different from a server that acts as a client as part of its server role. Once the server completes processing of an invocation, it returns to dormancy. A joint client/server is always in the active mode, executing code not related to a server role; the server role temporarily interrupts the active client role, but the client role is always resumed.

The server role of the remote joint client/server is considerably less robust than that of a server. Neither the client nor the server has any of the Oracle Tuxedo administrative and infrastructure components, such as tmadmin, FactoryFinder, and ISL/ISH (hence, none of Oracle Tuxedo’s scalability and reliability attributes).

Oracle Tuxedo CORBA object

A CORBA object that is implemented using TP Framework and that implements security, transactions, and object state management. CORBA objects are implemented in Oracle Tuxedo CORBA servers; that is, they are part of an Oracle Tuxedo domain and use the Oracle Tuxedo infrastructure.

Callback Object

A CORBA object supplied as a parameter in a client’s invocation on a target object. The target object can make invocations on the callback object either during the execution of the target object or at some later time (even after the invocation on the target object has been completed). A callback object might be located inside or outside an Oracle Tuxedo domain.

16.3 Remote CORBA Client Overview

In this section, the term “remote client” represents a CORBA client application that is deployed on systems that do not have the full Oracle Tuxedo CORBA server software installed. This means that no administration or application servers are running there and that no bulletin board is present. All communication between the client and the application takes place over the network.

The types of clients are:

• CORBA C++ client

  A client process can run on UNIX or Microsoft Windows. The client has access to the CORBA ORB interface. The networking behind the calls is transparent to the user. The client process registers with the system and has the same status as a native client.

  The client can do the following:

• Invoke methods on remote CORBA objects
• Begin, roll back, or commit transactions
• Be required to pass application security

Note:

A client process communicates with the native domain through the ISH.

• Illustration of an Application with Remote CORBA Clients
  
• How the Remote Client Connects to an Application
  

16.3.1 Illustration of an Application with Remote CORBA Clients

The following figure shows an example of an application with remote clients connected. Any request by a remote client to access the CORBA server application is sent over the network to the ISH. This process sends the request to the appropriate server and sends the reply back to the remote client.

Figure 16-1 Bank Application with Remote Clients

16.3.2 How the Remote Client Connects to an Application

The client connects to the ISL process in the IIOP Listener/Handler using a known network address. This is initiated when the client calls the Bootstrap object constructor. The ISL process uses a function that is specific to the operating system to pass the connection directly to the selected ISH process. To the client application, there is only one connection. The client application does not know, or need to know, that it is now connected to the ISH process.

16.4 Setting Environment Variables for Remote CORBA Clients

For CORBA C++ clients, environment variables can be used to pass information to the system, as follows:

• TUXDIR—the location of the Oracle Tuxedo CORBA client software on this remote client. It must be set for the client to connect.
• TOBJADDR—the network address of the ISL that the client wants to contact. This must match the address of an ISL process as specified in the application configuration file.

Note:

The network address that is specified by programmers in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the server application’s UBBCONFIG file. The format of the address as well as the capitalization must match. If the addresses do not match, the call to the Bootstrap constructor will fail with a seemingly unrelated error message:

ERROR: Unofficial connection from client at
<tcp/ip address>/<port-number>:

For example, if the network address is specified as //TRIXIE:3500;TLSv1.2 in the ISL command line option string (in the server application’s UBBCONFIG file), specifying either //192.12.4.6:3500;TLSv1.2 or //trixie:3500;TLSv1.2 in the Bootstrap constructor or in TOBJADDR will cause the connection attempt to fail.

On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Windows systems, see the host system's Network control panel to determine the capitalization used. Or use the environment variable COMPUTERNAME. For example:

echo %COMPUTERNAME%

16.5 Setting the Maximum Number of Remote CORBA Clients

To join remote clients to an application, you must specify the MAXWSCLIENTS parameter in the MACHINES section of the UBBCONFIG file.

MAXWSCLIENTS tells the Oracle Tuxedo system at boot time how many accesser slots to reserve exclusively for remote clients. For native clients, each accesser slot requires one semaphore. However, the ISH process (executing on the native platform on behalf of remote clients) multiplexes remote client accessers through a single accesser slot and, therefore, requires only one semaphore. This points out an additional benefit of the remote extension. By putting more clients out on remote systems and taking them off the native platform, an application reduces its IPC resource requirements.

MAXWSCLIENTS takes its specified number of accesser slots from the total set in MAXACCESSERS. This is important to remember when specifying MAXWSCLIENTS; enough slots must remain to accommodate native clients as well as servers. Do not specify a value for MAXWSCLIENTS greater than MAXACCESSERS. The following table describes the MAXWSCLIENTS parameter.

Parameter	Description
MAXWSCLIENTS	Specifies the maximum number of remote clients that may connect to a machine. The default is 0. If a value is not specified, remote clients may not connect to the machine being described. The syntax is MAXWSCLIENTS=number.

16.6 Configuring a Listener for a Remote CORBA Client

Remote clients access your application through the services of an ISL process and one or more ISH processes. The ISL is specified in one entry as a server supplied by the <Default ? Font>Oracle Tuxedo system. The ISL can support multiple remote clients and acts as the single point of contact for all the remote clients connected to your application at the network address specified on the ISL command line. The listener schedules work for one or more remote handler processes. An ISH process acts as a surrogate within the administrative domain of your application for remote clients on remote systems. The ISH uses a multiplexing scheme to support multiple remote clients concurrently.

To join remote clients to an application, you must list the ISL processes in the SERVERS section of the UBBCONFIG file. The processes follow the same syntax for listing any server.

• Format of the CLOPT Parameter
  

16.6.1 Format of the CLOPT Parameter

You use the following ISL command-line options (CLOPT) to pass information to the ISL process for remote clients. The format of the CLOPTparameter is as follows:

ISL SRVGRP=”identifier”
    SRVID="number"
    CLOPT="[ -A ] [ servopts options ] -- -n netaddr
           [ -C {detect|warn|none} ]
           [ -d device ]
           [ -K {client|handler|both|none} ]
           [ -m minh ]
           [ -M maxh ]
           [ -T client-timeout]
           [ -x mpx-factor ]
           [ -H external-netaddr"

For a detailed description of the CLOPT command line options, see the ISL command in the Oracle Tuxedo Command Reference

16.7 Modifying the Configuration File to Support Remote CORBA Clients

The following Listing shows a sample UBBCONFIG file to support remote clients:

• The MACHINES section shows the default MAXWSCLIENTS as being overridden for two sites. For SITE1, the default is raised to 150, while it is lowered to 0 for SITE2, which does not have remote clients connected to it.
• The MACHINES section shows the default MAXWSCLIENTS as being overridden for two sites. For SITE1, the default is raised to 150, while it is lowered to 0 for SITE2, which does not have remote clients connected to it.
• The SERVERS section shows an ISL process listed for group BANKB1. Its server ID is 500 and it is marked as restartable.
• The command line options show the following:
  • The IIOP Listener/Handler will advertise all of its services (-A).
  • The IIOP Listener/Handler will listen at host TRIXIE on port 2500.
  • The network provider is /dev/tcp (-d).
  • The minimum number of ISH processes to boot is 5 (-m).
  • The maximum number of ISH processes to boot is 30 (-M).
  • Each handler can have a maximum of 5 clients connected at any one time (-x).

Listing Sample UBBCONFIG File Configuration

*MACHINES
SITE1
                ...
                MAXWSCLIENTS=150
                ...
SITE2
                ...
                MAXWSCLIENTS=0
                ...
*SERVERS
                ...
ISL SRVGRP=”BANKB1" SRVID=500 RESTART=Y
           CLOPT=”-A -- -n //TRIXIE:2500 -d /dev/tcp
                  -m 5 -M 30 -x 5"
           ..

16.8 Configuring Outbound IIOP for Remote Joint Client/Servers

Support for outbound IIOP provides native clients and servers acting as native clients the ability to invoke on a remote object reference outside of the Oracle Tuxedo domain. This means that calls can be invoked on remote clients that have registered for callbacks, and objects in remote servers can be accessed.

Administrators are the only users who interact directly with the outbound IIOP support components. Administrators are responsible for booting the ISLs with the correct startup parameters to enable outbound IIOP to objects not located in a connected client. Administrators may need to adjust the number of ISLs they boot and the various startup parameters to obtain the best configuration for their installation’s specific workload characteristics.

Administrators have the option of booting the ISLs with the default parameters. However, the default Oracle Tuxedo ISL startup parameters do not enable use of outbound IIOP.

Note:

Outbound IIOP is not supported for transactions or security.

• Functional Description
  

16.8.1 Functional Description

Outbound IIOP support is required to support client callbacks. In Oracle WebLogic Enterprise versions 4.0 and 4.1, the ISL/ISH was an inbound half-gateway. Outbound IIOP support adds the outbound half-gateway to the ISL/ISH. (See the following figure.)

There are three types of outbound IIOP connections available, depending on the version of GIOP supported by the native server and the remote joint client/server application:

• Bidirectional—outbound IIOP reusing the same connection (supported only for Oracle WebLogic Enterprise release 4.2 or later C++ GIOP 1.2 servers, clients, and joint client/servers)
• Asymmetric—outbound IIOP via a second connection (supported for GIOP 1.0, GIOP 1.1, and GIOP 1.2 servers, clients, and joint client/server applications)
• Dual-paired connection—outbound IIOP (supported for GIOP 1.0, GIOP 1.1, and GIOP 1.2 servers, clients, and joint client/server applications)

Note:

GIOP 1.2 is supported only by Oracle WebLogic Enterprise release 4.2 (and later) and Oracle Tuxedo release 8.0 (and later) C++ clients, servers, and joint client/servers. Oracle WebLogic Enterprise releases 4.0 and 4.1 C++ clients and servers support GIOP versions 1.0 and 1.1, but not GIOP 1.2. Java clients, servers, and joint client/servers only support GIOP 1.0.

Bi-directional and dual-paired connection outbound IIOP provides outbound IIOP to object references located in joint client/servers connected to an ISH. Asymmetric outbound IIOP provides outbound IIOP to object references not located in a joint client/server connected to an ISH, and also allows Oracle Tuxedo CORBA clients to invoke on any object reference, not only object references located in clients currently connected to an ISH.

Each type of outbound IIOP is described in more detail in the following sections.

Figure 16-2 Joint Client/Server IIOP Connections Supported

• Bidirectional Outbound IIOP
  
• Asymmetric Outbound IIOP
  
• Dual-paired Connection Outbound IIOP
  
• How the Routing Code Finds an ISL
  

16.8.1.1 Bidirectional Outbound IIOP

With bidirectional outbound IIOP, the following operations are executed (see the following figure):

1. A client creates an object reference and invokes on a Oracle Tuxedo CORBA server. The client ORB identifies the connection as being bidirectional using the service context. The service context travels with the message to the Oracle Tuxedo CORBA server.
2. When unmarshaling the object reference, the Oracle Tuxedo CORBA server compares the host/port in the service context with the host/port in the object reference. If they match, the ORB adds the ISH client information needed for routing to the ISH. This client information travels with the object reference whenever it is passed to other Oracle Tuxedo CORBA servers.
3. At some point in time, an Oracle Tuxedo CORBA server or native client invokes on the object reference, and the routing code invokes on the appropriate ISH, given the client information.
4. The ISH sends the request to the client over the same client connection.
5. The client executes the method and sends the reply back to the ISH via the client connection.
6. The ISH receives the reply and sends it to the Oracle Tuxedo CORBA server.

Figure 16-3 Bidirectional Connection

16.8.1.2 Asymmetric Outbound IIOP

With asymmetric outbound IIOP, the following operations are executed (see the following figure):

1. A server gets an object reference from some source. It could be a naming service, a string_to_object, or it could be passed in through a client, but not located in that client. Since the object reference is not located in a client connected to an ISH, the outgoing call cannot be made using the bidirectional method. The Oracle Tuxedo CORBA server invokes on the object reference.
2. On the first invoke, the routing code invokes a service in the ISL and passes in the host/port.
3. The ISL selects an ISH to handle the outbound invoke and returns the ISH information to the Oracle Tuxedo CORBA server.
4. The Oracle Tuxedo CORBA server invokes on the ISH.
5. The ISH determines which outgoing connection to use to send the request to the client. If none is connected, the ISH creates a connection to the host/port.
6. The client executes the method and sends the reply back to the ISH.
7. The ISH receives the reply and sends it to the Oracle Tuxedo CORBA server.

Figure 16-4 Asymmetric Outbound IIOP

16.8.1.3 Dual-paired Connection Outbound IIOP

With dual-paired connection outbound IIOP, the following operations are executed (see the following figure):

1. A client creates an object reference and calls the Bootstrap function (register_callback_port) and passes the object reference.
2. The ISH gets the host/port from the IOR and stores it with the client context.
3. The client invokes on an Oracle Tuxedo CORBA server and passes the object reference. From the register_callback_port call, the ISH creates a service context containing the host/port. The service context travels with the message to the Oracle Tuxedo CORBA server.
4. When unmarshaling the object reference, the Oracle Tuxedo CORBA server compares the host/port in the service context with the host/port in the object reference. If they match, the ORB adds the ISH client information to the object reference. This client information travels with the object reference whenever it is passed to other Oracle Tuxedo CORBA servers.
5. At some point in time, an Oracle Tuxedo CORBA server or native client invokes on the object reference. The routing code invokes on the appropriate ISH, passing the client information.
6. The ISH creates a second connection to the client. It sends the request to the client over the second connection.
7. The client executes the method and sends the reply back to the ISH via the first client connection.
8. The ISH receives the reply and sends it to the Oracle Tuxedo CORBA server. If the client disconnects from the ISH, the second connection is also disconnected.

Figure 16-5 Dual-paired Connections Outbound IIOP

16.8.1.4 How the Routing Code Finds an ISL

The steps to finding an ISL are as follows:

1. A service is advertised in each ISL.
2. The routing code invokes on that service name.
3. Normal Oracle Tuxedo routing is used to find an ISL.
4. An idle ISL on the same machine is always chosen, if available. If not available, NETLOAD ensures that a local ISL is chosen most often.

Note:

Some invokes may be made to ISLs on nonlocal machines.

16.9 Using the ISL Command to Configure Outbound IIOP Support

Outbound IIOP support is used when a native C++ or Java client, or a server acting as a native client, invokes on an object reference that is a remote object reference. The routing code recognizes that the object reference is from a non-Oracle Tuxedo CORBA ORB or from a remote Oracle Tuxedo CORBA joint client/server.

• Types of Object References
  
• User Interface
  

16.9.1 Types of Object References

There are two kinds of remote object references:

• Object references created by Oracle Tuxedo CORBA remote joint client/servers outside of the <Default ? Font>Oracle Tuxedo domain
• Object references created by other vendors’ servers.

Both are detected by the routing code and sent to the outbound IIOP support for handling.

16.9.2 User Interface

The user interface to outbound IIOP support is the command line interface for booting the ISL process(es). New command-line options to configure the outbound IIOP processing were added to the ISL command in this release of the Oracle Tuxedo software. These options enable support for asymmetric IIOP to object references not located in clients connected to an ISH.

The ISL command syntax listed below shows the new options for outbound IIOP support:

ISL SRVGRP="identifier"   
   
    SRVID="number"
    CLOPT="[ -A ] [ servopts options ] -- -n netaddr  
           [ -C {detect|warn|none} ]  
           [ -d device ]
           [ -K {client|handler|both|none} ]
           [ -m minh ]
           [ -M maxh ]
           [ -T Client-timeout]
           [ -x mpx-factor ]
           [-H external-netaddr]
#NEW options for outbound IIOP
           [-O]
           [-o outbound-max-connections]
           [-s Server-timeout]
           [-u out-mpx-users] "

For a detailed description of the CLOPT command-line options, see the ISL command in the Oracle Tuxedo Command Reference.

16.10 Applying Service Version to Tuxedo Applications

• Overview
  
• Enabling and Disabling Application Service Versioning
  
• UBB Config File Application Service Version Configuration
  
• Domain Configuration File Application Service Version Configuration
  

16.10.1 Overview

It is common that the user wants to keep existing functionality but also want to add new functionality into a service as time going. To reduce the compatible risk, it had better to provide two different version services with the same service name, one for old functionality, and one for new functionality. The old client can still use the existing functionality without any code change while the new client can use the new functionality.

The application service version feature offer a configuration driven way which can be used by Tuxedo customers to plan, develop, test, scale, and deploy their Tuxedo applications in each stage. The user can use the version to partition current Tuxedo application into different virtual application domains, different virtual machines, and different virtual server groups on current Tuxedo management hierarchy. It provide a flexible method to let customers setup their application zone according to a defined version (from this perspective, version can be endowed a new meaning: logical partition identity) to respond all kinds of special business access logic, and on the other hand customers can use version to solve some upgrading requirements in non-stop mode and change the service business logic seamlessly for the end users.

16.10.2 Enabling and Disabling Application Service Versioning

You can enable/disable the application service version feature in UBB configuration file or through MIB.

• Enable/Disable Application Service Version Using UBB Config File
  
• Enable/Disable Application Service Versioning Using MIB
  

16.10.2.1 Enable/Disable Application Service Version Using UBB Config File

To enable the application service version, add the APPVER option to the OPTIONS parameter in *RESOURCES section. For example:

*RESOURCES 
OPTIONS       APPVER, LAN

To disable the application service version, remove the APPVER option from the OPTIONS parameter in *RESOURCES section. For example:

*RESOURCES 
OPTIONS     LAN

Note:

If the application version is disabled, the user cannot configure the application service version related configuration in the*RESOURCE and * GROUP sections.

16.10.2.2 Enable/Disable Application Service Versioning Using MIB

To enable the application service versioning in MIB, add the APPVER option to TA_OPTIONS in the T_DOMAIN class.

For example:

SRVCNM     .TMIB
TA_OPERATION   SET
TA_CLASS       T_DOMAIN
TA_OPTIONS     APPVER,LAN

To disable the application service versioning in MIB, remove the APPVER option from TA_OPTIONS in the T_DOMAIN class.

For example:

SRVCNM     .TMIB
TA_OPERATION   SET
TA_CLASS       T_DOMAIN
TA_OPTIONS     LAN

Note:

Before disabling the application service versioning, you should remove the application service versioning related options that were already configured in MIB. For more information, see Resetting the User Configured Service Version Information Using MIB.

16.10.3 UBB Config File Application Service Version Configuration

Three attributes (REQUEST_VERSION, VERSION_POLICY and VERSION_RANGE), are used in configuration files to specify what version and what allowable version range in a configured Tuxedo management entity. These three attributes can be configured in the *GROUP and *RESOUCEsection of the UBB Config File as shown in the following figure.

For more information, see UBBCONFIG(5), Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference in the Oracle Tuxedo Reference Guide.

Listing UBB Config File Application Service Version Configuration

*RESOUCE
DOMAINID LOCALDOM
OPTIONS LAN,APPVER
REQUEST_VERSION 1 VERSION_RANGE "1-2"
*GROUP
GRP1 GRPNO=1 REQUEST_VERSION=2 VERSION_POLICY="PROPAGATE"
GRP2 GRPNO=2 VERSION_RANGE="3-4"
GRP3 GRPNO=3 REQUEST_VERSION=3 VERSION_RANGE="1-3"
DMGRP GRPNO=4 LMID=SITE1
GWGRP GRPNO=5 LMID=SITE1
WSGRP GRPNO=6 LMID=SITE1 REQUEST_VERSION=4
JGRP GRPNO=7 LMID=SITE1 REQUEST_VERSION=3
*SERVER
SERVER1 SVRGRP=GRP1
SERVER2 SVRGRP=GRP2
SERVER3 SVRGRP=GRP3
DMADM SRVGRP=DMGRP
GWADM SRVGRP=GWGRP
GWTDOMAIN SRVGRP=GWGRP
WSL SRVGRP=WSGRP
JSL SRVGRP=JGRP

server1 advertises SVC2, SVC3. Because server1 belongs to GRP1, the REQUEST_VERSION of the server1, SVC2, SVC3 is inherited from GRP1. The configured REQUEST_VERSION of the GRP1 is 2, so REQUEST_VERSION of the server1, SVC2, SVC3 is 2.

The VERSION_RANGE, VERSION_POLICY of SVC2, SVC3 are inherited from GRP1. There is no configured VERSION_RANGE for GRP1, so it inherit from the *RESOURCE section, which is "1-2"

The VERSION_POLICY of SVC2, SVC3 are inherited from GRP1. The configured VERSION_POLICY of GRP1 is PROPAGATE, so the VERSION_POLICY of SVC2, SVC3 is PROPAGATE.

server2 advertises SVC1, SVC2, SVC3. According to the same rule described for server1, the REQUEST_VERSION of server2, SVC1, SVC2, SVC3 is1, the VERSION_RANGE of SVC1, SVC2, SVC3 are "3-4", the VERSION_POLICY of the SVC1, SVC2, SVC3 is non-PROPAGATE.

server3 advertises SVC1, SVC2. According to the same rule described for server1, the REQUEST_VERSION of the server3, SVC1, SVC2 is 3, the VERSION_RANGE of SVC1, SVC2 are "1-3", the VERSION_POLICY of the SVC1, SVC2 is non-PROPAGATE.

If a native client joins the application without specifying the group name, its REQUEST_VERSION is 1.

If a native client joins the application with a specific group name, such as GRP3, its REQUEST_VERSION is 3.

If a /WS client joins the application, its REQUEST_VERSION is determined by the WSL, whose REQUEST_VERSION is 4 according to the UBB config file. So the REQUEST_VERSION of the /WS client is 4.

If a JOLT client joins the application, its REQUEST_VERSION is determined by the JSL, whose REQUEST_VERSION is 3 according to the UBB config file. So the REQUEST_VERSION of the /WS client is 4.

16.10.4 Domain Configuration File Application Service Version Configuration

The following Listing shows a domain configuration file application service configuration example.

Listing Domain Configuration File Application Service Version Configuration

*DM_LOCAL
LOCALDOM TYPE=TDOMAIN
DOMAINID="LOCALDOM"
*DM_REMOTE
REMOTEDOM1 TYPE=TDOMAIN
DOMAINID= "DOM1" MTYPE="Linux"
REMOTEDOM2 TYPE=TDOMAIN
DOMAINID= "DOM2" MTYPE="Linux"
REQUEST_VERSION=4
*DM_IMPORT
R_SVC1 RDOM= REMOTEDOM1 VERSION_RANGE="1-3"
R_SVC2 RDOM= REMOTEDOM2 VERSION_RANGE="4-6"
R_SVC3 RDOM= REMOTEDOM2

No REQUEST_VERSION is configured forREMOTEDOM1, so the domain gateway will propagate the request version of all the requests come from REMOTEDOM1, i.e the domain gateway will not change the incoming request version.

The REQUEST_VERSION of the REMOTEDOM2 is configured as 4, so the domain gateway will change the request version of all the requests come from REMOTEDOM2 to 4.

TheLOCALDOM import R_SVC1 service from REMOTEDOM1 and specify the VERSION_RANGE as "1-3". So the VERSION_RANGE of the R_SVC1 service in theLOCALDOM is "1-3".

The LOCALDOM import R_SVC2 service from REMOTEDOM2 and specify the VERSION_RANGE as "4-6". So the VERSION_RANGE of the R_SVC2 service in the LOCALDOM is "4-6".

The LOCALDOM import R_SVC3 service without specified VERSION_RANGE. Because the VERSION_RANGE of the imported service is still determined by VERSION_RANGE configuration of the *GROUP and *RESOURCE, the VERSION_RANGE of the *RESOUCE is "1-2", so the VERSION_RANGE of R_SVC3 is "1-2".

For more information, see UBB Config File Application Service Version Configuration.

• Version Based Routing
  
• Resetting the User Configured Service Version Information Using MIB
  

16.10.4.1 Version Based Routing

When the application service feature is enabled, the system dispatches the request to the service according to both the service name and the version range of the service. We call the this mechanism as Version Based Routing (VBR). When a service entry matching the requested service name is found, the VBR is used to further routing decision.

VBR only does a simple numeric comparison using current request version number with the two boundary values of version range. VBR return "no entry is found" error to the caller when all of services with matching name are not allowable for this versioned request.

Tuxedo already offers several routing mechanisms: DDR (Data Dependent Routing), TAR (Transaction Affinity Routing), and RAR (Request Affinity Routing). VBR (Version Based Routing) is also a new routing mechanism that can owns same functions as these of existing routing algorithms.

VBR can be used together with the other routing mechanisms; Tuxedo will choose the services that match all criteria if there are multiple routing mechanisms. But the user had better to understand how the interaction among these routing mechanisms if use them together.

Suppose the configuration describe as above section.

1. If server3 needs to call SVC2 during its initialization period, The REQUEST_VERSION of server3 is 3, the candidate services are:

   Server1:SVC2 1-2
   Server2:SVC2 3-4

   So server3 will call Server2:SVC2.
2. If the native client need to call SVC3, the REQUEST_VERSION of the native client is 1, the candidate services are:

   Server1:SVC1 1-2
   Server2:SVC1 3-4

   Server2:SVC1 3-4So the native client will call Server1:SVC1
3. If Server1:SVC1 needs to call SVC3, the SVC1 will propagate the incoming REQUEST_VERSION, in this case the incoming REQUEST_VERSION is 1, so the current REQUEST_VERSION of Server1:SVC1 is 1, the candidate services are:

   Server2:SVC3 3-4
   Server3:SVC3 1-3

   Server3:SVC3 1-3 So Server1:SVC1calls Server3:SVC3
4. If a request come from REMOTEDOM2, suppose the original REQUEST_VERSION is 6, then the REQUEST_VERSION of the incoming request is changed to 4.
5. If a request comes from REMOTEDOM1, suppose the original REQUEST_VERSION is 2, then the REQUEST_VERSION of the incoming request will still be 2.

16.10.4.2 Resetting the User Configured Service Version Information Using MIB

You can configure REQUEST_VERSION, VERSION_RANGE, and VERSION_POLICY in the *GROUPS or *RESOURCES section of UBB config file. The low-level configuration overrides the high level-configuration.

If there is no user-configured service version configuration at any level, the system uses the default value. That causes the result very different for the user configured configuration and default value. If you modify the REQUEST_VERSION, VERSION_RANGE or VERSION_POLICY using MIB, it is the user-configured service version configuration. It is necessary to provide a method to reset this modification to the default value using MIB, otherwise you cannot restore the UBB config file to its original state through MIB operation.

To reset the REQUEST_VERSION, VERSION_RANGE, and VERSION_POLICY to default value, you just need to simply set value as DEFAULT.

For example, modify the REQUEST_VERSION in MIB as shown in the following Listing.

Listing Resetting the User Configured Service Version Information Using MIB

SRVCNM    .TMIB
TA_OPERATION    SET
TA_CLASS        T_GROUP
TA_SRVGRP       APPGRP1
TA_GRPNO        1
TA_CURLMID      SITE1
TA_REQUEST_VERSION       4
Then the user reset the REQUEST_VERSION to default value through MIB:
SRVCNM    .TMIB
TA_OPERATION    SET
TA_CLASS        T_GROUP
TA_SRVGRP       APPGRP1
TA_GRPNO        1
TA_CURLMID      SITE1
TA_REQUEST_VERSION       DEFAULT