Using the Oracle Tuxedo Domains Component

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

About Domains

The following sections provide an overview of the Oracle Tuxedo Domains component:

 


What Is the Oracle Tuxedo Domains Component?

As a company’s business grows, application engineers may need to organize the business information management into distinct applications, each having administrative autonomy, based on functionality, geographical location, or confidentiality. These distinct business applications, known as domains, need to share information. The Oracle Tuxedo Domains component provides the infrastructure for interoperability among the domains of a business, thereby extending the Oracle Tuxedo client/server model to multiple transaction processing (TP) domains. Figure 1-1 shows how the Oracle Tuxedo Domains component can tie multiple domains together.

Figure 1-1 Interdomain Communications Using the Oracle Tuxedo Domains Component

Interdomain Communications Using the Oracle Tuxedo Domains Component

Interoperability Among Domains

By transparently making services of a remote domain available to users of the local domain, and making services of the local domain available to users of a remote domain, the Oracle Tuxedo Domains component breaks down the walls between a company’s business applications. In addition, the Domains component enables a company running an Oracle Tuxedo application to expand its business by interoperating with applications running on other transaction processing (TP) systems, such as Oracle’s WebLogic Server, IBM/Transarc’s Encina, and IBM’s CICS.

Because a company often uses the nature of a business application as part of its name, applications have names like the “accounting” domain or the “order entry” domain. An Oracle Tuxedo domain is a single computer or network of computers controlled by a single configuration file known as the UBBCONFIG file. (The Oracle Tuxedo configuration file may have any name as long as the content of the file conforms to the format described on reference page UBBCONFIG(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.) An Oracle Tuxedo domain is administered as a single unit.

Types of Domain Gateways

The Oracle Tuxedo Domains component offers different types of gateways to be able to communicate with different types of networks and domains. Specifically, the Domains component offers the following domain gateways:

The discussions that follow focus on the Oracle TDomain gateway and the communication between Oracle Tuxedo domains. For information about the WTC gateway, see:

For information about Oracle TMA gateways, see http://download.oracle.com/docs/cd/E13161_01/tuxedo/tux100/interm/mainfrm.html.

 


Example of a Domains Configuration

Figure 1-2 shows an example Domains configuration involving four domains, three of which are Oracle Tuxedo domains.

Figure 1-2 A Banking Domains Configuration—Example

A Banking Domains Configuration—Example

The Oracle Tuxedo credit card authorization center at the bottom of the figure has two gateway groups: a TDomain gateway group named bankgw1 and an OSI TP gateway group named bankgw2. bankgw1 provides access to two remote Oracle Tuxedo domains, Bank ABC and Bank CBA, using network protocol TCP/IP. bankgw2 provides access to one remote domain, Bank XYZ, using network protocol OSI TP.

In this example, Bank ABC generates service requests to the credit card authorization center. These requests are received by a domain gateway server process named GWTDOMAIN running within group bankgw1. This gateway issues a service request, on behalf of the remote domain, to the credit card authorization service provided by another locally running server process. This server handles the request and sends the reply to the gateway, and the gateway forwards the reply to Bank ABC.

The credit card authorization center may also issue service requests. For example, the authorization center may send balance inquiries to Bank XYZ via a domain gateway server process named GWOSITP.

The Oracle Tuxedo Domains component makes the interdomain communications possible through domain gateway server processes that advertises remote services—services available in other domains—as if they were local services.

 


Functionality Supported by Domain Gateways

Domain gateways support the following functionality:

Request/Response Communication Between Local and Remote Domains

Domain gateways provide support for the request/response model of communication defined by the ATMI interface. Except for the following Oracle Tuxedo ATMI functions, which are logically limited to use within a single application and are not supported across domains, an Oracle Tuxedo application can request remote services exactly as if they were offered locally:

Support for tpforward(3c) is provided to preserve application portability. Forwarded requests are interpreted by domain gateways as simple service requests. This process is shown in Figure 1-3, which illustrates the simple scenario of a service using tpforward to send a request to a remote service.

Figure 1-3 Using tpforward to Send a Request to a Remote Service

Using tpforward to Send a Request to a Remote Service

For more information about the Oracle Tuxedo request/response model, see “Request/Response Communication” in Introducing Oracle Tuxedo ATMI.

Conversational Communication Between Local and Remote Domains

Domain gateways provide support for the conversational model of communication defined by the ATMI interface. The ATMI is a connection-oriented interface that enables clients to establish and maintain conversations with services programmed in the conversational model.

Oracle Tuxedo applications use tpconnect(3c) to open a conversation with a remote service, tpsend(3c) and tprecv(3c) to communicate with this service, and tpdiscon(3c) to end the conversation. Domain gateways maintain the conversation with the remote service, and support the same semantics for returns (that is, tpreturn with TPSUCCESS or TPFAIL) and disconnects that are defined for Oracle Tuxedo conversational services.

Note: The ATMI connection-oriented functions provide half-duplex conversations; tpforward(3c) is not allowed within a conversational service.

For more information about the Oracle Tuxedo conversational model, see “Conversational Communication” in Introducing Oracle Tuxedo ATMI.

Queuing Messages on Remote Domains

Domain gateways provide support for the queuing model of communication defined by the ATMI interface. Any client or server can store messages or service requests in a queue in a remote domain. All stored requests are sent through the transaction protocol to ensure safe storage.

The Oracle Tuxedo system enables messages to be queued to persistent storage (disk) or to non-persistent storage (memory) for later processing or retrieval. ATMI provides primitives that allow messages to be added (that is, tpenqueue) or read (that is, tpdequeue) from queues. Reply messages and error messages can be queued for later return to clients. An administrative command interpreter (that is, qmadmin) is provided for creating, listing, and modifying queues. Servers are provided to accept requests to enqueue and dequeue messages (that is, TMQUEUE server), to forward messages from the queue for processing (that is, TMQFORWARD server), and to manage the transactions that involve queues (that is, TMS_QM server).

For more information about the Oracle Tuxedo queueing model, see “Message Queuing Communication” in Introducing Oracle Tuxedo ATMI.

Encoding and Decoding Operations for Domains

Domain gateways support all predefined types of typed buffers supported by the release of Oracle Tuxedo system software in which the domain gateway server processes are running. Oracle Tuxedo supports 11 predefined buffer types.

Each buffer type supported by an Oracle Tuxedo release has its own set of routines that can be called automatically to initialize, send and receive messages, and encode and decode data without programmer intervention. The set of routines is called a typed buffer switch.

In Oracle Tuxedo ATMI applications, typed buffers are used to send data—service requests and replies—between clients and servers. Typed buffers, which by definition contain information about themselves (metadata), allow application programmers to transfer data without needing to know which data representation scheme is used by the machines on which the application’s clients and servers are running.

A domain gateway can receive and process service requests sent from workstations, from local Oracle Tuxedo machines, and from remote domains. Using the appropriate typed buffer switch, a domain gateway will decode any service request that it receives encoded for the following reasons:

OSI terminology provides a useful distinction between abstract syntax (that is, the structure of the data) and transfer syntax (that is, the particular encoding used to transfer the data). Each typed buffer implicitly defines a particular data structure (that is, its abstract syntax) and the encoding rules (or typed buffer operations) required to map the data structure to a particular transfer syntax (for example, XDR). For the predefined buffer types that support encoding/decoding, the Oracle Tuxedo system provides the encoding rules required to map these types to the XDR transfer syntax.

For more information about typed buffers and encoding and decoding operations, see “What Are Typed Buffers?” in Introducing Oracle Tuxedo ATMI.

 


Oracle Tuxedo Domains Architecture

The Oracle Tuxedo Domains architecture consists of four major parts:

Domains Configuration File

A Domains configuration is a set of two or more domains (applications) that can communicate and share services via the Oracle Tuxedo Domains component. How multiple domains are connected and which services they make accessible to one another are defined in Domains configuration files. Each Oracle Tuxedo domain involved in a Domains configuration requires its own Domains configuration file.

The text version of the Domains configuration file is known as the DMCONFIG file, although it may have any name as long as the content of the file conforms to the format described on reference page DMCONFIG(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference. The binary version of the Domains configuration file is known as BDMCONFIG. For a detailed description of the DMCONFIG file, see Understanding the Domains Configuration File.

Domain Gateway Servers

The Oracle Tuxedo Domains component achieves multiple-domain interoperability through a highly asynchronous, multitasking, multithreaded domain gateway process, which is an Oracle Tuxedo supplied server that makes access to services across domains transparent to both the application programmer and the application user.

Figure 1-4 illustrates how one Oracle Tuxedo domain communicates with another domain via a domain gateway.

Figure 1-4 Two-Way Communication Through a Gateway

Two-Way Communication Through a Gateway

In the figure, the domain gateway handles outgoing credit card authorization requests to another domain. It also handles incoming authorization responses.

Domains Administrative Servers

Figure 1-5 shows the Oracle Tuxedo Domains administrative servers used to administer a Domains configuration.

Figure 1-5 Domains Administrative Servers

Domains Administrative Servers

A domain gateway group, as shown in the previous figure, consists of a gateway administrative server (GWADM), a domain gateway server (for example, GWTDOMAIN), and (optional) a Domains transaction log (TLOG). The GWADM server enables run-time administration of the domain gateway. An Oracle Tuxedo domain can communicate with one or more remote domains through a domain gateway group.

Associated with all domain gateway groups running in an Oracle Tuxedo domain is a Domains administrative server (DMADM), which enables run-time administration of the Oracle Tuxedo Domains configuration file (BDMCONFIG).

GWADM Server

The GWADM(5) server registers with the DMADM server to obtain the configuration information used by the corresponding gateway group. GWADM accepts requests from the DMADMIN service, which is a generic administrative service advertised by the DMADM server, for run-time statistics or changes in the run-time options of the specified gateway group. Periodically, GWADM sends an “I-am-alive” message to the DMADM server. If no reply is received from DMADM, GWADM registers again. This process ensures the GWADM server always has the current information about the Domains configuration for its gateway group.

For more information about GWADM, see Administering Domains.

DMADM Server

the DMADM(5) server provides a registration service for gateway groups. This service is requested by GWADM servers as part of their initialization procedure. The registration service downloads the configuration information required by the requesting gateway group. The DMADM server maintains a list of registered gateway groups, and propagates to these groups any changes made to the Domains configuration file (BDMCONFIG).

For more information about DMADM, see Administering Domains.

Domains Administrative Tools

The following Domains administrative tools are provided by the Oracle Tuxedo system for setting up and maintaining a Domains configuration:

Figure 1-6 shows the relationships between the Domains administrative tools and the Domains text and binary configuration files. Administration using the dmadmin utility is through the DMADMIN service, which is advertised by the DMADM server.

Figure 1-6 Relationships Between Domains Administrative Tools and Files

Relationships Between Domains Administrative Tools and Files

dmloadcf Command

The dmloadcf(1) command parses the DMCONFIG file and loads the information into BDMCONFIG. The command uses the environment variable BDMCONFIG to point to the device or system filename in which the configuration should be stored.

The dmloadcf command, through the -c option, also provides an estimate of the interprocess communications (IPC) resources needed for each local domain specified in the configuration.

The dmloadcf command checks the DMTYPE file (%TUXDIR%\udataobj\DMTYPE for Windows or $TUXDIR/udataobj/DMTYPE for UNIX) to verify that the domain gateway types specified in the Domains configuration file are valid. Each type of domain gateway has a domain type designator (TDOMAIN, SNAX, OSITP, OSITPX), which is used as a tag in the DMTYPE file. Each line in this file has the following format:

dmtype:access_module_lib:comm_libs:tm_typesw_lib:gw_typesw_lib

The file has the following entry for the TDomain gateway:

TDOMAIN:-lgwt:-lnwi -lnws -lnwi::

For more information about dmloadcf, see reference page dmloadcf (1)in Oracle Tuxedo Command Reference.

dmunloadcf Command

The dmunloadcf(1) command converts the BDMCONFIG configuration file from binary to text format and prints the output to standard output. For more information about dmunloadcf, see reference page dmunloadcf (1) in Oracle Tuxedo Command Reference.

dmadmin Command

The dmadmin(1) command allows an Oracle Tuxedo administrator to configure, monitor, and tune domain gateways when the Tuxedo domain is running. It acts as an administrative command interpreter that translates administrative commands and sends requests to the DMADMIN service, a generic administrative service advertised by the DMADM server. DMADMIN invokes functions that validate, retrieve, or update information in the BDMCONFIG file.

You invoke dmadmin with the -c option to dynamically update the BDMCONFIG file. Depending on the configuration being changed, some updates will take place immediately, while others will take place only for new occurrences of whatever is affected by the update.

For more information about dmadmin, see Administering Domains.

 


Understanding the Domains Configuration File

Each Oracle Tuxedo domain involved in a Domains configuration has a configuration file in which the interdomain parameters are defined. The text version of the configuration file is referred to as DMCONFIG, although the configuration file may have any name, as long as the content of the file conforms to the format described on reference page DMCONFIG(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference. Typical configuration filenames begin with the string dm, followed by a mnemonic string, such as config in the filename dmconfig.

As the administrator for the Domains configuration, you need to create a separate DMCONFIG file for each Oracle Tuxedo domain participating in the configuration. You can create and edit a DMCONFIG file with any text editor.

Location of DMCONFIG File

For an Oracle Tuxedo domain involved in a Domains configuration, the DMCONFIG file resides on the machine on which the Domains administrative server DMADM is to run, as specified in the UBBCONFIG file for the Tuxedo domain. The DMADM server may run on any machine (master machine, non-master machine) in a Tuxedo domain.

Note: The master machine for an Oracle Tuxedo domain contains the domain’s UBBCONFIG file, and is designated as the master machine in the RESOURCES section of the UBBCONFIG file. Starting, stopping, and administering a Tuxedo domain is done through the master machine.

Binary Version of DMCONFIG File

The BDMCONFIG file is a binary version of the DMCONFIG file. It is created by running the dmloadcf command, which parses DMCONFIG and loads the binary BDMCONFIG file to the location referenced by the BDMCONFIG environment variable. As with DMCONFIG, the BDMCONFIG file may be given any name; the actual name is the device or system filename specified in the BDMCONFIG environment variable. The BDMCONFIG environment variable must be set to an absolute pathname ending with the device or system filename where BDMCONFIG is to be loaded.

Unlike the TUXCONFIG file, which is the binary version of UBBCONFIG, the BDMCONFIG file is not propagated to any other machine in a Tuxedo domain when the Tuxedo application is booted. For the BDMCONFIG file to reside on any other machine in a Tuxedo domain, the administrator for that domain must manually place it there.

Descriptions of Sections of the DMCONFIG File

The DMCONFIG file is made up of specification sections. Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. The asterisk is required when specifying a section name.

Allowable section names are:

Note: The DM_LOCAL section must precede the DM_REMOTE section.

As the administrator for the Domains configuration, you use these sections to:

Figure 1-7 is a simple example of what you are trying to accomplish.

Figure 1-7 Establishing What Services Are Shared Between Two Oracle Tuxedo Domains—Example

Establishing What Services Are Shared Between Two Oracle Tuxedo Domains—Example

In the example, you must also create a DMCONFIG file for Domain Y that complements the DMCONFIG file created for Domain X. That is, a local domain access point in the Domain X DMCONFIG file would be a remote domain access point in the Domain Y DMCONFIG file, and a remote domain access point in the Domain X DMCONFIG file would be a local domain access point in the Domain Y DMCONFIG file. The example demonstrates the use of the TDomain gateway server.

Table 1-1 provides a description of each section in the DMCONFIG file.

Table 1-1 DMCONFIG File Sections (Sheet 1 of 4)
Section
Purpose
DM_LOCAL (also known as DM_LOCAL_DOMAINS)
Defines one or more local domain access point identifiers (also known as local domains, or LDOMs). For each local domain access point (logical name) that you define, you specify a domain gateway group (TDOMAIN, ...) for the access point in this section, and you specify in the DM_EXPORT section the local services available through the access point. The local services available through the local domain access point will be available to clients in one or more remote domains.
You can define multiple local domain access points in this section, one for each gateway group (TDOMAIN, SNAX, OSITP, OSITPX) used by this Oracle Tuxedo domain to communicate with a remote domain.
One and only one local domain access point is allowed per gateway group. A domain gateway group consists of a GWADM server process and a domain gateway server process (for example, GWTDOMAIN, the TDomain gateway server).
Example of a local domain access point entry:
*DM_LOCAL
LOCAL1  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=
BA.CENTRAL01”

Note: You may substitute DOMAINID for the ACCESSPOINTID parameter.

DM_REMOTE (also known as DM_REMOTE_DOMAINS)
Defines one or more remote domain access point identifiers (also known as remote domains, or RDOMs). For each remote domain access point (logical name) that you define, you specify a domain gateway group (TDOMAIN, ...) for the access point in this section, and you specify in the DM_IMPORT section the remote services available through the access point. The remote services available through the remote domain access point will be available to clients in the local domain.
You can define multiple remote domain access points in this section, one or more for each gateway group (TDOMAIN, SNAX, OSITP, OSITPX) used by this Oracle Tuxedo domain to communicate with a remote domain.
Example of remote domain access point entries:
*DM_REMOTE
REMOT1  TYPE=TDOMAIN
        ACCESSPOINTID=
BA.BANK01”
REMOT2  TYPE=TDOMAIN
        ACCESSPOINTID=
BA.BANK02”

Note: You may substitute DOMAINID for the ACCESSPOINTID parameter.

DM_EXPORT (also known as DM_LOCAL_SERVICES)
Specifies the local services exported to one or more remote domains through a local domain access point defined in the DM_LOCAL section. Only the services specified for a local domain access point are available to clients on one or more remote domains, meaning that specifying services in this section is a way to restrict remote client access to local services. If the DM_EXPORT section is absent, or is present but empty, all services advertised by the local domain are available to the remote domains.
A local service made available to remote domains inherits many of its properties from the SERVICES section of the local UBBCONFIG file. Some of the properties that may be inherited are LOAD, PRIO, AUTOTRAN, ROUTING, BUFTYPE, and TRANTIME.
Example of a local service made available to remote domains:
*DM_EXPORT
LTOLOWER  LACCESSPOINT=LOCAL1
          CONV=N
          RNAME=
TOLOWER”
          ACL=branch

Note: You may substitute LDOM for the LACCESSPOINT parameter.

DM_IMPORT (also known as DM_REMOTE_SERVICES)
Specifies the remote services imported through one or more remote domain access points defined in the DM_REMOTE section and made available to the local domain through one or more local domain access points. If the DM_IMPORT section is absent, or is present but empty, no remote services are available to the local domain.
A remote Oracle Tuxedo service made available to the local domain inherits many of its properties from the SERVICES section of the remote UBBCONFIG file. Some of the properties that may be inherited are LOAD, PRIO, AUTOTRAN, ROUTING, BUFTYPE, and TRANTIME.
Example of a remote service made available to the local domain:
*DM_IMPORT
RTOUPPER  AUTOTRAN=N
          RACCESSPOINT=REMOT1
          LACCESSPOINT=LOCAL1
          CONV=N
          RNAME=
TOUPPER”

Note: You may substitute RDOM for the RACCESSPOINT parameter, and LDOM for the LACCESSPOINT parameter.

DM_RESOURCES
Specifies global Domains configuration information, specifically a user-supplied configuration version string. The only parameter in this section is VERSION=string, where string is a field in which users can enter a version number for the current DMCONFIG file. This field is not checked by the software.
DM_ROUTING
Specifies data-dependent routing criteria for routing local service requests to one of several remote domains offering the same service. For an example, see Specifying Domains Data-Dependent Routing.
DM_ACCESS_CONTROL
Specifies one or more access control list (ACL) names and associates one or more remote domain access points with each specified ACL name. You can use the ACL parameter in the DM_EXPORT section by setting ACL=ACL_NAME to restrict access to a local service exported through a particular local domain access point to just those remote domain access points associated with the ACL_NAME.
Example of an ACL entry:
*DM_ACCESS_CONTROL
branch ACLIST=REMOT1
   
DM_domtype
Defines the parameters required for a particular Domains configuration. Currently, the value of domtype can be TDOMAIN, OSITP, OSITPX, or SNACRM + SNALINKS + SNASTACKS. Each domain type must be specified in a separate section.
In a DM_TDOMAIN section, you define the TDomain-specific network configuration for a local or remote domain access point. You can also define the network configuration for one or more remote domain access points associated with one or more WebLogic Server applications, to combine Tuxedo ATMI servers and WebLogic Server Enterprise JavaBean (EJB) servers in an application; for details, see Oracle Tuxedo Interoperability.
The DM_TDOMAIN section should have an entry per local domain access point if requests from remote domains to local services are accepted through that access point. For each local domain access point specified in this section, you must specify the network address to be used for listening for incoming connections.
The DM_TDOMAIN section should have an entry per remote domain access point if requests from the local domain to remote services are accepted through that access point. For each remote domain access point specified in this section, you must specify the destination network address to be used when connecting to that remote domain access point.
Beginning with Tuxedo release 9.0, the DM_TDOMAIN section can have an entry per TDomain session between specific local and remote domain access points. For each TDomain session specified in this section, you must specify the destination network address to use when connecting to that TDomain session.
When Domains link-level failover is in use, you can specify more than one destination network address for a remote domain access point or TDomain session to implement the mirrored gateway capability. For an example of a mirrored gateway, see How to Configure Domains Link-Level Failover.
For information about the DM_OSITP, DM_OSITPX, DM_SNACRM, DM_SNALINKS, and DM_SNASTACKS sections, see http://download.oracle.com/docs/cd/E13161_01/tuxedo/tux100/interm/mainfrm.html.

For a detailed description of the DMCONFIG file, see reference pages DMCONFIG (5)and DM_MIB (5)in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

Terminology Improvements for DMCONFIG File

For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. The improved terminology has been applied to the DMCONFIG(5) reference page, section names, parameter names, and error messages, and to the DM_MIB(5) reference page, classes, and error messages.

For backwards compatibility, aliases are provided between the DMCONFIG terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. For Oracle Tuxedo release 7.1 or later, both versions of DMCONFIG terminology are accepted. Table 1-2 shows the mapping of the previous and improved terminology for the DMCONFIG file.

Table 1-2 Mapping of the Previous and Improved Terminology for the DMCONFIG File
Previous Terminology
Improved Terminology
Section Name
Parameter Name
Section Name
Parameter Name
DM_LOCAL_DOMAINS
 
DM_LOCAL
 
DM_REMOTE_DOMAINS
 
DM_REMOTE
 
 
DOMAINID
 
ACCESSPOINTID
 
MAXRDOM
 
MAXACCESSPOINT
 
MAXRDTRAN
 
MAXRAPTRAN
DM_LOCAL_SERVICES
 
DM_EXPORT
 
DM_REMOTE_SERVICES
 
DM_IMPORT
 
 
LDOM
 
LACCESSPOINT
 
RDOM
 
RACCESSPOINT

For Oracle Tuxedo release 7.1 or later, the dmunloadcf command generates by default a DMCONFIG file that uses the improved domains terminology. Use the -c option to print a DMCONFIG file that uses the previous domains terminology. For example:

prompt> dmunloadcf -c > dmconfig_prev

 


Specifying Domains Data-Dependent Routing

You can specify data-dependent routing criteria for the routing of local service requests to remote domains in the DM_ROUTING section of the DMCONFIG file for any of the following buffer types:

In the following example, the remote service TOUPPER is available through two different remote domain access points named REMOT1 and REMOT2, and the data-dependent routing criteria for TOUPPER is defined in the routing criteria table named ACCOUNT. In the example, RTOUPPER1 and RTOUPPER2 are alias service names for TOUPPER, which is the actual service name expected by the remote domains.

*DM_IMPORT
RTOUPPER1  AUTOTRAN=N
           RACCESSPOINT=REMOT1
           LACCESSPOINT=LOCAL1
           CONV=N
           RNAME=
TOUPPER”
           ROUTING=ACCOUNT
RTOUPPER2  AUTOTRAN=N
           RACCESSPOINT=REMOT2
           LACCESSPOINT=LOCAL1
           CONV=N
           RNAME=
TOUPPER”
           ROUTING=ACCOUNT

*DM_ROUTING
ACCOUNT    FIELD=branchid
           BUFTYPE=
VIEW:account”
           RANGES=
MIN-1000:REMOT1,1001-3000:REMOT2”

For the ACCOUNT routing table, VIEW and account are the type and subtype of data buffers for which this routing table is valid, and branchid is the name of the field in the VIEW data buffer to which routing is applied. The allowed values for the branchid field are as follows:

If the value of the branchid field for a TOUPPER service request is within the range MIN-1000, the service request is routed through the REMOT1 access point. If the value of the branchid field for a TOUPPER service request is within the range 1001-3000, the service request is routed through the REMOT2 access point.

 


Specifying Domains Transaction and Blocking Timeouts

The Oracle Tuxedo system provides two timeout mechanisms: a transaction timeout mechanism and a blocking timeout mechanism. The transaction timeout is used to define the duration of an ATMI transaction, which may involve several service requests. The timeout value is defined when the transaction is started. The blocking timeout is used to define the duration of individual service requests, that is, how long the ATMI application is willing to wait for a reply to a service request.

If a process is not in transaction mode, the Oracle Tuxedo system performs blocking timeouts. If a process is in transaction mode, the Oracle Tuxedo system performs transaction timeouts but not blocking timeouts. The latter statement is true for intradomain transactions (that is, transactions handled within a single Oracle Tuxedo domain) but is not true for interdomain transactions. For interdomain transactions, if a process is in transaction mode, the Domains software performs both transaction timeouts and blocking timeouts.

How the Domains Component Handles Transaction Timeouts

The Oracle Tuxedo transaction timeout mechanism is used unchanged in the Domains component. Use of the same transaction timeout mechanism is necessary because domain gateways implement the transaction manager server (TMS) functionality and therefore are required to handle the TMS timeout messages generated by the Oracle Tuxedo Bulletin Board Liaison (BBL) administrative process.

A local service made available to remote domains in the DM_EXPORT section of the DMCONFIG file inherits the following transaction-related properties from the SERVICES section of the local UBBCONFIG file:

Similarly, a remote Oracle Tuxedo service made available to the local domain in the DM_IMPORT section of the DMCONFIG file inherits the AUTOTRAN and TRANTIME properties from the SERVICES section of the remote UBBCONFIG file. If the TRANTIME timeout value is exceeded for a transaction, the Oracle Tuxedo nodes infected with the transaction generate a TMS timeout message.

A service advertised on a machine running Oracle Tuxedo release 8.1 or later inherits an additional transaction-timeout property named MAXTRANTIME from the RESOURCES section of the UBBCONFIG file. If the MAXTRANTIME timeout value is less than the TRANTIME timeout value or the timeout value passed in a tpbegin(3c) call to start a transaction, the timeout for a transaction is reduced to the MAXTRANTIME value. MAXTRANTIME has no effect on a transaction started on a machine running Oracle Tuxedo 8.0 or earlier, except that when a machine running Oracle Tuxedo 8.1 or later is infected by the transaction, the transaction timeout value is capped—reduced if necessary—to the MAXTRANTIME value configured for that node.

For a Domains configuration, the following transaction-handling scenarios are possible:

For more information about MAXTRANTIME, see MAXTRANTIME in the RESOURCES section in UBBCONFIG(5) or TA_MAXTRANTIME in the T_DOMAIN class in TM_MIB(5).

How the Domains Component Handles Blocking Timeouts

The Oracle Tuxedo blocking timeout mechanism uses information stored in the registry slot assigned to each Oracle Tuxedo client or server process—one registry slot per process—running on the local machine. Information in the registry slot is used by the local BBL to detect requesters that have been blocked for a time greater than BLOCKTIME. Because a domain gateway process is a multitasking server that can process several service requests at a time (which would require multiple registry slots), domain gateways cannot use the registry slot mechanism. When a blocking timeout condition arises in a Domains environment, a domain gateway sends an error/failure reply message to the requester and cleans any context associated with the service request.

In the DM_LOCAL section of the DMCONFIG file, you can set the blocking timeout for a local domain access point using the BLOCKTIME parameter. For example:

*DM_LOCAL
LOCAL1  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=
BA.CENTRAL01”
        BLOCKTIME=30

The BLOCKTIME parameter specifies the maximum wait time a blocking ATMI call will block before timing out. A blocking timeout condition implies that the affected service request has failed.

The blocking timeout value is a multiplier of the SCANUNIT parameter specified in the RESOURCES section of the UBBCONFIG file. The value SCANUNIT * BLOCKTIME must be greater than or equal to SCANUNIT and less than or equal to 32,767 seconds.

If BLOCKTIME is not specified in the DMCONFIG file, the default is set to the value of the BLOCKTIME parameter specified in the RESOURCES section of the UBBCONFIG file. If the BLOCKTIME parameter is not specified in the UBBCONFIG file, the default is set so that (SCANUNIT * BLOCKTIME) is approximately 60 seconds.

Be aware that interdomain transactions generate blocking timeout conditions when transaction duration exceeds BLOCKTIME. That is, for an interdomain transaction, if the BLOCKTIME value is less than (a) the TRANTIME timeout value specified in the SERVICES section of the UBBCONFIG file or (b) the timeout value passed in the tpbegin() call to start the transaction, the timeout for the transaction is reduced to the BLOCKTIME value. In contrast, for intradomain transactions (that is, transactions handled within a single Oracle Tuxedo domain), the BLOCKTIME value specified in the RESOURCES section of the TUXCONFIG file has no effect on the timeout of an intradomain transaction.

 


Specifying Domains Connection Policies

You can specify the conditions under which a local domain gateway tries to establish a connection to one or more remote domains by selecting one of the following connection policies:

Connection policy applies only to TDomain gateways.

How To Configure Your Connection Policy

In the DM_LOCAL section of the DMCONFIG file, you set the connection policy for a local domain access point using the CONNECTION_POLICY parameter. For example:

*DM_LOCAL
LOCAL1  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=“BA.CENTRAL01”
        BLOCKTIME=30
        CONNECTION_POLICY=ON_STARTUP

If you do not specify a connection policy for a local domain access point, the connection policy for that access point defaults to ON_DEMAND.

Per Local/Remote Domain Connection Policy

For TDomain gateways running Oracle Tuxedo release 8.1 or later software, you can set the connection policy on a per local or per remote domain basis in the DM_TDOMAIN section of the DMCONFIG file. For example:

*DM_LOCAL
LOCAL1  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=“BA.CENTRAL01”
        BLOCKTIME=30

*DM_REMOTE
REMOT1  TYPE=TDOMAIN
        DOMAINID=”REMOT1”

REMOT2  TYPE=TDOMAIN
        DOMAINID=”REMOT2”

*DM_TDOMAIN
LOCAL1  NWADDR=“//albany.acme.com:4051”
        CONNECTION_POLICY=ON_STARTUP
REMOT1  NWADDR=“//newyork.acme.com:65431”
        CONNECTION_POLICY=ON_DEMAND
REMOT2  NWADDR=“//philly.acme.com:65431”

The connection policy specified for a remote domain access point takes precedence over the connection policy specified for a local domain access point. So, in the preceding example, the connection policy configurations will be:

LOCAL1 to REMOT1ON_DEMAND
LOCAL1
to REMOT2ON_STARTUP

For Oracle Tuxedo 8.1 or later, you can specify any of the following connection policy values for a local domain access point in the DM_TDOMAIN section of the DMCONFIG file:

Specifying no connection policy for a local domain access point defaults to the global connection policy specified in the DM_LOCAL section of the DMCONFIG file. Specifying a global connection policy in the DM_TDOMAIN section takes precedence over the global connection policy specified in the DM_LOCAL section.

Note: If you choose to specify a global connection policy in the DM_TDOMAIN section, do not specify a global connection policy in the DM_LOCAL section.

For Oracle Tuxedo 8.1 or later, you can also specify any of the following connection policy values for a remote domain access point in the DM_TDOMAIN section of the DMCONFIG file:

Specifying LOCAL or no connection policy for a remote domain access point defaults to the global connection policy.

Without the remote-domain connection policy capability, a global connection policy of ON_STARTUP means that the local TDomain gateway will try to connect to all remote domains at boot time, even if some of the remote domains will not be used initially. With a large number of remote domains, the boot time could be substantial. With the remote-domain connection policy capability, you can select which remote domain connections not to automatically establish at boot time for a global connection policy of ON_STARTUP.

Per TDomain Session Connection Policy

Beginning with Oracle Tuxedo 9.0, you can set the connection policy for TDomain gateways on a per TDomain session basis in the DM_TDOMAIN section of the DMCONFIG file.

In order to initiate a per TDomain session connection policy you must do the following:

Creating A TDomain Session

Two parameters in the DM_TDOMAIN section of the DMCONFIG file are used to create a TDomain session:

You can specify other TDomain session parameters and attributes, for example SECURITY and DMKEEPALIVE. For more information on FAILOVERSEQ and LACCESSPOINT, as well as other TDomain parameters and attributes, see Optional parameters for the DM_TDOMAIN section in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

Creating A Per TDomain Session Connection Policy

The FAILOVERSEQ, LACCESSPOINT and CONNECTION_POLICY parameters are used to establish a per TDomain session policy and are specified in Listing 1-1:

Listing 1-1 Per TDOMAIN Session Connection Policy Example
*DM_LOCAL
LOCAL1  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=“BA.CENTRAL01”
        BLOCKTIME=30

LOCAL2  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=“BA.CENTRAL02”
        BLOCKTIME=30

*DM_REMOTE
REMOT1  TYPE=TDOMAIN
        DOMAINID=”REMOT1”

REMOT2  TYPE=TDOMAIN
        DOMAINID=”REMOT2”

*DM_TDOMAIN
LOCAL1  NWADDR=“//albany.acme.com:4051”
LOCAL2  NWADDR=“//chicago.acme.com:4032”
LOCAL1  NWADDR=“//albany.acme.com:4052”
REMOT1  NWADDR=“//newyork.acme.com:65431” LACCESSPOINT=LOCAL1
        CONNECTION_POLICY=ON_STARTUP
        MINENCRYPTBITS=128 MAXENCRYPTBITS=128
        FAILOVERSEQ=100
REMOT1  NWADDR=“//newyork.acme.com:65432” LACCESSPOINT=LOCAL2
        CONNECTION_POLICY=INCOMING_ONLY
        FAILOVERSEQ=110
REMOT2  NWADDR=“//philly.acme.com:65431” LACCESSPOINT=LOCAL2
        CONNECTION_POLICY=ON_DEMAND
        FAILOVERSEQ=120
REMOT1  NWADDR=“//detroit.acme.com:65431” LACCESSPOINT=LOCAL1
        CONNECTION_POLICY=INCOMING_ONLY
        MINENCRYPTBITS=40 MAXENCRYPTBITS=40
        FAILOVERSEQ=130

The DM_TDOMAIN section consists of seven records that include three TDomain sessions.

Table 1-3 TDomain Sessions
Record
Domain Session
Connection Policy
Connection/ Failover Sequence
Session Hierarchy
4
[LOCAL1,REMOT1]
ON_STARTUP
1st
Primary
7
[LOCAL1,REMOT1]
Ignored
2nd
Secondary
5
[LOCAL2,REMOT1]
INCOMING_ONLY
1st
Primary
6
[LOCAL2,REMOT2]
ON_DEMAND
1st
Primary

If two or more records for the same TDomain session have the same FAILOVERSEQ value, the first record entered will be the primary record. The failover sequence for the remaining records is determined based on record-entry order.

To initiate your per TDomain session policy, perform the following steps:

Using Regular Expressions with TDomain Sessions

To make the DMCONFIG file smaller and easier to work with, LACCESSPOINT can contain regular expressions to describe multiple local domain access points.

Note: DM_TDOMAIN is the only section in the DMCONFIG file that allows LACCESSPOINT to contain regular expressions.

When the DMCONFIG file is compiled, regular expressions are expanded to their full local domain names in the output binary BDMCONFIG file. The size of the BDMCONFIG file is increased accordingly as shown in Listing 1-2:

Listing 1-2 DMCONFIG File with Regular Expressions

*DM_LOCAL
ALPHA1   . . .
ALPHA2   . . .
ALPHA3   . . .
ALPHA10   . . .
ALPHA11   . . .
ALPHA24   . . .
ALPHA36   . . .
BETA2   . . .
BETA3   . . .
BETA15   . . .
BETA20   . . .
*DM_REMOTE
REMOT1   . . .
REMOT2   . . .
REMOT3   . . .
*DM_TDOMAIN
REMOT1  NWADDR=“//philly.acme.com:65431” LACCESSPOINT=ALPHA1
        CONNECTION_POLICY=INCOMING_ONLY
        FAILOVERSEQ=100
REMOT1  NWADDR=“//philly.acme.com:65432” LACCESSPOINT=BETA2
        CONNECTION_POLICY=ON_DEMAND
        FAILOVERSEQ=110
REMOT1  NWADDR=“//philly.acme.com:65433” LACCESSPOINT=”ALPHA[1-2][0-9]”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=120
REMOT1  NWADDR=“//philly.acme.com:65434” LACCESSPOINT=”BETA[1-2][0-9]*”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=130

TDomain session records three and four use regular expressions to define local access points. When dmloadcf parses this DMCONFIG file, the BDMCONFIG file output is as follows in Listing 1-3.

Listing 1-3 Compiled BDMCONFIG File for DMCONFIG File with Regular Expressions

REMOT1  NWADDR=“//philly.acme.com:65431” LACCESSPOINT=ALPHA1
        CONNECTION_POLICY=INCOMING_ONLY
        FAILOVERSEQ=100
REMOT1  NWADDR=“//philly.acme.com:65432” LACCESSPOINT=BETA2
        CONNECTION_POLICY=ON_DEMAND
        FAILOVERSEQ=110
REMOT1  NWADDR=“//philly.acme.com:65433” LACCESSPOINT=”ALPHA10”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=120
REMOT1  NWADDR=“//philly.acme.com:65433” LACCESSPOINT=”ALPHA11”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=120
REMOT1  NWADDR=“//philly.acme.com:65433” LACCESSPOINT=”ALPHA24”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=120
REMOT1  NWADDR=“//philly.acme.com:65434” LACCESSPOINT=”BETA2”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=130
REMOT1  NWADDR=“//philly.acme.com:65434” LACCESSPOINT=”BETA15”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=130
REMOT1  NWADDR=“//philly.acme.com:65434” LACCESSPOINT=”BETA20”
        CONNECTION_POLICY=ON_STARTUP
        FAILOVERSEQ=130

Using DM_MIB to Specify or Request TDomain Session Information

Using DM_MIB to specify and request TDomain session information directly modifies the BDMCONFIG file. The original DMCONFIG file is unmodified. For more information about DM_MIB, see DM_MIB(5) in Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference.

Note: You can use dmunloadcf >DMCONFIG to parse the BDMCONFIG file to update its changes in the DMCONFIG file. For more information about dmunloadcf, see Domains Administrative Tools.

DM_MIB uses three T_DM_TDOMAIN Class Definition attributes to create a per TDomain session connection policy in the BDMCONFIG file:

You can also specify and request other T_DM_TDOMAIN Class Definition attributes, for example security and keepalive. For more T_DM_TDOMAIN Class Definition attribute information, see T_DM_TDOMAIN Class Definition in Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference.

You can use DM_MIB to add, delete, or retrieve TDomain session records in the BDMCONFIG file. All applicable T_DM_TDOMAIN Class Definition key fields must be used to add, delete, or retrieve requests for TDomain session record information.

For example:

Example 1: DM_MIB request used to add a new TDomain session and connection policy record.

TA_OPERATION                SET
TA_CLASS                    T_DM_TDOMAIN
TA_DMACCESSPOINT            RDOM1
TA_DMNWADDR                 //philly.acme.com:65431
TA_STATE                    NEW
TA_DMLACCESSPOINT           LDOM3
TA_DMFAILOVERSEQ            50
TA_DMCONNECTION_POLICY      ON_STARTUP

This will add the following TDomain session record in BDMCONFIG file:

RDOM1  NWADDR=“//philly.acme.com:65431” LACCESSPOINT=LDOM3
       FAILOVERSEQ=50
       CONNECTION_POLICY=ON_STARTUP

Example 2: DM_MIB request used to delete an existing TDomain session connection policy record.

The requested record is marked “invalid” in the BDMCONFIG file and is not included in the TDomain session.

TA_OPERATION                SET
TA_CLASS                    T_DM_TDOMAIN
TA_DMACCESSPOINT            RDOM1
TA_DMNWADDR                 //philly.acme.com:65431
TA_STATE                    INV
TA_DMLACCESSPOINT           LDOM3
TA_DMFAILOVERSEQ            50
TA_DMCONNECTION_POLICY      ON_STARTUP

Example 3: DM_MIB request used to retrieve an existing TDomain session connection policy record.

TA_OPERATION                GET
TA_CLASS                    T_DM_TDOMAIN
TA_DMACCESSPOINT            RDOM1
TA_DMNWADDR                 //philly.acme.com:65431
TA_STATE                    INV
TA_DMLACCESSPOINT           LDOM3
TA_DMFAILOVERSEQ            50
TA_DMCONNECTION_POLICY      ON_STARTUP

Using DMADMIN to Specify or Request TDomain Session Information

You can use Tuxedo’s command line interface, DMADMIN, to specify and request TDomain session information. For a general description of DMADMIN, seeDomains Administrative Tools.

Using DMADMIN to specify and request TDomain information works similarly to using DM_MIB. That is to say, using DMADMIN modifies the BDMCONFIG file and leaves the original DMCONFIG file unmodified.

DMADMIN uses three field indentifiers to add a per TDomain connection policy record in the BDMCONFIG file:

For more information about TA_DMFAILOVERSEQ, TA_LDOM, TA_CONNECTION_POLICY and other field indentifiers, see dmadmin(1) in Oracle Tuxedo Command Reference.

You can use DMADMIN to add, delete, or retrieve TDomain session records. The following example illustrates how DMADMIN is used to add a TDomain session connection policy record in the BDMCONFIG file:

TA_CMPLIMIT                   2147483647
TA_MINENCRYPTBITS             0
TA_MAXENCRYPTBITS             128
TA_DMNWADDR                   //philly.acme.com:65431
TA_LDOM                       LDOM3
TA_DMFAILOVERSEQ              50
TA_RDOM                       RDOM1
TA_CONNECTION_POLICY          ON_STARTUP

TDomain Session Interoperability with Older Tuxedo Releases

Tuxedo 9.x TDomain gateways can communicate with older Tuxedo release TDomain gateways. However, if you want to use the TDomain session feature running Tuxedo 9.x and 8.1 in a mixed application environment, please note the following limitations:

The TDomain session feature does not work with Tuxedo releases older than 8.1 in a mixed application environment.

How To Use Connection Retry Processing

When CONNECTION_POLICY is set to ON_STARTUP, you can configure two other parameters to determine how many times the local domain gateway attempts to establish a connection to the remote domains. By default, the local domain gateway retries failed connections every 60 seconds, but you can specify a different value for this interval using parameters MAXRETRY and RETRY_INTERVAL.

You use the MAXRETRY parameter to specify the number of times that a domain gateway tries to establish connections to remote domains. The minimum value is 0, and the maximum value is 2147483647. The default setting is 2147483647. Setting this parameter to 0 turns off connection retry processing.

You use the RETRY_INTERVAL parameter to specify the number of seconds between automatic attempts to establish a connection to remote domains. The minimum value is 0, and the maximum value is 2147483647. The default setting is 60. If the MAXRETRY parameter is set to 0, setting RETRY_INTERVAL is not allowed.

Example 1:

*DM_LOCAL
LOCAL1  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=
BA.CENTRAL01”
        BLOCKTIME=30
        CONNECTION_POLICY=ON_STARTUP
        MAXRETRY=5
        RETRY_INTERVAL=100

Example 2 (Only possible for TDomain gateways running Oracle Tuxedo release 8.1 or later software):

*DM_LOCAL
LOCAL1  GWGRP=GWTGROUP
        TYPE=TDOMAIN
        ACCESSPOINTID=
BA.CENTRAL01”
        BLOCKTIME=30

*DM_TDOMAIN
LOCAL1  NWADDR=
//albany.acme.com:4051”
        CONNECTION_POLICY=ON_STARTUP
        MAXRETRY=5
        RETRY_INTERVAL=100
REMOT1  NWADDR=
//newyork.acme.com:65431”
        CONNECTION_POLICY=ON_STARTUP
        MAXRETRY=10
        RETRY_INTERVAL=40

In the second example, the MAXRETRY and RETRY_INTERVAL values 10 and 40 will be the automatic connection retry criteria used by the local TDomain gateway to establish a connection to the remote domain access point named REMOT1.

How Connection Policy Determines Availability of Remote Services

The connection policy that you specify determines how services imported from a remote domain are advertised in the Oracle Tuxedo bulletin board by the domain gateway:

When the connection policy is ON_STARTUP or INCOMING_ONLY (but not ON_DEMAND), Dynamic Status, a TDomain gateway feature, checks the status of remote services. The status of a remote service depends on the status of the network connection between the local and remote domain gateways. Remote services are advertised and available on the local domain whenever a connection is successfully established to the domain on which they reside. Remote services are suspended and unavailable whenever the connection is not established to the domain on which they reside.

For each service, the domain gateway keeps track not only of the remote domains from which the service is imported, but also of which remote domains are available. In this way, the gateway provides intelligent load balancing of requests to remote domains. If all the remote domains from which a service is imported become unreachable, the domain gateway suspends the service in the Oracle Tuxedo bulletin board.

For example, suppose a service named RSVC is imported from two remote domains, as specified by the following entries in the DM_IMPORT section of the DMCONFIG file:

*DM_IMPORT
RSVC  AUTOTRAN=N
      RACCESSPOINT=REMOT1
      LACCESSPOINT=LOCAL1
RSVC  AUTOTRAN=N
      RACCESSPOINT=REMOT2
      LACCESSPOINT=LOCAL1

When connections to both REMOT1 and REMOT2 are up, the domain gateway load balances requests for the RSVC service. If the connection to REMOT1 goes down, the gateway sends all requests for RSVC to REMOT2. If both connections go down, the gateway suspends RSVC in the bulletin board. Subsequent requests for RSVC are either routed to a local service or fail with TPENOENT.

See Also

 


Specifying Domains Failover and Failback

In the DM_IMPORT section of the DMCONFIG file, you can set up the Domains-level failover and failback functionality for your Domains configuration. In the DM_TDOMAIN section of the DMCONFIG file, you can set up the Domains link-level failover functionality for your Domains configuration.

How to Configure Domains-Level Failover and Failback

Domains-level failover is a mechanism that transfers requests to alternate remote domains when a failure is detected with a primary remote domain. It also provides failback to the primary remote domain when that domain is restored.

To support Domains-level failover and failback, you specify a list of the remote domain access points through which a particular service can be executed. For example:

*DM_IMPORT
TOUPPER RACCESSPOINT=
REMOT1,REMOT2,REMOT3”

In this example, the TOUPPER service can be executed through any of three remote domain access points: REMOT1 (primary), REMOT2, and REMOT3. When REMOT1 is unavailable, REMOT2 is used for failover. When REMOT1 and REMOT2 are both unavailable, REMOT3 is used for failover.

You must specify ON_STARTUP or INCOMING_ONLY as the value of the CONNECTION_POLICY parameter if you want to configure alternate remote domains for a service. If you specify ON_DEMAND as your connection policy, your servers cannot “fail over” to the alternate remote domains that you have specified in the RACCESSPOINT parameter.

Domains-level failback occurs when a network connection to the primary remote domain is re-established for any of the following reasons:

How to Configure Domains Link-Level Failover

Domains link-level failover is a mechanism that ensures that a secondary network link becomes active when a primary network link fails. However, it does not provide failback to the primary link when that link is restored, meaning that when the primary link is restored, you must manually bring down the secondary link to force traffic back onto the primary link.

To configure Domains link-level failover, you specify multiple entries for a remote domain access point in the DM_TDOMAIN section of the DMCONFIG file. For example:

*DM_TDOMAIN
REMOT1  NWADDR=
//newyork.acme.com:65431”
REMOT1  NWADDR=
//trenton.acme.com:65431”

The first entry is considered to be the primary address, which means its NWADDR is the first network address tried when a connection is being attempted to the remote domain access point. The second entry is considered to be the secondary address, which means its NWADDR is the second network address tried when a connection cannot be established using the primary address.

The second entry points to a secondary remote gateway that must reside in a different Oracle Tuxedo domain than the Oracle Tuxedo domain in which the primary remote gateway resides. The secondary and primary remote gateways must have the same ACCESSPOINTID defined in the DM_LOCAL section of their associated DMCONFIG files; this arrangement is often referred to as a mirrored gateway. This feature is not recommended for use with transactions or conversations. In addition, the mirrored gateway is not recommended for use when the primary remote gateway is available.

How to Configure TDomain Session Link-Level Failover

The FAILOVERSEQ parameter in the DM_TDOMAIN section of the DMCONFIG file is used to configure TDomain session link-level failover. For more information about specifying FAILOVERSEQ in a TDomain session, see Per TDomain Session Connection Policy.

You can also use the TA_DMFAILOVERSEQ attribute in DM_MIB to configure TDomain session link-level failover. For more information, see Using DM_MIB to Specify or Request TDomain Session Information.

 


Specifying Domains Keepalive

Domains keepalive, available for TDomain gateways running Oracle Tuxedo release 8.1 or later software, allows you to enable and configure a keepalive protocol at the TCP level and/or application level for each TDomain gateway connection. TCP-level keepalive and application-level keepalive are not mutually exclusive, meaning that you can configure a Domains connection using both options.

Table 1-4 provides some key information about Domains keepalive.

Most Oracle Tuxedo Domains configurations span across firewalls, and firewalls typically time out idle connections. Not only will Domains keepalive keep Oracle Tuxedo interdomain connections open during periods of inactivity, but it will also enable TDomain gateways to quickly detect Domains connection failures. Currently, a TDomain gateway learns of a Domains connection failure through the underlying TCP stack, which may report the failure 15 minutes or more (depending on the local operating system configuration) after the failure occurs.

What is TCP-Level Keepalive?

Although the keepalive functionality is not part of the TCP specification, most operating systems provide a TCP keepalive timer. The TCP keepalive timer allows the server machine at one end of a TCP connection to detect whether the client machine at the other end of the connection is reachable.

Every message received by the server machine over the TCP connection resets the TCP keepalive timer. If the keepalive timer detects no activity on the TCP connection for a predefined period of time (typically two hours), the timer expires, and the server machine sends a probe segment packet to the client machine. If the connection is still open and the client machine is still alive, the client machine responds by sending an acknowledgement to the server machine. If the server machine does not receive an acknowledgement within a fixed period of time of sending the probe segment packet, the server machine assumes that the connection is broken and releases any resources associated with the connection.

Besides determining whether the connection is open and the client machine is alive, TCP-level keepalive is a way of keeping idle connections open through firewalls. Automatically sending a probe segment packet after a predefined period of connection inactivity resets the firewall’s idle-connection timer before it times out, which allows the connection to stay open.

The interval for an operating system’s TCP keepalive timer is typically set to two hours. This interval can be changed, but changing it affects all TCP connections for a machine. An operating system’s TCP keepalive interval is a system-wide value.

How to Configure TCP-Level Keepalive for Domains

The Oracle Tuxedo TCP-level keepalive option for Domains is named TCPKEEPALIVE, which has been added as an optional parameter in the DM_TDOMAIN section of the DMCONFIG file. You can use this parameter to enable the Domains TCP-level keepalive option on a per local or per remote domain basis.

The allowed values for TCPKEEPALIVE are:

By default, the Domains TCP-level keepalive option is disabled. When you enable TCP-level keepalive for a Domains connection, the keepalive interval used for the connection is the system-wide value configured for the operating system’s TCP keepalive timer.

To clarify the use of TCPKEEPALIVE, consider the following Domains TCP-level keepalive configuration:

*DM_TDOMAIN
LOCAL1  NWADDR=
//albany.acme.com:4051”
        TCPKEEPALIVE=Y
REMOT1  NWADDR=
//newyork.acme.com:65431”
REMOT2  NWADDR=
//philly.acme.com:65431”
        TCPKEEPALIVE=NO

The TCP-level keepalive configuration specified for a remote domain access point takes precedence over the TCP-level keepalive configuration specified for the local domain access point. So, in the preceding example, the TCP-level keepalive configurations will be:

LOCAL1 to REMOT1 — TCP-level keepalive enabled
LOCAL1 to REMOT2 — TCP-level keepalive disabled

For a local domain access point, you can specify any of the following values for the TCPKEEPALIVE parameter:

For a remote domain access point, you can specify any of the following values for the TCPKEEPALIVE parameter:

Specifying LOCAL or no configuration for a remote domain access point defaults to the local TCP-level keepalive configuration.

Note: You can enable each of two interoperating Oracle Tuxedo domains with TCP-level keepalive, assuming that both domains are running Oracle Tuxedo 8.1 or later software.

If the connection policy for a Domains connection is ON_STARTUP and the TCP connection is closed due to a TCP-level keepalive failure, automatic connection retry attempts. If the connection retry is not successful, you must use the dmadmin connect command to re-establish the connection. For information about the dmadmin connect command, see How to Establish Connections Between Domains.

What is Application-Level Keepalive?

Some people argue against using the operating system’s TCP keepalive, citing that the probe segment packets consume unnecessary bandwidth and waste money on internet connections where users pay on a per packet basis. Some people also believe that keepalive belongs in the application layer or link layer, not in the transport (TCP) layer, citing that the application layer should:

Regardless of who thinks what, one advantage of application-level keepalive over TCP-level keepalive is that the interval for the keepalive timer can be set on a per connection basis. With TCP-level keepalive, the timer interval must be set on a per machine basis.

Using application-level keepalive, the server application sends an application-specific keepalive message whenever the application keepalive timer times out. (Typically, the keepalive message consists of just header information, meaning that the message has no associated data.) The client application responds by sending an acknowledgement to the server application. If the server application does not receive an acknowledgement within a predefined period of time of sending the keepalive message, the server application assumes that the connection is broken and releases any resources associated with the connection.

Besides determining whether the connection is open and the client application is running, application-level keepalive is a way of keeping idle connections open through firewalls. Automatically sending a keepalive message after a predefined period of connection inactivity resets the firewall’s idle-connection timer before it times out, which allows the connection to stay open.

How to Configure Application-Level Keepalive for Domains

The Oracle Tuxedo application-level keepalive option for Domains is named KEEPALIVE. This parameter and a companion parameter named KEEPALIVEWAIT have been added as optional parameters in the DM_TDOMAIN section of the DMCONFIG file. You can use these parameters to configure the Domains application-level keepalive option on a per local or per remote domain basis.

You use the DMKEEPALIVE parameter to specify the maximum time that the local TDomain gateway will wait without receiving any traffic on the Domains connection; if the maximum time is exceeded, the gateway sends an application-level keepalive request message. The allowed values for DMKEEPALIVE are:

The DMKEEPALIVE default setting is 0.

You use the DMKEEPALIVEWAIT parameter to specify the maximum time that the local TDomain gateway will wait without receiving an acknowledgement to a sent keepalive message. If the maximum time is exceeded, the gateway assumes that the connection to the remote TDomain gateway is broken and releases any resources associated with the connection. The minimum value for DMKEEPALIVEWAIT is 0, and the maximum value is 2147483647 milliseconds, currently rounded up to the nearest second by the Domains software. The DMKEEPALIVEWAIT default setting is 0.

To clarify the use of DMKEEPALIVE and DMKEEPALIVEWAIT, consider the following Domains application-level keepalive configuration:

*DM_TDOMAIN
LOCAL1  NWADDR=
//albany.acme.com:4051”
        DMKEEPALIVE=1010
        DMKEEPALIVEWAIT=20
REMOT1  NWADDR=
//newyork.acme.com:65431”
        DMKEEPALIVE=4000
        DMKEEPALIVEWAIT=3000
REMOT2  NWADDR=
//philly.acme.com:65431”
        DMKEEPALIVE=-1

The keepalive configuration specified for a remote domain access point takes precedence over the keepalive configuration specified for the local domain access point. So, in the preceding example, the application-level keepalive configurations will be:

LOCAL1 to REMOT1 — Keepalive timer = 4 seconds, and wait timer = 3 seconds
LOCAL1 to REMOT2 — Keepalive timer = 2 seconds, and wait timer = 1 second

For a local domain access point, you can specify any of the following values for the DMKEEPALIVE parameter:

For a remote domain access point, you can specify any of the following values for the DMKEEPALIVE parameter:

Specifying -1 or no keepalive configuration for a remote domain access point defaults to the local application-level keepalive configuration.

Note: You can configure each of two interoperating Oracle Tuxedo domains with application-level keepalive, using the same or different wait intervals, assuming that both domains are running Oracle Tuxedo 8.1 or later software.

If the connection policy for a Domains connection is ON_STARTUP and the connection experiences an application-level keepalive failure, automatic connection retry processing attempts to re-establish the connection. For more information about connection retry processing, see How To Use Connection Retry Processing.

Keepalive Compatibility with Earlier Oracle Tuxedo Releases

Domains TCP-level keepalive is compatible with Oracle Tuxedo 8.0 or earlier software. The Oracle Tuxedo software running at the other end of the TCP connection may be any release of Oracle Tuxedo because Domains TCP-level keepalive is executed at the network transport (TCP) layer.

Domains application-level keepalive is not compatible with Oracle Tuxedo 8.0 or earlier software. The Oracle Tuxedo software running at the other end of the TCP connection must be Oracle Tuxedo 8.1 or later to be able to understand an application-level keepalive message. When connected to a TDomain gateway running an earlier release of Oracle Tuxedo software, the TDomain gateway does not send an application-level keepalive message; instead, it logs a warning message in the local user log (ULOG) stating that the remote domain is running an earlier release of Oracle Tuxedo software and does not support Domains application-level keepalive.

 


Configuring a Domains Environment

The following list summarizes the tasks that you must complete to configure a Domains environment for the TDomain gateway type:

  1. Edit the UBBCONFIG file with any text editor and configure the Domains administrative servers and the TDomain gateway server. For example:
  2. *GROUPS
    DMADMGRP  LMID=SITE1 GRPNO=1
    GWTGROUP  LMID=SITE2 GRPNO=2

    *SERVERS
    DMADM     SRVGRP=DMADMGRP
              SRVID=1001
              REPLYQ=N
              RESTART=Y
              GRACE=0
    GWADM     SRVGRP=GWTGROUP
              SRVID=1002
              REPLYQ=N
              RESTART=Y
              GRACE=0
    GWTDOMAIN SRVGRP=GWTGROUP
              SRVID=1003
              RQADDR=
    GWTGROUP”
              REPLYQ=N
              RESTART=Y
              GRACE=0

    Note: In the previous example, REPLYQ=N is specified for the DMADM, GWADM, and GWTDOMAIN servers. This setting is not required: you can, if you prefer, designate a reply queue for any of these servers by specifying REPLYQ=Y. When REPLYQ is set to N, however, performance may be improved.

    The TDomain gateway server and its associated GWADM server must run on the same machine in an Oracle Tuxedo domain. The DMADM server may run on any machine—master machine, non-master machine—in the Oracle Tuxedo domain.

  3. Load the Oracle Tuxedo configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.
  4. Edit the DMCONFIG file with any text editor and configure the Domains environment for the TDomain gateway server. For example:
  5. *DM_LOCAL
    LOCAL1    GWGRP=GWTGROUP
              TYPE=TDOMAIN
              ACCESSPOINTID=
    BA.CENTRAL01”
              BLOCKTIME=30
              CONNECTION_POLICY=ON_STARTUP
              MAXRETRY=5
              RETRY_INTERVAL=100

    *DM_REMOTE
    REMOT1    TYPE=TDOMAIN
              ACCESSPOINTID=
    BA.BANK01”
    REMOT2    TYPE=TDOMAIN
              ACCESSPOINTID=
    BA.BANK02”

    *DM_EXPORT
    LTOLOWER  LACCESSPOINT=LOCAL1
              CONV=N
              RNAME=
    TOLOWER”

    *DM_IMPORT
    RTOUPPER  AUTOTRAN=N
              RACCESSPOINT=REMOT1
              LACCESSPOINT=LOCAL1
              CONV=N
              RNAME=
    TOUPPER”

    *DM_TDOMAIN
    LOCAL1  NWADDR=
    //albany.acme.com:4051”
    REMOT1  NWADDR=
    //newyork.acme.com:65431”
    REMOT2  NWADDR=
    //philly.acme.com:65431”

    The DMCONFIG file must reside on the same machine as the DMADM server.

  6. Load the Domains configuration by running dmloadcf(1). The dmloadcf command parses DMCONFIG and loads the binary BDMCONFIG file to the location referenced by the BDMCONFIG variable.
  7. Start the Oracle Tuxedo application servers by running tmboot(1). The tmboot command executes all administrative processes and all servers listed in the SERVERS section of the TUXCONFIG file named by the TUXCONFIG and TUXOFFSET environment variables. It starts the servers in the order that they are listed in the SERVERS section: DMADM, then GWADM, and then GWTDOMAIN. The Domains servers must be started in this order. In addition, the Domains servers must be started before the application servers.

For a detailed example of configuring a Domains ATMI environment, see Planning and Configuring ATMI Domains. For a detailed example of configuring a Domains CORBA environment, see Planning and Configuring CORBA Domains.

 


Configuring a Domains Environment for Migration

Listing 1-4 and Listing 1-5 give you an idea of how to configure an Oracle Tuxedo application for Domains migration. The entries of particular importance to the Domains migration are highlighted in bold.

Listing 1-4 Sample UBBCONFIG File Configured for Domains Migration
*RESOURCES
IPCKEY 76666
MASTER    SITE1,SITE2
OPTIONS LAN,MIGRATE
MODEL MP
#
*MACHINES
mach1     LMID=SITE1
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
mach2     LMID=SITE2
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
mach3     LMID=SITE3
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
#
*GROUPS
DMADMGRP  LMID=“SITE1,SITE3” GRPNO=1
GWTGROUP  LMID=“SITE2,SITE3” GRPNO=2
.
.
.
*NETWORK
SITE1  NADDR=“//albany.acme.com:4065”
 NLSADDR=“//albany.acme.com:4068”
SITE2  NADDR=“//auburn.acme.com:4065”
 NLSADDR=“//auburn.acme.com:4068”
SITE3  NADDR=“//boston.acme.com:4065”
 NLSADDR=“//boston.acme.com:4068”

#
*SERVERS
DMADM     SRVGRP=DMADMGRP
          SRVID=1001
          REPLYQ=N
          RESTART=Y
          GRACE=0
GWADM     SRVGRP=GWTGROUP
          SRVID=1002
          REPLYQ=N
          RESTART=Y
          GRACE=0
GWTDOMAIN SRVGRP=GWTGROUP
          SRVID=1003
          RQADDR=“GWTGROUP”
          REPLYQ=N
          RESTART=Y
          GRACE=0
.
.
.
Note: In the previous example, REPLYQ=N is specified for the DMADM, GWADM, and GWTDOMAIN servers. This setting is not required: you can, if you prefer, designate a reply queue for any of these servers by specifying REPLYQ=Y. When REPLYQ is set to N, however, performance may be improved.
Listing 1-5 Sample DMCONFIG File Configured for Domains Migration
*DM_LOCAL
LOCAL1    GWGRP=GWTGROUP
          TYPE=TDOMAIN
          ACCESSPOINTID=“BA.CENTRAL01”
          BLOCKTIME=30
          CONNECTION_POLICY=ON_STARTUP
          MAXRETRY=5
          RETRY_INTERVAL=100
*DM_REMOTE
REMOT1    TYPE=TDOMAIN
          ACCESSPOINTID=“BA.BANK01”
REMOT2    TYPE=TDOMAIN
          ACCESSPOINTID=“BA.BANK02”
*DM_EXPORT
LTOLOWER  LACCESSPOINT=LOCAL1
          CONV=N
          RNAME=“TOLOWER”
*DM_IMPORT
RTOUPPER  AUTOTRAN=N
          RACCESSPOINT=REMOT1
          LACCESSPOINT=LOCAL1
          CONV=N
          RNAME=”TOUPPER”
*DM_TDOMAIN
LOCAL1  NWADDR=“//albany.acme.com:4051”
LOCAL1  NWADDR=“//boston.acme.com:4051”
REMOT1  NWADDR=“//newyork.acme.com:65431”
REMOT2  NWADDR=“//philly.acme.com:65431”

In the sample configuration files, the DMADM server and the TDomain gateway group servers are configured to migrate to the SITE3 machine. For the DMADM migration, an administrator will activate a DMADM server process on the SITE3 machine after completing the following tasks:

For the TDomain gateway group migration, an administrator will activate GWADM and GWTDOMAIN server processes on the SITE3 machine. At that point, the configurations and responsibilities associated with the LOCAL1 access point will be handled by the new GWTDOMAIN server process listening for incoming connection requests on network address boston.acme.com:4051.

Note: The DMADM and domain gateway group(s) do not have to be migrated to the same machine.

How to Migrate the DMADM Server

To migrate DMADM to a new machine, follow these steps.

  1. Copy DMCONFIG to the new machine and run dmloadcf.
  2. Activate the DMADM server process on the new machine. For details, see Methods for Activating Individual Server Processes.
  3. Optional: Restart all domain gateway groups for the Oracle Tuxedo application. For details, see Methods for Activating Individual Server Processes.
  4. If you do not restart the domain gateway groups, they will continue to function, but after DMADM has been migrated, all MIB requests for them will fail.

How to Migrate a TDomain Gateway Group

When transactions are being used in a Domains configuration, the TDomain gateway group can be migrated only across machines of the same type.

To migrate a TDomain gateway group, follow these steps.

  1. In the DMCONFIG file, add multiple listening addresses, in the following format, to the DM_TDOMAIN section:
  2. *DM_TDOMAIN
    LOCAL1 NWADDR=“//primary:port
    LOCAL1 NWADDR=“//backup:port
  3. If you are using transactions, you must copy the Domains transaction log manually to the backup machine.
  4. The DMCONFIG files for the remote domains should include both network addresses specified in step 1.
  5. Activate the GWADM and GWTDOMAIN server processes on the new machine. For details, see the following section.

Methods for Activating Individual Server Processes

You can use any of the following methods to activate individual Oracle Tuxedo server processes:

For information about performing application migration tasks, see “Migrating Your Application” in Administering an Oracle Tuxedo Application at Run Time.


  Back to Top       Previous  Next