hamsterdb Environment Functions

Functions

HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_new (ham_env_t **env)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_delete (ham_env_t *env)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_create (ham_env_t *env, const char *filename, ham_u32_t flags, ham_u32_t mode)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_create_ex (ham_env_t *env, const char *filename, ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_open (ham_env_t *env, const char *filename, ham_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_open_ex (ham_env_t *env, const char *filename, ham_u32_t flags, const ham_parameter_t *param)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_get_parameters (ham_env_t *env, ham_parameter_t *param)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_create_db (ham_env_t *env, ham_db_t *db, ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_open_db (ham_env_t *env, ham_db_t *db, ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_rename_db (ham_env_t *env, ham_u16_t oldname, ham_u16_t newname, ham_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_erase_db (ham_env_t *env, ham_u16_t name, ham_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_flush (ham_env_t *env, ham_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_enable_encryption (ham_env_t *env, ham_u8_t key[16], ham_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_get_database_names (ham_env_t *env, ham_u16_t *names, ham_size_t *count)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_close (ham_env_t *env, ham_u32_t flags)

Function Documentation

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_close ( ham_env_t env,
ham_u32_t  flags 
)

Closes the Database Environment

This function closes the Database Environment. It does not free the memory resources allocated in the env handle - use ham_env_delete to free env.

If the flag HAM_AUTO_CLEANUP is specified, hamsterdb automatically calls ham_close with flag HAM_AUTO_CLEANUP on all open Databases (which closes all open Databases and their Cursors). This invalidates the ham_db_t and ham_cursor_t handles!

If the flag is not specified, the application must close all Database handles with ham_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.

This function removes all file-level filters installed with ham_env_add_file_filter (and hence also, implicitly, the filter installed by ham_env_enable_encryption).

Parameters:
env A valid Environment handle
flags Optional flags for closing the handle. Possible flags are:

Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if env is NULL

Referenced by ham::env::close().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_create ( ham_env_t env,
const char *  filename,
ham_u32_t  flags,
ham_u32_t  mode 
)

Creates a Database Environment

A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory). Per default, up to 16 Databases can be stored in one file (see ham_env_create_ex on how to store even more Databases).

Each Database is identified by a positive 16bit value (except 0 and values at or above 0xf000 (HAM_EMPTY_DATABASE_NAME)). Databases in an Environment can be created with ham_env_create_db or opened with ham_env_open_db.

Parameters:
env A valid Environment handle, which was created with ham_env_new
filename The filename of the Environment file. If the file already exists, it is overwritten. Can be NULL if an In-Memory Environment is created.
flags Optional flags for opening the Environment, combined with bitwise OR. For allowed flags, see ham_env_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 env 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 Environment 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_ENVIRONMENT_ALREADY_OPEN if env is already in use
See also:
ham_env_create_ex
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_create_db ( ham_env_t env,
ham_db_t db,
ham_u16_t  name,
ham_u32_t  flags,
const ham_parameter_t params 
)

Creates a new Database in a Database Environment

Parameters:
env A valid Environment handle.
db A valid Database handle, which will point to the created Database. To close the handle, use ham_close.
name The name of the Database. If a Database with this name already exists, the function will fail with HAM_DATABASE_ALREADY_EXISTS. Database names from 0xf000 to 0xffff and 0 are reserved.
flags Optional flags for creating the Database, combined with bitwise OR. Possible flags are:

  • 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, like 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_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_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.
params An array of ham_parameter_t structures. The following parameters are available:

Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified
HAM_DATABASE_ALREADY_EXISTS if a Database with this name already exists in this Environment
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_LIMITS_REACHED if the maximum number of Databases per Environment was already created
HAM_DATABASE_ALREADY_OPEN if db is already in use

Referenced by ham::env::create_db().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_create_ex ( ham_env_t env,
const char *  filename,
ham_u32_t  flags,
ham_u32_t  mode,
const ham_parameter_t param 
)

Creates a Database Environment - extended version

A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory). Per default, up to 16 Databases can be stored in one file, but this setting can be overwritten by specifying the parameter HAM_PARAM_MAX_ENV_DATABASES.

Each Database is identified by a positive 16bit value (except 0 and values at or above 0xf000 (HAM_EMPTY_DATABASE_NAME)). Databases in an Environment can be created with ham_env_create_db or opened with ham_env_open_db.

Parameters:
env A valid Environment handle, which was created with ham_env_new
filename The filename of the Environment file. If the file already exists, it is overwritten. Can be NULL for an In-Memory Environment.
flags Optional flags for opening the Environment, combined with bitwise OR. Possible flags are:

  • HAM_WRITE_THROUGH Immediately write modified pages to the disk. This slows down all Database operations, but may save the Database integrity in case of a system crash.
  • HAM_IN_MEMORY_DB Creates an In-Memory Environment. No file will be created, and the Database contents are lost after the Environment 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_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. Please read the README file for details.
    This flag implies 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_MAX_ENV_DATABASES The number of maximum Databases in this Environment; default value: 16.
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags or parameters was specified
HAM_INV_PARAMETER if the value for HAM_PARAM_MAX_ENV_DATABASES is too high (either decrease it or increase the page size)
HAM_IO_ERROR if the file could not be opened or reading/writing failed
HAM_INV_FILE_VERSION if the Environment 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_ENVIRONMENT_ALREADY_OPEN if env is already in use
See also:
ham_create_ex
ham_env_close
ham_env_open_ex

Referenced by ham::env::create().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_delete ( ham_env_t env  ) 

Frees a ham_env_t handle

Frees the ham_env_t structure, but does not close the Environment. Call this function AFTER you have closed the Environment using ham_env_close, or you will lose your data!

Parameters:
env A valid Environment handle
Returns:
This function always returns HAM_SUCCESS

Referenced by ham::env::close().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_enable_encryption ( ham_env_t env,
ham_u8_t  key[16],
ham_u32_t  flags 
)

Enables AES encryption

This function enables AES encryption for every Database in the Environment. The AES key is cached in the Environment handle. The AES encryption/decryption is only active when file chunks are written to disk/read from disk; the cached pages in RAM are decrypted. Please read the FAQ for security relevant notes.

The encryption has no effect on In-Memory Environments, but the function will return HAM_SUCCESS.

Log files and the header page of the Database are not encrypted.

The encryption will be active till ham_env_close is called. If the Environment handle is reused after calling ham_env_close, the encryption is no longer active. ham_env_enable_encryption should be called immediately after ham_env_create[_ex] or ham_env_open[_ex].

Parameters:
env A valid Environment handle
key A 128bit AES key
flags Optional flags for encrypting; unused, set to 0
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if one of the parameters is NULL
HAM_ALREADY_INITIALIZED if this function was called AFTER ham_env_open_db or ham_env_create_db
HAM_NOT_IMPLEMENTED if hamsterdb was compiled without support for AES encryption
HAM_ACCESS_DENIED if the key (= password) was wrong
HAM_ALREADY_INITIALIZED if encryption is already enabled for this Environment

Referenced by ham::env::enable_encryption().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_erase_db ( ham_env_t env,
ham_u16_t  name,
ham_u32_t  flags 
)

Deletes a Database from an Environment

Parameters:
env A valid Environment handle
name The name of the Database to delete. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND. If the Database was already opened, the function will fail with HAM_DATABASE_ALREADY_OPEN.
flags Optional flags for deleting the Database; unused, set to 0.
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved
HAM_DATABASE_NOT_FOUND if a Database with this name does not exist
HAM_DATABASE_ALREADY_OPEN if a Database with this name is still open

Referenced by ham::env::erase_db().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_flush ( ham_env_t env,
ham_u32_t  flags 
)

Flushes the Environment

This function flushes the Environment caches and writes the whole file to disk. All 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.

Parameters:
env A valid Environment handle
flags Optional flags for flushing; unused, set to 0
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db is NULL
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_get_database_names ( ham_env_t env,
ham_u16_t names,
ham_size_t count 
)

Returns the names of all Databases in an Environment

This function returns the names of all Databases and the number of Databases in an Environment.

The memory for names must be allocated by the user. count must be the size of names when calling the function, and will be the number of Databases when the function returns. The function returns HAM_LIMITS_REACHED if names is not big enough; in this case, the caller should resize the array and call the function again.

Parameters:
env A valid Environment handle
names Pointer to an array for the Database names
count Pointer to the size of the array; will be used to store the number of Databases when the function returns.
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if env, names or count is NULL
HAM_LIMITS_REACHED if names is not large enough to hold all Database names

Referenced by ham::env::get_database_names().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_get_parameters ( ham_env_t env,
ham_parameter_t param 
)

Retrieve the current value for a given Environment setting

Only those values requested by the parameter array will be stored.

Parameters:
env A valid Environment handle
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
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or param is NULL

Referenced by ham::env::get_parameters().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_new ( ham_env_t **  env  ) 

Allocates a ham_env_t handle

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

Referenced by ham::env::create(), and ham::env::open().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_open ( ham_env_t env,
const char *  filename,
ham_u32_t  flags 
)

Opens an existing Database Environment

Parameters:
env A valid Environment handle, which was created with ham_env_new
filename The filename of the Environment file
flags Optional flags for opening the Environment, combined with bitwise OR. See the documentation of ham_env_open_ex for the allowed flags.
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env 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 Environment 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_ENVIRONMENT_ALREADY_OPEN if env is already in use
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_open_db ( ham_env_t env,
ham_db_t db,
ham_u16_t  name,
ham_u32_t  flags,
const ham_parameter_t params 
)

Opens a Database in a Database Environment

Parameters:
env A valid Environment handle
db A valid Database handle, which will point to the opened Database. To close the handle, use
See also:
ham_close.
Parameters:
name The name of the Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND.
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:

Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified
HAM_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment.
HAM_DATABASE_ALREADY_OPEN if this Database was already opened
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_DATABASE_ALREADY_OPEN if db is already in use

Referenced by ham::env::open_db().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_open_ex ( ham_env_t env,
const char *  filename,
ham_u32_t  flags,
const ham_parameter_t param 
)

Opens an existing Database Environment - extended version

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

  • HAM_READ_ONLY Opens the file for reading only. Operations that need write access (i.e. ham_insert) will return HAM_DB_READ_ONLY
  • HAM_WRITE_THROUGH Immediately write modified pages to the disk. This slows down all Database operations, but could save the Database integrity in case of a system crash.
  • 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. Will return HAM_NEED_RECOVERY, if the Database is in an inconsistent state. Not allowed in combination with HAM_IN_MEMORY_DB, HAM_DISABLE_FREELIST_FLUSH and HAM_WRITE_THROUGH.
  • HAM_AUTO_RECOVERY Automatically recover the Database, if necessary. This flag implies HAM_ENABLE_RECOVERY.
  • 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.
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 env pointer is NULL, 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 Environment 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_ENVIRONMENT_ALREADY_OPEN if env is already in use

Referenced by ham::env::open().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_rename_db ( ham_env_t env,
ham_u16_t  oldname,
ham_u16_t  newname,
ham_u32_t  flags 
)

Renames a Database in an Environment.

Parameters:
env A valid Environment handle.
oldname The old name of the existing Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND.
newname The new name of this Database. If a Database with this name already exists, the function will fail with HAM_DATABASE_ALREADY_EXISTS.
flags Optional flags for renaming the Database, combined with bitwise OR; unused, set to 0.
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved
HAM_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment
HAM_DATABASE_ALREADY_EXISTS if a Database with the new name already exists
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_NOT_READY if the Environment env was not initialized correctly (i.e. not yet opened or created)

Referenced by ham::env::rename_db().


Generated on Tue Mar 16 20:19:44 2010 for hamsterdb Embedded Database by  doxygen 1.6.1