Progress
Open Client
Developer’s Guide


Updating SDOResultSet Objects

To update an SDOResultSet, you must complete two general steps:

  1. Make a change locally in the client application. For example, update column values in an existing row or create a new row (moveToInsertRow()).
  2. Commit the local changes to the database (through the remote SmartDataObject) by executing a row method, such as updateRow() or insertRow().

CAUTION: If you move the cursor from a row where you have updated columns (for example, using next()) but before you have committed the column updates to the database, your column updates to that row will be lost.
Transactions and Concurrency Control

By default, all updates that change the database occur in a transaction managed by the remote SmartDataObject. Typically, any method that updates or deletes an existing row, or that inserts a new row causes the SmartDataObject to complete a transaction for that row. Note that updating column values does not, in itself, change the database. Only row operations can actually cause a transaction to occur.

You can also extend a transaction to include modifications to multiple rows by using an SDOResultSet in Batch mode or by remotely controlling an automatic transaction, if one is available on the AppServer. For more information on Batch mode, see the "Using Batch Mode [Extension]" section, and on automatic transactions, see the "Using Extended Transactions" section.

SmartDataObjects use optimistic concurrency control, which means that records are read without a lock. Locks are acquired only for the short duration of the transaction when modifications are actually performed. Before updating or deleting a row, the remote SmartDataObject implementation compares the original values of the columns to their values in the database to determine if the columns where modified by another user. If one of the columns was modified, the modification does not succeed and the transaction is rolled back. A failed update then throws an SDOModificationException. If the SmartDataObject implementation tries to modify or delete a row that is already locked, it also throws an SDOModificationException. For more information on SDOModificationException, see the "Errors and Exceptions" section.

Updating Column Values

These methods modify a column in an SDOResultSet according to the specified data type. All column access methods in SDOResultSet use the flat model (see "Programming Concepts"). The column is specified by name (columnName) or number (columnIndex) and is set to the specified value (value):

Some java.util.Date and java.sql.Date methods are being deprecated by JavaSoft in favor of using the more robust java.util.GregorianCalendar. These are the methods that update column values with instances of this class:

For more information on the mapping between 4GL and Java data types, see the sections on Progress/Java data type mapping for TEMP–TABLE fields and passing INPUT TEMP–TABLE parameters in Programming Java Clients."

Inserting, Deleting, and Updating Rows

These methods manage operations on rows in the SDOResultSet:

SYNTAX
void moveToInsertRow() 

Moves the cursor to a staging position for creating a new row.

SYNTAX
void moveToCurrentRow() 

Moves the cursor from the insert row back to the current position.

SYNTAX
void insertRow() 

Sends the newly created row to the AppServer.

SYNTAX
void deleteRow() 

Deletes the row in the current position and sends the delete request to the AppServer.

SYNTAX
void updateRow() 

Sends the updates for the current row to the AppServer.

SYNTAX
void CancelRowUpdates() 

Cancels the updates by rolling back the effects of all method calls that updated column values. To cancel these updates, you must invoke this method before any call to updateRow() or insertRow().

SYNTAX
boolean rowInserted() 

Returns true if the cursor is positioned on an inserted row position and the row is not yet sent to the AppServer.

SYNTAX
boolean rowDeleted() 

Returns true if the cursor is positioned on a deleted row, whether or not the deletion is sent to the AppServer because it does not make sense to allow the user to manipulate a row that is logically deleted.

NOTE: The only time the row is not also physically deleted on the AppServer is if you are using a batch update. For more information, see the "Using Batch Mode [Extension]" section.

SYNTAX
boolean rowUpdated() 

Returns true if the cursor is positioned on a row that is modified but not yet sent to the AppServer.

Using Extended Transactions

As described earlier in this section, by default, each row modification (row update, insertion, and deletion method) executes as a single transaction in the SmartDataObject. You can extend a transaction to include multiple rows using Batch mode, where a sendBatch() method applies a set of row updates as a single transaction (see the "Using Batch Mode [Extension]" section). You can also explicitly manage a larger transaction on the AppServer remotely using an automatic transaction.

An automatic transaction allows you to remotely create a larger transaction within which all SmartDataObject transactions become nested as subtransactions. Using an automatic transaction, the Open Client application can start, commit, and roll back a single transaction by executing methods on a special ProcObject defined in the same AppObject that provides access to the corresponding SmartDataObject. The persistent procedure that underlies this ProcObject supports specific functionality and must be available for execution on the AppServer to make an automatic transaction possible. Such a transaction can encompass the entire life of the SDOResultSet. For more information on automatic transactions, see the Building Distributed Applications Using the Progress AppServer manual.

NOTE: You should call reOpenQuery() after an explicit transaction roll-back in order to maintain a cache that is consistent with the database. The reOpenQuery() method can also be desirable after committing a transaction containing inserted rows so that these rows are visible within the result set. For more information on row visibility, see the "Visibility of Updates" section.

Using Batch Mode [Extension]

Batch mode allows an Open Client to group together several updates and send them to the AppServer in one transaction. This might be a better update strategy than generating a transaction for each update method, depending on your application requirements. Thus:

These are the SDOResultSet methods that support Batch mode:

SYNTAX
void startBatch() [Extension] 

Starts a batch session. All the modifications (column updates, deletions and insertions) are maintained locally. Calling this method if you have already called it and have not called sendBatch() or cancelBatch() throws an Exception.

SYNTAX
void sendBatch() [Extension] 

Sends the current batch to the AppServer.

SYNTAX
void sendBatchAndReOpen() [Extension] 

Sends the current batch to the AppServer, then reopens the result set. In Stateless mode, this method is more efficient than separately calling sendBatch() and reOpenQuery(). For more information, see the "Visibility of Updates" section.

SYNTAX
void cancelBatch() [Extension] 

Undoes all the modifications of the current batch.

SYNTAX
boolean inBatch() [Extension] 

Returns true if the SDOResultSet object is in Batch mode (that is, you have called startBatch() and have not yet called sendBatch() or sendBatchandReopen()).

NOTE: A row that is updated or deleted in Batch mode, and has not yet been sent to the AppServer (using sendBatch()), cannot be refreshed using refreshRow(). Also, to save your changes locally in batch mode, you must still call the row update methods (for example, insertRow() or updateRow()) even though, in this mode, your changes are not sent to the AppServer.

Visibility of Updates

The visibility, from within the Open Client, of an update to the SDOResultSet object depends on whether the update is applied by:

The following rules determine the visibility of updates initiated by the Open Client:

Updates by external applications can typically occur on the data source that feeds the SDOResultSet. You can make any such updates visible to the Open Client application by calling reOpenQuery(), which refreshes all the data in the SDOResultSet. However, if you do not call reOpenQuery(), the following rules determine the visibility of updates from external applications:


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095