Defines | Typedefs | Functions

hamsterdb Database Functions

Defines

#define HAM_WRITE_THROUGH   0x00000001
#define HAM_READ_ONLY   0x00000004
#define HAM_USE_BTREE   0x00000010
#define HAM_DISABLE_VAR_KEYLEN   0x00000040
#define HAM_IN_MEMORY_DB   0x00000080
#define HAM_DISABLE_MMAP   0x00000200
#define HAM_CACHE_STRICT   0x00000400
#define HAM_DISABLE_FREELIST_FLUSH   0x00000800
#define HAM_LOCK_EXCLUSIVE   0x00001000
#define HAM_RECORD_NUMBER   0x00002000
#define HAM_ENABLE_DUPLICATES   0x00004000
#define HAM_ENABLE_RECOVERY   0x00008000
#define HAM_AUTO_RECOVERY   0x00010000
#define HAM_ENABLE_TRANSACTIONS   0x00020000
#define HAM_CACHE_UNLIMITED   0x00040000
#define HAM_SORT_DUPLICATES   0x00100000
#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   0x00FF0000
#define HAM_FAST_ESTIMATE   0x0001
#define HAM_PARAM_CACHESIZE   0x00000100
#define HAM_PARAM_PAGESIZE   0x00000101
#define HAM_PARAM_KEYSIZE   0x00000102
#define HAM_PARAM_MAX_ENV_DATABASES   0x00000103
#define HAM_PARAM_DATA_ACCESS_MODE   0x00000104
#define HAM_PARAM_GET_FLAGS   0x00000200
#define HAM_PARAM_GET_FILEMODE   0x00000201
#define HAM_PARAM_GET_FILENAME   0x00000202
#define HAM_PARAM_GET_DATABASE_NAME   0x00000203
#define HAM_PARAM_DBNAME   HAM_PARAM_GET_DATABASE_NAME
#define HAM_PARAM_GET_KEYS_PER_PAGE   0x00000204
#define HAM_PARAM_GET_DATA_ACCESS_MODE   0x00000205
#define HAM_PARAM_GET_DAM   HAM_PARAM_GET_DATA_ACCESS_MODE
#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_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 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 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)

Functions

HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_new (ham_db_t **db)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_delete (ham_db_t *db)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_create (ham_db_t *db, const char *filename, ham_u32_t flags, ham_u32_t mode)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_create_ex (ham_db_t *db, const char *filename, ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_open (ham_db_t *db, const char *filename, ham_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_open_ex (ham_db_t *db, const char *filename, ham_u32_t flags, const ham_parameter_t *param)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_get_error (ham_db_t *db)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_set_prefix_compare_func (ham_db_t *db, ham_prefix_compare_func_t foo)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_set_compare_func (ham_db_t *db, ham_compare_func_t foo)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_set_duplicate_compare_func (ham_db_t *db, ham_duplicate_compare_func_t foo)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_enable_compression (ham_db_t *db, ham_u32_t level, ham_u32_t flags)
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)
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)
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)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_flush (ham_db_t *db, ham_u32_t flags)
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)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_get_parameters (ham_db_t *db, ham_parameter_t *param)
HAM_EXPORT ham_u32_t HAM_CALLCONV ham_get_flags (ham_db_t *db)
HAM_EXPORT ham_env_t *HAM_CALLCONV ham_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_close (ham_db_t *db, ham_u32_t flags)

Define Documentation

#define HAM_AUTO_CLEANUP   1

Flag for ham_close, ham_env_close

Definition at line 2152 of file hamsterdb.h.

Referenced by main().

#define HAM_AUTO_RECOVERY   0x00010000

Flag for ham_open_ex, ham_env_open_ex. This flag is non persistent.

Definition at line 1431 of file hamsterdb.h.

#define HAM_CACHE_STRICT   0x00000400

Flag for ham_open, ham_open_ex, ham_create, ham_create_ex. This flag is non persistent.

Definition at line 1405 of file hamsterdb.h.

#define HAM_CACHE_UNLIMITED   0x00040000

Flag for ham_open, ham_open_ex, ham_create, ham_create_ex. This flag is non persistent.

Definition at line 1441 of file hamsterdb.h.

#define HAM_DIRECT_ACCESS   0x0040

Flag for ham_find, ham_cursor_find_ex, ham_cursor_move

Definition at line 1836 of file hamsterdb.h.

#define HAM_DISABLE_FREELIST_FLUSH   0x00000800
Deprecated:
Flag for ham_open, ham_open_ex, ham_create, ham_create_ex. This flag is non persistent.

Definition at line 1410 of file hamsterdb.h.

#define HAM_DISABLE_MMAP   0x00000200

Flag for ham_open, ham_open_ex, ham_create, ham_create_ex. This flag is non persistent.

Definition at line 1400 of file hamsterdb.h.

#define HAM_DISABLE_VAR_KEYLEN   0x00000040

Flag for ham_create, ham_create_ex. This flag is non persistent.

Definition at line 1389 of file hamsterdb.h.

#define HAM_DONT_CLEAR_LOG   2

Definition at line 2155 of file hamsterdb.h.

#define HAM_DUPLICATE   0x0002

Flag for ham_insert and ham_cursor_insert

Definition at line 1821 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 1827 of file hamsterdb.h.

#define HAM_DUPLICATE_INSERT_BEFORE   0x0004

Flag for ham_cursor_insert

Definition at line 1824 of file hamsterdb.h.

#define HAM_DUPLICATE_INSERT_FIRST   0x0010

Flag for ham_cursor_insert

Definition at line 1830 of file hamsterdb.h.

#define HAM_DUPLICATE_INSERT_LAST   0x0020

Flag for ham_cursor_insert

Definition at line 1833 of file hamsterdb.h.

#define HAM_ENABLE_DUPLICATES   0x00004000

Flag for ham_create, ham_create_ex. This flag is persisted in the Database.

Definition at line 1422 of file hamsterdb.h.

Referenced by main(), and run_demo().

#define HAM_ENABLE_RECOVERY   0x00008000

Flag for ham_create_ex, ham_open_ex, ham_env_create_ex, ham_env_open_ex. This flag is non persistent.

Definition at line 1427 of file hamsterdb.h.

#define HAM_ENABLE_TRANSACTIONS   0x00020000

Flag for ham_create_ex, ham_open_ex, ham_env_create_ex, ham_env_open_ex. This flag is non persistent.

Definition at line 1436 of file hamsterdb.h.

Referenced by main().

#define HAM_FAST_ESTIMATE   0x0001

Flag for ham_get_key_count

Definition at line 1948 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 1854 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 1868 of file hamsterdb.h.

#define HAM_HINTS_MASK   0x00FF0000

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

Definition at line 1874 of file hamsterdb.h.

#define HAM_IN_MEMORY_DB   0x00000080

Flag for ham_create, ham_create_ex. This flag is non persistent.

Definition at line 1393 of file hamsterdb.h.

#define HAM_LOCK_EXCLUSIVE   0x00001000

Flag for ham_open, ham_open_ex, ham_create, ham_create_ex

Definition at line 1414 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 1818 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 1987 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 2003 of file hamsterdb.h.

#define HAM_PARAM_DBNAME   HAM_PARAM_GET_DATABASE_NAME

Definition at line 2036 of file hamsterdb.h.

#define HAM_PARAM_GET_DAM   HAM_PARAM_GET_DATA_ACCESS_MODE

Definition at line 2052 of file hamsterdb.h.

#define HAM_PARAM_GET_DATA_ACCESS_MODE   0x00000205

Retrieve the Data Access mode for the Database

Definition at line 2051 of file hamsterdb.h.

#define HAM_PARAM_GET_DATABASE_NAME   0x00000203

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

When the Database is not related to an Environment, the reserved 'name' 0xf001 is used for this Database.

Definition at line 2035 of file hamsterdb.h.

#define HAM_PARAM_GET_FILEMODE   0x00000201

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

Definition at line 2017 of file hamsterdb.h.

#define HAM_PARAM_GET_FILENAME   0x00000202

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

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

Definition at line 2026 of file hamsterdb.h.

#define HAM_PARAM_GET_FLAGS   0x00000200

Retrieve the Database/Environment flags as were specified at the time of ham_create/ham_env_create/ham_open/ham_env_open invocation.

Definition at line 2010 of file hamsterdb.h.

#define HAM_PARAM_GET_KEYS_PER_PAGE   0x00000204

Retrieve the maximum number of keys per page; this number depends on the currently active page and key sizes.

When no Database or Environment is specified with the request, the default settings for all of these will be assumed in order to produce a viable ball park value for this one.

Definition at line 2046 of file hamsterdb.h.

#define HAM_PARAM_KEYSIZE   0x00000102

Parameter name for ham_create_ex; sets the key size

Definition at line 1994 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 1998 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 1991 of file hamsterdb.h.

#define HAM_PARTIAL   0x0080
#define HAM_READ_ONLY   0x00000004

Flag for ham_open, ham_open_ex. This flag is non persistent.

Definition at line 1377 of file hamsterdb.h.

#define HAM_RECORD_NUMBER   0x00002000

Flag for ham_create, ham_create_ex, ham_env_create_db. This flag is persisted in the Database.

Definition at line 1418 of file hamsterdb.h.

Referenced by main().

#define HAM_SORT_DUPLICATES   0x00100000

Flag for ham_create, ham_create_ex, ham_env_create_db, ham_open, ham_open_ex, ham_env_open_db This flag is non persistent.

Definition at line 1448 of file hamsterdb.h.

#define HAM_TXN_AUTO_ABORT   4

Automatically abort all open Transactions (the default)

Definition at line 2158 of file hamsterdb.h.

#define HAM_TXN_AUTO_COMMIT   8

Automatically commit all open Transactions

Definition at line 2161 of file hamsterdb.h.

#define HAM_USE_BTREE   0x00000010

Flag for ham_create, ham_create_ex. This flag is persisted in the Database.

Definition at line 1383 of file hamsterdb.h.

#define HAM_WRITE_THROUGH   0x00000001

Flag for ham_open, ham_open_ex, ham_create, ham_create_ex. This flag is non persistent.

Definition at line 1371 of file hamsterdb.h.


Typedef Documentation

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

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

Remarks:
This function compares two records. 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.
As hamsterdb allows zero-length records, it may happen that either lhs_length or rhs_length, or both are zero. In this case the related data pointers (rhs, lhs) may be NULL.

Definition at line 1550 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

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.
If one of the keys is only partially loaded, but the comparison function needs the full key, the return value should be HAM_PREFIX_REQUEST_FULLKEY.

Definition at line 1477 of file hamsterdb.h.


Function Documentation

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.

Parameters:
db A valid Database handle
flags Optional 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

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_create ( ham_db_t db,
const char *  filename,
ham_u32_t  flags,
ham_u32_t  mode 
)

Creates a Database

This function is a simplified version of

See also:
ham_create_ex. It is recommended to use ham_create_ex instead.
ham_create_ex

Referenced by main().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_create_ex ( ham_db_t db,
const char *  filename,
ham_u32_t  flags,
ham_u32_t  mode,
const ham_parameter_t param 
)

Creates a Database - extended version

This function is a shortcut for a sequence of ham_env_create_ex followed by ham_env_create_db.

It creates an (internal, hidden) Environment and in this Environment it creates a Database with a reserved identifier - HAM_DEFAULT_DATABASE_NAME.

As a consequence, it is no problem to create a Database with ham_create_ex, and later open it with ham_env_open_ex.

The internal Environment handle can be retrieved with ham_get_env.

Parameters:
db A valid Database handle
filename The filename of the Database file. If the file already exists, it will be overwritten. Can be NULL if you create an In-Memory Database
flags Optional flags for opening the Database, combined with bitwise OR. Possible flags are:

  • HAM_WRITE_THROUGH Immediately write modified pages to disk. This slows down all Database operations, but may save the Database integrity in case of a system crash.
  • HAM_USE_BTREE Use a B+Tree for the index structure. Currently enabled by default, but future releases of hamsterdb will offer additional index structures, i.e. hash tables.
  • HAM_DISABLE_VAR_KEYLEN Do not allow the use of variable length keys. Inserting a key, which is larger than the B+Tree index key size, returns HAM_INV_KEYSIZE.
  • HAM_IN_MEMORY_DB Creates an In-Memory Database. No file will be created, and the Database contents are lost after the Database is closed. The filename parameter can be NULL. Do NOT use in combination with HAM_CACHE_STRICT and do NOT specify cachesize other than 0.
  • HAM_RECORD_NUMBER Creates an "auto-increment" Database. Keys in Record Number Databases are automatically assigned an incrementing 64bit value. If key->data is not NULL (and key->flags is HAM_KEY_USER_ALLOC and key->size is 8), the value of the current key is returned in key (a host-endian 64bit number of type ham_u64_t). If key-data is NULL and key->size is 0, key->data is temporarily allocated by hamsterdb.
  • HAM_ENABLE_DUPLICATES Enable duplicate keys for this Database. By default, duplicate keys are disabled.
  • HAM_SORT_DUPLICATES Sort duplicate keys for this Database. Only allowed in combination with HAM_ENABLE_DUPLICATES. A compare function can be set with ham_set_duplicate_compare_func. This flag is not persistent.
  • HAM_DISABLE_MMAP Do not use memory mapped files for I/O. By default, hamsterdb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used.
  • HAM_CACHE_STRICT Do not allow the cache to grow larger than cachesize. If a Database operation needs to resize the cache, it will return HAM_CACHE_FULL. If the flag is not set, the cache is allowed to allocate more pages than the maximum cache size, but only if it's necessary and only for a short time.
  • HAM_CACHE_UNLIMITED Do not limit the cache. Nearly as fast as an In-Memory Database. Not allowed in combination with HAM_CACHE_STRICT or a limited cache size.
  • HAM_DISABLE_FREELIST_FLUSH This flag is deprecated.
  • HAM_LOCK_EXCLUSIVE Place an exclusive lock on the file. Only one process may hold an exclusive lock for a given file at a given time. Deprecated - this is now the default
  • HAM_ENABLE_RECOVERY Enables logging/recovery for this Database. Not allowed in combination with HAM_IN_MEMORY_DB, HAM_DISABLE_FREELIST_FLUSH and HAM_WRITE_THROUGH.
  • HAM_ENABLE_TRANSACTIONS Enables Transactions for this Database. Remark Transactions were introduced in hamsterdb 1.0.4, but with certain limitations (which will be removed in later version). Please read the README file and the Release Notes for details.
    This flag imples HAM_ENABLE_RECOVERY.
mode File access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows.
param An array of ham_parameter_t structures. The following parameters are available:

  • HAM_PARAM_CACHESIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as HAM_DEFAULT_CACHESIZE - usually 2MB
  • HAM_PARAM_PAGESIZE The size of a file page, in bytes. It is recommended not to change the default size. The default size depends on hardware and operating system. Page sizes must be 1024 or a multiple of 2048.
  • HAM_PARAM_KEYSIZE The size of the keys in the B+Tree index. The default size is 21 bytes.
  • HAM_PARAM_DATA_ACCESS_MODE Gives a hint regarding data access patterns. The default setting optimizes hamsterdb for random read/write access (HAM_DAM_RANDOM_WRITE). Use HAM_DAM_SEQUENTIAL_INSERT for sequential inserts (this is automatically set for record number Databases). For more information about available DAM (Data Access Mode) flags, see hamsterdb Data Access Mode Codes. The DAM is not persistent.
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db pointer is NULL or an invalid combination of flags was specified
HAM_IO_ERROR if the file could not be opened or reading/writing failed
HAM_INV_FILE_VERSION if the Database version is not compatible with the library version
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_INV_PAGESIZE if pagesize is not 1024 or a multiple of 2048
HAM_INV_KEYSIZE if keysize is too large (at least 4 keys must fit in a page)
HAM_WOULD_BLOCK if another process has locked the file
HAM_DATABASE_ALREADY_OPEN if db is already in use
See also:
hamsterdb Data Access Mode Codes

Referenced by ham::db::create(), and main().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_delete ( ham_db_t db  ) 

Frees a ham_db_t handle

Frees the memory and resources of a ham_db_t structure, but does not close the Database. Call this function AFTER you have closed the Database using ham_close, or you will lose your data!

Parameters:
db A valid Database handle
Returns:
This function always returns HAM_SUCCESS

Referenced by ham::db::close(), ham::env::create_db(), main(), and ham::env::open_db().

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.

Parameters:
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
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db is NULL or level is not between 0 and 9
HAM_NOT_IMPLEMENTED if hamsterdb was compiled without support for compression

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.

Parameters:
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
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or key is NULL
HAM_DB_READ_ONLY if you tried to erase a key from a read-only Database
HAM_KEY_NOT_FOUND if key was not found

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

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.

Parameters:
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:

  • 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! 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_KEY_NOT_FOUND if the key does not exist
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 ham::db::find(), and main().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_flush ( ham_db_t db,
ham_u32_t  flags 
)

Flushes the Database

This function is deprecated. Use ham_env_flush instead. Use ham_get_env to retrieve an Environment handle for your Database, in case the handle is not available because the Database was opened or created with ham_create_ex or ham_open_ex.

Deprecated:
This function was replaced by ham_env_flush.
See also:
ham_env_flush
ham_get_env

Referenced by ham::db::flush().

HAM_EXPORT ham_env_t* HAM_CALLCONV ham_get_env ( ham_db_t db  ) 

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

Parameters:
db A valid Database handle
Returns:
The Environment handle
HAM_EXPORT ham_status_t HAM_CALLCONV ham_get_error ( ham_db_t db  ) 

Returns the last error code

Parameters:
db A 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 ham::db::get_error().

HAM_EXPORT ham_u32_t HAM_CALLCONV ham_get_flags ( ham_db_t db  ) 

Retrieve the flags which were specified when the Database was created or opened

Parameters:
db A valid Database handle
Returns:
The Database flags
Deprecated:
This function was replaced by ham_get_parameters and ham_env_get_parameters
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.

Parameters:
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
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or keycount is NULL or when flags contains an invalid flag set

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.

The following parameters are supported:

  • HAM_PARAM_CACHESIZE returns the cache size
  • HAM_PARAM_PAGESIZE returns the page size
  • HAM_PARAM_KEYSIZE returns the key size
  • HAM_PARAM_MAX_ENV_DATABASES returns the max. number of Databases of this Database's Environment
  • HAM_PARAM_GET_FLAGS returns the flags which were used to open or create this Database
  • HAM_PARAM_GET_FILEMODE returns the mode parameter which was specified when creating this Database
  • HAM_PARAM_GET_FILENAME returns the filename (the value of this parameter is a const char * pointer casted to a ham_u64_t variable)
  • HAM_PARAM_GET_DATABASE_NAME returns the Database name
  • HAM_PARAM_GET_KEYS_PER_PAGE returns the maximum number of keys per page
  • HAM_PARAM_GET_DATA_ACCESS_MODE returns the Data Access Mode
Parameters:
db A valid Database handle
param An 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 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.

Parameters:
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:

  • 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 was specified AND duplicate sorting is enabled (HAM_SORT_DUPLICATES)
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_DUPLICATES.
HAM_INV_PARAMETER if HAM_PARTIAL is specified and record->partial_offset+record->partial_size exceeds the record->size
HAM_DB_READ_ONLY if you tried to insert a key in a read-only Database
HAM_INV_KEYSIZE if the key size is larger than the keysize parameter specified for ham_create_ex and variable key sizes are disabled (see HAM_DISABLE_VAR_KEYLEN) OR if the keysize parameter specified for ham_create_ex is smaller than 8.
See also:
HAM_DISABLE_VAR_KEYLEN

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

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.

Parameters:
key A 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 ham::key::get_approximate_match_type().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_new ( ham_db_t **  db  ) 

Allocates a ham_db_t handle

Parameters:
db Pointer to the pointer which is allocated
Returns:
HAM_SUCCESS upon success
HAM_OUT_OF_MEMORY if memory allocation failed

Referenced by ham::db::create(), ham::env::create_db(), main(), ham::db::open(), and ham::env::open_db().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_open ( ham_db_t db,
const char *  filename,
ham_u32_t  flags 
)

Opens an existing Database

This function is a simplified version of

See also:
ham_open_ex. It is recommended to use ham_open_ex instead.
ham_open_ex

Referenced by main().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_open_ex ( ham_db_t db,
const char *  filename,
ham_u32_t  flags,
const ham_parameter_t param 
)

Opens an existing Database - extended version

This function is a shortcut for a sequence of ham_env_open_ex followed by ham_env_open_db.

It opens an (internal, hidden) Environment and in this Environment it opens the first Database that was created.

As a consequence, it is no problem to open a Database with ham_open_ex, even if it was created with ham_env_create_ex.

The internal Environment handle can be retrieved with ham_get_env.

Parameters:
db A valid Database handle
filename The filename of the Database file
flags Optional flags for opening the Database, combined with bitwise OR. Possible flags are:

param An array of ham_parameter_t structures. The following parameters are available:

  • HAM_PARAM_CACHESIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as HAM_DEFAULT_CACHESIZE - usually 2MB
  • HAM_PARAM_DATA_ACCESS_MODE Gives a hint regarding data access patterns. The default setting optimizes hamsterdb for random read/write access (HAM_DAM_RANDOM_WRITE). Use HAM_DAM_SEQUENTIAL_INSERT for sequential inserts (this is automatically set for record number Databases). Data Access Mode hints can be set for individual Databases, too (see also ham_create_ex) but are applied globally to all Databases within a single Environment. For more information about available DAM (Data Access Mode) flags, see hamsterdb Data Access Mode Codes. The DAM is not persistent.
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db pointer is NULL or an invalid combination of flags was specified
HAM_FILE_NOT_FOUND if the file does not exist
HAM_IO_ERROR if the file could not be opened or reading failed
HAM_INV_FILE_VERSION if the Database version is not compatible with the library version
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_WOULD_BLOCK if another process has locked the file
HAM_NEED_RECOVERY if the Database is in an inconsistent state
HAM_LOG_INV_FILE_HEADER if the logfile is corrupt
HAM_DATABASE_ALREADY_OPEN if db is already in use

Referenced by main(), and ham::db::open().

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.

Parameters:
db A valid Database handle
foo A pointer to the compare function
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if one of the parameters is NULL
See also:
ham_set_prefix_compare_func

Referenced by main(), and 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.

Warning If duplicate sorting is enabled, and records are retrieved with HAM_DIRECT_ACCESS, the records must not be modified or the sort order might get lost.

Parameters:
db A valid Database handle
foo A pointer to the compare function
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if one of the parameters is NULL
See also:
HAM_ENABLE_DUPLICATES
HAM_SORT_DUPLICATES
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.

Parameters:
db A valid Database handle
foo A pointer to the prefix compare function
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db parameter is NULL

Referenced by ham::db::set_prefix_compare_func().