4. FileFlex and Director 5

Glenn Picher, a leading Director developer, recently wrote about FileFlex and Director for the February '96 issue of the Lingo User's Journal. The description was so clear that we asked for and got permission reprint portions of the review below:

Database Access in Director

When a multimedia production grows in scope to include a large volume of data, Director's built-in Lingo facilities for managing data can be pushed beyond their limits. Director's text cast members (in which you might store list data) have a 32K maximum on the Mac, and the FileIO XObject has problems reading in text files of more than 64K on Windows. There are also performance problems in searching large lists with Lingo. Symbol searching is fast on both the Mac and Windows platforms, but on Windows, a 64K limit on symbol data and list size effectively force you to use much slower string-based searches in smaller sublists. Windows string searches are considerably faster than on the Mac, probably due to the Intel x86 family of processors' one-opcode string instructions; but even on Windows, string searches can be slow with large volumes of information. Such Lingo-coded database schemes also can tie up a good deal of memory, which can be a problem on low-horsepower machines.

FileFlex from Component Software is a good solution that extends the volume of information possible in cross-platform Director multimedia productions, while kicking access speed into overdrive and simplifying the creation of data.

FileFlex is a database "back end" that your end users never see. You can design an interface "front end" any way you please with the Director cast members you're used to, then use Lingo to tie into the FileFlex back end for database functions. Since FileFlex uses compiled code, rather than interpreted Lingo, performance is in an altogether different league.

Rather than storing database information in Director cast members or in its own proprietary file format, FileFlex is designed to read and write standard dBASE-format files, supported by FoxPro, FileMaker Pro, and many other database applications on both Mac and Windows. Significantly, this means your data can be created, checked and updated independently of your Director development efforts. This can free the time and brainspace of a Director-saavy Lingo programmer while someone else massages the actual database content. Thus even a client who might know nothing at all about multimedia production, but knows a database program even better than you do, can join the production team in a meaningful way .

This approach gives you the power of a full-featured database application while creating your title, and even opens the door to useful authoring-time automation such as AppleScript droplets in combination with FileMaker Pro. This can be especially helpful in converting existing databases for use in multimedia productions. Since you'd only use a full-featured database program while you're authoring, you'd only need to license FileFlex-- small, fast and relatively cheap-- for end users. FileFlex itself has a very small footprint, both on disk and while active in memory. Alternatively, you can reconfigure and update databases with FileFlex using Lingo, without any database program.

FileFlex supports over a billion records in a single database file, allows access to multiple databases, and supports multiple independent index files (for speed in searching) for each database. Practically speaking, you'll never push these limits with Director. FileFlex databases don't store pictures, sounds or digital video movies per se, but could be used to keep track of internally stored castmembers, or even externally stored files that Director can import on-the-fly using Lingo's "the filename of cast" property or "importFileInto" keyword .

The software development kit for FileFlex is licensed separately from a distributable runtime version. The only difference is a not-too-onerous copy protection encryption scheme built into the runtime version which does not affect performance in any way. The runtime version only opens database filenames that have been pre-encrypted at authoring time.

The SDK and runtimes are licensed separately for each platform. The SDK lists for $195, but can be had for $119 plus $8 shipping. Run-time licenses are $100 per title plus $8 shipping. In short, it'll cost you $470 to license FileFlex for a crossplatform project. If your client will be reselling the product, they'll need to own their own SDK and runtime licenses.

Designing Databases for Use in Director Productions

How would you design a database and use it in a Director production? The database contents are most easily created and maintained in a full-featured database program such as FoxPro or FileMaker Pro. You'd first define the structure of the database according to the needs of your multimedia presentation.

dBASE files are defined by the "fields" they contain. A field is akin to a variable name in Lingo; each contains one discrete piece of information. For example, suppose you wanted to present a timeline in a Director project. For each event in the timeline, you'd need to record the date, a short description of the event, the name of a picture to be displayed when the event is viewed, a more lengthy narrative description of the event, and perhaps cross-references to subjects contained elsewhere in the project to which the event is relevant. Using FoxPro, you could use the Catalog Manager to define a table containing the fields "DATE", "DESCRIBE", "PICTURE", "FULLTEXT" and "SUBJECTS".

Unlike Director variables, database fields are generally defined in advance with a fixed size to represent a particular type of data, such as a date, a string or an integer. But it's also possible to use a free-form "memo"field when the size of the data isn't known in advance or varies widely. In this example, the "FULLTEXT" field would likely be a memo field, since a thorough narrative desciption of an event might take a sentence or a few pages. Memo fields can store up to 32K of text or other data.

Each event would be entered into the FoxPro table as a separate "record", which groups together data for all the defined fields of a particular event in the timeline. The table could contain any number of individual event records. The table can then be exported as a dBASE file with memo information, which actually generates two files. For example, the FoxPro "Events"table would be exported to "Events.dbf" (which contains the definition of the fields in the database, followed by all the individual event records) and to "Events.dbt" (which contains all the memo fields used in the database). These files are then used by the FileFlex externals within Director.

When your Director project first starts up, you need to set up FileFlex before actually opening any database files. In the startMovie handler, for instance, you would use the DBInitPlatform() FileFlex handler to locate and open the FileFlex engine. Once the externals are loaded and available, you initialize FileFlex with the DBOpenSession() handler. This sets up some global variables that FileFlex needs internally. Finally, you're ready to open a database.

The DBUse() handler opens a database file. Its syntax is variable. You can pass a full pathname, or a filename followed by the full pathname to its containing folder. For example, DBUse("events", the pathName) will open the .dbf database file created by FoxPro in the example above, assuming it's located in the same folder as the currently running Director movie. Since projects running from a CD or run on both platforms can't know the users' hard drive names in advance at authoring time, this two-parameter usage is much preferred. It's also important to use the two-parameter syntax for any project in which you will distribute the runtime version of FileFlex, since all filenames must encrypted at authoring time. The separate pathname needn't be encrypted.

If the database opened by DBUse() contains memo fields, its matching .dbt file is also implicitly opened. Since FileFlex allows more than one database to be open at a time, the final step is to call DBSelect(), supplying the database number returned by the DBUse() handler. Now you're ready to access records in the database.

At this point, your Director interface might display a splash screen, let the user choose where to navigate to, and ultimately end up in the timeline screen. You might provide button controls for selecting a particular year, zooming the scale of the timeline, or scrolling the timeline from left to right. Given the users' choices, you'd then want to extract events from the appropriate time period from the database and display them on the screen.

It's beyond the scope of this article to provide a detailed implementation of this timeline example. However, you might use some of the following FileFlex calls to extract information to the screen:

-- DBTop(), DBBottom(), DBGo(), DBSkip() and DBLocate() to select particular event records.

-- DBCount() to determine how many records are available

-- DBGetCurrRecVal("G") to set Lingo global variables (using the same names as the database's fields) to the values defined by the current record.

--DBFindMemo() to locate records with memo fields containing certain words.

--DBUseIndex(), DBCreateIndex(), DBSelectIndex(), or DBCheckIndex() to work with "index" files, which are a very quick way to sort and locate information. FileFlex uses .ndx formatted index files, rather than FoxPro's .idx format; however, this isn't a problem, since FileFlex can create its own .ndx files from FoxPro .dbf files.

When your Director project quits, you'll want to be sure to use DBClose() and DBClosePlatform() to free FileFlex's open files and resources.

Again, we'd like to thank Glenn and Tab Julius (publisher of the Lingo User's Journal) for permission to use the above article.

Using FileFlex with Director 5

Director has some amazing interactive media presentation capabilities. It would be an ideal front-end development tool except for one problem: it has no data storage mechanism. FileFlex solves that problem.

The Director application and multimedia production take up the vast majority of system resources. FileFlex, embedded in within the Director movie file and using only 100K, can search, sort, save, and retrieve information in industry-compatible database files external to the Director movie files.

FileFlex Adds Database Commands to Lingo

Think of FileFlex as an extension to the Lingo scripting language (this, of course, means you've got to be conversant with Lingo before you'll be able to use FileFlex). FileFlex provides no interface tools (not even alerts!), so it doesn't get in the way of your carefully crafted multimedia presentation. Instead, FileFlex provides a broad set of information storage, searching, access, encryption and management functions. FileFlex also provides ragingly-fast dynamic, on-the-fly encryption and full text search and retrieval.

The easiest way to make use of FileFlex within Director 5 is to drop the FileFlex Lingo Xtra into the Xtras folder where your Director application is located. Alternatively, you can use the OpenXLib Lingo command to provide access to the FileFlex code resources. Once you've done this, FileFlex API calls behave like any other Lingo functions.

Cross Platform Considerations

Director users can embed database capabilities in their movies and be confident they'll be usable under both Macintosh and Windows. There are only a few minor concerns you'll need to take into account when using FileFlex across platforms: 
     if DBPlatform() is "FFWIN" then
       put DBUse("C:\DEV\DBHOUSE\NAMES.DBF") into dbID
     else
       put DBUse("Windy City:Data Warehouse:Names.dbf") into dbID
     endif
That's it. Otherwise, your Lingo calls to FileFlex will be the same and the data files will be the same. We designed the Windows version specifically to make cross-platform porting as effortless as possible.

Installing FileFlex Files

FileFlex is very simple to install. All you need to do is copy the files into their appropriate locations as described in the next few paragraphs.

FileFlex takes full advantage of the Director 5 Xtra interface. This means that there are optimized versions of FileFlex for Macintosh 68K, Macintosh PPC, Windows 3.1, Windows 95, and Windows NT.

FileFlex Engine Files

The following files represent the actual Lingo Engine Xtra for Director 5: Note: Users of the bundled Lite version will have files called FileFlex Engine Xtra Lite, FFDIR5LT.X32, and FFDIR5LT.X16, respectively.

FileFlex Tool Xtra Files

FileFlex also includes a number of tool Xtras that make accessing and manipulating FileFlex data more effective. These include:

FileFlex Movie Utility Files

FileFlex includes a number of Director movies that are used as utilities to FileFlex. These utilities should be launched using the tool Xtras described above, but they can also be launched by selecting Open from the Director File menu (not recommended). Each of these files has a dash ('-') in front of it's name. This is so Director 5 doesn't display the name of the movie in the Xtras menu. Finally, FileFlex includes a test data folder containing the VIDEO.DBF and VIDEO.DBT data files.

Note: If you want to modify these files, MAKE A COPY and place them outside the Test Data folder. The FileFlex Validation Suite relies on the files in the Test Data folder being exactly as shipped from the Factory. Also, after running the validation suite, you may wish to remove from the Test Data folder all of the various temporary DBF, DBT, and NDX files other than VIDEO.DBF and VIDEO.DBT created by the validation suite.

FileFlex Folder/File Structure--Macintosh

Here's how your files should be arranged in their folders on the Macintosh:

FileFlex Folder/File Structure--Windows 3.1

Here's how your files should be arranged in their folders on Windows 3.1:

FileFlex Folder/File Structure--Windows 95 and Windows NT

Here's how your files should be arranged in their folders on Windows 95 and Windows NT:

Color Palette Considerations

The various utility movies all use the "System - Mac" 8-bit color palette and when invoked by the tool Xtras, are displayed as movies in a window (MIAW). There are some color concerns here because your movie may not (and probably won't) have the same color palettes as the utility movies. When each of the utility movies displays, it will attempt to change the palette to the "System - Mac" palette so the movie graphics look correct. When it exits, it will tell the stage to return the color palette back to it's original form. This will work fine if your movie is running. If it is stopped, however, the palette will not revert until you rewind or otherwise reset your movie to show your palette.

Upgrading from Earlier FileFlex Releases

If you're upgrading from an earlier FileFlex release, there are some things you should be aware of:

A Sample Lingo Session with FileFlex

What follows is a Lingo session (from the Director Message Window) showing some basic FileFlex interaction with Director: 
--   Welcome to MacroMind Director
--
put DBOpenSession()
-- "0"put DBUse("Video.dbf")
-- "1"put DBSelect("1")
-- "0"put DBListFields()
-- "12
TITLE,C,30,0
DESCRIPT,M,10,0
RATING,C,4,0
TYPE,C,10,0
DATE_ARRIV,D,8,0
AVAILABLE,L,1,0
COST_RENT,N,6,2
COST_BUY,N,6,2
TIMES_RENT,N,5,0
NUM_SOLD,N,5,0
FORMAT,C,3,0
LENGTH,N,3,0
"--
put DBGetCurrRecVal("L ") 
-- "1
N
TITLE,C,AMADEUS
DESCRIPT,M
RATING,C,PG
TYPE,C,Drama
DATE_ARRIV,D,19871225
AVAILABLE,L,F
COST_RENT,N,1.00
COST_BUY,N,1.00
TIMES_RENT,N,245
NUM_SOLD,N,125
FORMAT,C,1B
LENGTH,N,120
"put DBGo("15")
-- "0"put DBGetCurrRecVal("L ") 
-- "15
N
TITLE,C,THE FOG
DESCRIPT,M
RATING,C,R
TYPE,C,Suspense
DATE_ARRIV,D,19840831
AVAILABLE,L,T
COST_RENT,N,2.99
COST_BUY,N,29.95
TIMES_RENT,N,4478
NUM_SOLD,N,2348
FORMAT,C,VB
LENGTH,N,94
"
Of course, you'll want to embed your Lingo code within buttons and pretty screens.

FileFlex is an amazingly versatile tool. Combine it with the visual power of Director and there's no limit to the cool projects you'll be able to create.


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