ODBC: The ODBC Cursor Library

  • Article

|  Overview |  How Do I |  FAQ |  Sample |  |  ODBC Driver List

This article describes the ODBC Cursor Library and explains how to use it. Topics include:

  • The Cursor Library and Level 1 ODBC drivers

  • Positioned updates and timestamp columns

  • Using the Cursor Library

The ODBC Cursor Library is a dynamic-link library (DLL) that resides between the ODBC Driver Manager and the driver. In ODBC terms, a driver maintains a “cursor” to keep track of its position in the recordset. The cursor marks the position in the recordset to which you have already scrolled — the current record.

The Cursor Library and Level 1 ODBC Drivers

The ODBC Cursor Library gives Level 1 drivers the following new capabilities:

  • Forward and backward scrolling. Level 2 drivers don’t need the cursor library because they are already scrollable.

  • Support for snapshots. The cursor library manages a buffer containing the snapshot’s records. This buffer reflects your program’s deletions and edits to records but not the additions, deletions, or edits of other users, so the snapshot is only as current as the cursor library’s buffer. The buffer also does not reflect your own additions until you call Requery. Dynasets do not use the cursor library.

The cursor library will give you snapshots (static cursors) even if they are not normally supported by your driver. If your driver already supports static cursors, you don’t need to load the cursor library to get snapshot support. If you do use the cursor library, you can use only snapshots and forward-only recordsets. If your driver supports dynasets (KEYSET_DRIVEN cursors) and you want to use them, you must not use the cursor library. If you want to use both snapshots and dynasets, you must base them on two different CDatabase objects (two different connections) unless your driver supports both.

Positioned Updates and Timestamp Columns

****Note   ****ODBC data sources are accessible through the MFC ODBC classes, as described in this article, or through the MFC Data Access Object (DAO) classes. For information about the DAO classes, see the article DAO and MFC.

If your ODBC driver supports SQLSetPos, which MFC uses if available, this topic does not apply to you.

Most Level 1 drivers do not support positioned updates. Such drivers rely on the cursor library to emulate the capabilities of Level 2 drivers in this regard. The cursor library emulates positioned update support by doing a searched update on the unchanging fields.

In some cases, a recordset may contain a timestamp column as one of those unchanging fields. Two issues arise in using MFC recordsets with tables that contain timestamp columns.

The first issue concerns updatable snapshots on tables with timestamp columns. If the table to which your snapshot is bound contains a timestamp column, you should call Requery after you call Edit and Update. If not, you may not be able to edit the same record again. When you call Edit and then Update, the record is written to the data source and the timestamp column is updated. If you don’t call Requery, the timestamp value for the record in your snapshot no longer matches the corresponding timestamp on the data source. When you try to update the record again, the data source may disallow the update because of the mismatch.

The second issue concerns limitations of class when used with the RFX_Date function to transfer time and date information to or from a table. Processing the CTime object imposes some overhead in the form of extra intermediate processing during the data transfer. The date range of CTime objects may also be too limiting for some applications. A new version of the RFX_Date function takes an ODBC TIMESTAMP_STRUCT parameter instead of a CTime object. For more information, see RFX_Date in in the Class Library Reference.

Using the Cursor Library

When you connect to a data source — by calling or — you can specify whether to use the cursor library for the data source. If you will be creating snapshots on that data source, specify the CDatabase::useCursorLib option in the dwOptions parameter to OpenEx, or specify TRUE for the bUseCursorLib parameter to Open (the default value is TRUE). If your ODBC driver supports dynasets and you want to open dynasets on the data source, do not use the cursor library (it masks some driver functionality needed for dynasets). In that case, do not specify CDatabase::useCursorLib in OpenEx, or specify FALSE for the bUseCursorLib parameter in Open.