INFO: Failed to Enlist on Calling Object's Transaction

• Microsoft Transaction Server, versions 1.0, 2.0

SUMMARY

What does the message "Failed to Enlist on calling object's transaction" mean?

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.

This article references a white paper titled "Using Oracle Databases with Microsoft Transaction Server." For information about obtaining this document, see the following Knowledge Base article:

Q191517 Using Oracle Databases with MTS White Paper

MORE INFORMATION

When Using Microsoft SQL Server

1. Ensure that the Microsoft Distributed Transaction Coordinator (MS DTC) Service is started. Make certain that the MS 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 MS DTC Service is started on that system also. This is frequently the cause of the "Failed to Enlist Error." Perform the following steps to check the status of the MS DTC Service: a. On the Start menu, point to Settings, and then click Control Panel. b. Double-click the Services icon. c. Scroll through the Services list and confirm that the Status of the MS DTC service is Started. If the MS DTC Status is blank (not started), you can start it by selecting MSDTC and then clicking Start.



2. Check Your Network Configuration. When a transactional Microsoft Transaction Server component on one system accesses a SQL Server database on another system, MS 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. The DTC processes establish remote procedure call (RPC) connections in both directions, which means that a network configuration problem on either system can prevent the DTC processes from successfully communicating with one another. This causes ODBC to return a "Failed to Enlist" error. Often the following MS 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 the Microsoft Transaction Server computer was able to bind to DTC on the SQL Server, but DTC on the SQL Server could not perform the reverse bind to the Microsoft Transaction Server computer. If this occurs, check your network configuration using Pingtest.bat as follows: a. Use a text editor (such as Notepad) to create a file named Pingtest.bat. Copy the following batch file commands into it. 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 The batch file uses %computername% to display the local IP address. It then displays the IP address of the remote computer you specify in the command line when you run the batch file. When you invoke the batch file, you must specify the name of the remote computer and not its IP address. Using the machine name forces ping to resolve the machine name exactly the same as MS DTC does when it binds to the remote MS DTC computer. b. Run Pingtest.bat on the Microsoft Transaction Server computer to determine if you can ping the SQL Server computer by name. Capture the output from the batch file in a text file. For example, if Microsoft Transaction Server is running on computer A and SQL Server is running on computer B, use the following command: Pingtest B > AResults.txt c. Run Pingtest.bat on the SQL Server computer to determine if you can ping the Microsoft Transaction Server computer by name. Capture the output from the batch file in a text file. For example, if Microsoft Transaction Server is running on computer A and SQL Server is running on computer B, use the following command: Pingtest A > BResults.txt d. Examine the contents of the two text files to ensure that the two computers 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 computer and the SQL Server computer. Frequently, the file on one system will be correct, while that on the other system is incorrect.



3. Configure the SQL Server to use TCP/IP rather than Named Pipes. Microsoft strongly recommends that you configure the SQL Server to use TCP/IP rather than Named Pipes. Using Named Pipes can result in Intermittent "Failed to Enlist" errors. a. On the Start menu, point to Programs, point to Microsoft SQL Server 6.5, and then click SQL Client Configuration Utility. b. Click the Net Library tab. c. In the Default Network list, select TCP/IP Sockets. d. Click Done.



4. Check Transaction Timeout. The component's transaction may have aborted due to transaction time-out before the database enlistment completed. You can increase the transaction time-out value through the Microsoft Transaction Server Explorer. Use the following steps to increase the time-out value: a. Start the Microsoft Transaction Server Explorer and select Computers. b. Right-click the computer where the transaction was initiated and click Properties. c. Click the Options tab and specify a longer time-out value. This is unlikely to be the problem unless your transactions take an unusually long time. However, it may be helpful to temporarily increase the time-out value to eliminate this as a potential source of trouble.

When Using Oracle

1. Ensure that the MS DTC Service is started using the following steps to check its status: a. On the Start menu, point to Settings, and then click Control Panel. b. Double-click the Services icon. c. Scroll through the Services list and confirm that the Status of the MS DTC service is Started. If the MS DTC Status is blank (not started), you can start it by selecting MSDTC and then clicking the Start button.



2. Install the Oracle 7.3.4 release on the Microsoft Transaction Server computer. Ensure that Oracle 7.3.4 Client software is installed on the system that contains the Microsoft Transaction Server components. Note that it is common to upgrade the Oracle software on the system that contains the Oracle database but fail to upgrade the Oracle software on the system that contains the Microsoft Transaction Server components. You must upgrade the Oracle software on the client system.

1. Install the Oracle 7.3.4 release on the Windows NT Oracle Database Server System. If the Microsoft Transaction Server application accesses an Oracle database on a Windows NT system, ensure that the Oracle 7.3.4 release is installed on that system.

1. Install the latest Oracle release on the UNIX Oracle Database Server System. If the Oracle database is running on a UNIX system, ensure that the latest Oracle 7.3 patch release for that UNIX platform is installed on that system. You must check with Oracle Customer Support to determine if an Oracle 7.3 patch release is required for your UNIX platform. Explain that you are going to access your Oracle database on UNIX using the XA transaction support included in the Oracle 7.3.4 release for Microsoft Windows NT.



2. Use the Microsoft Oracle ODBC driver 2.0. Make certain that Microsoft Transaction Server is using the Microsoft Oracle ODBC driver version 2.0. No other Oracle ODBC driver supports Microsoft Transaction Server transactions. The Microsoft Oracle ODBC driver version 2.0 (Msorcl32.dll) that is installed by the Windows NT 4.0 Option Pack is version 02.73.7283.1. You may use this or any later version of the driver. If you wish to access an Oracle database, use the Microsoft Oracle ODBC driver version 2.0, even if you do not require transaction support. The version 2.0 driver offers better performance than the version 1.0 that it replaced. The version 1.0 driver serialized all activity at the driver level; requests were single-threaded through the driver. The version 2.0 driver serializes all activities at the connection level; this allows different database connections to be used in parallel.



3. Accessing an Oracle8 database. Your transactional Microsoft Transaction Server components may access an Oracle8 database on Windows NT. However, you must install Microsoft Transaction Server on one Windows NT computer and Oracle8 on another Windows NT computer. Microsoft Transaction Server and Oracle8 cannot coexist on a single computer. This restriction exists because the Microsoft Oracle ODBC driver is only capable of calling Oracle's 7.3 OCI client interfaces. It does not work with Oracle8 client interfaces. You must install the latest Oracle 7.3 client software on the system containing the Microsoft Transaction Server components. It may be possible to eliminate this restriction. Microsoft is investigating this issue, but has only tested Microsoft Transaction Server with Oracle8 when the two are on separate systems. The Oracle8 documentation discusses how to install and configure Oracle8 for coexistence with Oracle7 client software. For more information consult "Appendix F" in the following Oracle publication: Oracle 8[ASCII 153] Oracle Networking Products Release 8.0 for Windows Platforms Getting Started



4. Ensure that Oracle XA support is enabled. Check to be sure that Oracle XA transaction support has been enabled. For more information, refer to the section titled "Enabling Oracle XA Transaction Support" in the "Using Oracle Databases with Microsoft Transaction Server" white paper.



5. Ensure that Oracle numeric characters are configured correctly. WARNING: Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. For information about how to edit the registry, view the "Changing Keys And Values" Help topic in Registry Editor (Regedit.exe) or the "Add and Delete Information in the Registry" and "Edit Registry Data" Help topics in Regedt32.exe. Note that you should back up the registry before you edit it. Customers who have systems located outside the United States may need to configure Oracle numeric character support. In the Windows NT registry, locate the following registry key HKEY_LOCAL_MACHINE\SOFTWARE\Oracle and add this entry: "NLS_NUMERIC_CHARACTERS"=".," NOTE: The characters inside the quoted string above are a period and a comma, in that order.



6. Ensure that Oracle is configured with adequate connections. 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 "Using Oracle Databases with Microsoft Transaction Server" white paper.



7. Ensure that you have a connection to the Oracle database if you use Oracle Integrated Security. If you use Oracle Integrated Security, make certain that MS DTC is running under a login ID and password that is authorized to connect to the Oracle database. For more information, refer to the section titled "Configuring Integrated Security" in the "Using Oracle Databases with Microsoft Transaction Server" white paper.



8. Run the TestOracleXAConfig program. 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 "Using an Oracle Database with Microsoft Transaction Server" document.



9. Run the Sample Bank program. Run the Sample Bank program to ensure that you can successfully connect to the Oracle database from a Microsoft Transaction Server program. For more information, refer to the section titled "Validating Oracle Installation and Configuration Using the Sample Bank Application" in the "Using Oracle Databases with Microsoft Transaction Server" white paper.



10. Check the Oracle trace files. The Oracle trace files contain extended error information which can help you diagnose problems. To capture Oracle trace information, first find and delete all existing Oracle trace files on the system. These files have names ending with the .trc extension. After you delete all existing trace files, run the failing Microsoft Transaction Server component and examine the contents of the Oracle trace files.



11. Check Transaction time-out. Consider whether the Microsoft Transaction Server component's transaction may have ended 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 time-out value through the Microsoft Transaction Server Explorer. To do this, use these steps: a. Run Microsoft Transaction Server Explorer and select Computers. b. Right-click the computer where the transaction was initiated and click Properties on the shortcut menu. c. Click the Options tab and specify a longer time-out 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 time-out value to eliminate this as a potential source of trouble.

What to Do If You Still Get This Error

1. Describe the problem. 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?



2. Describe your application and system configuration. a. Describe the system the Microsoft Transaction Server application components are installed on. If you are using an Oracle database, provide the version of both the Oracle client software and the Microsoft Oracle ODBC driver are you using. b. Are you using a Microsoft SQL database or an Oracle database? Is the database on the same computer as the Microsoft Transaction Server application components or is it on a separate computer? If you are using an Oracle database, what kind of system is the Oracle database installed on and what version of Oracle software is installed? c. What network transport are you using: TCP/IP, Named Pipes, IPX/SPX, and so forth? What name service are you using: WINS, DNS, Host files, and so on?



3. Does the TestOracleXAConfig program run? If you are using an Oracle database, try to run the TestOracleXAConfig program. If this program fails, the problem lies with Oracle. Please report the problem to Oracle Customer Support.



4. Does the Sample Bank program run? Try to run the Sample Bank program with Microsoft SQL Server. If you are using an Oracle database, does the Sample Bank application run with Oracle? If not, what error are you experiencing?



5. What errors are reported in the Oracle trace files? If you are using an Oracle database, what information is present in the Oracle trace files? To capture this information, first find and deleting all existing Oracle trace files on the system. These files have names ending with the .trc extension. After you delete all existing trace files, run the failing Microsoft Transaction Server component and provide Microsoft with the contents of the Oracle trace files.



6. What errors are reported in the Windows NT event log? Check the Windows NT event log and report all DTC events that were recorded at or near the time of the failure.



7. Are you using Oracle Integrated Security? Report whether you are using Oracle Integrated Security.



8. What is the transaction time-out value? Advise what transaction time-out value is configured in Microsoft Transaction Server.

Additional query words: prodtranssrv

Keywords          : 
Version           : winnt:1.0,2.0
Platform          : winnt 
Issue type        : kbinfo 

Last Reviewed: June 18, 1999