Home > Language Reference > Classes

Recordset Class

  + Object
    + Database
      + Recordset

Description

The Recordset class implements the methods for manipulating a table or a recordset resulting from a query. This class is not instantiable, derivable or cloneable. You can only use its methods through the derived classes generated by HB++ when you define tables in your project.

For each table included in your project, HB++ generates a class automatically having the name of the corresponding table, and deriving from Recordset. The member variables which the compiler declares in these classes allows you to access the various fields; the methods inherited from Recordset allows you to access to the various records.

At any moment, only one record is accessible through the Recordset object. A cursor is used to determine which, and to navigate through all the records. This cursor is managed by the AbsolutePosition, MoveFirst, MoveLast, MoveNext and MovePrevious methods. The BOF and EOF properties are used to determine if the cursor is positioned before the first record or after the last one. You can use these indicators to exit a loop which steps through all the records, for example.

If the table is open for writing, the AddNew method adds a new record, while the Edit method switches the Recordset object to edit mode. You can then modify the value of the fields, and the Update method validates these modifications. Depending on circumstances, the new record will not immediately appear in the recordset; you should re-execute the query using the Requery method.

In addition to the fields defined by the structure of the table, each record has a UniqueID property, that contains a single identifier allocated by the system when the record was created. This value never changes; it is a unique identifier that can be used to identify a record, for example when you want to express a relation or a join between two tables.

Each record also has a Category property containing a number ranging from 0 to 15, which can be used for any purpose. This field is specifically designed to implement the Palm OS^® application categories system. A significant characteristic of these two preset fields is that queries are carried out much quicker on them than on other fields, because they are stored directly in the record header. If you want to write powerful applications, you should use these fields.

You can create as many Recordset objects as you need. The only restriction is that a table can't be opened for writing twice. When a recordset is no longer needed, it should be closed with the Close method.

Refer to the Autograph sample to see how all the basic database management functions are used.

Members

System requirements