5 Configuring Your ATMI Application to Use Transactions

This topic includes the following sections:

Note:

For information about using transactions in an Oracle Tuxedo CORBA environment, refer to Using CORBA Transactions.

• Modifying the UBBCONFIG File to Accommodate ATMI Transactions
  
• Specifying Global Transaction Parameters in the RESOURCES Section
  
• Creating a Transaction Log (TLOG) in the MACHINES Section
  
• Defining Resource Managers and the Transaction Manager Server in the GROUPS Section
  
• Enabling a Service to Begin a Transaction in the SERVICES Section
  
• Modifying the Domains Configuration File to Support Transactions
  
• Example: A Distributed Application with Transactions
  

5.1 Modifying the UBBCONFIG File to Accommodate ATMI Transactions

To accommodate transactions, you must modify the RESOURCES, MACHINES, GROUPS, and SERVICES sections of the application UBBCONFIG file in the following ways.

In This Section...	Specify...
RESOURCES	The number of transactions allowed in the application, and the value of the commit control flag.
MACHINES	The TLOG information for each machine.
GROUPS	Information about each resource manager, and about the Transaction Manager Server.
SERVICES	Enabling of the automatic transaction option.

5.2 Specifying Global Transaction Parameters in the RESOURCES Section

The following table describes the transaction-related parameters in the RESOURCES section.

Set This Parameter...	To...
MAXGTT	Limit the total number of global transaction identifiers (GTRIDs) allowed on one machine at one time. The maximum value allowed is 2048; the minimum, 0; and the default, 100. You can override the value of MAXGTT on a per-machine basis in the MACHINES section. Entries remain in the table only while a global transaction is active, so this parameter has the effect of setting a limit on the number of simultaneous transactions.
CMTRET	Indicate the initial setting of the TP_COMMIT_CONTROL characteristic as one of the following: LOGGED—the TP_COMMIT_CONTROL characteristic is set to TP_CMT_LOGGED, which means that tpcommit() returns when all the participants have successfully pre-committed. COMPLETE—the TP_COMMIT_CONTROL characteristic is set to TP_CMT_COMPLETE, which means that tpcommit() does not return until all the participants have successfully committed. The default is COMPLETE. To determine the appropriate setting, consult your resource manager (RM) vendors. If any RM in the application uses the late commit implementation of the XA standard, the setting should be COMPLETE. If all RMs use the early commit implementation, the setting should be LOGGED for performance reasons. (You can override this setting with tpscmt().)
MAXTRANTIME	Specify the maximum length of the timeout for the transactions. Valid values are between 0 and 2,147,483,647 inclusive. 0 represents no limitation on transaction timeout value occurs. Default is 0. Note: 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).

5.3 Creating a Transaction Log (TLOG) in the MACHINES Section

To create a TLOG, complete the following tasks:

• Create a Universal Device List (UDL).
• Define transaction-related parameters in the MACHINES section.
• Create a Domains transaction log.

• Creating the UDL
  
• Defining Transaction-related Parameters in the MACHINES Section
  
• Creating the Domains Transaction Log
  

5.3.1 Creating the UDL

The Universal Device List (UDL) is a map of the Oracle Tuxedo filesystem. The UDL gets loaded into shared memory when an application is booted. The TLOG refers to a log in which information about transactions is kept until the transaction is completed. To create an entry in the UDL for the TLOG device, create a 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 a UDL, enter the following command before the application is booted:

tmadmin -c crdl -z config -b blocks

Note:

The command fails if the device already exists.

The value of config must be the full pathname of the device on which you create the UDL. It should match the value of the TLOGDEVICE parameter in the MACHINES section of the configuration file. The value of blocks must be the number of blocks to be allocated on the device.

Note:

If the value of blocks is less than the value of TLOGSIZE, you risk a performance degradation. Therefore, you should specify a value for blocks that is greater than that of TLOGSIZE. For example, if TLOGSIZE is specified as 200 blocks, specifying -b 500 does not cause a degradation.

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

5.3.2 Defining Transaction-related Parameters in the MACHINES Section

To define a global transaction log (TLOG), you must set several parameters in the MACHINES section of the UBBCONFIG file.

For one of these parameters, TLOGDEVICE, you must manually create a 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 you must complete this step before the system is booted.

The following table describes the transaction-related parameters in the MACHINES section.

Set This Parameter...	To Specify...
TLOGNAME	The name of the DTP transaction log for the machine.
TLOGDEVICE	The Oracle Tuxedo filesystem that contains the DTP transaction log (TLOG) for the machine. If this parameter is not specified, it is assumed that there is no TLOG on the machine. The value may contain a maximum of 64 characters.
TLOGSIZEE	The size, in physical pages, of the TLOG file. The value must be between 1 and 2048; the default, 100. Assign a value that is 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 be enough for most applications.
TLOGOFFSET	The offset, in pages, from the beginning of the TLOGDEVICE to the start of the VTOC that contains the transaction log for the machine. The value 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 filesystem) that is shared with another application, you can use TLOGOFFSET to indicate a starting address relative to the address of the device.

• Writing TLOG to an Oracle Database
  

5.3.2.1 Writing TLOG to an Oracle Database

If you want to write tlog into an Oracle database, you do not need to create a UDL.

You must do the following steps:

1. Install Oracle database client, create link libclntsh.so for libclntsh.so.x.x (for example,libclntsh.so.10.1) and set LD_LIBRARY_PATH for linklibclntsh.so on Linux platform.
2. Set UBBCONFIG(5) TLOGDEVICE or DMCONFIG(5)DMTLOGDEV using the following format: "DB:Oracle_XA: ….".
3. Create tlog using thetmadmin and dmadmin commands.

   Note:

   You can only write tlog to an Oracle database. Third party databases are unsupported.

5.3.3 Creating the Domains Transaction Log

Before starting a Domains gateway group, you must create a Domains transaction log. Specifically, you must create a Domains transaction log for the named local domain on the current machine (that is, the machine on which DMADM is running). To create a log, enter the following command:

dmadmin crdmlog crdlog -d local_domain_name

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 a log already exists. If a transaction log has not been created, the Domains gateway group creates one when that group starts.

See Also:

• What Is the Transaction Log (TLOG)? in Administering an Oracle Tuxedo Application at Run Time

5.4 Defining Resource Managers and the Transaction Manager Server in the GROUPS Section

The parameters available for GROUPS section entries allow you to define the attributes of transaction manager servers (TMSs) and resource managers (RMs) for a particular group.

• For a TMS, a server that performs most of the work that controls global transactions, you can define the following parameters:
  • TMSNAME contains the name of the executable for the transaction manager server associated with the group defined in the entry. The Oracle Tuxedo system provides a null transaction manager server called TMS, which is used by groups that participate in transactions, but do not use an RM. This TMS server does not communicate with any resource manager; it simply manages transactions without communicating with an RM.
  • TMSCOUNT contains the number of TMSs to be booted (minimum of 2, maximum of 10, default of 3).
• For each resource manager you can define the OPENINFO and CLOSEINFO parameters. The value of each is a string that contains information needed to open or close a resource manager, respectively. Appropriate values for these parameters are supplied by RM vendors. For example, if you are using an Oracle database as your RM, you might supply the value shown in the following entry:

  OPENINFO=”ORACLE_XA:
  Oracle_XA+Acc=P/Scott/*****+SesTm=30+LogDit=/tmp” 

• Sample of the GROUPS Section
  

5.4.1 Sample of the GROUPS Section

The following sample entry is from the GROUPS section in bankapp, the sample banking application you received with the Oracle Tuxedo system.

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

• Description of Transaction Values in the Sample GROUPS Section
  
• Characteristics of the TMSNAME, TMSCOUNT, OPENINFO, and CLOSEINFO Parameters
  

5.4.1.1 Description of Transaction Values in the Sample GROUPS Section

This table describes the transaction values shown in the sample GROUPS entry.

Transaction Value	Purpose
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	Device name
bankdb	Database name
readwrite	Access mode

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

The following table lists the characteristics of the TMSNAME, TMSCOUNT, OPENINFO, and CLOSEINFO parameters.

Set This Parameter	To Specify The...
TMSNAME	Name of the transaction manager server executable. Required parameter for applications with transactions. TMS is a null transactional manager server.
TMSCOUNT	Number of transaction manager servers (must be between 2 and 10). Default is 3. This parameter is optional.
OPENINFO, CLOSEINFO	Information needed to open or close a resource manager. Content depends on the resource manager. Value starts with the name of the resource manager. Omission means the RM needs no information to open or close.

5.5 Enabling a Service to Begin a Transaction in the SERVICES Section

In certain situations, you may want to set three transaction-related parameters—AUTOTRAN, TRANTIME, and ROUTING—in the SERVICES section.

• If you want a transaction to be started by a service instead of a client, you must set the AUTOTRAN flag to Y. This setting is useful if a 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 a transaction already exists, this call becomes part of it. (The default is N.)

  Note:

  Generally, clients are the best initiators of transactions because a service can participate in a larger transaction.
• If AUTOTRAN is set to Y, you must set the TRANTIME parameter, which is the length of the timeout for transactions to be created. The value must be greater than or equal to 0, and must not exceed 2,147,483,647 (that is, 2 ³¹ - 1, or about 70 years). A value of zero implies there is no timeout for the transaction. (The default is 30 seconds.)
• You must define the ROUTING parameter for transactions that use data-dependent routing.

• Characteristics of the AUTOTRAN, TRANTIME, and ROUTING Parameters
  

5.5.1 Characteristics of the AUTOTRAN, TRANTIME, and ROUTING Parameters

The following table lists the characteristics of the AUTOTRAN, TRANTIME, and ROUTING parameters.

Set This Parameter...	To...
AUTOTRAN	Make a service the initiator of a transaction. To work properly, may be dependent on personal communication between the application designer and the application administrator. If the administrator sets this value to Y without prior knowledge of the ICF parameters set by the developer, the wrong application behavior, or failure of the application might be observed. If a transaction already exists, a new one is not started. Default is N.
TRANTIME	Specify the length of the timeout for the AUTOTRAN transactions. Valid values are between 0 and 2,147,483,647 inclusive. 0 represents no timeout. Default is 30 seconds.
ROUTING	Point to an entry in the ROUTING section where data-dependent routing is specified for transactions that request this service.

5.6 Modifying the Domains Configuration File to Support Transactions

To enable transactions across domains, you require to set parameters in both the DM_LOCAL and the DM_IMPORT sections of the Domains configuration file (DMCONFIG). Entries in the DM_LOCAL section define local domain characteristics. Entries in the DM_IMPORT section define services that are imported, or available from remote domains.

• Characteristics of the DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRAPTRAN, and MAXTRAN Parameters
  
• Characteristics of the AUTOTRAN and TRANTIME Parameters
  

5.6.1 Characteristics of the DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRAPTRAN, and MAXTRAN Parameters

The DM_LOCAL section of the Domains configuration file identifies local domains and the gateway groups associated with them. For each gateway group (Local Domain), you must create an entry that specifies the parameters required for the Domains gateway processes running in that group.

The following table describes the five transaction-related parameters in this section: DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRAPTRAN, and MAXTRAN.

Set This Parameter...	To Specify...
DMTLOGDEV	The Oracle Tuxedo filesystem that contains the Domains transaction log (DMTLOG) for this machine. The DMTLOG is stored as an Oracle Tuxedo VTOC table on the TLOGDEVICE (an Oracle Tuxedo filesystem). 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 filesystem, but a separate log (a table in the DMTLOGDEV) must be created for each local domain. The name of each log is determined by the DMTLOGNAME parameter.
DMTLOGNAME	The name of the Domains transaction log for this domain. If this domain resides on the same filesystem as other local domains (as reflected by a common value for DMTLOGDEV), then the value of DMTLOGNAME must be unique for each log. The value may contain a maximum of 30 characters. The default is DMTLOG.
DMTLOGSIZE	The size, in pages, of the Domains transaction log for this machine. The value must be greater than zero and less than the amount of available space on the Oracle Tuxedo filesystem. The default is 100 pages. Note: The number of domains in a transaction determines the number of pages you must specify in the DMTLOGSIZE parameter. There is no one-to-one mapping between transactions and log pages.
MAXRAPTRAN	The maximum number of domains that can be involved in a transaction. It must be greater than zero and less than 32,768. The default is 16.
MAXTRAN	The maximum number of simultaneous global transactions allowed in this local domain. It must be greater than or equal to zero, and less than or equal to the MAXGTT parameter (which is defined in the configuration file). The default is the value of MAXGTT.

5.6.2 Characteristics of the AUTOTRAN and TRANTIME Parameters

The DM_IMPORT section of the Domains configuration file provides information about services that are imported and thus available from remote domains. Each remote service is associated with a particular remote domain.

You have the option of setting two parameters in the DM_IMPORT section that support transactions: AUTOTRAN and TRANTIME.

The following table describes these parameters.

This Parameter...	Is Used...
AUTORAN	By gateways to automatically start and terminate transactions for remote services. This capability is required if you want to enforce reliable network communication with remote services. To request this capability, set the AUTOTRAN parameter to Y in the entry for the appropriate remote service.
TRANTIME	To specify the default timeout, in seconds, for a transaction automatically started for the service being defined. The value must be greater than or equal to zero, and less than 2147483648. A value of zero implies the maximum timeout value for the machine. The default is 30 seconds.

An additional transaction-timeout property named MAXTRANTIME from the RESOURCES section of the UBBCONFIG file is also available. 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 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 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).

5.7 Example: A Distributed Application with Transactions

This section provides sample entries from a configuration file that defines bankapp as an application that supports transactions and is distributed over three sites. The application is characterized by the following:

• Data-dependent routing on ACCOUNT_ID
• Data distributed over three databases
• BRIDGE processes communicating with the system via the ATMI interface
• Application administration from one site

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

• Sample RESOURCES Section
  
• Sample MACHINES Section
  
• Sample GROUPS and NETWORK Sections
  
• Sample SERVERS, SERVICES, and ROUTING Sections
  

5.7.1 Sample RESOURCES Section

The following listing shows a sample RESOURCES section.

Listing 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

In the preceding listing, note the following:

• MAXSERVERS, MAXSERVICES, and MAXGTT are set to values that are smaller than the defaults, which reduces the size of the bulletin board.
• The MASTER is SITE3 and the backup master is SITE1.
• It is possible to use a networked configuration with migration because MODEL is set to MP and OPTIONS is set to LAN, MIGRATE.
• Because BBLQUERY is set to 180 and SCANUNIT is set to 10, the DBBL will check the remote BBL s every 1800 seconds (that is, every half hour).

5.7.2 Sample MACHINES Section

The following listing shows a sample MACHINES section.

Listing Sample MACHINES Section

*MACHINES
 giselle       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”   

In the preceding listing, note the following:

• TLOGDEVICE and TLOGNAME are specified, which implies that transactions will be done.
• The TYPE parameters are all different, which indicates that all messages sent between machines will be encoded and decoded.

5.7.3 Sample GROUPS and NETWORK Sections

The following listing shows sample GROUPS and NETWORK sections.

Listing 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”

In the preceding listing, note the following:

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

5.7.4 Sample SERVERS, SERVICES, and ROUTING Sections

The following listing shows sample SERVERS, SERVICES, and ROUTING sections.

Listing 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
                     “”

In the preceding listing, note the following:

• Calls to the tpsvrinit() function by TLR servers will include a number (100, 400, or 700) specified with the -T option.
• All service requests are routed on the ACCOUNT_ID field.
• No services are performed in AUTOTRAN mode.

See Also:

• About Transactions
• Using Tuxedo with Oracle Real Application Clusters (RAC)
• Writing Global Transactions in Programming Oracle Tuxedo ATMI Applications Using C
• “What You Can Do Using the ATMI” in Introducing Oracle Tuxedo ATMI
• For more information about using transactions in an Oracle Tuxedo CORBA environment, refer to Using CORBA Transactions