Writing WebTen Bourne Shell Script CGIs


Writing CGIs under WebTen is simple. This describes one of the simplest WebTen CGIs -- a Bourne Shell CGI.

Most Web servers implement an interface called the Common Gateway Interface (or CGI interface) to support local extensions. WebTen has extended the Apache Web server to support five different styles of CGIs-- shell CGIs, Perl CGIs, AppleScript CGIs, WSAPI CGIs, and C or C++ program CGIs. While almost any script or programming method can be used as a CGI, these methods are the ones most commonly used with WebTen.

Shell CGIs are Text Files

This document describes what is possibly the simplest CGI to create and use -- the shell CGI. A shell CGI is a text file that contains commands for the Bourne Shell command interpreter.

Use any text editor to create a shell CGI. We recommend BBEdit as a great general purpose Macintosh text editor, but any editor will do (even SimpleText). Shell CGIs are typically given the suffix ".sh" (e.g., mycgi.sh).

Create a new CGI called mycgi.sh.

Store the newly created file in the WebTen directory. (We recommend the cgi-bin directory.) The new CGI can be referenced from a browser with the following URL:

/cgi-bin/<cgi-name>

If mycgi.sh is stored in the cgi-bin directory, the URL would be:

/cgi-bin/mycgi.sh

Basic Steps

Required Shell Script Content

In addition to creating the text file, there are a few important considerations with respect to the content of the file. First, the top line of the file must contain the following text:

#!/bin/sh

This tells the WebTen system that this is a Bourne Shell script and that the Bourne Shell should be used to interpret the rest of the script.

Second, you can use the echo command to generate text which will be returned to the browser that initiated the URL. The first echo command must contain the following Bourne Shell commands to generate HTTP. This puts WebTen and the browser in the proper mode to accept everything else:

echo Content-type: text/plain
echo

The first echo indicates that text/plain will follow. The second echo is necessary in order to get the HTTP interpreter to accept the Content-type request. After that, any text sent with an echo command is printed on the originating browser's screen as a response to the URL request.

Shell scripts are text files containing Bourne Shell commands that can generate a stream of characters in response to being executed. There are Bourne Shell commands for assigning integer and string values to shell variables, commands for prescribing conditional flow through the shell script, and commands for running other programs. Relatively sophisticated CGIs can be created by combining different Bourne Shell commands. There are a number of widely available books describing Bourne Shell programming.

Bourne Shell CGIs are fast and easy to develop

Bourne Shell CGIs are used for low-performance, easy-to-develop CGIs. Each Bourne Shell script is text, and is interpreted by a Bourne Shell interpreter controlled by WebTen. Since the interpreter interprets each command, shell scripts operate fairly slowly and use a large number of processing cycles. Therefore, Bourne Shell scripts should be used primarily for fast CGI development or CGI prototyping. If a CGI will be used in high volume, you may want to consider constructing a more efficient C Language CGI or a Perl CGI.

Printenv.sh Example

A sample shell CGI is included in the printenv.sh file located in the WebTen cgi-bin directory. The first few lines of the file establish the mandatory #!/bin/sh and echo Content-type: text/plain requirements for any shell script. The remaining shell script commands are used to output a few lines of constant text, followed by a dozen or more lines that output the values of a family of shell variables. The following is the content of the printenv.sh CGI:

#!/bin/sh
# disable filename globbing
set -f
echo Content-type: text/plain
echo
echo CGI/1.0 test script report:
echo
echo argc is $#. argv is "$*".
echo
echo SERVER_SOFTWARE = $SERVER_SOFTWARE
echo SERVER_NAME = $SERVER_NAME
echo GATEWAY_INTERFACE = $GATEWAY_INTERFACE
echo SERVER_PROTOCOL = $SERVER_PROTOCOL
echo SERVER_PORT = $SERVER_PORT
echo REQUEST_METHOD = $REQUEST_METHOD
echo HTTP_ACCEPT = "$HTTP_ACCEPT"
echo PATH_INFO = "$PATH_INFO"
echo PATH_TRANSLATED = "$PATH_TRANSLATED"                                          

echo QUERY_STRING  = $QUERY_STRING

echo SCRIPT_NAME =  $SCRIPT_NAME
echo REMOTE_HOST = $REMOTE_HOST
echo REMOTE_ADDR = $REMOTE_ADDR
echo REMOTE_USER = $REMOTE_USER
echo AUTH_TYPE = $AUTH_TYPE
echo CONTENT_TYPE = $CONTENT_TYPE
echo CONTENT_LENGTH = $CONTENT_LENGTH

When the printenv.sh CGI is referenced by a URL, it produces the following output:

CGI/1.0 test script report:
argc is 0. argv is .
SERVER_SOFTWARE = Apache/1.2b10 WebTen/1.0b8.7
SERVER_NAME = ppc0.tenon.com
GATEWAY_INTERFACE = CGI/1.1
SERVER_PROTOCOL = HTTP/1.0
SERVER_PORT = 81
REQUEST_METHOD = GET
HTTP_ACCEPT = image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, 
PATH_INFO =
PATH_TRANSLATED =
SCRIPT_NAME = /cgi-bin/printenv.sh
QUERY_STRING =
REMOTE_HOST = 205.180.86.8
REMOTE_ADDR = 205.180.86.8
REMOTE_USER =
AUTH_TYPE =
CONTENT_TYPE =
CONTENT_LENGTH =

Shell Variables

Shell variables are pre-defined values set by WebTen before the shell CGI is started. Shell variables are referenced by placing a "$" character in front of the name of the shell variable. If the shell interpreter finds a name that matches the string of characters following any "$" character, it substitutes the value of that variable in its processing. In the case of the echo command, the value of the $VAR shell variable is substituted as a parameter to the echo command and is output to the browser as a partial response to the URL request.


Page last updated 12/28/1999

http://www.tenon.com/support/webten/papers/webten-shell-cgi.html