DBM(3x,L)                   AIX Technical Reference                   DBM(3x,L)
 
 
 
-------------------------------------------------------------------------------
dbm:  dbminit, store, fetch, delete, firstkey, nextkey
 
 
 
PURPOSE
 
Performs data base operations.
 
LIBRARY
 
Database Library (libdbm.a)
 
SYNTAX
 
 
 
                int dbminit (file)          datum firstkey ( )
                char *file;
                                            datum nextkey (key)
                datum fetch (key)           datum key;
                datum key;
                                            typedef struct
                int store (key, content)    {
                datum key, content;            char  *dptr;
                                               int   dsize;
                int delete (key)            } datum;
                datum key;
 
 
 
DESCRIPTION
 
Notes:
 
  1. These subroutines are provided for System V compatibility.
 
  2. The dbm subroutines are superseded by the ndbm functions, and are
     implemented using them.
 
The dbm subroutines maintain a data base of key-content pairs.  These
subroutines can handle very large data bases and access keyed items in one or
two file-system accesses.
 
The key parameter is a pointer to data specified by the content parameter.  The
sum of the sizes of the key-content pairs must not exceed the internal block
size of 1024 bytes.  All key-content pairs that hash together must fit on a
single block.  The store subroutine returns an error if a disk block fills with
inseparable data.
 
The key and the content parameters are described by the typedef datum
structure.  The datum structure refers to a string of bytes, the length of
 
 
 
Processed October 11, 1991         DBM(3x,L)                                  1
 
 
 
 
 
 
DBM(3x,L)                   AIX Technical Reference                   DBM(3x,L)
 
 
 
which is specified by the dsize field.   The string is pointed to by the dptr
field.  The dptr pointers returned by these subroutines point to static storage
that changes with subsequent calls.  The strings can contain binary data or
normal ASCII characters.
 
The data base is stored in two files.  One file is a directory that contains a
bit map and is suffixed with .dir.  The second file contains all data and is
suffixed with .pag.  The .pag file contains holes that increase its apparent
size to about four times its actual size.  You cannot copy a .pag file using
the standard utilities such as cp and cat without first filling these holes.
 
Before you can access a data base, you must open the data base with the dbminit
subroutine.  The file.dir, and file.pag files must already exist before you
call dbminit.  You can create an empty data base by creating zero-length .dir
and .pag files.
 
After the data base is opened with the dbminit subroutine, you can use the
fetch subroutine to access the data that is pointed to by the key parameter.
You can use the store subroutine to write the data specified by the content
parameter to a file and to specify the key to be used to access that data with
the key parameter.
 
The delete subroutine removes the key specified by the key parameter and the
data to which that key points.  The delete subroutine does not actually reclaim
the file space, but it does make it available for reuse.
 
The firstkey and nextkey subroutines make a linear pass through all of the keys
in a data base.  The firstkey subroutine returns the first key in the data
base.  The nextkey subroutine returns the next key in the data base.  For
example, the following code makes a linear pass through a data base:
 
  for (key = firstkey(); key.dptr != NULL; key = nextkey(key))
     {
     ...
     }
 
The order of keys that are returned by firstkey and nextkey depend on the
hashing function.
 
RETURN VALUE
 
All of the dbm subroutines that return an int value return 0 upon successful
completion, and they return a negative value if an error occurs.  Subroutines
that return a datum value indicate an error by setting the dptr field to NULL.
 
RELATED INFORMATION
 
In this book:  "ndbm."
 
 
 
 
 
 
 
Processed October 11, 1991         DBM(3x,L)                                  2