Starts append of a new row.


<oRef>.beginAppend( )


The rowset you want to put in Append mode.

Property of



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.

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