Request

The <startTransaction> request begins a database transaction.

Data manipulation and query requests (update, delete, and read) can be sent within the context of a transaction. A client connection can only have one transaction open at a time.

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 <commit> request.

If a <startTransaction> request is sent, and then the connection is lost or the user logs off without sending a <commit> or <rollback> request, all pending requests are rolled back.

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

A timeout occurs between the <startTransaction> and <commit> requests. If the <commit> request is not sent out within the configured "Maximum Transaction Lifetime" on the SDS GUI (we recommend you see the SDS Online Help for more information) of the <startTransaction> request, the XML 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 <startTransaction> request 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 <startTransaction> request 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 <commit> request.

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

A block transaction (<tx> … </tx>) is not allowed with a normal transaction, and will result in an INV_REQ_IN_NORMAL_TX error being returned for that request.

Request Format

<startTransaction [resonly="resonly"] [id="id"] [timeout="timeout"]/>

Parameters

<startTransaction> Parameters (XML)
Parameter	Description	Values
resonly (Optional)	Indicates whether the response should consist of the result only, without including the original request in the response.	y - Only provide the result, do not include the original request (default). n - Include the original request in the response.
id (Optional)	Transaction ID value provided in request, and will be passed back in the response.	1-4294967295
timeout (Optional)	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 the requests were received.	0 (return immediately if not available) to 3600 seconds (default is 0).