• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

dbopen, dbopen_table, dbopen_database - open a database

SYNOPSIS

#include "db.h"

int dbopen ( char *path, char *permissions, Dbptr *db );

long dbopen_database ( char *path, char *permissions, Dbptr *db );

long dbopen_table ( char *path, char *permissions, Dbptr *db );

DESCRIPTION

dbopen opens the database specified by the path name, using the permissions given by opentype. A database pointer with the database index filled in is returned in db, and dbopen returns zero upon success or dbINVALID for failure. The opentype may be either "r" (for read only) or "r+" (for reading and writing). In the latter case, Datascope attempts to open tables read/write, but if permissions don't allow that, opens tables read only.

Dbopen_database is similar to dbopen, but also understands a full table path name, as well as just a database name. In this case, the returned dbptr has a table specified, rather than just dbALL. In addition, when it opens a table, dbopen_database returns the number of records in that table.

Dbopen_table expects either a full table path name or a bare table name. If it's given just a table name, then dbptr must contain a pointer to an already open database -- the call is then equivalent to "dblookup ( *db, 0, path, 0, 0)". This can be useful in writing commands like dbjoin(1) or dbe(1) where the command line may contain a list of tables or databases.

FILES

dbopen expects to find a descriptor file at path which contains the name of the schema and the database path associated with this database. The schema file is expected to be found either

Tables for the database are expected to be found in the directory with the database file, or along the database path. For example, a database descriptor file might look like:


% cat 1987177
css3.0
/spc/slick3/nrdc/data/tables/{nrdc}:/wfdisc/nrdc/{master}
%

This database uses the css3.0 schema. Its tables may either be found

RETURN VALUES

dbopen returns 0 for success and dbINVALID in the event of failure. dbopen_database and dbopen_table return a non-negative integer for success and dbINVALID in the event of failure.

ENVIRONMENT

In order to open a database, a file defining the schema must be present. Dbopen looks for this file first in the same directory as the database, then in $SCHEMA_DIR (if it is defined) and finally in $ANTELOPE/data/schemas.

LIBRARY

$(DBLIBS)

SEE ALSO

dbintro(3), dbadd(3), dbdelete(3), dbget(3), dbput(3), dbquery(3), dblookup(3), dbopen(3), dbinvalid(3)

BUGS AND CAVEATS

Databases that are opened by dbopen have metadata cached internally, such that further calls to dbopen merely return pointers to the already-open database. Thus, if a database is opened read-only and then a further call to dbopen is made to open that database read-write, the change in permissions will be ignored. Changing the permissions on an open database requires calling dbclose(3) before re-opening with dbopen.

AUTHOR

Daniel Quinlan
Printer icon