FlashDB v1.5

What is FlashDB?

FlashDB is a small database for Flash 4/5 written in Perl. It is very easy to use, and is very basic. There are just two actions: read and write. With “write” you can write a set of Flash variables to the webserver. With “read” you can read them all back into Flash. Simple yet powerful and flexible, that’s how I like things.

  • Freeware database for Flash 4 and Flash 5
  • Very easy to use
  • Written in Perl
  • Unix and Windows 98/NT/2000
  • Unlimited database size

FlashDB uses the “Load variables” action that was introduced in Flash 4. The database will therefore not work with Flash 3 or older. The “Load variables” action will write all currently active variables in one big lump to the server, or read them all back into Flash. You don’t have to specify which variables you want to write or read, and you don’t have to specify their format, type, size, recordname, database userid/password, or other things that can make other databases such a pain to use. FlashDB has no limit to the number of records (a set of Flash variables) you can store, other than the size of your harddisk. A record can hold up to 131072 bytes, imposed by the POST method of browsers. If you are planning a large database (more than 25.000 records, more than 1Kb per record) or heavy use (more than 5000 actions per day) then you should probably look around for something else. FlashDB can handle it allright, but commercial databases will be faster.

 

Examples

Visitor Counter

The visitor counter is a perfect example of how to use FlashDB. It’s very small and easy to understand, and still is a useful and practical application. You can use this counter as a stand-alone counter, or incorporate it into your Flash movie.The counter shows all the techniques needed: how to read data from the server into Flash (in this case a number), change that data (increment by 1), write the data back to the server, and present the data to the user. It may sound like a lot, but it’s all done in a single movieclip with about 10 actions!

The “counter.fla” source of this example is included in the download (see below). Take a look at the actions of the Counter movieclip. Specifically look at the “state” variable, used to wait for a reply from the server.

Here is the same counter again but this time dressed up with graphics and stuff. This version was designed for me by Fabrice at ZuidZijde Reclamebureau. This counter may sometimes show counter+1 if the counter above has finished before this one.

Chat

A slightly more elaborate example is the chat. I have kept it as basic as possible, you can add all kinds of bells and whistles yourself. The button below will open two (2) windows with the chat. Using the chat should be self-explanatory. Try entering some text, see your messages appear in the other window, chat to yourself.

 

 

The “chat.fla” source of this example is included in the download (see below). There are several movieclips, take a look at their actions.

Download and install

FlashDB is written in Perl, a populair programming language often used on the internet. Most webservers have support for Perl, but if your’s doesn’t then your administrator will have to install Perl first. Without Perl you cannot use FlashDB. The current version of Perl is version 5, but FlashDB will probably work with Perl 4 just as well.

Download FlashDB

* Download FlashDB-1.5.tar.gz for Unix and Mac webservers (11Kb)
* Download FlashDB-1.5.zip for Windows 98/NT/2000 webservers (13Kb)

Installing FlashDB

  1. Create a new directory on your webserver where FlashDB can store the data, the database directory. A good name would be “data”, and a good location would be near your html directory. Please make sure the permissions on the directory are so that FlashDB can read and write into it (try 777 on Unix only if you are having problems).
  2. Use a basic text editor to make the following changes in both scripts in the cgi-bin directory (“FlashDBread.pl” and “FlashDBwrite.pl”):
    1. Change the location of Perl. The location of Perl on webservers is usually “/usr/local/bin/perl”. If Perl lives in another directory on your webserver then you must change the first line of the scripts. Other common locations are “/usr/bin/perl” and “/bin/perl”. If your server is running on Windows 98/NT/2000 then this is a don’t-care.
    2. Change the “$Database” setting (both scripts) into the directory which you created in step 1. Please enter the complete directoryname all the way up to the root (sometimes called the “fully qualified path”). Do not use constructions like “..” or “$USER”, and do not enter an URL. See below for more information about fully qualified paths.
  3. Upload both scripts. The scripts should go into your cgi-bin directory, and must be made executable (permissions 755 on Unix). You may have to change the filename-extension from “.pl” into something else, some servers use “.cgi” instead. In some FTP-upload programs you have to manually set the upload-mode to “text” if the default is “bin”.
  4. Test the scripts. Start your browser and enter the URL of the “FlashDBwrite.pl” script (probably “http://www.yourserver.com/cgi-bin/FlashDBwrite.pl”). You should see a page with “filename=221&state;=done” (the number can be anything). If you see “state=cannot_open_file” then FlashDB has no permissions to access the “$Database” directory (see step 1).

Fully qualified paths

A fully qualified path is the complete directoryname all the way up to the root of the harddisk. It is not an URL and never starts with “http://”. When you enter your account (at the webserver, using FTP) you will see your folders such as “/cgi-bin”, “/html”, “/logs”, or whatever. You won’t see the rest of the server, you only have access to your own folders. Here is an example of an account and it’s fully qualified paths:

 

You see The fully qualified path
/cgi-bin /usr/home/www/www.foobar.com/jeroen/cgi-bin
/html /usr/home/www/www.foobar.com/jeroen/html
/www /usr/home/www/www.foobar.com/jeroen/www
/logs /usr/home/www/www.foobar.com/jeroen/logs

A good location for FlashDB’s data directory would be:

 

You see The fully qualified path
/data /usr/home/www/www.foobar.com/jeroen/data

You will have to figure out what the first part of your fully qualified path is. You can ask your provider, or maybe you can find it on their website in the help-pages. Or maybe you can find out with this little * showenv program. It’s a little Perl program, just upload it to your cgi-bin directory and execute it by entering the URL in your browser. Look in the output for something that looks like a fully qualified path.

Installing the visitor counter

  1. Edit the “counter.fla” file with your Flash editor. You can find this file in the distribution, the “html” directory. Open the “counter” symbol. Check the Actions in the properties of frame 2 and frame 5. The URL of the “Load Variables” action must be changed to point to the cgi-bin directory on your webserver.
  2. Create “counter.swf”. Use the Export function of the Flash Editor to create a “counter.swf” file.
  3. Upload “counter.swf” and “counter.html”. Upload the “counter.swf” you just created and the “counter.html” from the FlashDB distribution to your webserver. The location is not important, you can place them in the top of your document tree, or create a special FlashDB directory first.
  4. Test it. Start your browser and enter the URL of the “counter.html” file (probably “http://www.yoururl.com/counter.html“). You should now see “Visitors: 1”. The number should increment every time you hit the reload-button of your browser.

Installing the chat

To get the chat working on your server you should basically do the same as with the visitor counter (see above). I leave this as an excercise to the reader.

Using FlashDB

Tip: Copy the “Counter” movie clip from the “counter.fla” file in the distribution.

Write

Add the following actions to the properties of a frame. This will write the current Flash variables into a particular record of the FlashDB database on the server. The filename variable is the name of the file in which FlashDB will store the information. If you don’t specify a filename or the filename is “default” then FlashDB will generate a unique number as filename (the process-id), making the number available in Flash as, guess what, variable “filename”.

 

Flash Actions (frame properties) Remarks
Set Variable: “filename” = “record1” Select a filename for FlashDB.
Load Variables (“/cgi-bin/FlashDBwrite.pl”,””) Call FlashDBwrite at the server.

 

  • All variables in the current movieclip will be stored on the server. You do not have to select or deselect variables, they will all be stored automatically! The “current” movieclip is the movieclip that contains the FlashDB actions.
  • The filename is the name of the record in which FlashDB will store the variables. You can use characters a..z, A..Z, and 0..9. Use the “filename” to create multiple records. For example if you want to store the settings of a visitor then you would assign every visitor a unique userid and copy the userid into the “filename”.
  • The URL of the Load Variables action is the location where you have installed the FlashDBwrite script on your webserver.
  • You can also select “Send using GET”, but then the amount of data that can be transmitted is very limited. Depending on the user’s browser it is sometimes as low as 512 bytes.

Read

Add the following actions to the properties of a frame. This will read variables from a particular record in the FlashDB database on the server.

 

Frame Flash Actions (frame properties) Remarks
1 Set Variable: “filename” = “record1” Select a filename for FlashDB.
Set Variable: “state” = “busy” Initialize the “state” variable.
Load Variables (“/cgi-bin/FlashDBread.pl”,””) Call FlashDBread at the server.
2 Leave this frame empty, no actions.
3 If (state eq “busy”) Wait for the “state” variable to change.
    Go to and Play(2) Loop. Warning: do NOT use “Go to Previous frame”!
End If
4 The reply from the server has been received and the movie can now continue.

How does it work?

Flash has a special action called “Load Variables” (see the “load/unload movie” action). This action will communicate with the webserver, making it possible to read or write Flash variables. The protocol is very simple, but only sketchily explained in the Flash documentation.

Sending variables to the server

The “Load Variables” action will send a request to the webserver. Maybe a more logical name for the action would have been “Send Variables”, because that’s what it does. Complain to Macromedia, not me. The format of the request is exactly the same as with a form on a webpage. The contents of Flash variables is encoded as if they are fields in a form (you can select GET or POST in Flash). A typical request looks like this:

/cgi-bin/FlashDBwrite.pl?aa=Jeroen&bb;=Kessels

I’m sure you have seen URL’s like this before. In this example variable “aa” with contents “Jeroen” is sent, and variable “bb” with contents “Kessels”. The rest of the URL is determined by the URL parameter of the “Load Variables” action.

Reading variables from the server

Flash uses the same action (“Load Variables”) for reading. In this case the name of the action describes exactly what it does (no complaints here). Flash expects a flat text file as input, with a single line of text in it. The text-line is encoded exactly the same as when sending variables. Here is an example of the contents of such a textfile:

aa=Jeroen&bb;=Kessels

To read variables we can specify the URL of such a textfile as URL in the “Load Variables” action. With the “location” setting you can specify a movieclip into which the variables will be loaded.

Load Variables (“/data/sample.txt”,””)

About FlashDB

All FlashDB has to do is store everything after the question-mark “?” (see above) in a textfile, and dump that textfile back when we want to read the variables. FlashDB adds a “filename” parameter so you can select a textfile, and a “state” variable to wait for the server (see below).

Wait for the server

The “Load Variables” action will not wait for the server to respond. The movie will continue regardless. Depending on the speed of the internet the response may arrive several frames later, probably at a point where you don’t want it anymore. You have to make sure a reply from the server has been received. When you’re reading variables from FlashDB it will always add variable “state=done”. Set “state” to something else (for example “state=busy”), then use “Load Variables” to call FlashDB, and you are sure the variables have been received when the content of “state” becomes “done”.

 

About security

FlashDB is not protected with userids, passwords, and such stuff. The same is true for most other cgi-bin applications out there. Hackers love that. They thrive on it. It’s up to you to protect FlashDB with userids and passwords. Simply put FlashDB in a separate cgi-bin directory and let your webserver protect that directory. FlashDB will only write files in the data directory, nowhere else. It will only accept the following characters in incoming filenames: ‘a-z’, ‘A-Z’, and ‘0-9’. Any other characters are quietly removed, specifically directory-separators ‘/’ and ”, and shell-escapes such as ‘|’.