25.3. Reading Records There are two ways to read records from the database: looking up a record by its key, and reading sequential key/value pairs. 25.3.1. Reading a Particular Record Both dpget() and dpgetwb() look up database entries by a key. int dpget(DEPOT * depot, const char * key, int keySize, int start, int max, int * dataSize); The key is the item to look up in the database, and keySize is the length of the key (or -1, in which case Depot uses strlen(key) to determine the length). The next two parameters, start and max, allow partial records to be read in; start is the offset in the data where the read begins, and max is the maximum number of bytes to be read. If the data region were an array of 4 byte int values, for example, setting start to 12 and max to 8 would read in the fourth and fifth elements from the array. If less than start bytes are available, dpget() returns NULL. To read in all of the bytes from the data, set max to -1. If the final parameter, dataSize, is not NULL, the integer it points to is filled in with the number of bytes read. This function returns NULL on failure and a pointer to the data read in when it succeeds. If it fails, dpecode tells what caused the failure. In particular, if the item does not exist or has less than start bytes of data, it sets dpecode to DP_ENOITEM. When dpget() returns data, a 0 byte is appended to the data, allowing it to be used as a string. The pointer is allocated using malloc(), and the application is responsible for freeing the memory when it is finished with it. If applications would like to read into a buffer rather than having Depot allocate one with malloc(), they should instead use the dpgetwb() function. int dpgetwb(DEPOT * depot, const char * key, int keySize, int start, int max, const char * data); The only parameters that are different between dpgetwb() and dpget() are max (which is interpreted differently) and data (which replaces the dataSize parameter from dpgetwb()). data should point to a buffer of max bytes for dpgetwb() to fill in with the data read from the database. The max parameter should not be -1 for dpgetwb() and the buffer does not have a 0 byte automatically appended to it by dpgetwb(). This function returns the number of bytes stored at data, and -1 if the record was not found, the data was smaller than start bytes, or an error occurred. 25.3.2. Reading Records Sequentially Applications can iterate over all of the keys in the database by using dpiterinit() and dpiternext(). The keys are not returned in any particular order[8] and the database should not be modified while the application is iterating over it. [8] Well, they are returned in the order the items are referenced from the hash bucket. While this is an order, it is not a useful one. int dpiterinit(DEPOT * depot); char * dpiternext(DEPOT * depot, int * keySize); Calling dpiterinit() tells qdbm to return the first key in the database the next time dpiternext() is called. dpiternext() returns a pointer to either the first key in the database (if dpiterinit() was just called) or the key in the database just after the key it returned the previous time. If there are no more keys in the database, it returns NULL. If keySize is not NULL, the integer it points to is set to the size of the key returned. The buffer dpiternext() returns a pointer to is allocated with malloc(), and the pointer needs to be deallocated with free() when the application is done with the key. The buffer is also NULL terminated, allowing it to be used as a string, if appropriate. |