7
Troubleshooting

This chapter provides Oracle Service for MTS troubleshooting information.

Specific topics discussed are:

• Using Trace Files
• Correcting Windows NT Explorer Crashes
• Identifying Oracle Service for MTS Startup Problems
• Using the Event Viewer
• Starting MS DTC
• Viewing Oracle Service for MTS Configuration Information
• Correcting Net8 Changes that Impact Connection Pooling
• Common Questions

Using Trace Files

Trace files record information on Oracle Service for MTS performance. The information provided includes:

• Any errors
• Enlistment requests and outcomes
• Prepare, commit, and abort requests and outcomes

Use the Advanced tab of the Oracle Service for MTS Properties dialog box to specify trace levels and the output file name. You access this dialog box through the Oracle Manager for MTS Services snap-in of the Microsoft Management Console Explorer. See section "Modifying Oracle Service for MTS Trace File and MS DTC Information" for instructions.

In addition, there are two registry parameters to handle tracing within ORAMTS.DLL. ORAMTS.DLL implements the API for integrating the Oracle8i database with Microsoft Transaction Server. ORAMTS.DLL is a resource dispenser providing pooled OCI connections. ORAMTS.DLL also allows clients with non-pooled OCI connections to enlist in MS DTC-initiated transactions. The ORAMTS.DLL communicates with the Oracle Service for MTS to enlist the Oracle8i database in MS DTC-initiated transactions.

Parameter	Description	Data Type	Value Range
ORAMTS_CP_TRACE_LEVEL	Traces the Resource Dispenser layer within ORAMTS.DLL. A trace file is generated in the working directory of the process using ORAMTS.DLL. The trace file name uses the following format:  ORAMTSCPPID.TRC  where PID is the identification number of the process. New trace information is always added to the bottom of the file.	REG_EXP_SZ	0 to 4
ORAMTS_RPC_TRACE_LEVEL	Traces the remote procedure call (RPC) layer within ORAMTS.DLL. The RPC is used between the Oracle Service for MTS and the client to enlist in MS DTC transactions. A trace file is generated in the working directory of the process using ORAMTS.DLL. The trace file name uses the following format:  ORAMTSRCPPID.TRC  where PID is the identification number of the process. New trace information is always added to the bottom of the file.	REG_EXP_SZ	0 to 4

This table describes the range of trace values:

Level	Description
0	No tracing1
1	Traces errors only
2	Traces important events in addition to errors
4	Traces function entry/exit, important events, and errors

1 If neither registry parameter is set in the registry or as an environment variable, then tracing is disabled (the same as setting the level to 0). Note also that Level 3 is not currently supported. If you set either parameter to 3, level 2 tracing is instead enabled.

Set these parameters either as environmental variables for in- or out-of-process Microsoft Transaction Server components at the MS-DOS command prompt or in the registry:

To Set...	Then...
As an environment variable for in-process Microsoft Transaction Server components	In-process Microsoft Transaction Server components run as DLLs in the address of the clients invoking them.  Set ORAMTS_CP_TRACE_LEVEL to a value at the MS-DOS command prompt prior to launching your application:  C:\> SET ORAMTS_CP_TRACE_LEVEL=4  C:\> MYINPROCAPP.EXE
As an environment variable for out-of-process Microsoft Transaction Server components	Out-of-process Microsoft Transaction Server components are typically hosted by an external process, typically ROOTDRIVE:\WINNT\SYSTEM32\MTX.EXE.  The environment for this process is the system environment. Therefore, set ORAMTS_CP_TRACE_LEVEL as a system level or user-level environment variable. However, this requires the user to reboot the server. To avoid this, perform the following steps:  Stop all running MTX.EXE processes:  C:\> MTXSTOP  Set the environment variable:  C:\> SET ORAMTS_CP_TRACE_LEVEL=2  Manually start the surrogate process. MTX.EXE takes an argument, which is the package name of interest.  C:\> START MTX.EXE /p:"OraMTSSample"  C:\> MYOUTPROCAPP.EXE
As a registry variable	Enter the following at the MS-DOS command prompt:  C:\> REGEDT32  Go to HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEID, where ID is the identifier for your Oracle home directory.    Choose the Add Value option in the Edit menu. The Add Value dialog box appears.    Enter the appropriate parameter in the Value Name field.    Select REG_EXPAND_SZ in the Data Type field and click OK. The String Editor dialog box appears.    Enter an appropriate trace setting in the String Editor dialog box and click OK.    Exit the registry.

Warning: Tracing at level 4 can lead to performance degradation and large trace files. In general, turn on tracing only for debugging purposes. ORAMTS.DLL is also used by the Oracle Service for MTS. Setting the parameters in the registry also controls tracing within the Oracle Service for MTS.

Oracle Service for MTS tracing is controlled through the Oracle Manager for MTS Services snap-in.

Correcting Windows NT Explorer Crashes

If you experience Windows NT Explorer crashes or other unexpected Windows NT problems when using Microsoft Transaction Server with an Oracle8i database, install the Windows NT 4.0 Service Pack 4 available from Microsoft.

Identifying Oracle Service for MTS Startup Problems

When the Oracle Service for MTS is correctly configured and running properly, the trace file displays the following message:

============================================
OracleMTSService0 
9/11/1998 19:58:09 
--------------------------------------------
... 
530515: [273] Oracle MTS Service - Accepting new enlistment requests. 
...

If this message is not present and the Oracle Service for MTS is running (that is, the process has not exited), then the Oracle Service for MTS cannot complete the startup process. These are the most common causes for this problem:

Cause	Solution
The database has not been started or the account information of the service is incorrect.	Try connecting with SQL*Plus using the user name and database alias (net service name) that the Oracle Service for MTS is configured to use. If SQL*Plus fails to connect, the Oracle Service for MTS also fails. To correct this problem, start up the database and/or correct the login information of the Oracle Service for MTS. See Appendix B, "Deleting or Modifying an Existing Oracle Service for MTS" for information.
MS DTC is not running.	Using the Microsoft Transaction Server Explorer, verify that MS DTC is running. If MS DTC is not running, see section "Starting MS DTC" for startup instructions.
Recovery is being performed or cannot complete.	The Oracle Service for MTS does not start new transactions before all active transactions from an older run of the service are aborted. The following message is written to the trace file when recovery starts:  529765: [273] Recovery - Starting. In-doubt: number, Active: number. The number following "Active:" indicates the number of active transactions to abort. If the trace file shows that active transactions cannot be aborted during recovery, do the following:  Stop the Oracle Service for MTS.  Shut down the Oracle8i database.  Start the Oracle8i database. This procedure terminates all active transactions.  Start the Oracle Service for MTS. The service should now start without any problems.
Windows NT 4.0 Service Pack 4 or the special downloadable MS DTC patch is not installed.	Install either product (Service Pack 4 is recommended).  When neither product is installed, the following message is written to the trace file:  790172218: [135] DTCMgr::Initialize - Error: QueryInterface(IID_IResourceManager2) failed with error -2147467262. Retrying.    790172218: [135] DTCMgr::Initialize - Error: please make sure MS DTC is running.    790172718: [299] OracleMTSService0 is exiting.

Using the Event Viewer

Oracle Service for MTS problems and other significant occurrences are recorded as events. These events are recorded in an application event log. View and manage these recorded events in the Event Viewer. The types of events displayed include:

• MS DTC startup or shutdown status
• Recovery failure
• Oracle8i database startup or shutdown status
• Fatal errors that prevent Oracle Service for MTS startup

Accessing the Event Viewer

To access the Event Viewer:

1. Choose Start > Programs > Administrative Tools > Event Viewer.

The Event Viewer window appears.

2. Choose Application from the Log menu.

The Application view displays the following information:

Reading the Event Viewer

The icons beside each event determine the type of event:

Icon	Event Type	Description
red (stop sign)	Error	Indicates an error. Always check these icons.
blue (informational)	Information	Indicates a non-critical system event. You can ignore these icons unless you want to track a specific event.
yellow (exclamation point)	Warning	Indicates a special event, such as the termination of an instance or the shutdown of services. Investigate these icons, but they are usually non-critical.

The Oracle Service for MTS events display with a source of Oracle Service for MTS. Oracle Service for MTS consists of the following event IDs:

Event ID	Description
1	The Oracle Service for MTS started successfully.
2	The Oracle Service for MTS exited.
3	The Oracle Service for MTS failed to start. See the trace file for details.
4	The Oracle Service for MTS failed to start due to insufficient memory.
5	The Oracle Service for MTS failed to start. The service configuration parameters are missing or invalid.
6	The Oracle Service for MTS failed to start. Communication with the Service Control Manager failed.
7	The Oracle Service for MTS failed to start because CreateEvent failed.
8	The Oracle Service for MTS failed to start. The recovery mechanism failed. See the trace file for details.
9	The Oracle8i database has shut down, and the Oracle Service for MTS is stopping.
10	The Oracle Service for MTS has been notified that MS DTC is shutting down and exiting.
11	The trace file cannot be created and/or opened. The Oracle Service for MTS runs, but no trace information can be generated.
12	Missing parameter.
13	Invalid parameter.

Using the Event Viewer

To use the Event Viewer:

1. View the icons.

2. Double-click an icon to analyze (especially red icons).

The Event Detail dialog box appears with more information about the selected event:

Additional Information: See your Microsoft Windows NT documentation for more information on using the Windows NT Event Viewer.

Starting MS DTC

If the Oracle Service for MTS is running, but you do not receive a message in your trace file indicating that it is accepting new enlistment requests, ensure that the Microsoft Transaction Server's MS DTC component is started. MS DTC must be running to enable communication with the Oracle Service for MTS.

To start MS DTC:

1. Go to the computer on which Microsoft Transaction Server is installed and the Oracle Service for MTS is configured.

2. Choose Start > Programs > Windows NT 4.0 Option Pack > Microsoft Transaction Server > Transaction Server Explorer.

The Microsoft Management Console appears.

3. Double-click Console Root in the Microsoft Management Console Explorer window.

 
4. Double-click Microsoft Transaction Server.

 
5. Double-click Computers.

 
6. Right-click My Computer.

A menu appears with several options.

7. Choose Start MS DTC.

MS DTC starts.

Viewing Oracle Service for MTS Configuration Information

The Oracle Manager for MTS Services snap-in includes an Identification tab in the Oracle Service for MTS Properties dialog box that enables you to view information that can be useful when debugging problems with Oracle Support Services. Note that none of the information in the Identification tab can be changed.

To view configuration information:

1. Go to the computer from which to modify the Oracle Service for MTS. The Oracle Service for MTS can be running on this computer or on a remote computer that you can access from this computer.

2. Choose Start > Programs > Oracle - HOME_NAME > Application Development > Oracle Manager for Microsoft Transaction Server.

The Microsoft Management Console appears.

3. Find the Oracle Service for MTS to modify in the Explorer window.

 
4. Right-click the Oracle Service for MTS icon to modify.

A menu appears with several options:

5. Choose Stop Service.

A message indicates that the Oracle Service for MTS has stopped.

6. Right-click the same Oracle Service for MTS icon again.

A menu appears with several options.

7. Choose Properties.

The Properties dialog box appears.

8. Click the Identification tab.

 
9. View the following information:

 

 
 
 




Field	Description
NT Service Name	Displays the Oracle Service for MTS service name (for example, OracleMTSService0). This is the service name that displays in the Services dialog box of the Windows NT Control Panel.
Resource Manager GUID	Displays the resource manager global unique identifier (GUID) for identifying an Oracle8i database and its associated Oracle Service for MTS to MS DTC.
Database ID	Displays a value unique to each Oracle8i database. The Oracle Service for MTS retrieves this value from the database and sets it the first time it ever connects to that database.
Database Name	Displays the Oracle8i database name (as identified by the DB_NAME INIT.ORA file parameter value). The Oracle Service for MTS retrieves this value from the database and sets it the first time it connects to that database.

Correcting Net8 Changes that Impact Connection Pooling

The connection pool provided by the ORAMTS layer (that is, ORAMTS.DLL) uses a connection's Net8 net service name to identify pooled connections for an application. If changes are made to the Net8 net service name (for example, altering the host or the database system identifier (SID) for the Net8 net service name in TNSNAMES.ORA), and there are currently pooled connections, the application using the connection pool must be stopped and restarted.

This ensures that all currently pooled connections corresponding to the old Net8 net service name are destroyed and any new pooled connections use the changes made to the Net8 net service name. This includes both the Oracle Service for MTS and any application hosting Microsoft Transaction Server components.

Note: It is not recommended that you change the Net8 net service name that the Oracle Service for MTS uses to connect to a different database. If you must do this, follow the procedures in section "Preparing to Modify or Delete an Existing Oracle Service for MTS" before changing the Net8 net service name.

To empty connection pools:

1. Follow the instructions below:




If Your Application is an...	Then...
Out-of-process Microsoft Transaction Server component	Run the following application:  C:\> MTXSTOP  This empties the connection pools.
In-process Microsoft Transaction Server component	Kill the application, which also empties the connection pool.

Note: See the table in section "Using Trace Files" for definitions of out-of-process and in-process Microsoft Transaction Server components.

Common Questions

This section presents answers to common questions you may have when using Microsoft Transaction Server with an Oracle8i database.

Question: How do I design an application when I have multiple Oracle8i databases?

This release of the Oracle Service for MTS does not support the use of database links between Oracle8i databases running in dedicated server configurations. As alternatives, the Oracle Service for MTS supports using database links in a multi-threaded server environment or providing each Oracle8i database with its own Oracle Service for MTS in a dedicated server environment. This figure illustrates these alternatives:

Question: What are the differences between Oracle's Net8 connection pooling, OCI connection pooling, and Microsoft Transaction Server connection pooling?

Net8 connection pooling is a server-side feature that is implemented only if your Oracle8i database is configured for multi-threaded server support. Net8 connection pooling enables you to minimize the number of physical network connections to a multi-threaded server. This is achieved by sharing a dispatcher's set of connections among multiple client processes.

OCI connection pooling is a client-side feature that allows for the caching of Net8 connections to Oracle8i databases. It also allows for the multiplexing of multiple sessions to an Oracle8i database over a single Net8 connection. This second feature is not supported in ORAMTS.DLL for this release because of potential deadlock issues.

Microsoft Transaction Server connection pooling maintains a pool of Net8 connections and only uses one OCI session per Net8 connection.

Question: Can you use operating system authentication with your Oracle Service for MTS user name?

Yes, but only on Windows NT. Operating system authentication is not supported when connecting to databases on other platforms. See the Getting Started guide included with your Oracle8i database on Windows NT. See the following sections in this guide for instructions on creating an operating system-authenticated Oracle Service for MTS user:

To Enable Operating System Authentication For...	See...
A new Oracle Service for MTS	"Creating a New Operating System Authenticated Oracle Service for MTS"
An existing Oracle Service for MTS	"Enabling an Existing Oracle Service for MTS to be Operating System Authenticated"

---