[This is preliminary documentation and subject to change.]
The Guide data objects provide a set of recordset objects, named in the format CTableNameRecordset, that each connect to the table in the Guide database indicated by TableName. Using these objects, you can:
As an example of using these techniques, see:
The recordset objects do not contain record data themselves. Instead, they create CTableName record objects to store the data. Each CTableName object corresponds to a single record in the Guide database.
A recordset or record object can be repeatedly opened and closed without the need for deleting an object and re-instantiating a new object. You can open a recordset by calling either the OpenRecordset or OpenIndexed method of the appropriate recordset object. For example, you can access the records of the Episode table using the CEpisodeTRecordset object. To open a recordset, you can call either the CEpisodeTRecordset::OpenRecordset or CEpisodeTRecordset::OpenIndexed method.
When a recordset is opened by the Jet database engine, it can be opened as either a dynaset or snapshot. A dynaset is essentially a list of pointers to the records in the table. In other words, data is only read from the database when a record is retrieved. A snapshot reads all records in the set into a RAM cache. Part of the design process for an application that uses the Jet database engine is to determine the type of acccess required. You should consult the DAO documentation for more information on the trade-offs involved.
By default, the Jet engine opens recordsets as dynasets. You can specify that the Jet engine open a recordset as a snapshot by setting a value for the optional nOpenType parameter of the appropriate OpenIndexed method.
Note also that the record count for a recordset is not automatically defined when you open the recordset. Therefore, when your application calls the appropriate GetRecordCount method, the method must move to the last record in the set to count the records. This process can be slow for large recordsets. To avoid counting, your application can open a recordset with an ORDER BY clause, which correctly sets the initial record count.
Once your application has opened a recordset, it can retrieve a record object from the recordset by calling the GetRecordsetObject or GetRecord methods of the corresponding recordset object. The former method returns a CTableName object that wraps the current recordset. The latter method returns an object that wraps the record in the recordset indicated by the specified index. Using the CTableName object, you can retrieve or set field values for the indexed record.
For example, you can get an individual Episode record by calling the CEpisodeTRecordset::GetRecord or CEpisodeTRecordset::GetRecordsetObject methods. Both methods create a CEpisodeT object. You can then manipulate the field values of the Episode record by using the methods of the CEpisodeT object.