Foundation Class Library (Java): Administering Transactions

This chapter describes the tasks and conceptual information necessary for administering transactions using the Netscape Application Server (NAS) Administrator.

The following topics are included in this chapter:

About the Transaction Manager

Storing Distributed Transactions Log Data

Administering Distributed Transactions in the Transaction Window

Administering Distributed Transactions from the Command Line

Setting Up Resource Managers for Distributed Transactions

Enabling XA Error Logging

Resolving In-Doubt Transactions

Recovering from Log Failure

About the Transaction Manager

The transaction manager is installed with each instance of Netscape Application Server (NAS) to coordinate global transactions within a Java Server (KJS) process. Global transactions are a set of related operations that must be executed as a unit, though each operation may run in a different process.

You can use global transactions to update a database that uses one or more Enterprise Java Beans (EJBs) running concurrently for the same global transaction, from within one or more KJS processes. This occurs when an EJB triggers another EJB to run and they both participate in the same transaction. You can also update multiple databases that are distributed over different geographic locations or update multiple databases of different types (such as Oracle and Sybase).

The transaction manager runs within a KJS process and creates two files: a restart file and a restart.bak file. In addition, you need to provide a log file for each KJS process. You can administer these files from the command line or by using the Transaction window of NAS Administrator.

Storing Distributed Transactions Log Data

An installation of Netscape Application Server (NAS) consists of one Administration Server (KAS) process, one Executive Server (KXS) process, and at least one Java Server (KJS) process. A transaction manager exists for each KJS.

As a NAS administrator, you must maintain one logical volume and its restart data for each KJS in a NAS installation. A logical volume is made up of one or more physical volumes. A physical volume stores the state of all ongoing transactions. If you have more than one physical volume, additional physical volumes are backups, or mirrors, of the first physical volume.

When you initially start NAS, NAS looks in the registry for the location of the directory root. In this location is an empty log file for each KJS where NAS will write information about the state of all ongoing distributed transactions for that process. NAS then creates additional files called restart and restart.bak (a backup of restart) for each KJS, which record the location of the log file and the state of the logical and physical volumes. Thereafter, whenever you start the server, NAS refers to the restart file for the location and state of the log file and does not refer to the registry. Restart and restart.bak are stored in the following directories:

$DirectoryRoot/KJS #/restart

$DirectoryRoot/KJS #/restart.bak

You should store restart.bak on a different device if possible. If restart becomes corrupted, NAS uses restart.bak to determine the location of the log file and state of ongoing distributed transactions. If both restart and restart.bak are corrupted, the transaction manager will become inoperable and you must "cold-start" the server. When you cold-start a server, NAS must look to the registry for the location of the log file as it did in its initial startup; all restart data is lost. The log file and all data will then be overwritten.

The following table lists the registry entries to which NAS refers along with their default values:


Registry Entry	Default values
DirectoryRoot	NAS install directory/CCS0/TXNMGR
MirrorDirectoryRoot	NAS install directory/CCS0/TXNMGR_MIRROR
KJS #/LogVolumeDiskName	$DirectoryRoot/KJS #/logVol, size is 4M

Administering Distributed Transactions in the Transaction Window

You can administer transactions using the Transaction window of Netscape Application Server (NAS) Administrator. To access the Transaction window from the NAS Administrator toolbar, click the Transaction button as shown in the following illustration:

About the Transaction Window The left pane of the Transaction window displays a tree of nodes as shown in the following illustration:

The top level of the tree lists which servers are registered with NAS Administrator. The second level, below each registered server name, displays one or more process nodes. These nodes indicate which processes are running on each registered server. Only Java Server (KJS) processes appear in the tree because only KJS processes support transactions. The third level of the tree displays the physical volumes for each process. Finally, the fourth level of the tree displays the disks in each physical volume. See Storing Distributed Transactions Log Data for more information about physical volumes.

When you click a physical volume node, the right pane of the transactions window displays the page size, or size of a page used in the transaction manager, the total size of the physical volume, and the amount of unused disk space in the physical volume. You cannot edit these values.

A disk can be thought of as a partition of the physical volume. You can create an unlimited number of disks, but you cannot delete a disk once it's created. When you click a disk node, the right pane of the Transactions window displays the location and size of the selected disk.

Configuring Transactions per Server To change transaction settings for an application server, click a registered server in the left pane of the Transaction window. The Configuration tab appears in the right pane as shown here:

The selected server's current root and mirror directories are listed on the Configuration tab. Since no error checking is provided, it is not recommended that you edit these directories.

Viewing Transactions on a Selected Server
You can view transactions running on the selected server by clicking the Transaction Manager tab.

The following window appears:

The Transactions tab displays details about all the transactions running on the selected server. For each transaction, the tab displays the following information:

process: the Java Server process (KJS) where the transaction is running

transaction ID: an arbitrary number used to identify the transaction

the current state of the transaction

Click the Update button periodically to remove expired transactions from view and display currently running transactions in the window.

Viewing Transaction Details
To view details about a transaction, click the Details button.

The Transactions Detail dialog box appears.

In the text box, Originator indicates where the selected transaction originates. The Participants box indicates where the transaction is currently running.

You can force the transaction into a state by clicking the appropriate button (Abort, Force Abort, Force Commit, Force Finish).

Configuring Transactions per Process Click the process in the left pane of the Transaction window to change transaction settings for a process on an application server.

The Configuration tab appears in the right pane as shown in the following illustration:

The logical volume size for the process is displayed. You can set the size of the logical volume by entering a number in the Logical Volume Size field. A logical volume must be at least 8 MB and less than 10 MB.

Viewing Transactions on a Selected Process
Click the Transaction Manager tab to view the details of all transactions running on the selected process. The following window appears:

The transaction ID and state appear. See Configuring Transactions per Server for more information.

Configuring Resource Managers A resource manager enables you connect to a database back end for global transactions. If you enable a resource manager, the transaction manager within a KJS process attempts a connection to the database when the KJS process is started.

There is one resource manager for each database the application server can access. Click the Resource Manager tab in the Transaction window to configure resource managers. The following window appears:

The name of each resource manager (for instance, Microsoft SQL) as well as its status (enabled or disabled) is displayed. Click the Enabled checkbox to toggle the status of each resource manager. Note that you must restart the server before changes to your resource manager configuration take effect.

Adding and Editing Resource Managers
Click the Add or Modify buttons to add or edit a resource manager. The following dialog box appears:

In the Name field, enter a value to distinguish the selected resource manager from other resource managers.

In the OpenString field, enter the parameters for accessing a particular database (user name, password, permissions).

Select the type of database from the Type drop-down box (for instance, Microsoft SQL).

Choose the thread mode from the drop-down box:

multiple_associations: the transactation manager XA (TM-XA) service performs no serialization of XA operations between threads.

serialize_all_operation: the TM-XA service permits a maximum of one thread to make an XA call to the resource manager client library at a time.

serialize_start_end: the TM-XA service ensures that only one association with the resource manager client library is attempted at a time.

single_association: the TM-XA service does not prevent multiple threads from attempting different associations at the same time.

Finally, to enable or disable the resource manager, click the Enabled checkbox. Only one resource manager may be enabled for each database type.

You must restart the server before changes take effect.

Administering Distributed Transactions from the Command Line

You can also administer transactions from the command line. Invoke the command-line tool with the following script:

ksvradmin -l

The following table lists nasadmin commands you can execute from the command line. Once you invoke the command-line tool, each command in the following table is preceded by nasadmin command prompt as shown in the following example:

nasadmin > abort transaction


nasadmin Command	Function	Input parameter	Output parameter
abort transaction	Abort a server transaction.	DWORD tid
add trace	Add a trace mask.	STRING traceSpec
add mirror	Add a mirror to a logical volume.	STRING lVol, STRING pVol, STRING diskName
dump component	Dumps the internal state of a component	STRING componentName
dump ringbuffer	Dumps the current contents of the ringbuffer	STRING destination
expand lvol	Expand a logical volume.	STRING lVol, DWORD newSize
expand pvol	Expand a physical volume.	STRING pVol, STRING diskName
force transaction	Force the outcome of a transaction.	DWORD tid, WORD commitDesired, WORD finish
help	Display help message for given command	{STRING commands}
list trace	Lists the current trace masks for Encina components
list transactions	List unresolved transactions in the server.	DWORD originator, DWORD participant, DWORD globalID	DWORD tid, WORD state (for example, active or inactive)
list lvols	List all known logical volumes.	WORD enabled	{STRING lVol}
list pvols	List all known physical volumes.		{STRING pVol}
query transaction	Query transaction attributes.	DWORD tid, WORD state, WORD originator, WORD participants, WORD global	STRING globalID, WORD state, STRING originator, {STRING participant}
query logvol	Query a log volume.	STRING logVol	STRING archiveDevice, DWORD freePages, DWORD numLogFile, {STRING logFile}
query lvol	Obtain information about a logical volume.	STRING lVol	DWORD pageSize, DWORD size, {STRING pVol, WORD state (e.g. clean or dirty), WORD isMounted}
query pvol	Obtain information about a physical volume.	STRING pVol	STRING lVol, DWORD chunkSize, DWORD numRegions, {STRING disk, DWORD offset, DWORD size}, DWORD totalSize
redirect trace	Redirects trace to the specified destination	STRING destination {ringbuffer, stderr, stdout, filename}
remove mirror	Remove a mirror from a logical volume	STRING lVol, STRING pVol
sync mirrors	Synchronize mirrors of a logical volume	STRING lVol

The following table lists commands you can use in addition to those provided by nasadmin. As shown in the following example, these commands are not preceded by nasadmin at the command line.

%set server


Command	Function	Input parameter
logon	Log on to KAS for a NAS installation.	STRING name, DWORD host, DWORD port, STRING userName, STRING password, WORD autoconnect
list servers	List all the engines.
set server	Set KES as the current server and one of the engines to be the current engine. By default, the first KXS is the current server and the main engine of the KXS is the current engine.	STRING name, WORD engNum
create resourcemanager	Create a resource manager.	STRING name, STRING openString, STRING type, STRING threadmode, WORD isenabled
delete resourcemanager	Delete a resource manager.	STRING name
set resourcemanager	Set an existing resource manager by modifying its open string.	STRING name, STRING openString, STRING threadmode, WORD isenabled
list resourcemanager	List all the resource managers defined in the registry
get adminmode	Return admin mode(0 or 1) for a KJS.	WORD adminMode
set adminmode	Set admin mode for a KJS.

Setting Up Resource Managers for Distributed Transactions

Before you can connect to resource managers to use in distributed transactions, you must perform setup tasks that are not required for local transactions. The following section contains information about the following types of resource managers:

Oracle

Sybase

Microsoft SQL Server

You must restart the server after making changes to a resource manager.

Oracle To set up an Oracle resource manager, perform the following steps:

Enter the open string in the following format:

Oracle_XA+DB=<Server_Instance>+Acc=P/<user name>/
<password>+Sqlnet=<Server Instance>+SesTm=<Session time 
out>+Threads=<Thread safe mode>

If you are trying to connect to the bb734 instance using the user name system and the password manager, the open string appears as shown the following example:

Oracle_XA+DB=bb734+Acc=P/system/
manager+Sqlnet=bb734+SesTm=90+Threads=True

Use the setting Threads=True only in the multiple_associations thread mode, which is the recommended mode for use with Oracle resource managers. Other thread modes reject this setting. Omit this parameter or use the setting Threads=False with other thread modes.

It is strongly recommended that you use only one thread mode for all Oracle resource managers; do not mix and match thread modes for multiple resource managers.

Make sure the three required catalog tables for recovery exist. If they don't, create them using the following script:

$ORACLE_HOME/rdbms80/admin/xaviews.sql (see below)

rem 

rem $Header: xaview.sql 7020200.1 95/04/05 13:07:30 rdhoopar 

Generic<base> $ xaview2.sql Copyr (c) 	1989 Oracle 

rem 

Rem ----------------------------------------------------------------
-- 

Rem NAME 

Rem XAVIEW.SQL 

Rem FUNCTION 

Rem Create the view necessary to do XA recovery scan of prepared 

Rem and heuristically completed transactions. 

Rem NOTES 

Rem The view 'XATRAN' basically combines information from two 

Rem different types of tables: 

Rem pending_trans$ & pending_sessions$ 

Rem x$k2gte2 

Rem The view v$pending_xatrans$ combines and then filters 

Rem information 

Rem from the table pending_trans$ and pending_sessions$ into format 

Rem that satisfy XA criteria. 

Rem   Then the view v$xatrans$ combines information from x$k2gte2 and 

Rem   v$pending_xatrans$. 

Rem MODIFIED 

Rem   cchew     07-15-92  - added fmt column 

Rem   cchew     05-22-92  - No more fmt=0 condition 

Rem   cchew     01-19-92  - Creation 

Rem ----------------------------------------------------------------



DROP VIEW v$xatrans$; 

DROP VIEW v$pending_xatrans$; 



CREATE VIEW v$pending_xatrans$ AS 

(SELECT global_tran_fmt, global_foreign_id, branch_id 

   FROM   sys.pending_trans$ tran, sys.pending_sessions$ sess 

   WHERE  tran.local_tran_id = sess.local_tran_id 

     AND    tran.state != 'collecting' 

     AND    BITAND(TO_NUMBER(tran.session_vector), 

                   POWER(2, (sess.session_id - 1))) = sess.session_id) 

/ 



CREATE VIEW v$xatrans$ AS 

(((SELECT k2gtifmt, k2gtitid_ext, k2gtibid 

   FROM x$k2gte2 

   WHERE  k2gterct=k2gtdpct) 

 MINUS 

  SELECT global_tran_fmt, global_foreign_id, branch_id 

   FROM   v$pending_xatrans$) 

UNION 

 SELECT global_tran_fmt, global_foreign_id, branch_id 

   FROM   v$pending_xatrans$) 

/

Sybase Sybase is only available on Solaris platforms. To set up a Sybase resource manager, perform the following steps:

Name the resource manager by adding entries to xa_config. The entries should be in the following format:

[xa]

lrm=ksample_rm

server=ksample

Enter the open string in the following format:

-U<User name> -P<Password> -N<RM name> -Txa

For example, if you are trying to connect to ksample_rm, which is set up to connect to a ksample server instance, the open string is in the following format:

-Uuser -Ppswd -N ksample_rm -Tevent

If you want do not want to suppress logging user names and passwords to a trace file, use -Txa instead of -Tevent in the open string.

Make sure that libxa.so exists in the $SYBASE/lib directory.

XA libraries do not come by default with Sybase client libraries.

Run the following scripts available in the $SYBASE/scripts/ directory:

xacommit.sql

xacompot.sql

xasproc.sql

xapropt.sql

xa_ld_q1.sql

xa_ld_q2.sql

DB2 To set up a DB2 resource manager, perform the following steps:

Enter the open string in the following format:

<DataSourceName,UserName,Password>

For example, if you are connecting to ksample and using inst1/inst1 as user name and password, the open string is in the following format:

ksample,inst1,inst1

Enter the following in the DB2 configuration:

db2 update dbm cfg using TP_MON_NAME libEncServer_nodce

DB2 uses dynamic registration to participate in distributed transactions. On NT, DB2 needs to know which shared library implements the dynamic registration functions like ax_reg() and ax_unreg().

Make sure $DB2DIR/lib/libdb2.so has 755 permissions.

If it does not, the Java Server (KJS) process will crash when calling xa_open.

Make sure that $DB2LIB/sqllib/lib/libdb2.so has r-x permissions

If it does not, the KJS process will crash upon startup.

Set the CURSORHOLD parameter to zero in the db2cli.ini file.

The cursor hold feature does not work in the XA environment.

In the db2cli.ini file, set DISABLEMULTITHREAD to 1.

A sample entry in db2cli.ini should now look like the following example:

[ksample]

CURSORHOLD=0 

AUTOCOMMIT=0 

LONGDATACOMPAT=1 

DISABLEMULTITHREAD=1

Note. You cannot mix local and global connections using DB2 on either Solaris or Windows NT platforms. Disable all DB2 global data sources for local transactions to function properly.

Microsoft SQL Server To set up a Microsoft SQL resource manager, perform the following steps:

Enter the open string in the following format:

Tm=transaction manager's name RmRecoveryGuid=GUID

In the NAS environment, tm is Encina.

Find and copy the value for RmRecoveryGuid in the following registry entry:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSSQLServer\ResourceMgrID

If this registry entry is missing, generate a GUID using the kguidgen tool.

Install and set up the Distributed Transaction Coordinator (DTC). You can get DTC from Microsoft's web site or from MSDN Windows NT option pack 4.0.

When the DTC is installed, the Microsoft DTC (MS DTC) section exists in the SOFTWARE\MICROSOFT\hive.

It is not necessary to install the Microsoft Transaction Server (MTS).

Make sure the ODBC driver on your server machine is version 3.5 or higher.

Make sure the following XA-related stored procedures are installed on the MS SQL Server machine where the application server connects:

sp_start_xact, sp_scan_xact, sp_commit_xact or their deprecated names such as start_xact, scan_xact and commit_xact.

Enabling XA Error Logging

To log XS error messages, follow the directions for the type of resource manager you are using:

Oracle

Sybase

Microsoft SQL Server

Oracle In the open string, add a log directory as shown in the following example:

Oracle_XA+DB=<bb734>+Acc=P/system/
manager+Sqlnet=bb734+SesTm=90+Threads=True+LogDir=/export/logs

where /export/logs is the log directory.

Make sure that the log file generated by LogDir allows administrator access only as it contains the user names and passwords for the database.

Sybase In the open string, add a log directory as shown in the following example:

-Uuser -Ppswd -N ksample_rm -Tevent -L/export/logs/syb_xa_log

where /export/logs is the log directory.

Make sure that the log file generated by LogDir allows administrator access only as it contains the user names and passwords for the database.

DB2 Enter the following commands to enable the logging of XA calls and/or interfaces:

db2 update dbm cfg using DIAGLEVEL 4 

db2 update dbm cfg using DIAGPATH $GX_ROOTDIR/logs

The log will be created under file name called db2diag.log.

XA failures appear in the following format:

String Title: XA Interface SQLCA  PID:28084 Node:000 

SQLCODE = -998  REASON CODE: 4  SUBCODE: 4

Using the REASON CODE and SUB CODE, you can find the cause of an error by looking up the code in the following table:


Code	Cause of error	Action
01 - (XAER_ASYNC)	Asynchronous operation already outstanding.	Entry is made in system log.
02 - (XAER_RMERR)	Resource manager error occurred in transaction branch.	Entry is made in system log.
03 - (XAER_NOTA)	XID is not valid.	Entry is made in system log.
04 - (XAER_INVAL)	Invalid arguments given.	Entry is made in system log. Verify content of xa open string and make necessary corrections.
04 - 01 - (xa_info)	Pointer is invalid (for example, the XAOpen string is null).
04 - 02	Database name exceeds maximum length.
04 - 03	User name exceeds maximum length.
04 - 04	Password exceeds maximum length.
04 - 05	User name specified but not a password.
04 - 06	Password specified but not a user name.
04 - 07	Too many parameters in the xa_info string.
04 - 08	Multiple xa_opens generate different RM ids for the same database name.
04 - 09	Database name not specified.
05 - (XAER_PROTO)	Routine invoked in improper context.	Entry is made in system log.
06 - (XAER_RMFAIL)	Resource manager unavailable.	Entry is made in system log.
07 - (XAER_DUPID)	XID already exists.	Entry is made in system log.
08 - (XAER_OUTSIDE)	Resource manager doing work outside distributed transaction.	Entry is made in system log.
09	Registration (ax_reg) with transaction manager failed.
09 - 01	Joining XID not found.
09 - 02	Dynamic library specified in the tp_mon_name configuration parameter could not be loaded.	Ensure that the tp_mon_name configuration parameter contains the name of the dynamic library in the external product which has the ax_reg() function used for dynamic registration of transactions.
10	Attempted to start a different transaction while suspended.
12	Unregistering (ax_unreg) with transaction manager failed.
13	Ax interface failure: ax_reg() and ax_unreg() not found.
35	Heuristic operations invalid for non-XA database.	Heuristic operation attempted against a database that only participates only as a read-only resource manager in a distributed transaction (for example, any DRDA databases like DB2 on MVS).
36	XID not known by database manager.	Invalid heuristic operation attempted on an in-doubt transaction. Wrong XID specified or a heuristic or resync operation took place since you recorded XID. Perform a Heuristic Query request to get the current list of in-doubt transactions to verify if you still need to perform your heuristic operation.
37	Transaction has already been heuristically committed.	Invalid heuristic operation attempted on an in-doubt transaction. Wrong XID specified or a heuristic or resync operation took place since you recorded XID. Perform a Heuristic Query request to get the current list of in-doubt transactions to verify if you still need to perform your heuristic operation.
38	Transaction has already been heuristically rolled back.	Invalid heuristic operation attempted on an in-doubt transaction. Wrong XID specified or a heuristic or resync operation took place since you recorded XID. Perform a Heuristic Query request to get the current list of in-doubt transactions to verify if you still need to perform your heuristic operation.
39	Transaction is not an in-doubt transaction.	XID specified is for a transaction that has ended and is waiting for the two-phase commit process to begin. Only perform heuristic operations on transactions in the two-phase commit process and have become in-doubt transactions.
40	Only rollbacks allowed for this transaction.	SQL statement attempted under a failed transaction.
69	Database log ID mismatch during DUOW re-synchronization.	Transaction manager database or resource manager database names could be referencing different database instances.
85	As a result of heuristic processing, transaction has partially committed and rolled back.	Attempting to update multiple data sources. Some data sources have been heuristically rolled back or committed, resulting in partially committed transaction that has been rolled back. To correct the data, you must manually check every data source updated by the transaction.