Request

The <startTransactionRequest> message is sent to begin a database transaction. Database manipulation and query requests (update, delete, and read) can be sent within the context of the transaction.

If a <startTransactionRequest> is sent, and the connection is lost or the user logs off without sending a <commitRequest> or <rollbackRequest>>, all pending requests are rolled back.

A provisioning session can have one transaction open at a time. If a <startTransactionRequest> is sent, another <startTransactionRequest> will fail with an ACTIVE_TXN error.

A timeout can occur between the <startTransactionRequest> and the <commitRequest>. If the <commitRequest> is not sent out within the configured Maximum Transaction Lifetime (we recommend you see the SDS Online Help for more information) after the <startTransactionRequest>, the SOAP provisioning requests are rolled back (changes not applied to database).

A transaction can only be opened by one client at a time. If a transaction is already opened by another client, the <startTransactionRequest> is rejected immediately with WRITE_UNAVAIL or is queued up for the time specified by the timeout parameter. If the timeout parameter is specified with a non-zero value and that period of time elapses before the transaction is opened, the <startTransactionRequest> is rejected with WRITE_UNAVAIL.

Data manipulation requests are evaluated for validity and applied to a local database view which is a virtual representation of the main database plus local modifications made within this active transaction.

Local database view changes are not committed to the main database until the transaction is ended with a <commitRequest>.

The request can be aborted and rolled back with a <rollbackRequest> request any time before the transaction is ended with a <commitRequest>.

Request Format

The request must be inserted between the <soapenv:Body> and </soapenv:Body> XML tags of a SOAP request message, as shown in SOAP Request Messages.
<startTransactionRequest>timeout</startTransactionRequest>

Request Parameters

<startTransactionRequest> Parameters (SOAP)
Parameter Description Value
timeout The amount of time (in seconds) to wait to open a transaction if another connection already has one open. Clients waiting to open a transaction will be processed in the order that their requests were received.

0 (return immediately if not available) to 3600 seconds.

The default is 0.