_XOnDAO2_RecordSet_VIs.vi

Description

RSAddNew

Call this function to add a new record to a table-type or dynaset-type recordset. The record’s fields are initially Null. (In database terminology, Null means "having no value" and is not the same as NULL in C.!)

To complete the operation, you must call the RSUpdate function. Update saves your changes to the data source.

Caution: If you edit a record and then scroll to another record without calling Update, your changes are lost without warning.

If you add a record to a dynaset-type recordset by calling RSAddNew, the record is visible in the recordset and included in the underlying table where it becomes visible to any new Recordset objects.

The position of the new record depends on the type of recordset:

- In a dynaset-type recordset, records are inserted at the end

of the recordset, regardless of any sorting or ordering

rules that may have been in effect when the recordset was

opened.

- In a table-type recordset for which an index has been

specified, records are returned in their proper place in the

sort order. If no index has been specified, new records are

returned at the end of the recordset.

The record that was current before you used RSAddNew remains current. If you want to make the new record current and the recordset supports bookmarks, call RSSetBookmark to the bookmark identified by the LastModified property setting of the underlying DAO recordset object.

Doing so is useful for determining the value for counter (auto-increment) fields in an added record. For more information, see RSGetLastModifiedBookmark.

If the database supports transactions, you can make your RSAddNew call part of a transaction.

For more information about transactions, see the corresponding WS...-Functions.

Note that you should call WSBeginTrans before calling RSAddNew.

It is illegal to call RSAddNew for a recordset for which the RSOpen function has not been called.

A CDaoException is thrown if you call AddNew for a recordset that cannot be appended, causing this function to return -2.

You can determine whether the recordset is updatable by calling RSCanAppend.

The framework marks changed field data members to ensure they will be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you will seldom need to call RSSetFieldDirty yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of PSEUDO NULL.

If the double-buffering mechanism is not being used, then changing the value of the field does not automatically set the field as dirty. In this case, it will be necessary to explicitly set the field dirty. The flag contained in m_bCheckCacheForDirtyFields controls this automatic field checking.

Note: If records are double-buffered (that is, automatic field checking is enabled), calling RSCancelUpdate will restore the member variables to the values they had before RSAddNew or RSEdit was called.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSAddNew

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSCanAppend

Call this function to determine whether the previously opened recordset allows you to add new records by calling the RSAddNew member function.

Parameters

CanAppend Nonzero if the recordset allows adding new records;

otherwise -1 if Handle not initialized, -2 if Error.

RSCanAppend will return 0 if you opened the recordset as read-only.

RSCanAppend will also return 0 if the RSHDL is invalid.

rsHdl Handle of the Recordset

Connector Pane

RSCanAppend

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 CanAppend

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSCanBookmark

Call this function to determine whether the previously opened recordset allows you to individually mark records using bookmarks. If you are using recordsets based entirely on Microsoft Jet database engine tables, bookmarks can be used except on snapshot-type recordsets flagged as forward-only scrolling recordsets. Other database products (external ODBC data sources) may not support bookmarks.

Parameters

RSHandle in Handle of the Recordset (input)

RSHandle out Handle of the Recordset (output)

CanBookmark TRUE if the recordset supports bookmarks, otherwise FALSE.

Error Cluster as usual

XOn Software GmbH

Connector Pane

RSCanBookmark

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 CanBookmark

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSCancelUpdate

The CancelUpdate function cancels any pending updates due to an Edit or AddNew operation. For example, if an application calls the Edit or AddNew function and has not called Update, CancelUpdate cancels any changes made after Edit or AddNew was called.

NoteIf records are double-buffered (that is, automatic field checking is enabled), calling CancelUpdate will restore the member variables to the values they had before AddNew or Edit was called.

Parameters

RSHandle in Handle of the Recordset (input)

RSHandle out Handle of the Recordset (output)

Error Cluster as usual

XOn Software GmbH

Connector Pane

RSCancelUpdate

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSCanRestart

Call this function to determine whether the recordset allows restarting its query (to refresh its records) by calling the Requery function. Table-type recordsets do not support Requery.

If Requery is not supported, call Close then Open to refresh the data. You can call Requery to update a recordset object’s underlying parameter query after the parameter values have been changed.

Parameters

RSHandle in Handle of the Recordset (input)

RSHandle out Handle of the Recordset (output)

RSCanRestart TRUE if Requery can be called to run the recordset’s query again, otherwise

FALSE.

Error Cluster as usual

XOn Software GmbH

Connector Pane

RSCanRestart

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 RSCanRestart

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSCanScroll

Call this function to determine whether the recordset allows scrolling. If you call Open with dbForwardOnly (256), the recordset can only scroll forward.

Parameters

RSHandle in Handle of the Recordset (input)

RSHandle out Handle of the Recordset (output)

RSCanScroll TRUE if you can scroll through the records, otherwise FALSE.

Error Cluster as usual

XOn Software GmbH

Connector Pane

RSCanScroll

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 RSCanScroll

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSCanTransact

Call this function to determine whether the recordset allows transactions.

Parameters

RSHandle in Handle of the Recordset (input)

RSHandle out Handle of the Recordset (output)

RSCanTransact TRUE if the underlying data source supports transactions, otherwise FALSE.

Error Cluster as usual

XOn Software GmbH

Connector Pane

RSCanTransact

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 RSCanTransact

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSCanUpdate

Call this function to determine whether the recordset can be updated.

A recordset might be read-only if the underlying data source is read-only or if you specified dbReadOnly for Options when you called RSOpen for the recordset handle.

Parameters

CanUpdate Nonzero if the recordset can be updated (add, update, and delete records),

otherwise 0. RSCanUpdate will also return 0 if an Error occurred.

rsHdl Handle of the Recordset

Connector Pane

RSCanUpdate

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 CanUpdate

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSClose

Closing a Recordset object removes it from the collection of open recordsets in the associated database.

Because RSClose does not destroy the Recordset object, you can reuse the object by calling RSOpen on the same data source or a different data source.

All pending RSAddNew or RSEdit statements are canceled, and all pending transactions are rolled back.

If you want to preserve pending additions or edits, call RSUpdate before you call RSClose for each recordset.

You can call RSOpen again after calling RSClose. This lets you reuse the recordset object. A better alternative is to call RSRequery, if possible.

Parameters

rsHdl Handle of the new Recordset.

Connector Pane

RSClose

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSDelete

Call this function to delete the current record in an open dynaset-type or table-type recordset object.

After a successful deletion, the recordset’s field data members are set to a Null value, and you must explicitly call one of the recordset navigation functions (RSMove, RSSeek, RSSetBookmark, and so on) in order to move off the deleted record.

When you delete records from a recordset, there must be a current record in the recordset before you call RSDelete; otherwise, MFC throws an exception. You won't be able to recognise this as the exception is caught in DaoTool.dll.

RSDelete removes the current record and makes it inaccessible. Although you cannot edit or use the deleted record, it remains current. Once you move to another record, however, you cannot make the deleted record current again.

Caution: The recordset must be updatable and there must be a valid record current in the recordset when you call RSDelete. For example, if you delete a record but do not scroll to a new record before you call RSDelete again, RSDelete throws an Exception (You won't be able to recognise this! See above).

You can undelete a record if you use transactions and you call the WSRollback member function. If the base table is the primary table in a cascade delete relationship, deleting the current record may also delete one or more records in a foreign table.

Unlike RSAddNew and RSEdit, a call to RSDelete is not followed by a call to RSUpdate.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSDelete

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSDeleteRS

This function is Destructor of the Recordset Handle and returns the handle of the database used.

If the RSHDL was invalud, 0 is returned instead.

Parameters

rsHdl Handle of the new Recordset.

dbHdl The Handle of the Database the Recordset was connected to.

Connector Pane

RSDeleteRS

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 DBHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSEdit

Call this function to allow changes to the current record.

Once you call the RSEdit function, changes made to the current record’s fields are copied to the copy buffer. After you make the desired changes to the record, call RSUpdate to save your changes. RSEdit saves the values of the recordset’s data members. If you call RSEdit, make changes, then call RSEdit again, the record’s values are restored to what they were before the first RSEdit call.

Caution: If you edit a record and then perform any operation that moves to another record without first calling RSUpdate

, your changes are lost without warning. In addition, if you close the recordset or the parent database, your edited record is discarded without warning.

In some cases, you may want to update a column by making it Null (containing no data). To do so, call RSSetFieldNull with a parameter of TRUE to mark the field Null; this also causes the column to be updated. If you want a field to be written to the data source even though its value has not changed, call RSSetFieldDirty with a parameter of TRUE. This works even if the field had the value Null.

The framework marks changed field data members to ensure they will be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you will seldom need to call RSSetFieldDirty yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of PSEUDO NULL.

If the double-buffering mechanism is not being used, then changing the value of the field does not automatically set the field as dirty. In this case, it will be necessary to explicity set the field dirty.

When the recordset object is pessimistically locked in a multiuser environment, the record remains locked from the time RSEdit is used until the updating is complete. If the recordset is optimistically locked, the record is locked and compared with the pre-edited record just before it is updated in the database. If the record has changed since you called RSEdit, the RSUpdate operation fails and MFC throws an exception (You won't see this as the Exception is caught inside DaoTool.dll). You can change the locking mode with RSSetLockingMode.

Note: Optimistic locking is always used on external database formats, such as ODBC and installable ISAM.

The current record remains current after you call RSEdit. To call RSEdit, there must be a current record. If there is no current record or if the recordset does not refer to an open table-type or dynaset-type recordset object, an exception occurs (You won't see this, see above).

Calling RSEdit causes a Exception (You won't get it!) to be thrown under the following conditions:

* There is no current record.

* The database or recordset is read-only.

* No fields in the record are updatable.

* The database or recordset was opened for exclusive use by

another user.

* Another user has locked the page containing your record.

If the data source supports transactions, you can make the RSEdit call part of a transaction. Note that you should call WSBeginTrans before calling Edit and after the recordset has been opened. Also note that calling WSCommitTrans is not a substitute for calling RSUpdate to complete the RSEdit operation.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSEdit

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSFillCache

Call this function to cache a specified number of records from the recordset.

Caching improves the performance of an application that retrieves, or fetches, data from a remote server. A cache is space in local memory that holds the data most recently fetched from the server on the assumption that the data will probably be requested again while the application is running. When data is requested, the Microsoft Jet database engine checks the cache for the data first rather than fetching it from the server, which takes more time. Using data caching on non-ODBC data sources has no effect as the data is not saved in the cache.

Rather than waiting for the cache to be filled with records as they are fetched, you can explicitly fill the cache at any time by calling the RSFillCache function. This is a faster way to fill the cache because FillCache fetches several records at once instead of one at a time.

For example, while each screenful of records is being displayed, you can have your application call RSFillCache to fetch the next screenful of records.

Any ODBC database accessed with recordset objects can have a local cache. To create the cache, open a recordset object from the remote data source, and then call the RSSetCacheSize and RSSetCacheStart functions with the recordset handle.

If lSize and lBookmark create a range that is partly or wholly outside the range specified by RSSetCacheSize and RSSetCacheStart, the portion of the recordset outside this range is ignored and is not loaded into the cache.

If RSFillCache requests more records than remain in the remote data source, only the remaining records are fetched, and no exception is thrown.

Records fetched from the cache do not reflect changes made concurrently to the source data by other users.

FillCache fetches only records not already cached. To force an update of all the cached data, call the RSSetCacheSize member function with an lSize parameter equal to 0, call RSSetCacheSize again with the lSize parameter equal to the size of the cache you originally requested, and then call RSFillCache.

Parameters

rsHdl Handle of the Recordset

Size Specifies the number of rows to fill in the cache.

If you omit this parameter (setting it NULL), the value is determined by the CacheSize property setting of the underlying DAO object.

As the number is specified by reference, it might be possible (could be an undocumented feature) that the number actually written is returned. Even http://msdn.microsoft.com doesn't say anything about this.

ovHdl A COleVariant specifying a bookmark. The cache is filled starting

from the record indicated by this bookmark.

If you omit this parameter (setting it to 0), the cache is filled starting from the record indicated by the CacheStart property of the underlying DAO object.

Connector Pane

RSFillCache

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

ci32

 Size

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSFind

Call this function to locate a particular string in a dynaset- or snapshot-type recordset using a comparison operator.

You can find the first, next, previous, or last instance of the string.

To locate a record in a table-type recordset, call the RSSeek member function.

Tip: The smaller the set of records you have, the more effective RSFind will be.

In general, and especally with ODBC data, it is better to create a new query that retrieves just the records you want.

Parameters

error Errorcode of this operation:

-1 if handle not initialized,

-2 if an Error occurred,

1 if matching records are found,

0 otherwise

rsHdl Handle of the Recordset

FindType A value indicating the type of Find operation desired.

The possible values are:

Constant Value Description

================================================================

AFX_DAO_NEXT 1 Find the next location of a matching string.

AFX_DAO_PREV -1 Find the previous location of a matching string.

AFX_DAO_FIRST LONG_MIN Find the first location of a matching string.

AFX_DAO_LAST LONG_MAX Find the last location of a matching string.

Note that LONG_MIN is -2147483648 (0x80000000) while LONG_MAX is 2147483647 (0x7FFFFFFF)

Filter A string expression (like the WHERE clause in an SQL statement

without theword WHERE) used to locate the record.

For example:

RSFind(rsHdl, AFX_DAO_FIRST, "colRecID = 7")

RSFind(rsHdl, AFX_DAO_NEXT, "customerName = 'Jones'")

Connector Pane

RSFind

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Filter

ci32

 IFind Type

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSFindFirst

Call this function to find the first record that matches a specified condition.

The RSFindFirst function begins its search from the beginning of the recordset and searches to the end of the recordset.

If you want to include all the records in your search (not just those that meet a specific condition) use one of the RSMove operations to move from record to record.

To locate a record in a table-type recordset, call the RSSeek member function.

If a record matching the criteria is not located, the current record pointer is undetermined, and RSFind returns zero.

If the recordset contains more than one record that satisfies the criteria, RSFindFirst locates the first occurrence, RSFindNext locates the next occurrence, and so on.

Caution: If you edit the current record, be sure to save the changes by calling the RSUpdate function before you move to another record. If you move to another record without updating, your changes are lost without warning.

Important: When you call RSFindLast, the Microsoft Jet database engine fully populates your recordset before beginning the search, if this has not already been done. The first search may take longer than subsequent searches.

Using one of the RSFind operations is not the same as calling RSMoveFirst or RSMoveNext, however, which simply makes the first or next record current without specifying a condition. You can follow a RSFind operation with a RSMove operation.

Keep the following in mind when using the Find operations:

* If Find returns nonzero, the current record is not defined.

In this case, you must position the current record pointer

back to a valid record.

* You cannot use a Find operation with a forward-only scrolling

snapshot-type recordset.

* You should use the U.S. date format (month-day-year) when you

search for fields containing dates, even if you are not using

the U.S. version of the Microsoft Jet database engine;

otherwise, matching records may not be found.

* When working with ODBC databases and large dynasets, you may

discover that using the the Find operations is slow,

especially when working with large recordsets. You can

improve performance by using SQL queries with customized

ORDER BY or WHERE clauses, parameter queries, or Querydef

objects that retrieve specific indexed records.

Parameters

error Errorcode of this operation:

-1 if handle not initialized,

-2 if an Error occurred,

1 if matching records are found,

0 otherwise

rsHdl Handle of the Recordset

Filter A string expression (like the WHERE clause in an SQL statement without the

word WHERE) used to locate the record.

For example:

RSFind(rsHdl, AFX_DAO_FIRST, "colRecID = 7")

RSFind(rsHdl, AFX_DAO_NEXT, "customerName = 'Jones'")

Connector Pane

RSFindFirst

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Filter

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ibool

 no more results

RSFindLast

Call this function to find the last record that matches a specified condition.

The RSFindLast function begins its search at the end of the recordset and searches towards the beginning of the recordset.

If you want to include all the records in your search (not just those that meet a specific condition) use one of the RSMove

operations to move from record to record.

To locate a record in a table-type recordset, call the RSSeek member function.

If a record matching the criteria is not located, the current record pointer is undetermined, and RSFind returns zero.

If the recordset contains more than one record that satisfies the criteria, RSFindFirst locates the first occurrence, RSFindNext locates the next occurrence, and so on.

Caution: If you edit the current record, be sure to save the changes by calling the RSUpdate function before you move to another record. If you move to another record without updating, your changes are lost without warning.

Important: When you call RSFindLast, the Microsoft Jet database engine fully populates your recordset before beginning the search, if this has not already been done. The first search may take longer than subsequent searches.

Using one of the RSFind operations is not the same as calling RSMoveFirst or RSMoveNext, however, which simply makes the first or next record current without specifying a condition. You can follow a RSFind operation with a RSMove operation.

Keep the following in mind when using the Find operations:

* If Find returns nonzero, the current record is not defined.

In this case, you must position the current record pointer

back to a valid record.

* You cannot use a Find operation with a forward-only scrolling

snapshot-type recordset.

* You should use the U.S. date format (month-day-year) when you

search for fields containing dates, even if you are not using

the U.S. version of the Microsoft Jet database engine;

otherwise, matching records may not be found.

* When working with ODBC databases and large dynasets, you may

discover that using the the Find operations is slow,

especially when working with large recordsets. You can

improve performance by using SQL queries with customized

ORDER BY or WHERE clauses, parameter queries, or Querydef

objects that retrieve specific indexed records.

Parameters

error Errorcode of this operation:

-1 if handle not initialized,

-2 if an Error occurred,

1 if matching records are found,

0 otherwise

rsHdl Handle of the Recordset

Filter A string expression (like the WHERE clause in an SQL statement

without the word WHERE) used to locate the record.

For example:

RSFind(rsHdl, AFX_DAO_FIRST, "colRecID = 7")

RSFind(rsHdl, AFX_DAO_NEXT, "customerName = 'Jones'")

Connector Pane

RSFindLast

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Filter

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSFindNext

Call this function to find the next record that matches a specified condition.

The RSFindNext function begins its search at the current record and searches to the end of the recordset.

If you want to include all the records in your search (not just those that meet a specific condition) use one of the RSMove

operations to move from record to record.

To locate a record in a table-type recordset, call the RSSeek member function.

If a record matching the criteria is not located, the current record pointer is undetermined, and RSFind returns zero.

If the recordset contains more than one record that satisfies the criteria, RSFindFirst locates the first occurrence, RSFindNext locates the next occurrence, and so on.

Caution: If you edit the current record, be sure to save the changes by calling the RSUpdate function before you move to another record. If you move to another record without updating, your changes are lost without warning.

Important: When you call RSFindLast, the Microsoft Jet database engine fully populates your recordset before beginning the search, if this has not already been done. The first search may take longer than subsequent searches.

Using one of the RSFind operations is not the same as calling RSMoveFirst or RSMoveNext, however, which simply makes the first or next record current without specifying a condition. You can follow a RSFind operation with a RSMove operation.

Keep the following in mind when using the Find operations:

* If Find returns nonzero, the current record is not defined.

In this case, you must position the current record pointer

back to a valid record.

* You cannot use a Find operation with a forward-only scrolling

snapshot-type recordset.

* You should use the U.S. date format (month-day-year) when you

search for fields containing dates, even if you are not using

the U.S. version of the Microsoft Jet database engine;

otherwise, matching records may not be found.

* When working with ODBC databases and large dynasets, you may

discover that using the the Find operations is slow,

especially when working with large recordsets. You can

improve performance by using SQL queries with customized

ORDER BY or WHERE clauses, parameter queries, or Querydef

objects that retrieve specific indexed records.

Parameters

error Errorcode of this operation:

-1 if handle not initialized,

-2 if an Error occurred,

1 if matching records are found,

0 otherwise

rsHdl Handle of the Recordset

Filter A string expression (like the WHERE clause in an SQL statement

without the word WHERE) used to locate the record.

For example:

RSFind(rsHdl, AFX_DAO_FIRST, "colRecID = 7")

RSFind(rsHdl, AFX_DAO_NEXT, "customerName = 'Jones'")

Connector Pane

RSFindNext

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Filter

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ibool

 no more results

RSFindPrev

Call this function to find the previous record that matches a specified condition.

The RSFindPrev function begins its search at the current record and searches backwards towards the beginning of the recordset.

If you want to include all the records in your search (not just those that meet a specific condition) use one of the RSMove operations to move from record to record.

To locate a record in a table-type recordset, call the RSSeek member function.

If a record matching the criteria is not located, the current record pointer is undetermined, and RSFind returns zero.

If the recordset contains more than one record that satisfies the criteria, RSFindFirst locates the first occurrence, RSFindNext locates the next occurrence, and so on.

Caution: If you edit the current record, be sure to save the changes by calling the RSUpdate function before you move to another record. If you move to another record without updating, your changes are lost without warning.

Important: When you call RSFindLast, the Microsoft Jet database engine fully populates your recordset before beginning the search, if this has not already been done. The first search may take longer than subsequent searches.

Using one of the RSFind operations is not the same as calling RSMoveFirst or RSMoveNext, however, which simply makes the first or next record current without specifying a condition. You can follow a RSFind operation with a RSMove operation.

Keep the following in mind when using the Find operations:

* If Find returns nonzero, the current record is not defined.

In this case, you must position the current record pointer

back to a valid record.

* You cannot use a Find operation with a forward-only scrolling

snapshot-type recordset.

* You should use the U.S. date format (month-day-year) when you

search for fields containing dates, even if you are not using

the U.S. version of the Microsoft Jet database engine;

otherwise, matching records may not be found.

* When working with ODBC databases and large dynasets, you may

discover that using the the Find operations is slow,

especially when working with large recordsets. You can

improve performance by using SQL queries with customized

ORDER BY or WHERE clauses, parameter queries, or Querydef

objects that retrieve specific indexed records.

Parameters

error Errorcode of this operation:

-1 if handle not initialized,

-2 if an Error occurred,

1 if matching records are found,

0 otherwise

rsHdl Handle of the Recordset

Filter A string expression (like the WHERE clause in an SQL statement

without the word WHERE) used to locate the record.

For example:

RSFind(rsHdl, AFX_DAO_FIRST, "colRecID = 7")

RSFind(rsHdl, AFX_DAO_NEXT, "customerName = 'Jones'")

Connector Pane

RSFindPrev

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Filter

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetAbsolutePosition

Returns the record number of a recordset object’s current record.

The AbsolutePosition property value of the underlying DAO object is zero-based; a setting of 0 refers to the first record in the recordset.

You can determine the number of populated records in the recordset by calling RSGetRecordCount. Calling RSGetRecordCount may take some time because it must access all records to determine the count.

If there is no current record, as when there are no records in the recordset, -1 is returned. If the current record is deleted, the AbsolutePosition property value is not defined, and MFC throws an exception if it is referenced.

For dynaset-type recordsets, new records are added to the end of the sequence.

Note: This property is not intended to be used as a surrogate record number. Bookmarks are still the recommended way of retaining and returning to a given position and are the only way to position the current record across all types of recordset objects. In particular, the position of a given record changes when record(s) preceding it are deleted. There is also no assurance that a given record will have the same absolute position if the recordset is re-created again because the order of individual records within a recordset is not guaranteed unless it is created with an SQL statement using an ORDER BY clause.

Note: This function is valid only for dynaset-type and snapshot-type recordsets.

Parameters

Result An integer from 0 to the number of records in the recordset.

Corresponds to the

ordinal position of the current record in the recordset.

Also 0 when an error occurred (invalid handle or exception).

rsHdl Handle of the Recordset

Connector Pane

RSGetAbsolutePosition

Controls and Indicators

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

cdlrn

 RSHandle in

ii32

 Result

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

RSGetBookmark

Call this function to obtain the bookmark value in a particular record.

When a recordset object is created or opened, each of its records already has a unique bookmark if it supports them.

Call RSCanBookmark to determine whether a recordset supports bookmarks.

You can save the bookmark for the current record by assigning the value of the bookmark to a COleVariant object. To quickly return to that record at any time after moving to a different record, call RSSetBookmark with a parameter corresponding to the value of that COleVariant object.

Parameters

rsHdl Handle of the Recordset

ovHdl Will contain a COleVariant value representing the bookmark on the

current record.

Connector Pane

RSGetBookmark

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetCacheSize

Call this function to obtain the number of records cached.

Data caching improves the performance of an application that retrieves data from a remote server through dynaset-type recordset objects.

A cache is a space in local memory that holds the data most recently retrieved from the server in the event that the data will be requested again while the application is running. When data is requested, the Microsoft Jet database engine checks the cache for the requested data first rather than retrieving it from the server, which takes more time.

Data that does not come from an ODBC data source is not saved in the cache. Any ODBC data source, such as an attached table, can have a local cache.

Parameters

CacheSize A value that specifies the number of records in a dynaset-type recordset

containing data to be locally cached from an ODBC data source.

Will be 0 if an Error occurred.

rsHdl Handle of the Recordset

Connector Pane

RSGetCacheSize

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 CacheSize

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetCacheStart

Call this function to obtain the bookmark value of the first record in the recordset to be cached. The Microsoft Jet database engine requests records within the cache range from the cache, and it requests records outside the cache range from the server.

Note: Records retrieved from the cache do not reflect changes made concurrently to the source data by other users.

Parameters

rsHdl Handle of the Recordset

ovHdl A COleVariant that will specify the bookmark of the first record in the

recordset to be cached

Connector Pane

RSGetCacheStart

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetCurrentIndex

This function returns the index currently in use with a table-type Recordset .

Parameters

rsHdl Handle of the Recordset

CurrentIndex The name of the index currently in use with a table-type recordset.

Returns an empty string if no index has been set.

maxlen Max. length of CurrentIndex

Connector Pane

RSGetCurrentIndex

Controls and Indicators

cdlrn

 RSHandle in

cu32

 maxlen

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

istr

 CurrentIndex

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetDateCreated

Call this function to retrieve the date and time a base table was created.

Date and time settings are derived from the computer on which the base table was created.

Parameters

DateCreated A DATE value containing the date and time the base table was created.

Returns (DATE) 0 if an Error occurred.

rsHdl Handle of the Recordset

Connector Pane

RSGetDateCreated

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idbl

 DateCreated

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetDateLastUpdated

Call this function to retrieve the date and time a base table was last updated.

Date and time settings are derived from the computer on which the base table was last updated.

Parameters

DateLastUpdated A DATE value containing the date and time the base table last

updated. Returns (DATE) 0 if an Error occurred.

rsHdl Handle of the Recordset

Connector Pane

RSGetDateLastUpdated

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idbl

 DateLastUpdated

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetDefaultDBName

Call this function to determine the name of the database for this recordset.

If a recordset is created without a pointer to a CDaoDatabase, then this path is used by the recordset to open the default database.

Parameters

rsHdl Handle of the Recordset

DefaultDBName Will contain the path and name of the database from which this

recordset is derived.

maxlen Max. length of DefaultDBName

Connector Pane

RSGetDefaultDBName

Controls and Indicators

cu32

 maxlen

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

istr

 DefaultDBName

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetDefaultSQL

The framework calls this function to get the default SQL statement on which the recordset is based.

This might be a table name or an SQL SELECT statement.

If you pass a null SQL string to RSOpen, then this function is called to determine the table name or SQL for your recordset.

Parameters

rsHdl Handle of the Recordset

DefaultSQL Will contain the default SQL statement.

maxlen Max. length of DefaultSQL

Connector Pane

RSGetDefaultSQL

Controls and Indicators

cu32

 maxlen

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

cdlrn

 RSHandle in

istr

 DefaultSQL

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

RSGetEditMode

Call this member function to determine the state of editing.

Parameters

FResult values:

Constant Value Description

========================================================

dbEditNone 0 No editing operation is in progress.

dbEditInProgress 1 Edit has been called.

dbEditAdd 2 AddNew has been called.

rsHdl Handle of the Recordset

Connector Pane

RSGetEditMode

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ienum

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetFieldCount

Call this member function to retrieve the number of fields (columns) defined in the recordset.

Parameters

FieldCount -1 if handle not initialized, -2 if an Error occurred.

Any other value represents the number of fields defined in the recordset.

rsHdl Handle of the Recordset

Connector Pane

RSGetFieldCount

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

iu16

 FieldCount

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetFieldInfoByIdx

Call this function to obtain information about the fields in a recordset.

One version of the function (this one) lets you look up a field by index.

The other version (RSGetFieldInfoByName) lets you look up a field by name.

For a description of the information returned in fiHdl, see the FI...-Functions. These all return certain items of information.

Parameters

rsHdl Handle of the Recordset

Index The zero-based index of the predefined field in the recordset’s Fields collection

fiHdl A handle of a FieldInfo object that will contain the information requested.

Connector Pane

RSGetFieldInfoByIdx

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 FIHandle in

ci32

 Index

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 FIHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetFieldInfoByName

Call this function to obtain information about the fields in a recordset.

One version of the function (this one) lets you look up a Field by name.

The other version (RSGetFieldInfoByIdx) lets you look up a Field by Index.

For a description of the information returned in fiHdl, see the FI...-Functions. These all return certain items of information.

Parameters

rsHdl Handle of the Recordset

Name A string containing the name of the desired field

fiHdl A handle of a FieldInfo object that will contain the information requested.

Connector Pane

RSGetFieldInfoByName

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 FIHandle in

cstr

 FieldName

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 FIHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetFieldValueByIdx

Call this function to retrieve data in a recordset.

You can look up a field by name or by ordinal position.

Use RSGetFieldValue and RSSetFieldValue to dynamically bind fields at run time rather than statically binding columns using the RSDoFieldExchange mechanism.

RSGetFieldValue and the RSDoFieldExchange mechanism can be combined to improve performance.

For example, use RSGetFieldValue to retrieve a value that you need only on demand, and assign that call to a "More Information" button in the interface.

Parameters

rsHdl Handle of the Recordset

Index The zero-based index of the predefined field in the recordset’s Fields collection

ovHdl A handle of a OLE object that will contain the information requested.

Connector Pane

RSGetFieldValueByIdx

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

ci32

 Index

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetFieldValueByName

Call this function to retrieve data in a recordset.

You can look up a field by name or by ordinal position.

Use RSGetFieldValue and RSSetFieldValue to dynamically bind fields at run time rather than statically binding columns using the RSDoFieldExchange mechanism.

RSGetFieldValue and the RSDoFieldExchange mechanism can be combined to improve performance.

For example, use RSGetFieldValue to retrieve a value that you need only on demand, and assign that call to a "More Information" button in the interface.

Parameters

rsHdl Handle of the Recordset

Name A string containing the name of the desired field

ovHdl A handle of a OLE object that will contain the information requested.

Connector Pane

RSGetFieldValueByName

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

cstr

 Name

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetIndexCount

Call this function to determine the number of indexes available on the table-type recordset.

RSGetIndexCount is useful for looping through all indexes in the recordset. For that purpose, use RSGetIndexCount in conjunction with the RSGetIndexInfoBy functions.

If you call this function on dynaset-type or snapshot-type recordsets, MFC throws an exception.

Parameters

error Errorcode of this operation:

0 if handle not initialized, or an Error occurred.

Any other value represents the number of indexes in the table-type recordset.

rsHdl Handle of the Recordset

Connector Pane

RSGetIndexCount

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

iu16

 IndexCount

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetIndexInfoByIdx

Call this function to obtain various kinds of information about an index defined in the base table underlying a recordset.

One version of the function lets you look up a index by its position in the collection. The other version lets you look up an index by name.

For a description of the information returned in iiHdl, see the II...-Functions. These all return certain items of information.

Parameters

rsHdl Handle of the Recordset

Index The zero-based index in the table’s Indexes collection

iiHdl A handle of a IndexInfo object that will contain the information requested.

Connector Pane

RSGetIndexInfoByIdx

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 IIHandle in

ci32

 Index(0)

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 IIHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetIndexInfoByName

Call this function to obtain various kinds of information about an index defined in the base table underlying a recordset.

One version of the function lets you look up a index by its position in the collection. The other version lets you look up an index by name.

For a description of the information returned in iiHdl, see the II...-Functions. These all return certain items of information.

Parameters

rsHdl Handle of the Recordset

Name A pointer to the name of the index object

iiHdl A handle of a IndexInfo object that will contain the information requested.

Connector Pane

RSGetIndexInfoByName

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 IIHandle in

cstr

 Name

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 IIHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetLastModifiedBookmark

Call this function to retrieve the bookmark of the most recently added or updated record.

When a recordset object is created or opened, each of its records already has a unique bookmark if it supports them.

Call RSCanBookmark to determine if the recordset supports bookmarks. If the recordset does not support bookmarks, a CDaoException is thrown.

When you add a record, it appears at the end of the recordset, and is not the current record. To make the new record current, call RSGetLastModifiedBookmark and then call RSSetBookmark to return to the newly added record.

Parameters

rsHdl Handle of the Recordset

ovHdl Will contain a COleVariant value representing the bookmark that indicates the most recently added or changed record.

Connector Pane

RSGetLastModifiedBookmark

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetLockingMode

Call this function to determine the type of locking in effect for the recordset.

When pessimistic locking is in effect, the data page containing the record you are editing is locked as soon as you call the RSEdit function.

The page is unlocked when you call the RSUpdate or RSClose function or any of the RSMove or RSFind operations.

When optimistic locking is in effect, the data page containing the record is locked only while the record is being updated with the RSUpdate member function.

When working with ODBC data sources, the locking mode is always optimistic.

Parameters

LockingMode Nonzero if the type of locking is pessimistic,

otherwise 0 for optimistic record locking.

RSGetLockingMode will also return 0 if an Error occurred.

rsHdl Handle of the Recordset

Connector Pane

RSGetLockingMode

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 LockingMode

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetName

Call this function to retrieve the name of the recordset.

The name of the recordset must start with a letter and can contain a maximum of 40 characters. It can include numbers and underscore characters but can’t include punctuation or spaces.

Parameters

rsHdl Handle of the Recordset

Name Will contain the name of the recordset.

maxlen Max. length of Name

Connector Pane

RSGetName

Controls and Indicators

cdlrn

 RSHandle in

cu32

 maxlen

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

istr

 Name

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetParamValueByIdx

Call this function to retrieve the current value of the specified parameter stored in the underlying DAOParameter object.

You can access the parameter either by name or by its numerical position in the collection.

Parameters

rsHdl Handle of the Recordset

Index The numerical position of the parameter in the underlying DAOParameter object.

ovHdl A handle of a COleVariant object that will contain the parameter's value.

Connector Pane

RSGetParamValueByIdx

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

ci32

 Index

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetParamValueByName

Call this function to retrieve the current value of the specified parameter stored in the underlying DAOParameter object.

You can access the parameter either by name or by its numerical position in the collection.

Parameters

rsHdl Handle of the Recordset

Name The name of the parameter whose value you want to.

ovHdl A handle of a COleVariant object that will contain the parameter's value.

Connector Pane

RSGetParamValueByName

Controls and Indicators

cdlrn

 RSHandle in

cdlrn

 OVHandle in

cstr

 Name

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetPercentPosition

When working with a dynaset-type or snapshot-type recordset, if you call RSGetPercentPosition before fully populating the recordset, the amount of movement is relative to the number of records accessed as indicated by calling RSGetRecordCount.

You can move to the last record by calling RSMoveLast to complete the population of all recordsets, but this may take a significant amount of time.

You can call RSGetPercentPosition on all three types of recordset objects, including tables without indexes.

However, a CDaoException is thrown if you call RSGetPercentPosition on forward-only scrolling snapshots, or on a recordset opened from a pass-through query against an external database, if there is no current record, or the current record has been deleted.

Parameters

PercentPosition A number between 0 and 100 that indicates the approximate location of the current record in the recordset object based on a percentage of the records in the recordset. Returns 0.0 if any kind of Error occurred.

rsHdl Handle of the Recordset

Connector Pane

RSGetPercentPosition

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

isgl

 PercentPosition

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetRecordCount

Call this function to find out how many records in a recordset have been accessed.

RSGetRecordCount does not indicate how many records are contained in a dynaset-type or snapshot-type recordset until all records have been accessed.

This member function call may take a significant amount of time to complete.

Once the last record has been accessed, the return value indicates the total number of undeleted records in the recordset. To force the last record to be accessed, call the RSMoveLast or RSFindLast member function for the recordset. You can also use a SQL Count to determine the approximate number of records your query will return.

As your application deletes records in a dynaset-type recordset, the return value of GetRecordCount decreases. However, records deleted by other users are not reflected by RSGetRecordCount until the current record is positioned to a deleted record.

If you execute a transaction that affects the record count and subsequently roll back the transaction, RSGetRecordCount will not reflect the actual number of remaining records.

The value of RSGetRecordCount from a snapshot-type recordset is not affected by changes in the underlying tables.

The value of RSGetRecordCount from a table-type recordset reflects the approximate number of records in the table and is affected immediately as table records are added and deleted.

A recordset with no records returns a value of 0 (Note that this value is also returned in an error case!).

When working with attached tables or ODBC databases, GetRecordCount always returns -1.

Calling the RSRequery function on a recordset resets the value of RSGetRecordCount just as if the query were re-executed.

Parameters

RecordCount Returns the number of records in a recordset.

0 when an error occurred (invalid handle or exception).

rsHdl Handle of the Recordset

Connector Pane

RSGetRecordCount

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 Record Count

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetSQL

Call this function to get the SQL statement that was used to select the recordset’s records when it was opened.

This will generally be an SQL SELECT statement.

The string returned by RSGetSQL is typically different from any string you may have passed to the recordset in the lpszSQL parameter to the RSOpen member function. This is because the recordset constructs a full SQL statement based on what you passed to RSOpen.

Important: Call this member function only after calling RSOpen.

Parameters

rsHdl Handle of the Recordset

SQL Will contain the SQL statement.

maxlen Max. length of SQL

Connector Pane

RSGetSQL

Controls and Indicators

cu32

 maxlen

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

istr

 SQL

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetType

Call this member function after opening the recordset to determine the type of the recordset object.

Parameters

FResult Type

rsHdl Handle of the Recordset

Possible Types are:

Constant Name Value Description

================================================================

dbOpenDynaset 2 A dynaset-type recordset with

bidirectional scrolling. (default)

dbOpenTable 1 A table-type recordset with

bidirectional scrolling.

dbOpenSnapshot 4 A snapshot-type recordset with

bidirectional scrolling.

Connector Pane

RSGetType

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii16

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetValidationRule

Call this member function to determine the rule used to validate data.

This rule is text-based, and is applied each time the underlying table is changed.

If the data is not legal, MFC throws an exception. The returned error message is the text of the ValidationText property of the underlying field object, if specified, or the text of the expression specified by the ValidationRule property of the underlying field object.

You can call RSGetValidationText to obtain the text of the error message.

For example, a field in a record that requires the day of the month might have a validation rule such as "DAY BETWEEN 1 AND 31."

Parameters

rsHdl Handle of the Recordset

ValidationRule Will contain a value that validates the data in a record as it is changed or

added to a table.

maxlen Max. length of ValidationRule

Connector Pane

RSGetValidationRule

Controls and Indicators

cdlrn

 RSHandle in

cu32

 maxlen

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

istr

 ValidationRule

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSGetValidationText

Call this member function to retrieve the text of the ValidationText property of the underlying field object.

Parameters

rsHdl Handle of the Recordset

ValidationText Will contain the text of the message that is displayed if the value of a field does

not satisfy the validation rule of the underlying field object.

maxlen Max. length of ValidationText

Connector Pane

RSGetValidationText

Controls and Indicators

cdlrn

 RSHandle in

cu32

 maxlen

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

istr

 ValidationText

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsBOF

Call this function before you scroll from record to record to learn whether you have gone before the first record of the recordset.

You can also call RSIsBOF along with RSIsEOF to determine whether the recordset contains any records or is empty. Immediately after you call RSOpen, if the recordset contains no records, RSIsBOF returns nonzero. When you open a recordset that has at least one record, the first record is the current record and RSIsBOF returns 0.

If the first record is the current record and you call RSMovePrev, RSIsBOF will subsequently return nonzero. If RSIsBOF returns nonzero and you call RSMovePrev, an exception is thrown. If RSIsBOF returns nonzero, the current record is undefined, and any action that requires a current record will result in an exception.

Effect of specific functions on RSIsBOF and RSIsEOF settings:

* Calling Open internally makes the first record in the

recordset the current record by calling RSMoveFirst.

Therefore, calling Open on an empty set of records causes

IsBOF and IsEOF to return nonzero. (See the following table

for the behavior of a failed RSMoveFirst or RSMoveLast call)

* All RSMove operations that successfully locate a record cause

both RSIsBOF and RSIsEOF to return 0.

* An RSAddNew call followed by an RSUpdate call that

successfully inserts a new record will cause IsBOF to return

0, but only if RSIsEOF is already nonzero. The state of

RSIsEOF will always remain unchanged. As defined by the

Microsoft Jet database engine, the current record pointer of

an empty recordset is at the end of a file, so any new record

is inserted after the current record.

* Any RSDelete call, even if it removes the only remaining

record from a recordset, will not change the value of RSIsBOF

or RSIsEOF.

This table shows which Move operations are allowed with different combinations of RSIsBOF/RSIsEOF.

BOF EOF || MoveFirst, MovePrev, MoveNext,

|| MoveLast, Move < 0 Move 0 Move > 0

==========++====================================================

N 0 || Allowed Exception Exception Allowed

0 N || Allowed Allowed Exception Exception

N N || Exception Exception Exception Exception

0 0 || Allowed Allowed Allowed Allowed

(where N=nonzero)

Allowing a Move operation does not mean that the operation will successfully locate a record. It merely indicates that an attempt to perform the specified Move operation is allowed and will not generate an exception. The value of the RSIsBOF and RSIsEOF functions may change as a result of the attempted move.

The effect of Move operations that do not locate a record on the value of RSIsBOF and RSIsEOF settings is shown in the following table.

Operation || RSIsBOF RSIsEOF

==========================++====================================

MoveFirst, MoveLast || Nonzero Nonzero

Move 0 || No Change No Change

MovePrev, Move < 0 || Nonzero No Change

MoveNext, Move > 0 || No change Nonzero

Parameters

IsBOF Nonzero if the recordset contains no records or if you have scrolled

backward before the first record; otherwise 0. Also 0 in case of Error.

rsHdl Handle of the Recordset

Connector Pane

RSIsBOF

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsBOF

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsDeleted

Call this function to determine whether the current record has been deleted.

If you scroll to a record and IsDeleted returns TRUE (nonzero), then you must scroll to another record before you can perform any other recordset operations.

Note: You don't need to check the deleted status for records in a snapshot or table-type recordset. Because records cannot be deleted from a snapshot, there is no need to call RSIsDeleted.

For table-type recordsets, deleted records are actually removed from the recordset. Once a record has been deleted, either by you, another user, or in another recordset, you cannot scroll back to that record. Therefore, there is no need to call RSIsDeleted.

When you delete a record from a dynaset, it is removed from the recordset and you cannot scroll back to that record. However, if a record in a dynaset is deleted either by another user or in another recordset based on the same table, RSIsDeleted will return TRUE when you later scroll to that record.

Parameters

IsDeleted Nonzero if the recordset is positioned on a deleted record; otherwise 0.

Will also return 0 if an Error occurred.

rsHdl Handle of the Recordset

Connector Pane

RSIsDeleted

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsDeleted

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsEOF

Call this member function as you scroll from record to record to learn whether you have gone beyond the last record of the recordset.

You can also call RSIsBOF along with RSIsEOF to determine whether the recordset contains any records or is empty. Immediately after you call RSOpen, if the recordset contains no records, RSIsBOF returns nonzero. When you open a recordset that has at least one record, the first record is the current record and RSIsBOF returns 0.

If the first record is the current record and you call RSMovePrev, RSIsBOF will subsequently return nonzero. If RSIsBOF returns nonzero and you call RSMovePrev, an exception is thrown. If RSIsBOF returns nonzero, the current record is undefined, and any action that requires a current record will result in an exception.

Effect of specific functions on RSIsBOF and RSIsEOF settings:

* Calling Open internally makes the first record in the

recordset the current record by calling RSMoveFirst.

Therefore, calling Open on an empty set of records causes

IsBOF and IsEOF to return nonzero. (See the following table

for the behavior of a failed RSMoveFirst or RSMoveLast call)

* All RSMove operations that successfully locate a record cause

both RSIsBOF and RSIsEOF to return 0.

* An RSAddNew call followed by an RSUpdate call that

successfully inserts a new record will cause IsBOF to return

0, but only if RSIsEOF is already nonzero. The state of

RSIsEOF will always remain unchanged. As defined by the

Microsoft Jet database engine, the current record pointer of

an empty recordset is at the end of a file, so any new record

is inserted after the current record.

* Any RSDelete call, even if it removes the only remaining

record from a recordset, will not change the value of RSIsBOF

or RSIsEOF.

This table shows which Move operations are allowed with different combinations of RSIsBOF/RSIsEOF.

BOF EOF || MoveFirst, MovePrev, MoveNext,

|| MoveLast, Move < 0 Move 0 Move > 0

==========++====================================================

N 0 || Allowed Exception Exception Allowed

0 N || Allowed Allowed Exception Exception

N N || Exception Exception Exception Exception

0 0 || Allowed Allowed Allowed Allowed

(where N=nonzero)

Allowing a Move operation does not mean that the operation will successfully locate a record. It merely indicates that an attempt to perform the specified Move operation is allowed and will not generate an exception. The value of the RSIsBOF and RSIsEOF functions may change as a result of the attempted move.

The effect of Move operations that do not locate a record on the value of RSIsBOF and RSIsEOF settings is shown in the following table.

Operation || RSIsBOF RSIsEOF

==========================++====================================

MoveFirst, MoveLast || Nonzero Nonzero

Move 0 || No Change No Change

MovePrev, Move < 0 || Nonzero No Change

MoveNext, Move > 0 || No change Nonzero

Parameters

IsEOF Nonzero if the recordset contains no records or if you have scrolled

beyond the last record; otherwise 0. Also 0 in case of Error.

rsHdl Handle of the Recordset

Connector Pane

RSIsEOF

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsEOF

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsFieldDirty

Call this member function to determine whether the specified field data member of a dynaset has been flagged as "dirty" (changed).

The data in all dirty field data members will be transferred to the record on the data source when the current record is updated by a call to the RSUpdate function on the CDaoRecordset (following a call to RSEdit or RSAddNew).

With this knowledge, you can take further steps, such as unflagging the field data member to mark the column so it will not be written to the data source.

RSIsFieldDirty is implemented through DoFieldExchange.

Parameters

FieldIsDirty Nonzero if the specified field data member is flagged as dirty; otherwise 0.

Also 0 in case of Error.

rsHdl Handle of the Recordset

pv A pointer to the field data member whose status you want to check,

or NULL to determine if any of the fields are dirty.

Connector Pane

RSIsFieldDirty

Controls and Indicators

cdlrn

 RSHandle in

cu32

 pv

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 FieldIsDirty

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsFieldNullableByName

Connector Pane

RSIsFieldNullableByName

Controls and Indicators

cdlrn

 RSHandle in

cstr

 FieldName

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsFieldNullableByName

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsFieldNullableByRef

Call this function to to determine whether the specified field data member is "nullable" (can be set to a Null value; C NULL is not the same as Null, which, in database terminology, means "having no value").

A field that cannot be Null must have a value. If you attempt to set such a field to Null when adding or updating a record, the data source rejects the addition or update, and RSUpdate will throw an exception. The exception occurs when you call RSUpdate, not when you call RSSetFieldNull.

Parameters

IsFieldNullableByRef Nonzero if the specified field data member can be made Null; otherwise 0. Also 0 in case of Error.

rsHdl Handle of the Recordset

pv A pointer to the field data member whose status you want to check, or NULL to determine if any of the fields are Null.

Connector Pane

RSIsFieldNullableByRef

Controls and Indicators

cdlrn

 RSHandle in

cu32

 pv

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsFieldNullableByRef

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsFieldNullByName

Connector Pane

RSIsFieldNullByName

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Field

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsFieldNull

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsFieldNullByRef

Call this function to determine whether the specified field data member of a recordset has been flagged as Null.

(In database terminology, Null means "having no value" and is not the same as NULL in C.)

If a field data member is flagged as Null, it is interpreted as a column of the current record for which there is no value.

Note: In certain situations, using RSIsFieldNull can be inefficient, as the following code example illustrates:

OVHDL valhdl;

RSHDL rshdl;

// this code is inefficient because data must be retrieved

// for both RSIsFieldNull and RSGetFieldValue

if ( !RSIsFieldNull(rshdl, nField) )

RSGetFieldValue(rshdl, nField, hdl);

// this code is more efficient

RSGetFieldValue(rshdl, nField, varValue);

if ( OVGetvt(valhdl) == VT_NULL )

// do something

Parameters

IsFieldNull Nonzero if the specified field data member is flagged as Null; otherwise 0.

Also 0 in case of Error.

rsHdl Handle of the Recordset

FieldReference A pointer to the field data member whose status you want to check,

or NULL to determine if any of the fields are Null.

Connector Pane

RSIsFieldNullByRef

Controls and Indicators

cdlrn

 RSHandle in

cu32

 FieldReference

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsFieldNull

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSIsOpen

Call this member function to determine if the recordset is open.

Parameters

IsOpen Nonzero if the recordset object’s RSOpen or RSRequery member function has previously been called and the recordset has not been closed; otherwise 0.

Also 0 in case of Error.

Connector Pane

RSIsOpen

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 IsOpen

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSMove

Call this function to position the recordset lRows records from the current record. You can move forward or backward. RSMove(hdl,1) is equivalent to RSMoveNext(hdl), and RSMove(hdl,-1) is equivalent to RSMovePrev(hdl).

Caution: Calling any of the Move functions throws an exception if the recordset has no records. In general, call both RSIsBOF and RSIsEOF before a Move operation to determine whether the recordset has any records.

After you call RSOpen or RSRequery, call either IsBOF or IsEOF.

If you have scrolled past the beginning or end of the recordset (RSIsBOF or RSIsEOF returns nonzero), a call to RSMove throws a CDaoException. It will be caught by DaoTool.dll.

If you call any of the Move functions while the current record is being updated or added, the updates are lost without warning.

When you call Move on a forward-only scrolling snapshot, the lRows parameter must be a positive integer and bookmarks are not allowed, so you can move forward only.

To make the first, last, next, or previous record in a recordset the current record, call the RSMoveFirst, RSMoveLast, RSMoveNext, or RSMovePrev function.

Parameters

rsHdl Handle of the Recordset

rows The number of records to move forward or backward.

Positive values move forward, toward the end of the recordset.

Negative values move backward, toward the beginning.

Connector Pane

RSMove

Controls and Indicators

cdlrn

 RSHandle in

cu32

 rows

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSMoveFirst

Call this function to make the first record in the recordset (if any) the current record. You do not have to call MoveFirst immediately after you open the recordset. At that time, the first record (if any) is automatically the current record.

Caution: Calling any of the Move functions throws an exception if the recordset has no records. In general, call both RSIsBOF and RSIsEOF before a Move operation to determine whether the recordset has any records.

After you call RSOpen or RSRequery, call either IsBOF or IsEOF.

If you have scrolled past the beginning or end of the recordset (RSIsBOF or RSIsEOF returns nonzero), a call to RSMove throws a CDaoException. It will be caught by DaoTool.dll.

If you call any of the Move functions while the current record is being updated or added, the updates are lost without warning.

Use the Move functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call RSSeek.

If the recordset refers to a table-type recordset, movement follows the table’s current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined.

If you call RSMoveLast on a recordset object based on an SQL query or querydef, the query is forced to completion and the recordset object is fully populated.

You cannot call the RSMoveFirst or RSMovePrev member function with a forward-only scrolling snapshot.

To move the position of the current record in a recordset object a specific number of records forward or backward, call RSMove.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSMoveFirst

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSMoveLast

Call this function to make the last record (if any) in the recordset the current record.

Caution: Calling any of the Move functions throws an exception if the recordset has no records. In general, call both RSIsBOF and RSIsEOF before a Move operation to determine whether the recordset has any records.

After you call RSOpen or RSRequery, call either IsBOF or IsEOF.

If you call any of the Move functions while the current record is being updated or added, the updates are lost without warning.

Use the Move functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call RSSeek.

If the recordset refers to a table-type recordset, movement follows the table’s current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined.

If you call RSMoveLast on a recordset object based on an SQL query or querydef, the query is forced to completion and the recordset object is fully populated.

To move the position of the current record in a recordset object a specific number of records forward or backward, call RSMove.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSMoveLast

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSMoveNext

Call this function to make the next record in the recordset the current record.

It is recommended that you call RSIsEOF before you attempt to move to the previous record. A call to RSMoveNext will throw a CDaoException if RSIsEOF returns nonzero, indicating either that you have already scrolled past the last record or that no records were selected by the recordset.

Caution: Calling any of the Move functions throws an exception if the recordset has no records. In general, call both RSIsBOF and RSIsEOF before a Move operation to determine whether the recordset has any records.

After you call RSOpen or RSRequery, call either IsBOF or IsEOF.

If you call any of the Move functions while the current record is being updated or added, the updates are lost without warning.

Use the Move functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call RSSeek.

If the recordset refers to a table-type recordset, movement follows the table’s current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined.

To move the position of the current record in a recordset object a specific number of records forward or backward, call RSMove.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSMoveNext

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSMovePrev

Call this function to make the previous record in the recordset the current record.

It is recommended that you call RSIsBOF before you attempt to move to the previous record. A call to RSMovePrev will throw a CDaoException if RSIsBOF returns nonzero, indicating either that you have already scrolled before the first record or that no records were selected by the recordset.

Caution: Calling any of the Move functions throws an exception if the recordset has no records. In general, call both RSIsBOF and RSIsEOF before a Move operation to determine whether the recordset has any records.

After you call RSOpen or RSRequery, call either IsBOF or IsEOF.

If you call any of the Move functions while the current record is being updated or added, the updates are lost without warning.

Use the Move functions to move from record to record without applying a condition. Use the Find operations to locate records in a dynaset-type or snapshot-type recordset object that satisfy a certain condition. To locate a record in a table-type recordset object, call RSSeek.

If the recordset refers to a table-type recordset, movement follows the table’s current index. You can set the current index by using the Index property of the underlying DAO object. If you do not set the current index, the order of returned records is undefined.

To move the position of the current record in a recordset object a specific number of records forward or backward, call RSMove.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSMovePrev

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSNewRS

Constructs a CDaoRecordset object.

Pass NULL to your recordset constructor to have a CDaoDatabase object constructed and connected for you automatically.

This is a useful shortcut that does not require you to construct and connect a CDaoDatabase object prior to constructing your recordset.

If the CDaoDatabase object is not open, a CDaoWorkspace object will also be created for you that uses the default workspace.

Note that this Database object won't be closed automatically afterwards!

For more information, see DBNewDB.

Parameters

rsHdl Handle of the new Recordset. NULL in case of failure.

dbHdl Handle of the Database

Connector Pane

RSNewRS

Controls and Indicators

cdlrn

 DBHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

idlrn

 DBHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSOpenByName

You must call this function to retrieve the records for the recordset.

For this version of RSOpen that uses the lpszSQL parameter, once the recordset is open you can retrieve records in one of several ways. The first option is to have DFX functions in your DoFieldExchange. The second option is to use dynamic binding by calling the RSGetFieldValue function. These options can be implemented separately or in combination. If they are combined, you will have to pass in the SQL statement yourself on the call to RSOpen.

For this first version of Open that uses the lpszSQL parameter, records are selected based on criteria shown in the following table.

Value = Value of the lpszSQL parameter

determined by = Records selected are determined by

Value determined by Example

================================================================

NULL The string returned by

RSGetDefaultSQL.

A comma-separated list All columns represented "Customer"

of one or more in the DoFieldExchange.

tabledefs and/or

querydef names.

SELECT column-list The specified columns "SELECT CustId,

FROM table-list from the specified CustName FROM

tabledef(s) and/or Customer"

querydef(s).

The usual procedure is to pass NULL for lpszSQL; in that case, RSOpen calls RSGetDefaultSQL.

You can instead specify other information in the lpszSQL parameter.

Whatever version of RSOpen you use, it constructs a final SQL string for the query and then executes the query. You can examine the constructed string by calling GetSQL after calling RSOpen.

The field data members of your recordset are bound to the columns of the data selected. If any records are returned, the first record becomes the current record.

If you want to refresh the records in the recordset after the recordset is already open, call RSRequery.

Use the dbSeeChanges flag if you wish to trap changes made by another user or another program on your machine when you are editing or deleting the same record. For example, if two users start editing the same record, the first user to call the RSUpdate member function succeeds. When RSUpdate is called by the second user, a CDaoException is thrown. Similarly, if the second user tries to call RSDelete to delete the record, and it has already been changed by the first user, a CDaoException occurs.

Note however, that this is not wise as you cannot catch exceptions under CVI. In most of the functions, DaoTool.dll does, and returns -2, but this is the only possibility for you as the programmer to recognise that an exception occurred.

Tip: Use the forward-only scrolling option (dbForwardOnly) to improve performance when your application makes a single pass through a recordset opened from an ODBC data source.

Parameters

Fresult Errorcode of this operation: -2 if handle not initialized, 1 if function

works correct, -1 if Error.

Note: These return values are DIFFERENT from the default -1/1/-2 values!!!

rsHdl Handle of the Recordset

OpenType One of the following values

SQL A string pointer containing one of the following:

* A NULL pointer.

* The name of one or more tabledefs and/or querydefs

(comma-separated).

* An SQL SELECT statement (optionally with an SQL WHERE or

ORDER BY clause).

* A pass-through query.

Options One or more of the options listed here. The default value is 0.

Note: The constants dbConsistent (32) and dbInconsistent (16) are mutually exclusive. You can use one or the other, but not both in a given instance of Open.

Connector Pane

RSOpenByName

Controls and Indicators

cdlrn

 RSHandle in

ci32

 OpenType

ci32

 Options

cstr

 SQL

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSOpenByQuery

You must call this function to retrieve the records for the recordset.

When you use this third version of RSOpen where you pass in a QueryDef handle, that query will be executed, and the resulting columns will be available for you to bind via DoFieldExchange and the DFX mechanism, and/or bind dynamically via GetFieldValue.

Note: You can only call RSOpen using a QueryDef object for dynaset-type and snapshot-type recordsets.

When using this version, the CDaoDatabase pointer used to construct the CDaoRecordset is not used; the database in which the tabledef resides is used.

Whatever version of RSOpen you use, it constructs a final SQL string for the query and then executes the query. You can examine the constructed string by calling GetSQL after calling RSOpen.

The field data members of your recordset are bound to the columns of the data selected. If any records are returned, the first record becomes the current record.

If you want to refresh the records in the recordset after the recordset is already open, call RSRequery.

Use the dbSeeChanges flag if you wish to trap changes made by another user or another program on your machine when you are editing or deleting the same record. For example, if two users start editing the same record, the first user to call the RSUpdate member function succeeds. When RSUpdate is called by the second user, a CDaoException is thrown. Similarly, if the second user tries to call RSDelete to delete the record, and it has already been changed by the first user, a CDaoException occurs.

Note however, that this is not wise as you cannot catch exceptions under CVI. In most of the functions, DaoTool.dll does, and returns -2, but this is the only possibility for you as the programmer to recognise that an exception occurred.

Tip: Use the forward-only scrolling option (dbForwardOnly) to improve performance when your application makes a single pass through a recordset opened from an ODBC data source.

Parameters

error Errorcode of this operation: -2 if handle not initialized, 1 if function

works correct, -1 if Error.

Note: These return values are DIFFERENT from the default -1/1/-2 values!!!

rsHdl Handle of the Recordset

qdHdl Handle of a QueryDef object.

OpenType Constant Name Value Description

================================================================

dbOpenDynaset 2 A dynaset-type recordset with

bidirectional scrolling. (default)

dbOpenTable 1 A table-type recordset with

bidirectional scrolling.

dbOpenSnapshot 4 A snapshot-type recordset with

bidirectional scrolling.

nOptions Possible values are as follows:

Constant Name Value Description

================================================================

dbAppendOnly 8 You can only append new records

(dynaset-type recordset only). This

option means literally that records may

only be appended. The MFC ODBC database

classes have an append-only option that

allows records to be retrieved and appended.

dbForwardOnly 256 The recordset is a forward-only

scrolling snapshot.

dbSeeChanges 512 Generate an exception if another user is

changing data you are editing.

dbDenyWrite 1 Other users cannot modify or add

records.

dbDenyRead 2 Other users cannot view records

(table-type recordset only).

dbReadOnly 4 You can only view records; other users

can modify them.

dbInconsistent 16 Inconsistent updates are allowed

(dynaset-type recordset only).

dbConsistent 32 Only consistent updates are allowed

(dynaset-type recordset only).

Connector Pane

RSOpenByQuery

Controls and Indicators

cdlrn

 RSHandle in

ci32

 OpenType

cdlrn

 QDHandle

ci32

 nOptions

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

idlrn

 QDHandle

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSRequery

Call this function to rebuild (refresh) a recordset. If any records are returned, the first record becomes the current record.

In order for the recordset to reflect the additions and deletions that you or other users are making to the data source, you must rebuild the recordset by calling RSRequery.

If the recordset is a dynaset, it automatically reflects updates that you or other users make to its existing records (but not additions).

If the recordset is a snapshot, it is necessary to call RSRequery to reflect edits by other users as well as additions and deletions.

For either a dynaset or a snapshot, call Requery any time you want to rebuild the recordset using parameter values. Set the new filter or sort by setting m_strFilter and m_strSort before calling RSRequery.

Set new parameters by assigning new values to parameter data members before calling RSRequery.

If the attempt to rebuild the recordset fails, the recordset is closed. Before you call RSRequery, you can determine whether the recordset can be requeried by calling the RSCanRestart member function. RSCanRestart does not guarantee that Requery will succeed.

Caution: Call RSRequery only after you have called RSOpen.

You can’t call RSRequery on a dynaset-type or snapshot-type recordset if calling RSCanRestart returns 0, nor can you use it on a table-type recordset.

If both RSIsBOF and RSIsEOF return nonzero after you call RSRequery, the query didn’t return any records and the recordset will contain no data.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSRequery

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSSeekArr

Locates the record in an indexed table-type CdbRecordset object that satisfies the specified criteria for the current index and makes that record the current record.

You must set the current index with the Index property before you use Seek. If the index identifies a nonunique key field, Seek locates the first record that satisfies the criteria.

The Seek method searches through the specified key fields and locates the first record that satisfies the criteria specified by pstrComparison and cKey. Once found, it makes that record current and sets the NoMatch property to False. If the Seek method fails to locate a match, the NoMatch property is set to True, and the current record is undefined.

If pstrComparison is equal (=), greater than or equal (>=), or greater than (>), Seek starts at the beginning of the index and searches forward.

If pstrComparison is less than (<) or less than or equal (<=), Seek starts at the end of the index and searches backward. However, if there are duplicate index entries at the end of the index, Seek starts at an arbitrary entry among the duplicates and then searches backward.

You must specify values for all fields defined in the index. If you use Seek with a multiple-column index, and you don't specify a comparison value for every field in the index, then you cannot use the equal (=) operator in the comparison. That's because some of the cKey criteria fields will default to Null, which will probably not match. Therefore, the equal operator will work correctly only if you have a record which is all Null except the key you're looking for. It's recommended that you use the greater than or equal (>=) operator instead.

The cKey argument must be of the same field data type as the corresponding field in the current index. For example, if the current index refers to a number field (such as Employee ID), cKey must be numeric.

There doesn't have to be a current record when you use Seek.

You can use the Indexes collection to enumerate the existing indexes.

To locate a record in a dynaset- or snapshot-type CdbRecordset that satisfies a specific condition that is not covered by existing indexes, use the Find methods. To include all records, not just those that satisfy a specific condition, use the Move methods to move from record to record.

You can't use the Seek method on a linked table because you can't open linked tables as table-type Recordset objects. However, if you use the OpenDatabase method to directly open an installable ISAM (non-ODBC) database, you can use Seek on tables in that database.

In an ODBCDirect workspace, the Find and Seek methods are not available on any type of CdbRecordset object, because executing a Find or Seek through an ODBC connection is not very efficient over the network. Instead, you should design the query (that is, using the pstrSource argument to the OpenRecordset method) with an appropriate WHERE clause that restricts the returned records to only those that meet the criteria you would otherwise use in a Find or Seek.

Parameters

FResult TRUE, if the record is found

rsHdl Handle of the Recordset

Comparison One of the following string expressions: <, <=, =, >=, or >.

KeyArray Pointer to the Array which contains all keys.

nKeys Number of keys to read from the KeyArray

Connector Pane

RSSeekArr

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Comparison

cu32

 WORD nKeys

c1ddlrn

 KeyArray in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 RecordsFound

i1ddlrn

 KeyArray out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSSeekFix

Locates the record in an indexed table-type CdbRecordset object that satisfies the specified criteria for the current index and makes that record the current record.

You must set the current index with the Index property before you use Seek. If the index identifies a nonunique key field, Seek locates the first record that satisfies the criteria.

The Seek method searches through the specified key fields and locates the first record that satisfies the criteria specified by pstrComparison and cKey. Once found, it makes that record current and sets the NoMatch property to False. If the Seek method fails to locate a match, the NoMatch property is set to True, and the current record is undefined.

If pstrComparison is equal (=), greater than or equal (>=), or greater than (>), Seek starts at the beginning of the index and searches forward.

If pstrComparison is less than (<) or less than or equal (<=), Seek starts at the end of the index and searches backward. However, if there are duplicate index entries at the end of the index, Seek starts at an arbitrary entry among the duplicates and then searches backward.

You must specify values for all fields defined in the index. If you use Seek with a multiple-column index, and you don't specify a comparison value for every field in the index, then you cannot use the equal (=) operator in the comparison. That's because some of the cKey criteria fields will default to Null, which will probably not match. Therefore, the equal operator will work correctly only if you have a record which is all Null except the key you're looking for. It's recommended that you use the greater than or equal (>=) operator instead.

The cKey argument must be of the same field data type as the corresponding field in the current index. For example, if the current index refers to a number field (such as Employee ID), cKey must be numeric.

There doesn't have to be a current record when you use Seek.

You can use the Indexes collection to enumerate the existing indexes.

To locate a record in a dynaset- or snapshot-type CdbRecordset that satisfies a specific condition that is not covered by existing indexes, use the Find methods. To include all records, not just those that satisfy a specific condition, use the Move methods to move from record to record.

You can't use the Seek method on a linked table because you can't open linked tables as table-type Recordset objects. However, if you use the OpenDatabase method to directly open an installable ISAM (non-ODBC) database, you can use Seek on tables in that database.

In an ODBCDirect workspace, the Find and Seek methods are not available on any type of CdbRecordset object, because executing a Find or Seek through an ODBC connection is not very efficient over the network. Instead, you should design the query (that is, using the pstrSource argument to the OpenRecordset method) with an appropriate WHERE clause that restricts the returned records to only those that meet the criteria you would otherwise use in a Find or Seek.

Parameters

FResult TRUE, if the record is found

rsHdl Handle of the Recordset

Comparison One of the following string expressions: <, <=, =, >=, or >.

pKey1 One or more values corresponding to fields in the CdbRecordset object's current index, as specified by its Index property setting. Seek accepts an unspecified number of arguments, as indicated by the ellipsis symbol ("..."), however you may only have a

maximum of 13 key arguments.

pKey2, pKey3 See pKey1 description.

Connector Pane

RSSeekFix

Controls and Indicators

cdlrn

 RSHandle in

cstr

 Comparison

cdlrn

 OVHDL pKey1 in

cdlrn

 OVHDL pKey2 in

cdlrn

 OVHDL pKey3 in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

ibool

 FResult

idlrn

 OVHDL pKey1 out

idlrn

 OVHDL pKey2 out

idlrn

 OVHDL pKey2 out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSSetFieldDirty

Call this function to flag a field data member of the recordset as changed or as unchanged.

Marking fields as unchanged ensures the field is not updated.

The framework marks changed field data members to ensure they will be written to the record on the data source by the DAO record field exchange (DFX) mechanism. Changing the value of a field generally sets the field dirty automatically, so you will seldom need to call RSSetFieldDirty yourself, but you might sometimes want to ensure that columns will be explicitly updated or inserted regardless of what value is in the field data member. The DFX mechanism also employs the use of PSEUDO NULL.

If the double-buffering mechanism is not being used, then changing the value of the field does not automatically set the field as dirty. In this case, it will be necessary to explicity set the field as dirty.

Important: Call this member function only after you have called RSEdit or RSAddNew.

Using NULL for the second argument of the function will apply the function to all outputColumns.

RSSetFieldDirty is implemented through RSDoFieldExchange.

Parameters

rsHdl Handle of the Recordset

pv Contains the address of a field data member in the recordset or NULL.

If NULL, all field data members in the recordset are flagged.

(C NULL is not the same as Null in database terminology, which

means "having no value.")

Dirty TRUE if the field data member is to be flagged as "dirty" (changed).

Otherwise FALSE if the field data member is to be flagged as "clean" (unchanged).

Connector Pane

RSSetFieldDirty

Controls and Indicators

cdlrn

 RSHandle in

cbool

 Dirty

cu32

 pv

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSSetFieldNull

Call this function to flag a field data member of the recordset as Null (specifically having no value) or as non-Null.

When you add a new record to a recordset, all field data members are initially set to a Null value and flagged as "dirty" (changed).

When you retrieve a record from a data source, its columns either already have values or are Null.

If it is not appropriate to make a field Null, a CDaoException is thrown.

If you are using the double-buffering mechanism, for example, if you specifically wish to designate a field of the current record as not having a value, call RSSetFieldNull with bNull set to TRUE to flag it as Null.

If a field was previously marked Null and you now want to give it a value, simply set its new value. You do not have to remove the Null flag with RSSetFieldNull. To determine whether the field is allowed to be Null, call RSIsFieldNullable.

If you are not using the double-buffering mechanism, then changing the value of the field does not automatically set the field as dirty and non-Null. You must specifically set the fields dirty and non-Null.

The DFX mechanism employs the use of PSEUDO NULL.

Important: Call this member function only after you have called RSEdit or RSAddNew.

Using NULL for the second argument of the function will apply the function only to outputColumns, not params in CDaoFieldExchange. For instance, the call

RSSetFieldNull(rshdl, NULL, bNull);

will set only outputColumns to NULL. The value of param will be unaffected.

Parameters

rsHdl Handle of the Recordset

pv Contains the address of a field data member in the recordset or NULL.

If NULL, all field data members in the recordset are flagged.

(C NULL is not the same as Null in database terminology, which means "having no value.")

Null Nonzero if the field data member is to be flagged as having no value

Otherwise 0 if the field data member is to be flagged as non-Null.

Connector Pane

RSSetFieldNull

Controls and Indicators

cdlrn

 RSHandle in

cbool

 Null

cu32

 pv

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSSetFieldValueByIdx

Call this function to set the value of a field, by supplying its ordinal position.

The other version of this function works by supplying the field's Name.

Use RSSetFieldValue and RSGetFieldValue to dynamically bind fields at run time rather than statically binding columns using the RSDoFieldExchange mechanism.

Parameters

FResult Errorcode of this operation: -1 if handle not initialized, 1 if function

works correct, -2 if Error.

rsHdl Handle of the Recordset

Index An integer that represents the ordinal position of the field in the recordset’s Fields

collection (zero-based).

ovHdl A handle of a COleVariant object containing the value of the field’s contents.

Connector Pane

RSSetFieldValueByIdx

Controls and Indicators

cdlrn

 RSHandle in

cu32

 Index

cdlrn

 OVHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSSetFieldValueByName

Call this function to set the value of a field, by supplying its Name.

The other version of this function works by supplying the field's ordinal position.

Use RSSetFieldValue and RSGetFieldValue to dynamically bind fields at run time rather than statically binding columns using the RSDoFieldExchange mechanism.

Parameters

error Errorcode of this operation: -1 if handle not initialized, 1 if function

works correct, -2 if Error.

rsHdl Handle of the Recordset

FieldName A pointer to a string containing the name of a field.

ovHdl A handle of a COleVariant object containing the value of the field’s contents.

Connector Pane

RSSetFieldValueByName

Controls and Indicators

cdlrn

 RSHandle in

cstr

 FieldName

cdlrn

 OVHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

idlrn

 OVHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSSetLockingMode

Call this member function to set the type of locking for the recordset.

When pessimistic locking is in effect, the 2K page containing the record you are editing is locked as soon as you call the RSEdit member function. The page is unlocked when you call the RSUpdate or RSClose member function or any of the Move or Find operations.

When optimistic locking is in effect, the 2K page containing the record is locked only while the record is being updated with the RSUpdate member function.

If a page is locked, no other user can edit records on the same page. If you call RSSetLockingMode and pass a nonzero value and another user already has the page locked, an exception is thrown when you call RSEdit. Other users can read data from locked pages.

If you call RSSetLockingMode with a zero value and later call RSUpdate while the page is locked by another user, an exception occurs. To see the changes made to your record by another user (and lose your changes), call the RSSetBookmark member function with the bookmark value of the current record.

When working with ODBC data sources, the locking mode is always optimistic.

Parameters

rsHdl Handle of the Recordset

Mode A flag that indicates the type of locking.

Connector Pane

RSSetLockingMode

Controls and Indicators

cdlrn

 RSHandle in

cbool

 Mode

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

RSUpdate

Call this member function after a call to the RSAddNew or RSEdit member function. This call is required to complete the RSAddNew or RSEdit operation.

Both RSAddNew and RSEdit prepare an edit buffer in which the added or edited data is placed for saving to the data source. RSUpdate saves the data. Only those fields marked or detected as changed are updated.

If the data source supports transactions, you can make the RSUpdate call (and its corresponding RSAddNew or RSEdit call) part of a transaction.

See WSBeginTrans and WSCommitTrans for more information.

Caution: If you call RSUpdate without first calling either RSAddNew or RSEdit, RSUpdate throws a CDaoException. If you call RSAddNew or RSEdit, you must call RSUpdate before you call RSMoveNext or close either the recordset or the data source connection. Otherwise, your changes are lost without notification.

When the recordset object is pessimistically locked in a multiuser environment, the record remains locked from the time RSEdit is used until the updating is complete. If the recordset is optimistically locked, the record is locked and compared with the pre-edited record just before it is updated in the database. If the record has changed since you called RSEdit, the RSUpdate operation fails and MFC throws an exception. You can change the locking mode with RSSetLockingMode.

Note: Optimistic locking is always used on external database formats, such as ODBC and installable ISAM.

Parameters

rsHdl Handle of the Recordset

Connector Pane

RSUpdate

Controls and Indicators

cdlrn

 RSHandle in

cclst

 error in (no error)

The error in cluster can accept error information wired from VIs previously called. Use this information to decide if any functionality should be bypassed in the event of errors from other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.

ii32

 FResult

idlrn

 RSHandle out

iclst

 error out

The error out cluster passes error or warning information out of a VI to be used by other VIs.

The pop-up option Explain Error (or Explain Warning) gives more information about the error displayed.