hamsterdb Cursor Functions


Defines
#define	HAM_CURSOR_FIRST 1
#define	HAM_CURSOR_LAST 2
#define	HAM_CURSOR_NEXT 4
#define	HAM_CURSOR_PREVIOUS 8
#define	HAM_SKIP_DUPLICATES 16
#define	HAM_ONLY_DUPLICATES 32
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_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)
Variables
void *	ham_record_t::data
ham_u32_t	ham_record_t::flags
ham_u32_t	ham_record_t::_intflags
ham_u64_t	ham_record_t::_rid
void *	ham_key_t::data
ham_u32_t	ham_key_t::flags
ham_u32_t	ham_key_t::_flags
ham_u64_t	ham_parameter_t::value

Define Documentation

#define HAM_CURSOR_FIRST 1

Flag for ham_cursor_move

Definition at line 1617 of file hamsterdb.h.

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

#define HAM_CURSOR_LAST 2

Flag for ham_cursor_move

Definition at line 1620 of file hamsterdb.h.

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

#define HAM_CURSOR_NEXT 4

Flag for ham_cursor_move

Definition at line 1623 of file hamsterdb.h.

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

#define HAM_CURSOR_PREVIOUS 8

Flag for ham_cursor_move

Definition at line 1626 of file hamsterdb.h.

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

#define HAM_ONLY_DUPLICATES 32

Flag for ham_cursor_move

Definition at line 1632 of file hamsterdb.h.

#define HAM_SKIP_DUPLICATES 16

Flag for ham_cursor_move

Definition at line 1629 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_INV_PARAMETER if cursor is NULL

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	Optional flags for erasing the key; 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.

Parameters:

	cursor	A valid Cursor handle
	key	A valid key structure
	flags	Optional flags for searching the item; unused, set to 0

Returns:

HAM_SUCCESS upon success

HAM_INV_PARAMETER if cursor or key is NULL

HAM_KEY_NOT_FOUND if the requested key was not found

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

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.

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.

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. HAM_DUPLICATE. If the key already exists, a duplicate key is inserted. Same as HAM_DUPLICATE_INSERT_LAST. HAM_DUPLICATE_INSERT_BEFORE. If the key already exists, a duplicate key is inserted before the duplicate pointed to by the Cursor. HAM_DUPLICATE_INSERT_AFTER. If the key already exists, a duplicate key is inserted after the duplicate pointed to by the Cursor. HAM_DUPLICATE_INSERT_FIRST. If the key already exists, a duplicate key is inserted as the first duplicate of the current key. HAM_DUPLICATE_INSERT_LAST. If the key already exists, a duplicate key is inserted as the last duplicate of the current key.

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

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.

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. 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: skip 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.