hamsterdb Embedded Database  2.1.7
Macros | Functions
hamsterdb Cursor Functions

Macros

#define HAM_CURSOR_FIRST   0x0001
 
#define HAM_CURSOR_LAST   0x0002
 
#define HAM_CURSOR_NEXT   0x0004
 
#define HAM_CURSOR_PREVIOUS   0x0008
 
#define HAM_SKIP_DUPLICATES   0x0010
 
#define HAM_ONLY_DUPLICATES   0x0020
 
#define HAM_FIND_EXACT_MATCH   0x4000
 
#define HAM_FIND_LT_MATCH   0x1000
 
#define HAM_FIND_GT_MATCH   0x2000
 
#define HAM_FIND_LEQ_MATCH   (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
 
#define HAM_FIND_GEQ_MATCH   (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
 
#define HAM_FIND_NEAR_MATCH
 

Functions

HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_create (ham_cursor_t **cursor, ham_db_t *db, ham_txn_t *txn, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_clone (ham_cursor_t *src, ham_cursor_t **dest)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_move (ham_cursor_t *cursor, ham_key_t *key, ham_record_t *record, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_overwrite (ham_cursor_t *cursor, ham_record_t *record, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_find (ham_cursor_t *cursor, ham_key_t *key, ham_record_t *record, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_insert (ham_cursor_t *cursor, ham_key_t *key, ham_record_t *record, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_erase (ham_cursor_t *cursor, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_get_duplicate_count (ham_cursor_t *cursor, ham_u32_t *count, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_get_record_size (ham_cursor_t *cursor, ham_u64_t *size)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_close (ham_cursor_t *cursor)
 

Detailed Description

Macro Definition Documentation

#define HAM_CURSOR_FIRST   0x0001

Flag for ham_cursor_move

Definition at line 1996 of file hamsterdb.h.

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

#define HAM_CURSOR_LAST   0x0002

Flag for ham_cursor_move

Definition at line 1999 of file hamsterdb.h.

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

#define HAM_CURSOR_NEXT   0x0004

Flag for ham_cursor_move

Definition at line 2002 of file hamsterdb.h.

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

#define HAM_CURSOR_PREVIOUS   0x0008

Flag for ham_cursor_move

Definition at line 2005 of file hamsterdb.h.

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

#define HAM_FIND_EXACT_MATCH   0x4000

Cursor 'find' flag: return an exact match (default).

Note: For backwards compatibility, you can specify zero (0) as an alternative when this flag is used alone.

Approx. matching is disabled if Transactions are enabled.

Definition at line 2199 of file hamsterdb.h.

#define HAM_FIND_GEQ_MATCH   (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_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 HAM_FIND_LEQ_MATCH to accept any 'near' key, or you can use the HAM_FIND_NEAR_MATCH constant as a shorthand for that.

Approx. matching is disabled if Transactions are enabled.

Definition at line 2237 of file hamsterdb.h.

#define HAM_FIND_GT_MATCH   0x2000

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

Approx. matching is disabled if Transactions are enabled.

Definition at line 2215 of file hamsterdb.h.

#define HAM_FIND_LEQ_MATCH   (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_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 HAM_FIND_GEQ_MATCH to accept any 'near' key, or you can use the HAM_FIND_NEAR_MATCH constant as a shorthand for that.

Approx. matching is disabled if Transactions are enabled.

Definition at line 2226 of file hamsterdb.h.

#define HAM_FIND_LT_MATCH   0x1000

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

Approx. matching is disabled if Transactions are enabled.

Definition at line 2207 of file hamsterdb.h.

#define HAM_FIND_NEAR_MATCH
Value:

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 HAM_FIND_LEQ_MATCH and HAM_FIND_GEQ_MATCH flags.

Approx. matching is disabled if Transactions are enabled.

Definition at line 2254 of file hamsterdb.h.

#define HAM_ONLY_DUPLICATES   0x0020

Flag for ham_cursor_move

Definition at line 2011 of file hamsterdb.h.

Referenced by main(), and run_demo().

#define HAM_SKIP_DUPLICATES   0x0010

Flag for ham_cursor_move and ham_db_get_key_count

Definition at line 2008 of file hamsterdb.h.

Function Documentation

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_clone ( ham_cursor_t src,
ham_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 Transaction, then the new Cursor will also be bound to this Transaction.

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

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_close ( ham_cursor_t cursor)

Closes a Database Cursor

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

Parameters
cursorA valid Cursor handle
Returns
HAM_SUCCESS upon success
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
HAM_INV_PARAMETER if cursor is NULL
See Also
ham_db_close

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_create ( ham_cursor_t **  cursor,
ham_db_t db,
ham_txn_t txn,
ham_u32_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 (HAM_ENABLE_TRANSACTIONS), but txn is NULL, then each Cursor operation (i.e. ham_cursor_insert, ham_cursor_find etc) will create its own, temporary Transaction only for the lifetime of this operation and not for the lifetime of the whole Cursor!

Parameters
dbA valid Database handle
txnA Transaction 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
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or cursor is NULL
HAM_OUT_OF_MEMORY if the new structure could not be allocated

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_erase ( ham_cursor_t cursor,
ham_u32_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 HAM_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
HAM_SUCCESS upon success
HAM_INV_PARAMETER if cursor is NULL
HAM_WRITE_PROTECTED if you tried to erase a key from a read-only Database
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_find ( ham_cursor_t cursor,
ham_key_t key,
ham_record_t record,
ham_u32_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 ham_cursor_find can not search for duplicate keys. If key has multiple duplicates, only the first duplicate is returned.

When specifying HAM_DIRECT_ACCESS, the data pointer will point directly to the record that is stored in hamsterdb; the data can be modified, but the pointer must not be reallocated or freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases and not if Transactions are enabled.

You can read only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will read record->partial_size bytes of the record data at offset record->partial_offset. If necessary, the record data will be limited to the original record size. The number of actually read bytes is returned in record->partial_size. The original size of the record is stored in record->size.

HAM_PARTIAL is not allowed if record->size is <= 8 or if Transactions are enabled. In such a case, HAM_INV_PARAMETER is returned.

When either or both HAM_FIND_LT_MATCH and/or HAM_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 ham_cursor_move(...,HAM_CURSOR_*): key->data will point to temporary data upon return. This pointer will be invalidated by subsequent hamsterdb API calls using the same Transaction (or the same Database, if Transactions are disabled). See HAM_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. This is done for your benefit, as you may pass the returned key structure to ham_key_get_approximate_match_type() to retrieve additional info about the precise nature of the returned key: the sign value produced by ham_key_get_approximate_match_type() tells you which kind of match (equal, less than, greater than) occurred. This is very useful to discern between the various possible successful answers produced by the combinations of HAM_FIND_LT_MATCH, HAM_FIND_GT_MATCH and/or HAM_FIND_EXACT_MATCH.

Parameters
cursorA valid Cursor handle
keyA pointer to a ham_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 hamsterdb API calls. See HAM_KEY_USER_ALLOC on how to change this behaviour.
recordOptional pointer to a ham_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 hamsterdb API calls. See HAM_RECORD_USER_ALLOC on how to change this behaviour.
flagsOptional flags for searching, which can be combined with bitwise OR. Possible flags are:
  • HAM_FIND_EXACT_MATCH (default). If the key exists, the cursor is adjusted to reference the record. Otherwise, an error is returned. Note that for backwards compatibility the value zero (0) can specified as an alternative when this option is not mixed with any of the others in this list.
  • HAM_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.
  • HAM_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.
  • HAM_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.
  • HAM_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.
  • HAM_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.
  • HAM_DIRECT_ACCESS Only for In-Memory Databases and not if Transactions are enabled! Returns a direct pointer to the data blob stored by the hamsterdb engine. This pointer must not be resized or freed, but the data in this memory can be modified.

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 HAM_FIND_LEQ_MATCH and HAM_FIND_GEQ_MATCH flags.

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

HAM_FIND_LEQ_MATCH, HAM_FIND_GEQ_MATCH and HAM_FIND_NEAR_MATCH are themselves shorthands created using the bitwise OR operation like this:

Returns
HAM_SUCCESS upon success. Mind the remarks about the key flags being adjusted and the useful invocation of ham_key_get_approximate_match_type() afterwards.
HAM_INV_PARAMETER if db, key or record is NULL
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
HAM_KEY_NOT_FOUND if no suitable key (record) exists
HAM_INV_PARAMETER if HAM_DIRECT_ACCESS is specified, but the Database is not an In-Memory Database.
HAM_INV_PARAMETER if HAM_DIRECT_ACCESS and HAM_ENABLE_TRANSACTIONS were both specified.
HAM_INV_PARAMETER if HAM_PARTIAL is set but record size is <= 8 or Transactions are enabled
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted
See Also
HAM_KEY_USER_ALLOC
ham_key_t
HAM_RECORD_USER_ALLOC
ham_record_t

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_get_duplicate_count ( ham_cursor_t cursor,
ham_u32_t count,
ham_u32_t  flags 
)

Gets 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
HAM_SUCCESS upon success
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
HAM_INV_PARAMETER if cursor or count is NULL
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_get_record_size ( ham_cursor_t cursor,
ham_u64_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
HAM_SUCCESS upon success
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
HAM_INV_PARAMETER if cursor or size is NULL

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_insert ( ham_cursor_t cursor,
ham_key_t key,
ham_record_t record,
ham_u32_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 HAM_DUPLICATE_KEY is returned.

If you wish to overwrite an existing entry specify the flag HAM_OVERWRITE. The use of this flag is not allowed in combination with HAM_DUPLICATE.

If you wish to insert a duplicate key specify the flag HAM_DUPLICATE. (In order to use duplicate keys, the Database has to be created with HAM_ENABLE_DUPLICATE_KEYS.) By default, the duplicate key is inserted after all other duplicate keys (see HAM_DUPLICATE_INSERT_LAST). This behaviour can be overwritten by specifying HAM_DUPLICATE_INSERT_FIRST, HAM_DUPLICATE_INSERT_BEFORE or HAM_DUPLICATE_INSERT_AFTER.

You can write only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will write partial_size bytes of the record data at offset partial_offset. If necessary, the record data will grow. Gaps will be filled with null-bytes, if the record did not yet exist.

HAM_PARTIAL is not allowed if record->size is <= 8 or if Transactions are enabled. In such a case, HAM_INV_PARAMETER is returned.

Specify the flag HAM_HINT_APPEND if you insert sequential data and the current key is greater than any other key in this Database. In this case hamsterdb will optimize the insert algorithm. hamsterdb 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 HAM_HINT_PREPEND if you insert sequential data and the current key is lower than any other key in this Database. In this case hamsterdb will optimize the insert algorithm. hamsterdb 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 HAM_RECORD_NUMBER) expect either an empty key (with a size of 0 and data pointing to NULL), or a user-supplied key (with key.flag HAM_KEY_USER_ALLOC, a size of 8 and a valid data pointer). If key.size is 0 and key.data is NULL, hamsterdb will temporarily allocate memory for key->data, which will then point to an 8-byte unsigned integer in host-endian.

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:
  • HAM_OVERWRITE. If the key already exists, the record is overwritten. Otherwise, the key is inserted. Not allowed in combination with HAM_DUPLICATE.
  • HAM_DUPLICATE. If the key already exists, a duplicate key is inserted. Same as HAM_DUPLICATE_INSERT_LAST. Not allowed in combination with HAM_DUPLICATE.
  • HAM_DUPLICATE_INSERT_BEFORE. If the key already exists, a duplicate key is inserted before the duplicate pointed to by the Cursor. Not allowed if duplicate sorting is enabled.
  • HAM_DUPLICATE_INSERT_AFTER. If the key already exists, a duplicate key is inserted after the duplicate pointed to by the Cursor. Not allowed if duplicate sorting is enabled.
  • HAM_DUPLICATE_INSERT_FIRST. If the key already exists, a duplicate key is inserted as the first duplicate of the current key. Not allowed if duplicate sorting is enabled.
  • HAM_DUPLICATE_INSERT_LAST. If the key already exists, a duplicate key is inserted as the last duplicate of the current key. Not allowed if duplicate sorting is enabled.
  • HAM_HINT_APPEND. Hints the hamsterdb engine that the current key will compare as larger than any key already existing in the Database. The hamsterdb 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 HAM_HINT_PREPEND. This is the default for Record Number Databases.
  • HAM_HINT_PREPEND. Hints the hamsterdb engine that the current key will compare as lower than any key already existing in the Database. The hamsterdb 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 HAM_HINT_APPEND.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if key or record is NULL
HAM_INV_PARAMETER if the Database is a Record Number Database and the key is invalid (see above)
HAM_INV_PARAMETER if HAM_PARTIAL is set but record size is <= 8 or Transactions are enabled
HAM_INV_PARAMETER if the flags HAM_OVERWRITE and HAM_DUPLICATE were specified, or if HAM_DUPLICATE was specified, but the Database was not created with flag HAM_ENABLE_DUPLICATE_KEYS.
HAM_WRITE_PROTECTED if you tried to insert a key to a read-only Database.
HAM_INV_KEY_SIZE if the key size is different from the one specified with HAM_PARAM_KEY_SIZE
HAM_INV_RECORD_SIZE if the record size is different from the one specified with HAM_PARAM_RECORD_SIZE
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_move ( ham_cursor_t cursor,
ham_key_t key,
ham_record_t record,
ham_u32_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.

When specifying HAM_DIRECT_ACCESS, the data pointer will point directly to the record that is stored in hamsterdb; the data can be modified, but the pointer must not be reallocated or freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases and not if Transactions are enabled.

You can read only portions of the record by specifying the flag HAM_PARTIAL. In this case, hamsterdb will read record->partial_size bytes of the record data at offset record->partial_offset. If necessary, the record data will be limited to the original record size. The number of actually read bytes is returned in record->partial_size. The original size of the record is stored in record->size.

HAM_PARTIAL is not allowed if record->size is <= 8 or if Transactions are enabled. In such a case, HAM_INV_PARAMETER is returned.

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

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

If the first (HAM_CURSOR_FIRST) or last (HAM_CURSOR_LAST) key is requested, and the current key (or any of its duplicates) is currently modified in an active Transaction, then HAM_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 HAM_CURSOR_NEXT (or HAM_CURSOR_PREVIOUS) will be identical to HAM_CURSOR_FIRST (or HAM_CURSOR_LAST).

Parameters
cursorA valid Cursor handle
keyAn optional pointer to a ham_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 hamsterdb API calls. See HAM_KEY_USER_ALLOC on how to change this behaviour.
recordAn optional pointer to a ham_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 hamsterdb API calls. See HAM_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.
  • HAM_CURSOR_FIRST positions the Cursor on the first item in the Database
  • HAM_CURSOR_LAST positions the Cursor on the last item in the Database
  • HAM_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 HAM_CURSOR_FIRST.
  • HAM_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 HAM_CURSOR_LAST.
  • HAM_SKIP_DUPLICATES skips duplicate keys of the current key. Not allowed in combination with HAM_ONLY_DUPLICATES.
  • HAM_ONLY_DUPLICATES only move through duplicate keys of the current key. Not allowed in combination with HAM_SKIP_DUPLICATES.
  • HAM_DIRECT_ACCESS Only for In-Memory Databases and not if Transactions are enabled! Returns a direct pointer to the data blob stored by the hamsterdb engine. This pointer must not be resized or freed, but the data in this memory can be modified.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if cursor is NULL, or if an invalid combination of flags was specified
HAM_INV_PARAMETER if HAM_PARTIAL is set but record size is <= 8 or Transactions are enabled
HAM_CURSOR_IS_NIL if the Cursor does not point to an item, but key and/or record were requested
HAM_KEY_NOT_FOUND if cursor points to the first (or last) item, and a move to the previous (or next) item was requested
HAM_INV_PARAMETER if HAM_DIRECT_ACCESS is specified, but the Database is not an In-Memory Database.
HAM_INV_PARAMETER if HAM_DIRECT_ACCESS and HAM_ENABLE_TRANSACTIONS were both specified.
HAM_INV_PARAMETER if HAM_PARTIAL is specified and record->partial_offset+record->partial_size exceeds the record->size
HAM_TXN_CONFLICT if HAM_CURSOR_FIRST or HAM_CURSOR_LAST is specified but the first (or last) key or any of its duplicates is currently modified in an active Transaction
See Also
HAM_RECORD_USER_ALLOC
HAM_KEY_USER_ALLOC
ham_record_t
ham_key_t

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_overwrite ( ham_cursor_t cursor,
ham_record_t record,
ham_u32_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
HAM_SUCCESS upon success
HAM_INV_PARAMETER if cursor or record is NULL
HAM_INV_PARAMETER if cursor points to an item with duplicates and duplicate sorting is enabled
HAM_INV_PARAMETER if duplicate sorting is enabled
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
HAM_TXN_CONFLICT if the same key was inserted in another Transaction which was not yet committed or aborted

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