upscaledb  2.2.1
Macros | Typedefs | Functions
upscaledb Database Functions

Macros

#define UPS_ENABLE_FSYNC   0x00000001
 
#define UPS_IGNORE_MISSING_CALLBACK   0x00000002
 
#define UPS_READ_ONLY   0x00000004
 
#define UPS_IN_MEMORY   0x00000080
 
#define UPS_DISABLE_MMAP   0x00000200
 
#define UPS_RECORD_NUMBER   UPS_RECORD_NUMBER64
 
#define UPS_RECORD_NUMBER32   0x00001000
 
#define UPS_RECORD_NUMBER64   0x00002000
 
#define UPS_ENABLE_DUPLICATE_KEYS   0x00004000
 
#define UPS_ENABLE_DUPLICATES   UPS_ENABLE_DUPLICATE_KEYS
 
#define UPS_ENABLE_RECOVERY   UPS_ENABLE_TRANSACTIONS
 
#define UPS_AUTO_RECOVERY   0x00010000
 
#define UPS_ENABLE_TRANSACTIONS   0x00020000
 
#define UPS_CACHE_UNLIMITED   0x00040000
 
#define UPS_DISABLE_RECOVERY   0x00080000
 
#define UPS_IS_REMOTE_INTERNAL   0x00200000
 
#define UPS_DISABLE_RECLAIM_INTERNAL   0x00400000
 
#define UPS_FORCE_RECORDS_INLINE   0x00800000
 
#define UPS_ENABLE_CRC32   0x02000000
 
#define UPS_DONT_FLUSH_TRANSACTIONS   0x04000000
 
#define UPS_FLUSH_TRANSACTIONS_IMMEDIATELY   0x08000000
 
#define UPS_OVERWRITE   0x0001
 
#define UPS_DUPLICATE   0x0002
 
#define UPS_DUPLICATE_INSERT_BEFORE   0x0004
 
#define UPS_DUPLICATE_INSERT_AFTER   0x0008
 
#define UPS_DUPLICATE_INSERT_FIRST   0x0010
 
#define UPS_DUPLICATE_INSERT_LAST   0x0020
 
#define UPS_DIRECT_ACCESS   0x0040
 
#define UPS_FORCE_DEEP_COPY   0x0100
 
#define UPS_HINT_APPEND   0x00080000
 
#define UPS_HINT_PREPEND   0x00100000
 
#define UPS_ERASE_ALL_DUPLICATES   1
 
#define UPS_PARAM_JOURNAL_SWITCH_THRESHOLD   0x00001
 
#define UPS_PARAM_CACHE_SIZE   0x00000100
 
#define UPS_PARAM_CACHESIZE   UPS_PARAM_CACHE_SIZE
 
#define UPS_PARAM_PAGE_SIZE   0x00000101
 
#define UPS_PARAM_PAGESIZE   UPS_PARAM_PAGE_SIZE
 
#define UPS_PARAM_KEY_SIZE   0x00000102
 
#define UPS_PARAM_KEYSIZE   UPS_PARAM_KEY_SIZE
 
#define UPS_PARAM_MAX_DATABASES   0x00000103
 
#define UPS_PARAM_KEY_TYPE   0x00000104
 
#define UPS_PARAM_LOG_DIRECTORY   0x00000105
 
#define UPS_PARAM_ENCRYPTION_KEY   0x00000106
 
#define UPS_PARAM_NETWORK_TIMEOUT_SEC   0x00000107
 
#define UPS_PARAM_RECORD_SIZE   0x00000108
 
#define UPS_PARAM_FILE_SIZE_LIMIT   0x00000109
 
#define UPS_PARAM_POSIX_FADVISE   0x00000110
 
#define UPS_PARAM_CUSTOM_COMPARE_NAME   0x00000111
 
#define UPS_PARAM_RECORD_TYPE   0x00000112
 
#define UPS_POSIX_FADVICE_NORMAL   0
 
#define UPS_POSIX_FADVICE_RANDOM   1
 
#define UPS_RECORD_SIZE_UNLIMITED   ((uint32_t)-1)
 
#define UPS_KEY_SIZE_UNLIMITED   ((uint16_t)-1)
 
#define UPS_PARAM_FLAGS   0x00000200
 
#define UPS_PARAM_FILEMODE   0x00000201
 
#define UPS_PARAM_FILENAME   0x00000202
 
#define UPS_PARAM_DATABASE_NAME   0x00000203
 
#define UPS_PARAM_MAX_KEYS_PER_PAGE   0x00000204
 
#define UPS_PARAM_JOURNAL_COMPRESSION   0x00001000
 
#define UPS_PARAM_RECORD_COMPRESSION   0x00001001
 
#define UPS_PARAM_KEY_COMPRESSION   0x00001002
 
#define UPS_COMPRESSOR_NONE   0
 
#define UPS_COMPRESSOR_ZLIB   1
 
#define UPS_COMPRESSOR_SNAPPY   2
 
#define UPS_COMPRESSOR_LZF   3
 
#define UPS_COMPRESSOR_UINT32_VARBYTE   5
 
#define UPS_COMPRESSOR_UINT32_MASKEDVBYTE   UPS_COMPRESSOR_UINT32_VARBYTE
 
#define UPS_COMPRESSOR_UINT32_SIMDCOMP   6
 
#define UPS_COMPRESSOR_UINT32_GROUPVARINT   7
 
#define UPS_COMPRESSOR_UINT32_STREAMVBYTE   8
 
#define UPS_COMPRESSOR_UINT32_FOR   10
 
#define UPS_COMPRESSOR_UINT32_SIMDFOR   11
 
#define UPS_AUTO_CLEANUP   1
 
#define UPS_DONT_CLEAR_LOG   2
 
#define UPS_TXN_AUTO_ABORT   4
 
#define UPS_TXN_AUTO_COMMIT   8
 

Typedefs

typedef int UPS_CALLCONV(* ups_compare_func_t) (ups_db_t *db, const uint8_t *lhs, uint32_t lhs_length, const uint8_t *rhs, uint32_t rhs_length)
 

Functions

UPS_EXPORT ups_status_t UPS_CALLCONV ups_register_compare (const char *name, ups_compare_func_t func)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_set_compare_func (ups_db_t *db, ups_compare_func_t foo)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_find (ups_db_t *db, ups_txn_t *txn, ups_key_t *key, ups_record_t *record, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_insert (ups_db_t *db, ups_txn_t *txn, ups_key_t *key, ups_record_t *record, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_erase (ups_db_t *db, ups_txn_t *txn, ups_key_t *key, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_count (ups_db_t *db, ups_txn_t *txn, uint32_t flags, uint64_t *count)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_get_parameters (ups_db_t *db, ups_parameter_t *param)
 
UPS_EXPORT ups_env_t *UPS_CALLCONV ups_db_get_env (ups_db_t *db)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_close (ups_db_t *db, uint32_t flags)
 

Detailed Description

Macro Definition Documentation

#define UPS_AUTO_CLEANUP   1

Flag for ups_db_close, ups_env_close

Definition at line 1883 of file upscaledb.h.

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

#define UPS_AUTO_RECOVERY   0x00010000

Flag for ups_env_open. This flag is non persistent.

Definition at line 1318 of file upscaledb.h.

#define UPS_CACHE_UNLIMITED   0x00040000

Flag for ups_env_open, ups_env_create. This flag is non persistent.

Definition at line 1326 of file upscaledb.h.

#define UPS_COMPRESSOR_LZF   3

selects lzf compression http://oldhome.schmorp.de/marc/liblzf.html

Definition at line 1822 of file upscaledb.h.

#define UPS_COMPRESSOR_NONE   0

helper macro for disabling compression

Definition at line 1804 of file upscaledb.h.

#define UPS_COMPRESSOR_SNAPPY   2

selects google snappy compression http://code.google.com/p/snappy

Definition at line 1816 of file upscaledb.h.

#define UPS_COMPRESSOR_UINT32_FOR   10

uint32 key compression (libfor - Frame Of Reference)

Definition at line 1838 of file upscaledb.h.

#define UPS_COMPRESSOR_UINT32_GROUPVARINT   7

Definition at line 1832 of file upscaledb.h.

#define UPS_COMPRESSOR_UINT32_MASKEDVBYTE   UPS_COMPRESSOR_UINT32_VARBYTE

Definition at line 1826 of file upscaledb.h.

#define UPS_COMPRESSOR_UINT32_SIMDCOMP   6

uint32 key compression (BP128)

Definition at line 1829 of file upscaledb.h.

#define UPS_COMPRESSOR_UINT32_SIMDFOR   11

uint32 key compression (SIMDFOR - Frame Of Reference w/ SIMD)

Definition at line 1841 of file upscaledb.h.

#define UPS_COMPRESSOR_UINT32_STREAMVBYTE   8

Definition at line 1835 of file upscaledb.h.

#define UPS_COMPRESSOR_UINT32_VARBYTE   5

uint32 key compression (varbyte)

Definition at line 1825 of file upscaledb.h.

#define UPS_COMPRESSOR_ZLIB   1

selects zlib compression http://www.zlib.net/

Definition at line 1810 of file upscaledb.h.

#define UPS_DIRECT_ACCESS   0x0040

Definition at line 1581 of file upscaledb.h.

#define UPS_DISABLE_MMAP   0x00000200

Flag for ups_env_open, ups_env_create. This flag is non persistent.

Definition at line 1294 of file upscaledb.h.

#define UPS_DISABLE_RECLAIM_INTERNAL   0x00400000

Definition at line 1336 of file upscaledb.h.

#define UPS_DISABLE_RECOVERY   0x00080000

Flag for ups_env_create, ups_env_open. This flag is non persistent.

Definition at line 1330 of file upscaledb.h.

#define UPS_DONT_CLEAR_LOG   2

Definition at line 1886 of file upscaledb.h.

#define UPS_DONT_FLUSH_TRANSACTIONS   0x04000000

Definition at line 1346 of file upscaledb.h.

#define UPS_DUPLICATE   0x0002

Flag for ups_db_insert and ups_cursor_insert

Definition at line 1566 of file upscaledb.h.

Referenced by copy_db(), main(), and run_demo().

#define UPS_DUPLICATE_INSERT_AFTER   0x0008

Flag for ups_cursor_insert

Definition at line 1572 of file upscaledb.h.

#define UPS_DUPLICATE_INSERT_BEFORE   0x0004

Flag for ups_cursor_insert

Definition at line 1569 of file upscaledb.h.

#define UPS_DUPLICATE_INSERT_FIRST   0x0010

FlagFlag for ups_cursor_insert

Definition at line 1575 of file upscaledb.h.

#define UPS_DUPLICATE_INSERT_LAST   0x0020

Flag for ups_cursor_insert

Definition at line 1578 of file upscaledb.h.

#define UPS_ENABLE_CRC32   0x02000000

Flag for ups_env_open, ups_env_create. This flag is non persistent.

Definition at line 1343 of file upscaledb.h.

#define UPS_ENABLE_DUPLICATE_KEYS   0x00004000

Flag for ups_env_create_db. This flag is persisted in the Database.

Definition at line 1309 of file upscaledb.h.

Referenced by main(), and run_demo().

#define UPS_ENABLE_DUPLICATES   UPS_ENABLE_DUPLICATE_KEYS

Definition at line 1311 of file upscaledb.h.

#define UPS_ENABLE_FSYNC   0x00000001

Flag for ups_env_open, ups_env_create. This flag is non persistent.

Definition at line 1269 of file upscaledb.h.

#define UPS_ENABLE_RECOVERY   UPS_ENABLE_TRANSACTIONS

Definition at line 1314 of file upscaledb.h.

#define UPS_ENABLE_TRANSACTIONS   0x00020000

Flag for ups_env_create, ups_env_open. This flag is non persistent.

Definition at line 1322 of file upscaledb.h.

Referenced by main().

#define UPS_ERASE_ALL_DUPLICATES   1

Definition at line 1619 of file upscaledb.h.

#define UPS_FLUSH_TRANSACTIONS_IMMEDIATELY   0x08000000

Flag for ups_env_open, ups_env_create. This flag is non persistent.

Definition at line 1350 of file upscaledb.h.

#define UPS_FORCE_DEEP_COPY   0x0100

Definition at line 1584 of file upscaledb.h.

#define UPS_FORCE_RECORDS_INLINE   0x00800000

Definition at line 1339 of file upscaledb.h.

#define UPS_HINT_APPEND   0x00080000

Definition at line 1587 of file upscaledb.h.

#define UPS_HINT_PREPEND   0x00100000

Definition at line 1590 of file upscaledb.h.

#define UPS_IGNORE_MISSING_CALLBACK   0x00000002

Definition at line 1272 of file upscaledb.h.

#define UPS_IN_MEMORY   0x00000080

Flag for ups_env_create. This flag is non persistent.

Definition at line 1288 of file upscaledb.h.

Referenced by main().

#define UPS_IS_REMOTE_INTERNAL   0x00200000

Definition at line 1333 of file upscaledb.h.

#define UPS_KEY_SIZE_UNLIMITED   ((uint16_t)-1)

Value for unlimited key sizes

Definition at line 1751 of file upscaledb.h.

#define UPS_OVERWRITE   0x0001

Flag for ups_db_insert and ups_cursor_insert

When specified with ups_db_insert and in case a key is specified which stores duplicates in the Database, the first duplicate record will be overwritten.

When used with ups_cursor_insert and assuming the same conditions, the duplicate currently referenced by the Cursor will be overwritten.

Definition at line 1563 of file upscaledb.h.

#define UPS_PARAM_CACHE_SIZE   0x00000100

Parameter name for ups_env_open, ups_env_create; sets the cache size

Definition at line 1691 of file upscaledb.h.

#define UPS_PARAM_CACHESIZE   UPS_PARAM_CACHE_SIZE

Definition at line 1693 of file upscaledb.h.

#define UPS_PARAM_CUSTOM_COMPARE_NAME   0x00000111

Parameter name for ups_env_create_db

Definition at line 1736 of file upscaledb.h.

#define UPS_PARAM_DATABASE_NAME   0x00000203

Retrieve the Database 'name' number of this ups_db_t Database within the current ups_env_t Environment.

Definition at line 1774 of file upscaledb.h.

#define UPS_PARAM_ENCRYPTION_KEY   0x00000106

Parameter name for ups_env_open, ups_env_create; sets the AES encryption key

Definition at line 1718 of file upscaledb.h.

#define UPS_PARAM_FILE_SIZE_LIMIT   0x00000109

Parameter name for ups_env_create, ups_env_open; sets a limit for the file size (in bytes)

Definition at line 1729 of file upscaledb.h.

#define UPS_PARAM_FILEMODE   0x00000201

Retrieves the filesystem file access mode as was specified at the time of ups_env_create/ups_env_open invocation.

Definition at line 1759 of file upscaledb.h.

#define UPS_PARAM_FILENAME   0x00000202

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

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

Definition at line 1768 of file upscaledb.h.

#define UPS_PARAM_FLAGS   0x00000200

Retrieves the Database/Environment flags as were specified at the time of ups_env_create/ups_env_open invocation.

Definition at line 1755 of file upscaledb.h.

#define UPS_PARAM_JOURNAL_COMPRESSION   0x00001000

Parameter name for ups_env_create, ups_env_open; enables compression for the journal.

Definition at line 1787 of file upscaledb.h.

#define UPS_PARAM_JOURNAL_SWITCH_THRESHOLD   0x00001

Parameter name for ups_env_open, ups_env_create; Journal files are switched whenever the number of new Transactions exceeds this threshold.

Definition at line 1687 of file upscaledb.h.

#define UPS_PARAM_KEY_COMPRESSION   0x00001002

Parameter name for ups_env_create_db, ups_env_open_db; enables compression for the records of a Database.

Definition at line 1801 of file upscaledb.h.

#define UPS_PARAM_KEY_SIZE   0x00000102

Parameter name for ups_env_create_db; sets the key size

Definition at line 1701 of file upscaledb.h.

#define UPS_PARAM_KEY_TYPE   0x00000104

Parameter name for ups_env_create_db; sets the key type

Definition at line 1710 of file upscaledb.h.

Referenced by main(), and run_demo().

#define UPS_PARAM_KEYSIZE   UPS_PARAM_KEY_SIZE

Definition at line 1703 of file upscaledb.h.

#define UPS_PARAM_LOG_DIRECTORY   0x00000105

Parameter name for ups_env_open, ups_env_create; sets the path of the log files

Definition at line 1714 of file upscaledb.h.

#define UPS_PARAM_MAX_DATABASES   0x00000103

Parameter name for ups_env_get_parameters; retrieves the number of maximum Databases

Definition at line 1707 of file upscaledb.h.

#define UPS_PARAM_MAX_KEYS_PER_PAGE   0x00000204

Retrieve the maximum number of keys per page; this number depends on the currently active page and key sizes. Can be an estimate if keys do not have constant sizes or if duplicate keys are used.

Definition at line 1781 of file upscaledb.h.

#define UPS_PARAM_NETWORK_TIMEOUT_SEC   0x00000107

Parameter name for ups_env_open, ups_env_create; sets the network timeout (in seconds)

Definition at line 1722 of file upscaledb.h.

#define UPS_PARAM_PAGE_SIZE   0x00000101

Parameter name for ups_env_create; sets the page size

Definition at line 1696 of file upscaledb.h.

#define UPS_PARAM_PAGESIZE   UPS_PARAM_PAGE_SIZE

Definition at line 1698 of file upscaledb.h.

#define UPS_PARAM_POSIX_FADVISE   0x00000110

Parameter name for ups_env_create, ups_env_open; sets the parameter for posix_fadvise()

Definition at line 1733 of file upscaledb.h.

#define UPS_PARAM_RECORD_COMPRESSION   0x00001001

Parameter name for ups_env_create_db, ups_env_open_db; enables compression for the records of a Database.

Definition at line 1794 of file upscaledb.h.

#define UPS_PARAM_RECORD_SIZE   0x00000108

Parameter name for ups_env_create_db; sets the key size

Definition at line 1725 of file upscaledb.h.

Referenced by main(), and run_demo().

#define UPS_PARAM_RECORD_TYPE   0x00000112

Parameter name for ups_env_create_db; sets the record type

Definition at line 1739 of file upscaledb.h.

Referenced by main().

#define UPS_POSIX_FADVICE_NORMAL   0

Value for UPS_PARAM_POSIX_FADVISE

Definition at line 1742 of file upscaledb.h.

#define UPS_POSIX_FADVICE_RANDOM   1

Value for UPS_PARAM_POSIX_FADVISE

Definition at line 1745 of file upscaledb.h.

#define UPS_READ_ONLY   0x00000004

Flag for ups_env_open, ups_env_open_db. This flag is non persistent.

Definition at line 1276 of file upscaledb.h.

#define UPS_RECORD_NUMBER   UPS_RECORD_NUMBER64

Definition at line 1297 of file upscaledb.h.

#define UPS_RECORD_NUMBER32   0x00001000

Flag for ups_env_create_db. This flag is persisted in the Database.

Definition at line 1301 of file upscaledb.h.

Referenced by main().

#define UPS_RECORD_NUMBER64   0x00002000

Flag for ups_env_create_db. This flag is persisted in the Database.

Definition at line 1305 of file upscaledb.h.

Referenced by main().

#define UPS_RECORD_SIZE_UNLIMITED   ((uint32_t)-1)

Value for unlimited record sizes

Definition at line 1748 of file upscaledb.h.

#define UPS_TXN_AUTO_ABORT   4

Automatically abort all open Transactions (the default)

Definition at line 1889 of file upscaledb.h.

#define UPS_TXN_AUTO_COMMIT   8

Automatically commit all open Transactions

Definition at line 1892 of file upscaledb.h.

Typedef Documentation

typedef int UPS_CALLCONV(* ups_compare_func_t) (ups_db_t *db, const uint8_t *lhs, uint32_t lhs_length, const uint8_t *rhs, uint32_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 1360 of file upscaledb.h.

Function Documentation

UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_close ( ups_db_t db,
uint32_t  flags 
)

Closes the Database

This function flushes the Database and then closes the file handle. It also free the memory resources allocated in the db handle.

If the flag UPS_AUTO_CLEANUP is specified, upscaledb automatically calls ups_cursor_close on all open Cursors. This invalidates the ups_cursor_t handle!

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

Parameters
dbA valid Database handle
flagsOptional flags for closing the Database. Possible values are:
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db is NULL
UPS_CURSOR_STILL_OPEN if not all Cursors of this Database were closed, and UPS_AUTO_CLEANUP was not specified
UPS_TXN_STILL_OPEN if this Database is modified by a currently active Txn

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_count ( ups_db_t db,
ups_txn_t txn,
uint32_t  flags,
uint64_t count 
)

Returns the number of keys stored in the Database

You can specify the UPS_SKIP_DUPLICATES if you do now want to include any duplicates in the count. This will also speed up the counting.

Parameters
dbA valid Database handle
txnA Txn handle, or NULL
flagsOptional flags:
countA pointer to a variable which will receive the calculated key count per page
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db or keycount is NULL or when flags contains an invalid flag set

Referenced by upscaledb::db::count().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_erase ( ups_db_t db,
ups_txn_t txn,
ups_key_t key,
uint32_t  flags 
)

Erases a Database item

This function erases a Database item. If the item key does not exist, UPS_KEY_NOT_FOUND is returned.

Note that ups_db_erase can not erase a single duplicate key. If the key has multiple duplicates, all duplicates of this key will be erased. Use ups_cursor_erase to erase a specific duplicate key.

Parameters
dbA valid Database handle
txnA Txn handle, or NULL
keyThe key to delete
flagsOptional flags for erasing; unused, set to 0
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db or key is NULL
UPS_WRITE_PROTECTED if you tried to erase a key from a read-only Database
UPS_KEY_NOT_FOUND if key was not found
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_find ( ups_db_t db,
ups_txn_t txn,
ups_key_t key,
ups_record_t record,
uint32_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 UPS_SUCCESS is returned. If the key is not found, the function returns UPS_KEY_NOT_FOUND.

A ups_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 upscaledb API calls using the same Txn (or, if Transactions are disabled, using the same Database). You can alter this behaviour by allocating the data pointer in the application and setting record.flags to UPS_RECORD_USER_ALLOC. Make sure that the allocated buffer is large enough.

ups_db_find can not search for duplicate keys. If key has multiple duplicates, only the first duplicate is returned.

If Transactions are enabled (see UPS_ENABLE_TRANSACTIONS) and txn is NULL then upscaledb will create a temporary Txn. When moving the Cursor, and the new key is currently modified in an active Txn (one that is not yet committed or aborted) then upscaledb will skip this key and move to the next/previous one. However if flags are 0 (and the Cursor is not moved), and key or rec is NOT NULL, then upscaledb will return error UPS_TXN_CONFLICT.

Parameters
dbA valid Database handle
txnA Txn handle, or NULL
keyThe key of the item
recordThe record of the item
flagsOptional flags for searching, which can be combined with bitwise OR. Possible flags are:
  • UPS_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.
  • UPS_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.
  • UPS_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.
  • UPS_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.
  • UPS_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.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db, key or record is NULL
UPS_KEY_NOT_FOUND if the key does not exist
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted
Remarks
When either or both UPS_FIND_LT_MATCH and/or UPS_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 ups_cursor_move(..., UPS_CURSOR_NEXT).
See also
UPS_RECORD_USER_ALLOC
UPS_KEY_USER_ALLOC
ups_record_t
ups_key_t

Referenced by upscaledb::db::find(), and main().

UPS_EXPORT ups_env_t* UPS_CALLCONV ups_db_get_env ( ups_db_t db)

Retrieves the Environment handle of a Database

Parameters
dbA valid Database handle
Returns
The Environment handle
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_get_parameters ( ups_db_t db,
ups_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:

  • UPS_PARAM_FLAGS returns the flags which were used to open or create this Database
  • UPS_PARAM_DATABASE_NAME returns the Database name
  • UPS_PARAM_KEY_TYPE returns the Btree key type
  • UPS_PARAM_KEY_SIZE returns the Btree key size or UPS_KEY_SIZE_UNLIMITED if there was no fixed key size specified.
  • UPS_PARAM_RECORD_TYPE returns the Btree record type
  • UPS_PARAM_RECORD_SIZE returns the record size, or UPS_RECORD_SIZE_UNLIMITED if there was no fixed record size specified.
  • UPS_PARAM_MAX_KEYS_PER_PAGE returns the maximum number of keys per page. This number is precise if the key size is fixed and duplicates are disabled; otherwise it's an estimate.
  • UPS_PARAM_RECORD_COMPRESSION Returns the selected algorithm for record compression, or 0 if compression is disabled
  • UPS_PARAM_KEY_COMPRESSION Returns the selected algorithm for key compression, or 0 if compression is disabled
Parameters
dbA valid Database handle
paramAn array of ups_parameter_t structures
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if the db pointer is NULL or param is NULL

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_insert ( ups_db_t db,
ups_txn_t txn,
ups_key_t key,
ups_record_t record,
uint32_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 UPS_DUPLICATE_KEY is returned.

If you wish to overwrite an existing entry specify the flag UPS_OVERWRITE.

If you wish to insert a duplicate key specify the flag UPS_DUPLICATE. (Note that the Database has to be created with UPS_ENABLE_DUPLICATE_KEYS in order to use duplicate keys.) The duplicate key is inserted after all other duplicate keys (see UPS_DUPLICATE_INSERT_LAST).

Record Number Databases (created with UPS_RECORD_NUMBER32 or UPS_RECORD_NUMBER64) expect either an empty key (with a size of 0 and data pointing to NULL), or a user-supplied key (with key.flag UPS_KEY_USER_ALLOC and a valid data pointer). If key.size is 0 and key.data is NULL, upscaledb will temporarily allocate memory for key->data, which will then point to an 4-byte (or 8-byte) unsigned integer.

Parameters
dbA valid Database handle
txnA Txn handle, or NULL
keyThe key of the new item
recordThe record of the new item
flagsOptional flags for inserting. Possible flags are:
  • UPS_OVERWRITE. If the key already exists, the record is overwritten. Otherwise, the key is inserted. Flag is not allowed in combination with UPS_DUPLICATE.
  • UPS_DUPLICATE. If the key already exists, a duplicate key is inserted. The key is inserted before the already existing key. Flag is not allowed in combination with UPS_OVERWRITE.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db, key or record is NULL
UPS_INV_PARAMETER if the Database is a Record Number Database and the key is invalid (see above)
UPS_INV_PARAMETER if the flags UPS_OVERWRITE and UPS_DUPLICATE were specified, or if UPS_DUPLICATE was specified, but the Database was not created with flag UPS_ENABLE_DUPLICATE_KEYS.
UPS_WRITE_PROTECTED if you tried to insert a key in a read-only Database
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted
UPS_INV_KEY_SIZE if the key size is larger than the UPS_PARAMETER_KEY_SIZE parameter specified for ups_env_create_db OR if the key's size is greater than the Btree key size (see UPS_PARAM_KEY_SIZE).
UPS_INV_RECORD_SIZE if the record size is different from the one specified with UPS_PARAM_RECORD_SIZE

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_set_compare_func ( ups_db_t db,
ups_compare_func_t  foo 
)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_register_compare ( const char *  name,
ups_compare_func_t  func 
)

Globally registers a function to compare custom keys

Supplying a comparison function is only allowed for the key type UPS_TYPE_CUSTOM; see the documentation of

See also
ups_env_create_db for more information.

When creating a database (

See also
ups_env_create_db), the name of the comparison function has to be specified as an extended parameter (
UPS_PARAM_CUSTOM_COMPARE_NAME). It is valid to register a compare function multiple times under the same name.

!!! The compare functions should be registered PRIOR to opening or creating Environments!

Parameters
nameA (case-insensitive) name of the callback function
funcA pointer to the compare function
Returns
UPS_SUCCESS