Visual Basic Concepts

Manipulating Your Data Environment

This section contains information on viewing objects within your Data Environment designer, modifying and deleting objects, refreshing Command and Connection objects, and setting Data Environment designer options.

Data Environment Designer Views

The Data Environment designer window has an outline view that shows the defined Connection and Command objects. This outline view can be arranged either by object type or by connection. You can also set this outline view to either display or hide the field objects of each Command object.

View By Connection

By Connection displays the objects grouped by connection, with the Command objects listed under the Connection object to which they are linked. Thus, you can easily view the association of Command objects with Connection objects. All defined Command hierarchies retain their structure.

To view By Connection

Click the Arrange by Connections button in the Data Environment designer toolbar.

Outline View By Connection

View By Object

By Object groups objects of the same type together. This enables you to focus on objects of a specific type, regardless of their associated connection.

To view By Object

Click the Arrange by Objects button in the Data Environment designer toolbar.

Outline View By Object

Hiding Field Objects in Your Data Environment Designer

By default, the Field objects of each Command object display in the outline view of the Data Environment designer. You can expand or collapse the view of these Field objects by clicking the plus (+) or minus (-) bitmap associated with the Command object. However, you can hide all Field objects completely from the outline view to clearly view relationships between Command objects.

To hide the Field objects for all Command objects

Right-click on the DataEnvironment object. The DataEnvironment object is the top-most object in your Data Environment outline view.
Clear the selection of Show Fields from the shortcut menu.

Modifying an Object in Your Data Environment Designer

You can modify any existing Command or Connection object by accessing either its Properties dialog box or the Visual Basic Properties window. Common modifications include changing a Command object's connection source, adjusting a Connection object's logon information, and renaming an object.

Note While using the Visual Basic Properties window provides a direct means of changing individual property values, it can be more difficult if you are unfamiliar with the properties associated with the object.

To modify an existing Command or Connection object using its Properties dialog box

Right-click the Command or Connection object to modify, and then select Properties from the shortcut menu to access its Properties dialog box.
-or-

Double-click your Command or Connection object to open its Properties dialog box.
To change any of the Command object's properties, from the Command Properties dialog box, click the appropriate tab: General, Parameters, Relation, Grouping, Aggregates, or Advanced, and then make the appropriate changes. For information on each tab's settings, click the tab, and then press F1 to access online Help for the Command object's properties.
Note When the source of a Command object is changed, the Data Environment updates its associated field and parameter information.
To change any of the Connection object's properties, from the Data Link Properties dialog box, click the appropriate tab: Provider, Connection, Advanced, or All, and then make the appropriate changes. For information on each tab's settings, press F1 or Help to access the online Help for the Connection object's properties.
Click OK to apply the properties to the object.

To modify an existing Command or Connection object using the Visual Basic Properties window

Select the Command or Connection object from the drop-down list in the Visual Basic Properties window.
Choose either the Alphabetic or the Categorized tab, and then change the property information in the right column as necessary.

Renaming an Object in Your Data Environment Designer

Upon creation, objects in your Data Environment designer are given default names, such as Command1, Connection1, or DataEnvironment1. However, you can change these to more meaningful, unique names. For example, if you are creating a connection based on the Northwind database, a logical name may be "Northwind." Likewise, if you are creating a command based on the customer's table, a logical name may be "Customers."

Note When a Connection object is renamed, any Command objects associated with it automatically update in the ActiveConnectionName property. In addition, when a Command object is renamed, its link to the Connection object and other Command objects is maintained.

To rename an object in your Data Environment designer

Right-click the object that you wish to rename and choose Properties from the shortcut menu. The Properties dialog box appears. Type a new name in the Name box and click OK to apply the changes and exit the dialog box.
-or-

Right-click the Command or Connection object you wish to rename and choose Rename from the shortcut menu. The outline view is now in edit mode. Type the new name, and then press ENTER to accept the change.

-or-

On the Visual Basic Properties window, select the entry to the right of (Name), and type the new name.

Deleting an Object from Your Data Environment

You can remove DataEnvironment, Connection, or Command objects from your Data Environment designer. When deleting an object, a warning message appears, unless Prompt before deleting objects is cleared in the Options dialog box. In addition, if the object selected for deletion has dependent objects, a message appears, asking if you also want to delete the dependent objects. For example, a Connection object has dependent objects if it is associated with a Command object, or a Command object has dependent objects if it is involved in a relation or grouping hierarchy.

Caution Once a Connection object is deleted, any Command objects associated with it become invalid, and the ActiveConnectionName property for all its associated Command objects is cleared.

To delete a Command or Connection object from your Data Environment designer

Select the object that you wish to remove and press DELETE.
-or-

Right-click the Command or Connection object that you wish to remove and choose Delete from the shortcut menu.
If Prompt before deleting objects is selected in the Options dialog box, warning messages display to alert you to any affects of the delete.

Refreshing an Object in Your Data Environment Designer

The Refresh function differs in function between Connection and Command objects.

Refreshing Connection Objects

When a refresh is performed on a Connection object, the connection is closed and the internal cache is cleared of the metadata associated with the Connection object. In addition, refreshing a Connection forces the Data Environment to open the connection. After the refresh, the next time a list of tables or stored procedures is accessed, the list is rebuilt.

Note Refreshing a Connection object does not automatically refresh its associated Command objects.

Refreshing Command Objects

When a refresh is performed on a Command object, all metadata stored with the object, including the Field and Parameter objects, is rebuilt. If the Command object's definition of the table or stored procedure has changed, the changes are reflected in the Command object after the refresh.

Caution Refreshing a Command object removes user-defined data, including parameter and field mapping information. Once removed, it cannot be retrieved.

To refresh a Connection or Command object

Select the Command or Connection object to refresh, and then click Refresh in the Data Environment designer toolbar.
-or-

Right-click the Command or Connection object to refresh, and choose Refresh from the shortcut menu.

Connection and Command objects are also refreshed whenever their respective source properties are modified.

Note The status bar text indicates whether a Connection object is open (connected).

Changing Warning and Confirmation Dialog Box Display

You can change the display of warning and confirmation dialog boxes using the Options dialog box.

To change warning and confirmation dialog box display

Click Options in the Data Environment designer toolbar.
-or-

Right-click a DataEnvironment object and choose Options from the shortcut menu.

From the General tab of the Options dialog box, set the following:

Item	Description
Prompt before deleting object	When selected, a confirmation dialog box displays when you delete an object. Note It is recommended that this option remain selected, so that the system presents an alert when deletion of an object affects other objects within your Data Environment.
Disable Warnings	When not selected, warning messages appear when appropriate.
Prompt before executing command	When selected, the system prompts you before executing a Command object. Occasionally it is not possible for the Data Environment to obtain field information about a Command object from the data provider using its normal processes. When the Data Environment is unsuccessful in obtaining metadata about the Recordset of a particular Command object, it attempts to obtain this information from the data provider by executing the Command object. Thus, your permission is requested before the Data Environment executes the user-defined code. Note This situation generally only occurs for Command objects based on stored procedures or SQL text.

Click OK to apply the options to your Data Environment designer and close the Options dialog box.