AS400JDBCSavepoint class

The AS400JDBCSavepoint class represents a logical breaking point in a transaction. Using savepoints gives you more granular control over which changes are affected when you roll back a transaction.

Figure 1: Using savepoints to control rollbacks in a transaction

Using savepoints to control roll backs in a transaction

For example, Figure 1 shows a transaction that includes two savepoints, A and B. Rolling back the transaction to either savepoint undoes (or reverses) only those changes from the point a rollback is called to the savepoint. This prevents having to undo all the changes in the entire transaction. Note that once you rollback to savepoint A, you cannot later rollback to savepoint B. You cannot access savepoint B after work is rolled back past it.

Example: Using savepoints

In this scenario, assume that your application updates student records. At the end of updating a certain field in every student record, you perform a commit. Your code detects a particular error associated with updating this field and rolls back the work done when this error occurs. You know that this particular error affects only the work performed on the current record.

So, you set a savepoint between each update of student records. Now, when this error occurs, you rollback only the last update in the student table. Instead of having to roll back a large amount of work, you can now roll back only a small amount of work.

The following example code helps illustrate how you can use savepoints. The example assumes that the student ID for John is 123456 and the student ID for Jane is 987654.

     // Get a connection from the driver
     Class.forName("com.ibm.as400.access.AS400JDBCDriver");

     // Get a statement object
     Statement statement = connection.createStatement();

     // Update John's record with his 'B' grade in gym.
     int rows = statement.executeUpdate(
       "UPDATE STUDENTTABLE SET GRADE_SECOND_PERIOD = 'B' WHERE STUDENT_ID= '123456'");

     // Set a savepoint marking an intermediate point in the transaction
     Savepoint savepoint1 = connection.setSavepoint("SAVEPOINT_1");

     // Update Jane's record with her 'C' grade in biochemistry.
     int rows = statement.executeUpdate(
        "UPDATE STUDENTTABLE SET GRADE_SECOND_PERIOD = 'C' WHERE STUDENT_ID= '987654'");

     // An error is detected, so we need to roll back Jane's record, but not John's.
     // Rollback the transaction to savepoint 1. The change to Jane's record is 
     // removed while the change to John's record remains.
     connection.rollback(savepoint1);

     // Commit the transaction; only John's 'B' grade is committed to the database.
     connection.commit();

Considerations and restrictions

Using savepoints requires that you be aware of the following considerations and restrictions:

Considerations

IBM® Toolbox for Java™ follows database rules regarding how rollbacks affect cursors and retained locks. For example, when you set the connection option to keep cursors open after a traditional rollback, cursors also remain open after a rollback to a savepoint. In other words, when a rollback request happens involving savepoints, IBM Toolbox for Java does not move or close the cursor when the underlying database does not support this.

Using a savepoint to roll back a transaction undoes only the actions performed from the point where you start the roll back to the savepoint. Actions performed before that savepoint remain. As in the previous example, be aware that you can commit a transaction that includes work performed before a particular savepoint but does not include work performed after the savepoint.

All savepoints are released and become invalid when the transaction is committed or when the entire transaction is rolled back. You can also release savepoints by calling Connection.releaseSavepoint().

Restrictions

The following restrictions apply when using savepoints: