Macros
#define	UPS_FLUSH_COMMITTED_TRANSACTIONS 1

#define	UPS_DONT_LOCK 0xf0000000

Functions
UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_create (ups_env_t *env, const char filename, uint32_t flags, uint32_t mode, const ups_parameter_t *param)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_open (ups_env_t *env, const char filename, uint32_t flags, const ups_parameter_t *param)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_get_parameters (ups_env_t env, ups_parameter_t param)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_create_db (ups_env_t env, ups_db_t db, uint16_t name, uint32_t flags, const ups_parameter_t params)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_open_db (ups_env_t env, ups_db_t db, uint16_t name, uint32_t flags, const ups_parameter_t params)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_rename_db (ups_env_t *env, uint16_t oldname, uint16_t newname, uint32_t flags)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_erase_db (ups_env_t *env, uint16_t name, uint32_t flags)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_flush (ups_env_t *env, uint32_t flags)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_get_database_names (ups_env_t env, uint16_t names, uint32_t *length)

UPS_EXPORT ups_status_t UPS_CALLCONV	ups_env_close (ups_env_t *env, uint32_t flags)

Detailed Description

Macro Definition Documentation

#define UPS_DONT_LOCK 0xf0000000

Definition at line 1082 of file upscaledb.h.

#define UPS_FLUSH_COMMITTED_TRANSACTIONS 1

Definition at line 1061 of file upscaledb.h.

Function Documentation

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_close	(	ups_env_t *	env,
		uint32_t	flags
	)

Closes the Database Environment

This function closes the Database Environment. It also frees the memory resources allocated in the env handle, and tries to truncate the file (see below).

If the flag UPS_AUTO_CLEANUP is specified, upscaledb automatically calls ups_db_close with flag UPS_AUTO_CLEANUP on all open Databases (which closes all open Databases and their Cursors). This invalidates the ups_db_t and ups_cursor_t handles!

If the flag is not specified, the application must close all Database handles with ups_db_close to prevent memory leaks.

This function also aborts all Transactions which were not yet committed, and therefore renders all Txn handles invalid. If the flag UPS_TXN_AUTO_COMMIT is specified, all Transactions will be committed.

This function also tries to truncate the file and "cut off" unused space at the end of the file to reduce the file size. This feature is disabled on Win32 if memory mapped I/O is used (see UPS_DISABLE_MMAP).

Parameters

env	A valid Environment handle
flags	Optional flags for closing the handle. Possible flags are: UPS_AUTO_CLEANUP. Calls ups_db_close with the flag UPS_AUTO_CLEANUP on every open Database UPS_TXN_AUTO_COMMIT. Automatically commit all open Transactions UPS_TXN_AUTO_ABORT. Automatically abort all open Transactions; this is the default behaviour

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if env is NULL

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create	(	ups_env_t **	env,
		const char *	filename,
		uint32_t	flags,
		uint32_t	mode,
		const ups_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). The maximum number of Databases depends on the page size; the default is above 600.

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 ups_env_create_db or opened with ups_env_open_db.

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

To enable ACID Transactions, supply the flag UPS_ENABLE_TRANSACTIONS. By default, upscaledb will use a Journal for recovering the Environment and its data in case of a crash, and also to re-apply committed Transactions which were not yet flushed to disk. This Journalling can be disabled with the flag UPS_DISABLE_RECOVERY. (It is disabled if the Environment is in-memory.)

For performance reasons the Journal does not use fsync(2) (or FlushFileBuffers on Win32) to flush modified buffers to disk. Use the flag UPS_ENABLE_FSYNC to force the use of fsync.

If Transactions are enabled, a journal file is written in order to provide recovery if the system crashes. These journal files can be compressed by supplying the parameter UPS_PARAM_ENABLE_JOURNAL_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details. This parameter is not persisted.

Upscaledb can transparently encrypt the generated file using 128bit AES in CBC mode. The transactional journal is not encrypted. Encryption can be enabled by specifying UPS_PARAM_ENCRYPTION_KEY (see below). The identical key has to be provided in ups_env_open as well. Ignored for remote Environments.

CRC32 checksums are stored when a page is flushed, and verified when it is fetched from disk if the flag UPS_ENABLE_CRC32 is set. API functions will return UPS_INTEGRITY_VIOLATED in case of failed verifications. Not allowed in In-Memory Environments. This flag is not persisted.

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. Can be a URL ("ups://<hostname>:<port>/<environment>") for remote access.
flags	Optional flags for opening the Environment, combined with bitwise OR. Possible flags are: UPS_ENABLE_FSYNC Flushes all file handles after committing or aborting a Txn 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. UPS_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 specify cache_size other than 0. UPS_DISABLE_MMAP Do not use memory mapped files for I/O. By default, upscaledb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used. UPS_CACHE_UNLIMITED Do not limit the cache. Nearly as fast as an In-Memory Database. Not allowed in combination with a limited cache size. UPS_ENABLE_TRANSACTIONS Enables Transactions for this Environment. UPS_DISABLE_RECOVERY Disables logging/recovery for this Environment. UPS_ENABLE_CRC32 Stores (and verifies) CRC32 checksums. Not allowed in combination with UPS_IN_MEMORY.
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 ups_parameter_t structures. The following parameters are available: UPS_PARAM_CACHE_SIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as UPS_DEFAULT_CACHE_SIZE - usually 2MB UPS_PARAM_POSIX_FADVISE Sets the "advice" for posix_fadvise(). Only on supported platforms. Allowed values are UPS_POSIX_FADVICE_NORMAL (which is the default) or UPS_POSIX_FADVICE_RANDOM. UPS_PARAM_PAGE_SIZE 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. UPS_PARAM_FILE_SIZE_LIMIT Sets a file size limit (in bytes). Disabled by default. Not allowed in combination with UPS_IN_MEMORY. If the limit is exceeded, API functions return UPS_LIMITS_REACHED. UPS_PARAM_LOG_DIRECTORY The path of the log file and the journal files; default is the same path as the database file. Ignored for remote Environments. UPS_PARAM_NETWORK_TIMEOUT_SEC Timeout (in seconds) when waiting for data from a remote server. By default, no timeout is set. UPS_PARAM_ENABLE_JOURNAL_COMPRESSION Compresses the journal files to reduce I/O. See notes above. UPS_PARAM_ENCRYPTION_KEY The 16 byte long AES encryption key; enables AES encryption for the Environment file. Not allowed for In-Memory Environments. Ignored for remote Environments.

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags or parameters was specified; UPS_IO_ERROR if the file could not be opened or reading/writing failed; UPS_INV_FILE_VERSION if the Environment version is not compatible with the library version; UPS_OUT_OF_MEMORY if memory could not be allocated; UPS_INV_PAGE_SIZE if page_size is not 1024 or a multiple of 2048; UPS_INV_KEY_SIZE if key_size is too large (at least 4 keys must fit in a page); UPS_WOULD_BLOCK if another process has locked the file; UPS_ENVIRONMENT_ALREADY_OPEN if env is already in use

See also: ups_env_create; ups_env_close; ups_env_open

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create_db	(	ups_env_t *	env,
		ups_db_t **	db,
		uint16_t	name,
		uint32_t	flags,
		const ups_parameter_t *	params
	)

Creates a new Database in a Database Environment

An Environment can contain a (limited) amount of Databases; the exact limit depends on the page size and is above 600.

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

This function initializes the ups_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ups_db_close. Alternatively, the Database handle is closed automatically if ups_env_close is called with the flag UPS_AUTO_CLEANUP.

A Database can (and should) be configured and optimized for the data that is inserted. The data is described through flags and parameters. upscaledb differentiates between several data characteristics, and offers predefined "types" to describe the keys. In general, the default key type (UPS_TYPE_BINARY) is slower than the other types, and fixed-length binary keys (UPS_TYPE_BINARY in combination with UPS_PARAM_KEY_SIZE) is faster than variable-length binary keys. It is therefore recommended to always set the key size and record size, although it is not required.

Internally, upscaledb uses two different layouts ("default" and "pax) depending on the settings specified by the user. The "default" layout is enabled for variable-length keys or if duplicate keys are enabled. For fixed-length keys (without duplicates) the "pax" layout is chosen. The "pax" layout is more compact and usually faster.

A word of warning regarding the use of fixed length binary keys (UPS_TYPE_CUSTOM or UPS_TYPE_BINARY in combination with UPS_PARAM_KEY_SIZE): if your key size is too large, only few keys will fit in a Btree node. The Btree fanout will be very high, which will decrease performance. In such cases it might be better to NOT specify the key size; then upscaledb will store keys as blobs if they are too large.

See the Wiki documentation for Evaluating and Benchmarking on how to test different configurations and optimize for performance.

The key type is set with UPS_PARAM_KEY_TYPE and the record type is set with UPS_PARAM_RECORD_TYPE. The types can have one of the following values:

UPS_TYPE_BINARY This is the default typef or keys and records: a binary blob with fixed or variable length. Internally, upscaledb uses memcmp(3) for the sort order of binary keys. Key size depends on UPS_PARAM_KEY_SIZE and is unlimited (UPS_KEY_SIZE_UNLIMITED) by default. Record size depends on UPS_PARAM_RECORD_SIZE and is unlimited (UPS_RECORD_SIZE_UNLIMITED) by default.
UPS_TYPE_CUSTOM Only for keys: similar to UPS_TYPE_BINARY, but uses a callback function for the sort order. This function is set with the parameter UPS_PARAM_CUSTOM_COMPARE_NAME.
UPS_TYPE_UINT8 Key is a 8bit (1 byte) unsigned integer
UPS_TYPE_UINT16 Key is a 16bit (2 byte) unsigned integer
UPS_TYPE_UINT32 Key is a 32bit (4 byte) unsigned integer
UPS_TYPE_UINT64 Key is a 64bit (8 byte) unsigned integer
UPS_TYPE_REAL32 Key is a 32bit (4 byte) float
UPS_TYPE_REAL64 Key is a 64bit (8 byte) double

If the type is ommitted then UPS_TYPE_BINARY is the default.

If binary/custom keys are so big that they cannot be stored in the Btree, then the full key will be stored in an overflow area, which has performance implications when accessing such keys.

In addition to the flags above, you can specify UPS_ENABLE_DUPLICATE_KEYS to insert duplicate keys, i.e. to model 1:n or n:m relationships.

If the size of the records is always constant, then UPS_PARAM_RECORD_SIZE should be used to specify this size. This allows upscaledb to optimize the record storage, and small records will automatically be stored in the Btree's leaf nodes instead of a separately allocated blob, allowing faster access. Setting a record size to 0 is valid and suited for boolean values ("key exists" vs "key doesn't exist"). The default record size is UPS_RECORD_SIZE_UNLIMITED.

Records can be compressed transparently in order to reduce I/O and disk space. Compression is enabled with UPS_PARAM_RECORD_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details.

Keys can also be compressed by setting the parameter UPS_PARAM_KEY_COMPRESSION. See the upscaledb documentation for more details.

In addition, several integer compression algorithms are available for Databases created with the type UPS_TYPE_UINT32. Note that integer compression only works with the default page size of 16kb.

UPS_COMPRESSOR_UINT32_SIMDCOMP: fast and extremely good compression for dense keys (i.e. record number keys).
UPS_COMPRESSOR_UINT32_SIMDFOR: faster than UPS_COMPRESSOR_UINT32_SIMDCOMP but with slightly worse compression. Only for Intel platforms, requires SSE3. Not compatible to UPS_COMPRESSOR_UINT32_FOR.
UPS_COMPRESSOR_UINT32_FOR: Pure C implementation, slightly slower than UPS_COMPRESSOR_UINT32_SIMDFOR. Not compatible to UPS_COMPRESSOR_UINT32_SIMDFOR.
UPS_COMPRESSOR_UINT32_VARBYTE: Good compression and performance, especially for keys that are not dense (i.e. with "gaps"). If possible, uses AVX-instructions based on MaskedVbyte. Otherwise falls back to a plain C implementation.

Parameters

env	A valid Environment handle.
db	A valid Database handle, which will point to the created Database. To close the handle, use ups_db_close.
name	The name of the Database. If a Database with this name already exists, the function will fail with UPS_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: UPS_ENABLE_DUPLICATE_KEYS Enable duplicate keys for this Database. By default, duplicate keys are disabled. UPS_RECORD_NUMBER32 Creates an "auto-increment" Database. Keys in Record Number Databases are automatically assigned an incrementing 32bit value. If key->data is not NULL (and key->flags is UPS_KEY_USER_ALLOC), the value of the current key is returned in key. If key-data is NULL and key->size is 0, key->data is temporarily allocated by upscaledb. UPS_RECORD_NUMBER64 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 UPS_KEY_USER_ALLOC), the value of the current key is returned in key. If key-data is NULL and key->size is 0, key->data is temporarily allocated by upscaledb.
params	An array of ups_parameter_t structures. The following parameters are available: UPS_PARAM_KEY_TYPE The type of the keys in the B+Tree index. The default is UPS_TYPE_BINARY. See above for more information. UPS_PARAM_KEY_SIZE The (fixed) size of the keys in the B+Tree index; or UPS_KEY_SIZE_UNLIMITED for unlimited and variable keys (this is the default). UPS_PARAM_RECORD_TYPE The type of the records in the B+Tree index. The default is UPS_TYPE_BINARY. See above for more information. UPS_PARAM_RECORD_SIZE The (fixed) size of the records; or UPS_RECORD_SIZE_UNLIMITED if there was no fixed record size specified (this is the default). UPS_PARAM_RECORD_COMPRESSION Compresses the records. UPS_PARAM_KEY_COMPRESSION Compresses the keys. UPS_PARAM_CUSTOM_COMPARE_NAME Specifies the name of the custom compare function (only if UPS_PARAM_KEY_TYPE is UPS_TYPE_CUSTOM).

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified; UPS_DATABASE_ALREADY_EXISTS if a Database with this name already exists in this Environment; UPS_OUT_OF_MEMORY if memory could not be allocated; UPS_LIMITS_REACHED if the maximum number of Databases per Environment was already created

Referenced by upscaledb::env::create_db(), and main().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_erase_db	(	ups_env_t *	env,
		uint16_t	name,
		uint32_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 UPS_DATABASE_NOT_FOUND. If the Database was already opened, the function will fail with UPS_DATABASE_ALREADY_OPEN.
flags	Optional flags for deleting the Database; unused, set to 0.

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved; UPS_DATABASE_NOT_FOUND if a Database with this name does not exist; UPS_DATABASE_ALREADY_OPEN if a Database with this name is still open

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_flush	(	ups_env_t *	env,
		uint32_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 UPS_SUCCESS.

Parameters

env	A valid Environment handle
flags	Optional flags for flushing; unused, set to 0

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if db is NULL

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_database_names	(	ups_env_t *	env,
		uint16_t *	names,
		uint32_t *	length
	)

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. length must be the length of names when calling the function, and will be the number of Databases when the function returns. The function returns UPS_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
length	Pointer to the length of the array; will be used to store the number of Databases when the function returns.

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if env, names or length is NULL; UPS_LIMITS_REACHED if names is not large enough to hold all Database names

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_parameters	(	ups_env_t *	env,
		ups_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:

UPS_PARAM_CACHE_SIZE returns the cache size
UPS_PARAM_PAGE_SIZE returns the page size
UPS_PARAM_MAX_DATABASES returns the max. number of Databases of this Database's Environment
UPS_PARAM_FLAGS returns the flags which were used to open or create this Database
UPS_PARAM_FILEMODE returns the mode parameter which was specified when creating this Database
UPS_PARAM_FILENAME returns the filename (the value of this parameter is a const char * pointer casted to a uint64_t variable)
UPS_PARAM_LOG_DIRECTORY The path of the log file and the journal files. Ignored for remote Environments.
UPS_PARAM_JOURNAL_COMPRESSION Returns the selected algorithm for journal compression, or 0 if compression is disabled

Parameters

env	A valid Environment handle
param	An array of ups_parameter_t structures

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if the env pointer is NULL or param is NULL

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open	(	ups_env_t **	env,
		const char *	filename,
		uint32_t	flags,
		const ups_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).

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 ups_env_create_db or opened with ups_env_open_db.

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

Also see the documentation ups_env_create about Transactions, Recovery, AES encryption and the use of fsync.

If Transactions are enabled, a journal file is written in order to provide recovery if the system crashes. These journal files can be compressed by supplying the parameter UPS_PARAM_JOURNAL_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details. This parameter is not persisted.

CRC32 checksums are stored when a page is flushed, and verified when it is fetched from disk if the flag UPS_ENABLE_CRC32 is set. API functions will return UPS_INTEGRITY_VIOLATED in case of failed verifications. This flag is not persisted.

Parameters

env	A valid Environment handle
filename	The filename of the Environment file, or URL of a upscaledb Server
flags	Optional flags for opening the Environment, combined with bitwise OR. Possible flags are: UPS_READ_ONLY Opens the file for reading only. Operations that need write access (i.e. ups_db_insert) will return UPS_WRITE_PROTECTED. UPS_ENABLE_FSYNC Flushes all file handles after committing or aborting a Txn 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. UPS_DISABLE_MMAP Do not use memory mapped files for I/O. By default, upscaledb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used. UPS_CACHE_UNLIMITED Do not limit the cache. Nearly as fast as an In-Memory Database. Not allowed in combination with a limited cache size. UPS_ENABLE_TRANSACTIONS Enables Transactions for this Environment. UPS_DISABLE_RECOVERY Disables logging/recovery for this Environment. UPS_AUTO_RECOVERY Automatically recover the Environment, if necessary. UPS_ENABLE_CRC32 Stores (and verifies) CRC32 checksums.
param	An array of ups_parameter_t structures. The following parameters are available: UPS_PARAM_CACHE_SIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as UPS_DEFAULT_CACHE_SIZE - usually 2MB UPS_PARAM_POSIX_FADVISE Sets the "advice" for posix_fadvise(). Only on supported platforms. Allowed values are UPS_POSIX_FADVICE_NORMAL (which is the default) or UPS_POSIX_FADVICE_RANDOM. UPS_PARAM_FILE_SIZE_LIMIT Sets a file size limit (in bytes). Disabled by default. If the limit is exceeded, API functions return UPS_LIMITS_REACHED. UPS_PARAM_LOG_DIRECTORY The path of the log file and the journal files; default is the same path as the database file. Ignored for remote Environments. UPS_PARAM_NETWORK_TIMEOUT_SEC Timeout (in seconds) when waiting for data from a remote server. By default, no timeout is set. UPS_PARAM_JOURNAL_COMPRESSION Compresses the journal files to reduce I/O. See notes above. UPS_PARAM_ENCRYPTION_KEY The 16 byte long AES encryption key; enables AES encryption for the Environment file. Not allowed for In-Memory Environments. Ignored for remote Environments.

Returns: UPS_SUCCESS upon success.; UPS_INV_PARAMETER if the env pointer is NULL, an invalid combination of flags was specified; UPS_FILE_NOT_FOUND if the file does not exist; UPS_IO_ERROR if the file could not be opened or reading failed; UPS_INV_FILE_VERSION if the Environment version is not compatible with the library version.; UPS_OUT_OF_MEMORY if memory could not be allocated; UPS_WOULD_BLOCK if another process has locked the file; UPS_NEED_RECOVERY if the Database is in an inconsistent state; UPS_LOG_INV_FILE_HEADER if the logfile is corrupt; UPS_ENVIRONMENT_ALREADY_OPEN if env is already in use; UPS_NETWORK_ERROR if a remote server is not reachable

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open_db	(	ups_env_t *	env,
		ups_db_t **	db,
		uint16_t	name,
		uint32_t	flags,
		const ups_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 ups_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ups_db_close. Alternatively, the Database handle is closed automatically if ups_env_close is called with the flag UPS_AUTO_CLEANUP.

If this database stores keys with a custom compare function then you have to install the compare function (ups_register_compare) prior to opening the database.

Records can be compressed transparently in order to reduce I/O and disk space. Compression is enabled with UPS_PARAM_ENABLE_RECORD_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details. This parameter is not persisted.

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

Parameters

name	The name of the Database. If a Database with this name does not exist, the function will fail with UPS_DATABASE_NOT_FOUND.
flags	Optional flags for opening the Database, combined with bitwise OR. Possible flags are: UPS_READ_ONLY Opens the Database for reading only. Operations that need write access (i.e. ups_db_insert) will return UPS_WRITE_PROTECTED.
params	Reserved; set to NULL

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified; UPS_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment.; UPS_DATABASE_ALREADY_OPEN if this Database was already opened; UPS_OUT_OF_MEMORY if memory could not be allocated; UPS_NOT_READY if the database requires a custom callback function, but this function was not yet registered

Referenced by main(), and upscaledb::env::open_db().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_rename_db	(	ups_env_t *	env,
		uint16_t	oldname,
		uint16_t	newname,
		uint32_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 UPS_DATABASE_NOT_FOUND.
newname	The new name of this Database. If a Database with this name already exists, the function will fail with UPS_DATABASE_ALREADY_EXISTS.
flags	Optional flags for renaming the Database, combined with bitwise OR; unused, set to 0.

Returns: UPS_SUCCESS upon success; UPS_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved; UPS_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment; UPS_DATABASE_ALREADY_EXISTS if a Database with the new name already exists; UPS_OUT_OF_MEMORY if memory could not be allocated; UPS_NOT_READY if the Environment env was not initialized correctly (i.e. not yet opened or created)

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

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation