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
-
1)
in the directory data/schemas wherever the Antelope software is installed,
which is normally indicated by the environment variable ANTELOPE.
-
2)
in the same directory as the database file.
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
-
1)
in the same directory as the database file, with a base
name of "1987177", or
-
2)
in /spc/slick3/nrdc/data/tables, with a base name of
"nrdc", or
-
3)
in /wfdisc/nrdc, with a base name of "master".
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