Updated: July 19, 2016
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.|
|Called by:||Application programs and resource managers.|
EXTERN_C EXPORTAPI __cdecl DtcGetTransactionManagerEx( tchar * pszHost, tchar * pszTmName, REFIIDriid, DWORDgrfOptions, void * pvConfigParams, void ** ppvObject);
This API should not be called without the OLE_TM_FLAG_NO_DEMANDSTART during service startup.
pszHost value refers to a remote computer, then you must configure the computers participating in the transaction as follows, otherwise the call will fail:
On the computer where the application that makes this call resides, make sure the Remote Registry service is running.
Click Start, Run, type
Servicesand click OK to launch the Services MMC Snap-in.
Make sure the Remote Registry Service is running.
On the remote computer referred to by the
pszHostparameter, make sure the MSDTC service is configured to accept Network Transactions and allows remote clients.
Click Start, Run, type
dcomcnfgand click OK to launch the Component Services MMC Snap-in.
For the corresponding MSDTC service, enable Network DTC Access, and make sure the Allow Remote Clients option is enabled.
[in] Name of the host system which will serve as the transaction commit coordinator.
If the host system is not found the HRESULT XACT_E_UNABLE_TO_READ_DTC_CONFIG is returned.
[in] String Name of the transaction manager which will serve as the transaction commit coordinator. Must be NULL.
[in] IID of the requested interface.
[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.
[in] Pointer to a self-describing structure. You can use the structure to pass various configuration parameters into the TM object. Must be NULL.
[out] Pointer to the pointer to the requested interface.
Unable to provide the requested interface.
Unexpected error encountered.
One or more arguments are invalid.
Failed to carry out the operation.
Unable to read DTC configuration information. This error is returned if the host system specified by the pszHost parameter does not exist.
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:
If the workstation making the call has a locally installed DTC, the local DTC is used.
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:
Calls into DtcGetTransactionManagerEx will demand start the TM if required. DtcGetTransactionManagerEx can still return XACT_E_TM_NOTAVAILABLE.
This behavior is the same for local and remote clients.
If clients want to restart DTC without shutting down and restarting their executables, they should release all references and call on DtcGetTransactionManagerEx again.
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