Setting Up an Oracle Tuxedo Application

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

To accommodate transactions, you must modify the RESOURCES, MACHINES, GROUPS, and SERVICES sections of the application’s 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.

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

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

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.

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.

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.

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

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

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

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.

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, 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 define the ROUTING parameter for transactions that use data-dependent routing.

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.

Modifying the Domains Configuration File to Support Transactions

To enable transactions across domains, you need 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

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.

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

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

The following listing shows a sample RESOURCES section.

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

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 BBLs every 1800 seconds (that is, every half hour).

Sample MACHINES Section

The following listing shows a sample MACHINES section.

Listing 5-2 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.

Sample GROUPS and NETWORK Sections

The following listing shows sample GROUPS and NETWORK sections.

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”

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.

Sample SERVERS, SERVICES, and ROUTING Sections

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

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

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.

Setting Up an Oracle Tuxedo Application

Configuring Your ATMI Application to Use 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

Creating the UDL

Defining Transaction-related Parameters in the MACHINES Section

Creating the Domains Transaction Log

See Also

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

Sample of the GROUPS Section

Description of Transaction Values in the Sample GROUPS Section

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

Enabling a Service to Begin a Transaction in the SERVICES Section

Characteristics of the AUTOTRAN, TRANTIME, and ROUTING Parameters

Modifying the Domains Configuration File to Support Transactions

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

Characteristics of the AUTOTRAN and TRANTIME Parameters

Example: A Distributed Application with Transactions

Sample RESOURCES Section

Sample MACHINES Section

Sample GROUPS and NETWORK Sections

Sample SERVERS, SERVICES, and ROUTING Sections

See Also