CGI Programming using PowerBASIC - Part 2: Server Side Includes

By Joe Byrne

In part one, we looked at the basic concepts of developing a CGI application.  The Contacts sample used a straight forward HTML page that included a FORM and a few standard HTML form controls.  When the Submit button is clicked, the user-entered data from this form is passed to our CGI application and then simply spit back the to web browser.  The main idea here, was to demonstrait the basic components necessary to create a CGI web page.  To summerize:

  1. A standard HTML page that contains a <FORM> and various FORM controls (text boxes, checkboxes, pull-down menus, etc)
  2. The action= portion of the FORM command points to the CGI executable a the web server:
    - <form name="MyForm" action="/cgi-bin/myCGIprogram.exe">
  3. A PB executable that reads the FORM control values, processes that data, and returns some valid HTML code to the browser

In addition to all this, you must have a Web Server that runs under Windows and supports executable CGI programs.  There are a number of such programs available, but the two I most highly recommend are Abyss and Sambar.  Both of these offer a very decent free version, they are both rock solid, and both will work with PB Execs without a problem.  If your web site is hosted someplace else, you need to be sure they allow/support Windows compiled programs.

Server Sided Includes (SSI)
There are times when you only need a little dynamic content for your existing pages, so repainting the entire page maybe over kill.  Then too, there are times that you need to pull data from an external source that changes frequently.  This type of data is often presented in a 'drop-down' menu, or a combobox as we often call it.  When the data is static, such as a list of States, its usually easier to simply hard code the list in your HTML page like this:

However, when your data changes frequently, you really don't want to edit the HTML page every time! One option is to create the entire page using CGI but
then other changs to the page become more difficult to manage. Enter SSI, or Server Sided Includes. SSI is a special tag that instucts the web server to insert
the content from a CGI application at the appropriate spot on the page.  Not all web servers support this feature though, so make sure yours does.  The normal tag for an SSI command is:  <!--#exec cgi="myCGIprogram"-->

The first part of the tag: (<!--#exec) tells the web server to pass the processing on to a script or program that resides on the server and place the output from that program at this point of the page.  cgi= tells the server that the following script is a CGI application, the name of which is enclosed in quotes.  Where this CGI application physically exists is determined by the configuration of the web server.  Most servers allow SSI programs to reside anyplace within the sites namespace, but for security reasons its normally best to keep all CGI applications under on folder, even SSI programs.  I normally hard-code the reletive path to all my CGI applications in the HTML text, such as:  cgi="./cgi-bin/myCGIprogram.exe"  This tells the web server that the CGI program, myCGIprogram is located in the folder /cgi-bin/ within the main documents section.  If you omit the path information, most web servers will assume the SSI program is located within the documents directory and you will end up with an error on your page.

Pages that include SSI tags must be scanned by the web server in full before they are presented to the browser.  Therefore, you can really slow down your entire site if the web server has to pre-scan every document you wish to display.  To avoid this, pages that include SSI commands (normally) use the .SHTM or .SHTML file extension to their name.  This way, the web server only scans pages ending with .shtm/.shtml for valid SSI tags.  If you have an SSI tag in a normal document, the actual tag itself will be displayed, not the output from the CGI program as desired.

So, to dynamically create a combobox like the one above using SSI, our coding looks something like this:

HTML PAGE, states.shtm:

SSI/CGI Application, statelist.exe

The method you use to store/maintain your data list is immaterial here.  You can just as easy read the data from an SQL database, a Cheetah or Tsumani database, or any other source.  The advantage here is flexibility for dynamic data.  Whenever you change the data in your source file, the HTML page will instantly reflect that change without any further editing of the HTML page itself.

SSI capabilities offer a powerful method of including dynamic data to your web site with minimum fuss.  A common use of SSI is to maintain a 'hit couter' on one or more pages.  Someplace (normally near the bottom of the page) simply include an SSI directive to increment a counter value and write that value out to your page.  You can then keep track of the number of times that page has been displayed.  In order to track unique visits however, you'll need to identify the browser in some way.  One method of doing that is with cookies which we'll talk about next time.