FirstBase: GETXREC(3)

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

NAME

getxrec - read an indexed record

SYNOPSIS

#include <firstbase/fb.h>

fb_getxrec(key, db)
char *key;
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.

Fb_getxrec attempts to load a database record which has a current index entry of key into db. A binary search is done on the current index in an attempt to locate a record with an index entry of key. In the case of flat FirstBase indexes, if no record is found, the index overflow area is searched sequentially.

For alpha type fields, key needs to be left justified in a field of blanks, and for numeric keys, key should be right justified. Use makess(3) to generate a search string key. For example:

      fb_field *f;

      f = cdb_kp[0];
      fb_fetch(f, cdb_afld, cdb_db);
      fb_makess(cdb_afld, f->type, f->size);
      fb_getxrec(cdb_afld, cdb_db);

Once a record number is retrieved from the index, fb_getxrec uses getrec(3) to load the record into the database structures.

When using a FirstBase flat index, the physical position number of the index entry, the index record number, is stored in the database structure db->bsrec. If db->bsrec is greater than db->bsend, the returned record's key is stored in the overflow area of the index, otherwise it is stored in the binary searchable area.

However, when using a FirstBase Btree+ index, the db->bsrec value is actually the record number (not the index record number).

When fb_getxrec fails to locate an entry, the record that is loaded will be the one where the search failure occurred. Again, on an FB_ERROR return from fb_getxrec, the record loaded will be where the search key would have been, the record containing a key value greater than the search key. If such a record does not exist, then db->rec and db->bsrec will be set to 0, indicating an undefined record.

Note: Before calling fb_getxrec on a normal (flat) FirstBase index, the index header numbers should be updated using getxhead if there have been new records added to the index since it was opened, as in the following code fragment:

      /* get bsmax, bsend from index header file */
      fb_getxhead(dp->ihfd, &dp->bsmax, &dp->bsend);

CLIENT/SERVER

The fb_getxrec routine will transparently call the fb_getxrec_clnt mechanism when the global FirstBase variable cdb_use_rpc is set to one. See fb_clnt_create(3) for more details.

DIAGNOSTICS