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:

(UPS_FIND_LT_MATCH | UPS_FIND_GT_MATCH \

| UPS_FIND_EQ_MATCH)

UPS_FIND_GT_MATCH

#define UPS_FIND_GT_MATCH

Definition: upscaledb.h:2194

UPS_FIND_LT_MATCH

#define UPS_FIND_LT_MATCH

Definition: upscaledb.h:2188

UPS_FIND_EQ_MATCH

#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

src	The existing Cursor
dest	A 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

cursor A 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

db	A valid Database handle
txn	A Txn handle, or NULL
flags	Optional flags for creating the Cursor; unused, set to 0
cursor	A 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

cursor	A valid Cursor handle
flags	Unused, 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

cursor	A valid Cursor handle
key	A 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.
record	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.
flags	Optional 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

cursor	A valid Cursor handle
count	Returns the number of duplicate keys
flags	Optional 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

cursor	A valid Cursor handle
position	Returns 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

cursor	A valid Cursor handle
size	Returns 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

cursor	A valid Cursor handle
key	A valid key structure
record	A valid record structure
flags	Optional 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

cursor	A valid Cursor handle
key	An 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.
record	An 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.
flags	The 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. UPS_CURSOR_FIRST positions the Cursor on the first item in the Database UPS_CURSOR_LAST positions the Cursor on the last item in the Database UPS_CURSOR_NEXT positions the Cursor on the next item in the Database; if the Cursor does not point to any item, the function behaves as if direction was UPS_CURSOR_FIRST. UPS_CURSOR_PREVIOUS positions the Cursor on the previous item in the Database; if the Cursor does not point to any item, the function behaves as if direction was UPS_CURSOR_LAST. UPS_SKIP_DUPLICATES skips duplicate keys of the current key. Not allowed in combination with UPS_ONLY_DUPLICATES. UPS_ONLY_DUPLICATES only move through duplicate keys of the current key. Not allowed in combination with UPS_SKIP_DUPLICATES.

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

cursor	A valid Cursor handle
record	A valid record structure
flags	Optional 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().

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation