Oracle Services for Microsoft Transaction Server

Oracle Services for Microsoft Transaction Server (OraMTS) allow client components to leverage Oracle database participation in MSDTC transactions. It acts as a proxy for the Oracle database to MSDTC to ensure that Oracle distributed database transactions commit or rollback together with the rest of the distributed transaction.

If a failure occurs, such as a network failure or server hardware failure, then it can leave an in-process distributed transaction in-doubt. OraMTS has a recovery service to resolve these transactions on the machine that began this transaction. This recovery service runs as a Windows service.

It is required to install the OraMTS Recovery Service on all the client machines where ODP.NET is running and participating in MSDTC. As a machine may have multiple IP addresses, administrators for managed ODP.NET applications can specify the host machine name or IP address that has the running recovery service in the application's .NET configuration file. ODP.NET, Unmanaged Driver automatically resolves the IP/machine name for the recovery service.

With .NET Framework 4.5.2, Microsoft introduced new API support that allows Oracle to use only managed calls to coordinate ODP.NET transactions with the MSDTC. ODP.NET utilizes this managed code with the managed driver (starting with ODAC 12c Release 3) and with the unmanaged driver (starting with ODAC 12c Release 4).

While ODP.NET, Unmanaged Driver developers can opt out of using OraMTS when using the latest .NET Framework and ODP.NET versions, they still need to install and configure the OraMTS Windows recovery service to manage recovery scenarios

ODP.NET, Managed Driver Setup

This section explains the setup and configuration steps required for using distributed transactions with ODP.NET, Managed Driver.

Oracle recommends that applications use .NET's native managed distributed transaction implementation (default), which is available in .NET Framework 4.5.2 or higher. Applications can set whether .NET's native managed distributed transaction or Oracle.ManagedDataAccessDTC.dll is used by setting the UseManagedDTC parameter in the .NET configuration file. Follow these steps to configure distributed transactions in these .NET Framework versions:

1. Create and setup the OraMTS recovery service or make sure an existing recovery service is running.

2. Set the value of OMTSRECO_PORT in the .NET configuration to specify the port number that the OraMTS recovery service is running.

Alternatively, you can still use Oracle.ManagedDataAccessDTC.dll with .NET Framework 4.5.2 and managed ODP.NET. To do so, set UseManagedDTC to true and follow the instructions listed below for .NET Framework 4.5.1.

For .NET Framework 4.5.1 and lower applications, follow these steps to setup and configure managed ODP.NET for distributed instructions:

1. Create and setup the OraMTS recovery service or make sure an existing recovery service is running.

2. Deploy Oracle.ManagedDataAccessDTC.dll along with the application.

3. Set the value of OMTSRECO_PORT in the .NET configuration to specify the port number that the OraMTS recovery service is running.

Oracle.ManagedDataAccessDTC.dll is included with ODP.NET, Managed Driver. This DLL makes unmanaged MSDTC COM calls to MSDTC, which means there is a 32-bit version and a 64-bit version of this DLL. These two DLLs share the same name. If you are using a 32-bit .NET Framework, then deploy the 32-bit Oracle.ManagedDataAccessDTC.dll. If you are using a 64-bit .NET Framework, then deploy the 64-bit Oracle.ManagedDataAccessDTC.dll. The DLLs are located in the following directories:

• For 32-bit .NET Framework: ORACLE_HOME\odp.net\managed\x86

• For 64-bit .NET Framework: ORACLE_HOME\odp.net\managed\x64

Upon ODP.NET installation, Oracle.ManagedDataAccessDTC.dll is no longer placed into the Global Assembly Cache (GAC). For applications that use this DLL, Oracle.ManagedDataAccessDTC.dll must either be placed in the application directory or in the GAC.

Oracle.ManagedDataAccessDTC.dll should not be directly referenced by a .NET application. It will be implicitly loaded by ODP.NET, Managed Driver when using distributed transactions.

For applications with platform target x64 or x86 specifically, Oracle.ManagedDataAccess.dll will load Oracle.ManagedDataAccessDTC.dll appropriately if it is placed into the GAC or if it resides in the application directory.

For applications that target AnyCPU, the corresponding Oracle.ManagedDataAccessDTC.dll needs to be placed into x64 and x86 subdirectories under wherever the Oracle.ManagedDataAccess.dll is loaded from by the application. ODP.NET, Managed Driver will load the appropriate Oracle.ManagedDataAccessDTC.dll assembly (32-bit or 64-bit), based on whether the application is 32-bit or 64-bit. If both 32-bit and 64-bit versions of Oracle.ManagedDataAccessDTC.dll are in the GAC, then the appropriate assemblies will be loaded automatically.

ODP.NET, Unmanaged Driver Setup

This section explains the setup and configuration steps required for using distributed transactions with ODP.NET, Unmanaged Driver.

For .NET Framework 4.5.2 and higher, ODP.NET, Unmanaged Driver has embedded a managed OraMTS implementation into its assembly. OraMTS remains the default implementation for the ODP.NET, Unmanaged Driver, but the managed OraMTS implementation is recommended when using any high availability FAN operations (HA Events = true) with Oracle Real Application Clusters or Oracle Data Guard. The managed OraMTS implementation supports this high availability functionality, while the traditional OraMTS does not.

Applications can set whether OraMTS (default) or managed OraMTS is used by setting the UseOraMTSManaged parameter in the .NET configuration file.

Install and configure OraMTS, including its recovery service to use OraMTS implementation for ODP.NET, Unmanaged Driver.

For .NET Framework 4.5.2 and higher applications, you can use the managed OraMTS implementation instead of the traditional OraMTS. To set this up, perform the following steps:

1. Set UseOraMTSManaged to true in the .NET configuration file.

2. Create and setup the OraMTS recovery service or make sure an existing recovery service is running.

Starting with Oracle Database 12c, Oracle Database on Windows software includes the oramtsctl.exe utility to enable manual creation of the OraMTS recovery service. ODP.NET, Managed and Unmanaged Drivers can both opt to use fully managed MS DTC solutions, which eliminates the need for OraMTS. However, in all cases, the OraMTS recovery service is still required to be setup. Every Oracle client machine that uses MS DTC must have one OraMTS recovery service configured. Multiple Oracle applications on the same machine can share using that one service. When run, the service will be created for the current Oracle home and runs as the Oracle Home User.

To manually create an Oracle MTS Recovery Service:

To delete an Oracle MTS Recovery Service run:

oramtsctl -delete

Usage

oramtsctl <-new|-delete|-start|-stop|-status|-config|-passwd|-trace|-trcdir>
          [-host    <hostname|IP_address> ...]
          [-port    <number>]
          [-ip      <IP_address>]
          [-dtchost <DTC_hostname>]
          [-cluster <on|off>]
          [-default]
 
 -new    

Create and start a new Oracler1MTSRecoveryService service.

 
 -delete [Oracle_home_directory]

Delete Oracler1MTSRecoveryService of current home or specified home.

 
 -start  

Start Oracler1MTSRecoveryService service.

 
 -stop   

Stop Oracler1MTSRecoveryService service.

 
 -status Query Oracler1MTSRecoveryService

service status.

 
 -config [-port <number>] [-ip <IP_address>] [-dtchost <DTC_hostname>]
         [-cluster <on|off>] [-default]

Show or set Oracler1MTSRecoveryService service configuration.

Use -default to reset Oracler1MTSRecoveryService configuration.

 
 -passwd

Update Oracler1MTSRecoveryService service user password.

 
 -trace  [0-5]

Show traces or set trace level. Set level 0 to turn off tracing.

 
 -trcdir [trace_directory]

Show or set trace directory.

 
 -host   <hostname|IP_address> ...

Execute operation on host(s) identified by name(s) or IP address(es).

Local host is used if option not specified.

 
 -port   <number>

Execute -new or -config with this option to specify a service port.

Service port is configured automatically if option not specified.

 
 -ip     <IP_address>

Execute -new or -config with this option to specify an IP address.

 
 -default

Execute -new or -config with this option to set default configuration.

 
oramtsctl -new -host host1 host2.domain.com host3 -port 2033

Examples:

Install the service with automatic configuration:

oramtsctl -new
 

Install the service on port 2032:

oramtsctl -new -port 2032
 

Configure the service to use port 2033:

oramtsctl -config -port 2033
 

Update the service user password:

oramtsctl -passwd
 

Install the service on several hosts and use uniform port 2033:

oramtsctl -new -host host1 host2.domain.com host3 -port 2033