FIX: Mtxoci.dll Logging Support Enabled (230145)

RESOLUTION

Windows NT Server or Workstation 4.0

A hotfix (ID: 051099b) is available that enables logging in Mtxoci.dll. This fix can help in troubleshooting problems when using the DTC transactions and an Oracle server. When used in conjuction with the Oracle XA tracing, it can help narrow down problems very quickly.

Microsoft recommends that this fix be used only for troubleshooting purposes. It does not contain any changes that would modify the behavior from the product version that is currently shipping with Windows NT 4.0 Service Pack 4 or 5. It is included as part of Windows NT 4.0 Service Pack 6a. For more information or to download this Service Pack, please see the STATUS section of this article.

A supported hotfix is now available from Microsoft, but it is only intended to correct the problem that this article describes. Apply it only to systems that are experiencing this specific problem.

To resolve this problem, contact Microsoft Product Support Services to obtain the hotfix. For a complete list of Microsoft Product Support Services telephone numbers and information about support costs, visit the following Microsoft Web site:

http://support.microsoft.com/contactus/?ws=support

Note In special cases, charges that are ordinarily incurred for support calls may be canceled if a Microsoft Support Professional determines that a specific update will resolve your problem. The usual support costs will apply to additional support questions and issues that do not qualify for the specific update in question.

The English version of this fix should have the following file attributes or later:

        Date      Version         Size    File name    
        -------------------------------------------- 
i386    5/1/99    1999.2.853.0    85KB    Mtxoci.dll
alpha   5/1/99    1999.2.853.0   109KB    Mtxoci.dll

Windows NT Server 4.0, Terminal Server Edition

To resolve this problem, obtain the latest service pack for Windows NT Server 4.0, Terminal Server Edition. For additional information, click the following article number to view the article in the Microsoft Knowledge Base:

152734 How to Obtain the Latest Windows NT 4.0 Service Pack

MORE INFORMATION

Who Should Install This Release

You should install hotfix 051099b if you need logging support in Mtxoci.dll in order to better troubleshoot a problem involving Oracle, DTC, and XA.

Installation

This hotfix should be installed only on systems running Microsoft Windows NT version 4.0 (Service Pack 4 or later is recommended). It should not be installed on systems running Microsoft Windows NT version 3.51 or Microsoft Windows 2000.

Note that this hotfix is based on the version of Microsoft DTC included with the Windows NT 4.0 Service Pack 5 release. By installing this hotfix, you are upgrading Microsoft DTC to the Windows NT 4.0 Service Pack 5 release level in addition to correcting the problems described here.

How to Install on a Nonclustered System

Create an empty temporary directory on your system.
Run the self-extracting executable file (i051099b.exe (i386) or a051099b.exe [alpha]) and type the name of the temporary directory when you are prompted to do so. The program will unzip the following files into the temporary directory:
- Dtcsetup.exe
- Qfe051099b.txt
Stop the Microsoft DTC Service, if it is running. Stop all services that depend on Microsoft DTC (including Microsoft Transaction Server, Microsoft SQL Server, Microsoft Message Queue, and Microsoft COM Transaction Integrator [COMTI]).
Close Control Panel, if it is open.
Run Dtcsetup.exe.
Restart the system.
Restart all services that depend on DTC.

How to Install on a Cluster with an Already Clustered Microsoft DTC

Create an empty temporary directory on both nodes of the cluster.
Run the self-extracting executable file (i051099b.exe (i386) or a051099b.exe [alpha]) on both nodes of the cluster and type the name of the temporary directory when you are prompted to do so. The program will unzip the following files into the temporary directory:
- Dtcsetup.exe
- Qfe051099b.txt
Use the MSCS Cluster Administrator to stop the Microsoft DTC cluster resource if it is running. Stop all services that depend on Microsoft DTC (including Microsoft Transaction Server, Microsoft SQL Server, Microsoft Message Queue, and Microsoft COMTI).
Close Windows NT Control Panel on all systems in the cluster.
Run Dtcsetup.exe on the node that controls the Microsoft DTC cluster resource. When you are prompted to install Microsoft DTC on the other nodes in the cluster, run Dtcsetup.exe on those nodes.
Restart all systems.
Restart all services that depend on Microsoft DTC.

How to Install on a Cluster with a Non-clustered Microsoft DTC

Create an empty temporary directory on both nodes of the cluster.
Run the self-extracting executable file (i051099b.exe [i386] or a051099b.exe [alpha]) on both nodes of the cluster and type the name of the temporary directory when you are prompted to do so. The program will unzip the following files into the temporary directory:
- Dtcsetup.exe
- Qfe051099b.txt
Stop the Microsoft DTC Service on all systems in the cluster. Stop all services that depend on Microsoft DTC (including Microsoft Transaction Server, Microsoft SQL Server, Microsoft Message Queue, and Microsoft COMTI).
Close Windows NT Control Panel on all systems in the cluster.
When you install this release on a clustered system, the Setup program automatically installs a clustered version of Microsoft DTC. The clustered version of Microsoft DTC requires an MSCS Resource Group that contains both a Network Name Resource and a Shared Disk Resource. Before installing this release, ensure that at least one such MSCS Resource Group exists. Dtcsetup.exe assigns Microsoft DTC to the first MSCS Resource Group that it finds that contains both a Network Name Resource and Shared Disk Resource. After ensuring that the necessary Resource Group exists, run Dtcsetup.exe on the node controlling that Resource Group.
When you are prompted to install Microsoft DTC on the other nodes in the cluster, run Dtcsetup.exe on those nodes.
Reboot all systems.
Restart all services that depend on Microsoft DTC.

Enabling Logging:

The following registry setting turns on logging and sets the log path as well:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping\mtx.ini

To enable logging and set the log path, create a named string (REG_SZ) value named DebugTrace. Set the value equal to the path that you wish to log to, for example:

C:\Temp\MtxOci

Reading the Log Output

The log files will have significantly more meaning to Microsoft and Oracle Product Support personnel, but it is possible to use the information in the log to troubleshoot some problems assuming that you have some knowledge of the DTC Resource Manager specification and the XA protocol specification.

File Naming convention:

The naming convention used for the log files is:

MtxOCI-Month-Day-Year-Hour-Minute--ProcessID.log

The process ID can be used to associate the log to a given server process.

Log file Format:

MTXOCI logs out an entry into the file when certain key functions in the code are hit. These include the following:

CreateConnectionAPI - Out/App - helper function for making OCI connections.
COCIConnection::Connect - Out/App - function that makes the actual xa_open call.
COCIConnection::Disconnect - Out/App - function that makes the actual xa_close call (and xa_end if still pending).
COCIConnection::Enlist - Out/App - function that makes the xa_start call.
COCIConnection::PrepareRequest - Out/DTC - function that makes the xa_prepare or xa_commit (single phase) call.
COCIConnection::CommitRequest - Out/DTC - function that makes the xa_commit call.
COCIConnection::AbortRequest - Out/DTC - function that makes the xa_rollback call.
COCIConnection::Init - Out/App - function that registers the connection with DTC and XA (xa_open)
COCIConnection::MakeCallAsynch - In/DTC - function that handles incoming DTC requests and schedules one of the above functions to be called.
COCIConnection::StateMachineDriver - In/Out/App/DTC - function that handles the entire state machine. Is the root or in decision tree of all above functions.
- In = A call that is made as a result of a call into MTXOCI
- Out = A call that is going to make a call into XA.
- App = A call that originated in the application.
- DTC = A call that originated in DTC.

Keywords in log entries:

pConn = this is the physical address of the OCI connection. Useful only for comparison throughout log.
openstring = the actual string used in the xa_open call. This can be compared with that in the XA log files generated by Oracle.
XALib = Library registering with XA - should always be Mtxoci.dll.
RMId = Unique identifier for the RM. This is most useful for enlistment. It is incremented each time a new connection enlists in the same transaction and can used to differentiate connections enlisted in the same transaction.
ThreadId = ID of the thread. This can be used to track threads throughout log and to compare with stack traces from a debugger.
TransactionState = Current state of the transaction. Can be used to troubleshoot state machine issues.
RequestId = Requested new state for the transaction. Can be used to troubleshoot state machine issues.
UOW = The DTC transaction identifier. Can be compared with DTC monitoring tool output and MTS Spy logs.
GTRID = The XA version of the transaction identifier. Printed in a form that makes it easier to compare to the Oracle XA trace files.