A WT_CURSOR handle is the interface to a cursor. More...

Public Member Functions
int	close (WT_CURSOR *cursor)
	Close the cursor.
Data access
int	get_key (WT_CURSOR *cursor,...)
	Get the key for the current record.
int	get_value (WT_CURSOR *cursor,...)
	Get the value for the current record.
void	set_key (WT_CURSOR *cursor,...)
	Set the key for the next operation.
void	set_value (WT_CURSOR *cursor,...)
	Set the value for the next operation.
Cursor positioning
int	equals (WT_CURSOR cursor, WT_CURSOR other)
	Test whether two cursors refer to the same item.
int	next (WT_CURSOR *cursor)
	Return the next record.
int	prev (WT_CURSOR *cursor)
	Return the previous record.
int	reset (WT_CURSOR *cursor)
	Reset the position of the cursor.
int	search (WT_CURSOR *cursor)
	Move to the record matching the key.
int	search_near (WT_CURSOR cursor, int exactp)
	Move to the record matching the key if it exists, or a record that would be adjacent.
Data modification
int	insert (WT_CURSOR *cursor)
	Insert a record, and optionally overwrite an existing record.
int	update (WT_CURSOR *cursor)
	Update a record.
int	remove (WT_CURSOR *cursor)
	Remove a record.
Public Attributes
WT_SESSION *	session
	The session handle for this cursor.
const char *	uri
	The name of the data source for the cursor, matches the `uri` parameter to WT_SESSION::open_cursor used to open the cursor.
const char *	key_format
	The format of the data packed into key items.
const char *	value_format
	The format of the data packed into value items.

Detailed Description

A WT_CURSOR handle is the interface to a cursor.

Cursors allow data to be searched, stepped through and updated: the so-called CRUD operations (create, read, update and delete).

Raw data is represented by key/value pairs of WT_ITEM structures, but cursors can also provide access to fields within the key and value if the formats are described in the WT_SESSION::create method.

A cursor can be positioned in a collection of data. Cursors are opened in the context of a session (which may have an associated transaction), and can query and update records. In the common case, a cursor is used to access records in a table. However, cursors can be used on subsets of tables (such as a single column or a projection of multiple columns), as an interface to statistics, configuration data or application-specific data sources. See WT_SESSION::open_cursor for more information.

Thread safety: A WT_CURSOR handle cannot be shared between threads: it may only be used within the same thread as the encapsulating WT_SESSION.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_schema.c, ex_stat.c, and ex_thread.c.

Member Function Documentation

int WT_CURSOR::close ( WT_CURSOR * cursor )

Close the cursor.

This releases the resources associated with the cursor handle. Cursors are closed implicitly by ending the enclosing transaction or closing the session in which they were opened.

        ret = cursor->close(cursor);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c, ex_call_center.c, ex_cursor.c, and ex_schema.c.

int WT_CURSOR::equals	(	WT_CURSOR *	cursor,
		WT_CURSOR *	other
	)

Test whether two cursors refer to the same item.

To be equal, both cursors must have the same data source, have valid keys, and the keys must be equal.

        if (cursor->equals(cursor, other)) {
                /* Take some action. */
        }

Parameters:

cursor	the cursor handle
other	another cursor handle

Returns:: true (non-zero) if both cursors reference the same item, false (zero) otherwise

Examples:: ex_all.c.

int WT_CURSOR::get_key	(	WT_CURSOR *	cursor,
			...
	)

Get the key for the current record.

        const char *key;        /* Get the cursor's string key. */
        ret = cursor->get_key(cursor, &key);

        uint64_t recno;         /* Get the cursor's record number key. */
        ret = cursor->get_key(cursor, &recno);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_all.c, ex_config.c, ex_cursor.c, ex_schema.c, and ex_thread.c.

int WT_CURSOR::get_value	(	WT_CURSOR *	cursor,
			...
	)

Get the value for the current record.

        const char *value;      /* Get the cursor's string value. */
        ret = cursor->get_value(cursor, &value);

        WT_ITEM value;          /* Get the cursor's raw value. */
        ret = cursor->get_value(cursor, &value);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_schema.c, ex_stat.c, and ex_thread.c.

int WT_CURSOR::insert ( WT_CURSOR * cursor )

Insert a record, and optionally overwrite an existing record.

If the cursor was not configured with "append" or "overwrite", both the key and value must be set and the record must not already exist; the record will be inserted.

If the cursor was configured with "overwrite", both the key and value must be set; if the record already exists, the key's value will be updated, otherwise, the record will be inserted.

In a cursor with record number keys was configured with "append", the value must be set; a new record will be appended and the record number set as the cursor key value.

Inserting a new record after the current maximum record in a fixed-length column-store implicitly creates skipped records as records with a value of 0.

        /* Insert a new record. */
        const char *key = "some key";
        const char *value = "some value";
        cursor->set_key(cursor, key);
        cursor->set_value(cursor, value);
        ret = cursor->insert(cursor);

        /* Insert a new record or overwrite an existing record. */
        const char *key = "some key";
        const char *value = "some value";
        ret = session->open_cursor(
            session, "table:mytable", NULL, "overwrite", &cursor);
        cursor->set_key(cursor, key);
        cursor->set_value(cursor, value);
        ret = cursor->insert(cursor);

        /* Insert a new record and assign a record number. */
        uint64_t recno;
        const char *value = "some value";
        ret = session->open_cursor(
            session, "table:mytable", NULL, "append", &cursor);
        cursor->set_value(cursor, value);
        ret = cursor->insert(cursor);
        if (ret == 0)
                recno = cursor->get_key(cursor, &recno);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_cursor.c, ex_schema.c, and ex_thread.c.

int WT_CURSOR::next ( WT_CURSOR * cursor )

Return the next record.

        ret = cursor->next(cursor);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_all.c, ex_config.c, ex_cursor.c, ex_schema.c, ex_stat.c, and ex_thread.c.

int WT_CURSOR::prev ( WT_CURSOR * cursor )

Return the previous record.

        ret = cursor->prev(cursor);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c, ex_call_center.c, and ex_cursor.c.

int WT_CURSOR::remove ( WT_CURSOR * cursor )

Remove a record.

The key must be set, and the key's record will be removed.

Removing a record in a fixed-length column-store is identical to setting the record's value to 0.

        const char *key = "some key";
        cursor->set_key(cursor, key);
        ret = cursor->remove(cursor);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details. In particular, if no record with the specified key exists, WT_NOTFOUND is returned.

Examples:: ex_all.c, and ex_cursor.c.

int WT_CURSOR::reset ( WT_CURSOR * cursor )

Reset the position of the cursor.

Any resources held by the cursor are released, and the cursor position is no longer valid. Subsequent iteration with WT_CURSOR::next will move to the first record, or with WT_CURSOR::prev will move to the last record.

        ret = cursor->reset(cursor);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_all.c, and ex_cursor.c.

int WT_CURSOR::search ( WT_CURSOR * cursor )

Move to the record matching the key.

The key must first be set.

        const char *key = "some key";
        cursor->set_key(cursor, key);
        ret = cursor->search(cursor);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c, ex_call_center.c, ex_cursor.c, and ex_stat.c.

int WT_CURSOR::search_near	(	WT_CURSOR *	cursor,
		int *	exactp
	)

Move to the record matching the key if it exists, or a record that would be adjacent.

Either the smallest record larger than the key or the largest record smaller than the key (in other words, a logically adjacent key). The key must first be set.

        cursor->set_key(cursor, key);
        ret = cursor->search_near(cursor, &exact);
        if (ret == 0) {
                if (exact == 0) {
                        /* an exact match */
                } else if (exact < 0) {
                        /* returned smaller key */
                } else if (exact > 0) {
                        /* returned larger key */
                }
        }

        /*
         * An example of a forward scan through the table, where all keys
         * greater than or equal to a specified prefix are included in the
         * scan.
         */
        cursor->set_key(cursor, key);
        ret = cursor->search_near(cursor, &exact);
        if (ret == 0 && exact >= 0) {
                /* include first key returned in the scan */
        }

        while ((ret = cursor->next(cursor)) == 0) {
                /* the rest of the scan */
        }

        /*
         * An example of a backward scan through the table, where all keys
         * less than a specified prefix are included in the scan.
         */
        cursor->set_key(cursor, key);
        ret = cursor->search_near(cursor, &exact);
        if (ret == 0 && exact < 0) {
                /* include first key returned in the scan */
        }

        while ((ret = cursor->prev(cursor)) == 0) {
                /* the rest of the scan */
        }

Parameters:

cursor	the cursor handle
exactp	the status of the search: 0 if an exact match is found, < 0 if a smaller key is returned, > 0 if a larger key is returned

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c, ex_call_center.c, and ex_cursor.c.

void WT_CURSOR::set_key	(	WT_CURSOR *	cursor,
			...
	)

Set the key for the next operation.

                                /* Set the cursor's string key. */
        const char *key = "another key";
        cursor->set_key(cursor, key);

        uint64_t recno = 37;    /* Set the cursor's record number key. */
        cursor->set_key(cursor, recno);

Parameters:

cursor the cursor handle

If an error occurs during this operation, a flag will be set in the cursor, and the next operation to access the key will fail. This simplifies error handling in applications.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_cursor.c, ex_stat.c, and ex_thread.c.

void WT_CURSOR::set_value	(	WT_CURSOR *	cursor,
			...
	)

Set the value for the next operation.

                                /* Set the cursor's string value. */
        const char *value = "another value";
        cursor->set_value(cursor, value);

        WT_ITEM value;          /* Set the cursor's raw value. */
        value.data = "another value";
        value.size = strlen("another value");
        cursor->set_value(cursor, &value);

Parameters:

cursor the cursor handle

If an error occurs during this operation, a flag will be set in the cursor, and the next operation to access the value will fail. This simplifies error handling in applications.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_cursor.c, ex_schema.c, and ex_thread.c.

int WT_CURSOR::update ( WT_CURSOR * cursor )

Update a record.

Both key and value must be set, the key must exist, and the value of the key's record will be updated.

        const char *key = "some key";
        const char *value = "some value";
        cursor->set_key(cursor, key);
        cursor->set_value(cursor, value);
        ret = cursor->update(cursor);

Parameters:

cursor the cursor handle

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details. In particular, if no record with the specified key exists, WT_NOTFOUND is returned.

Examples:: ex_all.c, and ex_cursor.c.

Member Data Documentation

const char* WT_CURSOR::key_format

The format of the data packed into key items.

See Packing and Unpacking Data for details. If not set, a default value of "u" is assumed, and applications must use WT_ITEM structures to manipulate untyped byte arrays.

WT_SESSION* WT_CURSOR::session

The session handle for this cursor.

const char* WT_CURSOR::value_format

The format of the data packed into value items.

See Packing and Unpacking Data for details. If not set, a default value of "u" is assumed, and applications must use WT_ITEM structures to manipulate untyped byte arrays.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation