Inserting a New UserConnection Object

To insert a new connection object

1. Make sure the Remote Data Object 2.0 library is referenced in the References dialog box available from the Project menu.
   
   
2. Make sure the designer is enabled by checking Microsoft UserConnection on the Designers tab of the Components dialog box, available on the Projects menu.
   
   
3. Insert the UserConnection designer into the project by selecting Microsoft UserConnection from the Add ActiveX Designer item on the Project menu.

The Connection Designer Properties Window

When you insert the UserConnection designer, a new connection class is added to the current project and brings up a visual representation of the class, overlaid with its properties window, shown below.

UserConnection Properties Connection tab

The UserConnection properties window has three tabs: Connection, Authentication, and Miscellaneous.

Connection Properties

The Connection properties are used to establish connections to the server during design time (for retrieving a list of available stored procedures) and is also persisted in the new UserConnection object so that you don't have to specify connection information when the class is created at run time. This connection information is just the data source name (or, if you select Use DSN-less Connection String, the driver and server name) along with any special connection tokens specified in the "Other ODBC Attributes" box.

The Use ODBC Datasource box displays all DSNs on the current computer. You can also define a new DSN by clicking on the New button.

Authentication Properties

The authentication tab contains information needed for connecting to the data source specified in the connection information tab. These properties of the connection may or may not be persisted with the new connection object, depending on the setting of the check boxes at the bottom of the page. See "Persistence of Authentication" below for more details.

Authentication tab

The user name and password text boxes are self-explanatory. The password box displays asterisks as the password is entered.

The Prompt Behavior box allows you to choose the prompt behavior for the rdoConnection object.

Persistence of Authentication

Due to concerns about security and password protection, there are two levels of persistence available for the UserConnection object's authentication properties. By default both of these levels are turned off, so that no caching or persistence of authentication properties occurs.

If Save Connection Information for new Run-Mode Class is checked, the user name and password properties are stored in the properties of the actual class and are persisted in the built executable or DLL.

If Save Connection Information for Design Time is checked, the user name and password properties persist only during design-time, and are not written into the built .exe or .dll file.

Miscellaneous Properties

The last tab on the connection property page allows the developer to adjust the Timeout properties and cursor library for the new UserConnection class.

Miscellaneous Properties

The Logon Timeout and Query Timeout values can be set to any values allowed in RDO 2.0.

The Cursor Driver combo box contains options that map to the RDO constants for the "CursorDriver" property.

The UserConnection designer form

After entering the properties to establish an ODBC connection for your UserConnection object, click OK to close the properties window. The new object appears in the main UserConnection form.

The UserConnection Form

The toolbar buttons at the top of the form allow you to add single or multiple queries, delete queries, examine or change query properties, and change global options for the UserConnection designer.