Welcome To The Home Of The Visual FoxPro Experts  
home. signup. forum. archives. search. google. articles. downloads. faq. members. weblogs. file info. rss. print.

What is FoxDataObjects?
FoxDataObjects (http://www.foxdataobjects.com) is an object/relational persistence and query engine for Visual FoxPro. It lets us develop persistent classes following object-oriented idiom - including association, inheritance, composition, and collections, and allows us to express queries using a simple Object Query language, as well as in native SQL. Basically the product automates the Data-Access layer of an n-Tier application, but more important, it maps our business object model to a relational model, connects our Business layer to any supported database engine and provides a simple API for object persistence and querying. In this article, we will re-create parts of the Tasmanian Traders (Tastrade) sample application, but in an n-Tier architecture to show some basic features of FoxDataObjects.

The Tasmanian Traders sample
When you installed Visual FoxPro on your computer, a complete set of samples where copied into the Visual FoxPro install folder. One of these samples is the Tasmanian Traders application. The Tastrade application is an order entry system for a fictional import and export company that sells specialty foods from around the world.

Tasmanian Traders provides order entry functionality, making it possible for users to:

- Create new orders
- Add items to orders directly
- Select items from previous orders
- Calculate line item extensions, subtotals, and order totals adjusted for discounts and freight

You can check the original Tasmanian Traders sample application located on your Visual FoxPro’s Samples folder to get an exact idea of the application.

Building the Application
This article assumes you have Visual FoxPro (7, 8 or 9) and FoxDataObjects installed on your computer. It will introduce you on how to begin the project, how to define the business objects’ classes, how to use FDO to create a complete relational model for the object model, how to use persistence services to test the classes’ definitions, and how to access the entire Business Rules layer services from the User interface layer.

From an Object-Oriented Analysis viewpoint, the central entity on this application is an Order, which is involved in the most relationships. Other entities directly or indirectly support an order:

- A customer places an order
- An employee creates or "takes" an order
- A shipper delivers the order
- Orders contain line items, which, in turn, contain products

Two entities, Supplier and Category, support the Product entity although they do not directly supply information for an order. Suppliers are the source of the products while the Category entity provides information that can be used to manage the products. In Tasmanian Traders, these entities are not very significant. In other applications, for example, an inventory management application, they would be.

To show how a complete object orientation helps us with the application design, we will create a generic Person class. Employee entity will inherit from Person. Customer and Provider will be related to a Person instance (as Contact). In addition, all Addresses will be managed as entities to show you how powerful an object model like this becomes.

Initiating the Project
The first step is to create a folder for the project files, so, use the Windows Explorer or your favourite file management tool to create a C:\Tastrade folder on your local drive.
FoxDataObjects allows us to begin our application development process right from the object model, therefore, on this example, we will use a PRG based approach for our business classes definitions, in order to be easy for you to cut and copy the samples code from the tutorial right into your VFP project.

Start Visual FoxPro (a short splash screen will announce you that FoxDataObjects is installed on your development machine) and type this in the Visual FoxPro’s Command window:

CD C:\Tastrade
Modify Command classes 

Then type or paste this code into the Classes.PRG edit window.

DEFINE CLASS Category AS Custom
      CategoryName  = ""
      Description   = ""
      PictureBitMap = ""
DEFINE CLASS Product AS Custom
      ProductName       = ""
      EnglishName       = ""
      Category          = .Null.
      QuantityInUnits   = 0
      UnitPrice         = 0.0000
      UnitCost          = 0.0000
      UnitsInStock      = 0
      UnitsOnOrder      = 0
      ReorderLevel      = 0
      Discontinued      = .F.
DEFINE CLASS Address AS Custom
      Street      = ""
      City        = ""
      Region      = ""
      PostalCode  = ""
      Country     = ""

Note that, in the class definitions, we have not defined properties for object identification, just the business-required attributes. This is the first difference we encounter why modeling our classes in a complete object oriented realm. In the object-oriented world, objects has identity by themselves, they do not require a “primary key”. The Primary Key concept appears when we deal with a Relational schema; however, that is a job for FoxDataObjects.

So, let us start using FoxDataObjects with your recently created business classes.

- Save your program file and select the Schema Manager option from the Visual FoxPro’s Tools menu. It will open the Schema Manager mapping tool with no schema file loaded.

FoxDataObjects stores all of the mapping information for your business classes into a Mapping Schema file (a XML file with a .FDO extension).

- To create an empty mapping file, choose File \ New and type a schema name like Tastrade. Make sure your folder name appears selected in the Folder field (the complete file name should appear as C:\Tastrade\Tastrade.FDO).

After creating the schema file, the Copy/Update FDO libraries files into project location form appears.

- Click on Do It and the FoxDataObjects API libraries will be copied into your project folder. Click on Done.

At this time, you have created a basic class library file (classes.prg), an empty mapping schema file (tastrade.fdo) and copied the FoxDataObjects library into your application folder (FDO.FLL and FDO.FXP).
The Schema Manager shows your empty mapping schema file in a two-panel split window. In the left panel, a Tree View control lets you navigate on both, the Object Model and the resulting Relational Model or Data Dictionary entries. The Object Model nodes show all of your Classes and Members definitions. The Relational Model nodes show all of the tables definitions needed to persist your object instances in a relational database. By now, your schema file is empty.

At development time, FoxDataObjects can parse your classes’ definitions either manually or automatically, and document them on the Object Model sub tree. You cannot add items directly to your Object Model tree. It is the current representation of your classes’ definitions from your class libraries.
To add a class or a member to your object model, it is as simple as adding a class definition or a member definition into your class library. It means that now, you will only need to focus on your classes’ code. There is no need to worry about maintaining synchronized definitions or parallel mapping structures like most of the ORM frameworks for Java or .NET require. FoxDataObjects parses your class libraries and maintain those structures for you.
Now you can instruct the Schema Manager to parse your library file in order to document your classes’ definitions for the first time.

- Choose Tools \ Parse class library… in the Schema Manager menu, and select your Classes.PRG file.

The class library is parsed and your classes are documented. Click to expand the Object Model node and you will see all of your classes and properties documented on the schema file as you can see in the figure. Note that in the Product class, the Category member is shown as an object pointer to any object (we will change that soon).

When you click on a Class node or on a Member node, the right side panel shows a form where you can document your object model item, customize how oxDataObjects maps the item to the Relational Model, and specify advanced options for Concurrency Control, Relationships definitions, and more.

At this time, all of your Object Model entities have been mapped into a Relational Model schema. Click to expand the Relational Model node and you will see all of the tables and columns definitions that FoxDataObjects created when mapped your Object Model.

Note that, by default, FoxDataObjects created a table definition for each class defined in the class library. Tables’ definitions contain not only the columns needed to store a given entity instance (one table column per single value type property or simple reference) but also a Primary Key column definition named Object_ID.

At this point, FoxDataObjects parsed your class library, documented your object model and mapped your classes and members into a complete relational model definition ready to be used to create a database on any supported data store and begin storing and retrieving object instances. All of this has been done almost without your intervention, you just written your class code. However, you may want to customize how FDO maps your classes or make changes to the resulting Relational Model. We will do that soon, but before making changes on the proposed schema, save the current mapping schema state:

- Click on the Save toolbar’s button or choose File / Save from the Schema Manager menu.

Therefore, without any code you are ready to begin storing objects instances on a real database!

To do so, you will use the Persistence Services provided by the FoxDataObjects library copied into your application folder (when you created the empty schema file).

FoxDataObjects provides a powerful persistence engine in two lightweight files. The FDO.FLL file contains all the low-level code (C++ compiled code) required to persist, retrieve and fill your object instances. However, all of the Persistence Services are exposed as an easy to use object model provided by a set of classes stored on the FDO.FXP file. The FDO.FXP file contains all the classes that wrap the C++ level functions calls and constitute a powerful interface to the complete services provided by FDO.

You will need to get a Session object (from the fdoSession class provided in the FDO.FXP file) in order to get access to all of the Persistence Services. A Session object represents a connection to a database and lets you Connect, Disconnect, Save and Retrieve Objects and so on.

The Server.NewSession() method works as a Session object factory. There are two main resources required to get a valid Session object:

- A Mapping Schema file (In this case Tastrade.fdo)
- A DataSource object

A datasource object is an easy to use wrapper around supported ODBC drivers (and VFP native databases) that provides meaningful information to FDO, not only on how to connect with the database layer, but also on what to do at the first connection time.
You can create a datasource object programmatically and set the minimum properties values required to connect to a data store or you can create and store a datasource definition directly in the mapping schema file. This way, Server.NewSession will look into your mapping schema file for a valid DataSource definition, and will use it to connect to the data store.
In the next steps, you we will show you how to create a datasource definition and store it on your recently created schema file.

- Click on the Tastrade (Main Schema) node on the Schema Manager left panel. In the right panel select the DataSources tab and click on the Add… button. You will be prompted to select the data store brand for which you want to create a datasource definition.

If you have SqlServer or MySQL installed on your local computer or in your LAN please select it. Otherwise, select Visual FoxPro (native DBC access) and make sure you create a dedicated folder for the database file named (as an example) data on your current folder (use the Windows Explorer or click on the Visual FoxPro Command window and type :

MD data

(Make sure your Database Path field contains the name of you data folder).

If you selected Microsoft SQl Server or MySql, make sure your Server, UID and PWD fields contains the proper information (leave the Database Name (DB) field empty). You can use the Test button to make sure the DataSource definition is valid.

- Click on OK and check that the datasource definition is added to the datasources list and marked as Default.
- Now you can close the Schema Manager (ensure your changes are saved)

Now, you can begin testing your classes and using persistence services. You can do it from the Visual FoxPro’s Command window:

? oSession.IsConnected && = .T.

At this point, you have a valid Session object. The Session object connected to the data store and created the database automatically for you.
If you created a datasource definition for native FoxPro databases, you can use the Windows Explorer and explore the C:\tastrade\data folder, where you will find the Tastrade.DBC container and all of the tables and indexes defined in the Relational Model data dictionary.
If you created a Microsoft SQL Server or MySQL datasource definition, use your favourite administrative or query tool to connect to your server and you will see the recently created Tastrade database.

With a valid Session object you can access all of the persistence services to save, retrieve or delete objects from the database. The next commands show how simple is to use the persistence services.

oAddress.Street="647 White Blvrd"
oAddress.City="New York"

? oSession.SaveObject(oAddress) && = .T.


? oAddress.City && New York
? oAddress.Street && 647 White Blvrd
? oSession.DeleteObject(oAddress) && = .T.

In this very basic example, FoxDataObjects mapped your classes, created the database container, tables and indexes, then, a simple address objects was saved, retrieved and deleted from the database. In the next article, you will learn how to make changes on mapping definitions and how to work with simple relationships.


Bernardo Fourcade RunAhead Technologies was founded in 1999 by the Visual FoxPro Senior Architect Bernardo Fourcade. Fourcade graduated with honors in Information Systems Engineering and Information Systems Analysis at Universidad Tecnológica Nacional. He started developing software early in 1986 with FoxBASE+ and closely followed the language evolution, working with every single version to the latest Visual FoxPro version. Beyond his deep commitment with the FoxPro platform, he also expanded to Visual C++, Visual C#, Visual Basic .Net, ASP3 and ASP.Net technologies. A solid experience on Project Management and the whole software development process, from designing, coding, testing, to deployment and re-engineering, lead him to work for some of the most important software companies. Prior to RunAhead foundation, he performed for more than 10 years as Chief Technology Officer at an important consulting company, mainly focused on the Health Care and Television Broadcast markets, where he lead and managed the most advanced and challenging software development projects. Now, at RunAhead Technologies, Fourcade is leading a strong development and supporting team, committed with the high standards of the industry. You can contact him at info@runahead-tech.com and you can find additional information at http://www.foxdataobjects.com/About.htm.


Fazil aliev @ 12/12/2008 6:08:53 AM
Hi I couldnot find scheme manager from Foxpro's tools menu(versions 6,7,9). Can you please clarify why I don't have that option. May it was from VB?


MR G @ 9/15/2016 3:52:25 AM

Your Name: 
Your Feedback: 

Spam Protection:
Enter the code shown: