Parameters
#define HAM_AUTO_CLEANUP 1 |
Flag for ham_close, ham_env_close
Definition at line 2208 of file hamsterdb.h.
#define HAM_DIRECT_ACCESS 0x0040 |
Flag for ham_find, ham_cursor_find_ex, ham_cursor_move
Definition at line 2026 of file hamsterdb.h.
#define HAM_DONT_CLEAR_LOG 2 |
Definition at line 2211 of file hamsterdb.h.
#define HAM_DUPLICATE 0x0002 |
Flag for ham_insert and ham_cursor_insert
Definition at line 2011 of file hamsterdb.h.
#define HAM_DUPLICATE_INSERT_AFTER 0x0008 |
Flag for ham_cursor_insert
Definition at line 2017 of file hamsterdb.h.
#define HAM_DUPLICATE_INSERT_BEFORE 0x0004 |
Flag for ham_cursor_insert
Definition at line 2014 of file hamsterdb.h.
#define HAM_DUPLICATE_INSERT_FIRST 0x0010 |
Flag for ham_cursor_insert
Definition at line 2020 of file hamsterdb.h.
#define HAM_DUPLICATE_INSERT_LAST 0x0020 |
Flag for ham_cursor_insert
Definition at line 2023 of file hamsterdb.h.
#define HAM_FAST_ESTIMATE 0x0001 |
Flag for ham_get_key_count
Definition at line 2165 of file hamsterdb.h.
#define HAM_OVERWRITE 0x0001 |
Flag for ham_insert and ham_cursor_insert
When specified with ham_insert and in case a key is specified which stores duplicates in the Database, the first duplicate record will be overwritten.
When used with ham_cursor_insert and assuming the same conditions, the duplicate currently referenced by the Cursor will be overwritten.
Definition at line 2008 of file hamsterdb.h.
#define HAM_PARAM_CACHESIZE 0x00000100 |
Parameter name for ham_open_ex, ham_create_ex; sets the cache size
Definition at line 1477 of file hamsterdb.h.
#define HAM_PARAM_DATA_ACCESS_MODE 0x00000104 |
Parameter name for ham_create_ex, ham_open_ex; set the expected access mode.
Definition at line 1493 of file hamsterdb.h.
#define HAM_PARAM_KEYSIZE 0x00000102 |
Parameter name for ham_create_ex; sets the key size
Definition at line 1484 of file hamsterdb.h.
#define HAM_PARAM_MAX_ENV_DATABASES 0x00000103 |
Parameter name for ham_env_create_ex; sets the number of maximum Databases
Definition at line 1488 of file hamsterdb.h.
#define HAM_PARAM_PAGESIZE 0x00000101 |
Parameter name for ham_open_ex, ham_create_ex; sets the page size
Definition at line 1481 of file hamsterdb.h.
#define HAM_PARTIAL 0x0080 |
Flag for ham_insert, ham_cursor_insert, ham_find, ham_find_ex, ham_cursor_move
Definition at line 2030 of file hamsterdb.h.
#define HAM_TXN_AUTO_ABORT 4 |
Automatically abort all open Transactions (the default)
Definition at line 2214 of file hamsterdb.h.
#define HAM_TXN_AUTO_COMMIT 8 |
Automatically commit all open Transactions
Definition at line 2217 of file hamsterdb.h.
typedef int HAM_CALLCONV(* ham_compare_func_t)(ham_db_t *db, const ham_u8_t *lhs, ham_size_t lhs_length, const ham_u8_t *rhs, ham_size_t rhs_length) |
Typedef for a key comparison function
Definition at line 1703 of file hamsterdb.h.
typedef int HAM_CALLCONV(* ham_duplicate_compare_func_t)(ham_db_t *db, const ham_u8_t *lhs, ham_size_t lhs_length, const ham_u8_t *rhs, ham_size_t rhs_length) |
Typedef for a record comparison function
Definition at line 1744 of file hamsterdb.h.
typedef int HAM_CALLCONV(* ham_prefix_compare_func_t)(ham_db_t *db, const ham_u8_t *lhs, ham_size_t lhs_length, ham_size_t lhs_real_length, const ham_u8_t *rhs, ham_size_t rhs_length, ham_size_t rhs_real_length) |
Typedef for a prefix comparison function
Definition at line 1671 of file hamsterdb.h.
HAM_EXPORT ham_status_t HAM_CALLCONV ham_close | ( | ham_db_t * | db, | |
ham_u32_t | flags | |||
) |
Closes the Database
This function flushes the Database and then closes the file handle. It does not free the memory resources allocated in the db handle - use ham_delete to free db.
If the flag HAM_AUTO_CLEANUP is specified, hamsterdb automatically calls ham_cursor_close on all open Cursors. This invalidates the ham_cursor_t handle!
If the flag is not specified, the application must close all Database Cursors with ham_cursor_close to prevent memory leaks.
This function removes all record-level filters installed with ham_add_record_filter (and hence also, implicitly, the filter installed by ham_enable_compression).
This function also aborts all Transactions which were not yet committed, and therefore renders all Transaction handles invalid. If the flag HAM_TXN_AUTO_COMMIT is specified, all Transactions will be committed.
db | A valid Database handle | |
flags | Optional flags for closing the Database. Possible values are:
|
Referenced by ham::db::close().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_enable_compression | ( | ham_db_t * | db, | |
ham_u32_t | level, | |||
ham_u32_t | flags | |||
) |
Enables zlib compression for all inserted records
This function enables zlib compression for all inserted Database records.
The compression will be active till ham_close is called. If the Database handle is reused after calling ham_close, the compression is no longer active. ham_enable_compression should be called immediately after ham_create[_ex] or ham_open[_ex]. When opening the Database, the compression has to be enabled again.
Note that zlib usually has an overhead and often is not effective if the records are small (i.e. < 128byte), but this highly depends on the data that is inserted.
The zlib compression filter does not allow queries (i.e. with ham_find) with user-allocated records and the flag HAM_RECORD_USER_ALLOC. In this case, the query-function will return HAM_INV_PARAMETER.
db | A valid Database handle | |
level | The compression level. 0 for the zlib default, 1 for best speed and 9 for minimum size | |
flags | Optional flags for the compression; unused, set to 0 |
Referenced by ham::db::enable_compression().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_erase | ( | ham_db_t * | db, | |
ham_txn_t * | txn, | |||
ham_key_t * | key, | |||
ham_u32_t | flags | |||
) |
Erases a Database item
This function erases a Database item. If the item key does not exist, HAM_KEY_NOT_FOUND is returned.
Note that ham_erase can not erase a single duplicate key. If the key has multiple duplicates, all duplicates of this key will be erased. Use ham_cursor_erase to erase a specific duplicate key.
db | A valid Database handle | |
txn | A Transaction handle, or NULL | |
key | The key to delete | |
flags | Optional flags for erasing; unused, set to 0 |
Referenced by ham::db::erase().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_find | ( | ham_db_t * | db, | |
ham_txn_t * | txn, | |||
ham_key_t * | key, | |||
ham_record_t * | record, | |||
ham_u32_t | flags | |||
) |
Searches an item in the Database
This function searches the Database for key. If the key is found, record will receive the record of this item and HAM_SUCCESS is returned. If the key is not found, the function returns HAM_KEY_NOT_FOUND.
A ham_record_t structure should be initialized with zeroes before it is being used. This can be done with the C library routines memset(3) or bzero(2).
If the function completes successfully, the record pointer is initialized with the size of the record (in record.size) and the actual record data (in record.data). If the record is empty, size is 0 and data points to NULL.
The data pointer is a temporary pointer and will be overwritten by subsequent hamsterdb API calls. You can alter this behaviour by allocating the data pointer in the application and setting record.flags to HAM_RECORD_USER_ALLOC. Make sure that the allocated buffer is large enough.
When specifying HAM_DIRECT_ACCESS, the data pointer will point directly to the record that is stored in hamsterdb; the data can be modified, but the pointer must not be reallocated of freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases.
ham_find can not search for duplicate keys. If key has multiple duplicates, only the first duplicate is returned.
You can read only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will read record->partial_size bytes of the record data at offset record->partial_offset. If necessary, the record data will be limited to the original record size. The number of actually read bytes is returned in record->size.
db | A valid Database handle | |
txn | A Transaction handle, or NULL | |
key | The key of the item | |
record | The record of the item | |
flags | Optional flags for searching, which can be combined with bitwise OR. Possible flags are:
|
Referenced by ham::db::find().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_flush | ( | ham_db_t * | db, | |
ham_u32_t | flags | |||
) |
Flushes the Database
This function flushes the Database cache and writes the whole file to disk. If this Database was opened in an Environment, all other Databases of this Environment are flushed as well.
Since In-Memory Databases do not have a file on disk, the function will have no effect and will return HAM_SUCCESS.
db | A valid Database handle | |
flags | Optional flags for flushing; unused, set to 0 |
Referenced by ham::db::flush().
Retrieve the Environment handle of a Database
Every Database belongs to an Environment, even if it was created with ham_create[_ex] or ham_open[_ex].
Therefore this function always returns a valid handle, if the Database handle was also valid and initialized (otherwise it returns NULL).
db | A valid Database handle |
HAM_EXPORT ham_status_t HAM_CALLCONV ham_get_error | ( | ham_db_t * | db | ) |
Returns the last error code
db | A valid Database handle |
Referenced by ham::db::get_error().
Retrieve the flags which were specified when the Database was created or opened
db | A valid Database handle |
HAM_EXPORT ham_status_t HAM_CALLCONV ham_get_key_count | ( | ham_db_t * | db, | |
ham_txn_t * | txn, | |||
ham_u32_t | flags, | |||
ham_offset_t * | keycount | |||
) |
Calculates the number of keys stored in the Database
You can specify the HAM_SKIP_DUPLICATES if you do now want to include any duplicates in the count; if all you're after is a quick estimate, you can specify the flag HAM_FAST_ESTIMATE (which implies HAM_SKIP_DUPLICATES), which will improve the execution speed of this operation significantly.
db | A valid Database handle | |
txn | A Transaction handle, or NULL | |
flags | Optional flags:
| |
keycount | A reference to a variable which will receive the calculated key count per page |
Referenced by ham::db::get_key_count().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_get_parameters | ( | ham_db_t * | db, | |
ham_parameter_t * | param | |||
) |
Retrieve the current value for a given Database setting
Only those values requested by the parameter array will be stored.
db | A valid Database handle | |
param | An array of ham_parameter_t structures |
Referenced by ham::db::get_parameters().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_insert | ( | ham_db_t * | db, | |
ham_txn_t * | txn, | |||
ham_key_t * | key, | |||
ham_record_t * | record, | |||
ham_u32_t | flags | |||
) |
Inserts a Database item
This function inserts a key/record pair as a new Database item.
If the key already exists in the Database, error HAM_DUPLICATE_KEY is returned.
If you wish to overwrite an existing entry specify the flag HAM_OVERWRITE.
You can write only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will write partial_size bytes of the record data at offset partial_offset. The full record size will always be given in record->size! If partial_size+partial_offset exceed record->size then partial_size will be limited. To shrink or grow the record, adjust record->size. HAM_PARTIAL automatically overwrites existing records. Gaps will be filled with null-bytes if the record did not yet exist. Using HAM_PARTIAL is not allowed in combination with sorted duplicates (HAM_SORT_DUPLICATES).
If you wish to insert a duplicate key specify the flag HAM_DUPLICATE. (Note that the Database has to be created with HAM_ENABLE_DUPLICATES in order to use duplicate keys.) If no duplicate sorting is enabled (see HAM_SORT_DUPLICATES), the duplicate key is inserted after all other duplicate keys (see HAM_DUPLICATE_INSERT_LAST). Otherwise it is inserted in sorted order.
Record Number Databases (created with HAM_RECORD_NUMBER) expect either an empty key (with a size of 0 and data pointing to NULL), or a user-supplied key (with key.flag HAM_KEY_USER_ALLOC, a size of 8 and a valid data pointer). If key.size is 0 and key.data is NULL, hamsterdb will temporarily allocate memory for key->data, which will then point to an 8-byte unsigned integer in host-endian.
db | A valid Database handle | |
txn | A Transaction handle, or NULL | |
key | The key of the new item | |
record | The record of the new item | |
flags | Optional flags for inserting. Possible flags are:
|
Referenced by ham::db::insert().
HAM_EXPORT int HAM_CALLCONV ham_key_get_approximate_match_type | ( | ham_key_t * | key | ) |
Returns the kind of key match which produced this key as it was returned by one of the ham_find(), ham_cursor_find() or ham_cursor_find_ex() functions
This routine assumes the key was passed back by one of the ham_find, ham_cursor_find or ham_cursor_find_ex functions and not used by any other hamsterdb functions after that.
As such, this function produces an answer akin to the 'sign' of the specified key as it was returned by the find operation.
key | A valid key |
Referenced by ham::key::get_approximate_match_type().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_set_compare_func | ( | ham_db_t * | db, | |
ham_compare_func_t | foo | |||
) |
Sets the comparison function
The comparison function compares two index keys. It returns -1 if the first key is smaller, +1 if the second key is smaller or 0 if both keys are equal.
If foo is NULL, hamsterdb will use the default compare function (which is based on memcmp(3)).
Note that if you use a custom comparison routine in combination with extended keys, it might be useful to disable the prefix comparison, which is based on memcmp(3). See ham_set_prefix_compare_func for details.
db | A valid Database handle | |
foo | A pointer to the compare function |
Referenced by ham::db::set_compare_func().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_set_duplicate_compare_func | ( | ham_db_t * | db, | |
ham_duplicate_compare_func_t | foo | |||
) |
Sets the duplicate comparison function
The comparison function compares two records which share the same key. It returns -1 if the first record is smaller, +1 if the second record is smaller or 0 if both records are equal.
If foo is NULL, hamsterdb will use the default compare function (which is based on memcmp(3)).
To enable this function, the flag HAM_SORT_DUPLICATES has to be specified when creating or opening a Database.
Sorting duplicate keys comes with a small performance penalty compared to unsorted duplicates, since the records of other duplicates have to be fetched for the comparison.
db | A valid Database handle | |
foo | A pointer to the compare function |
HAM_EXPORT ham_status_t HAM_CALLCONV ham_set_prefix_compare_func | ( | ham_db_t * | db, | |
ham_prefix_compare_func_t | foo | |||
) |
Sets the prefix comparison function
The prefix comparison function is called when an index uses keys with variable length and at least one of the two keys is loaded only partially.
If foo is NULL, hamsterdb will not use any prefix comparison.
db | A valid Database handle | |
foo | A pointer to the prefix compare function |
Referenced by ham::db::set_prefix_compare_func().