DtcGetTransactionManager

  • [アーティクル]

 

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

This 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.

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

  
EXPORTAPI __cdecl DtcGetTransactionManager(   char * pszHost,  char * pszTmName,  REFIID riid,  DWORD dwReserved1,  WORD wcbReserved2,  void * pvReserved2,  void ** ppv);

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.

dwReserved1
[in] See remarks below.

wcbReserved2
[in] See remarks below.

pvReserved2
[in] See remarks below.

ppv
[out] 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 DtcGetTransactionManager 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 is configured to use a Remote DTC, the Remote DTC will be used whether or not a local DTC is installed.

  2. If the workstation making the call has a locally installed DTC, and is not configured for a Remote DTC, the local DTC is used.

  3. 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.

Currently there are only two acceptable combinations for values for dwReserved1, wcbReserved2 and pvReserved2. They are:

  1. dwReserved1 = 0, wcbReserved2 = 0 and pvReserved2 = NULL

  2. dwReserved1 = dwUSER_MS_SQLSERVER, wcbReserved2 = sizeof (PROXY_CONFIG_PARAMS) and pvReserved2 = pparamsProxy, where pparamsProxy is a pointer to a structure of type PROXY_CONFIG_PARAMS

    The wcThreadsMax field in the PROXY_CONFIG_PARAMS structure hints at the maximum number of threads to use on behalf of the calling application. This combination of values is usually only used by resource managers or clients that require high concurrency.

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.lib