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

UPDATE table_name SET (setField1 = ?, setField1 = ?, …) WHERE whereField1 = ? AND wherefield2 = ? AND …

The collection of fields used to set the values in the database row, setField1, setField2, … 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 changed by the user, row["field_name", DataRowVersionEnum.Current] is not equal to row["field_name", DataRowVersionEnum.Original].

Parameters used to set values are assigned the current row values: row["field_name"].

The collection of fields used to locate the record for update in the WHERE clause, whereField1, whereField2, … depends on the table property UpdateLocateMode and field properties UpdateIgnore and UpdateLocate:

• Unbound fields (with empty DbFieldName), fields with UpdateIgnore = True and fields with UpdateLocate = False are not included regardless of the UpdateLocateMode value.
• If UpdateLocateMode = PrimaryKey, only primary key fields (those with PrimaryKey = True) are included.
• If UpdateLocateMode = AllFields, all fields are included provided they are not excluded by conditions above.
• If UpdateLocateMode = PrimaryKeyAndChangedFields (default), the locate fields include primary keys and fields whose values have changed, row["field_name", DataRowVersionEnum.Current] is not equal to row["field_name", DataRowVersionEnum.Original].

Parameter used to locate the record are set to original row values: row["field_name", DataRowVersionEnum.Original].

If the original value of a field is Null, the condition is field IS NULLinstead of field = ?.

Locating the record for update can fail (no record found), due to changes made to the database by other users between the time the record was fetched and the time it is updated. This is usually called optimistic concurrency, see Handling Concurrency Conflicts for more information. Including more fields in the WHERE clause (manipulating the UpdateLocateMode and UpdateLocate properties) makes the concurrency check stricter: changes made by other users to one of this field can fail the update. Excluding fields from the WHERE clause makes the check less strict, allowing more concurrency, more tolerant to changes made by other users.

After the database row has been successfully modified, DataObjects for .NET generates and executes another SQL statement, to retrieve the modified 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 changed by the database itself, using triggers, 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["field_name"]) or to the original (row["field_name", DataRowVersionEnum.Original]) values of primary keys, depending on whether a primary key field's value has been set by the UPDATE SQL statement. If it has not been set in UPDATE, the original value is used. If it has been set, the current value is used.