FirstBase: OPENDB(3)

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

NAME

opendb, closedb - open/close a FirstBase database

SYNOPSIS

#include <firstbase/fb.h>

fb_opendb(db, mode, ixflag, ixoption)
fb_database *db;
int mode;
int ixflag;
int ixoption;

fb_closedb(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.

Fb_opendb and fb_closedb provide mechanisms to open and close an entire database -- including simple and autoindex structures. In other words, the entire database structure is initialized, with all needed file descriptors and structure pointers. Fb_opendb will also provide file name extensions if needed.

The database structure needs to be allocated and the file names need to be in the database structure prior to the fb_opendb call. Typically, these preliminary tasks are done using dballoc(3) and dbargs(3).

The mode reflects desired permissions to the database, with three possibilities -- READ, WRITE, and READWRITE. If a database does not exist, and the mode is WRITE or READWRITE, fb_opendb creates a database and database map, and initializes both.

The other two parameters are for database indexes. Ixflag can take on three values. FB_NOINDEX means that no index will be opened at all. FB_WITHINDEX indicates that only the database index is to be opened. FB_ALLINDEX means that all indexes, including the autoindexes, are to be opened.

Ixoption controls what fb_opendb will do if index errors occur during the database initialization. It also has three possible settings. FB_OPTIONAL_INDEX means that no error messages are produced. FB_MAYBE_OPTIONAL_INDEX will make error messages appear, but control returns to the caller. FB_MUST_INDEX will make fb_opendb die after displaying the error message.

Fb_closedb closes all open file descriptors (databases, indexes, and the database map), and frees up (most) all allocated space.

NOTE: There are allocated areas that fb_closedb does not free up due to the underlying FirstBase structures for handling more than one open database. To free and reset these areas, use free_globals(3) after all the databases have been closed using fb_closedb.

EXAMPLES

Before opening a database from a C program, the database needs to be defined using the FirstBase tool dbdbas(1). Then, assuming the database is named Phone, the following could be used to initialize and open this database without any indexes:



   fb_database *db;
   ...
   db = fb_dballoc();
   fb_dbargs("Phone", NIL, db);
   fb_opendb(db, READWRITE, FB_NOINDEX, 0);

As another example, the following code fragment will set up the database variables and open the database named Phone using an index named Clients:



   fb_database *db;
   ...
   db = fb_dballoc();
   fb_dbargs("Phone", "Clients", db);
   fb_opendb(db, READWRITE, FB_WITH_INDEX, FB_MUST_INDEX);

FILES

dbase: default name of FirstBase database and screen.
index: default name of FirstBase index.
\.cdb: extension of FirstBase database.
\.map: extension of record map for FirstBase database.
\.idx: extension of FirstBase database index.
\.ddict: extension of FirstBase database dictionary.
\.idict: extension of FirstBase database index dictionary.

CLIENT/SERVER

The fb_opendb and fb_closedb routines will transparently call the fb_opendb_clnt and fb_closedb_clnt mechanisms when the global FirstBase variable cdb_use_rpc is set to one. See fb_clnt_create(3) for more details.

DIAGNOSTICS

If fb_opendb cannot open the database file, it will die with an error message. However, if a program sets the global variable cdb_returnerror to one before calling fb_opendb, then the process will not terminate on errors. In this case, fb_opendb will return either FB_AOK or FB_ERROR. The global variable cdb_error will be set on FB_ERROR returns. See setup(5) for details on these and other global variables.