Initialize a Hash Database

Copying The Bthash Library

The subroutine hinit.c allows you to initialize a hash database based on configuration parameters.

Syntax

int hinit(char *dbname, int truncflag, int totrcds, int rcdlen, int keylen, int keyofst);

The following is an example of calling hinit.

      retcd = hinit(filename,INITNEW,97,30,10,5);

In this example:

Return Code

User error codes are above 350 million. System error codes are above 400 million.

Truncate Flag

Integer

The truncate flag tells hinit.c whether to truncate an existing database or not. Truncating an existing database risks the loss of irreplaceable data. The truncate flag is one way to prevent the loss of valuable data.

Possible values for the truncate flag are:

Recommendations for using the truncate flag:

totrcds (total number of records)

Integer.

The estimated number of records that you will add to the database.

Use the getprime program to calculate the prime number for totrcds.

Example:

      getprime 100000

The result is 99991.

Range: 1 - 9999999

rcdlen (record length)

Integer.

Record length or row length

Range: 1 - 32000

keylen (key length)

Integer.

The key uniquely identifies each record in the hash database. Duplicates are not allowed.

Range: 1 - 32000

keyofst (key offset)

Integer.

The location of the key in the record relative to the beginning of the record.

Range: 0 - (32000 minus key-length)

Processing

The hash configuration program truncates a hash file, depending on the truncate flag. It then writes blank records to the database based on the estimated number of records totrcds.

If you are unsure how many records you will have, or you want your database to grow larger over time, you may want to use a btree database, instead. A hash database degrades with growth. A btree database keeps itself balanced as it grows larger.

Be sure to back up all your data before calling hinit.c.

Binary data is allowed in a record. A record may need to exceed 32000 bytes in length if it's an audio track or video sequence. In this case, you may want to design the hash database as an index into a separate audio or video file.

The parameter information is stored in the first 256 bytes of the initialized database. See the hashfmt structure in the bthash.h header file for the placement and format of this data. Please note that the fields from hndl to the end of the structure are temporary, and are not stored on disk.


Error Codes