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.

However, 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.

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:

• Oracle Tuxedo TDomain gateway (implemented by the GWTDOMAIN server process)—provides interoperability between two or more Oracle Tuxedo domains through a specially designed TP protocol that flows over network protocol TCP/IP. Working with the WebLogic Tuxedo Connector (WTC) gateway, an Oracle WebLogic Server component, the Oracle Tuxedo TDomain gateway can also provide interoperability between Tuxedo domains and WebLogic Server applications.
• Oracle TMA TCP gateway (implemented by the GWIDOMAIN server process) provides interoperability between Oracle Tuxedo domains and applications running under IBM OS/390 Customer Information Control System (CICS) and Information Management System (IMS) over network protocol TCP/IP. The gateway supports only non-transactional tasks.
• Oracle TMA SNA gateway (implemented by the GWSNAX server process)—provides interoperability between Oracle Tuxedo domains and applications running on any System Network Architecture (SNA) Advanced Program-to-Program Communications (APPC) or Common Programming Interface for Communications (CPI-C) supported platform, including IBM OS/400, OS/390 CICS and IMS systems and VSE/CICS. The gateway supports communication with multiple SNA networks.

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

• Oracle® Tuxedo Overview Guide
• WebLogic Tuxedo Connector

For information about Oracle TMA gateways, see Oracle Tuxedo Mainframe Adapter Documentation.

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:

• tpinit(3c)/tpterm(3c)—Oracle Tuxedo applications do not attach to the environment of a remote domain; they use domain gateways to access a remote domain. Therefore, an extra tpinit()/tpterm() sequence is not needed for remote applications.
• tpadvertise(3c) and tpunadvertise(3c)—Domains does not support these functions because domain gateways do not support dynamic service advertisements across domains.
• tpnotify(3c) and tpbroadcast(3c)—Domains does not support the unsolicited communication paradigm provided by these functions.
• Event posting (tppost(3c)) and notification of events (tpsubscribe(3c))—Domains does not support these functions across domains.

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 the following Figure, 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

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

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.

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

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 queuing model, see “Message Queuing Communication” in Introducing Oracle Tuxedo ATMI.

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:

• Data-dependent routing depends upon matching specified criteria to fields within data. Therefore, a domain gateway must decode the encoded data in order to route that data to the appropriate remote domain for the service requested.
• Different data formats may be used within different domains, depending on the networking protocols implemented or used in a domain. Therefore, a domain gateway must decode the encoded data to determine which data format is being used.

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.

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.

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.

The following Figure illustrates how one Oracle Tuxedo domain communicates with another domain through a domain gateway.

Figure 1-4 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.

The following figure illustrates the Oracle Tuxedo Domains administrative servers used to administer a Domains configuration.

Figure 1-5 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
  
• DMADM Server
  

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

• dmloadcf(1)—reads the DMCONFIG file, checks the syntax, and loads the binary BDMCONFIG configuration file.
• dmunloadcf(1)—translates the BDMCONFIG configuration file from binary to text format.
• dmadmin(1)—allows an Oracle Tuxedo administrator to update the BDMCONFIG file when the Tuxedo domain is running.

The following figure illustrates 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

• dmloadcf Command
  
• dmunloadcf Command
  
• dmadmin Command
  

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.

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.

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:

• DM_LOCAL (also known as DM_LOCAL_DOMAINS)
• DM_REMOTE (also known as DM_REMOTE_DOMAINS)
• DM_EXPORT (also known as DM_LOCAL_SERVICES)
• DM_IMPORT (also known as DM_REMOTE_SERVICES)
• DM_RESOURCES
• DM_ROUTING
• DM_ACCESS_CONTROL
• DM_domtype , where domtype is TDOMAIN, or SNACRM + SNALINKS + SNASTACKS
• The DM_LOCAL section must precede the DM_REMOTE section.

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

• Define local domain access points through which application clients on a remote domain can access services on the local domain.
• Specify the local services available through each local domain access point.
• Define remote domain access points through which application clients on the local domain can access services on a remote domain.
• Specify the remote services available through each remote domain access point.
• Map local domain access points and remote domain access points to specific domain gateway groups (TDOMAIN, ...) and network addresses.

The following figure 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

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.

The following table provides a description of each section in the DMCONFIG file.

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

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

*DM_EXPORT
LTOLOWER  LACCESSPOINT=LOCAL1
          CONV=N
          RNAME=“TOLOWER”
          ACL=branch

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

*DM_ACCESS_CONTROL
branch ACLIST=REMOT1

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.

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. The following table shows the mapping of the previous and improved terminology for the DMCONFIG file.

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

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:

• AUTOTRAN—When AUTOTRAN is turned on for a service and a service request is received for the service that is not already within a transaction, the local Oracle Tuxedo system automatically starts a transaction for the service.
• TRANTIME—Transaction timeout value in seconds for transactions automatically started for the service. If this timeout value is exceeded for a transaction, the Oracle Tuxedo nodes (machines) infected with the transaction generate a TMS timeout message.

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:

• If an interdomain transaction infects a node that does not understand the MAXTRANTIME parameter, or the node understands the MAXTRANTIME parameter but the parameter is not set, the timeout value for the transaction is determined by TRANTIME or by the timeout value passed in the tpbegin() call that started the transaction. If the TRANTIME or tpbegin() timeout value is exceeded, all Oracle Tuxedo nodes infected with the transaction—including the node that started the transaction—generate a TMS timeout message.
• If an interdomain transaction infects a node that understands the MAXTRANTIME parameter and the parameter is set for that node, the timeout value for the transaction is reduced to no greater than the MAXTRANTIME value on that node.

  If the TRANTIME or tpbegin() timeout value is less than or equal to MAXTRANTIME, the transaction-handling scenario becomes the one previously described.

  If the TRANTIME or tpbegin() timeout value is greater than MAXTRANTIME, the infected node reduces the timeout value for the transaction to MAXTRANTIME. If the MAXTRANTIME timeout value is exceeded, the infected node generates a TMS timeout message.

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).

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.

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
  
• Per TDomain Session Connection Policy
  

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.

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:

• For ON_DEMAND, the local domain gateway continually advertises services imported from a remote domain.
• For ON_STARTUP, the local domain gateway advertises services imported from a remote domain as long as a connection exists to the remote domain.
• For INCOMING_ONLY, the local domain gateway advertises services imported from a remote domain when the gateway receives an incoming connection or when a dmadmin connect command is issued.

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.

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:

• Automatic connection retries (ON_STARTUP only)
• Incoming connections
• Manual dmadmin connect command

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
  

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 acknowledgment to the server machine. If the server machine does not receive an acknowledgment 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.

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:

• LOCAL (relevant only to remote domain access points)
• NO (keepalive disabled)
• YES (keepalive enabled)

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:

• NO (default)
• YES

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

• LOCAL (default)
• NO
• YES

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

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.

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 must:

• Decide whether the application has been waiting an excessively long time to receive incoming messages.
• Decide what actions to take to determine whether the TCP connection is still open and that the machine and application at the other end of the connection are still running.

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 acknowledgment to the server application. If the server application does not receive an acknowledgment 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.

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:

• -1 (relevant only to remote domain access points)
• 0 (keepalive disabled)
• 1 <= value <= 2147483647 (keepalive enabled), in milliseconds, currently rounded up to the nearest second by the Domains software

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 acknowledgment 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.

• If DMKEEPALIVE is 0 (keepalive disabled), setting DMKEEPALIVEWAIT has no effect.
• If DMKEEPALIVE is enabled and DMKEEPALIVEWAIT is set to a value greater than DMKEEPALIVE, the local TDomain gateway will send more than one application-level keepalive message before the DMKEEPALIVEWAIT timer expires. This combination of settings is allowed.
• If DMKEEPALIVE is enabled and DMKEEPALIVEWAIT is set to 0, receiving an acknowledgment to a sent keepalive message is unimportant: any such acknowledgment is ignored by the local TDomain gateway. The local TDomain gateway continues to send keepalive messages every time the DMKEEPALIVE timer times out. Use this combination of settings to keep an idle connection open through a firewall.

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 second

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:

• 0 (default)
• 1 <= value <= 2147483647 in milliseconds, currently rounded up to the nearest second by the Domains software

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

• -1 (default)
• 0
• 1 <= value <= 2147483647 in milliseconds, currently rounded up to the nearest second by the Domains software

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

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.

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.

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.

   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.

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:

   *DM_TDOMAIN
   LOCAL1 NWADDR=“//primary:port”
   LOCAL1 NWADDR=“//backup:port”

2. If you are using transactions, you must copy the Domains transaction log manually to the backup machine.
3. The DMCONFIG files for the remote domains should include both network addresses specified in step 1.
4. Activate the GWADM and GWTDOMAIN server processes on the new machine. For details, see the following section.

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

• Command tmboot(1) with the -s command line option
• MIB (TM_MIB(5)) API

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

In this release, we introduce a new model, bypass-domain model, which describes the relationship among domains. A set of domains which interconnect with each other directly or indirectly and run on bypass-domain model constitute a bypass-domain group. Domains in the same bypass-domain group will have the following feature behaviors.

Running on bypass-domain model, the services that are configured as imported ones from other domains are registered to local bulletin board, clients find the provider of target service in the local bulletin board, and send the message to remote server directly. To facilitate that, all necessary information ("global resources") is shared among the nodes in bypass-domain group and must be accessed by all the domains in this bypass-domain group.

• Tuxedo tpcalls across domains are not performed through the GWTDOMAIN process in each domain any more.
• Unlike the mechanism of advertising/unadvertising performed by GWTDOMAIN, the imported services that are exported by remote domains are added to BB directly and invoked through RDMA queue address.
• An Oracle Tuxedo file system with fix file name "."+"DOMGLOBAL"+"_"+"BYPASSDOM_ID"+"_"+"BYPASSDOM_SEQ_NUM" in BYPASSDOM_SHARED_DIR specified directory is automatically created. It is the media of exchanging information between multiple domains.

  Note:

  Bypass domain ID is the logic bypass domain group name. Bypass domain sequence number is a number that identifies the domains within a domain group; it must be unique number within one group.
• GWTDOMAIN no longer participates transaction as a TMS; however, local domain takes the responsibility of importing necessary TMS service to BB so that transactions can be performed, as well as exchanging necessary information between two domains.
• GWTDOMAIN can work on either bypass domain model by default or non-bypass domain model by specifying THROUGHGATEWAY=Y in DMCONFIG.
• GWTDOMAIN explores the abilities of remote domain and determines whether this feature is able to be employed. GWTDOMAIN may work on both bypass domain model and non-bypass model, according to the opposite domain's setting. However, for the same connection, namely a certain remote domain gateway, it can only be either bypass-domain or traditional.
• The rule of remote service routing is a little different from non-bypass domain model. Basically, as imported services are registered in BB, the election of an imported service is the same as a local service, meaning the load balance algorithm implemented by GWTDOMAIN no longer takes effect.
• Bypass-domain model does not support security level ACL or MANDATORY_ACL with different security tokens across domains. If ACL or MANDATORY_ACL is specified in UBBCONFIG and ACL_POLICY in DMCONFIG is set to LOCAL, the two domains of which ACL_POLICY is specified automatically switch off their bypass domain feature.
• Event Broker is only provided as a non-bypass gateway, even if GWTDOMAIN is specified as bypass model.
• Even if exported by multiple GWTDOMAIN in one domain, a remote service is imported as one service in local domain.
• Even if imported by multiple GWTDOMAIN, a remote service is imported as one service in local domain.
• Inter-connection to WTC can only be under non-bypass domain.
• You cannot configure GWWS in UBBCONFIG when bypass domain is specified; otherwise, tmloadcf will report an error.

• If this feature is switched on, all machines in the domains must be upgraded to Tuxedo 12c Release 2 (12.1.3) on Exalogic.
• If this feature is switched on and transactions are involved in the applications, the transaction log (known as TLOG and DMTLOG) should be regenerated.

Only supports Linux platforms on Exalogic.

The following table lists the changed behaviors on Direct Cross-Domain Communication Leveraging RDMA.