Share via


CRecordset::AddNew

Prepares for adding a new record to the table.

virtual void AddNew( );

Remarks

You must call the Requery member function to see the newly added record. 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 Update member function. Update saves your changes to the data source.

Note

If you have implemented bulk row fetching, you cannot call AddNew. This will result in a failed assertion. Although class CRecordset does not provide a mechanism for updating bulk rows of data, you can write your own functions by using the ODBC API function SQLSetPos. For more information about bulk row fetching, see the article Recordset: Fetching Records in Bulk (ODBC).

AddNew prepares a new, empty record using the recordset's field data members. After you call AddNew, set the values you want in the recordset's field data members. (You do not have to call the Edit member function for this purpose; use Edit only for existing records.) When you subsequently call Update, changed values in the field data members are saved on the data source.

Warning

If you scroll to a new record before you call Update, the new record is lost, and no warning is given.

If the data source supports transactions, you can make your AddNew call part of a transaction. For more information about transactions, see class CDatabase. Note that you should call CDatabase::BeginTrans before calling AddNew.

Note

For dynasets, new records are added to the recordset as the last record. Added records are not added to snapshots; you must call Requery to refresh the recordset.

It is illegal to call AddNew for a recordset whose Open member function has not been called. A CDBException is thrown if you call AddNew for a recordset that cannot be appended to. You can determine whether the recordset is updatable by calling CanAppend.

For more information, see the following articles: Recordset: How Recordsets Update Records (ODBC), Recordset: Adding, Updating, and Deleting Records (ODBC), and Transaction (ODBC).

Exceptions

This method can throw exceptions of type CDBException*.

Example

See the article Transaction: Performing a Transaction in a Recordset (ODBC).

Requirements

Header: afxdb.h

See Also

Reference

CRecordset Class

Hierarchy Chart

CRecordset::Edit

CRecordset::Delete

CRecordset::Update

CRecordset::Requery

CDatabase::BeginTrans

CDBException Class