hamsterdb Embedded Database  2.1.7
Macros | Typedefs | Functions
hamsterdb Database Functions

Macros

#define HAM_ENABLE_FSYNC   0x00000001
 
#define HAM_READ_ONLY   0x00000004
 
#define HAM_IN_MEMORY   0x00000080
 
#define HAM_DISABLE_MMAP   0x00000200
 
#define HAM_RECORD_NUMBER   0x00002000
 
#define HAM_ENABLE_DUPLICATE_KEYS   0x00004000
 
#define HAM_ENABLE_DUPLICATES   HAM_ENABLE_DUPLICATE_KEYS
 
#define HAM_ENABLE_RECOVERY   0x00008000
 
#define HAM_AUTO_RECOVERY   0x00010000
 
#define HAM_ENABLE_TRANSACTIONS   0x00020000
 
#define HAM_CACHE_UNLIMITED   0x00040000
 
#define HAM_DISABLE_RECOVERY   0x00080000
 
#define HAM_IS_REMOTE_INTERNAL   0x00200000
 
#define HAM_DISABLE_RECLAIM_INTERNAL   0x00400000
 
#define HAM_FORCE_RECORDS_INLINE   0x00800000
 
#define HAM_FLUSH_WHEN_COMMITTED   0x01000000
 
#define HAM_OVERWRITE   0x0001
 
#define HAM_DUPLICATE   0x0002
 
#define HAM_DUPLICATE_INSERT_BEFORE   0x0004
 
#define HAM_DUPLICATE_INSERT_AFTER   0x0008
 
#define HAM_DUPLICATE_INSERT_FIRST   0x0010
 
#define HAM_DUPLICATE_INSERT_LAST   0x0020
 
#define HAM_DIRECT_ACCESS   0x0040
 
#define HAM_PARTIAL   0x0080
 
#define HAM_HINT_APPEND   0x00080000
 
#define HAM_HINT_PREPEND   0x00100000
 
#define HAM_HINTS_MASK   0x001F0000
 
#define HAM_ERASE_ALL_DUPLICATES   1
 
#define HAM_PARAM_CACHE_SIZE   0x00000100
 
#define HAM_PARAM_CACHESIZE   HAM_PARAM_CACHE_SIZE
 
#define HAM_PARAM_PAGE_SIZE   0x00000101
 
#define HAM_PARAM_PAGESIZE   HAM_PARAM_PAGE_SIZE
 
#define HAM_PARAM_KEY_SIZE   0x00000102
 
#define HAM_PARAM_KEYSIZE   HAM_PARAM_KEY_SIZE
 
#define HAM_PARAM_MAX_DATABASES   0x00000103
 
#define HAM_PARAM_KEY_TYPE   0x00000104
 
#define HAM_PARAM_LOG_DIRECTORY   0x00000105
 
#define HAM_PARAM_ENCRYPTION_KEY   0x00000106
 
#define HAM_PARAM_NETWORK_TIMEOUT_SEC   0x00000107
 
#define HAM_PARAM_RECORD_SIZE   0x00000108
 
#define HAM_RECORD_SIZE_UNLIMITED   ((ham_u32_t)-1)
 
#define HAM_KEY_SIZE_UNLIMITED   ((ham_u16_t)-1)
 
#define HAM_PARAM_FLAGS   0x00000200
 
#define HAM_PARAM_FILEMODE   0x00000201
 
#define HAM_PARAM_FILENAME   0x00000202
 
#define HAM_PARAM_DATABASE_NAME   0x00000203
 
#define HAM_PARAM_MAX_KEYS_PER_PAGE   0x00000204
 
#define HAM_PARAM_JOURNAL_COMPRESSION   0x1000
 
#define HAM_PARAM_RECORD_COMPRESSION   0x1001
 
#define HAM_PARAM_KEY_COMPRESSION   0x1002
 
#define HAM_COMPRESSOR_NONE   0
 
#define HAM_COMPRESSOR_ZLIB   1
 
#define HAM_COMPRESSOR_SNAPPY   2
 
#define HAM_COMPRESSOR_LZF   3
 
#define HAM_COMPRESSOR_LZO   4
 
#define HAM_AUTO_CLEANUP   1
 
#define HAM_DONT_CLEAR_LOG   2
 
#define HAM_TXN_AUTO_ABORT   4
 
#define HAM_TXN_AUTO_COMMIT   8
 

Typedefs

typedef int HAM_CALLCONV(* ham_compare_func_t )(ham_db_t *db, const ham_u8_t *lhs, ham_u32_t lhs_length, const ham_u8_t *rhs, ham_u32_t rhs_length)
 

Functions

HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_get_error (ham_db_t *db)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_set_compare_func (ham_db_t *db, ham_compare_func_t foo)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_find (ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_record_t *record, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_insert (ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_record_t *record, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_erase (ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_get_key_count (ham_db_t *db, ham_txn_t *txn, ham_u32_t flags, ham_u64_t *keycount)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_get_parameters (ham_db_t *db, ham_parameter_t *param)
 
HAM_EXPORT ham_env_t *HAM_CALLCONV ham_db_get_env (ham_db_t *db)
 
HAM_EXPORT int HAM_CALLCONV ham_key_get_approximate_match_type (ham_key_t *key)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_db_close (ham_db_t *db, ham_u32_t flags)
 

Detailed Description

Macro Definition Documentation

#define HAM_AUTO_CLEANUP   1

Flag for ham_db_close, ham_env_close

Definition at line 1803 of file hamsterdb.h.

Referenced by hamsterdb::db::close(), hamsterdb::env::close(), and main().

#define HAM_AUTO_RECOVERY   0x00010000

Flag for ham_env_open. This flag is non persistent.

Definition at line 1167 of file hamsterdb.h.

#define HAM_CACHE_UNLIMITED   0x00040000

Flag for ham_env_open, ham_env_create. This flag is non persistent.

Definition at line 1175 of file hamsterdb.h.

#define HAM_COMPRESSOR_LZF   3

hamsterdb pro: selects lzf compression http://oldhome.schmorp.de/marc/liblzf.html

Definition at line 1721 of file hamsterdb.h.

#define HAM_COMPRESSOR_LZO   4

hamsterdb pro: selects lzop compression http://www.oberhumer.com/opensource/lzo

Definition at line 1727 of file hamsterdb.h.

#define HAM_COMPRESSOR_NONE   0

hamsterdb pro: helper macro for disabling compression

Definition at line 1706 of file hamsterdb.h.

#define HAM_COMPRESSOR_SNAPPY   2

hamsterdb pro: selects google snappy compression http://code.google.com/p/snappy

Definition at line 1715 of file hamsterdb.h.

#define HAM_COMPRESSOR_ZLIB   1

hamsterdb pro: selects zlib compression

Definition at line 1709 of file hamsterdb.h.

#define HAM_DIRECT_ACCESS   0x0040

Flag for ham_db_find, ham_cursor_find, ham_cursor_move

Definition at line 1482 of file hamsterdb.h.

#define HAM_DISABLE_MMAP   0x00000200

Flag for ham_env_open, ham_env_create. This flag is non persistent.

Definition at line 1149 of file hamsterdb.h.

#define HAM_DISABLE_RECLAIM_INTERNAL   0x00400000

Definition at line 1185 of file hamsterdb.h.

#define HAM_DISABLE_RECOVERY   0x00080000

Flag for ham_env_create, ham_env_open. This flag is non persistent.

Definition at line 1179 of file hamsterdb.h.

#define HAM_DONT_CLEAR_LOG   2

Definition at line 1806 of file hamsterdb.h.

#define HAM_DUPLICATE   0x0002

Flag for ham_db_insert and ham_cursor_insert

Definition at line 1467 of file hamsterdb.h.

Referenced by copy_db(), main(), and run_demo().

#define HAM_DUPLICATE_INSERT_AFTER   0x0008

Flag for ham_cursor_insert

Definition at line 1473 of file hamsterdb.h.

#define HAM_DUPLICATE_INSERT_BEFORE   0x0004

Flag for ham_cursor_insert

Definition at line 1470 of file hamsterdb.h.

#define HAM_DUPLICATE_INSERT_FIRST   0x0010

Flag for ham_cursor_insert

Definition at line 1476 of file hamsterdb.h.

#define HAM_DUPLICATE_INSERT_LAST   0x0020

Flag for ham_cursor_insert

Definition at line 1479 of file hamsterdb.h.

#define HAM_ENABLE_DUPLICATE_KEYS   0x00004000

Flag for ham_env_create_db. This flag is persisted in the Database.

Definition at line 1157 of file hamsterdb.h.

Referenced by main(), and run_demo().

#define HAM_ENABLE_DUPLICATES   HAM_ENABLE_DUPLICATE_KEYS

Definition at line 1159 of file hamsterdb.h.

#define HAM_ENABLE_FSYNC   0x00000001

Flag for ham_env_open, ham_env_create. This flag is non persistent.

Definition at line 1125 of file hamsterdb.h.

#define HAM_ENABLE_RECOVERY   0x00008000

Flag for ham_env_create, ham_env_open. This flag is non persistent.

Definition at line 1163 of file hamsterdb.h.

#define HAM_ENABLE_TRANSACTIONS   0x00020000

Flag for ham_env_create, ham_env_open. This flag is non persistent.

Definition at line 1171 of file hamsterdb.h.

Referenced by main().

#define HAM_ERASE_ALL_DUPLICATES   1

Definition at line 1549 of file hamsterdb.h.

#define HAM_FLUSH_WHEN_COMMITTED   0x01000000

Flag for ham_env_open, ham_env_create. This flag is non persistent.

Definition at line 1192 of file hamsterdb.h.

#define HAM_FORCE_RECORDS_INLINE   0x00800000

Definition at line 1188 of file hamsterdb.h.

#define HAM_HINT_APPEND   0x00080000

Flag for ham_cursor_insert

Mutually exclusive with flag HAM_HINT_PREPEND.

Hints the hamsterdb engine that the current key will compare as larger than any key already existing in the Database. The hamsterdb engine will verify this postulation and when found not to be true, will revert to a regular insert operation as if this flag was not specified. The incurred cost then is only one additional key comparison.

Definition at line 1500 of file hamsterdb.h.

#define HAM_HINT_PREPEND   0x00100000

Flag for ham_cursor_insert

Mutually exclusive with flag HAM_HINT_APPEND.

Hints the hamsterdb engine that the current key will compare as smaller than any key already existing in the Database. The hamsterdb engine will verify this postulation and when found not to be true, will revert to a regular insert operation as if this flag was not specified. The incurred cost then is only one additional key comparison.

Definition at line 1514 of file hamsterdb.h.

#define HAM_HINTS_MASK   0x001F0000

Flag mask to extract the common hint flags from a find/move/insert/erase flag value.

Definition at line 1520 of file hamsterdb.h.

#define HAM_IN_MEMORY   0x00000080

Flag for ham_env_create. This flag is non persistent.

Definition at line 1143 of file hamsterdb.h.

Referenced by main().

#define HAM_IS_REMOTE_INTERNAL   0x00200000

Definition at line 1182 of file hamsterdb.h.

#define HAM_KEY_SIZE_UNLIMITED   ((ham_u16_t)-1)

Value for unlimited key sizes

Definition at line 1653 of file hamsterdb.h.

#define HAM_OVERWRITE   0x0001

Flag for ham_db_insert and ham_cursor_insert

When specified with ham_db_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 1464 of file hamsterdb.h.

#define HAM_PARAM_CACHE_SIZE   0x00000100

Parameter name for ham_env_open, ham_env_create; sets the cache size

Definition at line 1613 of file hamsterdb.h.

#define HAM_PARAM_CACHESIZE   HAM_PARAM_CACHE_SIZE

Definition at line 1615 of file hamsterdb.h.

#define HAM_PARAM_DATABASE_NAME   0x00000203

Retrieve the Database 'name' number of this ham_db_t Database within the current ham_env_t Environment.

Definition at line 1676 of file hamsterdb.h.

#define HAM_PARAM_ENCRYPTION_KEY   0x00000106

hamsterdb pro: Parameter name for ham_env_open, ham_env_create; sets the AES encryption key

Definition at line 1640 of file hamsterdb.h.

#define HAM_PARAM_FILEMODE   0x00000201

Retrieves the filesystem file access mode as was specified at the time of ham_env_create/ham_env_open invocation.

Definition at line 1661 of file hamsterdb.h.

#define HAM_PARAM_FILENAME   0x00000202

Return a const char * pointer to the current Environment/Database file name in the ham_u64_t value member, when the Database is actually stored on disc.

In-memory Databases will return a NULL (0) pointer instead.

Definition at line 1670 of file hamsterdb.h.

#define HAM_PARAM_FLAGS   0x00000200

Retrieves the Database/Environment flags as were specified at the time of ham_env_create/ham_env_open invocation.

Definition at line 1657 of file hamsterdb.h.

#define HAM_PARAM_JOURNAL_COMPRESSION   0x1000

hamsterdb pro: Parameter name for ham_env_create, ham_env_open; enables compression for the journal.

Definition at line 1689 of file hamsterdb.h.

#define HAM_PARAM_KEY_COMPRESSION   0x1002

hamsterdb pro: Parameter name for ham_env_create_db, ham_env_open_db; enables compression for the records of a Database.

Definition at line 1703 of file hamsterdb.h.

#define HAM_PARAM_KEY_SIZE   0x00000102

Parameter name for ham_env_create_db; sets the key size

Definition at line 1623 of file hamsterdb.h.

#define HAM_PARAM_KEY_TYPE   0x00000104

Parameter name for ham_env_create_db; sets the key type

Definition at line 1632 of file hamsterdb.h.

Referenced by main(), and run_demo().

#define HAM_PARAM_KEYSIZE   HAM_PARAM_KEY_SIZE

Definition at line 1625 of file hamsterdb.h.

#define HAM_PARAM_LOG_DIRECTORY   0x00000105

Parameter name for ham_env_open, ham_env_create; sets the path of the log files

Definition at line 1636 of file hamsterdb.h.

#define HAM_PARAM_MAX_DATABASES   0x00000103

Parameter name for ham_env_get_parameters; retrieves the number of maximum Databases

Definition at line 1629 of file hamsterdb.h.

#define HAM_PARAM_MAX_KEYS_PER_PAGE   0x00000204

Retrieve the maximum number of keys per page; this number depends on the currently active page and key sizes. Can be an estimate if keys do not have constant sizes or if duplicate keys are used.

Definition at line 1683 of file hamsterdb.h.

#define HAM_PARAM_NETWORK_TIMEOUT_SEC   0x00000107

Parameter name for ham_env_open, ham_env_create; sets the network timeout (in seconds)

Definition at line 1644 of file hamsterdb.h.

#define HAM_PARAM_PAGE_SIZE   0x00000101

Parameter name for ham_env_create; sets the page size

Definition at line 1618 of file hamsterdb.h.

#define HAM_PARAM_PAGESIZE   HAM_PARAM_PAGE_SIZE

Definition at line 1620 of file hamsterdb.h.

#define HAM_PARAM_RECORD_COMPRESSION   0x1001

hamsterdb pro: Parameter name for ham_env_create_db, ham_env_open_db; enables compression for the records of a Database.

Definition at line 1696 of file hamsterdb.h.

#define HAM_PARAM_RECORD_SIZE   0x00000108

Parameter name for ham_env_create_db; sets the key size

Definition at line 1647 of file hamsterdb.h.

Referenced by main(), and run_demo().

#define HAM_PARTIAL   0x0080
#define HAM_READ_ONLY   0x00000004

Flag for ham_env_open, ham_env_open_db. This flag is non persistent.

Definition at line 1131 of file hamsterdb.h.

#define HAM_RECORD_NUMBER   0x00002000

Flag for ham_env_create_db. This flag is persisted in the Database.

Definition at line 1153 of file hamsterdb.h.

Referenced by main().

#define HAM_RECORD_SIZE_UNLIMITED   ((ham_u32_t)-1)

Value for unlimited record sizes

Definition at line 1650 of file hamsterdb.h.

#define HAM_TXN_AUTO_ABORT   4

Automatically abort all open Transactions (the default)

Definition at line 1809 of file hamsterdb.h.

#define HAM_TXN_AUTO_COMMIT   8

Automatically commit all open Transactions

Definition at line 1812 of file hamsterdb.h.

Typedef Documentation

typedef int HAM_CALLCONV(* ham_compare_func_t)(ham_db_t *db, const ham_u8_t *lhs, ham_u32_t lhs_length, const ham_u8_t *rhs, ham_u32_t rhs_length)

Typedef for a key comparison function

Remarks
This function compares two index keys. It returns -1, if lhs ("left-hand side", the parameter on the left side) is smaller than rhs ("right-hand side"), 0 if both keys are equal, and 1 if lhs is larger than rhs.

Definition at line 1214 of file hamsterdb.h.

Function Documentation

HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_close ( ham_db_t db,
ham_u32_t  flags 
)

Closes the Database

This function flushes the Database and then closes the file handle. It also free the memory resources allocated in the db handle.

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 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.

Parameters
dbA valid Database handle
flagsOptional flags for closing the Database. Possible values are:
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db is NULL
HAM_CURSOR_STILL_OPEN if not all Cursors of this Database were closed, and HAM_AUTO_CLEANUP was not specified
HAM_TXN_STILL_OPEN if this Database is modified by a currently active Transaction

Referenced by hamsterdb::db::close(), and main().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_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_db_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.

Parameters
dbA valid Database handle
txnA Transaction handle, or NULL
keyThe key to delete
flagsOptional flags for erasing; unused, set to 0
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or key is NULL
HAM_WRITE_PROTECTED if you tried to erase a key from a read-only Database
HAM_KEY_NOT_FOUND if key was not found
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted

Referenced by hamsterdb::db::erase(), and main().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_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 using the same Transaction (or, if Transactions are disabled, using the same Database). 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 or freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases and not if Transactions are enabled.

ham_db_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->partial_size. The original size of the record is stored in record->size.

HAM_PARTIAL is not allowed if record->size is <= 8 or if Transactions are enabled. In such a case, HAM_INV_PARAMETER is returned.

If Transactions are enabled (see HAM_ENABLE_TRANSACTIONS) and txn is NULL then hamsterdb will create a temporary Transaction. When moving the Cursor, and the new key is currently modified in an active Transaction (one that is not yet committed or aborted) then hamsterdb will skip this key and move to the next/previous one. However if flags are 0 (and the Cursor is not moved), and key or rec is NOT NULL, then hamsterdb will return error HAM_TXN_CONFLICT.

Parameters
dbA valid Database handle
txnA Transaction handle, or NULL
keyThe key of the item
recordThe record of the item
flagsOptional flags for searching, which can be combined with bitwise OR. Possible flags are:
  • HAM_FIND_EXACT_MATCH (default). If the key exists, the cursor is adjusted to reference the record. Otherwise, an error is returned. Note that for backwards compatibility the value zero (0) can specified as an alternative when this option is not mixed with any of the others in this list.
  • HAM_FIND_LT_MATCH Cursor 'find' flag 'Less Than': the cursor is moved to point at the last record which' key is less than the specified key. When such a record cannot be located, an error is returned.
  • HAM_FIND_GT_MATCH Cursor 'find' flag 'Greater Than': the cursor is moved to point at the first record which' key is larger than the specified key. When such a record cannot be located, an error is returned.
  • HAM_FIND_LEQ_MATCH Cursor 'find' flag 'Less or EQual': the cursor is moved to point at the record which' key matches the specified key and when such a record is not available the cursor is moved to point at the last record which' key is less than the specified key. When such a record cannot be located, an error is returned.
  • HAM_FIND_GEQ_MATCH Cursor 'find' flag 'Greater or Equal': the cursor is moved to point at the record which' key matches the specified key and when such a record is not available the cursor is moved to point at the first record which' key is larger than the specified key. When such a record cannot be located, an error is returned.
  • HAM_FIND_NEAR_MATCH Cursor 'find' flag 'Any Near Or Equal': the cursor is moved to point at the record which' key matches the specified key and when such a record is not available the cursor is moved to point at either the last record which' key is less than the specified key or the first record which' key is larger than the specified key, whichever of these records is located first. When such records cannot be located, an error is returned.
  • HAM_DIRECT_ACCESS Only for In-Memory Databases and not if Transactions are enabled! Returns a direct pointer to the data blob stored by the hamsterdb engine. This pointer must not be resized or freed, but the data in this memory can be modified.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db, key or record is NULL
HAM_INV_PARAMETER if HAM_DIRECT_ACCESS is specified, but the Database is not an In-Memory Database.
HAM_INV_PARAMETER if HAM_DIRECT_ACCESS and HAM_ENABLE_TRANSACTIONS were both specified.
HAM_INV_PARAMETER if HAM_PARTIAL is set but record size is <= 8 or Transactions are enabled
HAM_KEY_NOT_FOUND if the key does not exist
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted
Remarks
When either or both HAM_FIND_LT_MATCH and/or HAM_FIND_GT_MATCH have been specified as flags, the key structure will be overwritten when an approximate match was found: the key and record structures will then point at the located key and record. In this case the caller should ensure key points at a structure which must adhere to the same restrictions and conditions as specified for ham_cursor_move(..., HAM_CURSOR_NEXT).
See Also
HAM_RECORD_USER_ALLOC
HAM_KEY_USER_ALLOC
ham_record_t
ham_key_t

Referenced by hamsterdb::db::find(), and main().

HAM_EXPORT ham_env_t* HAM_CALLCONV ham_db_get_env ( ham_db_t db)

Retrieves the Environment handle of a Database

Parameters
dbA valid Database handle
Returns
The Environment handle
HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_get_error ( ham_db_t db)

Returns the last error code

Parameters
dbA valid Database handle
Returns
The last error code which was returned by one of the hamsterdb API functions. Use ham_strerror to translate this code to a descriptive string

Referenced by hamsterdb::db::get_error().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_get_key_count ( ham_db_t db,
ham_txn_t txn,
ham_u32_t  flags,
ham_u64_t keycount 
)

Returns 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. This will also speed up the counting.

Parameters
dbA valid Database handle
txnA Transaction handle, or NULL
flagsOptional flags:
keycountA reference to a variable which will receive the calculated key count per page
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or keycount is NULL or when flags contains an invalid flag set

Referenced by hamsterdb::db::get_key_count().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_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.

The following parameters are supported:

  • HAM_PARAM_FLAGS returns the flags which were used to open or create this Database
  • HAM_PARAM_DATABASE_NAME returns the Database name
  • HAM_PARAM_KEY_TYPE returns the Btree key type
  • HAM_PARAM_KEY_SIZE returns the Btree key size or HAM_KEY_SIZE_UNLIMITED if there was no fixed key size specified.
  • HAM_PARAM_RECORD_SIZE returns the record size, or HAM_RECORD_SIZE_UNLIMITED if there was no fixed record size specified.
  • HAM_PARAM_MAX_KEYS_PER_PAGE returns the maximum number of keys per page. This number is precise if the key size is fixed and duplicates are disabled; otherwise it's an estimate.
  • HAM_PARAM_RECORD_COMPRESSION Returns the selected algorithm for record compression, or 0 if compression is disabled
Parameters
dbA valid Database handle
paramAn array of ham_parameter_t structures
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db pointer is NULL or param is NULL

Referenced by hamsterdb::db::get_parameters().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_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.

HAM_PARTIAL is not allowed if record->size is <= 8 or if Transactions are enabled. In such a case, HAM_INV_PARAMETER is returned.

If you wish to insert a duplicate key specify the flag HAM_DUPLICATE. (Note that the Database has to be created with HAM_ENABLE_DUPLICATE_KEYS in order to use duplicate keys.) The duplicate key is inserted after all other duplicate keys (see HAM_DUPLICATE_INSERT_LAST).

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.

For very fast sequential inserts please use ham_cursor_insert in combination with the flag HAM_HINT_APPEND.

Parameters
dbA valid Database handle
txnA Transaction handle, or NULL
keyThe key of the new item
recordThe record of the new item
flagsOptional flags for inserting. Possible flags are:
  • HAM_OVERWRITE. If the key already exists, the record is overwritten. Otherwise, the key is inserted. Flag is not allowed in combination with HAM_DUPLICATE.
  • HAM_DUPLICATE. If the key already exists, a duplicate key is inserted. The key is inserted before the already existing key, or according to the sort order. Flag is not allowed in combination with HAM_OVERWRITE.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db, key or record is NULL
HAM_INV_PARAMETER if the Database is a Record Number Database and the key is invalid (see above)
HAM_INV_PARAMETER if HAM_PARTIAL is set but record size is <= 8 or Transactions are enabled
HAM_INV_PARAMETER if the flags HAM_OVERWRITE and HAM_DUPLICATE were specified, or if HAM_DUPLICATE was specified, but the Database was not created with flag HAM_ENABLE_DUPLICATE_KEYS.
HAM_INV_PARAMETER if HAM_PARTIAL is specified and record->partial_offset+record->partial_size exceeds the record->size
HAM_WRITE_PROTECTED if you tried to insert a key in a read-only Database
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted
HAM_INV_KEY_SIZE if the key size is larger than the HAM_PARAMETER_KEY_SIZE parameter specified for ham_env_create_db OR if the key's size is greater than the Btree key size (see HAM_PARAM_KEY_SIZE).
HAM_INV_RECORD_SIZE if the record size is different from the one specified with HAM_PARAM_RECORD_SIZE

Referenced by copy_db(), hamsterdb::db::insert(), and main().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_db_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.

Supplying a comparison function is only allowed for the key type HAM_TYPE_CUSTOM; see the documentation of

See Also
ham_env_create_db for more information.
Parameters
dbA valid Database handle
fooA pointer to the compare function
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if one of the parameters is NULL
HAM_INV_PARAMETER if the database's key type was not specified as HAM_TYPE_CUSTOM

Referenced by main(), and hamsterdb::db::set_compare_func().

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_db_find() and ham_cursor_find().

This routine assumes the key was passed back by one of the ham_db_find and ham_cursor_find 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.

Parameters
keyA valid key
Returns
1 (greater than) or -1 (less than) when the given key is an approximate result / zero (0) otherwise. Specifically:
  • +1 when the key is greater than the item searched for (key was a GT match)
  • -1 when the key is less than the item searched for (key was a LT match)
  • zero (0) otherwise (key was an EQ (EXACT) match)

Referenced by hamsterdb::key::get_approximate_match_type().