CGI scripts and xBase

Site hosted by Angelfire.com: Build your free website today!

CGI scripts and xBase

First we need to understand what a Database is and how they work.
A Database is a collection of organized data. If you created a file with organized entrees.
You could consider it a Database. Hear is an example.

Rogers
Joe
83

Johns
mick
14

Al-through most people think of a Database in a larger since.

A way to enter the data. Spreadsheet, HTML forms, and Forms.

A way to retrieve the data.

A way to search the data.

Automatic backups of the Database file.

And if using in a Multiuser Environments. -- File locking.
This is called a database system.
A Database is a collection of organized data "The file".
How you put the data in or retrieve it is up to you.

We are going to use xBase 3 as an example. To write a simple database.
That uses HTML form to enter the data.

*So what is xBase?
It is a database format derived from dBase ®.
*So why use xBase with CGI scripts?
Because databases are fast, efficient, and proven.
We are going to write a raw database system.
Called a Flat-file database.
*So what is a Flat-file database?
A flat-file database is a database stored in a single file that follow a uniform format.
And are not structured for indexing or "recognizing relationships between records" (Relational database).

*Purpose -- Is not to show you how to manage a database (Database administrator).
It is to show you how they work, and how to write your own.
Using CGI scripts and HTML forms with them.

Order of study:
1) What a Database is and how they work.
2) Database terms.
3) Basic xBase 3 file structure.
4) Database system structure: Read and write.
5) Create an empty mollified Xbase 3 file.
6) Compile and test it.

Part 2: Howto Create a HTML form and read CGI script.
1) Install Apache 2 link.
2) Setup Apache 2 to execute CGI scripts.
3) Test Apache 2 setup.
4) Wright a CGI script to Receive, transcribe, And display the form's input.
5) POST and GET: What the difference.

Part 3: Howto add data to the Xbase 3 file.
1)

Fist you need to know a few terms:

Field is a column.
Record is a roll.
Both together is a Table.
Where the roll intersects a column is a value.
All xBase file are binary files. Including the memo file.

xBase file like all files start with a header. xBase header has two parts.
The part that describes the xBase file. And the part that describes the columns.

The file header part (DB_HEADER):

xBase version.
Whether there is a memo fields.
Year, Month, and Day last modified.
Number of records.
Offset to first record.
Each record length.
And a reserved fields.

This is a xBase 3 file header description.

Byte	Contents	Description
0	1 byte	Valid dBASE III PLUS table file (03h without a memo 83h with a memo).
1-3	3 bytes	Date of last update; in YYMMDD format. Like 210415 == April, 15, 2021
4-7	4 bytes	Number of records in the table. (Rows in table) also used as a ID.
8-9	2 bytes	Number of bytes in the header. (32 bytes + column * 32 + terminator 1) data start.
10-11	2 bytes	Number of bytes in the record.
12-31	20 bytes	Reserved

Side note: Having reserved bytes in a header was a common practise.
It allowed for future expansion.

This is xBase version 3. From ver 3 to 4 is similar.
Each newer version add something to header;
By version 7. The file and column headers had more then double.
This structure (struct) is used to describe the xBase file.
Version 3++ (03h without a memo, 83h with a memo). .dbt memo file.

#pragma pack(1)

typedef struct {
  unsigned int   Ver;             
  unsigned int   Year_m;           //Year last modified. 
  unsigned int   Month_m;          //Month last modified.
  unsigned int   Day_m;            //Day last modified.
  long int       Number_records;   //Number of records. And used as a ID number.
  ///File header (32bytes) + (32bytes * Number of columns) + (1byte 0Dh field terminator.)
  short int      R_offset;         //Offset to first record.
  short int      R_length;         //Each record length.
  unsigned int   Reserved[20];     //Do not use.
} DB_HEADER;

The secound decribes the column or field (32bytes) each.
char column_name[11] //Name of the column, upto 10 charters. In ver 3 and 4.
So if you have 3 columns. You have 3 DB_COLUMN structs.

typedef struct {
  char           column_name[11]  //Name of the column, upto 10 charters and terminator '\0'.
  char           char_type;       //The type of data in the column. N,C,L,M,D,F, OR P.
  long           res_field;       //Not used by most databases. 
  //The column length + 1 (delete byte) is the R_length. in the DB_HEADER.       
  unsigned char  Col_length;      //Column length. Not including the delete byte. 
  //The format of the number in the column. 0 = integer, if > 0 = floating point.
  unsigned char  decimalPlace;    
  char           Reserved[14];    //Do not use.
} DB_COLUMN;

In 1984 dBase 3 was grate. Provably the first really usable databases.
Remember that in 1984.
Computer's memory, hard drive space and processor power was limited.
The DOS operating system had a 640K limit. That way you packed to 1 byte boundary.
But not new. We going to use xBase 3 as a reference. Not as a template.

This is the file header.

This is a column template.

Col_type is defined with 1 character. N, C, L, M, D, F, AND P.
Number, character, logical, memo, date, float, or picture.
After the column headers. There a Field (column) Descriptor terminator (0x0D).
The record data starts directly after the field descriptor terminator.

*Then the data starts. Records.
Before each record is a delete byte. Witch is not part of the record.
A space ' ' not deleted,and an asterisk '*' if the record is deleted.
We are not going to use. The Pre-compiler detective #pragma pack(1).
Most compiler's CPU, today, pad there structs to division of 4. It is more efficient.
Because of the way modern CPU are structured.

This is xBase 3 file structure

New we are going to switch gears. And talk about CGI scripts.

Lets write a CGI script.

What does the CGI script need to do?

To write.

Check to see if the write file is open. Being used by an other user.
If so. Loop tell it is not open or it times out.

After you open the write file.
Add the lock marker.
Add new data to end of file (append) and close it.
At intervals, make a backup of the file.

Remove the lock marker.
Send a successful message. or Send a unsuccessful message.

To read.

Check to see if the read file is open. May ot be needed!!!
If so. Loop tell it is not open or it times out.

After you open the read file.
Add the lock marker.
Read it (read only) and close it.

Remove the lock marker.
Send a copy successful message. or Send a copy unsuccessful message.

This is the main.h file. We use the main.h for all the c++ files.
main.h

/*
Put all your structs in main.h
So you can use them as a globles.
*/
#ifndef MAIN_H_INCLUDED
#define MAIN_H_INCLUDED

#include <iostream>
#include <string.h>    ///strncpy().
#include <ctime>       ///Date functions.
#include <cstdio>
#include <fstream>     ///File functions
using namespace std;

char DELETE_RECORD =   '*';
char USABLE_RECORD =   ' ';
///Number of columns. One record element for each column.
#define NumberOfColumns   5
///ADDRESS Struct is 124 bytes.///
/// Of witch 38 is used by the columns. And 86 by the records.
#define RecordLength      86
///End of columns, (char)'0x0D';
#define EOC            (char)'0x0D'

/// /////////////// Structs ///////////////////////////////
///This is the file header.///
///03 without a memo, 83 with a memo
typedef struct {
  short int     Ver = 03;             ///Uses 2 bytes. Ranges is -32768 to 32767.
  short int     Year_m;               ///Year last modified.                                 **
  short int     Month_m;              ///Month last modified.                                **
  short int     Day_m;                ///Day last modified.                                  **
  unsigned int  umber_records = 0;    ///Number of records. And used as a ID number.         **
  ///File header (32bytes) + (32bytes * Number of columns) + (1byte 0Dh field terminator.)
  long int      R_offset = 0;         ///Offset to first record.  long.
  short int     R_length = 86;        ///Each record (Roll) length.
  unsigned int  Reserved[20];         ///Do not use.
} DB_HEADER;   ///Sapost to be 32 bytes. But it is 98 bytes.
///umber_records * R_length
///This is a column templet. ///
///
typedef struct {
  char           column_name[32];  ///Name of the column, upto 31 charters and terminator '\0'. **
  char           char_type;        ///The type of data in the column. N,C,L,M,D,F, OR P.        **
  long           res_field = 0;    ///Not used by most databases.
  ///The column length + 1 (delete byte) is the R_length. in the DB_HEADER.
  short          Col_length = 32;  ///Column length. 32 is biggest column length.                **
  ///The format of the number in the column. 0 = integer, if > 0 = floating point.
  ///  example: 2 would mean 2 places after the number. 1.67. Like $1.67.
  ///     0 would mean 0 places after the number. Or an integer. 34
  short          decimalPlace = 0; ///Integer. Can be overwrote.                            ** sometimes.
  char           Reserved[14];     ///Do not use.
} DB_COLUMN;   ///Sapost to be 32 bytes. But it is 53 bytes.
/// ////////////////// USER FUNCTIONS /////////////////////
///Store formated time info.
typedef struct {
   short int year;    ///2 bytes, not 4.
   short int month;
   short int day;
}TIMEINFO;
/// /////////////////////////
///
///The first char of the data string.
///  But not part of the record.
char Del=' ';
typedef struct {
   char ID[6];
   char LName[32];
   char FName[32];
   char Age[3];
   char Phone[13];
}ADDRESS;
/// /////////////////////////

/// ///////////////////// HTML ////////////////////////////
///HTML header. Start of a HTML file.
void HHeader() {
   ///You need this line. To tell the web browser whot to do.
   printf("%s%c%c\n","Content-Type:text/html;charset=iso-8859-1",13,10);
   printf("<html>\n");
   printf("<head><title>CGI Output</title></head>\n");
   printf("<body>\n");
}
/// /////////////////////////
///HTML foot. End of a HTML file.
void HFoot() {
   printf("\n</body>\n");
   printf("</html>\n");
}
/// /////////////////////////
///ERRORs
bool CGI_Error(char *error,char *str) {
   printf("%s%c%c\n","Content-Type:text/html;charset=iso-8859-1",13,10);
   printf("<html>\n");
   printf("<head><title>CGI Output</title></head>\n");
   printf("<body>\n");
   printf("<H3>CGI ERROR!</CENTER></H3>");
   printf("<br>ERROR = %s, in %s",error,str);
   printf("</body>\n");
   printf("</html>\n");
return false;
}
/// /////////////////////////
///Print the table header.
void TableHeader() {

printf("<center>");
   printf("<p><h3>Address Book</h3></P>");
   printf("<table border = \"2\">\n");
   printf("<tr>\n");
   printf("<th> ID </th> <th> Last Name </th>");
   printf("<th> First Name </th> <th> Age </th> <th> Phone Number </th>\n");
   printf("</tr>");
}
/// /////////////////////////
///Print Table foot.
void TableFoot() {

printf("\n</table>\n");
   printf("</center>");
}
/// /////////////////////////
/* Add to index.html file.
<CENTER>
<form action="http://localhost/cgi-bin/WriteHtmlOutput.cgi" method="post">
<br><input type="submit" value="WriteHtmlOutpu">
</CENTER>

#endif // MAIN_H_INCLUDED

To append to a database file. We need a database file.
This file create an empty database. File without records.
main.cpp

/*
Gary Russell (ISSW)
ghrussell@yahoo.com
https://russellman128.angelfire.com/
Date:
Create an empty database file. Without records.
*/

#include "main.h"

/// GLOBLES ///
///Are in the main.cpp becouse. The struct must be defined before there uses.
TIMEINFO tin;                       ///struct for time object.
DB_HEADER fileheader;               ///File header object.
DB_COLUMN scolumn[NumberOfColumns]; ///Array of structs objects.

///std::size_t strftime( char* str, std::size_t count, const char* format, const std::tm* time );
void get_time() {
///get current time. Sence 1970.
time_t ttime = time(0);
///Get localtime from ttime. Using the struct tm.
///Struct containing a calendar date and time broken down into its components.
tm *local_time = localtime(&ttime);

///Full the tinfo struct.///
   ///Note add 1900 to get the year in YYYY.
   /// Then subtract 2000. To get the year in YY.
   tin.year = (1900 + local_time->tm_year) - 2000;
   ///tm_mon start with 0 = Jan. We wont 1 = Jan.
   tin.month = 1 + local_time->tm_mon;
   ///tm_mday rains is 1 - 31. No 0 day.
   tin.day = local_time->tm_mday;

///DEBUG///
   //printf("\nDate %d %d %d\n",tin.month,tin.day,tin.year);
}
/// /////////////////////////

/// ///////////////// MAIN ////////////////////////////////
int main(int argc, char *argv[]) {
   ///Database filename.
   char *filename = (char *)"MyData.dbf";

///Get time in YY/MM/DD format.
   get_time();
   ///Changes to the file header struct.///
   ///Put the, last modified date into the header struct.
   fileheader.Year_m  = tin.year;
   fileheader.Month_m = tin.month;
   fileheader.Day_m   = tin.day;
   ///Offset to first record.
   fileheader.R_offset = sizeof(DB_HEADER) + (sizeof(DB_COLUMN)*NumberOfColumns) + 1;
   ///Record length is the sum of all the entrees + columns terminator.
   /// 6+32+32+3+13 = 85 + Column Terminator (1). = 86.
   fileheader.R_length = RecordLength;

/*strncpy(char *destination, const char *source, size_t max number);
     If the source string is longer the the max number. No null-character is appended.
     If the source string is not longer the the max number - 1. A null-character is appended.
     We use strncpy() becouse. we don't wont to overload the struct element.
   */

///Changes made to the 5 column structs objects.///
   ///Changes made to the first column struct.
   strncpy(scolumn[0].column_name,"ID",6);
   scolumn[0].char_type = 'I';  ///It is integer.
   ///So when we draw the columns length.
   scolumn[0].Col_length = 6; ///Length of the column.

strncpy(scolumn[1].column_name,"Last Name",32);
   scolumn[1].char_type = 'C';  ///It is charters.
   ///So when we draw the columns length.
   scolumn[1].Col_length = 32; ///Length of the column.

strncpy(scolumn[2].column_name,"First Name",32);
   scolumn[2].char_type = 'C';  ///It is charters.
   scolumn[2].Col_length = 32;

strncpy(scolumn[3].column_name,"Age",4);
   scolumn[3].char_type = 'I';  ///It is integer.
   scolumn[3].Col_length = 4;
   ///If char_type = 'F'; then. scolumn[1].decimalPlace = '1';

strncpy(scolumn[4].column_name,"Phone Number",13);
   scolumn[4].char_type = 'C';  ///It is charters.
   scolumn[4].Col_length = 13;

/*///DEBUG structs. See whot in the file input file header struct.///
   ///File header. Before copy struct into file.
   cout << "\nIn the Main fileheader\nVerstion = " << fileheader.Ver << endl;
   printf("Date last modifided %d %d %d",tin.month,tin.day,tin.year);
   printf("\nNumber of records = %ld",fileheader.umber_records);
   printf("\nOffset = %ld",fileheader.R_offset);
   printf("\nRecord length = %d",fileheader.R_length);
   ///DEBUG/// Column headers. 4
   cout << endl;
   for(int x=0;x<NumberOfColumns;x++) {
      printf("\nColumn %d Name = %s",x+1,scolumn[x].column_name);
      printf("\nColumn %d type = %c",x+1,scolumn[x].char_type);
      printf("\nColumn %d lenhth = %d",x+1,scolumn[x].Col_length);
      printf("\nColumn %d decimalPlace = %d",x+1,scolumn[x].decimalPlace);
   }
   */

///ofstream is write only.
   ofstream Datafile;
   ///Database files are binary.
   Datafile.open(filename,ios::binary);
   ///Write the file header to the file.
   Datafile.write((char *)&fileheader,sizeof(fileheader));
   ///Write the column header to the file. All of them.
   Datafile.write((char *)&scolumn,sizeof(scolumn));
   ///Write the Descriptor terminator to the end of the file.
   Datafile << EOC;  ///If not cast. Well be 4 bytes.
   ///Close file.
   Datafile.close();

///DEBUG.///
   ///See what is in the struct copy from the database file.
   ifstream Datafile2;
   Datafile2.open(filename,ios::binary);
   Datafile2.read((char *)&fileheader,sizeof(fileheader));
   Datafile2.close();

///DEBUG/////////////////////////////////////////////
   /*cout << "\nIn the Main fileheader2\nVerstion = " << fileheader.Ver << endl;
   printf("Date last modifided %d %d %d",tin.month,tin.day,tin.year);
   printf("\nNumber of records = %d",fileheader.umber_records);
   printf("\nOffset = %ld",fileheader.R_offset);
   printf("\nRecord length = %d",fileheader.R_length);
   cout << endl;
   */
   /*
   for(int x=0;x<NumberOfColumns;x++) {
      printf("\nColumn %d Name = %s",  x+1,scolumn[x].column_name);
      printf("\nColumn %d type = %c",  x+1,scolumn[x].char_type);
      printf("\nColumn %d length = %d",x+1,scolumn[x].Col_length);
      printf("\nColumn %d decimalPlace = %d",x+1,scolumn[x].decimalPlace);
      printf("\n");
   }
   */
   /// End DEBUG //////

return 0;
}

Coding

In codeblocks. Create a console project called CreateDbFile.
In codeblocks File > New > File... > choose C/C++ header > Go button.
In the C/C++ header window.
Click the small square box next to "Filename with full path:".
In the Select Filename window > File name: type main.h and save.
New your back to the C/C++ header window.
Under the Debug / Release box choose the All button.
Finish button.

In the main.h code box above.
Right-click in the box and selects "Select All" and copy.
In codeblocks Editor window, click on the main.h tab selected.
Overwrite the main.h code. By pasting the code from the main.h code box above.
Click the save button.

New "Build and run" button.
A console window will pop-up with Hello world! in it. Good.

In the main.cpp code box above.
Right-click in the box and selects "Select All" and copy.
In codeblocks Editor window, click on the main.cpp tab selected.
Overwrite the main.cpp code. By pasting the code from the main.cpp code box above.
Click the save button.

New "Build and run" button.
There will be a file called MyData.dbf.
This is your empty database file.

If you wont to check you MyData.dbf file. And do not have DBase file viewer.
You can download a free one at Windows Dbf Table Manager Download.
And Codeblocks at Windows CODEBLOCKS IDE Download.
Windows Apache 2 web server.
Choose either 32Bit or 64Bit. DO NOT FORGET to download the runtime too (vc_redist_x64/86.exe).
Do not download any modules.
LINUX -- Use the Software manager that comes with your distribution (distro) to install Apache 2 web server.
Howto compile Console apps.

Part 2 Create a HTML form and read CGI script.
Howto Create a HTML form and read CGI script.