sanbachs.NET Serving the DataPerfect* Community

Firestorm – Usage Guide

This usage guide documents the way in which Firestorm has been used over the last four years. Many of the instructions are based on conventions and are open to change as more experience is gained, and better ways are found to do things. Please don't hesitate to suggest improvements.

There are three directory structures that you will need to set up.

1. METAD and generation of PBA.C files (on a machine that can run DataPerfect)
2. Firestorm and CGI scripts (on a machine that can generate executables that will run on your web server)
3. Web server HTML documents and CGI executables

There are three kinds of work that you will need to do in order to create a web application based on your DataPerfect database. Using METAD, which is itself a DataPerfect database (somewhat like the STE Manager, though not nearly as complete), you will create the PBA.C file that describes your database. This file contains a small part of the information from your DataPerfect structure file, in a format suitable for the programmatic interface. We suggest that you place the METAD database, and the accompanying METADXP.COM program in a directory named "metad". The METAD database will produce its output in a subdirectory whose name is (by default) the first five characters of your database name.

The second kind of work you will do is to compile the ANSI C source code for the Firestorm database engine. We suggest that you do this work in a directory named "fs". Again, the CGI scripts that you will write for a particular one of your databases will be placed in a subdirectory whose name is the first five characters of your database name (or a five character abbreviation of your choice).

Once you have created and compiled the PBA.C file, and have compiled the Firestorm source code, and have compiled and linked these with your own CGI scripts, you will need to copy the executable files into a directory that can be used by your web server. So, the third kind of work you have to do is to set up a web server, and configure it to run CGI scripts. All of the database files (except the .STR file) will also need to be copied (or reside permanently) in the directory from which the CGI scripts are to be run.

1. METAD and generation of PBA.C files

Unzip md001126.zip in a directory named METAD. Create the METAD database using DPIMP.COM. If you followed the instructions in the installation guide you will have already performed these steps.

For each database you wish to use on the Internet, you will need to follow the same steps. These are given below (using METAD itself as an example).

1. Choose an abbreviation for the database name that is no more than five characters in length (METAD)
2. Make a subdirectory of that name (mkdir metad)
3. Change directories to the new subdirectory (cd metad)
4. Copy the database structure file from wherever you customarily work on it to the new subdirectory (copy ..\metad.str .)
5. Run the program METADXP.COM (..\metadxp) and press Enter when prompted for the database structure file. This will create a file with a ".{X}" extension (METAD.{X})
6. Return to the parent directory (cd ..)
7. Run DataPerfect on the METAD database (dp metad), at which time you will see the METAD menu
8. Type option number 98 and press Enter to see the METAD panel list
9. Press Enter to select the "Database Description" panel
10. Press Shift-F9, select option "8 - Import Transaction Log", and Enter the filename (METAD\METAD.{X}). When the import is finished, press any key and you will see the results of importing the file METAD\METAD.{X} (which was created in step 5)
11. Press F6 to edit, type a 1 (one) to change the database to be number one, and Tab twice to the Filename field and ensure that the first five characters of this name match the subdirectory name created in step 2. Then press F10 to save the record. There will be a short pause while the cascade update feature changes the database number in all of the records. Then you will see the renumbered record in the Database Description panel
12. Now press Shift-F7 to see the report list
13. Press the down-arrow once to select the report named "Assign index base blocks" and press Enter. Then press F7 twice to return to the record, and press Alt-F7 to run the report for this record. Press any key when the report is finished
14. Press Shift-F7, then down-arrow to select the report named "Count fields and indexes" and press Enter. Then press F7 twice to return to the record, and press Alt-F7 to run the report for this record. Press any key when the report is finished
15. At this point, you will see the Database Description record with the correct number of fields per panel shown in the right hand column
16. Press Shift-F7, then down-arrow to select the report named "Generate PBA.C" and press Enter. Then press F7 twice to return to the record, and press Alt-F7 to run the report for this record. Press any key when the report is finished. This will create the PBA.C file for the database (metad\PBA.C). If you see an error screen it is probably because you didn't create a directory name that the report expects (METAD) in step 2 or didn't edit the Filename field (step 11) in the Database Description record so that its first five characters match the subdirectory name

Repeat steps 1-16 for each database you want to use with Firestorm, replacing "metad" and "METAD" with your five character abbreviation in steps 1, 2, 3, 4, 10, and 16. Step 11 will need to be changed to give each database its own number, one for the first, two for the second, and so forth. If you get to database number 22, you will need to have that one be number 23, as METADXP.COM always produces number 22, and you need to leave that number free for the import.

Whenever you change one of your databases, by adding or removing fields or indexes, you will need to repeat steps 3-16 to generate a new PBA.C file that describes it correctly. You may delete its record in the Database Description panel and reuse the same number, or give the new version a new number, as you wish.

The directory structure for this first kind of work will look something like the following diagram. This assumes that you have followed steps 1-16 for the metad.str database itself, for one of your databases named "phone.str", and for one of your databases named "contacts.str" for which you have chosen the abbreviation "cntct".

  |
  +-metad
  |   |
  |   +-metad.str (etc.)
  |   +-METADXP.COM
  |   +-metad
  |   |   |
  |   |   +-metad.str
  |   |   +-METAD.{X}
  |   |   +-PBA.C
  |   +-phone
  |   |   |
  |   |   +-phone.str
  |   |   +-PHONE.{X}
  |   |   +-PBA.C
  |   +-cntct
  |       |
  |       +-contacts.str
  |       +-CONTACTS.{X}
  |       +-PBA.C
  |

2. Firestorm and CGI scripts

If you have followed the installation guide you will have set up a directory named "fs", unzipped one of the Firestorm source code archives, and compiled the code.

This directory should contain the files from the following list. If you are compiling on a Windows machine, the object files will have a ".OBJ" extension, rather than the ".o" extension used in UNIX-like systems. The various files are given in order from the lowest, most central, or foundational layer first.

dot.c

The foundation of all, this is the Forth engine. It is accompanied by dot.h, forth.h, and ftable.h, which together describe certain aspects of the Forth engine. Another definition file, machine.h, describes certain data types used throughout.

engine.c

The C program that interprets the Forth engine. It is accompanied by engine.h, which describes it for the next level. This program includes symbols.c, which contains information useful when debugging is needed at the engine level (neither frequently nor recently).

dpif.c

The lowest level of the programmatic interface. Its entry points are described by dpif.h. All current and future uses of the engine are and will be built on top of this level.

dp.c

This implements the command line interface, using the lower level parts. It also needs to be linked with the compiled version of map.c, which maps between the DOS character set and the ISO Latin1 character set used on the web. A PBA.C file must be linked with this program. The structures used are defined in the the definitional file pba.h.

fsCore.c

This implements the programmatic interface. Either dp.c or fsCore.c can be used with the underlying levels, but not both at the same time. A PBA.C file must be linked with this program. The definitional file fs.h describes the data types and function calls that together make up the programmatic interface.

fsMain.c

This provides a main program for CGI scripts. It accepts input values from a URL or from a form and makes them available to your CGI program, which must be named "FSquery". See the programmatic interface demonstration (part five) for more information, and a working example.

All of the programs described above, together with their .o (or .OBJ) compiled versions, will reside in the fs directory. Make a subdirectory of fs, named with your five character abbreviation, for each of your databases. Copy into each of these the corresponding PBA.C program, which was generated by the METAD report. Compile this program to produce PBA.O (or PBA.OBJ).

With all of this done, you are ready to begin making executable programs for your database. To make a command line program for your database, link together pba.o ../dp.o ../map.o ../dpif.o ../engine.o and ../dot.o to form the executable program named fs-xxxxx, where "xxxxx" is replaced with your five character abbreviation. The command to do this on UNIX-like machines is:

  gcc -o fs-xxxxx pba.o ../dp.o ../map.o ../dpif.o ../engine.o ../dot.o

We recommend that you create a subdirectory (of the database-specific directory) named "Data". Copy into this directory all of the panel data files, the index file, and the .TXX file for your database. One important note here is that the index base blocks must be assigned the same way in the PBA.C file and your database. The simplest way to ensure this is to delete the .IND index file, run DataPerfect (answering "1 - Create a New Index File with New Indexes for All Data Files." when prompted) on your database. Then, go into one of its panels (doesn't matter which one), and answer "3 - Re-create the Indexes for All Files." when prompted. This will create a new index file with all of the index blocks allocated in the same way the PBA.C assumes.

Now change into the Data subdirectory and try out the command line interface for your database.

Now, working in the database-specific subdirectory of fs, you can begin to create your CGI scripts. Let's say, for example, that you are working with a contacts database, for which you have chosen the abbreviation "cntct" and that you are working on a CGI script named "cntct-enter.c" to accept the data from an HTML form and add a new contact to the database. Your directory structure will look something like this:

  |
  +-fs
  |  |
  |  +-dot.c, dot.o, engine.c, etc.
  |  +-cntct
  |  |   |
  |  |   +-pba.c, pba.o
  |  |   +-fs-cntct
  |  |   +-Data
  |  |   |   |
  |  |   |   +-contacts.txx
  |  |   |   +-contacts.ind
  |  |   |   +-contacts.dat, etc.
  |  |   |
  |  |   +-cntct-enter.c
  |  |   +-cntct-enter.o
  |  |   +-cntct-enter.cgi
  |  |
  |  +-phone
  |      |
  |      +-pba.c, pba.o
  |      +-fs-phone
  |      +-Data
  |          |
  |          +-phone.txx, phone.ind, etc.

The command to compile cntct-enter.c and create cntct-enter.o is, on UNIX-like systems:

   gcc -c cntct-enter.c

The command to create the executable file, cntct-enter.cgi, is:

   gcc -o cntct-enter.cgi cntct-enter.o pba.o \
      ../fsMain.o ../fsCore.o ../dpif.o ../engine.o ../dot.o

Once the executable CGI script has been created, you can test it from the command line. For example, assuming a very simple contact structure, consisting of Name, Title, and Phone, you might test it like this:

  cd Data
  ../cntct-enter.cgi Name=Bob "Title=Mangaging Director" Phone=555-4073

To add the same record using the command line interface would be done this way:

  cd Data
  ../fs-cntct p1 a Bob "Managing Director" 555-4073 q

At this point, you are now able to create Firestorm programs to access your database on a UNIX-like system. You have a command line interface and the ability to write an unlimited number of custom access programs and executable CGI scripts. The next step is to get these CGI scripts running in conjuction with your web server, so that you have Internet (or intranet) access to your database.

3. Web server HTML documents and CGI executables

Contacting sanbachs.NET

Sign or browse our guest book.

Disclaimer