CGI Application Overview

A Web server receives a request for a document that is (through naming conventions or directory mapping) an executable program.

The Web server establishes an environment and starts the program. In some cases the program passes data to the standard input handle of the script process. The environment variables, plus the format definition of the data sent on the standard input channel to the executable, are defined by the CGI specification.

The program sends an HTML document back to the server on its standard output handle and then exits. The server, in turn, sends the document back to the browser that made the original request.

Some servers running in non-UNIX environments have additional methods of communicating with the executable. An example is O'Reilly's WebSite for Windows NT and Windows 95, which uses a file-based interface called "Win-CGI". Netscape's Fast Start server also supports Win-CGI.

The data passed to the program is normally made up of name=value pairs, passed either through the document request itself or through an HTML form. The program evaluates the names and associated values, performs an action based on the data, and returns an HTML formatted document. An example follows:

http://www.yourcomp.com/cgi/showcust?custnum=5

In this example, the executable "showcust" is given the data "custnum=5", which is used to find a customer record and format an HTML document showing customer information.

Because Business BASIC interpreters cannot directly communicate with the Web server, a middle layer is provided by the BASIC Web Utility. There are two methods used by the BASIC Web Utility: the on-demand method and the shared directory method.

On-Demand Method

The most efficient method is to start a Business BASIC task for each request. Because requests are usually answered quickly, and the task exits, problems with user count restrictions are few. A shell script, called "bwu.sh ", is included with the BASIC Web Utility and can be used for this interface method. Also, bwu.sh can be copied to a PATHed directory and CGI scripts written:

#!/bin/sh
PGM=program.bb; export PGM
MEM=512; export MEM
exec bwu.sh

Replace program.bb with the Business BASIC program name to be started by bwu.sh . An alternative is to copy bwu.sh to the desired script name in the CGI directory and edit it to include the PGM and MEM variables internal to that script.

With Windows NT and Windows 95, use the stdcgi.exe or wincgi.exe, depending on the Web server's CGI support. Most support standard CGI. Others, such as O'Reilly website, also support Win-CGI. Associated ".bat" files must be provided for stdcgi.exe and wincgi.exe to work.

On-Demand Programming Example

Once the Business BASIC program is started, it must read the CGI input and develop a HTML response. A CALL to "utcgi.wbb" is needed to read the input. A variety of routines are available to produce the output and should be sent out through CALLs to "utsend.wbb". When the output is complete, a CALL to "utexit.wbb" completes the task. Below is an example that builds a list from a small file:

call "utcgi.wbb",env$,cgi$,errmsg$
call "uttags.wbb","h1","Data File Listing",html$
dim tpl$:"id:c(5),name:c(30)"
line$="<li> [id] [name]"
chan=unt; open(chan)"data.fil"
call "uthtmfil.wbb", chan, "", "", 0,0,0,"", tpl$,line$,work$, ""
call "uttags.wbb","ul",work$,html$
call "utsend.wbb",html$
call "utexit.wbb",cgi$
release

This example was created with the following steps:

  1. The CGI input is read.

  2. A HTML heading is placed into the variable html$

  3. A template is defined for reading data from "data.fil".

  4. A line structure is specified to be used for each record from the file.

  5. The file is opened.

  6. A list of all records, using the specified line$ structure for each, is placed in work$.

  7. The "unordered list" tags are added to work$, and the result is added to html$.

  8. html$, which now contains a HTML document, is sent back to the user.

  9. The task is formatted and released.

Shared Directory Method

A second method uses a shared directory, with a script or other executable started by the Web Server generating files that contain requests, and one or more Business BASIC tasks running in the background, monitoring the same directory and producing results in associated files. This method is less efficient that the on-demand method, but it allows control of user counts, and can also be implemented in environments where Business BASIC cannot work with standard input and output handles.

The Business BASIC program "utwatch.wbb" can be in the background and watch a directory or run other programs based on requests in that directory. The UNIX shell script bwu2.sh can also be used to create shared directory requests.

Shared Directory Programming Example

In the on-demand mode, the Business BASIC program is RELEASEd, while in the shared directory mode, the program "utwatch.wbb" is repeated until the next request. An option in BBxPROGRESSION/PRO/5 installations uses the BACKGROUND directive to start utwatch.wbb before completing the request. The program starts more quickly to respond to other requests and takes advantage of the BASIS user count logic of multiple background slots per foreground slot. When BACKGROUND is used successfully, the task running in background should RELEASE:

The first attempt to pass control back is with the "background" verb. If successful, the current program is running under a different task, and it sets the bkg variable flag to 1. The original task again runs utwatch.wbb. Note that utcgi.wbb must be called before the background verb because if successful, standard input handles are no longer available. This example is identical to the previous one, except that control is passed back to the program "utwatch.wbb", rather than to the operating system.

call "utcgi.wbb",env$,cgi$,errmsg$
rem "-- try background
bkg=0
background "utwatch.wbb",err=continue
bkg=1
continue:
call "uttags.wbb","h1","Data File Listing",html$
dim tpl$:"id:c(5),name:c(30)"
line$="<li> [id] [name]"
chan=unt; open(chan)"data.fil"
call "uthtmfil.wbb", chan, "", "", 0,0,0,"", tpl$,line$,work$, ""
call "uttags.wbb","ul",work$,html$
call "utsend.wbb",html$
call "utexit.wbb",cgi$
rem "-- if background worked, then release
if bkg then release
run "utwatch.wbb"