Administering Transactions

This topic includes the following sections:

•	Modifying the UBBCONFIG File to Accommodate Transactions

•	Modifying the Domain Configuration File to Support Transactions (Oracle Tuxedo CORBA Servers)

•	Sample Distributed Application Using Transactions

Before you begin, you should read Chapter 1, “Introducing Transactions.”

Notes:

The administrative information applies whether you are using the Bootstrap object or the CORBA interoperable Naming Service (INS) to obtain initial object references to the Oracle Tuxedo ORB.

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.

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

Modifying the UBBCONFIG File to Accommodate Transactions

This topic includes the following sections:

•	Summary of Steps

•	Step 1: Specify Application-wide Transactions in the RESOURCES Section

•	Step 2: Create a Transaction Log (TLOG)

•	Step 3: Define Each Resource Manager (RM) and the Transaction Manager Server in the GROUPS Section

•	Step 4: Enable an Interface to Begin a Transaction

Summary of Steps

To accommodate transactions, you must modify the RESOURCES, MACHINES, GROUPS, and the INTERFACES or SERVICES sections of the application’s UBBCONFIG file in the following ways:

•	In the RESOURCES section, specify the application-wide number of allowed transactions and the value of the commit control flag.

•	In the MACHINES section, create the TLOG information for each machine.

•	In the GROUPS section, indicate information about each resource manager and about the Transaction Manager Server.

•	In the INTERFACES section (for Oracle Tuxedo CORBA applications only) or the SERVICES section (for Oracle Tuxedo ATMI applications only), enable the automatic transaction option.

For instructions about modifying these sections in the UBBCONFIG file, see “Creating a Configuration File” in the Setting Up an Oracle Tuxedo Application.

Step 1: Specify Application-wide Transactions in the RESOURCES Section

Table 5‑1 provides a description of transaction-related parameters in the RESOURCES section of the configuration file.

 

Table 5‑1 Transaction-related Parameters in the RESOURCES Section 

Parameter	Meaning
MAXGTT	Limits the total number of global transaction identifiers (GTRIDs) allowed on one machine at one time. The maximum value allowed is 2048, the minimum is 0, and the default is 100. You can override this value on a per-machine basis in the MACHINES section. Entries remain in the table only while the global transaction is active, so this parameter has the effect of setting a limit on the number of simultaneous transactions.
CMTRET	Specifies the initial setting of the TP_COMMIT_CONTROL characteristic. The default is COMPLETE. Following are its two settings: • LOGGED—the TP_COMMIT_CONTROL characteristic is set to TP_CMT_LOGGED, which means that tpcommit() returns when all the participants have successfully precommitted. • COMPLETE—the TP_COMMIT_CONTROL characteristic is set to TP_CMT_COMPLETE, which means that tpcommit() will not return until all the participants have successfully committed. Note: You should consult with the RM vendors to determine the appropriate setting. If any RM in the application uses the late commit implementation of the XA standard, the setting should be COMPLETE. If all the resource managers use the early commit implementation, the setting should be LOGGED for performance reasons. (You can override this setting with tpscmt().)

Step 2: Create a Transaction Log (TLOG)

This section discusses creating a transaction log (TLOG), which refers to a log in which information on transactions is kept until the transaction is completed.

Creating the UDL

The Universal Device List (UDL) is like a map of the Oracle Tuxedo file system. The UDL gets loaded into shared memory when an application is booted. To create an entry in the UDL for the TLOG device, create the UDL on each machine using global transactions. If the TLOGDEVICE is mirrored between two machines, it is unnecessary to do this on the paired machine. The Bulletin Board Liaison (BBL) then initializes and opens the TLOG during the boot process.

To create the UDL, enter a command using the following format, before the application has been booted:

tmadmin -c crdl -z config -b blocks

where:

 

-z config	Specifies the full pathname for the device where you should create the UDL.
-b blocks	Specifies the number of blocks to be allocated on the device.
config	Should match the value of the TLOGDEVICE parameter in the MACHINES section of the UBBCONFIG file.

Note:

In general, the value that you supply for blocks should not be less than the value for TLOGSIZE. For example, if TLOGSIZE is specified as 200 blocks, specifying -b 500 would not cause a degradation.

For more information about storing the TLOG, see Installing the Oracle Tuxedo System.

Defining Transaction-related Parameters in the MACHINES Section

You can define a global transaction log (TLOG) using several parameters in the MACHINES section of the UBBCONFIG file. You must manually create the device list entry for the TLOGDEVICE on each machine where a TLOG is needed. You can do this either before or after TUXCONFIG has been loaded, but it must be done before the system is booted.

Note:

If you are not using transactions, the TLOG parameters are not required.

Table 5‑2 provides a description of transaction-related parameters in the MACHINES section of the configuration file.

 

Table 5‑2 Transaction-related Parameters in the MACHINES Section 

Parameter	Meaning
TLOGNAME	The name of the DTP transaction log for this machine.
TLOGDEVICE	Specifies the Oracle Tuxedo or Oracle Tuxedo file system that contains the DTP transaction log (TLOG) for this machine. If this parameter is not specified, the machine is assumed not to have a TLOG. The maximum string value length is 64 characters.
TLOGSIZE	The size of the TLOG file in physical pages. Its value must be between 1 and 2048, and its default is 100. The value should be large enough to hold the number of outstanding transactions on the machine at a given time. One transaction is logged per page. The default should suffice for most applications.
TLOGOFFSET	Specifies the offset in pages from the beginning of TLOGDEVICE to the start of the VTOC that contains the transaction log for this machine.The number must be greater than or equal to 0 and less than the number of pages on the device. The default is 0. TLOGOFFSET is rarely necessary. However, if two VTOCs share the same device or if a VTOC is stored on a device (such as a file system) that is shared with another application, you can use TLOGOFFSET to indicate a starting address relative to the address of the device.

Creating the Domains Transaction Log (Oracle Tuxedo ATMI Servers Only)

This section applies to the ATMI servers only.

You can create the Domains transaction log before starting the Domains gateway group by using the following command:

dmadmin(1) crdmlog (crdlog) -d local_domain_name

Create the Domains transaction log for the named local domain on the current machine (the machine on which dmadmin is running). The command uses the parameters specified in the DMCONFIG file. This command fails if the named local domain is active on the current machine or if the log already exists. If the transaction log has not been created, the Domains gateway group creates the log when it starts up.

Step 3: Define Each Resource Manager (RM) and the Transaction Manager Server in the GROUPS Section

Additions to the GROUPS section fall into two categories:

•	Defining the Transaction Manager Servers that perform most of the work that controls global transactions:

•	The TMSNAME parameter specifies the name of the server executable.

•	The TMSCOUNT parameter specifies the number of such servers to boot (the minimum is 2, the maximum is 10, and the default is 3).

A NULL Transactional Manager Server does not communicate with any resource manager. It is used to exercise an application’s use of the transactional primitives before actually testing the application in a recoverable, real environment. This server is named TMS and it simply begins, commits, or terminates without talking to any resource manager.

•	Defining opening and closing information for each resource manager:

•	OPENINFO is a string with information used to open a resource manager.

•	CLOSEINFO is used to close a resource manager.

Sample GROUPS Section

The following sample GROUPS section derives from the bankapp banking application:

BANKB1 GRPNO=1 TMSNAME=TMS_SQL TMSCOUNT=2
OPENINFO=”TUXEDO/SQL:<APPDIR>/bankdl1:bankdb:readwrite”

Table 5‑3 describes the transaction values specified in this sample GROUPS section.

 

Table 5‑3 Transaction Values in the GROUPS Section of a Sample UBBCONFIG File 

Transaction Value	Meaning
BANKB1 GRPNO=1 TMSNAME=TMS_SQL\ TMSCOUNT=2	Contains the name of the Transaction Manager Server (TMS_SQL) and the number (2) of these servers to be booted in the group BANKB1
TUXEDO/SQL	Published name of the resource manager
<APPDIR>/bankdl1	Includes a device name
bankdb	Database name
readwrite	Access mode

Characteristics of the TMSNAME, TMSCOUNT, OPENINFO, and CLOSEINFO Parameters

Table 5‑4 lists the characteristics of the TMSNAME, TMSCOUNT, OPENINFO, and CLOSEINFO parameters.

 

Table 5‑4 Characteristics of the TMSNAME, TMSCOUNT, OPENINFO, and CLOSEINFO Parameters 

Parameter	Characteristics
TMSNAME	Name of the Transaction Manager Server executable. Required parameter for transactional configurations. TMS is a NULL Transactional Manager Server.
TMSCOUNT	Number of Transaction Manager Servers (must be between 2 and 10). Default is 3.
OPENINFO CLOSEINFO	Represents information to open or close a resource manager. Content depends on the specific resource manager. Starts with the name of the resource manager. Omission means the resource manager needs no information to open.

Step 4: Enable an Interface to Begin a Transaction

To enable an interface to begin a transaction, you change different sections in the UBBCONFIG file, depending on whether you are configuring an Oracle Tuxedo CORBA server or Oracle Tuxedo ATMI server.

•	Changing the INTERFACES Section (Oracle Tuxedo CORBA Servers)

•	Changing the SERVICES Section (Oracle Tuxedo ATMI Servers)

Changing the INTERFACES Section (Oracle Tuxedo CORBA Servers)

The INTERFACES section in the UBBCONFIG file supports Oracle Tuxedo CORBA interfaces:

•

For each CORBA interface, set AUTOTRAN to Y if you want a transaction to start automatically when an operation invocation is received. AUTOTRAN=Y has no effect if the interface is already in transaction mode. The default is N. The effect of specifying a value for AUTOTRAN depends on the transactional policy specified by the developer in the Implementation Configuration File (ICF) for the interface. This transactional policy will become the transactional policy attribute of the associated T_IFQUEUE MIB object at run time. The only time this value affects the behavior of the application is if the developer specified a transaction policy of optional.

Note:

To work properly, this feature depends on collaboration between the system designer and the administrator. If the administrator sets this value to Y without prior knowledge of the transaction policy defined by the developer in the interface’s ICF, the actual run time effect of the parameter might be unknown.

•

If AUTOTRAN is set to Y, you must set the TRANTIME parameter, which specifies the transaction timeout, in seconds, for the transactions to be created. The value must be greater than or equal to zero and must not exceed 2,147,483,647 (231 - 1, or about 70 years). A value of zero implies there is no timeout for the transaction. (The default is 30 seconds.)

Table 5‑5 describes the characteristics of the AUTOTRAN, TRANTIME, and FACTORYROUTING parameters.

 

Table 5‑5 Characteristics of the AUTOTRAN, TRANTIME, and FACTORYROUTING Parameters 

Parameter	Characteristics
AUTOTRAN	• Makes an interface the initiator of a transaction. • To work properly, it is dependent on collaboration between the system designer and the system administrator. If the administrator sets this value to Y without prior knowledge of the ICF transaction policy set by the developer, the actual run-time effort of the parameter might be unknown. • The only time this value affects the behavior of the application is if the developer specified a transaction policy of optional. • If a transaction already exists, a new one is not started. • Default is N.
TRANTIME	• Represents the timeout for the AUTOTRAN transactions. • Valid values are between 0 and 231 - 1, inclusive. • Zero (0) represents no timeout. • Default is 30 seconds.
FACTORYROUTING	• Specifies the name of the routing criteria to be used for factory-based routing for this CORBA interface. • You must specify a FACTORYROUTING parameter for interfaces requesting factory-based routing.

Changing the SERVICES Section (Oracle Tuxedo ATMI Servers)

The following are three transaction-related features in the SERVICES section:

•

If you want a service (instead of a client) to begin a transaction, you must set the AUTOTRAN flag to Y. This is useful if the service is not needed as part of any larger transaction, and if the application wants to relieve the client of making transaction decisions. If the service is called when there is already an existing transaction, this call becomes part of it. (The default is N.)

Note:

Generally, clients are the best initiators of transactions because a service has the potential of participating in a larger transaction.

•

If AUTOTRAN is set to Y, you must set the TRANTIME parameter, which is the transaction timeout, in seconds, for the transactions to be created. The value must be greater than or equal to 0 and must not exceed 2,147,483,647 (231 - 1, or about 70 years). A value of zero implies there is no timeout for the transaction. (The default is 30 seconds.)

•	You must specify a ROUTING parameter for transactions that request data-dependent routing.

Table 5‑6 describes the characteristics of the AUTOTRAN, TRANTIME, and ROUTING parameters:

 

Table 5‑6 Characteristics of the AUTOTRAN, TRANTIME, and ROUTING Parameters 

Parameter	Characteristics
AUTOTRAN	Makes a service the initiator of a transaction. Relieves the client of the transactional burden. If a transaction already exists, a new one is not started. Default is N.
TRANTIME	Represents the timeout for the AUTOTRAN transactions. Valid values are between 0 and 231 - 1, inclusive. 0 represents no timeout. Default is 30 seconds.
ROUTING	Points to an entry in the ROUTING section where data-dependent routing is specified for transactions that request this service.

Modifying the Domain Configuration File to Support Transactions (Oracle Tuxedo CORBA Servers)

This topic includes the following sections:

•	Characteristics of the DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRDTRAN, and MAXTRAN Parameters

•	Characteristics of the AUTOTRAN and TRANTIME Parameters (Oracle Tuxedo CORBA and ATMI Servers)

To enable transactions across domains, you need to set parameters in both the DM_LOCAL_DOMAINS and the DM_REMOTE_SERVICES sections of the Domains configuration file (DMCONFIG). Entries in the DM_LOCAL_DOMAINS section define local domain characteristics. Entries in the DM_REMOTE_SERVICES section define information on services that are imported and that are available on remote domains.

Characteristics of the DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRDTRAN, and MAXTRAN Parameters

The DM_LOCAL_DOMAINS section of the Domains configuration file identifies local domains and their associated gateway groups. This section must have an entry for each gateway group (local domain). Each entry specifies the parameters required for the Domains gateway processes running in that group.

Table 5‑7 provides a description of the five transaction-related parameters in this section: DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRDTRAN, and MAXTRAN.

 

Table 5‑7 Characteristics of the DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRDTRAN, and MAXTRAN Parameters 

Parameter	Characteristics
DMTLOGDEV	Specifies the Oracle Tuxedo file system that contains the Domains transaction log (DMTLOG) for this machine. The DMTLOG is stored as an Oracle Tuxedo VTOC table on the device. If this parameter is not specified, the Domains gateway group is not allowed to process requests in transaction mode. Local domains running on the same machine can share the same DMTLOGDEV file system, but each local domain must have its own log (a table in the DMTLOGDEV) named as specified by the DMTLOGNAME keyword.
DMTLOGNAME	Specifies the name of the Domains transaction log for this domain. This name must be unique when the same DMTLOGDEV is used for several local domains. If a value is not specified, the value defaults to the string DMTLOG. The name must contain 30 characters or less.
DMTLOGSIZE	Specifies the numeric size of the Domains transaction log for this machine (in pages). It must be greater than zero and less than the amount of available space on the Oracle Tuxedo file system. If a value is not specified, the value defaults to 100 pages. Note: The number of domains in a transaction determine the number of pages you must specify in the DMTLOGSIZE parameter. One transaction does not necessarily equal one log page.
MAXRDTRAN	Specifies the maximum number of domains that can be involved in a transaction. It must be greater than zero and less than 32,768. If a value is not specified, the value defaults to 16.
MAXTRAN	Specifies the maximum number of simultaneous global transactions allowed on this local domain. It must be greater than or equal to zero, and less than or equal to the MAXGTT parameter specified in the TUXCONFIG file. If not specified, the default is the value of MAXGTT.

Characteristics of the AUTOTRAN and TRANTIME Parameters (Oracle Tuxedo CORBA and ATMI Servers)

The DM_REMOTE_SERVICES section of the Domains configuration file identifies information on services imported and available on remote domains. Remote services are associated with a particular remote domain.

Table 5‑8 describes the two transaction-related parameters in this section: AUTOTRAN and TRANTIME.

 

Table 5‑8 Characteristics of the AUTOTRAN and TRANTIME Parameters 

Parameter	Characteristics
AUTOTRAN	Used by gateways to automatically start/terminate transactions for remote services. This capability is required if you want to enforce reliable network communication with remote services. You specify this capability by setting the AUTOTRAN parameter to Y in the corresponding remote service definition.
TRANTIME	Specifies the default timeout value in seconds for a transaction automatically started for the associated service. The value must be greater than or equal to zero, and less than 2147483648. The default is 30 seconds. A value of zero implies the maximum timeout value for the machine.

Sample Distributed Application Using Transactions

This topic includes the following sections:

•	RESOURCES Section

•	MACHINES Section

•	GROUPS and NETWORK Sections

•	SERVERS, SERVICES, and ROUTING Sections

This topic describes a sample configuration file for a sample CORBA application that enables transactions and distributes the application over three sites. The application includes the following features:

•	Data-dependent routing on ACCOUNT_ID.

•	Data distributed over three databases.

•	BRIDGE processes communicating with the system via the ATMI interface.

•	System administration from one site.

The configuration file includes seven sections: RESOURCES, MACHINES, GROUPS, NETWORK, SERVERS, SERVICES, and ROUTING.

RESOURCES Section

The RESOURCES section shown in Listing 5‑1 specifies the following parameters:

•	MAXSERVERS, MAXSERVICES, and MAXGTT are less than the defaults. This makes the Bulletin Board smaller.

•	MASTER is SITE3 and the backup master is SITE1.

•	MODEL is set to MP and OPTIONS is set to LAN, MIGRATE. This allows a networked configuration with migration.

•	BBLQUERY is set to 180 and SCANUNIT is set to 10. This means that DBBL checks of the remote BBLs are done every 1800 seconds (one half hour).

Listing 5‑1 Sample RESOURCES Section

*RESOURCES
#
IPCKEY 99999
UID 1
GID 0
PERM 0660
MAXACCESSERS 25
MAXSERVERS 25
MAXSERVICES 40
MAXGTT 20
MASTER SITE3, SITE1
SCANUNIT 10
SANITYSCAN 12
BBLQUERY 180
BLOCKTIME 30
DBBLWAIT 6
OPTIONS LAN, MIGRATE
MODEL MP
LDBAL Y

 

MACHINES Section

The MACHINES section shown in Listing 5‑2 specifies the following parameters:

•	TLOGDEVICE and TLOGNAME are specified, which indicate that transactions will be done.

•	The TYPE parameters are all different, which indicates that encode/decode will be done on all messages sent between machines.

Listing 5‑2 Sample MACHINES Section

*MACHINES
Gisela       LMID=SITE1
              TUXDIR=”/usr/tuxedo”
              APPDIR=”/usr/home”
              ENVFILE=”/usr/home/ENVFILE”
              TLOGDEVICE=”/usr/home/TLOG”
              TLOGNAME=TLOG
              TUXCONFIG=”/usr/home/tuxconfig”
              TYPE=”3B600”

romeo        LMID=SITE2
              TUXDIR=”/usr/tuxedo”
              APPDIR=”/usr/home”
              ENVFILE=”/usr/home/ENVFILE”
              TLOGDEVICE=”/usr/home/TLOG”
              TLOGNAME=TLOG
              TUXCONFIG=”/usr/home/tuxconfig”
              TYPE=”SEQUENT”

juliet       LMID=SITE3
              TUXDIR=”/usr/tuxedo”
              APPDIR=’/usr/home”
              ENVFILE=”/usr/home/ENVFILE”
              TLOGDEVICE=”/usr/home/TLOG”
              TLOGNAME=TLOG
              TUXCONFIG=”/usr/home/tuxconfig”
              TYPE=”AMDAHL”

 

GROUPS and NETWORK Sections

The GROUPS and NETWORK sections shown in Listing 5‑3 specify the following parameters:

•	The TMSCOUNT is set to 2, which means that only two TMS_SQL transaction manager servers will be booted per group.

•	The OPENINFO string indicates that the application will perform database access.

Listing 5‑3 Sample GROUPS and NETWORK Sections

*GROUPS
DEFAULT:        TMSNAME=TMS_SQL       TMSCOUNT=2
BANKB1          LMID=SITE1            GRPNO=1
OPENINFO=”TUXEDO/SQL:/usr/home/bankdl1:bankdb:readwrite”
BANKB2          LMID=SITE2            GRPNO=2
OPENINFO=”TUXEDO/SQL:/usr/home/bankdl2:bankdb:readwrite”
BANKB3          LMID=SITE3            GRPNO=3
OPENINFO=”TUXEDO/SQL:/usr/home/bankdl3:bankdb:readwrite”

*NETWORK
SITE1            NADDR=”0X0002ab117B2D4359”
                 BRIDGE=”/dev/tcp”
                 NLSADDR=”0X0002ab127B2D4359”

SITE2            NADDR=”0X0002ab117B2D4360”
                 BRIDGE=”/dev/tcp”
                 NLSADDR=”0X0002ab127B2D4360”

SITE3            NADDR=”0X0002ab117B2D4361”
                 BRIDGE=”/dev/tcp”
                 NLSADDR=”0X0002ab127B2D4361”

 

SERVERS, SERVICES, and ROUTING Sections

The SERVERS, SERVICES, and ROUTING sections shown in Listing 5‑4 specify the following parameters:

•	The TLR servers have a -T number passed to their tpsrvrinit() functions.

•	All requests for the services are routed on the ACCOUNT_ID field.

•	None of the services will be performed in AUTOTRAN mode.

Listing 5‑4 Sample SERVERS, SERVICES, and ROUTING Sections

*SERVERS
DEFAULT: RESTART=Y MAXGEN=5 REPLYQ=N CLOPT=”-A”
TLR      SRVGRP=BANKB1 SRVID=1 CLOPT=”-A -- -T 100"
TLR      SRVGRP=BANKB2 SRVID=3 CLOPT=”-A -- -T 400"
TLR      SRVGRP=BANKB3 SRVID=4 CLOPT=”-A -- -T 700"
XFER     SRVGRP=BANKB1 SRVID=5 REPLYQ=Y
XFER     SRVGRP=BANKB2 SRVID=6 REPLYQ=Y
XFER     SRVGRP=BANKB3 SRVID=7 REPLYQ=Y

*SERVICES
DEFAULT:    AUTOTRAN=N
WITHDRAW        ROUTING=ACCOUNT_ID
DEPOSIT         ROUTING=ACCOUNT_ID
TRANSFER        ROUTING=ACCOUNT_ID
INQUIRY         ROUTING=ACCOUNT_ID

*ROUTING
ACCOUNT_ID FIELD=ACCOUNT_ID BUFTYPE=”FML”
                     RANGES=”MON - 9999:*,
                     10000 - 39999:BANKB1
                     40000 - 69999:BANKB2
                     70000 - 100000:BANKB3
                        “”