abandon( )

Topic group Related topics Example

Abandons any pending changes to the current row.

Syntax

<oRef>.abandon( )

<oRef>

The rowset whose current row buffer you want to abandon.

Property of

Rowset

Description

Changes made to a row, either through dataLinked controls or by assigning values to the value property of fields, are not written to disk until the rowset’s save( ) method is explicitly called or there is an implicit save, which is usually caused by navigation in the rowset. You can discard any pending changes to the rowset with the abandon( ) method. This is usually done in response to the user’s request.

You can check the modified property first to see if there have been any changes made to the row. Calling abandon( ) when there’s nothing to abandon has no ill effects (although the canAbandon and onAbandon events are still fired).

You may also want to discard unwritten changes when a query is closed, the opposite of the default behavior. If you are relying on the query’s event handlers to do this instead of abandoning and closing the query through code, you must call abandon( ) during the query’s canClose event and return true from the canClose event handler; calling abandon( ) during the onClose event will have no effect, since the onClose event fires after the query has already closed, and any changes have been written.

When using abandon( ) to discard changes to an existing row, all fields are returned to their original values and any dataLinked controls are automatically restored. If the row was automatically locked when editing began, it is unlocked.

You may also use abandon( ) to discard a new row created by the beginAppend( ) method, in which case the new row is discarded, and the row that was current at the time beginAppend( ) was called is restored. This is not considered navigation, so the rowset’s onNavigate does not fire. If you have a onNavigate event handler, call it from the onAbandon event. abandon( ) also cancels a rowset’s Filter or Locate mode in the same manner.

The order of events when calling abandon( ) is as follows:

1. If the rowset has a canAbandon event handler, it is called. If not, it’s as if canAbandon returns true.

• If the canAbandon event handler returns false, nothing else happens and abandon( ) returns false.

• If the canAbandon event handler returns true:

The current row buffer/state is abandoned, restoring the rowset to its previous row/state.

The onAbandon event fires.

abandon( ) returns true.

While abandon( ) discards unwritten changes to the current row, there are two mutually exclusive ways of abandoning changes to more than one row in more than one table in a database, which you can use instead of or in addition to single-row buffering. Calling beginTrans( ) starts transaction logging which logs all changes and allows you to undo them by calling rollback( ) if necessary. The alternative is to set the database’s cacheUpdates property to true so that changes are written to a local cache but not written to disk, and then call abandonUpdates( ) to discard all the changes if needed.