To add a row to the database, DataObjects for .NET generates and executes the following SQL statement:

INSERT INTO table_name (field1, field2, …) VALUES (?, ?, …)

Parameter values are set to the current row values: row["field_name"].

The collection of fields used to set the values in the newly added record depends on the field properties UpdateIgnore and UpdateSet and DataSourceReadOnly:

• Unbound fields (with empty DbFieldName), fields with UpdateIgnore = True and fields with DataSourceReadOnly = True are not included regardless of the UpdateSet value.
• If UpdateSet = Always, the field is included provided the other properties do not preclude it.
• If UpdateSet = Never, the field is not included.
• If UpdateSet = IfChanged (default), the field is included if its value has been set by the user.

After a new row has been successfully created, DataObjects for .NET generates and executes another SQL statement, to retrieve the new row from the database:

SELECT selectField1, selectField2, … FROM table_name WHERE keyField1 = ? AND keyField2 = ? AND …

This refresh phase is needed because some field values could be assigned by the database itself, such as autoincrement fields, and so on.

The refresh phase is controlled by the table property UpdateRefreshMode:

• If UpdateRefreshMode = Always, the refresh phase always takes place, and its failure generates an error.
• If UpdateRefreshMode = Never, the refresh phase is skipped.
• If UpdateRefreshMode = IfPossible (default), the refresh phase takes place, but its possible failure does not generate an error.

Fields selectField1, selectField2, … are those whose values are retrieved from the new database row. The retrieved values, if different from the row values sent for update, substitute the row values and the client receives them back in the refreshed row.

A bound field (with non-empty DbFieldName) is included in selectField1, selectField2, …if its UpdateRefresh property is set to True.

Fields keyField1, keyField2, … used to locate the record in the WHERE clause, are the primary key fields of the table.

Parameter values are set to the current row values of primary keys: row["field_name"].