Data Explorer Task Pane
The Data Explorer Task Pane is used to open data connections and to log on to servers and explore their databases. You can right-click on nodes to perform various actions against the data elements represented by those nodes. You can drag nodes from Data Explorer and drop them onto Visual FoxPro designers and editors. This creates new data controls on forms or code that is preconfigured to reference the item dropped.
To access the Data Explorer Task Pane, select Task Pane on the Tools menu to bring up the Task Pane Manager. Choose the Data Explorer Task Pane from the Task Panes drop-down list box at the top.
The Data Explorer is also a stand-alone application and can be run outside of the Task Pane manager. To run the Data Explorer as a separate application, execute the following command from the Command window.
DO HOME() + DATAEXPLORER.APP
Note
The Data Explorer stores your connections and settings in a table named DataExplorer.dbf, which is stored in your user data directory (see HOME(7)).
Using the Data Explorer
The Data Explorer is very easy to use. It has a simple interface that makes viewing and working with remote data easy. The basic operation of the Data Explorer is as follows:
You create a connection to your remote data such as a SQL Server database. This is done using the Add Connection button.
The connection appears as a node under the Connections root node and is persisted for future use.
You can expand nodes and view all the components of your data connection. When you select a node, detailed information about that node is shown in the description pane at the bottom.
You can right-click on individual nodes to perform actions such as browsing a table, examining a view definition or editing a stored procedure.
You can drag-and-drop nodes to Visual FoxPro editors and have code added for that specific node. You can also drag-and-drop to a form designer and have an appropriate control dropped to represent the node.
Use the Data Explorer to perform different actions with your remote data. The following is a list of some of the more common actions:
Add a new connection
Add a new connection to your remote data source by clicking Add Connection or by right-clicking the Connections root node and selecting the Add Connection… menu item. When the Add Connection dialog box appears, select a connection type. After choosing a connection type, you will be asked for more details about your data source. If you select a SQL or ADO Connection type, you will be prompted with a Connection Properties dialog box.Access an existing SQL Server
The SQL Servers root node is a convenient way for you to explore and access SQL Servers available from your network. Simply click on the root node to expand and view all available servers.Note
It is often more convenient to create a separate connection for a specific SQL Server database than to access it from the SQL Servers root node. A separate connection will also provide quicker access.
Modify an existing connection
Once the connection is added to the Data Explorer, it is persisted so that it is available the next time you launch Visual FoxPro. You can make modifications to the connection by right-clicking the connection node and selecting the Properties menu item.Work with Databases
If you select a SQL Server connection type, the nodes beneath the connection will be databases. With databases, you can expand the node to see various items including tables, views, stored procedures and functions.If using a SQL or ADO connection, you can drag and drop a database node to a program and code will be inserted that handles the connection and sets up a CursorAdapter object to retrieve data.
Work with Tables
You can expand the Tables node to see a list of all the tables in your data source. Information about that table, such as the owner or location, is displayed in the description pane. You can further expand a table node to view its fields.To view the data, you can right-click the desired table node and select the Browse menu.
To run a more advanced query, select the Run Query menu.
If you are working with a Fox table, you can right-click and select Design to open the Table Designer.
Note
Through the extensibility architecture, you can add design support for remote data sources such as SQL Server.
When you drag and drop a table to a form or class designer, a Grid control for that table is added.
Note
You will still need to add code or data environment objects to connect to the remote data source.
When you drag and drop a table to an edit window, code is inserted to view that table:
If you drag from a Fox table, a simple SELECT statement is inserted.
If you drag from a SQL or ADO connection, code is also inserted that handles the connection and sets up a CursorAdapter object to retrieve data.
Work with Views
You can expand the Views node to see a list of all views in your data source. Information about that view, such as the owner, is displayed in the description pane. You can further expand a view node to see its fields.To view the data, you can right-click the desired node and select the Browse menu.
To run a more advanced query, select the Run Query menu.
To see the definition of that view, select the View Definition menu.
Note
Certain connection types, such as an ADO connection to SQL Server, may not display this option.
If you are working with a Fox view, you can right-click and select Design to open the View Designer.
Note
Through the extensibility architecture, you can add design support for remote data sources such as SQL Server.
When you drag and drop a view to a form or class designer, a Grid control for that view is added.
Note
You will still need to add code or data environment objects to connect to the remote data source.
When you drag and drop a view to an edit window, code is inserted to browse that view:
If you drag from a Fox view, a simple SELECT statement is inserted.
If you drag from a SQL or ADO connection, code is also inserted that handles the connection and sets up a CursorAdapter object to retrieve data.
Work with Fields
You can expand a Table or View node to see a list of its fields. Information about that field, such as the data type, is displayed in the description pane. If Column Info is checked for that connection, the data type is displayed in the field node.Note
Certain connection types may not support displaying field detail.
To run a query, select the Run Query menu.
When you drag and drop a field to a form or class designer, a Textbox control for that field is added.
Note
You will still need to add code or data environment objects to connect to the remote data source.
When you drag and drop a field to an edit window, code is inserted to browse that field:
If you drag from a Fox field, a simple SELECT statement is inserted.
If you drag from a SQL or ADO connection, code is also inserted that handles the connection and sets up a CursorAdapter object to retrieve data.
Working with Stored Procedures
You can expand the Stored Procedures node to see a list of all stored procedures in your data source. Information about the stored procedure, such as the owner, is displayed in the description pane. You can further expand an individual stored procedure node to see its parameters.Note
Certain connection types, may not support this option.
To execute the stored procedure, you can right-click that node and select the Run Stored Procedure menu. If the stored procedure requires parameters, a dialog box prompts you to enter parameters. The results are displayed in the Run Query window where you can modify and execute your procedure again.
To execute your procedure with more control over the calling syntax, select the Run Query menu.
To see the definition of the procedure, select the View Definition menu.
To edit a procedure, select the Edit Procedure menu.
To delete a procedure, select the Delete Procedure menu.
To add a new procedure, select the New Procedure menu.
You can drag and drop a SQL or ADO connection stored procedure to an edit window. When you do this, code is inserted that handles the connection and calls the procedure. For SQL connection procedures, code is also included to set up a CursorAdapter object to retrieve data from the stored procedure.
Work with Functions
You can expand the Functions node to see a list of all functions in your data source. Information about the function, such as the owner, is displayed in the description pane. You can further expand an individual function node to see its parameters.Note
Certain connection types, such as a Fox connection, may not support this option.
To call the function, you can right-click the desired node and select the Run Stored Procedure menu. If the stored procedure requires parameters, a dialog box prompts you to enter parameters. The results are displayed in the Run Query window where you can modify and execute your procedure again.
To execute your function with more control over the calling syntax, select the Run Query menu.
To see the definition of the function, select the View Definition menu.
To edit a procedure, select the Edit Function menu.
To delete a procedure, select the Delete Function menu.
To add a new procedure, select the New Function menu.
You can drag and drop a SQL or ADO connection function to an edit window. When you do this, code is inserted that handles the connection and calls the function.
Use the Run Query Window
When you select the Run Query menu item, the Run Query window displays and contains commands of relevance to the selected node.For example, if you open the Run Query window for a table, the edit box contains a SELECT statement for that table. If you choose a stored procedure, an EXEC statement (applicable to SQL) will be shown.
With the Run Query window, you can type in a query, run it to see the results and perform additional add-in tasks such as copying the results to the clipboard.
To run a query, enter in a query command such as SELECT or EXEC statement and click the Run button. The results will be displayed in the lower portion of the window.
Set a Filter
You can select the Filter menu to set a filter to display only child nodes that match or do not match the specified criteria. For example, you may want to filter for all tables that begin with "sys" to exclude system tables.Refresh Data Nodes
If you right-click a node, you can select the Refresh menu to have all child nodes refreshed.
Add Connection Dialog Box
The Add Connection button brings up the Add Connection dialog box so that you can create a new persisted connection. You can choose from SQL Server, Visual FoxPro or ADO data sources. The following types are available in this dialog box:
Connection Type |
Description |
---|---|
SQL Server |
A connection to a SQL Server. The connection node will display separate nodes for each database in that server. |
SQL Database |
A connection to a SQL Server database. |
FoxPro Directory |
A connection to a directory. The connection node displays separate nodes for each Visual FoxPro database (.dbc). |
FoxPro Database |
A connection to a Visual FoxPro database. |
FoxPro Table |
A connection to a Visual FoxPro table. |
ADO Connection |
A connection to an ADO data source. Note If you are creating ADO Connections to SQL Server, it is recommended that you instead use one of the SQL Server connection types since there is more functionality available, such as additional shortcut menu items. |
SQL Connection Properties Dialog Box
The SQL Connection Properties dialog box is used to specify connection information to a SQL Server database. This dialog box appears when you first create a SQL connection for either the SQL Server or SQL Database connection type. You can bring this dialog box up later and make changes once the connection is created by right-clicking the specific connection node and selecting the Properties menu item.
Server Name
You can type the SQL Server name in the combo box directly or select one from the drop-down list box. The drop-down list box contains the same list of servers that appear under the SQL Servers node.Database
Once you have chosen a SQL Server, you can pick a database for your connection. This option is only available for a SQL Database connection.Note
You may be prompted to enter a Login/Password combination if the current Trusted Connection does not permit access to the list of databases for the selected server.
Use Trusted Connection
Select this to use your Windows login credentials to connect to the SQL Server.Login
If you uncheck Use Trusted Connection, you can specify a SQL login name to use for the connection.Password
If you uncheck Use Trusted Connection, you can specify a SQL login password to use for the connection.Connection Timeout
Specifies the time to wait (seconds) before returning a connection time-out error. If you specify 0, the wait is indefinite and no time-out error is returned. The value can be from 0 to 600.Note
This is equivalent to using SQLSETPROP(0, “ConnectTimeOut”, nTimeout) before establishing the connection.
Query Timeout
Specifies the time to wait (seconds) before returning a general time-out error. If you specify 0, the wait is indefinite and no time-out error is returned. The value can be from 0 to 600.Note
This is equivalent to using SQLSETPROP(nHandle, “QueryTimeOut”, nTimeout) before executing the query.
Show Column Info
Displays the column type and length next to the column name on each column node.Sort Objects
Sort objects beneath the connection by name.
ADO Connection Properties Dialog Box
The ADO Connection Properties dialog box is used to specify connection information to an ADO data source (OLE DB Provider). This dialog box appears when you first create an ADO connection. You can open this dialog box later and make changes once the connection is created by right-clicking the specific connection node and selecting the Properties menu item.
Use DSN
Specify a connection using an existing DSN. Enter the necessary OLE DB Provider information by select an available data source from the drop-down list box and optionally entering a User ID and Password.Use Connection String
Enter a valid connection string. The Build button is available to assist in generating the connection string. This button opens the standard Data Link Properties dialog box where you can chose a registered OLE DB Provider.Connection Timeout
Specifies the time to wait (seconds) before returning a connection time out error. If you specify 0, the wait is indefinite and no time out error is returned. The value can be from 0 to 600.Note
This is equivalent to using SQLSETPROP(0, “ConnectTimeOut”, nTimeout) before establishing the connection.
Query Timeout
Specifies the time to wait (seconds) before returning a general time out error. If you specify 0, the wait is indefinite and no time out error is returned. The value can be from 0 to 600.Note
This is equivalent to using SQLSETPROP(nHandle, “QueryTimeOut”, nTimeout) before executing the query.
Show Column Info
Displays the column type and length next to the column name on each column node.
Run Query Window
The Run Query window is a core part of the Data Explorer. It allows you to execute queries against the selected data node. You can also execute stored procedures and functions. To run a query, perform the following steps:
Right-click a data node whose data you want to query and select the Run Query menu.
If text is in the top edit box, you can click the Run button to execute the query. If no text is displayed, enter a query such as a SELECT statement and click Run.
The results of your query will appear in the bottom half of the Run Query window in a grid. If the query was unsuccessful, an error will appear in the lower results pane. You can edit your query to fix the problem and click Run to requery.
The Run Query window also allows you to execute stored procedures and functions. If these return result sets, such as from SQL Server, they will be displayed in a grid. Otherwise, the results are stored in the results pane.
The Run Query window supports add-in extensibility that allows for custom actions against the query or the data results. Add-ins which are managed using the Add-In Manager (Options dialog box), appear as buttons above the query edit box and results pane. You can also access add-ins by right-clicking the query edit box.
The following add-ins are included with Visual FoxPro and can be modified using the Add-In Manager:
Add-In |
Description |
---|---|
Save Query |
You can save your current query text to a text file with a .SQL extension. This is a query add-in. |
Load Query |
You can load a previously saved query from a text file. This is a query add-in. |
Format for VFP |
This modifies the current query to add a continuation character (;) to the end of all lines, remove any blank lines, and convert any SQL "--" comments to "&&". In addition, all brackets surrounding words are removed. This is useful if you have a SQL statement originally written for SQL Server and want to run it against Visual FoxPro data. For example, the following query: SELECT [au_lname] FROM [pubs] -- retrieve all last names is reformatted as: SELECT au_lname ; FROM pubs && retrieve all last names This is a query add-in. |
Format for SQL |
This modifies the current query to remove any end-of-line continuation characters (;), convert any VFP comment lines that begin with "*" to SQL comment lines beginning with "--", change double quotes to single quotes, and change double equals (==) to single equals (=). This is useful if you are modifying a query originally written to go against VFP data to run against SQL Server data. This is a query add-in. |
Clipboard to Variable |
Copy query to clipboard formatted with variable assignment. This is a query add-in. |
Clipboard to TEXT/ENDT |
Copy query to clipboard formatted with TEXT ... ENDTEXT Command. This is a query add-in. |
Copy Results to Clipboard. |
The data displayed in the grid is copied to the clipboard. This is a data result add-in. |
Options Dialog Box
- The Options dialog box allows you to customize the Data Explorer and connection behaviors.
Font
Sets the default font used by the Data Explorer.Show Description Pane
Displays a description pane at the bottom of the Data Explorer.Show Column Info
Shows column data type info in column nodes. This is the default setting for new connections. You can change this later in the Connection Properties dialog box.Note
If the description pane is visible, column data type info is displayed there for the selected column.
Manage Add-Ins
Opens the Add-Ins Manager.Manage Menus
Opens the Menu Manager.Manage DragDrop
Opens the DragDrop Manager.Restore to Default
Restores the Data Explorer to its default settings.A backup of the original DataExplorer.dbf table is made with the name DataExplorerBackup_xx.dbf, where xx is a sequential number so that prior backups are not overwritten.
Add-In Manager
The Run Query window lets you add new and customize existing add-ins for working with your queries as well as the query data results. These add-ins appear in the Run Query window as buttons. Add-Ins are stored in your DataExplorer.dbf settings table.
Query Add-Ins
Add-Ins that appear at the top of the Run Query window and apply to the query.Data Results Add-Ins
Add-Ins that appear toward the bottom of the Run Query window and apply to the results that appear after the query is run.Add-In List
List of all registered Add-Ins. When you select an add-in, its details appear in the controls to the right.New
Creates a new add-in.Delete
Removes an add-in.Move Up/Move Down
Use the arrows to move a selected add-in up or down in the list order. This controls the position the add-in appears in the Run Query window.Add-In
Specifies the full descriptive name of the add-in.Abbreviated Name
Specifies how the add-in is displayed in the menu bar.Select Image
Select the image to be associated with the currently selected add-in.Script Code Editbox
Specifies the code to execute when the add-in is selected. The script must accept one parameter, which is an object containing the query text, a reference to the data management object, and a reference to the DataExplorer engine.Modify
Brings up editor window to modify script if you want a larger edit window.
Menu Manager
The Menu Manager lets you customize shortcut menus items available for specific nodes. Menus are stored in your DataExplorer.dbf settings table.
Menu List
List of all registered menus. When you select a menu, its details appear in the controls to the right.New
Creates a new shortcut menu item.Copy
Creates a new shortcut menu item using definition from selected item.Delete
Deletes a shortcut menu item.Move Up/Move Down
Use the arrows to move a selected menu up or down in the list order. This controls the position the menu item appears in a node's shortcut menu.Caption
Specifies the name of the custom menu as it appears on the context menu of node. Use “\-“ to create a menu separator.Additional Info
Allows you to easily categorize menu items. This is displayed as the second column in the list of menu items.Template
Optional template of code that can be referenced in the menu's script code. Click the Modify button to open the code in an edit window.Display Only
This page lets you control which nodes will display the menu. The Display only… text box lets you include a comma-separated list of node names (classes) that can display the menu. You can specify an asterisk at the end of any node name to specify any nodes that begin with the text.Code to Determine…
Code that is executed for specified node classes included in the Display Only text box that can further be used to filter whether a menu is displayed or not. This is particularly useful if you want to limit a menu to only certain Providers with ADO Connections.The code must accept a single object parameter containing information about the node.
Click the Modify button to open the code in an edit window.
Script To Run
Code to execute when the menu item is selected.The code must accept a single object parameter containing information about the node.
Click the Modify button to bring up the code in an edit window.
DragDrop Manager
The DragDrop Manager lets you customize the drag-and-drop behavior for specified nodes. Drag-and-drop actions are stored in your DataExplorer.dbf settings table.
DragDrop Item List
List of all registered drag-and-drop actions. When you select an item, its details appear in the controls to the right.New
Creates a new drag-and-drop item.Copy
Creates a new drag-and-drop item using definition from selected item.Delete
Deletes a drag-and-drop item.Move Up/Move Down
Use the arrows to move a selected item up or down in the list order. This controls the order in which action's code is executed.Caption
Specifies the name of the drag-and-drop item for future reference.Template
Optional template of code that can be referenced in the script code. Click the Modify button to open the code in an edit window.Execute Only
Specifies a comma-separated list of node names to apply the drag-and-drop action. If this is left blank then the node check is not performed. You can include an asterisk at the end of any node name to specify any nodes that begin with the text.Script To Run
Code to execute when you drag and drop from a node to edit window.The code must accept a single object parameter containing information about the node. If you want to specify text to insert, you need to set the parameter object’s DropText property.
Click the Modify button to open the code in an edit window.
Extending the Data Explorer
The Data Explorer that ships with Visual FoxPro includes support for many core remote data needs. With the extensibility architecture, you can add additional capabilities not currently available such as the ability to modify remote tables or views through a custom designer. Additionally, you can add support for new remote data sources as they become available in the future (such as new versions of SQL Server).
The Data Explorer can be extended by adding, removing, or swapping in node classes or connection manager classes. Each of these is defined in the DataExplorer table which is located in the user data directory (see HOME(7)). If the table is not found, then it is automatically created using the DataExplorerDefault.dbf table that is bound into the DataExplorer application.
Note
If you want to make modifications or enhancements to the Data Explorer, you can find the source in XSource.zip contained in the Tools\XSource folder.
DataExplorer.dbf
Much of the Data Explorer extensibility is handled through this table so that you do not need to make modifications to the DataExplorer.app file. All of the customizations that are set by the various managers in the Options dialog box stored in this table.The following table contains details on extending the Data Explorer settings table:
Fieldname |
Type |
Description |
---|---|---|
UniqueID |
C(25) |
A unique ID for the record created. This should be in the format of: vendor.id For example: microsoft.textscraps |
DefType |
C(1) |
The record definition:
|
ConnType |
C(25) |
Connection type for a user created connection. |
ConnName |
C(100) |
Name of the connection. |
ConnInfo |
M |
Connection info. |
ClassName |
M |
Name of class. |
ClassLib |
M |
Name and location of class library. |
ScriptCode |
M |
Script code to run. |
DisplayOrd |
I |
Display order. |
Options |
M |
Optional data for specific DefType record. |
OptionData |
M |
Contains node settings that can be customized by the user. This applies to Connection and Root nodes. For connections, connection properties are stored in this field. |
Template |
M |
Can be used by add-ins. |
WhenNodes |
M |
Comma-delimited list of nodes that a menu add-in applies to. |
WhenCode |
M |
Script code to execute when determining if a menu add-in should be displayed. |
AddinImage |
W |
Image to display for add-in. |
Inactive |
L |
If set to TRUE (.T.), then record is ignored. |
User |
M |
User-defined. |
Modified |
T |
Last modified. |
The following table contains details about the different DefType field values in the Data Explorer table:
DefType Value |
Description |
---|---|
R |
Root. Contains detail about root node. Data Connections and SQL Servers are the pre-defined root nodes. |
S |
Data Source. Specifies a valid connection type that can be made. The following columns are utilized:
|
C |
Connection. Contains a user created connection. |
M |
Menu. Specifies a right-click menu option that is available for a node.
If the first word of ScriptCode is 'THIS.', then the DataExplorer assumes it is a method of the data management class and will run only if it finds the specified method name to be a member of that object. If the DataExplorer finds a method called <MethodName>Okay(), then the DataExplorer calls this method first to determine if the menu option should be visible or not (and returns TRUE if it should be included). If the first word of ScriptCode is not ‘THIS.’ then the run the code is executed normally. |
P |
Picture. Contains image used to represent a certain node. ConnInfo - relative location of picture, such as "bitmaps\column.bmp." |
T |
Template (reserved for future). |
Q |
Query Add-In. This is a Run Query window query add-in that appears as a button towards top of window or from the shortcut menu. The following fields are used.
|
Z |
Data Add-In. This is a Run Query window data add-in that appears as a button towards bottom of window. See Query Add-In above for more detail on fields used. |
E |
Expanded Info (reserved for future). Stores which nodes are expanded when the Data Explorer is closed so that these same nodes can be expanded when restarted. This information is stored in the OptionData column. |
Y |
DragDrop Action for Code Window.
|
V |
DragDrop Action for Design Surface. See previous item for details. |
Customizing ADO Connections
The Data Explorer contains support for generic ADO connection handling. However, you may want to customize for a specific connection type. In fact, the Data Explorer contains an example of this using Oracle. Here are steps you need to do to add this type of customization:Create a new class based on the core ADO Data Management class. Here is an example of the Oracle one in Datamgmt_Oracle.prg:
DEFINE CLASS OracleDatabaseMgmt AS ADODatabaseMgmt OF DataMgmt_ADO.prg
In this class, you can specify behaviors such as how to populate nodes or right-click menu functionality.
You can rebuild the DataExplorer.app with your new class or just leave it external.
You need to reference this class in your DataExplorer.dbf so it can be used. To do this:
Open the DataExplorer.dbf table from your HOME(7) location and locate the ADO Connection record (Deftype="S").
Open the ScriptCode memo field
Add another CASE statement to existing code (below) for your specific provider along with the custom class information.
LPARAMETERS oParam, oConn IF TYPE("oConn") == 'O' AND !ISNULL(oConn) DO CASE CASE ATC("ORACLE", oConn.DBMSName) > 0 oParam.DataMgmtClass = "OracleDatabaseMgmt" oParam.DataMgmtClassLibrary = "DataMgmt_Oracle.prg" oParam.ProviderName = "ORACLE" CASE ATC("SQL Server", oConn.DBMSName) > 0 oParam.ProviderName = "SQLSERVER" CASE ATC("FOXPRO", oConn.DBMSName) > 0 oParam.ProviderName = "FOXPRO" ENDCASE ENDIF
To add custom right-click menu and drag-and-drop functionality, use the specific managers available from the Options dialog box. For hints, take a look at the existing items in the various managers.