sanbachs.NET Serving the DataPerfect* Community

Firestorm – Programmatic Interface

The Firestorm programmatic interface provides a few ANSI C type definitions and a handful of ANSI C functions to access the data files of a DataPerfect database from a C program that you would write. After writing and compiling your program, you would link it with the executable engine and the PBA (panel byte array) that describes your database. Then your program is ready to run.

We advise you to look through the demonstration before reading the specifications of the programmatic interface, particularly if you are new to programming.

Demonstration

In the demonstration, we will show how to take a simple DataPerfect database and create a web application based on it. When complete, the demonstration will consist of:

1. a simple program to print all the records
2. a program to generate an HTML page showing all the records
3. a CGI script to generate an HTML page showing all the records
4. a CGI script to add one to a field of a particular record, creating it if necessary
5. a CGI script to generate an HTML page showing a subset of the records

Specification

[ This part is not yet finished. Please check back from time to time. Thank you for your interest and patience! ]

To use the programmatic interface to write CGI scripts, you will need to follow the instructions in the usage guide to create a PBA.C file describing your database. You will also need to link together the compiled Firestorm files dot.o, engine.o, dpif.o, fsCore.o, fsMain.o together with your compiled pba.o file and an ANSI C function you write to implement the FSquery function. See the demo5.c program from the demonstration for a complete example.

Field values

Each field value from a record of a DataPerfect panel is represented by a variable of type Field_Value* (read "field value pointer"). You can declare such a value in C using a declaration of the form:

  Field_Value *P1F2;

Once you have found a record in a panel, you can assign a field value to this variable (these steps will be explained below). With a field value assigned to P1F2, you can then get access to certain aspects of the field value.

  P1F2->field_number   // the field number (a C int)
  P1F2->field_type     // the field type (a C char)
  P1F2->field_length   // the number of characters in the field value (a C int)
  P1F2->field_data     // the actual field value string (a C char*)

Of these the last is by far the most frequently used in Firestorm CGI scripts.

Besides field values which come from data records in panels, there is also the C equivalent of "report variables" which are also represented as variables of type Field_Value*. In particular, the values that you expect to get as inputs to your CGI scripts are declared in this way:

  Field_Value *Name;
  Field_Value *Address;

  FS_CGI_arg FSexpect[] = {
    { "Name", &Name, NULL},
    { "Address", &Address, NULL},
    NULL
  };

These declarations are of the same form as declarations of real field values. The appearance of such a variable in the FSexpect[] array signals to the fsMain program that you "expect" these variables to be filled with values coming in to your CGI script from the HTML page that links to the script.

Identifying a panel

You will need a variable in your program for each panel that you plan to use. Each of these will be declared as:

  FS_panel p1;

Before you can use the FS_panel variable, you will need to initialize it. This is done by calling the FSsetPanel function:

  p1 = FSsetPanel(1);

It is only by convention that panel variables are named "p" followed by a number. You may name them anything you like. Similarly, field variables need not be named "P" panel number "F" field number. Again, you are free to name them anything you like. They are simply C variable names.

Positioning to a record

Once you have a panel variable, there are several ways to position to a record. In all of them you must specify an index, by number. In some of them you also must specify values for some or all of the key fields in the index. This is done by calling the function FSifList (read Firestorm index and field list). A sample call of this function is shown here:

  FSifList(p1,3,Name,NULL)

The arguments to this function call are, in order, the panel, the index number, a field value for each of the key fields. In the example, the C constant NULL is used to indicate a premature end to the field list. In other words, we have specified a subset.

Examples of functions that position to a record are:

  err = FSfirstRec(p1,2);                                // 1
  err = FSlastRec(p1,3);                                 // 2
  err = FSequalRec(p1,FSifList(p1,1,Name,Address));      // 3
  err = FSsubFirstRec(p2,FSifList(p2,4,P1F3,NULL));      // 4
  err = FSsubLastRec(p2,FSifList(p2,4,P1F3,Name,NULL));  // 5
  err = FSnextRec(p1);                                   // 6
  err = FSprevRec(p1);                                   // 7
  err = FSsubNextRec(p2);                                // 8
  err = FSsubPrevRec(p2);                                // 9

These examples have the following purposes:

1. position to the first record in panel 1 using index 2
2. position to the last record in panel 1 using index 3
3. position to the record in panel 1 whose key field values for index 1 are held in the variables Name and Address (in that order)
4. position to the first record in panel 2 that matches the field value in the variable P1F3, using index 4
5. position to the last record in panel 2 that matches the field values P1F3 and Name (in that order), using index 4
6. position to the next record in panel 1, using the current index
7. position to the previous record in panel 1, using the current index
8. position to the next record in the current subset of panel 2, using the current index
9. position to the previous record in the current subset of panel 2, using the current index

Getting field values from a record

Once you have positioned to a record, you may get the field values from the record using the FSfield function. This function returns a Field_Value* data type. For example,

  FSfield(p2,3)

is the field value for panel 2, field 3, of the current record. And

  FSfield(p2,3)->field_data

is the actual character string containing that field's value.

If you have declared a variable

  Field_Value *P1F2;

  P1F2 = FSfield(p1,2);

Creating a new field value

[ From this point on, there is only an outline. Please check back again. Thank you for your interest and patience. ]

  FStoday();
  FSnow();
  NewField(field_type, field_number, field_length, field_data);

Updating a single field in an existing record

  FSupdateField(panel, ifList, field_number, update_type, field_value);
    /* update_type */
    /* ':' - simple replacement */
    /* '+' - add the field value into field_number */
    /* '-' - subtract the field value into field_number */
    /* Note: these last two are a little like DP's keep-a-total */

Creating a record

  FScreateRec(panel, fList);
    /* fList is a "field list" created by calling FSfList */

Deleting a record

There is (as of yet) no function in the programmatic interface for doing this. For now, we can use one of the lower-level functions (from dpif.c).

  dpe_DeleteRec(panel->pba, ifList);

Updating a record

There is (as of yet) no function in the programmatic interface for doing this. For now, we can use one of the lower-level functions (from dpif.c).

  dpe_UpdateRec(panel->pba, fList, old_fList);
    /* fList is a "field list" created by calling FSfList */
    /* old_fList is a "field list" of the old field values */

Contacting sanbachs.NET

Sign or browse our guest book.

Disclaimer