CreateTransaction function

Creates a new transaction object.

Syntax

HANDLE CreateTransaction(
  IN LPSECURITY_ATTRIBUTES lpTransactionAttributes,
  IN LPGUID                UOW,
  IN DWORD                 CreateOptions,
  IN DWORD                 IsolationLevel,
  IN DWORD                 IsolationFlags,
  IN DWORD                 Timeout,
  LPWSTR                   Description
);

Parameters

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.

UOW

Reserved. Must be zero (0).

CreateOptions

Any optional transaction instructions.

Value Meaning
TRANSACTION_DO_NOT_PROMOTE
The transaction cannot be distributed.

IsolationLevel

Reserved; specify zero (0).

IsolationFlags

Reserved; specify zero (0).

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.

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

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

See Also

CommitTransaction

Distributed Transaction Coordinator

Kernel Transaction Manager Functions

RollbackTransaction

SECURITY_ATTRIBUTES

SetTransactionInformation