Creating and Setting Up CursorAdapters

The Data Builder can store a great deal of information about a CursorAdapter and its fields. You may decide not to set up all the information the Data Builder stores for every CursorAdapter and every field. Certainly, you don’t have to set up all field properties before you start using a CursorAdapter to build Application Objects. Most field properties can be entered and changed later.

However, there are certain CursorAdapter and field properties that you should set up as a minimum before you start building Application Objects. If you don’t set up those CursorAdapter and field properties, VPM Enterprise won’t be able to trigger all its automatic features that help you build Application Objects. 

You can, of course, set up all CursorAdapter and field properties before you start creating Application Objects. In fact, you are encouraged to do so. It’s probably more productive and efficient to use the Data Builder to set up all CursorAdapter and field properties at one time than to do it piecemeal.

This section describes how to create a CursorAdapter in the Data Builder and the minimum set up required for a CursorAdapter in the VPM Enterprise Data Builder. The section points out the CursorAdapter and field properties that you should set up before you build an Application Object that uses a CursorAdapter.

Tip – Adding Existing CursorAdapters: If you have existing CursorAdapters that you want to add to the Data Builder, see Adding CursorAdapters. You will need to “set up” the CursorAdapters in the Data Builder.

Ø To create & set up a CursorAdapter in the Data Builder

When you create a new CursorAdapter, create it through the VPME Data Builder. Make sure there is a CursorAdapter class library in the Data Builder to hold your new CursorAdapter class.

1.   Select “CursorAdapters”: In the treeview on the Data Builder List page select the “CursorAdapters” entry under the name of the CursorAdapter library in which you want to create your CursorAdapter class.

2.   Click New: Click the New button on the Data Builder List page. VPM Enterprise displays the New Class dialog.

   Enter the name you want to give your new CursorAdapter class in the Class Name textbox. Click OK. VPME brings up the Visual FoxPro Class Designer.

3.   Select CursorAdapter Builder in Class Designer: Right-click the icon in the Class Designer window and select Builder from the shortcut menu.

   VPME displays the CursorAdapter Builder. You use the pages on the CursorAdapter Builder to build your CursorAdapter.

4.   CursorAdapter Builder – Properties: You use the Properties page to identify the data source type and the data source for your CursorAdapter. The data source types you can choose are ADO (ActiveX Data Object), Native, ODBC (Open Database Connectivity) and XML (Extensible Markup Language).

   In this example, we will use an ODBC data source type and the System DSN that you created for the Northwind database Creating and Setting Up Remote Views. Therefore, in the Data source type listbox on the Properties page, select ODBC. Click the Use DSN option button and select Northwind in the Data source listbox.

   Click the Test Connection button to verify that you can connect to the Northwind database. Then, when the connection test succeeds, click the Data Access tab.

5.   CursorAdapter Builder – Data Access: You use the Data Access page:

·       First, to build the select command that will retrieve data from the data source; and

·       Then, to insert a WHERE clause in the select command to set filters using certain variables with specific names expected by VPM.

   Build Select Command: Click the Build button on the Data Access page to display the Select Command Builder. In the Table listbox, select the table to be used as the data source for the CursorAdapter. In our example, we will select the Employees table in the Northwind database.

    The fields in the table you select are displayed in the left fields list of the Select Command Builder. Move the fields that you want to access with your CursorAdapter to the right fields list. The Select Comand Builder will now look like this:

Tip – Include Primary Key: Be sure to include in the selected fields list the primary key field for the table that you want to update using the CursorAdapter.

   Click OK.

   The select command is now displayed in the Select command edit box on the Data Access page.

   Use CursorSchema: Click the “Use CursorSchema when filling cursor” checkbox to turn it on.

   Leave all other options on the Data Access page set at their default values.

6.   CursorAdapter Builder – Auto-Update: Click the Auto-Update tab on the CursorAdapter Builder to display the Auto-Update page. You use the Auto-Update page to specify how the CursorAdapter should update records in the data source table.

·       Auto-Update: Click the Auto-update checkbox to turn Auto-Update on.

·       Select Fields to Update: The Cursor field list shows all the fields that you selected for retrieval in the Select Command Builder. If you want to update all the fields in the Cursor field list, click the Update all fields checkbox. A check mark will appear to the left of all the fields. If you do not want to update all the fields in the Cursor field list, select the fields you want to update by clicking under the pencil symbol to the left of each field.

·       Primary Key Field: Click the box underneath the key symbol to the left of the primary key field. A check mark should appear.

·       Other Options: Leave all other options on the Auto-Update page set at their default values.         

7.   Close CursorAdapter Builder: After you have finished setting up the Auto-Update page, click OK to close the CursorAdapter Builder.

8.   Save and Close Class Designer: Click Save on the File Menu to save your new CursorAdapter class. Close the Class Designer.

When you return to the Data Builder you will see your new CursorAdapter in the List Page treeview under its class library. Click the “+” next to the CursorAdapter name, and you will see a list of the fields in the CursorAdapter.

9.   CursorAdapter Properties: With your new CursorAdapter selected on the List page, click the Edit page. On the Properties page under the Edit page, you can enter the following:

·       Description: Enter a brief description of the CursorAdapter; up to 100 characters. The description you enter is displayed to the right of the CursorAdapter name in the Data Builder List.

·       Comments: Enter any comments you want to record about the CursorAdapter in the Comments box on the Properties page. Enter as much text as you want. The comments you enter can be used to provide users of your application important information about the CursorAdapter.

·       Data Source: In the Data Source list box, select the entry that defines the elements of the CursorAdapter filter WHERE clause for the CursorAdapter’s data source. See Data Sources.

10. Field Description: For each CursorAdapter field that will appear on a form or report, select the Edit - Properties page and enter descriptive labels in the Description text boxes. Enter the descriptive label that you want to appear next to the field on a form or in the heading of a grid.

·       Description (Short) – Grid: Enter the label that you want to appear in the heading of a grid column.

·       Description (Long) – Form: Enter the label that you want to appear next to the field on a form.

11. Required Indexes: Create index tag definitions for the CursorAdapter by selecting the Tags treeview entry under the CursorAdapter’s fields list on the Data Builder List page. With “Tags” selected, click the New button and enter the index tag definition on the Edit Page. See Defining Indexes for CursorAdapters to learn how to create index tag definitions for CursorAdapters. You need to create index tag definitions for CursorAdapters to make Related Forms, One-To-Many forms and Related Pages forms based on CursorAdapters work. You can also create index tag definitions for the Toolbar Order control.

Tip: You must create the indexes described inRequired Indexes for CursorAdapters.

12. Referential Integrity:  If the CursorAdapter contains a foreign key field matching the primary key of another CursorAdapter, table or view, select the field and click the Edit tab. Then, click the Integrity tab on the Edit page to set up Referential Integrity validation for the field(s) in the foreign key.  VPM Enterprise uses your Referential Integrity validation setup to determine how tables, views and CursorAdapters are related to each other in an application.  See Referential Integrity for the details.

13. CursorAdapter Filters: If the CursorAdapter you are creating will be used with certain functionality provided by VPME,  you must set filters for the CursorAdapter using certain variables with specific names expected by VPM. You insert a WHERE clause in the Select command on the Data Access page to set the filters you need.

Examples of the VPME functionality that require CursorAdapter filters include using a CursorAdapter (a) as a child CursorAdapter on a One-To-Many or Related Pages form, (b) as an Initial Selected Alias CursorAdapter on a Related Forms parent form, or (c) with the SQL Find Form.

Tip – CursorAdapter Filter Instructions: The filters you must set and when you must set them are described in the next section CursorAdapter Filters. At this point, read the "CursorAdapter Filters" section and set up the filters that you determine your CursorAdapter needs.


CursorAdapter Filters