Microsoft Transaction Server Error Diagnosis

Microsoft Corporation

June 1997

Abstract

This article describes how to determine the source of an error in your Microsoft® Transaction Server (MTS) version 1.0 application. You can diagnose the source and description of application errors by using a combination of Microsoft Windows NT®, MTS, and other tools. If you discover that the application error is caused by MTS, you can interpret the error message using the Win32® (Win32.h) or MTS header files (mts.h), or the Microsoft Visual C++® error utility.

Refer to the article "Debugging Microsoft Transaction Server Components" for more information on debugging an MTS application.

Finding the Source of the Error

If your server application is failing or causing unexpected behavior, you must first determine where your error occurred. Windows NT provides a system Event Viewer that tracks application, security, and system events. Refer to the Application Log in the Event Viewer first to check the application associated with the event message. (Because you can also archive event logs, you can track an event history of the error.) Selecting an entry in your log activates an Event Detail, which provides further information about the system event. If you attempt to run the Sample Bank client without starting the Microsoft Distributed Transaction Coordinator (MS DTC), you will be returned the following Automation error.

Since this error doesn't indicate which application caused the failure, you can reference the Application Log in the Event viewer, which shows the error was caused by MTS.

Interpreting Error Messages

The Event Viewer helps you determine the application source of the problem. You can use other tools to interpret individual error messages. Success, warning, and error values are returned using a 32-bit number known as a result handle, or HRESULT. HRESULTs are 32-bit values with several fields encoded in the value. A zero result indicates failure if that bit is set. A non-zero result can be a warning or informational message.

HRESULTs work differently, depending on the platform you are using. On 16-bit platforms, an HRESULT is generated from a 32-bit value known as a status code, or SCODE. On 32-bit platforms, an HRESULT is the same as an SCODE; they are synonymous. Note that if you are returning HRESULTs from Java™, you should throw an instance of com.ms.com.ComFailException to indicate failure. You can specify a particular HRESULT when constructing the ComFailException object. The HRESULT will be used as the return value for the COM method. To indicate successful completion, you don't need to do anything; just return normally. To return S_FALSE (indicating a successful completion but a return value of Boolean False), throw an instance of com.ms.com.ComSuccessException. In Visual Basic®, you use the Err.Raise function to set and the On Error…/Err.Number to retrieve HRESULTs.

For a list of the values of common system-defined HRESULTs, see ComFailException. For a complete list of system-defined HRESULT values, see the header file Winerror.h included with the Win32 SDK.

MTS never changes the value of an HRESULT error code (such as E_UNEXPECTED or E_FAIL) returned by an MTS object method. When an MTS object returns an HRESULT status code (such as S_OK or S_FALSE), MTS may convert the status code into an MTS error code before it returns to the caller. This occurs, for example, when the application returns S_OK after calling the SetComplete function; if the object is the root of an automatic transaction that fails to commit, the HRESULT is converted to CONTEXT_E_ABORTED. When MTS converts a status code to an error code, all the method's output parameters are cleared. Returned references are released and the values of the returned object pointers are set to NULL.

The Mtx.h header file contains the MTS-specific error codes. Winerror.h contains the error code definitions for the Win32 API functions. For an overview of error codes, see "Error Handling" in the ActiveX™ Programmer's Reference in the Win32 SDK.

You can also use the ERRLOOK utility in Microsoft Visual Studio™ 97 to retrieve a system error message or module error message based on the value entered. ERRLOOK retrieves the error message text automatically if you drag-and-drop a hexadecimal or decimal value from the Visual Studio debugger or other OLE-enabled application. You can also enter a value either by typing it in or pasting it from the IDE clipboard and clicking the Look Up option.

Contacting Microsoft Transaction Server Support

If you run into a problem that you cannot solve, you can contact Microsoft support with the following information:

• Topography of the application where the error occurred (for example, a description of packages, components, and interfaces)
  
  
• Application event log on all computers
  
  
• Reproduction of the error, if possible

Troubleshooting

If you are having trouble diagnosing your problem, refer to the following list of troubleshooting tips:

• Make sure that the Distributed Transaction Coordinator (DTC) is running on all servers.
  
  
• Check network communication by first testing on a local computer to verify that the application works. If you are running TCP/IP on your network, you can then use the Windows NT ping.exe utility to verify that the machines are on the network.
  
  
• Make sure that SQL and DTC are either located on the same computer or that the DTC Client Configuration program specifies that the DTC is on another computer. If not, SQLConnect will return an error internally when called from a transactional component.
  
  
• Set the MTS transaction timeout to a higher number than the default 60 seconds, otherwise MTS will abort the transaction after this time has lapsed. All subsequent calls to the component will return immediately with CONTEXT_E_ABORTED.
  
  
• Make sure that your ODBC drivers are thread-safe and do not have thread affinity.
  
  
• If you have difficulty getting an application to work over several servers, try rebooting the client and then verify that your Windows NT domain controller is configured properly.

See the DCOM documentation and DCOM-related Knowledge Base articles if you are experiencing application errors that you suspect are caused by DCOM.