HOWTO: Using CDaoRecordset::Seek

ID: Q149087

The information in this article applies to:

The Microsoft Foundation Classes (MFC), included with:
- Microsoft Visual C++, 32-bit Editions, versions 4.0, 4.1, 4.2, 5.0, 6.0

SUMMARY

This article explains how to use CDaoRecordset::Seek. Seek enables high- performance indexed searching on table-type recordsets. You can call Seek to find the first record that satisfies the specified criteria for the current index and make that record the current record. There are two versions of the Seek member function that you can use to locate a record in an indexed table-type recordset object. This article explains both.

MORE INFORMATION

There are two versions of Seek, one works with indexes that are comprised of up to three fields and the other handles indexes comprised of more than three fields. You must set the current index by calling SetCurrentIndex before calling Seek. If you do not, an exception will be thrown, as MFC does not specify a default index when a recordset is opened. If the index identifies a non-unique key, Seek locates the first record that satisfies the criteria.

NOTE: If you are not creating a UNICODE recordset, any character string COleVariant objects must be explicitly declared ANSI. This can be done by using the COleVariant::COleVariant( lpszSrc, vtSrc ) form of constructor with vtSrc set to VT_BSTRT (ANSI) or by using the COleVariant function SetString( lpszSrc, vtSrc ) with vtSrc set to VT_BSTRT. SetString() is only available in MFC Version 4.1 or later.

Here are the declarations for Seek:


   BOOL Seek( LPCTSTR lpszComparison,
              COleVariant* pKey1,
              COleVariant* pKey2 = NULL,
              COleVariant* pKey3 = NULL );

   BOOL Seek (LPCTSTR lpszComparison,
              COleVariant* pKeyArray,
              WORD nKeys );

When you call Seek, you pass one or more key values and a comparison operator (<, <=, =, >=, or >). Seek searches through the current index and locates the first record that satisfies the criteria specified by lpszComparison and the key values passed to it. Once found, Seek returns a nonzero value and makes that record current. If Seek fails to locate a match, Seek returns zero and the current record is undefined.

If the current index is a multiple-field index, then the key values for Seek must be in the same order as the fields in the index. In this case, trailing key values can be omitted. You can leave off any number of key values from the end of the list of key values but not from the beginning or middle. If you do choose to leave off trailing key values, Microsoft recommends that you use the >= operator instead of the = operator. The missing key values will be treated as NULL, which probably won't match the values in your table.

NOTE: The Microsoft Jet database engine, and therefore the Seek method, does not perform case-sensitive searches.

The easiest way to create an index object is from within Microsoft Access.

Steps to Create an Index Object

Start Microsoft Access.

Open the database file (.mdb) to be targeted.

Open the target table in Design View.

Invoke the Index Dialog by choosing Indexes on the View menu.

Decide on a name for your index object, and then type it into the Index Name field of the Index Dialog.

Type the field names of the fields you want tied to the index object into the Field Name field of the Index Dialog.

Sample Code


   // Using the first version of Seek specifying the
   // first field in the index:

   void CMyDaoRecordset::FindCourse()
   {
      m_pSet->SetCurrentIndex( _T("PrimaryKey") );

      COleVariant varCourse ( _T("MATH202"), VT_BSTRT );

      if( m_pSet->Seek( _T( "=" ), &varCourse ) )
      // then you have found the record and it is now
      // the current record

   // Using the first version of Seek specifying the
   // first two fields in the index:
   void CMyDaoRecordset::FindCourse()
   {
      m_pSet->SetCurrentIndex( _T("PrimaryKey") );

      COleVariant varCourse ( _T("MATH202"), VT_BSTRT );
      COleVariant varSection( _T( "2"     ), VT_BSTRT );

      if( m_pSet->Seek( _T( "=" ), &varCourse, &varSection ) )
      // then you have found the record and it is now
      // the current record

The first version of Seek may be used with up to three fields. If an index has more than three fields and you need to specify more than three fields, use the second version of Seek. An array of COleVariants will be passed.


   // Using the second version of Seek, specifying the first four
   // fields of the index:

   void CMyDaoRecordset::FindCourse()
   {
      m_pSet->SetCurrentIndex( _T("Secondary") );

      COleVariant varCourse    ( _T( "MATH202"  ), VT_BSTRT );
      COleVariant varSection   ( _T( "2"        ), VT_BSTRT );
      COleVariant varInstructor( _T( "ROGERSN"  ), VT_BSTRT );
      COleVariant varRoomNo      ( _T( "KEN-12"   ), VT_BSTRT );

      // Now create an array and let the assignment
      // operator of COleVariant populate the array
      COleVariant rgVariant[4];

      rgVariant[0] = varCourse;
      rgVariant[1] = varSection;
      rgVariant[2] = varInstructor;
      rgVariant[3] = varRoomNo;

      if( m_pSet->Seek( _T( "=" ), &rgVariant[0], 4 ) )
      // then you have found the record and it is now
      // the current record

REFERENCES

For more information, please see the following article in the Microsoft Knowledge Base:

Q140599 PRB: MFC DAO Functions Accepting COleVariant Strings May Fail

Additional query words:

Keywords : kbcode kbDAO kbMFC kbVC400 kbVC410 kbVC420 kbVC500 kbVC600
Version : 4.0 4.1 4.2 4.2b 5.0 6.0
Platform : NT WINDOWS
Issue type : kbhowto