Share via

DtcGetTransactionManagerEx

  • Article

 

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The DtcGetTransactionManagerEx function is typically the first DTC call that application programs and resource managers make when using DTC. This helper function establishes the initial connection to DTC. It returns an interface pointer to one of the interfaces on the DTC proxy core object. This function helps reduce the boot time and minimize resource consumption and adds the ability to demand start DTC to compensate for removing boot start.

Implemented by: DTC proxy.
Object This is a helper function, not a method on an object.
Interface Source N/A
Called by: Application programs and resource managers.

Syntax

  
    EXTERN_C EXPORTAPI __cdecl DtcGetTransactionManagerEx( tchar * pszHost,  
tchar * pszTmName,  
REFIIDriid,  
DWORDgrfOptions,  
void * pvConfigParams,  
void ** ppvObject);

Remarks

Note

This API should not be called without the OLE_TM_FLAG_NO_DEMANDSTART during service startup.

If the pszHost value refers to a remote computer, then you must configure the computers participating in the transaction as follows, otherwise the call will fail:

  1. On the computer where the application that makes this call resides, make sure the Remote Registry service is running.

    1. Click Start, Run, type Services and click OK to launch the Services MMC Snap-in.

    2. Make sure the Remote Registry Service is running.

  2. On the remote computer referred to by the pszHost parameter, make sure the MSDTC service is configured to accept Network Transactions and allows remote clients.

    1. Click Start, Run, type dcomcnfg and click OK to launch the Component Services MMC Snap-in.

    2. For the corresponding MSDTC service, enable Network DTC Access, and make sure the Allow Remote Clients option is enabled.

Parameters

pszHost
[in] Name of the host system which will serve as the transaction commit coordinator.

Note

If the host system is not found the HRESULT XACT_E_UNABLE_TO_READ_DTC_CONFIG is returned.

pszTmName
[in] String Name of the transaction manager which will serve as the transaction commit coordinator. Must be NULL.

riid
[in] IID of the requested interface.

grfOptions
[in] Specifies any configuration or startup options for the transaction manager object. Currently the supported flags are:

OLE_TM_FLAG_NODEMANDSTART (Value = 0x00000001)

Callers can specify this option if they do not want demand start of DTC.

OLE_TM_FLAG_NONE (Value = 0x00000000)

External callers should use this flag if they want the default behavior (which is to demand start DTC). This approach provides meaningful text and is preferable to directly using the value 0 for i_grfOptions.

OLE_TM_FLAG_INTERNAL_TO_TM (Internal only)

Only components internal to the Transaction manager (such as XATM) should use this flag. This flag should not be used by external callers.

OLE_TM_FLAG_QUERY_SERVICE_LOCKSTATUS (Internal only)

Specifying this flag will cause DTC to query the lock status and fail demand start if someone else is holding SCM lock. This flag should not be used by external callers.

pvConfigParams
[in] Pointer to a self-describing structure. You can use the structure to pass various configuration parameters into the TM object. Must be NULL.

ppvObject
[out] Pointer to the pointer to the requested interface.

Return Values

S_OK
Success.

E_NOINTERFACE
Unable to provide the requested interface.

E_UNEXPECTED
Unexpected error encountered.

E_INVALIDARG
One or more arguments are invalid.

E_FAIL
Failed to carry out the operation.

XACT_E_UNABLE_TO_READ_DTC_CONFIG
Unable to read DTC configuration information. This error is returned if the host system specified by the pszHost parameter does not exist.

Remarks

Calls to DtcGetTransactionManagerEx can specify a server host name to serve as the transaction commit coordinator in the pszHost parameter. However, the parameter is taken into consideration only if the machine is set to use the local transaction coordinator. If the machine is not set to use the local transaction coordinator, or if a value of NULL is supplied, the following rules determine where the transaction is started and coordinated:

  1. If the workstation making the call has a locally installed DTC, the local DTC is used.

  2. If the workstation making the call is a Windows 95 computer or a Windows computer that does not have a local DTC installed, the default DTC is used. The default DTC is specified as the Remote Host field on the MSDTC tab of the Component Services administrative tool.

The DtcGetTransactionManagerEx function helps reduce the boot time and minimize resource consumption. The function also adds the ability to demand start DTC to compensate for removing boot start. In general, clients of DTC call this function DTC is not running. It demand starts the transaction manager (TM) for the caller. The caller specify OLE_TM_FLAG_NODEMANDSTART to explicitly disable demand start. The semantics for demand start are as follows:

  1. Calls into DtcGetTransactionManagerEx will demand start the TM if required. DtcGetTransactionManagerEx can still return XACT_E_TM_NOTAVAILABLE.

  2. This behavior is the same for local and remote clients.

  3. If clients want to restart DTC without shutting down and restarting their executables, they should release all references and call on DtcGetTransactionManagerEx again.

Requirements

For an explanation of the requirement values, see Requirements (Component Services).

Platforms: Windows Server 2016, Windows 10, Windows Server 2012 R2, Windows 8.1, Windows Server 2012, Windows 8, Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista

Header: Declared in xolehlp.h

Library: Included as a resource in xolehlp.dll