hamsterdb Database Functions

Modules

 hamsterdb Database Access Flags
 hamsterdb Database Configuration
 hamsterdb Cursor Functions

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)

Variables

void * ham_record_t::data
ham_u32_t ham_record_t::flags
ham_u32_t ham_record_t::_intflags
ham_u64_t ham_record_t::_rid
void * ham_key_t::data
ham_u32_t ham_key_t::flags
ham_u32_t ham_key_t::_flags
ham_u64_t ham_parameter_t::value

Function Documentation

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

Parameters:
db A valid Database handle
filename The filename of the Database file. If the file already exists, it is overwritten. Can be NULL if you create an In-Memory Database
flags Optional flags for opening the Database, combined with bitwise OR. For allowed flags, see ham_create_ex.
mode File access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows.
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_WOULD_BLOCK if another process has locked the file
HAM_DATABASE_ALREADY_OPEN if db is already in use
See also:
ham_create_ex
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

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 64 pages, i.e. 256kb on UNIX where 4K pages are usual (or 4Mb on Win32/Win64 where 64K pages are usual).
  • 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().

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(), and ham::env::open_db().

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(), 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

Parameters:
db A valid Database handle
filename The filename of the Database file
flags Optional flags for opening the Database, combined with bitwise OR. See the documentation of ham_open_ex for the allowed flags.
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_DATABASE_ALREADY_OPEN if db is already in use
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

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 64 pages, i.e. 256kb on UNIX where 4K pages are usual (or 4Mb on Win32/Win64 where 64K pages are usual).
  • 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 ham::db::open().


Variable Documentation

For internal use

Definition at line 131 of file hamsterdb.h.

For internal use

Definition at line 87 of file hamsterdb.h.

For internal use

Definition at line 90 of file hamsterdb.h.

void* ham_key_t::data [inherited]

The data of the key

Definition at line 125 of file hamsterdb.h.

Referenced by ham::key::get_data(), ham::key::key(), and ham::key::set_data().

void* ham_record_t::data [inherited]

Pointer to the record data

Definition at line 81 of file hamsterdb.h.

Referenced by ham::record::get_data(), ham::record::record(), and ham::record::set_data().

The key flags; see HAM_KEY_USER_ALLOC

Definition at line 128 of file hamsterdb.h.

Referenced by ham::key::get_flags(), ham::key::key(), and ham::key::set_flags().

The record flags; see HAM_RECORD_USER_ALLOC

Definition at line 84 of file hamsterdb.h.

Referenced by ham::record::get_flags(), ham::record::record(), and ham::record::set_flags().

The value of the parameter.

Definition at line 162 of file hamsterdb.h.


Generated on Thu Feb 11 22:04:58 2010 for hamsterdb Embedded Database by  doxygen 1.6.1