xHarbour Reference Documentation > Function Reference

DbAppend()

Appends a new record to a database open in a work area.

Syntax

DbAppend( [<lUnlockRecords>] ) --> NIL

Arguments

<lUnlockRecords>

This parameter defaults to .T. (true). It causes all pending record locks set with RLock() or DbRLock() be released before a new record is appended to the database. Pass .F. (false) to keep all record locks intact.

Return

The return value is always NIL.

Description

The DbAppend() function adds a new record to the end of the database in the current work area. Use an aliased expression to append a record in a different work area.

All fields of the new record are filled with empty data of their respective data types. That is, Character fields are filled with blank spaces, Date fields contain empty dates, logical fields contain .F. (false) and numeric fields zero. Memo fields contain a null string ("").

The DbAppend() function is guaranteed to add a new record when the database file is open for EXCLUSIVE access by the application. This, however, is rarely the case. In a multi-user environment, databases are usually open for SHARED access. As a result, DbAppend() tries to lock the new record so that no other user can change it during the operation. If this lock fails, there is no new record available for the application. Instead, the function NetErr() is set to .T. (true) indicating a failure of locking the new record. A failure of this kind can happen, for example, when another application has obtained a file lock prior to DbAppend(). Such an error condition is gracefully handled if NetErr() is checked after DbAppend().

If DbAppend() has successfully locked the new record, all other records locks set in the database are released by default. To keep pending record locks in place, the value .F. (false) must be passed to DbAppend().

Info

See also:	APPEND BLANK, DbRLock(), DbUnlock(), DbUnlockAll(), NetAppend(), RLock()
Category:	Database functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example shows a typical coding pattern for appending a new
// record to a database open in SHARED mode

   PROCEDURE Main
      USE Customer SHARED ALIAS Cust
      SET INDEX TO Cust01, Cust02

      Cust->( DbAppend() )

      IF NetErr()
         ? "Unabled to append new record"
      ELSE
         ? "Fill data to new record"
         REPLACE Cust->Firstame WITH "Paul"
         REPLACE Cust->Lastname WITH "Newman"
         DbCommit()
         DbUnlock()
      ENDIF

      WAIT
      Browse()

      CLOSE Customer
   RETURN