Table Cursor

Data Structures
struct	db_table_cursor_t
	Table cursor settings. More...
Functions
db_result_t	db_table_cursor_init (db_table_cursor_t *)
db_result_t	db_table_cursor_destroy (db_table_cursor_t *)
db_cursor_t	db_open_table_cursor (db_t, const db_objname_t *table, const db_table_cursor_t *)
db_result_t	db_seek_prior (db_cursor_t)
db_result_t	db_seek_last (db_cursor_t)
db_result_t	db_seek (db_cursor_t, db_seek_t, db_row_t, db_object_t, db_fieldno_t nfields)
db_result_t	db_insert (db_cursor_t, db_row_t, db_object_t, db_flags_t)
db_result_t	db_delete (db_cursor_t, db_flags_t)
db_result_t	db_update (db_cursor_t, db_row_t, db_object_t)
db_result_t	db_update_flags (db_cursor_t, db_row_t, db_object_t, db_flags_t)
db_result_t	db_get_bookmark (db_cursor_t, db_oid_t *)
db_result_t	db_goto_bookmark (db_cursor_t, const db_oid_t *)
db_result_t	db_set_range (db_cursor_t h, db_row_t low_row, db_object_t low_object, db_fieldno_t low_fields, db_row_t high_row, db_object_t high_object, db_fieldno_t high_fields)
db_result_t	db_add_filter (db_cursor_t h, db_seek_t relation, db_row_t filter_row, db_object_t filter_row_object, const db_indexfield_t *fields, db_fieldno_t nfields)
db_result_t	db_remove_filters (db_cursor_t)
db_result_t	db_sort (db_cursor_t cursor, const db_indexfield_t *fields, db_fieldno_t nfields)
int	db_is_sorted_by (db_cursor_t cursor, const db_indexfield_t *fields, db_fieldno_t nfields)
db_result_t	db_qseek (db_cursor_t, db_seek_t, const db_bind_t *, db_len_t, db_object_t, db_fieldno_t nfields)
db_result_t	db_qinsert (db_cursor_t, const db_bind_t *, db_len_t, db_object_t, db_flags_t)
db_result_t	db_qupdate (db_cursor_t, const db_bind_t *, db_len_t, db_object_t)
db_result_t	db_qupdate_flags (db_cursor_t, const db_bind_t *, db_len_t, db_object_t, db_flags_t)
C_EXPORT db_result_t	db_get_row_num (db_cursor_t hcursor, int64_t *num)
Insert Flags
#define	DB_INSERT_SEEK_NEW   _DB_INSERT_SEEK_NEW
#define	DB_INSERT_SEEK_MASK   _DB_INSERT_SEEK_MASK
Update Flags
#define	DB_UPDATE_SEEK_NEW   _DB_UPDATE_SEEK_NEW
#define	DB_UPDATE_SEEK_NEXT   _DB_UPDATE_SEEK_NEXT
#define	DB_UPDATE_SEEK_PRIOR   _DB_UPDATE_SEEK_PRIOR
#define	DB_UPDATE_SEEK_MASK   _DB_UPDATE_SEEK_MASK
Delete Flags
#define	DB_DELETE_SEEK_NEXT   _DB_DELETE_SEEK_NEXT
#define	DB_DELETE_SEEK_PRIOR   _DB_DELETE_SEEK_PRIOR
#define	DB_DELETE_SEEK_MASK   _DB_DELETE_SEEK_MASK
Seek Flags
#define	DB_SEEK_LESS   _DB_SEEK_LESS
#define	DB_SEEK_LESS_OR_EQUAL   _DB_SEEK_LESS_OR_EQUAL
#define	DB_SEEK_FIRST_EQUAL   _DB_SEEK_FIRST_EQUAL
#define	DB_SEEK_LAST_EQUAL   _DB_SEEK_LAST_EQUAL
#define	DB_SEEK_GREATER   _DB_SEEK_GREATER
#define	DB_SEEK_GREATER_OR_EQUAL   _DB_SEEK_GREATER_OR_EQUAL
#define	DB_SEEK_EQUAL   _DB_SEEK_EQUAL

---

Detailed Description

A table cursor provides direct access to a database table and, optionally, one of its indexes.

To obtain a cursor handle for a table, call

db_open_table_cursor.

---

Define Documentation

#define DB_INSERT_SEEK_NEW   _DB_INSERT_SEEK_NEW

Move the cursor position to the inserted record.

Examples:

phonebook_c.c.

#define DB_UPDATE_SEEK_NEW   _DB_UPDATE_SEEK_NEW

Move the cursor position to the new position of the current record, if the record's position has changed after the update.

#define DB_DELETE_SEEK_NEXT   _DB_DELETE_SEEK_NEXT

Move the cursor position to the next record.

Examples:

phonebook_c.c.

#define DB_SEEK_LESS   _DB_SEEK_LESS

Less than.

#define DB_UPDATE_SEEK_NEXT   _DB_UPDATE_SEEK_NEXT

Move the cursor position to the next record, based on the position of the record before the update.

#define DB_UPDATE_SEEK_PRIOR   _DB_UPDATE_SEEK_PRIOR

Move the cursor position to the previous record, based on the position of the record before the update.

#define DB_DELETE_SEEK_PRIOR   _DB_DELETE_SEEK_PRIOR

Move the cursor position to the prior record.

#define DB_SEEK_LESS_OR_EQUAL   _DB_SEEK_LESS_OR_EQUAL

Less than or equal to.

#define DB_SEEK_FIRST_EQUAL   _DB_SEEK_FIRST_EQUAL

First exact match.

#define DB_SEEK_LAST_EQUAL   _DB_SEEK_LAST_EQUAL

Last exact match.

#define DB_SEEK_GREATER   _DB_SEEK_GREATER

Greater than.

#define DB_SEEK_GREATER_OR_EQUAL   _DB_SEEK_GREATER_OR_EQUAL

Greater than or equal to.

#define DB_SEEK_EQUAL   _DB_SEEK_EQUAL

Equivalent to DB_SEEK_FIRST_EQUAL.

Examples:

phonebook_c.c, and phonebook_c_sql.c.

---

Function Documentation

db_result_t db_table_cursor_init

(

db_table_cursor_t *

tcdef

)

Initialize a table cursor.

Parameters:

tcdef

Table cursor configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Table cursor configuration is null.

See also:

db_table_cursor_destroy,
get_db_error, clear_db_error, Error Handling

db_result_t db_table_cursor_destroy

(

db_table_cursor_t *

tcdef

)

Destroy a table cursor.

Parameters:

tcdef

Table cursor configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Table cursor configuration is null.

See also:

db_table_cursor_init,
get_db_error, clear_db_error, Error Handling

db_cursor_t db_open_table_cursor	(	db_t	hdb,
		const db_objname_t *	table,
		const db_table_cursor_t *	params
	)

Obtain a cursor to access the data in a table.

Parameters:

hdb	Database handle.
table	Table name. A name must start with a letter and can be followed by one or more letters, numbers, or underscores.
params	Cursor parameter structure. Use NULL to create a table scan cursor (no index) with all capabilities enabled.

Returns:

• Cursor handle.
• NULL on failure.

Note:

When no longer needed, the cursor must be closed with db_close_cursor.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, invalid params->flags.
• DB_ENAME Invalid name.
• DB_EINDEX Unable to find cursor index using name sepcified.

See also:

db_close_cursor,
get_db_error, clear_db_error, Error Handling

db_result_t db_seek_prior

(

db_cursor_t

hcursor

)

Move the cursor to the previous row in the table or result set.

Parameters:

hcursor

Cursor handle.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

Note:

If the cursor is on the first row in the table and db_seek_prior is called, the cursor will not have a current row and db_bof will return true.

On failure, one of the following error codes is set:

• DB_EINVAL Cursor handle is invalid.
• DB_ESTATE Cursor does not support backward scanning.
• DB_ENOMOREDATA Cursor is already positioned before the beginning of the table.

Forward-only SQL cursors cannot use this function.

See also:

db_seek_next, db_seek_first, db_seek_last,
get_db_error, clear_db_error, Error Handling

db_result_t db_seek_last

(

db_cursor_t

hcursor

)

Move the cursor to the last row in the table or result set.

Parameters:

hcursor

Cursor handle.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Cursor handle is invalid.
• DB_ESTATE Cursor does not support forward scanning.

Forward-only SQL cursors cannot use this function.

See also:

db_seek_next, db_seek_first, db_seek_prior,
get_db_error, clear_db_error, Error Handling

db_result_t db_seek	(	db_cursor_t	hcursor,
		db_seek_t	seek,
		db_row_t	hrow,
		db_object_t	uobject,
		db_fieldno_t	nfields
	)

Search for a row matching the criteria given in the row hrow.

The cursor is positioned on the first table row that is in the relationship seek to the data in hrow.

Parameters:

hcursor	Cursor handle.
seek	DB_SEEK_LESS DB_SEEK_LESS_OR_EQUAL DB_SEEK_FIRST_EQUAL DB_SEEK_LAST_EQUAL DB_SEEK_GREATER DB_SEEK_GREATER_OR_EQUAL DB_SEEK_EQUAL
hrow	Row of search values.
uobject	Row data for relative bindings. Use NULL if hrow does not contain relative bindings.
nfields	The first nfields fields in the cursor's index will be used to find a match.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, invalid row handle.
• DB_EINDEX Index not available.
• DB_ENOTFOUND No rows match the search criteria.

See also:

db_seek_next, db_seek_first, db_seek_prior,
get_db_error, clear_db_error, Error Handling

db_result_t db_insert	(	db_cursor_t	hcursor,
		db_row_t	hrow,
		db_object_t	uobject,
		db_flags_t	flags
	)

Insert the data in hrow into the table represented by the cursor and position the cursor on the inserted row.

Parameters:

hcursor	Cursor handle.
hrow	Row of values for insert. Unbound fields will be treated as null.
uobject	Row data for relative bindings. Use NULL if hrow does not contain relative bindings.
flags	Post positioning flag DB_INSERT_SEEK_NEW - seek to the newly inserted record. 0 - stay at the current record whatever it is.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, invalid row handle.
• DB_ESTATE The cursor does not support insert operations.
• DB_EINDVALUE Invalid length indicator (*ind_ptr) value in row.
• DB_ENULLFIELD Insert would violate a NOT NULL constraint. Use a value that is not null.

Postcondition:

A transaction is active on database if the operation succeeds.

See also:

db_fetch, db_update, db_delete,
get_db_error, clear_db_error, Error Handling

db_result_t db_delete	(	db_cursor_t	hcursor,
		db_flags_t	flags
	)

Delete the current row in a cursor.

Parameters:

hcursor	Cursor handle.
flags	Post positioning flag DB_DELETE_SEEK_PRIOR - after row deletion seek to the record preceding deleted one DB_DELETE_SEEK_NEXT - after row deletion seek to the record following deleted one (default)

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Cursor handle is invalid.
• DB_ESTATE The cursor does not support delete operations.

Postcondition:

A transaction is active on database if the operation succeeds.

See also:

db_fetch, db_insert, db_update,
get_db_error, clear_db_error, Error Handling

db_result_t db_update	(	db_cursor_t	hcursor,
		db_row_t	hrow,
		db_object_t	uobject
	)

Update the contents of a cursor's current row using the data in hrow.

Parameters:

hcursor	Cursor handle.
hrow	Row of values for update. Only bound fields will be updated.
uobject	Row data for relative bindings. Use NULL if hrow does not contain relative bindings.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, invalid row handle.
• DB_ESTATE The cursor does not support update operations.
• DB_EINDVALUE Invalid length indicator (*ind_ptr) value in row.
• DB_ENULLFIELD Update would violate a NOT NULL constraint. Use a value that is not null.

Postcondition:

A transaction is active on database if the operation succeeds.

db_update is equivalent to db_update_flags with DB_UPDATE_SEEK_NEW.

If the position of the cursor after update is not important,

db_update_flags with no seek flags may offer better performance.

db_update is provided for backward compatibility.

See also:

db_update_flags, db_fetch, db_insert, db_delete,
get_db_error, clear_db_error, Error Handling

db_result_t db_update_flags	(	db_cursor_t	hcursor,
		db_row_t	hrow,
		db_object_t	uobject,
		db_flags_t	flags
	)

Update the contents of a cursor's current row using the data in hrow.

Parameters:

hcursor	Cursor handle.
hrow	Row of values for update. Only bound fields will be updated.
uobject	Row data for relative bindings. Use NULL if hrow does not contain relative bindings.
flags	Position of the cursor after update. If no flags are specified, the final cursor position is undefined and execution may be faster. DB_UPDATE_SEEK_NEW DB_UPDATE_SEEK_NEXT DB_UPDATE_SEEK_PRIOR

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, invalid row handle.
• DB_ESTATE The cursor does not support update operations.

Postcondition:

A transaction is active on database if the operation succeeds.

See also:

db_fetch, db_insert, db_delete,
get_db_error, clear_db_error, Error Handling

db_result_t db_get_bookmark	(	db_cursor_t	hcursor,
		db_oid_t *	bookmark
	)

Set a bookmark to the cursor's current row.

Parameters:

hcursor	Cursor handle.
bookmark	Returned bookmark id.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, bookmark is null.

See also:

db_goto_bookmark,
get_db_error, clear_db_error, Error Handling

db_result_t db_goto_bookmark	(	db_cursor_t	hcursor,
		const db_oid_t *	bookmark
	)

Set a cursor's current row from a bookmark.

Parameters:

hcursor	Cursor handle.
bookmark	Bookmark to go to.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Cursor handle is invalid or bookmark is null.

See also:

db_get_bookmark,
get_db_error, clear_db_error, Error Handling

db_result_t db_set_range	(	db_cursor_t	hcursor,
		db_row_t	low_row,
		db_object_t	low_uobject,
		db_fieldno_t	low_size,
		db_row_t	high_row,
		db_object_t	high_uobject,
		db_fieldno_t	high_size
	)

Restrict a cursor to only access rows within a given range.

Parameters:

hcursor	Cursor handle.
low_row	Low row handle.
low_uobject	Low bound object data.
low_size	Low size.
high_row	High row handle.
high_uobject	High bound object data.
high_size	High size.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, invalid low row handle, invalid high row handle, low row is null, high row is null.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_add_filter	(	db_cursor_t	hcursor,
		db_seek_t	relation,
		db_row_t	filter_row,
		db_object_t	filter_row_uobject,
		const db_indexfield_t *	fields,
		db_fieldno_t	nfields
	)

Filter a table cursor by one or more fields.

After the filter is applied, the cursor will only access rows that satisfy the filter criteria.

Parameters:

hcursor	Cursor handle.
relation	Relation between values in the table and assigned values. DB_SEEK_LESS DB_SEEK_LESS_OR_EQUAL DB_SEEK_GREATER DB_SEEK_GREATER_OR_EQUAL DB_SEEK_EQUAL
filter_row	A row of fields table fields for comparison.
filter_row_uobject	Binding object data for the filter row.
fields	List of fields to use in comparison, or NULL. Order is important.
nfields	Number of fields in the list.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_ENOMEM Cannot allocate enough memory to store the filter criteria.
• DB_EFIELD Invalid field number used in filter_row.

Note:

This function does not support SQL queries. Instead, use a WHERE clause in the query.

The cursor position is not changed by db_add_filter. Filters are applied when the cursor is next positioned, usually by db_seek_next.

The row can be safely modified or destroyed after the filter is added. Additional filters can be added to the cursor by calling db_add_filter again with another row or the same row with new values assigned to it.

If an index was selected when the cursor was created, that index will be used to optimize performance if it starts with any filter fields. Otherwise,

db_seek_first, db_seek_next, db_seek_prior, and db_seek_last will scan

the table until a row that satisfies the filter is found.

If fields is used, fields are compared in the order they appear in the list. A field is only used in the comparison if all earlier fields are equal in both filter_row and the table row. For example, the comparison:

("a", "z") =< ("c", "b") is true.

The same comparison, but with the order of the fields reversed:

("z', "a") =< ("b", "c") is false.

If fields is NULL or nfields is zero, all fields in filter_row are used in the comparison. Additionally, each field is compared individually and all fields must satisfy the relation. For example, the comparison:

("a", "b", "z") =< ("c", "b", "a")

is evaluated as three separate filters when fields is NULL:

("a") =< ("c") and ("b") =< ("b") and ("z") <= ("a")

The result of this comparison is false because "z" =< "a" is false.

See also:

db_remove_filters, db_seek_next

db_result_t db_remove_filters

(

db_cursor_t

hcursor

)

Remove all filters applied to a cursor.

Parameters:

hcursor

Cursor handle.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

Note:

This function does not support SQL queries.

See also:

db_add_filter

db_result_t db_sort	(	db_cursor_t	hcursor,
		const db_indexfield_t *	fields,
		db_fieldno_t	nfields
	)

Sort a table cursor dynamically.

Parameters:

hcursor	Cursor handle.
fields	A list of fields by which to sort the cursor.
nfields	Number of fields in the list.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

Note:

This function does not support SQL queries. Instead, use an ORDER BY clause in the query.

If an index was selected when the cursor was created and that index can be used to fully sort the table, db_sort does nothing. Otherwise, the table is dynamically sorted. For best performance, apply filters to the table before sorting.

If db_add_filter, db_remove_filters, or db_set_range are called after a table has been sorted, they will not be active until until the next time

db_sort is called.

Set fields to NULL to remove the sort criteria, which will also apply any new filters.

See also:

db_is_sorted_by, db_add_filter

int db_is_sorted_by	(	db_cursor_t	hcursor,
		const db_indexfield_t *	fields,
		db_fieldno_t	nfields
	)

Determine whether a table cursor is sorted by a list of fields.

Parameters:

fields	A list of fields.
nfields	Number of fields in the list.
hcursor	Cursor handle.

Returns:

• true if the table is sorted by fields.
• false if the table may not be sorted by fields.
• -1 if an error occurs.

Note:

This function does not support SQL queries.

The cursor's index and filters are used to determine whether the cursor is sorted by fields. If the cursor does not use an index, db_is_sorted_by will always return false.

This function can be used to predict whether or not db_sort will return immediately if called. If db_is_sorted_by returns true, db_sort would have no effect. If db_is_sorted_by returns false, db_sort would perform a dynamic sort.

See also:

db_sort

db_result_t db_qseek	(	db_cursor_t	hcursor,
		db_seek_t	seek,
		const db_bind_t *	binds,
		db_len_t	nbinds,
		db_object_t	uobject,
		db_fieldno_t	nfields
	)

Position on the row matching the search criteria given the first nfields fields in the cursor's index.

Parameters:

hcursor	Cursor handle.
seek	DB_SEEK_LESS DB_SEEK_LESS_OR_EQUAL DB_SEEK_FIRST_EQUAL DB_SEEK_LAST_EQUAL DB_SEEK_GREATER DB_SEEK_GREATER_OR_EQUAL DB_SEEK_EQUAL
binds	Relative field bindings.
nbinds	Number of fields bound.
uobject	Source for row contents.
nfields	Number of uobject criteria fields.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, relative field binding is null number of fields bound is <= 0.
• DB_EINDEX Index error. Seek needs an index to seek by.
• DB_ENOTFOUND No rows match the search criteria.

Postcondition:

A transaction is active on database if the operation succeeds.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_qinsert	(	db_cursor_t	hcursor,
		const db_bind_t *	binds,
		db_len_t	nbinds,
		db_object_t	uobject,
		db_flags_t	flags
	)

Insert a new row into a cursor's table using a binding array.

db_qinsert is a convenience function that combines db_alloc_row and

db_insert. For best performance in tight loops, use db_alloc_row outside the

loop and db_insert inside the loop.

Postcondition:

The cursor is positioned on the inserted row.

Parameters:

hcursor	Cursor handle.
binds	Array of bindings.
nbinds	Number of fields in binds.
uobject	Row data for relative bindings. Use NULL if hrow does not contain relative bindings.
flags	DB_INSERT_SEEK_NEW - seek to the newly inserted record. 0 - stay at the current record whatever it is.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor, relative field binding is null.
• DB_EBINDSIZE Invalid bind size
• DB_ERANGE Argument is out of range. Number of fields < 0 or number of fields > binds.size.
• DB_ENAME Invalid field name used in binding.
• DB_ESTATE The cursor does not support insert operations.

Postcondition:

A transaction is active on database if the operation succeeds.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_qupdate	(	db_cursor_t	hcursor,
		const db_bind_t *	binds,
		db_len_t	nbinds,
		db_object_t	uobject
	)

Update the contents of the cursor's current row using a binding array.

db_qupdate is a convenience function that combines db_alloc_row and

db_update. For best performance in tight loops, use db_alloc_row outside the

loop and db_update inside the loop.

Postcondition:

The cursor is positioned on the inserted row.

Parameters:

hcursor	Cursor handle.
binds	Array of bindings.
nbinds	Number of fields in binds.
uobject	Row data for relative bindings. Use NULL if hrow does not contain relative bindings.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, relative field binding is null, number of fields bound <=0.
• DB_EBINDSIZE Invalid bind size.
• DB_ERANGE Argument is out of range. Number of fields < 0 or number of feilds > binds.size.
• DB_ENAME Invalid field name used in binding.
• DB_ESTATE The table or row is locked, or the cursor does not support update operations.

db_qupdate is equivalent to db_qupdate_flags with DB_UPDATE_SEEK_NEW.

If the position of the cursor after update is not important,

db_qupdate_flags with no seek flags may offer better performance.

db_qupdate is provided for backward compatibility.

Postcondition:

A transaction is active on database if the operation succeeds.

See also:

db_qupdate_flags, get_db_error, clear_db_error, Error Handling

db_result_t db_qupdate_flags	(	db_cursor_t	hcursor,
		const db_bind_t *	binds,
		db_len_t	nbinds,
		db_object_t	uobject,
		db_flags_t	flags
	)

Update the contents of the cursor's current row using a binding array.

db_qupdate is a convenience function that combines db_alloc_row and

db_update. For best performance in tight loops, use db_alloc_row outside the

loop and db_update inside the loop.

Postcondition:

The cursor is positioned on the inserted row.

Parameters:

hcursor	Cursor handle.
binds	Array of bindings.
nbinds	Number of fields in binds.
uobject	Row data for relative bindings. Use NULL if hrow does not contain relative bindings.
flags	Position of the cursor after update. If no flags are specified, the final cursor position is undefined and execution may be faster. DB_UPDATE_SEEK_NEW DB_UPDATE_SEEK_NEXT DB_UPDATE_SEEK_PRIOR

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid cursor handle, relative field binding is null, number of fields bound <=0.
• DB_EBINDSIZE Invalid bind size.
• DB_ERANGE Argument is out of range. Number of fields < 0 or number of feilds > binds.size.
• DB_ENAME Invalid field name used in binding.
• DB_ESTATE The table or row is locked, or the cursor does not support update operations.

Postcondition:

A transaction is active on database if the operation succeeds.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_get_row_num	(	db_cursor_t	hcursor,
		int64_t *	num
	)

Get the current row number from a numbered index.

If the cursor supports this feature, the row number will increase as the cursor seeks forward. The row number may increase by more than one for each row.

The number returned does not uniquely identify the row and may change if any row in the table is modified.

This function only supports a table cursor that was created using a numbered index.