3. Interacting with FileFlex

FileFlex is a relational database engine. It's functionality is designed to store, retrieve, search, and sort text-based information. Unlike most database engines, which are standalone applications containing other features including user-interface builders and report writers, FileFlex only manages data. Also, unlike most other database engines, FileFlex is designed to be embedded within your application, not reside as an external application called by your application or communicated with via interprocess communications.

This embedded nature of FileFlex provides a great deal of benefit to the developer of multimedia applications: A principle design decision was that FileFlex uses each host application's "plug-in" architecture. This allows the host application to talk to FileFlex with no penalty for speed and allows FileFlex to be very tightly integrated into the programming environment of the host application. For example, in Director 5, the FileFlex engine exists as a Lingo Xtra. Just drop it into the Xtras folder and full relational database capability is available.

Wrapper Scripts

When you install FileFlex, your development environment talks with the FileFlex plug-in via "Wrapper Scripts". Wrapper scripts are very short handlers written in your host language's scripting language. Here's a sample wrapper script for Director 5, written in Lingo: 
  on DBSelect dbID
    DBCheckActive
    return FileFlex("5",string(dbID))
  end DBSelect
In the above example, the DBSelect function is defined. You'll learn later that DBSelect switches the current database from one open database file to another. The wrapper script does two simple functions. First it calls DBCheckActive, itself a wrapper that determines if the FileFlex engine has been properly initialized. Second, it calls the FileFlex engine plug-in with the function code "5" and with an ID number contained in the variable dbID.

The reason this is done is that the FileFlex engine is actually one solid code module. The FileFlex code knows which of it's forty-some-odd functions to perform based on which code number is specified. So, if FileFlex is passed a code 3, then it performs a DBUse to open a database. If it's passed a code 30, it knows to write a record to the database.

But programming by remembering all those numerical codes is difficult and hard to debug. It's much easier to remember descriptively named commands. These are the commands in the wrapper scripts, such as DBSelect above.

There is one other reason why the wrapper scripts are so important: You can place a breakpoint inside the wrapper. In this way, you can tell exactly what data you're passing to the database engine through the function's parameters, prior to actually invoking the engine. This debugging tool can often be an invaluable way to make sure you know what you're telling FileFlex to do.

FileFlex Has Its Own Data Files

FileFlex data files (the database) are external to your project . This is in direct contrast to how Director stores data. When you build a Director movie the "normal" way, you defined various text cast members within the movie. The data itself is stored in the cast members, and as you add data, the movie size grows.

There are some amazing advantages to having the data stored separately from the controlling application.

The first, of course, is speed. Text-based searches using FileFlex'ultra-high speed indexing technology allow you to go anywhere in the database virtually instantly. Because the data is structured specifically around this search mechanism, everything is optimized for speed.

The next key advantage to using your development environment as a front-end to data is how easy it is to change "views" or "layouts"on the data file. If you've used FileMaker, you know that you can have a bunch of different layouts for the same data fields. The layout is simply the way you look at the data. For example, you might have a purchase order system with fields such as P.O. number, vendor name and address, a list of items, expected date, and a total dollar amount. However, depending on the level of detail interest you have in the order, you might want to view the data different ways: with all the details, or just a summary of the information. FileFlex allows you to work the same way. Rather than having to switch your entire cast or stack, FileFlex lets you instantly jump between databases and sort orders without incurring any overhead of disk access.

Lastly, it is far easier to deliver updates to users of your software if the program or application is separate from the data. There's no need to try to save off the old data and read it into the new, updated project (or update all the scripts of the old movie). You just delete the old movie and replace it with the new. The data file is untouched.

xBASE Standard Data File Formats

When you create a FileFlex database, you're going to create one, two, or three different types of data files. They are: The value of using these file formats is that they are extremely fast and extremely common. While they're the native format for FileFlex, virtually any database engine can read and write the xBASE standard. Even products that aren't databases, like Word 6 and Excel, can both read and export into the DBF format.

One word of caution though: the xBASE standard, to which FileFlex adheres religiously, is the dBASE III file format. If you choose to export data from another application (say Access), be sure to specify the dBASE III format. If you select native, accellerated FoxPro format or dBASE IV format, FileFlex will refuse to recognize the file.

FileFlex Data Types

FileFlex supports the following native data types:

Managing Multimedia Data

FileFlex does not internally store "blob" data like graphics files, QuickTime movies, sounds, etc. This doesn't mean you can't or shouldn't use FileFlex to manage multimedia data. Far from it. Instead, you should store the images or video clips as individual files on disk, perhaps assigning them to specified folders or directories. Then, store the location, path, or some identifying characteristic inside a FileFlex text or memo field. When you want to access the image, do a search in FileFlex, grab the path from a character field, and just import the image into Director.

There are strong advantages to this approach. First, you're able to use your native image editing tools to modify the files. Second, you can replace images individually, rather than having to reinstall a complete database. And third, as you add images, you can span disk volumes or store certain images or multimedia components easily on different parts of your network.

Finally, by not storing multimedia data within the data file, the database files are substantially faster and smaller.

How Does "Relational" Work?

FileFlex is a fully relational database system. This means you can "connect"or "relate" data together. The best way to describe how this works is with our ever-popular mail list example.

Imagine a mailing list that consists of two "databases" or .DBF files. Here are the fields for the two databases: 
  NAME AND ADDRESS DBF            KEYWORD DBF

  Customer ID <-----------------> Customer ID
  Name                            Keyword
  Company 
  Street 
  City 
  State 
  Zip 
  Country
As a software publisher, we'd use the database for two purposes: doing direct mailings to new prospects, and tracking our registered customers.

Whenever a customer buys one of our products and returns the registration card, we enter his address information into the NAD (name and address) database and the product purchased in the keyword database. Since a customer might have purchased more than one product from us at varying times, there will probably be more than one entry in the keyword database.

Later, the customer calls us for technical support. Using the "view"that allows us to call up the customer's information on the screen, we ask the customer for his last name and zip code (which is how the data is indexed). Our program does the following: That's one use of the data. Here's another: Let's assume we've completed an upgrade to FileFlex. We want to do a mailing to our customers to give them the option of upgrading. Here's what our program does:
    a. Gets the customer ID from the keyword field
    b. Selects the NAD database;
    c. Selects the NAD database index for customer ID;
    d. Does a seek on customer ID;
    e. Retrieves and prints a label;

Calling FileFlex

Calling FileFlex is a simple matter of executing a function call. Here's an example that opens the database file "STARS.DBF": 
  put DBUse("STARS.DBF") into dbResult
As described earlier, DBUse is a wrapper that tells the FileFlex engine to open a database file. Every FileFlex function returns a value, which should be placed into a variable and then tested. In the above example, the result of the DBUse command is placed into the variable dbResult.

When you call most FileFlex functions, you should check the value returned by the program to be sure that no error occurred in the process. The mechanism by which FileFlex notifies you of an error is simple. If the value returned by the function call is less than zero, then an error occurred. The FileFlex Result Code Reference lists all the possible error codes.

To handle errors in your scripts, then, you must simply: Here is a simple example of dealing with a potential FileFlex error condition: 
  on mouseUp
    put DBUse("VIDEO") into dbResult
    if dbResult < 0 then
      beep
      exit
    end if
    -- continues other normal processing
  end mouseUp
This is a good general-purpose approach to the problem. However, you may wish to get more specific, as this expanded version of the above handler indicates: 
  on mouseUp
    put DBUse("VIDEO") into dbResult
    if dbResult = -120 then
      alert "Can't find VIDEO file"      exit 
    end if
    if dbResult = -200 then
      alert "Database file is bad"      exit 
    end if
    -- continue other processibng
  end mouseUp
If other errors could occur but you don't need to provide special handling for them, you can add another if-then clause to deal with those as well.

Six FileFlex functions can return positive results that indicate some special situation has arisen. When you use these functions, you should know that a return value of 1 means that the beginning of the file has been reached and a return value of 3 means the end of the file has been reached. . Here is an example of dealing with these conditions (the DBSkip call moves the pointer to the next record in the database): 
  on mouseUp
    put DBSkip(1) into dbResult
    if dbResult = 3 then
      alert "End of file reached"      exit
    end if
    -- continues normal processing
  end mouseUp


  [Previous Chapter]    [Table of Contents]    [Next Chapter]
Copyright (c) 1996 David Gewirtz under license to Component Software Corp. All rights reserved worldwide.