<< Click to Display Table of Contents >> Navigation:  Basic concepts > BDE Objects > Cursors

The Borland Database Engine (BDE) provides access to tables or query results through cursors. A cursor provides addressability to a collection of records one at a time. All data manipulation operations (insert, delete, update, and fetch), as well as positioning the cursor in the table (sometimes referred to as navigation) are performed with a cursor.

When the application opens a table with DbiOpenTable or executes a query, a cursor handle is returned. After the cursor handle is returned, you can use it to retrieve data stored in a table as well as information about a table. You can also obtain and set properties of this cursor. The application can close a cursor at any time with DbiCloseCursor. When the cursor is closed, the cursor handle becomes invalid. (Multiple cursors can be created on the same table.)

To access data in a table, the application opens the table and obtains a cursor handle. The table can be opened exclusively or shared. The translation mode can be specified as either xltNONE or xltFIELD. If xltNONE is specified, the data is returned from the table as the untranslated physical type (the native data type as stored by the data source). If xltFIELD is specified, the data is translated into a generic, logical type by BDE. Logical types are compatible with C language data types.

Ordered and unordered cursors

By default, the records returned by a cursor are not in any particular order. Ordered cursors can be obtained by specifying a current active index for a cursor (using DbiOpenTable or DbiSwitchToIndex). A query executed using the ORDER BY clause is also an ordered cursor.

Positioning the cursor

Whenever the application opens a cursor on a table or a query result, the resulting cursor is positioned at the beginning of the result set, before the first row, rather than on the first record of the table. This initial position enables the application to access all the records with the DbiGetNextRecord function.

At any time, the cursor can be positioned on a record or on a crack. A crack is a position between records at the beginning of the table, at the end of the table, or the place left when a record is deleted.

The possible cursor positions are

•At the beginning of the table or result set (the crack before the first record). DbiSetToBegin can be used to explicitly position the cursor here; the cursor is always positioned here when the cursor is opened.

•At the end of the table or result set (the crack after the last record). DbiSetToEnd can be used to explicitly position the cursor here.

•On a record (after a successful call to retrieve, insert, or update a record).

•On a crack between records. DbiSetToKey positions the cursor on the crack before the record of the specified key.

•The cursor is positioned on a crack if it was previously positioned on a record, and that record was deleted.

Bookmarks

A bookmark can be obtained to save the cursor's current position, so that it can be repositioned to that place later. Bookmarks can remember any position: on the current row, at the beginning or end of the table, or on a crack. A call to DbiGetBookMark saves the current position of the cursor as a bookmark. A subsequent call to DbiSetToBookMark positions the cursor to the location saved by DbiGetBookMark. Multiple bookmarks can be placed on a cursor. The positions of two bookmarks can be compared with a call to DbiCompareBookMarks.