CreateTransaction function (ktmw32.h)

Article
10/13/2021

Creates a new transaction object.

Syntax

HANDLE CreateTransaction(
  [in, optional] LPSECURITY_ATTRIBUTES lpTransactionAttributes,
  [in, optional] LPGUID                UOW,
  [in, optional] DWORD                 CreateOptions,
  [in, optional] DWORD                 IsolationLevel,
  [in, optional] DWORD                 IsolationFlags,
  [in, optional] DWORD                 Timeout,
  [in, optional] LPWSTR                Description
);

Parameters

[in, optional] lpTransactionAttributes

A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If this parameter is NULL, the handle cannot be inherited.

The lpSecurityDescriptor member of the structure specifies a security descriptor for the new event. If lpTransactionAttributes is NULL, the object gets a default security descriptor. The access control lists (ACL) in the default security descriptor for a transaction come from the primary or impersonation token of the creator.

[in, optional] UOW

Reserved. Must be zero (0).

[in, optional] CreateOptions

Any optional transaction instructions.

Value	Meaning
TRANSACTION_DO_NOT_PROMOTE	The transaction cannot be distributed.

[in, optional] IsolationLevel

Reserved; specify zero (0).

[in, optional] IsolationFlags

Reserved; specify zero (0).

[in, optional] Timeout

The time-out interval, in milliseconds. If a nonzero value is specified, the transaction will be aborted when the interval elapses if it has not already reached the prepared state.

Specify zero (0) or INFINITE to provide an infinite time-out.

[in, optional] Description

A user-readable description of the transaction.

Return value

If the function succeeds, the return value is a handle to the transaction.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call the GetLastError function.

The following list identifies the possible error codes:

Remarks

Use the CloseHandle function to close the transaction handle. If the last transaction handle is closed before a client calls the CommitTransaction function with the transaction handle, then KTM rolls back the transaction.

If the transaction might need to be promotable to a distributed transaction, then you must grant the Distributed Transaction Coordinator (DTC) access rights to enlist in the transaction. To do this, the lpTransactionAttributes parameter needs to contain an access control entry with the DTC’s SID (S-1-5-80-2818357584-3387065753-4000393942-342927828-138088443) and the TRANSACTION_ENLIST right. For more information, see Distributed Transaction Coordinator and Access Control Components.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	ktmw32.h
Library	KtmW32.lib
DLL	KtmW32.dll