FirstBase: ADDREC(3)

URL: http://www.firstbasesoftware.com/man/man3/addrec.htm
Last modified: 12 September 1995
Copyright © by FirstBase Software.
[ Index of Contents] [ FirstBase RDBMS Overview]

NAME

addrec, b_addrec - add a record

SYNOPSIS

#include <firstbase/fb.h>

fb_addrec(db)
fb_database *db;

fb_b_addrec(db)
fb_database *db;

DESCRIPTION

As explained in the database(4) manual page, a database structure contains all of the elements needed for an entire database, including an array of field structures, all file names and descriptors, and index information. Altogether, the array of field structures can hold one complete record.

The field structures within the database structure may be updated by using the store(3) routine. Once a record has been completely set up within the array of field descriptors, the fb_addrec routine is called to physically write the fields of data as a single record to the end of the database. This new record is stored as physical record number db->reccnt + 1.

Fb_addrec will perform the following sequence of events:

1): The database header variables db->reccnt and db->delcnt are read.
2): The record count is bumped to db->reccnt + 1 and the record is added to the database using the putrec(3) routine.
3): Autoindex fields that contain the AUTOINCR marker, the asterisk ("*"), are resolved by incrementing the last value used in the autoindex.
4): Any autoindexes in the database are updated to reflect this new record.
5): The database header information is written back into the database.

Note that fb_addrec does not check for unique field values. However, checkfields(3). can be used to enforce this integrity check.

But, fb_addrec does enforce mutual exclusion among any other FirstBase database tools that are running at the same time. In other words, a record added to a database using fb_addrec will properly lock out all other processes before actually adding the record.

Sometimes it is desirable to add many records as fast as possible. Since fb_addrec will lock the database, synchronize the data files, and unlock the database for each record, it can be inefficient. The bulk record processing mechanism can be used in these cases. (See bulkrec(3)).

The bulk processing of records consists of three steps. First, fb_bulkrec_begin is called before any processing. This preliminary call will lock and synchronize the database, and read the database header. Then, fb_b_addrec and/or fb_b_delrec are called repeatedly, as needed. Finally, fb_bulkrec_end is used to write the header, synchronize the data files, and unlock the database.

CLIENT/SERVER

The fb_addrec and fb_b_addrec routines will transparently make calls to fb_addrec_clnt and fb_b_addrec_clnt when the global FirstBase variable cdb_use_rpc is set to one. See fb_clnt_create(3) for more details.

DIAGNOSTICS