CRecordset::Open

virtual BOOL Open( UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE, LPCTSTR lpszSQL = NULL, DWORD dwOptions = none );
throw( CDBException, CMemoryException );

Return Value

Nonzero if the CRecordset object was successfully opened; otherwise 0 if CDatabase::Open (if called) returns 0.

Parameters

nOpenType

Accept the default value, AFX_DB_USE_DEFAULT_TYPE, or use one of the following values from the enum OpenType:

lpszSQL

A string pointer containing one of the following:

dwOptions

A bitmask which can specify a combination of the values listed below. Some of these are mutually exclusive. The default value is none.

Remarks

You must call this member function to run the query defined by the recordset. Before calling Open, you must construct the recordset object.

This recordset’s connection to the data source depends on how you construct the recordset before calling Open. If you pass a CDatabase object to the recordset constructor that has not been connected to the data source, this member function uses GetDefaultConnect to attempt to open the database object. If you pass NULL to the recordset constructor, the constructor constructs a CDatabase object for you, and Open attempts to connect the database object. For details on closing the recordset and the connection under these varying circumstances, see Close.

Note   Access to a data source through a CRecordset object is always shared. Unlike the CDaoRecordset class, you cannot use a CRecordset object to open a data source with exclusive access.

When you call Open, a query, usually an SQL SELECT statement, selects records based on criteria shown in the following table.

Value of the lpszSQL parameter Records selected are determined by Example
NULL The string returned by GetDefaultSQL.
SQL table name All columns of the table-list in DoFieldExchange or DoBulkFieldExchange. 
"Customer"
Predefined query (stored procedure) name The columns the query is defined to return. 
"{call OverDueAccts}"
SELECT column-list FROM table-list The specified columns from the specified table(s). 
"SELECT CustId, CustName FROM 
Customer"

! Warning   Be careful that you do not insert extra whitespace in your SQL string. For example, if you insert whitespace between the curly brace and the CALL keyword, MFC will misinterpret the SQL string as a table name and incorporate it into a SELECT statement, which will result in an exception being thrown. Similarly, if your predefined query uses an output parameter, do not insert whitespace between the curly brace and the '?' symbol. Finally, you must not insert whitespace before the curly brace in a CALL statement or before the SELECT keyword in a SELECT statment.

The usual procedure is to pass NULL to Open; in this case, Open calls GetDefaultSQL. If you are using a derived CRecordset class, GetDefualtSQL gives the table name(s) you specified in ClassWizard. You can instead specify other information in the lpszSQL parameter.

Whatever you pass, Open constructs a final SQL string for the query (the string may have SQL WHERE and ORDER BY clauses appended to the lpszSQL string you passed) and then executes the query. You can examine the constructed string by calling GetSQL after calling Open. For additional details about how the recordset constructs an SQL statement and selects records, see the article Recordset: How Recordsets Select Records (ODBC) in Visual C++ Programmer’s Guide.

The field data members of your recordset class 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 set options for the recordset, such as a filter or sort, specify these after you construct the recordset object but before you call Open. If you want to refresh the records in the recordset after the recordset is already open, call Requery.

For more information, including additional examples, see the articles Recordset (ODBC), Recordset: How Recordsets Select Records (ODBC), and Recordset: Creating and Closing Recordsets (ODBC) in Visual C++ Programmer’s Guide.

Example

The following code examples show different forms of the Open call.

// rs is a CRecordset or
// CRecordset-derived object

// Open rs using the default SQL statement,
// implement bookmarks, and turn off
// automatic dirty field checking
rs.Open( CRecordset::snapshot, NULL,
         CRecordset::useBookmarks |
         CRecordset::noDirtyFieldCheck );

// Pass a complete SELECT statement
// and open as a dynaset
rs.Open( CRecordset::dynaset,
         _T( "Select L_Name from Customer" ) );

// Accept all defaults
rs.Open( );

CRecordset Overview |  Class Members |  Hierarchy Chart

See Also   CRecordset::CRecordset, CRecordset::Close, CRecordset::GetDefaultSQL, CRecordset::GetSQL, CRecordset::m_strFilter, CRecordset::m_strSort, CRecordset::Requery