hamsterdb Cursor Functions

Defines

#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_db_t *db, ham_txn_t *txn, ham_u32_t flags, ham_cursor_t **cursor)
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_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_find_ex (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_size_t *count, ham_u32_t flags)
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_cursor_close (ham_cursor_t *cursor)

Define Documentation

#define HAM_CURSOR_FIRST   0x0001

Flag for ham_cursor_move

Definition at line 2320 of file hamsterdb.h.

Referenced by ham::cursor::move_first().

#define HAM_CURSOR_LAST   0x0002

Flag for ham_cursor_move

Definition at line 2323 of file hamsterdb.h.

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

#define HAM_CURSOR_NEXT   0x0004

Flag for ham_cursor_move

Definition at line 2326 of file hamsterdb.h.

Referenced by ham::cursor::move_next().

#define HAM_CURSOR_PREVIOUS   0x0008

Flag for ham_cursor_move

Definition at line 2329 of file hamsterdb.h.

Referenced by ham::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.

Definition at line 2642 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.

Definition at line 2672 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.

Definition at line 2654 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.

Definition at line 2663 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.

Definition at line 2648 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.

Definition at line 2687 of file hamsterdb.h.

#define HAM_ONLY_DUPLICATES   0x0020

Flag for ham_cursor_move

Definition at line 2335 of file hamsterdb.h.

#define HAM_SKIP_DUPLICATES   0x0010

Flag for ham_cursor_move and ham_get_key_count

Definition at line 2332 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:
src The existing Cursor
dest A 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 ham::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_close).

Parameters:
cursor A 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_close

Referenced by ham::cursor::close().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_create ( ham_db_t db,
ham_txn_t txn,
ham_u32_t  flags,
ham_cursor_t **  cursor 
)

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 Database Cursors before closing the Database.

Parameters:
db A valid Database handle
txn A Transaction 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:
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 ham::cursor::create().

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_DUPLICATES, this function erases only the duplicate item to which the Cursor refers.

Parameters:
cursor A valid Cursor handle
flags Unused, set to 0
Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if cursor is NULL
HAM_DB_READ_ONLY 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

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

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_find ( ham_cursor_t cursor,
ham_key_t key,
ham_u32_t  flags 
)

Searches a key and points the Cursor to this key

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 of freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases.

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. 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:
cursor A valid Cursor handle
key A 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.
flags Optional 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! 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.
See also:
HAM_KEY_USER_ALLOC
ham_key_t

Referenced by ham::cursor::find().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_find_ex ( 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

This function is identical to ham_cursor_find, but it immediately retrieves the located record if the lookup operation was successful.

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 of freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases.

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->size.

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. 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:
cursor A valid Cursor handle
key A 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.
record A 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.
flags Optional 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! 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.
See also:
HAM_KEY_USER_ALLOC
ham_key_t
HAM_RECORD_USER_ALLOC
ham_record_t

Referenced by ham::cursor::find_ex().

HAM_EXPORT ham_status_t HAM_CALLCONV ham_cursor_get_duplicate_count ( ham_cursor_t cursor,
ham_size_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:
cursor A valid Cursor handle
count Returns the number of duplicate keys
flags Optional 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

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

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. (Note that the Database has to be created with HAM_ENABLE_DUPLICATES, in order to use 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. Using HAM_PARTIAL is not allowed in combination with sorted duplicates (HAM_SORT_DUPLICATES).

However, if a sort order is specified (see HAM_SORT_DUPLICATES) then the key is inserted in sorted order. In this case, the use of HAM_DUPLICATE_INSERT_FIRST, HAM_DUPLICATE_INSERT_LAST, HAM_DUPLICATE_INSERT_BEFORE and HAM_DUPLICATE_INSERT_AFTER is not allowed and will return HAM_INV_PARAMETER.

Specify the flag HAM_HINT_APPEND if you insert sequential data and the current key is higher than any other key in this Database. In this case hamsterdb will optimize the insert algorithm. hamsterdb will verify that this key is the highest; if not, it will perform a normal insert. This 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:
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:

  • 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 was specified AND duplicate sorting is enabled (HAM_SORT_DUPLICATES)
HAM_INV_PARAMETER if duplicate sorting is enabled (with HAM_SORT_DUPLICATES) but one of HAM_DUPLICATE_INSERT_* was specified
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_DUPLICATES.
HAM_DB_READ_ONLY if you tried to insert a key to a read-only Database.
HAM_INV_KEYSIZE if the key's size is larger than the keysize parameter specified for ham_create_ex and variable key sizes are disabled (see HAM_DISABLE_VAR_KEYLEN) OR if the keysize parameter specified for ham_create_ex is smaller than 8.
HAM_CURSOR_IS_NIL if the Cursor does not point to an item
See also:
HAM_DISABLE_VAR_KEYLEN
HAM_SORT_DUPLICATES
ham_set_duplicate_compare_func

Referenced by ham::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 of freed. The flag HAM_DIRECT_ACCESS is only allowed in In-Memory Databases.

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. The full record size will always be given in record->size! If partial_size+partial_offset exceed record->size then partial_size will be limited. To shrink or grow the record, adjust record->size. HAM_PARTIAL automatically overwrites existing records. Gaps will be filled with null-bytes if the record did not yet exist. Using HAM_PARTIAL is not allowed in combination with sorted duplicates (HAM_SORT_DUPLICATES).

Parameters:
cursor A valid Cursor handle
key An 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.
record An 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.
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.

Returns:
HAM_SUCCESS upon success
HAM_INV_PARAMETER if cursor is NULL, or if an invalid combination of flags was specified
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_PARTIAL is specified and record->partial_offset+record->partial_size exceeds the record->size
See also:
HAM_RECORD_USER_ALLOC
HAM_KEY_USER_ALLOC
ham_record_t
ham_key_t

Referenced by ham::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.

The use of this function is not allowed if the item has duplicate keys and the duplicate sorting is enabled (see HAM_SORT_DUPLICATES). In this case, HAM_INV_PARAMETER is returned.

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

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

Generated by  doxygen 1.6.3