beginAppend( )

Topic group Related topics Example

Starts append of a new row.

Syntax

<oRef>.beginAppend( )

<oRef>

The rowset you want to put in Append mode.

Property of

Rowset

Description

beginAppend( ) clears the row buffer and puts the rowset in Append mode, allowing the creation of a new row, via data entry through dataLinked controls, by directly assigning values to the value property of fields, or a combination of both. The row buffer is 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. At that point, a save attempt is made only if the rowset’s modified property is true; this is intended to prevent blank rows from being added. Calling beginAppend( ) again to add another row will also cause an implicit save first, if the row has been modified.

The integrity of the data in the row, for example making sure that all required fields are filled in, should be checked in the rowset’s canSave event. The abandon( ) method will discard the new row, leaving no trace of the attempt.

The rowset’s canAppend event is fired when beginAppend( ) is called. If there is a canAppend event handler, it must return true or the beginAppend( ) will not proceed.

The onAppend event is fired after the row buffer is cleared, allowing you to preset default values for any fields. After you preset values, set the modified property to false, so that the values in the fields immediately after the onAppend event are considered as the baseline for whether the row has been changed and needs to be saved.

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

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

• If the canAppend event handler returns false, nothing else happens and beginAppend( ) returns false.

• If the canAppend event handler returns true, the rowset’s modified property is checked.

• If modified is true:

• The rowset’s canSave event is fired. If there is no canSave event, it’s as if canSave returns true.

• If canSave returns false, nothing else happens and beginAppend( ) returns false.

• If canSave returns true, dBASE Plus tries to save the row. If the row is not saved, perhaps because it fails some database engine-level validation, a DbException occurs—beginAppend( ) does not return.

• If the row is saved, the modified property is set to false, and the onSave event is fired.

• Ater the current row is saved (if necessary):

• The rowset is switched to Append mode.

• The onAppend event fires.

• beginAppend( ) returns true.

An exception occurs when calling beginAppend( ) if the rowset’s live property is false, or if the user has insufficient rights to add rows.