FILEFLEX PROGRAMMER MANUAL


CHAPTER 6
FileFlex and Director

Glenn Picher, a leading Director developer, wrote about FileFlex and Director for 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 Xtra/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 FoxPro-format files. 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. 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.

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 Access. You'd first define the structure of the database according to the needs of your multimedia presentation.

FoxPro 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.

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 use directly within FileFlex as a database file with memo information, which actually results in 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.FPT" (which contains all the memo fields used in the database). These files are then used by the FileFlex externals within Director.

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.

If the database opened by DBUse contains memo fields, its matching .FPT 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:

When your Director project quits, you'll want to be sure to use DBClose and DBCloseSession 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

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 a few hundred Kbytes, 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 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

You can embed database capabilities in your movies and be confident those movies will 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:

Path specifications
Path specifications to your database will be different. The Macintosh uses colons (:) to separate folders, while Windows uses backslashes (\) to do the same. If you choose to open a database with a fully-realized path, you'll need to change your code as in the example below:

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

Memo field data
If you're using memo field data that comes from an external database (not entered in Director), you may need to be concerned with line-termination. The Macintosh terminates each line with a newline, and under Windows the convention is that each line is terminated with a carriage return and line feed. FileFlex provides a DBConvertCRLF function that helps manage this inconsistency.

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.

Upgrading from Earlier FileFlex Releases

If you're upgrading from an earlier FileFlex release, there is a considerable amount you need to 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:

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("A") 
-- "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("A") 
-- "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.


Discuss this chapter on the FileFlex Boards.


Copyright © 1992-1998 by David Gewirtz, under license to Component Enterprises, Inc.
Contact: info@component-net.com

Casa de Bender