Defining SourceRecordset at design time

There are two different ways to connect a True DataControl to the data at design time:

Using True DataControl as an independent data source, specifying data connection on its DataSource property page. This is the most convenient way of using True DataControl. This option is described in the remainder of this section. This option is unavailable in True DataControl Lite.
Setting its DataSource and DataMember properties to an available standard ADO/OLE DB data source, such as ADODC control or DataEnvironment. This is the only option in True DataControl Lite, see Binding TDataLite to a data source.

The DataSource property page is used to define the data source connection at design time. It resembles the property pages of a standard ADO data control (ADODC), so its use should be easy for those who are familiar with ADODC. It combines all the attributes that can be found on the General, Authentication, and RecordSource pages in ADODC.

We refer to the properties specified in the DataSource page as data source properties. They can be set in the Visual Basic Properties Window, or the DataSource property page. They can also be set from code at run time, for example in the Form_Load event, or the WillOpenData event. Setting data source properties at run time after initial startup is also possible, but it will not affect the TData control until the Refresh method is called, at which time the True DataControl recordset will be recreated with the new data source property values.

The Source of Connection section of the DataSource page is designed to facilitate ConnectionString setting by allowing you to set the ConnectionString property either directly with Use Connection String option and Build dialog box, or by using special Data Link File and ODBC Data Source Name options. The standard Build dialog presents all available OLE DB providers and their properties. The Other Attributes edit box allows you to add some information to the ConnectionString, in case it is not supported by the standard Build dialog.

The Authentication section contains the UserName and Password properties that are necessary in case the selected OLE DB provider uses authorization.

The RecordSource section facilitates setting the RecordSource property. Depending on the choice in the CommandType combo box, the user can either select a table or stored procedure name from a list, or enter the text of a SQL statement.

Finally, the LockType combo box specifies the type of locking used in editing, including an adLockReadOnly option, which means a read-only recordset.

Some of less common data source properties are not represented on the DataSource property page. They are available at design time in the Visual Basic Properties window. All data source properties have read/write access both at design and at run time.

The Test button located on the DataSource page tests the connection and recordset creation as specified by the data source property values.

With data source properties defined, True DataControl tries to establish database connection when it needs information from the database. That is, when the Fields property page is opened, performing syntax check and on other occasions. This “live connection at design time” behavior can be turned off by setting the DesignConnection property to False. It can be useful when working in disconnected mode, where you don’t have access to the database, or if establishing connection is too time consuming or simply unnecessary. With the DesignTimeout property you can control the timeout, number of seconds that True DataControl waits for establishing connection at design time.

The following is the list of all True DataControl data source properties. All of these are standard properties of ADO Connection, Command, and Recordset objects. See ADO documentation for detailed description of these properties. You may notice that not all ADO recordset properties are listed. Some important properties, such as Filer and Sort, are not supported at design time as True DataControl data source properties. If you need to set such properties, use the OpenData event. For more information, see Events in creating recordset at run time.

Properties for Establishing Connection with a Data Source:

ConnectionString	Contains the information used to establish a connection to a data source.
ConnectionTimeout	Indicates how long to wait while establishing a connection before terminating the attempt and generating an error.
Mode	Indicates the available permissions for modifying data.
Password	For OLE DB providers that need authentication.
UserName	For OLE DB providers that need authentication.

Properties for Creating a Recordset Object (SourceRecordset):

CacheSize	The number of records from a recordset object that are cached locally in memory.
CommandTimeout	How long to wait while executing a command before terminating the attempt and generating an error.
CommandType	How RecordSource string must be interpreted.
CursorLocation	Location of the cursor engine, either on server or on client.
CursorType	Type of cursor used for a recordset object.
LockType	The type of locks placed on records during editing.
MaxRecords	The maximum number of records to return to a recordset from a query.
RecordSource	Source of recordset, usually an SQL statement or a table name.