1. Domains Component User's Guide
  2. Introduction to Administering Domains

4 Introduction to Administering Domains

The following sections explain how to administer an Oracle Tuxedo Domains environment:

4.1 Using Domains Run-Time Administrative Commands

To integrate the Domains component with an existing Oracle Tuxedo application, you add entries for domain gateway groups and gateway servers to the TUXCONFIG file. You can use either the tmconfig(1) or tmadmin(1) command to add a Domains configuration to a running Oracle Tuxedo application. You can also use tmadmin to list the information available in the bulletin board for domain gateway groups and individual domain gateways.

Once your Domains environment is configured and integrated, you can administer it dynamically using a set of administrative tools provided by the Domains component. For example, you can specify and modify the list of services that are accessible across applications. The Domains software preserves the characteristics of the Oracle Tuxedo programming interface (ATMI) and extends the scope of the ATMI so that clients can invoke services across domains. This functionality allows programmers to expand or partition applications without changing any application code.

The following figure illustrates the relationship between administrative commands and servers in the Domains administrative subsystem.

Figure 4-1 Domains Run-Time Administration


Domains Run-Time Administration Diagram

The Oracle Tuxedo Domains component offers the following administrative commands:

  • dmadmin(1) command, a generic administrative service—Enables administrators to configure, monitor, and tune domain gateway groups dynamically, and to update the Domains configuration file (BDMCONFIG) while the Oracle Tuxedo application is running. The command acts as a front-end process that translates administrative commands and sends service requests to the DMADMIN service, a generic administrative service advertised by the DMADM server. The DMADMIN service invokes the validation, retrieval, or update of functions provided in the DMADM server to maintain the BDMCONFIG file.
  • DMADM(5), the Domains administrative server—Provides the administrative processing required for updating the Domains configuration. This server acts as a back-end to the dmadmin command. It provides a registration service to domain gateway groups. This registration service is requested by GWADM servers as part of their initialization procedure. The registration service downloads the configuration information required by the requesting domain gateway group. The DMADM server maintains a list of registered domain gateway groups, and propagates to these groups any changes made to the configuration.
  • GWADM(5), the gateway administrative server—Registers with the DMADM server to obtain the configuration information used by the corresponding domain gateway group. The GWADM accepts queries from DMADM to obtain run-time statistics or to change the run-time options of the corresponding domain gateway group. Periodically, the GWADM server sends an “I-am-alive” message to the DMADM server. If no reply is received from the DMADM server, the GWADM server registers again. This mechanism makes sure the GWADM server always has the latest copy of the Domains configuration for its group.
  • GWTDOMAIN(5), the TDomain gateway server—Provides interoperability between two or more Oracle Tuxedo domains. 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.

    Note:

    For information about domain gateway types other than GWTDOMAIN, see Oracle Tuxedo Mainframe Adapters 12c Release 2 (12.2.2)
  • BDMCONFIG—the binary version of the Domains configuration file, which together with the TUXCONFIG file and factory_finder.ini file (CORBA only) contain all the configuration parameters that the Oracle Tuxedo software needs to create a Domains configuration.

Note:

You can also specify gateway parameters when a domain gateway group is booted using the CLOPT parameter, when the GWADM server is defined in the SERVERS section of the TUXCONFIG file.

Parent topic: Introduction to Administering Domains

4.2 Using the Administrative Interface, dmadmin(1)

dmadmin is an administrative interface to the DMADM and GWADM servers. The communication between the two servers is done via FML typed buffers. Administrators can use the dmadmin command in the following ways:

  • For the interactive administration of the information stored in the BDMCONFIG file and the different domain gateway groups running within a particular Oracle Tuxedo application.
  • To obtain statistics or other information gathered by domain gateway groups.
  • To change domain gateway group parameters.
  • To add (or update) information in the BDMCONFIG file.

Note:

You can delete information from the BDMCONFIG file at run time only if the deletions do not involve an active domain gateway group.

See Also:

dmadmin(1) in Oracle Tuxedo Command Reference

Parent topic: Introduction to Administering Domains

4.3 Using the Domains Administrative Server, DMADM(5)

4The Domains administrative server, DMADM(5), is an Oracle Tuxedo-supplied server that performs the following functions:

  • Supports run-time administration of the BDMCONFIG file
  • Maintains the BDMCONFIG file
  • Supports a list of registered domain gateway groups
  • Propagates run-time configuration changes to the registered domain gateway groups

The DMADM server advertises two services:

  • DMADMIN, which is used by the dmadmin command and the GWADM server.
  • A service called DMADM_ svrid , where srvid is the appropriate server ID for the service. Registered GWADM servers use DMADM_ svrid for specific administrative functions (for example, to refresh the domain gateway group configuration information or to signal that a GWADM is still registered).

The DMADM server must be defined in the SERVERS section of the TUXCONFIG file as a server running within a group (for example, DMADMGRP). There should be only one instance of the DMADM server in this group.

See Also:

Parent topic: Introduction to Administering Domains

4.4 Using the Gateway Administrative Server, GWADM(5)

The gateway administrative server, GWADM(5), is an Oracle Tuxedo-supplied server that provides administrative functions for a domain gateway group. The main functions of the GWADM server include:

  • Getting Domains configuration information from the DMADM server, and accepting queries from dmadmin. The GWADM server gets the domain gateway group configuration information by registering with the DMADM server. The GWADM server then makes the configuration available to gateways by storing the information in shared memory.
  • Providing administrative functionality for a domain gateway group, for example, by accepting queries from dmadmin for run-time statistics or by changing the run-time parameters of the domain gateway group.
  • Providing transaction logging functionality for a domain gateway group. The GWADM server determines which transactions need to be logged by reading information stored in shared memory. When the GWADM server is booted, it scans the log to see whether any transactions need to be recovered, and then reconstructs the transaction information in shared memory. The gateway server scans the information in shared memory and performs recovery for the corresponding transactions. The recovery procedure is performed asynchronously with new incoming or outgoing requests received by the domain gateway group.

The GWADM server advertises a service name based on the local domain access point name (as specified in the DM_LOCAL section of the BDMCONFIG file) associated with the domain gateway group to which the GWADM server belongs. The dmadmin command uses this service to retrieve information from all active domain gateway groups or from a specific domain gateway group.

The GWADM server must be defined in the SERVERS section of the TUXCONFIG file. It should not be part of the MSSQ used by the gateways associated with the group. It must be the first server booted within the domain gateway group; that is, either (a) it must have a SEQUENCE number, or (b) it must be defined ahead of the gateway servers.

The GWADM server requires the existence of a DMADM server. Specifically, a DMADM server must be booted before that GWADM is booted.

The GWADM server must create the shared memory required by the domain gateway group to populate the configuration tables with information received from the DMADM server. The GWADM server uses IPC_PRIVATE with shmget and stores the ipckey returned in the shmid field of its registry entry in the bulletin board. Gateways can obtain the ipckey by retrieving the GWADM registry entry and checking the shmid field.

See Also:

Parent topic: Introduction to Administering Domains

4.5 Using the Domain Gateway Server

A domain gateway server provides connectivity to remote domain gateway servers, and can communicate with one or more remote gateways simultaneously. A gateway advertises the services imported to an Oracle Tuxedo application and controls access to the local services exported by the application. You define your application’s exported and imported services in the Domains configuration file (DMCONFIG). Use dmadmin to dynamically configure, monitor, and tune domain gateway groups.

See Also:

Parent topic: Introduction to Administering Domains

4.5.1 Tuning the Performance of the Domain Gateway

Oracle Tuxedo 9.x improves the GWTDOMAIN gateway performance while also keeping compatibility with other types of /Domain gateways. It limits most of the performance to the threaded platforms. It also allows other types of /Domain gateways to take advantage of this feature in the enhanced Common Gateway Architecture with simple program changes.

Many factors may affect performance of applications across multiple domains. For example:

  • Service processing time
  • Database transactions
  • Message buffer size
  • Security facilities, such as Link Level Encryption
  • Network transmission speed

Therefore, in order to observe achieved Domain Gateway performance improvement, the application has to minimize the above-mentioned factors. Otherwise the performance improvement for the gateway may not be significant.

Some suggestions for performance testing this feature are listed below:

  • Many clients send a request to a single remote service. The size of the message is small (less than a few K bytes.
  • Many clients send a request to different remote services or use load balancing to distribute service requests. In this case, the message size can be larger.

Note:

As a prerequisite, service processing time on the server side should not be time-consuming. The total response time contains both gateway processing time and service processing time. If service processing time is quite long, the performance improvement for the gateway is submerged.

Parent topic: Using the Domain Gateway Server

4.6 Managing Transactions in a Domains Environment

Application programmers can request the execution of remote services within a transaction. Also, users of remote domains can request local services to be executed within a transaction. Domains, therefore, coordinates the mapping of remote transactions to local transactions, and the sane termination (commitment or rollback) of these transactions.

The Oracle Tuxedo system architecture uses a separate process, the Transaction Manager Server (TMS), to coordinate the commitment and recovery of transaction branches accessing a particular group. In a Domains environment, however, this architecture would require extra messages from the gateway to the TMS server to process a commitment for an incoming transaction. To simplify the Domains architecture and to reduce the number of messages, the TMS code is integrated with the gateway code. Thus, domain gateways can process the transaction protocol used by the Oracle Tuxedo system. The Oracle Tuxedo transaction protocol requires that the domain gateway group advertise the TMS service, which is done when the first gateway is booted. Once the TMS service is advertised, any transaction control messages directed to the domain gateway group are placed on the gateway’s queue.

Domain gateway groups should be defined in the TUXCONFIG file without the TMSNAME, TMSCOUNT , OPENINFO, and CLOSEINFO parameters. These four parameters apply only to groups that use an XA-compliant resource manager, which domain gateways do not use.

The commitment protocol across domains is strictly hierarchical. It is not possible to flatten the transaction tree because the structure of the transaction tree is not fully known by every domain; a superior knows only its immediately subordinate domains. Flattening the tree would also require the root domain to be fully connected to all domains participating in the transaction.

Domain gateways provide four capabilities that you can use to manage transactions. These capabilities are described in the following sections:

Parent topic: Introduction to Administering Domains

4.6.1 Using the TMS Capability Across Domains

In the Oracle Tuxedo system, the TMS is a special server that is implicitly associated with server groups that use X/Open XA-compliant resource managers. The TMS server releases application servers from the delays associated with the distributed 2-phase commitment protocol. TMS servers coordinate the commitment of a transaction via special service requests to the TMS service, which is offered by all TMS servers.

In a Domains environment, GWTDOMAIN gateways are not associated with an XA-compliant resource manager. The Transaction Processing Working Group (TPWG) of X/Open has proposed an advanced XA interface. This interface is not used in the Oracle Tuxedo system because the interface does not match the highly asynchronous and non-blocking model required by the gateway. While domain gateways do not use a separate TMS server, they do offer the Transaction Manager Servers capability, which allows gateways to coordinate the 2-phase commitment of transactions executed across domains.

Domain gateways coordinate transactions across domains in the following manner:

  1. Domain gateways advertise the TMS service and perform all operations associated with that service. Messages sent to this service are placed on the queue used by the appropriate domain gateway group, and the gateways manage the transactions associated with the group.
  2. A gateway can act as a subordinate of transactions coordinated by another group within the domain. In this case, the gateway is a superior of the transaction branches executed in other remote domains. When acting as a subordinate of a transaction coordinated by a remote domain, the gateway also acts as the coordinator for all groups in the local domain accessed by the transaction. The gateway, acting as both subordinate and coordinator, is illustrated in the following figure.

    Figure 4-2 The Domain Gateway as Subordinate/Coordinator of Another Domain Gateway Group


    The Domain Gateway as Subordinate/Coordinator of Another Domain Gateway Group Diagram

  3. As a coordinator of transactions within the domain, the gateway manages the commitment of a transaction for a particular client. This is illustrated in the following figure.

    Figure 4-3 Client Commit Managed by a Domain Gateway


    Client Commit Managed by a Domain Gateway Diagram

  4. Gateways manage transaction commitment for a particular client or for a server that uses the forwarding service with the AUTOTRAN capability. When this combination is used, the last server in the forward chain (the domain gateway) issues the commit and becomes the coordinator of the transaction. (A domain gateway always acts as the last server in a forward chain.)
  5. Gateways automatically start and terminate transactions for remote services specified with the AUTOTRAN capability. This capability is required when an the application administrator wants to enforce reliable network communication with remote services. Administrators can specify this capability by setting the AUTOTRAN parameter to Y in the corresponding remote service definition.
  6. Gateways map the Oracle Tuxedo system transaction protocol to the networking transaction protocol used for interoperation with remote domains. How this mapping is done depends on which instantiation of domain gateway you are using: TDomain and SNA.

See Also:

For more information, see the DM_IMPORT section of DMCONFIG(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

Parent topic: Managing Transactions in a Domains Environment

4.6.2 Using GTRID Mapping in Transactions

In the Oracle Tuxedo system, a transaction tree is a 2-level tree where the root is the domain gateway group coordinating a global transaction and branches are involved in the transaction. Each group performs its part of the global transaction independently from the parts performed by other groups. Each group, therefore, implicitly defines a transaction branch. The Oracle Tuxedo system, through TMS servers, coordinates the completion of the global transaction, making sure each branch is completed.

A GTRID is a Global Transaction Identifier. GTRID mapping defines how to construct a transaction tree that crosses domain boundaries. You specify GTRIDs using the MAXGTT parameter in the RESOURCES section of the Oracle Tuxedo configuration file.

Parent topic: Managing Transactions in a Domains Environment

4.6.2.1 Defining Tightly-coupled and Loosely-coupled Relationships

In the X/Open DTP Model, a Transaction Manager Server can construct transaction trees by defining either tightly-coupled or loosely-coupled relationships with a resource manager (RM) by the way it interprets the transaction identifiers (XIDs) used by the XA interface.

A tightly-coupled relationship is one in which a single transaction identifier, XID, is used by all processes participating in a single global transaction, accessing a single RM. This relationship maximizes data sharing between processes; XA-compliant RMs expect to share locks for resources used by processes having the same XID. The Oracle Tuxedo system achieves the tightly-coupled relationship via the group concept; that is, all work done by a group on behalf of a given global transaction belongs to the same transaction branch; all the processes executed by the group are given the same XID.

In a loosely-coupled relationship, the TMS generates a transaction branch for each part of the work in support of the global transaction. The RM handles each transaction branch separately; there is no sharing of data or of locks between the transaction branches. Deadlocks between transaction branches can occur and result in the rollback of a global transaction. In the Oracle Tuxedo application, when different groups participate in a single global transaction, each group defines a separate transaction branch, which results in a loosely-coupled relationship.

4.6.2.2 Global Transactions Across Domains

There are several differences between global transactions in a single Oracle Tuxedo application and global transactions across domains. The first difference is that in the Domains framework, the transaction tree cannot be flattened to a 2-level tree. There are two reasons for this:

  • The transaction may involve more domains than can be known from the root domain (where the transaction is controlled), so the structure of the transaction tree cannot be fully known.
  • If a transaction tree is flattened to two levels, the root domain must be connected directly to all domains in the transaction.

This means that the commitment protocol across domains must be hierarchical. Even a loopback service request defines a new branch in the transaction tree.

Note:

A loop back request goes to another domain and then comes back to be processed in the original domain. For example, Domain A requests a service of Domain B. The service in Domain B requests another service in Domain A. The transaction tree has two branches at the network level: a branch b1 from A to B and a branch b2 from B to A. Domain A cannot commit the work done on branch b2 before receiving commit instructions from B.

The structure of a transaction tree for global transactions across domains also depends on the distributed transaction processing protocol used by a relevant domain gateway instantiation.

This property, however, applies only to outgoing service requests (that is, service requests sent from the root domain to subordinate domains). It cannot be applied to incoming service requests.

The TDomain instantiation tries to optimize GTRID mapping by implementing a tightly-coupled relationship. In TDomain, multiple service requests issued on behalf of the same global transaction are mapped to the same network transaction branch. Therefore, incoming service requests can be mapped to a single Oracle Tuxedo transaction. However, the hierarchical structure of interdomain communication and the interdomain transaction tree must still be maintained.

The optimization that TDomain introduces applies only to a single domain. When two or more domains are involved in a transaction, the network transaction tree contains at least one branch per domain interaction. Hence, across domains, the network transaction tree remains loosely-coupled. There are as many branches as there are domains involved in the transaction (even if all the branches access the same resource manager instance).

Domain gateway groups implement a loosely-coupled relationship because they generate different transaction branches for interdomain transactions.

4.6.2.3 Example of a Service Request Graph Generating Local and Remote Requests

The following Figure illustrates the service request graph for a client that generates three service requests: one local request (r0) and two remote requests (r2 and r3). Request r0 goes to a local service (Svc0), which generates another remote service request (r1). Request r1 goes to remote service Rsvc1, which issues a loop back service request r4 to local service Svc4. Svc0 and Svc4 are executed in different groups (G0 and G4). The domain gateway is executed within another group (GW), and the remote services Rscv1, Rsvc2, and Rsvc3 are executed in another domain (Domain B).

Figure 4-4 Service Request Graph


Service Request Graph Diagram

4.6.2.4 Transaction Trees for Oracle Tuxedo Domains

The following figure shows the transaction tree for Oracle Tuxedo domains. It is assumed, in these figures, that both Domain A and Domain B are Oracle Tuxedo system applications.

The TDomain instantiation provides a tightly-coupled integration that solves this deadlock problem by minimizing the number of transaction branches required in the interoperation between two domains. The corresponding transaction tree is shown in the following figure.

Figure 4-5 Transaction Tree for TDomain Environment


Transaction Tree for TDomain Environment Diagram

Notice that the gateway still must perform mappings between an Oracle Tuxedo system transaction and a network transaction, and that the hierarchical nature of the communication between domains must be strictly enforced. The diagram shows that requests r1, r2, and r3 are mapped to a single TDomain transaction branch. Therefore, on Domain B only one Oracle Tuxedo system transaction needs to be generated; T2 represents this mapping and the graph shows domain gateway group GW on Domain B coordinating group G1. Request r4 is mapped to identifier T2 on Domain B, but TDomain will generate a new branch in its transaction tree (r4: B to A'). Because this is a new transaction branch on Domain A, the gateway generates a new mapping, T3, to a new Oracle Tuxedo system transaction. The graph shows that domain gateway group GW on Domain A also coordinates group G4. Hence, the hierarchical nature of interdomain communication is fully enforced with this mapping: group G4 cannot commit before group G1.

4.6.2.5 Summary of Domains Transaction Management

Domains transaction management can be summarized as follows:

  • Gateways generate mappings from an Oracle Tuxedo system transaction to a network transaction. A new mapping is generated for each Oracle Tuxedo system transaction and each incoming network transaction branch.
  • Each instantiation of domain gateway (TDomain and SNA) handles its own representation of the network transaction tree. All instantiations observe the hierarchical nature of the interdomain communication.

4.6.3 Using Logging to Track Transactions

Logging is used to keep track of the progress of a 2-phase commit protocol. The information stored in the log is used to make sure a transaction is completed in the event of a network failure or machine crash.

To ensure completion of transactions across domains, domain gateways log the mapping between local and remote identifiers. Along with this information, the Domains transaction management facility records the decisions made during different phases of the commitment protocol, and any information available about the remote domains involved in the transaction. The information is referred to as a blob (binary large object) and is kept in the same log record as the commit information to make recovery easier.

Domains log records have a different structure from the log records stored in the Oracle Tuxedo system TLOG. TLOG records are fixed in size and are stored in a single page. Domains log records vary in size; more than one page may be required to store the record. The Domains logging mechanism, DMTLOG, has the capability of storing variable-size log records.

When a TMS is the superior of a domain gateway group, the Oracle Tuxedo TLOG is still required to coordinate the commitment.

Logging is performed by the GWADM administrative server. The request for a log write is made by the GWTDOMAIN process, but the actual log write is performed by the GWADM process.

You must create a log called DMTLOG for each domain gateway group. The DMTLOG files are defined in the DM_LOCAL section of the DMCONFIG file. To create a DMTLOG file, add an entry for the DMTLOGDEV parameter:

DMTLOGDEV=string

where string is the name of the log file. In addition, you cam set one or both of the two optional parameters:

  • DMTLOGNAME= identifier
  • DMTLOGSIZE= numeric

Administrators also have the option of using the run-time administration utility (dmadmin) to create a DMTLOG.

If a DMTLOG has not been created when a domain gateway group is booted, the gateway server automatically creates the log, based on information in the BDMCONFIG file.

Until a logging device is specified in the BDMCONFIG file, a domain gateway group cannot process requests in transaction mode and the domain gateway group cannot offer the TMS service.

To coordinate the commit protocol, domain gateways require the following two log records:

  • Ready record—a ready record is a file created by a gateway acting as a leaf or intermediate machine in a transaction tree. It records information about the superior and subordinate remote domains involved in the transaction. A ready record indicates that all subordinates of the domain gateway group logging the record have been prepared.
  • Commit record—a commit record documents that a transaction has been committed. A domain gateway creates a commit record as the coordinator of a particular transaction tree.

When a transaction has been committed on all machines, these logs for the transaction are removed.

Heuristic log records persist until they are explicitly removed by the administrator. This persistence is required to provide the correct information during recovery after a crash, and to provide diagnostic information for administrators.

The administrator uses the forgettran command (run with tmadmin(1)) to remove heuristic records when they are no longer needed.

Note:

Parent topic: Managing Transactions in a Domains Environment

4.6.4 Recovering Failed Transactions

When a domain gateway group is booted, the gateway server performs an automatic warm-start of the DMTLOG. The warm-start includes scanning the log to see if any transactions were not completed. If incomplete transactions are found, action is taken to complete them.

In the case of heuristic decisions, if a domain gateway group is a subordinate of a local TMS and a heuristic decision has been indicated, the TMS generates a TMS_STATUS message to learn the final decision:

  • If a gateway fails, then it cleans up after itself when it is restarted (this is called a hot-start). The gateway rolls back all undecided transactions in which it was involved.
  • If a communication line failure occurs and the first phase of the commit has not been completed, the gateway rolls back the transactions associated with that connection.

Parent topic: Managing Transactions in a Domains Environment