_DBAppend( ) API Library Routine

Attempts to append a new record to the table open in the specified workarea.

int _DBAppend(int workarea, int carryflag)
int workarea;               /* Work area number. */
int carryflag;               /* SET CARRY setting. */

Remarks

The current work area is represented by – 1. _DBAppend( ) returns 0 if the routine is successful. If the routine fails, _DBAppend( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

Values for carryflag

Value	Effect
1	Carries information from the previous record into the new record.
0	Makes the new record blank.
– 1	Uses the setting of SET CARRY to determine whether information from the previous record is carried to the new record.

_DBAppend( ) automatically performs any necessary locking. If it's unable to lock the file header, _DBAppend( ) fails and returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _DBAppend( ) to append a record to the table open in the current work area.

Visual FoxPro Code

SET LIBRARY TO DBAPPEND
DO CreateTest

SET CARRY ON
= DBAPPEND(-1)   && SET CARRY is ON, so carry
SET CARRY OFF
= DBAPPEND(1)   && carry regardless of SET CARRY
= DBAPPEND(-1)   && SET CARRY is OFF, so no carry

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "Golly month of"
   APPEND BLANK
   REPLACE ABC WITH "A twelfth of"
   APPEND BLANK
   REPLACE ABC WITH "Hello, world"
   APPEND BLANK
   REPLACE ABC WITH "When in the"
   GO TOP
RETURN

C Code

#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int RetCode;
   if ((RetCode = _DBAppend(-1, (int) parm->p[0].val.ev_long)) < 0) {
      _Error(-RetCode);
   }
}

FoxInfo myFoxInfo[] = {
   {"DBAPPEND", (FPFI) Example, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

_DBLock( ) API Library Routine | _DBUnlock( ) API Library Routine | Appending Data to an Existing Table | SET CARRY Command | APPEND Command