cgi_protocol(n) 1.0 "flibs"

NAME

cgi_protocol - Module for supporting the Internet CGI protocol

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    DATA TYPES AND ROUTINES
    NOTES
    COPYRIGHT

SYNOPSIS

dict_struct

dict_data

call cgi_begin( html, dict, luout )

call cgi_header( type )

call cgi_end

call cgi_error( msg, template )

call cgi_get_session( dict, value )

call cgi_get( dict, varname, value )

When you want to create web applications, the CGI (common gateway interface) is one of the means to integrate your underlying programs with the web server. The protocol itself is, at least superficially, simple enough, but you need to take care of a number of details. It is these details that the cgi_protocol module seeks to take care of.

The global structure of a program that uses this module to communicate with the web server is basically:

Get the data from the web server, via cgi_begin
Handle these input data and write the corresponding HTML-file
Notify the web server the result is available and stop

DATA TYPES AND ROUTINES

The module defines the following data types:

dict_struct: A derived type holding a list of keyword-value pairs. Each value is of the type "dict_data" (see below). The routine cgi_begin fills such a structure to hold all form variables and their values.
dict_data: The derived type whose contents is the string value of a particular form variable. It has one component: value, a string of 200 characters long (the actual length is set via the parameter "dict_value_length", so you can easily change it if this should prove necessary).

The module defines the following routines:

call cgi_begin( html, dict, luout )

Routine to start the interaction with the web server. It automatically determines the protocol to be used and fills the "dictionary" dict with the values of the form variables for easy retrieval. The last parameter, luout, should be used to write the results to the web server.

integer, intent(in) html

Type of output that will be written. Should be one of the following parameters:

output_html - the output will be HTML text (the corresponding CGI header is written by this routine)
output_text - the output will be plain ASCII text (the corresponding CGI header is written by this routine)
output_no_header - it is not known yet what the output type will be - you can decide this on the basis of the form input. Use cgi_header to write the appropriate header later.
output_html_delayed, output_text_delayed - (not implemented yet) indicate that the computation will take a while, so that a simple message is written first.

type(dict_struct), pointer dict

Variable to hold alll the form variables and their values. You pass this variable to cgi_get() to retrieve these values. You can also store new variables and values, if this is useful (via the plain dictionary routines).

Note: Initialise it to "null()" before calling the routine.

integer, intent(out) luout

LU-number for writing output to the web server. Always use this LU-number, not "*" to write the output.

Note: If "standard output" is used in the protocol, then this LU-number is set to 6 - this is not completely portable of course.

call cgi_header( type )

Write the CGI header information

integer, intent(in) type: Type of output that will be written. See above

call cgi_end

Indicate to the server that we are done. The routine stops the program.

Note: If the run-time library produces extra output as a consequence of finishing the program, then you may want to use compile options to suppress that output. The g95 compiler for instance reports any memory that has not been freed. Such output may end up in your HTML output!

call cgi_error( msg, template )

Report a fatal error in the form of HTML text

character(len=*), intent(in) msg: Message to be written
character(len=*), intent(in), optional template: Name of a file to be used as a template. If not given, a simple page will be written instead. The string "MSG" in that template is replaced by the contents of the variable msg.

call cgi_get_session( dict, value )

Get the value of the "sessionid" variable. This variable is already present in the form or it is set by this routine to a (more or less) unique value.

To use it as a session identifier (if your application requires a continued conversation with the user), make sure each subsequent HTML reply contains a line like:

character(len=*), intent(out) value: The unique session ID

call cgi_get( dict, varname, value )

Get the value of a variable defined in the HTML form. If the variable is not actually present, the value is left unchanged.

If you want to check if a form variable by the name of varname actually exists, you can use the dict_has_key function, defined by the dictionary module.

type(DICT_STRUCT), pointer dict: The dictionary as returned originally by cgi_begin (you may want to add new values and variables yourself for easy reference).
character(len=*), intent(in) varname: The name of the variable to retrieve
character(len=*)|real|integer|logical, intent(inout) value: The value (if the variable exists) - it can be a string, (single precision) real, integer or logical.

NOTES

The current implementation assumes that the compiler supports the new intrinsic routine get_environment_variable. If this is not the case, then it is possible to mimick this routine (with a bit of trickery), but that has not been implemented yet in this version.

There is no support as yet for a delayed response. The idea is that the program sends a short note to the web server, to inform the user that the final result takes a few minutes (or longer) and that he/she can find it at such and such a location.

The cgi_protocol module uses the dictionary module underneath. For convenience the source code for that module is contained within the source directory for the cgi_protocol.