bozimmerman / cgidb Goto Github PK

CGI-Database

This program is a CGI (Common Gateway Interface) program for use on LINUX and WINDOWS web servers.

It's purpose is to handle one or more flat file database tables, and to display your data on web pages.  It includes a built in HTML interface for modifying your existing tables, and an interface for inserting table data into your own custom web pages.  It requires a rudamentary knowledge of modifying text files in your system, where and how to install new cgi programs in your web server, and some knowledge of how web URLs are constructed, and good command of HTML.  Much of this you can learn as you go along.  The rest can be answered in USENET. :)


Compiling
=========
If you are using a modern linux, it goes something like this:
c++ cgimain.cpp

This will produce an a.out file, which I usually rename to db.exe.


Installing
==========
put the db.exe, db.ini, sample.dat, and sample.tag files into your cgi-bin directory.


Setting Up
==========
First thing to do is define a password.
By default, your db.ini has a blank first line. The first line is the password line.
Open up a browser and enter:
http://mydomain.com/cgi-bin/db.exe?DBPASS=mynewpass
Where mynewpass, enter one you like.  Keep it simple.. the encryption/decryption stuff isn't perfect.
The page that displays will say something like: New password is: p+4('m7e
Now open up the db.ini in your fav text editor and enter the encrypted characters in the first line.

Second thing to do is define your tables.
Still in the db.ini, you'll see three lines after the password.  The first of these is a table identifier, the second is the filename of that tables tags or columns, and the third is the filename of that tables rows or data.
To add new tables, you should first add those three entries for each table you want to define.  All of the files referred to will be in your cgi-bin directory, so you should not enter any path information -- just the filenames.
Now you should open up the tag/column file (for sample database, it was called sample.tag) in your favorite text editor.
The first line of the tag/columns file is the all-uppercase name of the first column in your table, without spaces.  The second line is the maximum number of characters for this column (used for display purposes only).  Repeat this process for every column. Save it.
Now you should open up the rows file (for sample database, it was called sample.dat) in your favorite text editor.  Save it empty.

Using the built in pages
========================
Before you start building custom pages, you should play around with the built in features to get the hang of it.
Now, Examine this URL closely and then try it out in your browser:
http://mydomain.com/cgi-bin/db.exe?REQ=VIEW&DB=sample&T1=THUMBNAIL&T2=DESCRIPTION
This will list both of the columns in the sample database.  The REQ is the command we are requesting of the cgi.  DB will always be the name of our table, which should match one of the table names in the db.ini.  T1 and T2 and any other T's we might want to include for our own tables are the names of table columns to show, in the order that we want them displayed.

Now, Examine this URL closely and try it out:
http://mydomain.com/cgi-bin/db.exe?REQ=EDIT&DB=sample&DBPASS=mynewpass&T1=THUMBNAIL&T2=DESCRIPTION
Where mynewpass be sure to put your UNENCRYPTED password.  This interface will allow you to edit the data in the table, add new rows, and even modify the columns (tags).

In addition to the REQ field you learned about above, as well as the DB field, the DBPASS field, and the T1, T2, ... TN fields you learned about, there are also several other fields you may encounter on other requests.  These include DBKEY, which is always an integer from 0 .. number of rows in your table.  DBKEY denotes which row in a table is being selected for a function.  EDTKEY is identical in meaning to DBKEY.  BACKREQ you may see generated by some of the requests -- it's just to help the db.exe remember what your last REQ was.  INPUTFILE is the important extra field required for the HTML request.  It should be set to the name of an html text file in your cgi-bin directory.


Here is a list of the main commands you can put as values for REQ=, and what they do:
VIEW - requires DB, and T1, T2, ... TN. 
LIST - requires DB, and T1, T2, ... TN.
EDIT - requires DB, DBPASS, and T1, T2, ... TN
DETAILS - requires DB, DBKEY, BACKREQ, and T1, T2, ... TN. 
EDITDETAILS - requires DB, DBPASS, EDTKEY, and T1, T2, ... TN. 
ADDDETAILS - requires DB, DBPASS, and T1, T2, ... TN. 
HTML - requires DB, and INPUTFILE.

Here is the complete list of the main commands. Some are generated by one of the above (VIEW, LIST, or EDIT) and should not be manually requested unless you know what you are doing.  How do you know?  By clicking the proper request from one of the above and then looking up at your address bar to see what tags they generate.  You'll also learn the meaning of others of these in the next section.

CHANGEROW, ADDROW, DELROW, TAGS, DELTAG, MODIFY, SORT, SELECT, IF, PARM, and FIELD

Building your own pages
=======================
It's time to learn how to insert your data into your own custom web pages.  Which means it's time to look at the samples again. :/
Now, Examine this URL closely and then try it out in your browser:
http://mydomain.com/cgi-bin/db.exe?REQ=HTML&DB=sample&INPUTFILE=index.html

The page you see has a little navigation bar on the top with the names of several tables.  Of course, unless you've created tables called sample2, sample3, etc.. only the first one (sample) will work.  Below this is a hyperlink to go into edit mode.  Below that is an HTML table showing our database table rows and data.  Now let's see how its done.  Go back to the cgi-bin directory and open up the file index.html in your favorite text editor.

You'll notice that in several places, there are HTML-like request tags that look like this: <#REQ=FIELD&T1=DESCRIPTION> and so forth.  These special requests are how we insert data into our web page, create loops, and perform conditionals.  The special html requests all begin with the '<#REQ=' string and end with a normal '>' character. Here is a run-down of the several html requests and their uses.

<#REQ=IF&MYTAG1=myValue1> ... html or other requests shown only if the condition is true
<#REQ=ELSE> .. html or other requests shown if the condition is false 
<#REQ=ENDIF>

The IF conditional request allows you to display certain HTML or other requests depending upon whether the condition is true or false.  The condition is defined by the expressions following the first & symbol.  More than one expression may be included, but each expression must be separated by a & symbol, and at least one expression must evaluate to true for the condition to be true.  This makes the default condition like a series of programming OR statements.  Each expression is of the form TAGNAME=VALUE.  The TAGNAME value may be DBNAME to test the name of the current table, DBKEY to test the current row number (0..n-1), or the name of one of the current table tags/columns.  These last are only available if DBKEY has been defined either in the URL for the page, or was defined by a previous <#REQ=.. > request.  If conditionals can NOT be truely nested, though you can mest additional <#REQ=IF..> requests to accomodate AND conditions.  There should only be one <#REQ=ENDIF> regardless of the number of <#REQ=IF..> conditionals in a single nesting.

<#REQ=ROWLOOP> ... html or other data to repeat <#REQ=ENDLOOP>

The ROWLOOP and ENDLOOP requests define a block of html which is repeated once for every row of the current table.  The DBKEY tag is automatically updated on each iteration through this loop.  Since the ROWLOOP request selects rows in your table, it opens up the availability of the column names for use, for instance, in the IF request, or in the FIELD request below.

<#REQ=FIELD&T1=MYTAG1>

The FIELD request allows you to display the value of fields in the current selected row.  Rows are selected whenever the DBKEY tag is defined, either by the URL of the current page, or by one of the other requests.  The T1 string is a required portion of the request.  The MYTAG1 portion is any of the tags discussed above in the IF request, such as DBNAME, DBKEY, or a table tag/column name.

<#REQ=SORT&BY=MYTAG1&THENBY=MYTAG2&ANDTHENBY=MYTAG3>

The SORT request will sort the rows of the current table by the column names specified.  No specific row needs to be selected with the DBKEY tag to make this request work.  The BY portion of the request should be made equal to a valid table tag/column name.  The THENBY portion and the ANDTHENBY portions are optional.  They define how the rows will be sorted when the values of the BY column are equal, and (in the case of ANDTHENBY) when the values of the THENBY column are equal.  After this request is encountered, future row iterations using the ROWLOOP request will reflect the sorted data.

<#REQ=PARM&NAMED=MYURLTAG>

The PARM request will insert into the HTML the value of one of the URL tags for the current page.  It is useful for reflecting on the current value of such URL tags as DB, DBKEY, or even REQ.  The name of the URL tag to display should be the value set for the NAMED portion of the tag.  If you wanted to display the DB URL tag for instance, you would enter <#REQ=PARM&NAMED=DB>.

<#REQ=REFRESH>

This request, entered exactly as above, removes any of the current sorting and returns the table to its original form.

<#REQ=NEWDB&DB=MYTABLENAME>

This request will change the current table mid-stream in the HTML.  Where MYTABLENAME you should put in the name of your table as it appears in the db.ini file.

<#REQ=SELECT&DBKEY=MYROWNUM>

This request will select a specific numbered row in the current table.  Where MYROWNUM would be a number from 0..n-1 where n=number of rows.  This request allows others which require DBKEY to be defined, such as FIELD or IF requests, to work properly.


Troubleshooting your pages
==========================

The most common error is entering table tag/column names incorrectly, or not specifying a table name properly.  When debugging your custom html pages, you may receive either an error message, or a db cgi failure message of some sort, either from the cgi itself, or from the web server, if data is entered incorrectly.

The best way to troubleshoot this is to begin taking request <#REQ=...> tags out of your html until the problem disappears, thereby narrowing down which request is causing the issue.