upscaledb  2.2.1
Macros | Functions
upscaledb Cursor Functions

Macros

#define UPS_CURSOR_FIRST   0x0001
 
#define UPS_CURSOR_LAST   0x0002
 
#define UPS_CURSOR_NEXT   0x0004
 
#define UPS_CURSOR_PREVIOUS   0x0008
 
#define UPS_SKIP_DUPLICATES   0x0010
 
#define UPS_ONLY_DUPLICATES   0x0020
 
#define UPS_FIND_EQ_MATCH   0x4000
 
#define UPS_FIND_LT_MATCH   0x1000
 
#define UPS_FIND_GT_MATCH   0x2000
 
#define UPS_FIND_LEQ_MATCH   (UPS_FIND_LT_MATCH | UPS_FIND_EQ_MATCH)
 
#define UPS_FIND_GEQ_MATCH   (UPS_FIND_GT_MATCH | UPS_FIND_EQ_MATCH)
 
#define UPS_FIND_NEAR_MATCH
 

Functions

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_create (ups_cursor_t **cursor, ups_db_t *db, ups_txn_t *txn, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_clone (ups_cursor_t *src, ups_cursor_t **dest)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_move (ups_cursor_t *cursor, ups_key_t *key, ups_record_t *record, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_overwrite (ups_cursor_t *cursor, ups_record_t *record, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_find (ups_cursor_t *cursor, ups_key_t *key, ups_record_t *record, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_insert (ups_cursor_t *cursor, ups_key_t *key, ups_record_t *record, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_erase (ups_cursor_t *cursor, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_duplicate_count (ups_cursor_t *cursor, uint32_t *count, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_duplicate_position (ups_cursor_t *cursor, uint32_t *position)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_record_size (ups_cursor_t *cursor, uint32_t *size)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_close (ups_cursor_t *cursor)
 

Detailed Description

Macro Definition Documentation

#define UPS_CURSOR_FIRST   0x0001

Flag for ups_cursor_move

Definition at line 2045 of file upscaledb.h.

Referenced by copy_db(), main(), and upscaledb::cursor::move_first().

#define UPS_CURSOR_LAST   0x0002

Flag for ups_cursor_move

Definition at line 2048 of file upscaledb.h.

Referenced by upscaledb::cursor::move_last().

#define UPS_CURSOR_NEXT   0x0004

Flag for ups_cursor_move

Definition at line 2051 of file upscaledb.h.

Referenced by copy_db(), main(), upscaledb::cursor::move_next(), and run_demo().

#define UPS_CURSOR_PREVIOUS   0x0008

Flag for ups_cursor_move

Definition at line 2054 of file upscaledb.h.

Referenced by upscaledb::cursor::move_previous().

#define UPS_FIND_EQ_MATCH   0x4000

Definition at line 2182 of file upscaledb.h.

#define UPS_FIND_GEQ_MATCH   (UPS_FIND_GT_MATCH | UPS_FIND_EQ_MATCH)

Cursor 'find' flag 'Greater or Equal': return the nearest match above the given key, when an exact match does not exist.

May be combined with UPS_FIND_LEQ_MATCH to accept any 'near' key, or you can use the UPS_FIND_NEAR_MATCH constant as a shorthand for that.

Definition at line 2212 of file upscaledb.h.

#define UPS_FIND_GT_MATCH   0x2000

Cursor 'find' flag 'Greater Than': return the nearest match above the given key, whether an exact match exists or not.

Definition at line 2194 of file upscaledb.h.

#define UPS_FIND_LEQ_MATCH   (UPS_FIND_LT_MATCH | UPS_FIND_EQ_MATCH)

Cursor 'find' flag 'Less or EQual': return the nearest match below the given key, when an exact match does not exist.

May be combined with UPS_FIND_GEQ_MATCH to accept any 'near' key, or you can use the UPS_FIND_NEAR_MATCH constant as a shorthand for that.

Definition at line 2203 of file upscaledb.h.

#define UPS_FIND_LT_MATCH   0x1000

Cursor 'find' flag 'Less Than': return the nearest match below the given key, whether an exact match exists or not.

Definition at line 2188 of file upscaledb.h.

#define UPS_FIND_NEAR_MATCH
Value:
#define UPS_FIND_GT_MATCH
Definition: upscaledb.h:2194
#define UPS_FIND_LT_MATCH
Definition: upscaledb.h:2188
#define UPS_FIND_EQ_MATCH
Definition: upscaledb.h:2182

Cursor 'find' flag 'Any Near Or Equal': return a match directly below or above the given key, when an exact match does not exist.

Be aware that the returned match will either match the key exactly or is either the first key available above or below the given key when an exact match could not be found; 'find' does NOT spend any effort, in the sense of determining which of both is the 'nearest' to the given key, when both a key above and a key below the one given exist; 'find' will simply return the first of both found. As such, this flag is the simplest possible combination of the combined UPS_FIND_LEQ_MATCH and UPS_FIND_GEQ_MATCH flags.

Definition at line 2227 of file upscaledb.h.

#define UPS_ONLY_DUPLICATES   0x0020

Flag for ups_cursor_move

Definition at line 2060 of file upscaledb.h.

Referenced by main(), and run_demo().

#define UPS_SKIP_DUPLICATES   0x0010

Flag for ups_cursor_move and ups_db_count()

Definition at line 2057 of file upscaledb.h.

Function Documentation

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_clone ( ups_cursor_t src,
ups_cursor_t **  dest 
)

Clones a Database Cursor

Clones an existing Cursor. The new Cursor will point to exactly the same item as the old Cursor. If the old Cursor did not point to any item, so will the new Cursor.

If the old Cursor is bound to a Txn, then the new Cursor will also be bound to this Txn.

Parameters
srcThe existing Cursor
destA pointer to a pointer, which is allocated for the cloned Cursor handle
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if src or dest is NULL
UPS_OUT_OF_MEMORY if the new structure could not be allocated

Referenced by upscaledb::cursor::clone().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_close ( ups_cursor_t cursor)

Closes a Database Cursor

Closes a Cursor and frees allocated memory. All Cursors should be closed before closing the Database (see ups_db_close).

Parameters
cursorA valid Cursor handle
Returns
UPS_SUCCESS upon success
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_INV_PARAMETER if cursor is NULL
See also
ups_db_close

Referenced by upscaledb::cursor::close(), copy_db(), and main().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_create ( ups_cursor_t **  cursor,
ups_db_t db,
ups_txn_t txn,
uint32_t  flags 
)

Creates a Database Cursor

Creates a new Database Cursor. Cursors can be used to traverse the Database from start to end or vice versa. Cursors can also be used to insert, delete or search Database items.

A newly created Cursor does not point to any item in the Database.

The application should close all Cursors of a Database before closing the Database.

If Transactions are enabled (UPS_ENABLE_TRANSACTIONS), but txn is NULL, then each Cursor operation (i.e. ups_cursor_insert, ups_cursor_find etc) will create its own, temporary Txn only for the lifetime of this operation and not for the lifetime of the whole Cursor!

Parameters
dbA valid Database handle
txnA Txn handle, or NULL
flagsOptional flags for creating the Cursor; unused, set to 0
cursorA pointer to a pointer which is allocated for the new Cursor handle
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db or cursor is NULL
UPS_OUT_OF_MEMORY if the new structure could not be allocated

Referenced by copy_db(), upscaledb::cursor::create(), and main().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_erase ( ups_cursor_t cursor,
uint32_t  flags 
)

Erases the current key

Erases a key from the Database. If the erase was successful, the Cursor is invalidated and does no longer point to any item. In case of an error, the Cursor is not modified.

If the Database was opened with the flag UPS_ENABLE_DUPLICATE_KEYS, this function erases only the duplicate item to which the Cursor refers.

Parameters
cursorA valid Cursor handle
flagsUnused, set to 0
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if cursor is NULL
UPS_WRITE_PROTECTED if you tried to erase a key from a read-only Database
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted

Referenced by upscaledb::cursor::erase().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_find ( ups_cursor_t cursor,
ups_key_t key,
ups_record_t record,
uint32_t  flags 
)

Searches with a key and points the Cursor to the key found, retrieves the located record

Searches for an item in the Database and points the Cursor to this item. If the item could not be found, the Cursor is not modified.

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

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_*): key->data will point to temporary data upon return. This pointer will be invalidated by subsequent upscaledb API calls using the same Txn (or the same Database, if Transactions are disabled). See UPS_KEY_USER_ALLOC on how to change this behaviour.

Further note that the key structure must be non-const at all times as its internal flag bits may be written to.

Parameters
cursorA valid Cursor handle
keyA pointer to a ups_key_t structure. If this pointer is not NULL, the key of the new item is returned. Note that key->data will point to temporary data. This pointer will be invalidated by subsequent upscaledb API calls. See UPS_KEY_USER_ALLOC on how to change this behaviour.
recordOptional pointer to a ups_record_t structure. If this pointer is not NULL, the record of the new item is returned. Note that record->data will point to temporary data. This pointer will be invalidated by subsequent upscaledb API calls. See UPS_RECORD_USER_ALLOC on how to change this behaviour.
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.

Remark For Approximate Matching the returned match will either match the key exactly or is either the first key available above or below the given key when an exact match could not be found; 'find' does NOT spend any effort, in the sense of determining which of both is the 'nearest' to the given key, when both a key above and a key below the one given exist; 'find' will simply return the first of both found. As such, this flag is the simplest possible combination of the combined UPS_FIND_LEQ_MATCH and UPS_FIND_GEQ_MATCH flags.

Note that these flags may be bitwise OR-ed to form functional combinations.

UPS_FIND_LEQ_MATCH, UPS_FIND_GEQ_MATCH and UPS_FIND_LT_MATCH, UPS_FIND_GT_MATCH

Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db, key or record is NULL
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_KEY_NOT_FOUND if no suitable key (record) exists
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted
See also
UPS_KEY_USER_ALLOC
ups_key_t
UPS_RECORD_USER_ALLOC
ups_record_t

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

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_duplicate_count ( ups_cursor_t cursor,
uint32_t count,
uint32_t  flags 
)

Returns the number of duplicate keys

Returns the number of duplicate keys of the item to which the Cursor currently refers. Returns 1 if the key has no duplicates.

Parameters
cursorA valid Cursor handle
countReturns the number of duplicate keys
flagsOptional flags; unused, set to 0.
Returns
UPS_SUCCESS upon success
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_INV_PARAMETER if cursor or count is NULL
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted

Referenced by upscaledb::cursor::get_duplicate_count().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_duplicate_position ( ups_cursor_t cursor,
uint32_t position 
)

Returns the current cursor position in the duplicate list

Returns the position in the duplicate list of the current key. The position is 0-based.

Parameters
cursorA valid Cursor handle
positionReturns the duplicate position
Returns
UPS_SUCCESS upon success
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_INV_PARAMETER if cursor or position is NULL
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_record_size ( ups_cursor_t cursor,
uint32_t size 
)

Returns the record size of the current key

Returns the record size of the item to which the Cursor currently refers.

Parameters
cursorA valid Cursor handle
sizeReturns the record size, in bytes
Returns
UPS_SUCCESS upon success
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_INV_PARAMETER if cursor or size is NULL

Referenced by upscaledb::cursor::get_record_size().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_insert ( ups_cursor_t cursor,
ups_key_t key,
ups_record_t record,
uint32_t  flags 
)

Inserts a Database item and points the Cursor to the inserted 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. The use of this flag is not allowed in combination with UPS_DUPLICATE.

If you wish to insert a duplicate key specify the flag UPS_DUPLICATE. (In order to use duplicate keys, the Database has to be created with UPS_ENABLE_DUPLICATE_KEYS.) By default, the duplicate key is inserted after all other duplicate keys (see UPS_DUPLICATE_INSERT_LAST). This behaviour can be overwritten by specifying UPS_DUPLICATE_INSERT_FIRST, UPS_DUPLICATE_INSERT_BEFORE or UPS_DUPLICATE_INSERT_AFTER.

Specify the flag UPS_HINT_APPEND if you insert sequential data and the current key is greater than any other key in this Database. In this case upscaledb will optimize the insert algorithm. upscaledb will verify that this key is the greatest; if not, it will perform a normal insert. This flag is the default for Record Number Databases.

Specify the flag UPS_HINT_PREPEND if you insert sequential data and the current key is lower than any other key in this Database. In this case upscaledb will optimize the insert algorithm. upscaledb will verify that this key is the lowest; if not, it will perform a normal insert.

After inserting, the Cursor will point to the new item. If inserting the item failed, the Cursor is not modified.

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
cursorA valid Cursor handle
keyA valid key structure
recordA valid record structure
flagsOptional flags for inserting the item, combined with bitwise OR. Possible flags are:
  • UPS_OVERWRITE. If the key already exists, the record is overwritten. Otherwise, the key is inserted. Not allowed in combination with UPS_DUPLICATE.
  • UPS_DUPLICATE. If the key already exists, a duplicate key is inserted. Same as UPS_DUPLICATE_INSERT_LAST. Not allowed in combination with UPS_DUPLICATE.
  • UPS_DUPLICATE_INSERT_BEFORE. If the key already exists, a duplicate key is inserted before the duplicate pointed to by the Cursor
  • UPS_DUPLICATE_INSERT_AFTER. If the key already exists, a duplicate key is inserted after the duplicate pointed to by the Cursor
  • UPS_DUPLICATE_INSERT_FIRST. If the key already exists, a duplicate key is inserted as the first duplicate of the current key
  • UPS_DUPLICATE_INSERT_LAST. If the key already exists, a duplicate key is inserted as the last duplicate of the current key
  • UPS_HINT_APPEND. Hints the upscaledb engine that the current key will compare as larger than any key already existing in the Database. The upscaledb engine will verify this postulation and when found not to be true, will revert to a regular insert operation as if this flag was not specified. The incurred cost then is only one additional key comparison. Mutually exclusive with flag UPS_HINT_PREPEND. This is the default for Record Number Databases.
  • UPS_HINT_PREPEND. Hints the upscaledb engine that the current key will compare as lower than any key already existing in the Database. The upscaledb engine will verify this postulation and when found not to be true, will revert to a regular insert operation as if this flag was not specified. The incurred cost then is only one additional key comparison. Mutually exclusive with flag UPS_HINT_APPEND.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if 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 to a read-only Database.
UPS_INV_KEY_SIZE if the key size is different from the one specified with UPS_PARAM_KEY_SIZE
UPS_INV_RECORD_SIZE if the record size is different from the one specified with UPS_PARAM_RECORD_SIZE
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted

Referenced by upscaledb::cursor::insert().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_move ( ups_cursor_t cursor,
ups_key_t key,
ups_record_t record,
uint32_t  flags 
)

Moves the Cursor

Moves the Cursor. Use the flags to specify the direction. After the move, key and record of the item are returned, if key and/or record are valid pointers.

If the direction is not specified, the Cursor will not move. Do not specify a direction if you want to fetch the key and/or record of the current item.

If Transactions are enabled (see UPS_ENABLE_TRANSACTIONS), and the Cursor moves next or previous to a key which is currently modified in an active Txn (one that is not yet committed or aborted), then upscaledb will skip the modified key. (This behavior is different from i.e. ups_cursor_find, which would return the error UPS_TXN_CONFLICT).

If a key has duplicates and any of the duplicates is currently modified in another active Txn, then ALL duplicate keys are skipped when moving to the next or previous key.

If the first (UPS_CURSOR_FIRST) or last (UPS_CURSOR_LAST) key is requested, and the current key (or any of its duplicates) is currently modified in an active Txn, then UPS_TXN_CONFLICT is returned.

If this Cursor is nil (i.e. because it was not yet used or the Cursor's item was erased) then the flag UPS_CURSOR_NEXT (or UPS_CURSOR_PREVIOUS) will be identical to UPS_CURSOR_FIRST (or UPS_CURSOR_LAST).

Parameters
cursorA valid Cursor handle
keyAn optional pointer to a ups_key_t structure. If this pointer is not NULL, the key of the new item is returned. Note that key->data will point to temporary data. This pointer will be invalidated by subsequent upscaledb API calls. See UPS_KEY_USER_ALLOC on how to change this behaviour.
recordAn optional pointer to a ups_record_t structure. If this pointer is not NULL, the record of the new item is returned. Note that record->data will point to temporary data. This pointer will be invalidated by subsequent upscaledb API calls. See UPS_RECORD_USER_ALLOC on how to change this behaviour.
flagsThe flags for this operation. They are used to specify the direction for the "move". If you do not specify a direction, the Cursor will remain on the current position.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if cursor is NULL, or if an invalid combination of flags was specified
UPS_CURSOR_IS_NIL if the Cursor does not point to an item, but key and/or record were requested
UPS_KEY_NOT_FOUND if cursor points to the first (or last) item, and a move to the previous (or next) item was requested
UPS_TXN_CONFLICT if UPS_CURSOR_FIRST or UPS_CURSOR_LAST is specified but the first (or last) key or any of its duplicates is currently modified in an active Txn
See also
UPS_RECORD_USER_ALLOC
UPS_KEY_USER_ALLOC
ups_record_t
ups_key_t

Referenced by copy_db(), main(), and upscaledb::cursor::move().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_overwrite ( ups_cursor_t cursor,
ups_record_t record,
uint32_t  flags 
)

Overwrites the current record

This function overwrites the record of the current item.

Parameters
cursorA valid Cursor handle
recordA valid record structure
flagsOptional flags for overwriting the item; unused, set to 0
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if cursor or record is NULL
UPS_CURSOR_IS_NIL if the Cursor does not point to an item
UPS_TXN_CONFLICT if the same key was inserted in another Txn which was not yet committed or aborted

Referenced by upscaledb::cursor::overwrite().