Defines
#define	HAM_DONT_LOCK 0xf0000000
Functions
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, 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, 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_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)

Define Documentation

#define HAM_DONT_LOCK 0xf0000000

Definition at line 835 of file hamsterdb.h.

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 also frees the memory resources allocated in the env handle.

If the flag HAM_AUTO_CLEANUP is specified, hamsterdb automatically calls ham_db_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_db_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:

env	A valid Environment handle
flags	Optional flags for closing the handle. Possible flags are: HAM_AUTO_CLEANUP. Calls ham_db_close with the flag HAM_AUTO_CLEANUP on every open Database HAM_TXN_AUTO_COMMIT. Automatically commit all open Transactions HAM_TXN_AUTO_ABORT. Automatically abort all open Transactions; this is the default behaviour

Returns:: HAM_SUCCESS upon success; HAM_INV_PARAMETER if env is NULL

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

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,
		const ham_parameter_t *	param
	)

Creates a Database Environment

A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory). By default, up to 16 Databases can be stored in one file.

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

Parameters:

env	A pointer to an Environment handle
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_ENABLE_FSYNC Flushes all file handles after committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This file has no effect if Transactions are disabled. Slows down performance but makes sure that all file handles and operating system caches are transferred to disk, thus providing a stronger durability. HAM_IN_MEMORY 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_ENABLE_RECOVERY Enables logging/recovery for this Database. Not allowed in combination with HAM_IN_MEMORY. HAM_ENABLE_TRANSACTIONS Enables Transactions for this Database. 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. Default is 0644.
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_DATABASES The number of maximum Databases in this Environment; default value: 16. HAM_PARAM_LOG_DIRECTORY The path of the log file and the journal files; default is the same path as the database file

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_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_env_create; ham_env_close; ham_env_open

Referenced by hamsterdb::env::create(), and main().

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

An Environment can handle up to 16 Databases, unless higher values are configured when the Environment is created (see

See also:: ham_env_create).

Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000).

This function initializes the ham_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ham_db_close. Alternatively, the Database handle is closed automatically if ham_env_close is called with the flag HAM_AUTO_CLEANUP.

Parameters:

env	A valid Environment handle.
db	A valid Database handle, which will point to the created Database. To close the handle, use ham_db_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_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_ENABLE_EXTENDED_KEYS Enable extended keys for this Database. By default, extended keys are disabled. 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: HAM_PARAM_KEYSIZE The size of the keys in the B+Tree index. The default size is 21 bytes.

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 hamsterdb::env::create_db(), and main().

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

Referenced by hamsterdb::env::flush().

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

The following parameters are supported:

HAM_PARAM_CACHESIZE returns the cache size
HAM_PARAM_PAGESIZE returns the page size
HAM_PARAM_MAX_DATABASES returns the max. number of Databases of this Database's Environment
HAM_PARAM_FLAGS returns the flags which were used to open or create this Database
HAM_PARAM_FILEMODE returns the mode parameter which was specified when creating this Database
HAM_PARAM_FILENAME returns the filename (the value of this parameter is a const char * pointer casted to a ham_u64_t variable)
HAM_PARAM_LOG_DIRECTORY The path of the log file and the journal files

Parameters:

env	A valid Environment handle
param	An array of ham_parameter_t structures

Returns:: HAM_SUCCESS upon success; HAM_INV_PARAMETER if the env pointer is NULL or param is NULL

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

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

Opens an existing Database Environment

This function opens an existing Database Environment.

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

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

Specify a URL instead of a filename (i.e. "http://localhost:8080/customers.db") to access a remote hamsterdb Server.

Parameters:

env	A valid Environment handle
filename	The filename of the Environment file, or URL of a hamsterdb Server
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_db_insert) will return HAM_WRITE_PROTECTED. HAM_ENABLE_FSYNC Flushes all file handles after committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This file has no effect if Transactions are disabled. Slows down performance but makes sure that all file handles and operating system caches are transferred to disk, thus providing a stronger durability. 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_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. HAM_AUTO_RECOVERY Automatically recover the Database, if necessary. This flag implies HAM_ENABLE_RECOVERY. HAM_ENABLE_TRANSACTIONS Enables Transactions for this Database. 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_LOG_DIRECTORY The path of the log file and the journal files; default is the same path as the database file

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; HAM_NETWORK_ERROR if a remote server is not reachable

Referenced by main(), and hamsterdb::env::open().

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

Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000).

This function initializes the ham_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ham_db_close. Alternatively, the Database handle is closed automatically if ham_env_close is called with the flag HAM_AUTO_CLEANUP.

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_db_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: 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_READ_ONLY Opens the Database for reading only. Operations that need write access (i.e. ham_db_insert) will return HAM_WRITE_PROTECTED.
params	Reserved; set to NULL

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

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 hamsterdb::env::rename_db().

Defines

Functions

Define Documentation

Function Documentation