Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

OSS Library Calls (a - d) dbm_clearerr(3)
store_mode Determines whether the record being stored by the dbm_store( ) function
replaces an existing record or is inserted.
DESCRIPTION
These functions create, access, and modify a database. A database consists of two files: one with
a .dir suffix and one with a .pag suffix. The .dir file contains a catalog of the keys in the data-
base and how to find them, while the .pag file contains the actual data.
To manipulate such a database, these functions use a data type called datum, which is a structure
containing at least two fields: dptr and dsize. The dptr field is a pointer to an object that is dsize
bytes long.
The dbm_open( ) function opens a database. The file parameter is the database’s pathname.
dbm_open( ) opens both the file.dir and file.pag files. The open_flags parameter is the same as
the flags parameter used by the open( ) function, except if you open a database for write-only
access, in which case the files are opened for both reading and writing. The file_mode parameter
is also related to the open( ) function; it is equivalent to open( )’s mode parameter.
The dbm_close( ) function closes the database pointed to by the db parameter. The value of db
must be a pointer to a dbm structure previously returned by dbm_open( ).
The dbm_fetch( ) function retrieves a record from the database pointed to by the db parameter.
The key parameter is the key of the record to be retrieved. key is a datum initialized earlier by
application to the value of record to be fetched.
The dbm_store( ) function writes a record whose value is contained in the content parameter to
the database pointed to by the db parameter. The key parameter is the key of the record being
written. The store_mode parameter must be set to either DBM_REPLACE or DBM_INSERT.
When a record already exists with a key identical to the key parameter, a value of
DBM_REPLACE replaces the contents of the existing record with content, while a value of
DBM_INSERT
causes no such replacement to occur. When no existing record has a key that
matches
the key parameter,
a value of either DBM_INSERT or DBM_REPLACE inserts the
new record into the database.
The dbm_delete( ) function deletes the record with the key indicated by the key parameter from
the database pointed to by the db parameter. The record’s key is also deleted.
The dbm_firstkey( ) function returns the first key in the database pointed to by the db parameter.
The dbm_nextkey( ) function returns the next key in the database pointed to by the db parameter.
Subsequent calls to dbm_nextkey( ) return the next key until all of the keys in the database have
been returned.
The dbm_firstkey( ) function must be called before this function can be used for the first time.
The dbm_error() function returns the error condition of the database pointed to by the db
parameter.
The dbm_clearerr( ) function clears the error condition of the database pointed to by the db
parameter.
These database functions support key/content pairs of at least 1024 bytes.
NOTES
These functions can be called by native processes only.
These functions are not intended as a general-purpose database management system. They are
most useful when you require the fast lookup of relatively static information indexed by a single
key.
If a database is opened for write access by more than one process, the results are undefined.
527187-017 Hewlett-Packard Company 1−175