CreateTransaction function

Creates a new transaction object.

Syntax

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

Parameters

lpTransactionAttributes [in, optional]

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 [in, optional]

Reserved. Must be zero (0).

CreateOptions [in, optional]

Any optional transaction instructions.

Value	Meaning
TRANSACTION_DO_NOT_PROMOTE	The transaction cannot be distributed.

 

IsolationLevel [in, optional]

Reserved; specify zero (0).

IsolationFlags [in, optional]

Reserved; specify zero (0).

Timeout [in, optional]

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 [in, optional]

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:

ERROR_INSUFFICIENT_RESOURCES

ERROR_INVALID_ACL

ERROR_INVALID_SID

ERROR_INVALID_PARAMETER

ERROR_OBJECT_NAME_COLLISION

ERROR_OBJECT_NAME_EXISTS

ERROR_OBJECT_NAME_INVALID

ERROR_OBJECT_TYPE_MISMATCH

ERROR_PRIVILEGE_NOT_HELD

ERROR_UNKNOWN_REVISION

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

See also

Distributed Transaction Coordinator

Kernel Transaction Manager Functions

CommitTransaction

RollbackTransaction

SetTransactionInformation

SECURITY_ATTRIBUTES