This property allows to support updateable SQL-based tables based on a SQL SELECT statement or a stored procedure, without manual code, using ADO.NET data adapter. This makes working with SQL-based tables in C1DataObjects almost as easy as working with bound tables (when C1.Data.SchemaObjects.DbTable.DataMode=Bound, C1.Data.SchemaObjects.DbTable.DbTableName set to a database table name). However, bound tables should be always preferable when you have a choice. Bound tables are more intimately related to database tables, so C1DataObjects can support features, such as virtual mode, that are unavailable for SQL-based tables, see Bound, SQL-Based and Unbound tables.

See the SQLBasedTablesEasy sample in the samples directory for an example of using a data adapter.

In C1DataObjects Enterprise edition, data adapter is specified in the DataAdapter property of a C1TableLogic component attached to a table. The table must be SQL-based (C1.Data.SchemaObjects.DbTable.DataMode=SqlBased). In C1DataExpress, it is specified in the C1ExpressTable DataAdapter property. In both editions, a data adapter component can be created using the Create DataAdapter context menu item or created manually and attached to the DataAdapter property.

If specified, the DataAdapter is used to fill and update the table. Filling the table, only its SelectCommand property is used, not the whole data adapter component. The SelectCommand is executed to fetch the data on filling the data set. Updating modified rows to the database, C1DataObjects calls the data adapter's method DbDataAdapter.Update(DataRow[]) for each modified row (each call uses a single element in the DataRow[] array).

A data adapter component must be attached to a Connection component. The Create DataAdapter menu item creates that component automatically. The connection component is used only at design time. At run time, it is always ignored, the schema connection (or, in the Express edition, C1ExpressConnection.ConnectionString) is always used at run time regardless of what you specify in DataAdapter.Connection.

You are not required to set up the adapter's TableMappings property. It is not used at run time. C1DataObjects always uses the mapping between your table fields and the database fields that you already have in the schema in the fields' C1.Data.SchemaObjects.DbTableField.DbFieldName property. In fact, the adapter's TableMappings are automatically updated to reflect the mappings specified in the fields' DbFieldName property.

ADO.NET data adapter supports both SQL statements and stored procedures. To fill a SQL-based table with data returned by a stored procedure, set C1.Data.SchemaObjects.DbTable.SelectCommandType=StoredProcedure and type the procedure name in the C1.Data.SchemaObjects.DbTable.SelectCommandText property or select it from the dropdown list of stored procedures in SelectCommandText.

When you set C1.Data.SchemaObjects.DbTable.SelectCommandText to a procedure name, the fields returned by the procedure are automatically retrieved (if the procedure returns a recordset; only procedures returning a recordset as return value or one of out parameters can be used in C1DataObjects as well as in ADO.NET).

When you use a stored procedure as your C1.Data.SchemaObjects.DbTable.SelectCommandText (C1.Data.SchemaObjects.DbTable.SelectCommandType=StoredProcedure; in this case your adapter's SelectCommand will also be the same stored procedure), you can specify parameter values in the data adapter's SelectCommand property. Even if you do not use data adapter for update (in which case you can leave its UpdateCommand/ InsertCommand/DeleteCommand properties empty), you can use it this way to specify parameter values for the stored procedure you use to fill the table.

Regardless of whether you use a stored procedure or a SQL statement in C1.Data.SchemaObjects.DbTable.SelectCommandText, your data adapter commands for updating modified rows (data adapter properties UpdateCommand, InsertCommand, DeleteCommand) can be either SQL statements or stored procedures, as supported by the data adapter (so you can select Create New Stored Procedures or Use Existing Stored Procedures in the wizard).

If a data adapter is used for update, some C1DataObjects update features become unavailable, as they only relate to update made by SQL commands generated by C1DataObjects itself, not by an external component. These are table properties UpdateLocateMode, UpdateRefreshMode, IgnoreDeleteError, field properties AutoIncrement (only on the server, it still works on the client), UpdateLocate, UpdateRefresh, UpdateSet. This does not mean that features supported by these properties are unavailable, it only means that they must be supported in a different way. All these features are supported by ADO.NET DataAdapter, but may require more property settings and some coding, see the ADO.NET documentation.

To control the update process for every row, you can use BeforeUpdateRow and BaseLogic.AfterUpdateRow events in SQL-based tables with DataAdapter as well as in bound tables. You can also use RowUpdating and RowUpdated events of the data adapter component. These events fire between BeforeUpdateRow and BaseLogic.AfterUpdateRow events. They (and data adapter's ContinueUpdateOnError property) allow you to specify whether to continue or throw an exception, allow to make this decision in the context of the data adapter component itself. If an exception is thrown, it is passed to the BaseLogic.AfterUpdateRow event, and, if it is suppressed in the adapter event, then, accordingly, BaseLogic.AfterUpdateRow does not receive an error. But using adapter events is optional, you can do all necessary error handling in the BaseLogic.AfterUpdateRow event.

Reference

C1TableLogic Class
C1TableLogic Members
Bound, SQL-Based and Unbound Tables