cgi_protocol(n) 1.0 "flibs"
cgi_protocol - Module for supporting the Internet CGI protocol
TABLE OF CONTENTS
DATA TYPES AND ROUTINES
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
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
The module defines the following data types:
The module defines the following routines:
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.
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).
- 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
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
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.
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.
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
- 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:
<input type="hidden" name="sessionid" value="(contents of the string)">
- 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.
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.
Copyright © 2008 Arjen Markus <firstname.lastname@example.org>