Open System Services Library Calls Reference Manual (G06.27+, H06.04+)

OSS Library Calls (a - d) dbm_clearerr(3)
If the db parameter does not point to a database structure, the results are undefined and [EIN-
VAL] is returned.
CAUTIONS
The dptr pointer returned by some of these functions may point to static storage that may be
overwritten by future function calls.
The dbm_delete() function only makes file space available for future use; it does not physically
reclaim the space.
If, while making a pass through the database with the dbm_firstkey() and dbm_nextkey() func-
tions, either dbm_store( ) or dbm_delete() is called, dbm_firstkey() should be called to reset
the database before again calling dbm_nextkey().
Be careful when using the dbm_open() function with files in the Guardian (/G) file system. If
the file parameter is longer than five characters, the dbm_open() function appends the .pag and
.dir extensions accordingly, but the Guardian file system then removes the . character and trun-
cates the name to the eight character maximum, thereby creating two filenames that are identical.
RETURN VALUES
The dbm_open( ) function returns a pointer to a database structure. If an error occurs, it returns (
"DBM *" )0 and sets errno.
The dbm_close( ) function does not return a value.
The dbm_fetch() function returns a datum structure with the contents of the specified record. If
the database does not contain a record with a key that matches the key parameter, or an error
occurs, the dptr field of the datum structure is a null pointer. When an error occurs, errno is set.
The dbm_store( ) function returns 1 if it was called with a flag value of DBM_INSERT and an
existing record was found with the same key. It returns 0 (zero) for other successes, and negative
values for failures. When the failure is due to an error, errno is set.
The dbm_delete() function returns 0 (zero) when it succeeds, and a negative value when it fails.
When the failure is due to an error, errno is set.
The dbm_firstkey() and dbm_nextkey() functions return a key datum that is the key to a
record in the database. When the end of a database is reached, the dptr field of the datum is a
null pointer. If an error is detected, the dptr value is also set to null and the error condition of the
database is set.
The dbm_error() function returns 0 (zero) if the database’s error condition is not set, and a
nonzero value if it is set.
The return value of the dbm_clearerr() function is unspecified.
EXAMPLES
The following code can be used to traverse the database:
for (key = dbm.firstkey(db); key.dptr !=NULL; key = dbm_netkey(db))
ERRORS
If the following condition occurs, these functions set errno to the corresponding value:
[EINVAL] An invalid parameter was passed to the function.
[ENOMEM] There was insufficient storage space available.
[ENOPERM] A write operation was attempted on a read-only database.
Other errno values may be returned for I/O operations from a failed internal system call to
open(|), read(), write(), and lseek().
527187-004 Hewlett-Packard Company 1−67