dbOpenRecordset()

Synopsis

int dbOpenRecordset(dbConnection connection, string cmdStr, dbRecordset &recordset [, int cursorType]);

Parameters

Return Value

The return value is an error code; 0 indicates the operation has been performed successfully. For other values dbGetError() can be used to obtain detailed error information.

Errors

An error is returned if an invalid connection reference, an erroneous data selection command or an incorrect record set reference is passed.

Description

In order to be able to work on the data in a data source on a data-record basis, a record set must be opened, with the selection set specified by an SQL statement (parameter cmdStr).

Depending on the application, a so-called "Cursor type" can also be specified when the record set is opened (record sets are often portrayed as "cursors" in relational databases). The individual types have the following meanings:

• adOpenForwardOnly: the records can only be read in one direction (from start to finish); changes to the record set are not permitted.

• adOpenKeyset: the data can be read and modified in any way; records deleted or inserted by other users are not visible (although access to deleted records is locked); changes made by other users are visible.

• adOpenDynamic: the data can be read and modified in any way; records deleted or inserted by other users are visible, as are changes made by other users.

• adOpenStatic: the data can be read in any way, but cannot be modified; records deleted or inserted by other users, or changes made by other users, are not visible.

It should be noted that not all cursor types are available for all data sources.

The cursor type that is adequate for the application should always be used, as otherwise unnecessary locks in the database are created and additional resources taken up. The order in which resources are used is as follows in ascending order: adOpenForwardOnly - adOpenStatic - adOpenKeyset - adOpenDynamic.

For the cursor types adOpenKeyset and adOpenDynamic, pessimistic locking is used, i.e. the data records are locked when the first change is made to a field.

Each record set has an internal pointer to the current data record ("data record pointer"). All read and write methods on data fields (dbGetField() and dbPutField()) refer to this current record. The position of the current data record within the record set can be changed using the record set navigation methods (dbMove...). After opening the record set the pointer is positioned at the first data record of the record set. If the record set is empty, the data record pointer is undefined and no record set methods are permitted except for dbAddNew() and dbCloseRecordset().

Record sets opened successfully with dbOpenRecordset must be released again with dbCloseRecordset().

Example

main()
{
  int rc;
  dbConnection conn;
  dbRecordset rs;
  anytype fld;
  rc = dbOpenConnection ("DRIVER=Microsoft Access Driver
  (*.mdb);DBQ=TEST.MDB;
  DefaultDir=C:\\test\\jetdb;UID=;PWD=;", conn);
  if (!rc)
  {
    rc = dbOpenRecordset (conn, "SELECT * FROM PERS", rs);
    // The data subset is opened
    if (!rc)
    {
      while (!rc && !dbEOF (rs))
      // as long as the file end is not reached
      {
        rc = dbGetField (rs, 0, fld);
        //reads current column
        if (!rc)
        DebugN("Field 1: " , fld);
        rc = dbGetField (rs, 1, fld);
        if (!rc)
        DebugN("Field 2: " , fld);
        rc = dbMoveNext (rs); //to the next record
      }
      dbCloseRecordset (rs); //closes subset
    }
    dbCloseConnection (conn); //closes connection
  }
}

Assignment

ADO and Qt, Database functions

Availability

CTRL