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.
      

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.

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.

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.
   

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

Platforms: Windows 2000, Windows XP, Windows Server 2003

Header: Declared in xolehlp.h

Library: Included as a resource in xolehlp.dll