Documentation Home
X DevAPI User Guide
Download this Manual

X DevAPI User Guide  /  Statement Execution  /  Working with Savepoints

8.2 Working with Savepoints

X DevAPI supports savepoints, which enable you to set a named transaction savepoint that you can rollback to. This section documents how to work with savepoints in X DevAPI. See SAVEPOINT for background information.

Setting a Savepoint

Savepoints are represented by a string name. The string can contain any character allowed for an identifier. Validation of the name is performed by the server. To create a savepoint, use the Session.setSavepoint() operation, which maps to the SQL statement SAVEPOINT name; . If you do not specify a name, one is automatically generated. For example by issuing:

string Session.setSavepoint()

a transaction savepoint is created with an automatically generated name and a string is returned with the name of the savepoint. This name can be used with the Session.rollbackTo() or Session.releaseSavepoint() operations. The Sesison.setSavepoint() operation can be called multiple times in this way and the automatically generated name is unique per session.

It is also possible to manually define the name of the savepoint by passing in a string name. For example issuing:

Session.setSavepoint(string name)

results in a transaction savepoint with the specified name, which is returned by the operation as a string. The Session.setSavepoint() operation can be called multiple times in this way, and if the name has already been used for a savepoint then the previous savepoint is overwritten.

Rolling Back to a Savepoint

When a session has transaction savepoints, you can undo any subsequent transactions using the Session.rollbackTo() operation, which maps to the ROLLBACK TO name statement. For example, issuing:

Session.rollbackTo(name)

rolls back to the transaction savepoint name. This operation succeeds as long as the given savepoint has not been released. Rolling back to a savepoint which was created prior to other savepoints results in the subsequent savepoints being either released or rolled back.

For example (using SQL):

SAVEPOINT abc;	 <---- succeeds
SAVEPOINT def;	 <---- succeeds
ROLLBACK TO abc;       <---- succeeds
ROLLBACK TO abc;       <---- still succeeds, position stays the same
ROLLBACK TO def;       <---- gives error since lines above already cleared def
ROLLBACK TO abc;       <---- still succeeds

Releasing a Savepoint

To cancel a savepoint, for example when it is no longer needed, use x and pass in the name of the savepoint you want to release. For example, issuing:

Session.releaseSavepoint(name)

releases the savepoint name. Same comment about errors applies here as from rollback.

Maps to:

RELEASE `name`;

Savepoints and Implicit Transaction Behavior

The exact behavior of savepoints is defined by the server, and specifically how autocommit and Y are configured.

For example, consider the following statements with no explicit BEGIN, Session.startTransaction() or similar call:

session.setSavepoint(testsavepoint);
session.releaseSavepoint(testsavepoint);

If auto commit mode is enabled on the server, these statements result in an error because the savepoint named testsavepoint does not exist. This is because the call to Session.setSavepoint() creates a transaction, then the savepoint and directly commits it. The result is that savepoint does not exist by the time the call to releaseSavepoint() is issued, which is instead in it's own transaction. In this case, for the savepoint to survive you need to start an explicit transaction block first. For example:


User Comments
Sign Up Login You must be logged in to post a comment.