		BEA WebLogic Enterprise 4.2 Developer Center
		HOME \| SITE MAP \| SEARCH \| CONTACT \| GLOSSARY \| PDF FILES \| WHAT'S NEW
		Administration \| TABLE OF CONTENTS \| PREVIOUS TOPIC \| NEXT TOPIC \| INDEX

Configuring Transactions

This chapter discusses the following topics:

Understanding Transactions

Transactions greatly simplify the writing of distributed applications. They allow your application to cope more easily with a large set of problems that occur in a distributed environment, such as machine, program, or network failures. One of the greatest strengths of the WLE or BEA TUXEDO system is that the transaction semantic was built into the software and into the BEA TUXEDO ATMI. Global transactions were woven into the fabric of the system and into its communication APIs and protocols.

The ability to define a global transaction around communication calls makes it an indispensable tool for writing distributed applications. A global transaction allows not only the effects of your communications to be committed as a single unit, but it also gives you a simple, programmatic way to undo work if errors occur.

To illustrate the power of global transactions, consider the following example. A Place Order service performs two operations: it updates the Order database and enqueues the order to the shipping department. The business intends that both these actions occur together as a unit or that neither action should occur if one action fails.

To accomplish this, the client application invoking the Place Order service associates the call with a global transaction. You do this by using the ATMI begin-transaction function before issuing the service request, and issuing the commit-transaction function after it. Because the service is invoked as part of a global transaction, its work is done on its behalf. The server is propagated with the client's transaction when the Place Order service is invoked. Both the database access and the enqueue operation to the shipping application queue become part of the client's transaction.

Should either operation fail because of an application or system error, the work done in the transaction is rolled back to its state at the outset of the transaction. If both succeed, however, the client's call to commit the transaction causes the effects of the database update and the enqueued message to become permanent records of this transaction.

Modifying the UBBCONFIG File 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 way to accommodate transactions:

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 (WLE System) or the SERVICES section (BEA TUXEDO System), enable the automatic transaction option.

Specifying Application-wide Transactions in the RESOURCES Section

The following table provides a description of transaction-related parameters in the RESOURCES section of the configuration file.


Parameter	Meaning
`MAXGTT`	Limits the total number of global transaction identifiers (`GTRID`s) allowed on one machine at one time. The maximum value allowed is `2048`, minimum `0`, and default `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()`.)


Parameter	Meaning
`TLOGNAME`	The name of the `DTP` transaction log for this machine.
`TLOGDEVICE`	Specifies the WLE or BEA 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 be enough 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 (BEA TUXEDO Servers)

This section is specific to the BEA TUXEDO system.

You can create the Domains transaction log before starting the Domains gateway group by using dmadmin(1) crdmlog (crdlog) -d local_domain_name. Create the Domains transaction log for the named local domain on the current machine (that is, the machine where 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 Domains gateway group starts.

Defining 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 is the name of the server executable; TMSCOUNT is the number of such servers to boot (minimum 2, maximum 10, default 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 RM.
Defining opening and closing information for each resource manager. OPENINFO is a string with information used to open a resource manager, and CLOSEINFO is used to close a resource manager.

Sample of the GROUPS Section

The following is an example from the GROUPS section in the banking application, called bankapp.

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

Description of Transaction Values in the Sample GROUPS Section

The following table describes the transaction values shown in the sample GROUPS section:


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

The following table lists the 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 RM needs no information to open.

Enabling an Interface to Begin a Transaction in the INTERFACES Section (WLE Servers)

The INTERFACES section has been added to the UBBCONFIG file to support WLE CORBA interfaces. There are two transaction-related additions in the INTERFACES section:

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), or the Server Description File (XML) 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 personal communication 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 or XML file, the actual run time effect of the parameter might be unknown.
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 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.)

Characteristics of the AUTOTRAN and TRANTIME Parameters

The following table lists the 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 personal communication between the system designer and the system administrator. If the administrator sets this value to Y without prior knowledge of the ICF or XML 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. 0 represents no timeout. Default is 30 seconds.

Enabling a Service to Begin a Transaction in the SERVICES Section (BEA TUXEDO Servers)

The following are three transaction-related additions 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.

Characteristics of the AUTOTRAN, TRANTIME, and ROUTING Parameters

The following table lists the 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 (BEA TUXEDO Servers)

This section is specific to BEA TUXEDO 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.

The following table provides a description of the five transaction-related parameters in this section: DMTLOGDEV, DMTLOGNAME, DMTLOGSIZE, MAXRDTRAN, and MAXTRAN.


Parameter	Characteristics
`DMTLOGDEV`	Specifies the BEA TUXEDO file system that contains the Domains transaction log (`DMTLOG`) for this machine. The `DMTLOG` is stored as a BEA 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 BEA 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

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.

The following table describes the two transaction-related parameters in this section: AUTOTRAN and TRANTIME.


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.

Example: A Distributed Application Using Transactions

The following configuration file shows bankapp as an application that is distributed over three sites and that uses transactions. The application includes the following:

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 file includes seven sections: RESOURCES, MACHINES, GROUPS, NETWORK, SERVERS, SERVICES, and ROUTING.

The RESOURCES Section

The RESOURCES section shown in Listing 7-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 7-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

The MACHINES Section

The MACHINES section shown in Listing 7-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 7-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"

The GROUPS and NETWORK Sections

The GROUPS and NETWORK sections shown in Listing 7-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 7-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"

The SERVERS, SERVICES, and ROUTING Sections

The SERVERS, SERVICES, and ROUTING sections shown in Listing 7-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 7-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
                        ""

Copyright � 1999 BEA Systems, Inc. All Rights Reserved.
Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
Last update: July 05, 1999.