Microsoft Transaction
Server
Failed to Enlist on Calling Object's
Transaction
Version 2.10
April 07, 1999
The ODBC driver manager reports this error when a transactional Microsoft Transaction Server component attempts to open a database connection and the driver manager cannot enlist the database connection in the current transaction. The ODBC Driver Manager enlists the database connection in the current transaction by calling the ODBC driver’s SQLSetConnectionAttr (SQL_ATTR_ENLIST_IN_DTC) procedure. The ODBC driver manager displays the “Failed to enlist” message if the call to the SQLSetConnectionAttr procedure fails.
If this error occurs when your transactional Microsoft Transaction Server component is accessing a Microsoft SQL Server database, please check the following:
Make certain that the Microsoft DTC Service is “Started” on the system on which your Microsoft Transaction Server components are deployed.
If your Microsoft Transaction Server application is accessing a Microsoft SQL Server database on a remote system, ensure that the Microsoft DTC Service is “Started” on that system also. This is frequently the cause of the “Failed to Enlist Error”.
If every attempt to connect to a remote SQL Server database results in a “failed to enlist” error, you should immediately check to ensure that Microsoft DTC is started on both systems. Failing to start Microsoft DTC on both systems is the most common cause of the “failed to enlist” error.
You can check the status of the Microsoft DTC Service using the “Services” Control Panel applet. From the “Start” menu select “Settings” and then “Control Panel”. Start the “Services” applet on the control panel. Use the Services applet to ensure that “MSDTC” is “Started”. If Microsoft DTC is not started, you can start it by selecting “MSDTC” and then clicking “Start”.
When a transactional Microsoft Transaction Server component on one system accesses a SQL Server database on another system, Microsoft DTC propagates the DTC transaction from the first or “primary” system to the secondary system. Transaction propagation can only occur if the DTC process on the primary system can communicate with the DTC process on the secondary system. Actually, the DTC processes establish RPC connections in both directions, so a network configuration problem on either system can prevent the DTC processes from successfully communicating with one another. This will result in a “Failed to enlist error” being returned by ODBC.
Often the following Microsoft DTC event will be recorded in the Windows NT Application event log.
Primary: Session Bind Failed.
Primary Timed Out while waiting for the secondary to Bind.
This error indicates that DTC on your Microsoft Transaction Server system was able to bind to DTC on the SQL Server machine, but DTC on the SQL Server machine could not perform the reverse bind to the Microsoft Transaction Server machine.
If your network configuration is incorrect, every attempt to connect to the remote SQL Server database will result in a “failed to enlist” error. If you consistently get a “failed to enlist” error even after Microsoft DTC has been started on both systems, the most likely cause of the failure is a network configuration error.
You can check you network configuration with the Pingtest.bat as follows:
a.
Use Notepad to create the file “Pingtest.bat” and copy the following batch file
commands in it.
The batch file uses %computername% to
display the local IP address. It then displays the IP address of the remote
machine you specify in the command line when executing the batch file. When you
invoke the batch file, you must specify the name of the remote machine and not
its IP address. Using the machine name forces Ping to resolve the machine name
exactly as Microsoft DTC does when it binds to the remote Microsoft DTC
machine.
echo off
REM Usage pingtest
OtherMachineName
REM Must use a machine name
and NOT an IP address
ping -n 1 %computername%
ping -n 1 %1
ipconfig /all
echo on
b. Run “Pingtest.bat” on your Microsoft Transaction Server machine to determine if you can ping your SQL Server machine by name. Capture the output from the batch file in a text file. For example, if Microsoft Transaction Server is running on machine “A” and SQL Server is running on machine “B”, do the following:
Pingtest B > AResults.txt
c. Run “Pingtest.bat” on your SQL Server machine to determine if you can ping your Microsoft Transaction Server machine by name. Capture the output from the batch file in a text file. For example, if Microsoft Transaction Server is running on machine “A” and SQL Server is running on machine “B”, do the following:
Pingtest A > BResults.txt
d. Examine the two results text files to ensure that the two machines can ping one another successfully.
If you use Hosts or Lmhosts files for TCP/IP name resolution, check these files very carefully to ensure that they contain valid computer name to IP address mappings. To do this, check the “Hosts” and the “Lmhosts” files in the “WINNT40\system32\drivers\etc\” directory on both the Microsoft Transaction Server system and the SQL Server system. Frequently, the file on one system will be correct, while that on the other system is incorrect.
If you
only see the “failed to enlist” error intermittently, then using Named Pipes
rather than TCP/IP may be the cause of the problem. Using Named Pipes can
result in intermittent “Failed to Enlist” errors. We strongly recommend that
you configure SQL Server to use TCP/IP rather than Named Pipes.
From the “Start” menu select “Programs” , “Microsoft SQL Server 6.5”, and “SQL Client Configuration Utility”. . Select the “Net Library” tab. In the “Default Network” pull down menu select “TCP/IP Sockets”. Finally, select “Done”.
Consider whether the component’s transaction may have aborted due to transaction timeout before the database enlistment completed. You can increase the transaction timeout value through the Microsoft Transaction Server Explorer. To do this, run the Microsoft Transaction Server Explorer and select “Computers”. Right click on the computer where the transaction was initiated and select “Properties”. Select the “Options” tab and specify a longer “Timeout” value.
This is unlikely to be the problem unless your transactions are unusually long. However, it may be helpful to temporarily increase the timeout value to eliminate this as a potential source of trouble.
If this error occurs when your transactional Microsoft Transaction Server component is accessing an Oracle 7.3 or Oracle8 database, please check the following:
Make certain that the Microsoft DTC Service is “Started” on the system on which your Microsoft Transaction Server components are deployed.
You can check the status of the Microsoft DTC Service using the “Services” Control Panel applet. From the “Start” menu select “Settings” and then “Control Panel”. Start the “Services” applet on the control panel. Use the Services applet to ensure that “MSDTC” is “Started”. If Microsoft DTC is not started, you can start it by selecting “MSDTC” and then clicking “Start”.
Ensure that the latest Oracle 7.3 or Oracle 8 Client software patch release is installed on the system containing your Microsoft Transaction Server components. Customers often upgrade these Oracle patch releases on the system containing their Oracle database but fail to install the Oracle patch release on the system containing their Microsoft Transaction Server components. Oracle has corrected several bugs that affect their XA transactional client support; therefore, installing the latest Oracle patch release on your Microsoft Transaction Server system may eliminate the “Failed to Enlist” error.
You can obtain the latest Oracle patches Windows NT from the Oracle FTP site. Go to ftp://oracle-ftp.oracle.com and select "server", "wgt-tech", "server", and "windowsNT"
If your Microsoft Transaction Server application is accessing an Oracle database on either Windows NT or Unix, ensure that the latest Oracle patch is installed on that system.
You can obtain the latest Oracle patches for Windows NT from the Oracle FTP site. Go to ftp://oracle-ftp.oracle.com and select "server", "wgt-tech", "server", and "windowsNT"
Make certain that your Microsoft Transaction Server application is using the Microsoft Oracle ODBC Driver. No other Oracle ODBC driver supports Microsoft Transaction Server transactions.
You must install one of the following Microsoft Oracle ODBC drivers if you wish to use Microsoft Transaction Server transactions from an Intel x86 platform.
|
MS Oracle ODBC Driver |
Version Number |
Release Vehicles |
|
2.0 updated |
2.73.7283.03 |
MDAC 1.5b & MDAC 1.5c & Windows NT 4.0 Option Pack |
|
2.0 updated |
2.73.7356 |
ODBC 3.5 SDK |
|
2.5 |
2.573.2927 |
Visual Studio 6.0 & Data Access SDK 2.0 & MDAC 2.0 |
You must install the Microsoft Oracle ODBC 2.5 driver version 2.573.2927, if you wish to use Microsoft Transaction Server transactions from a Compaq Alpha platform. Earlier versions of the Microsoft Oracle ODBC driver did not support the Compaq Alpha platform.
You can obtain the Microsoft Oracle ODBC Driver 2.5 from www.microsoft.com/data by following the “Downloads” link.
If you wish to access an Oracle database, we suggest that you use the Microsoft Oracle ODBC Driver 2.0 or later driver even if you do not require transaction support. This new driver offers better performance than the Microsoft Oracle ODBC 1.0 driver it replaced The Oracle 1.0 driver serialized all activity at the driver level; requests were single-threaded through the driver. The Microsoft Oracle 2.0 and later drivers serialize all activities at the connection level. This allows different database connections to be used in parallel.
Ensure that Oracle XA transaction support has been properly enabled. For more information, refer to the section titled “Enabling Oracle XA Transaction Support” in the document “Using Oracle Databases with Microsoft Transaction Server”.
a.
If you are using Oracle 7.3, ensure that V$XATRANS$ exists.
This view should have been created when the XA library was installed. If this
view does not exist, your Oracle system administrator must create it by running
the Oracle-supplied script named "XAVIEW.SQL". This file can be found
in C:\ORANT\RDBMS73\ADMIN. This SQL script must be executed as the Oracle user
“SYS”.
If you are using Oracle8, this view should exist. You should not need to create
it.
b. For both Oracle 7.3 and Oracle8, the Oracle system administrator must grant SELECT access to the public on the DBA_PENDING_TRANSACTIONS view.
Grant Select on V$XATRANS$ to public.
c. In the Oracle Instance Manager, click “Advanced Mode” on the View menu and select “Initialization Parameters” in the left pane. In the right pane, select “Advanced Tuning” and increase the "distributed_transactions" parameter to allow more concurrent MTS transactions to update the database at a single time.
Consult your Oracle Server documentation for more information about configuring Oracle XA transaction support.
Customers running outside the United States may need to configure Oracle numeric character support. Add the following entry to your Windows NT registry using Regedit.
[HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE] "NLS_NUMERIC_CHARACTERS"=".,"
The characters inside the quoted string are a decimal point and a comma, in that order.
If you want to create more than a few dozen connections to an Oracle database, ensure that Oracle is configured to support additional database connections. For more information, refer to the section titled “Configuring Oracle to Support a Large Number of Connections” in the document “Using Oracle Databases with Microsoft Transaction Server”.
If you use Oracle Integrated Security make certain that Microsoft DTC is running under a login ID and password authorized to connect to you Oracle database. For more information, refer to the section titled “Configuring Integrated Security” in the document “Using Oracle Databases with Microsoft Transaction Server”.
Run the “TestOracleXAConfig” program to ensure that you can successfully connect to the Oracle database without using Microsoft Transaction Server. For more information, refer to the section titled “Testing Installation and Configuration of MTS Support for Oracle” in the document “Using Oracle Databases with Microsoft Transaction Server”.
Run the Sample Bank application to ensure that you can successfully connect to the Oracle database from a Microsoft Transaction Server application. For more information, refer to the section titled “Validating Oracle Installation and Configuration Using the Sample Bank Application” in the document “Using Oracle Databases with Microsoft Transaction Server”.
Oracle is capable of generating trace files that record the information sent between the Oracle client and server. These trace files can be extremely helpful in diagnosing problems. You can enable Oracle tracing as follows:
a. Ensure that the mtxoci.dll installed on your MTS system is version 1998.08.762.0 or later. Version 1998.08.762.0 was released with the NT4 Service Pack 4 release. It was the first version of the mtxoci.dll that allows you to enable Oracle tracing and control the location of Oracle trace files.
b. Use the Explorer to find and delete any existing Oracle trace files on your system. These files have names ending with the suffix “.TRC”. By deleting any obsolete trace files, you make it easier to find any newly created ones.
c.
Run REGEDIT to create the
following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Transaction Server\Local
Computer\My Computer\OracleTraceFilePath
Give this key the following REG_SZ value:
C:\OraTrace+DbgFl=7
You may choose a different disk drive and
directory for the trace files if you wish.
d. Use the Explorer to create the Oracle trace file directory. In our example, create the directory “OraTrace” on the “C” drive.
e. Stop the MTS package that is accessing the Oracle database. By stopping the package you ensure that all existing Oracle database connections are closed and that new Oracle database connections will be opened when the MTS component is next invoked. These newly opened Oracle database connections will have Oracle tracing enabled.
f. Invoke the Microsoft Transaction Server component that is opening the Oracle database.
g. Examine the newly created Oracle trace files.
MTS is capable of capturing additional information regarding Oracle errors in the Windows Application Event log. You can capture this information as follows:
a.
Run REGEDIT to create the following
registry key
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows
NT\CurrentVersion\IniFileMapping\MTx.Ini\TRACE
b. Stop the MTS package that is accessing the Oracle database. By stopping the package you ensure that the mtxoci.dll will perform tracing when it is restarted.
c. Invoke the Microsoft Transaction Server component that is opening the Oracle database.
d. Use
the Windows Event Viewer to examine the Application event log. Look for events
generated by MTXOCI. You may see events like the following:
String message: sqlld2 call failed with error
0x849.
The error value is displayed in octal. You can use the Calculator program
to convert the error value into decimal. In this example, “0x849” translates
into the Oracle error value 2121.
Consider whether the Microsoft Transaction Server component’s transaction may have aborted before the database enlistment completed. This may occur if the transaction time out expires before the Oracle database enlistment completes.
You can increase the transaction timeout value through the Microsoft Transaction Server Explorer. To do this, run the Microsoft Transaction Server Explorer and select “Computers”. Right click on the computer where the transaction was initiated and select “Properties”. Select the “Options” tab and specify a longer “Timeout” value.
This is unlikely to be the problem unless your transactions last for more than one minute. However, it may be helpful to temporarily increase the timeout value to eliminate this as a potential source of trouble.
If you still get this error after doing everything described here, you should report the error to the Microsoft Product Support organization. Please supply the following information with your problem report.
Does the “Failed to enlist error” occur every time you attempt to use Microsoft Transaction Server transactions or is the failure intermittent? If the failure is intermittent, how often does it occur?
Describe your application and system configuration.
a. Describe the system on which your Microsoft Transaction Server application components reside. If you are using an Oracle database, what version of the Oracle client software are you using and what version of the Microsoft Oracle ODBC Driver are you using.
b. Are you using a Microsoft SQL or an Oracle database? Does your database reside on the same system as you Microsoft Transaction Server application components or is it on a separate system? If you are using an Oracle database, what kind of system does the Oracle database reside on and what version of Oracle software are you using?
c. What network transport are you using: TCP/IP, Named Pipes, SPX/IPX, etc? What name service are you using: WINS, DNS, Host files, etc?
If you are using an Oracle database does the TestOracleXAConfig program run? If this program fails, the problem lies with Oracle. Please report the problem to the Oracle support organization.
Does the Sample Bank application run with Microsoft SQL Server? If you are using an Oracle database, does the Sample Bank application run with Oracle? If the Sample Bank application fails, what error are you experiencing?
If you are using an Oracle database, what information is present in the Oracle trace files? To capture this information, start by finding and deleting all existing Oracle trace files on your system. These files have names ending with the suffix “TRC”. After you delete any existing trace files, rerun the failing Microsoft Transaction Server component and provide us with the contexts of the Oracle trace files.
Check the Windows NT event log and report any MS DTC and MTXOCI events recorded there at or near the time of the failure.
Please tell us if you are using Oracle Integrated Security.
Please tell us what transaction timeout value is configured in Microsoft Transaction Server.