WWW CGI Features

The WWW CGI features include: script=, @CONTENT_LENGTH, @PATH_INFO, @HTML, @STDIN, @HOST, @HTTP_COOKIE, and the commands: Decode_HTML, Puts, and HTML_Table_Vectors Unique_Name, and Image_Map_Areas.

Invoking ACON as a CGI Application

This section of the documentation assumes a basic working knowledge of HTML.
For more information on HTML, please refer to one of the plethora of books available on HTML.

The Common Gateway Interface (CGI) defines a specific protocol for information passing between a WWW page (containing HTML text) and a gateway application used to process the FORM information generated by the WWW page. ACON supports the POST method of CGI interaction.

Here is an example demonstrating how ACON is invoked through the POST method of the FORM command:

The scriptfile is an ACON script which has been previously written to handle the parameter (in this case, the source parameter) passed through the HTML FORM and generate the resultant HTML output and graphics requested.

Here is an example of invoking ACON through an HREF.

The scriptfile in this case, is an ACON script which has been previously written to handle the parameters (query and header) passed through the href to query a database and generate the resultant HTML output and graphics requested.

Handling CGI Requests

When ACON is invoked through the Common Gateway Interface (CGI) a specific protocol is used to pass information from the POST method of the HTML FORM to ACON.

The steps taken during initialization (if ACON is being called as a CGI application) are:

• If the environmental variable CONTENT_LENGTH exists, it is stored as the character string <A NAME="@CONTENT_LENGTH">@CONTENT_LENGTH</A>.
• If the environmental variable PATH_INFO exists, it is stored as the character string <A NAME="@PATH_INFO">@PATH_INFO</A>.
• <A NAME="@HTML">@HTML</A> is set to the integer value of 1, otherwise it is left as its default vaue of 0.
• @CONTENT_LENGTH bytes are read from stdin, and saved as the character string <A NAME="@STDIN"><B>@STDIN</B></A>. This text contains the raw posted parameters from the HTML form.
• If @PATH_INFO begins with /script= the remaining text in @PATH_INFO is assumed to contain the directory path/filename of an ACON script, which is executed if successfully opened. This script should parse @STDIN and handle the request.

The Decode_HTML() command may be used to parse the @STDIN text into separate variables for each passed parameter:

Generating a CGI Response

When ACON is invoked through the Common Gateway Interface (CGI) the response is expected to be valid HTML output. An example of the minimum ACON script to generate a response from a CGI invocation is:

@HOST

The variable @HOST is available to query to determine what generic type of machine ACON is currently executing on. Since ACON is currently designed for Windows operating systems, @HOST will contain "win" when running on this respective host.

@HTTP_COOKIE

The variable @HTTP_COOKIE is available to obtain the current cookies from the user´s browser.
@HTTP_COOKIE will contain a character string with keyword=value pairs.

Decode_HTML

The Decode_HTML() command may be used to parse the @STDIN text into separate variables for each passed parameter. A character matrix is returned which contains the parameter name and value for each passed parameter. In addition, each of the parameters are internalized as variables of the same name, as character strings.

There is 1 parameter:

encoded str- the encoded HTML string containing the parameters.

parameter matrix = Decode_HTML(encoded character string);

For example, if the Posted parameters were passed via the WWW server as the encoded string:

species=COD&mgtunit=4VN&strata=440&strata=441&strata=444
&syear=1996&eyear=1996&summary=SET&stat1=Abundance
&survey=SCOTIA+SHELF+SUMMER+1970-1996
&source=Canadian+Groundfish+Research+Trawl+Surveys

then calling the Decode_HTML function would produce:

Note: More importantly, each of these parameters would now exist in memory as a character string
e.g. the variable SPECIES would exist, containing the string "COD".
When a parameter exists more than once (has more than one value), then it is saved as a character string with a "&" between each value
e.g. the variable STRATA would exist, containing the string "440&441&444".

Puts

The Puts command prints it arguments in a formatted form to StdList (the proper channel to generate HTML output). This command is similar to the Print() command, except that it prints to StdList reguardless of the state of the Echo() command.

In contrast, with the Print() command, when Echo() is 0, then all normal printed output is directed to the acon.lis file only, bypassing StdList. When Echo() is 1, output is directed to StdList as well, but in this case it is intermixed with the text of the command file being executed. Because of the intermixing of print() output with the command output, it is desirable that the Puts() command be used to print to the HTML StdList output in lieu of the Print() command.

Any numeric or string arguments are allowed.

Puts(any values passed as arguments);

HTML_Table_Vectors

The HTML_Table_Vectors command prints a set of numeric vectors or character matrices as a formatted table to StdList (the proper channel to generate HTML output).

There are up to 8 parameters:

namemat - character matrix containing the names of the variables containing the vector data to be formatted (required parameter).

tableparm - character string containing the HTML table parameters to be applied to the entire table. This string should contain text defining the parameters using the standard HTML table syntax (default - no table param).

coltitles - character matrix containing the column titles to be used for each variable contained in namemat (default - the names in ´namemat´).

rowtitles - character matrix containing the row titles to be used for each row in the table (default - no titles).

border - integer defining the pixel width of the table border (default 0).

alignment - character string defining the alignment of each column (default "MIDDLE").

TDparm - character string containing the HTML table parameters to be applied to the each TD entry. This string should contain text defining the parameters using the standard HTML table syntax (default - no TD param)

digits - integer vector defining the number of digits to display for each column. The length of this vector should match the number of columns of data displayed (character string columns will ignore their corresponding entry in this vector) (default 6 digits).

HTML_Table_Vectors(namemat, tableparam, coltitles, rowtitles, border, alignment);

Assuming you are viewing this document with a WWW browser, the following table is as the table will appear when this command is issued while creating HTML output. To view the actual output, view the source of this page.

Unique_Name

The Unique_Name() command returns a character string containing a unique filename for the target host Operating System. filename = Unique_Name();

Image_Map_Areas

This command prints an Image Map to the output device for longitude/latitude data. This command is typically used to create image map circles for each data point plotted.

There are 8 parameters:

lon - vector of x user coordinate (longitude) values.

lat - vector of y user coordinate (latitude) values.

x - vector of x screen coordinate values.

y - vector of y screen coorindate values.

alttags - character matrix of alt tags.

href - optional character matrix of hrefs. This element may be null.

shapestr - format string that generates the shape definition for each element.

attrstr - attribute string to include with each image map entry.