Functions and Directives

Function DbAppend() Foundation

Creates a new record.

Syntax
DbAppend( [<nLockMode>] ) --> NIL
Parameters
<nLockMode>
If the value 1 is specified for <nLockMode> all existing record locks remain active when DbAppend() is called. Otherwise existing record locks are released prior to appending a new record to a database.
Return

The return value of DbAppend() is always NIL.

Description

The database function DbAppend() creates a new, empty record at the end of a database file. The record pointer is positioned on the new (last) data record, regardless of active filter or index conditions. When the functions is called without the alias operator, the new record is appended to the database open in the current work area.

The command APPEND BLANK can be used instead of DbAppend(). APPEND BLANK is only effective in the current work area.

Multi-user access: When the file is opened on a network or simultaneously by two Xbase++ applications on a single computer, DbAppend() automatically attempts to lock the new record. If the record cannot be locked, the append is not successful. A runtime error is generated which is caught by a default error routine and nothing in the file is changed. The default error handling routine handles this error by changing the value returned by NetErr() to .T. (true) and allowing the application to continue.

By default DbAppend() calls function RLock() to lock the new record. This releases all existing record locks. If the value 1 is passed, DbAppend() uses DbRLock() to lock the new record and all existing record locks remain active.

Examples
DbAppend()
// In the example, data for a new record is first 
// input to memory variables and then an attempt is 
// made to create a new record. If it could be 
// created, the data is copied into the file. 

PROCEDURE Main 
   LOCAL cItemNo := Space(10), cItem := Space(50) 

   USE InvItem INDEX InvItemA, InvItemB ALIAS Items NEW 

   CLS 

   @ 10,5 SAY "Item number     :" GET cItemNo 


   @ 11,5 SAY "Item description:" GET cItem 

   READ 

   IF .NOT. Empty( cItemNo + cItem ) 
      DbAppend() 
      IF NetErr() 
         ? "record could not be created" 
      ELSE 
         REPLACE Items->ItemNo WITH cItemNo  , ; 
                 Items->Item   WITH cItem 
      ENDIF 
   ENDIF 

   USE 
RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.