BTREEPERL(1) USER COMMANDS BTREEPERL(1) NAME btreeperl - btree extensions to the Perl Programming Language DESCRIPTION In the perl source distribution directory there is an object module, uperl.o, which is the complete perl program except for a single undefined function, userinit (). This function is called from perl's initialization routines to provide the capability of adding functions, written in C, to the perl program. See the README in the usub directory of the perl sources for particulars. The BSD NDBM database library contains btree file index functions which were added to the perl program to enable the btree database functions to be called directly from perl scripts. The functions added are: $db = &btopen ($fname, $flags, $mode, $duplicates) opens a btree database file, where: $fname is the name of the database file. $flags is the logical "or" of any combination of $O_CREAT, $O_EXCL, $O_EXLOCK, $O_NONBLOCK, $O_RDONLY, $O_RDWR, $O_SHLOCK and $O_TRUNC-opening a database file $O_WRONLY is not possible. See fcntl(1), or equivalent, for the description of these flags. $mode is chmod(1) absolute mode permissions of the database file. $duplicates is either 0 if duplicate keys are not permitted, or $R_DUP if duplicate keys are permitted. The return value of &btopen() is a file reference to the open database on success (all operations on the database will be referenced via this return value,) or $bterror != 0 on failure. For example: $db = &btopen ("example.db", $O_CREAT | $O_RDWR, 0600, 0) if ($bterror != 0) # database open? { print "Error opening database\n"; exit (1); } $retval = &btclose ($db) closes a btree database file, where: $db is the database file reference returned by a successful call to &dbopen(). The return value of &btclose() is $RET_SUCCESS if successful, and $RET_ERROR if not. For example: if (($retval = &btclose ($db)) != $RET_SUCCESS) { print "Error closing database\n"; } $retval = &btsync ($db) flush the cached data to the database file, where: $db is the database file reference returned by a successful call to &dbopen(). The return value of &btsync() is $RET_SUCCESS if successful, and $RET_ERROR if not. For example: if (($retval = &btsync ($db)) != $RET_SUCCESS) { print "Error in sync\n"; } $retval = &btseq ($db, $key, $key_size, $data, $data_size, $mode) sets the database cursor to reference a key, where: $db is the database file reference returned by a successful call to &dbopen(). $key is the key value to be referenced. $key_size is the length of the key value to be referenced (eg., via length ($key).) $data will contain the data of the key/data pair on successful completion. $data_size will contain the length of the data on successful completion. $mode specifies the mode sequence, and is any one of $R_CURSOR, to return the data from the specified key, $R_FIRST, to return the data from the first key in the database, $R_LAST, to return the data from the last key in the database, $R_NEXT to return the data from the next key in the database, or $R_PREVIOUS to return the data from the previous key in the database. (Note that for $R_CURSOR, the returned key is not necessarily an exact match for the specified key. The returned key is the smallest key greater than or equal to the specified key, permitting partial key matches and range searches.) The return value of &btseq() is $RET_SUCCESS if successful, and $RET_ERROR if not. For example (for partial key searches): if (($retval = &btseq ($db, $key, $key_size, $data, \ $data_size, $R_CURSOR)) != $RET_SUCCESS) { print "Error getting key/data pair\n"; } else { print "$data\n"; } and to get the data of the next key/data pair in the database: if (($retval = &btseq ($db, $key, $key_size, $data, \ $data_size, $R_NEXT)) != $RET_SUCCESS) { print "Error getting key/data pair\n"; } else { print "$data\n"; } $retval = &btput ($db, $key, $key_size, $data, $data_size, $mode) add a key/data pair to the database, where: $db is the database file reference returned by a successful call to &dbopen(). $key is the key value by which the data will be referenced. $key_size is the length of the key value (eg., via length ($key).) $data is the data to be stored in the database. $data_size is the length of the data to be stored (eg., via length ($key).) $mode specifies the mode with which the data will be stored, and is any one of $R_CURSOR, to replace the key/data pair referenced by the cursor, $R_NOOVERWRITE to add the key/data pair only if the key does not exist, and $R_SETCURSOR to store the key/data pair, setting the cursor to reference this key/data pair. The return value of &btput() is $RET_SUCCESS if successful, and $RET_ERROR if not. For example: if (($retval = &btput ($db, $key, $key_size, $data, \ $data_size, $R_NOOVERWRITE)) != $RET_SUCCESS) { print "Error inserting key/data pair\n"; } will add the key/data pair to the database (but only if the key does not already exist in the database.) Or to replace the key/data pair referenced by the cursor: if (($retval = &btput ($db, $key, $key_size, $data, \ $data_size, $R_CURSOR)) != $RET_SUCCESS) { print "Error inserting key/data pair\n"; } And: if (($retval = &btput ($db, $key, $key_size, $data, \ $data_size, $R_SETCURSOR)) != $RET_SUCCESS) { print = "Error inserting key/data pair\n"; } will add the key/data pair to the database (as a duplicate key, if the key exists in the database, if the the file was opened with R_DUP.) $retval = &btget ($db, $key, $key_size, $data, $data_size, $mode) to get a key/data pair from the database, where: $db is the database file reference returned by a successful call to &dbopen(). $key is the key value to be referenced. $key_size is the length of the key value to be referenced (eg., via length ($key).) $data will contain the data of the key/data pair on successful completion. $data_size will contain the length of the data on successful completion. $mode is currently not used, and should be 0. The return value of &btget() is $RET_SUCCESS if successful, and $RET_ERROR if not. For example: if (($retval = &btget ($db, $key, $key_size, $data, \ $data_size, 0)) != $RET_SUCCESS) { print "Error getting key/data pair\n"; } else { print "$data\n"; } $retval = &btdel ($db, $key, $key_size, $mode) to delete a key from the database, where: $db is the database file reference returned by a successful call to &dbopen(). $key is the key value of the key/data pair to be deleted. $key_size is the length of the key value to be deleted (eg., via length ($key).) $mode specifies the mode with which the data will be deleted, and is either 0 to delete specified key, or $R_CURSOR to delete the key/data pair referenced by the cursor. The return value of &btdel() is $RET_SUCCESS if successful, and $RET_ERROR if not. For example: if (($retval = &btdel ($db, $key, $key_size, 0)) != \ $RET_SUCCESS) { print "Error deleting key/data pair\n"; } would delete the specified key/data pair, or: if (($retval = &btdel ($db, $key, $key_size, $R_CURSOR)) \ != 0) { print "Error deleting key/data pair\n"; } would delete the key/data pair referenced by the cursor. Error handling is through return values on all functions, except &btopen(). The variable, $bterror, is set by all functions to 0 if the call to a function was successful, and 1 if it was not. Comments may be addressed to john@email.johncon.com (John Conover). SEE ALSO perl(1), dbopen(3), btree(3), dbm(3), ndbm(3)