192 lines
6.4 KiB
Groff
192 lines
6.4 KiB
Groff
[comment {-*- flibs -*- doctools manpage}]
|
|
[manpage_begin cgi_protocol n 1.0]
|
|
[copyright {2008 Arjen Markus <arjenmarkus@sourceforge.net>}]
|
|
[moddesc flibs]
|
|
[titledesc {Module for supporting the Internet CGI protocol}]
|
|
|
|
[description]
|
|
|
|
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 [emph cgi_protocol] module seeks to take
|
|
care of.
|
|
|
|
[para]
|
|
The global structure of a program that uses this module to
|
|
communicate with the web server is basically:
|
|
|
|
[list_begin bullet]
|
|
[bullet]
|
|
Get the data from the web server, via [emph cgi_begin]
|
|
[bullet]
|
|
Handle these input data and write the corresponding HTML-file
|
|
[bullet]
|
|
Notify the web server the result is available and stop
|
|
[list_end]
|
|
|
|
[section "DATA TYPES AND ROUTINES"]
|
|
The module defines the following data types:
|
|
|
|
[list_begin definitions]
|
|
|
|
[call [cmd "dict_struct"]]
|
|
A derived type holding a list of keyword-value pairs. Each value is of the
|
|
type "dict_data" (see below). The routine [emph cgi_begin] fills such a
|
|
structure to hold all form variables and their values.
|
|
|
|
[call [cmd "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).
|
|
|
|
[list_end]
|
|
|
|
The module defines the following routines:
|
|
|
|
[list_begin definitions]
|
|
|
|
[call [cmd "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.
|
|
|
|
[list_begin arg]
|
|
|
|
[arg_def "integer, intent(in)" html]
|
|
Type of output that will be written. Should be one of the following
|
|
parameters:
|
|
[list_begin bullet]
|
|
[bullet]
|
|
output_html - the output will be HTML text (the corresponding CGI header
|
|
is written by this routine)
|
|
[bullet]
|
|
output_text - the output will be plain ASCII text (the corresponding CGI
|
|
header is written by this routine)
|
|
[bullet]
|
|
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 [emph cgi_header]
|
|
to write the appropriate header later.
|
|
[bullet]
|
|
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.
|
|
[list_end]
|
|
|
|
[arg_def "type(dict_struct), pointer" dict]
|
|
Variable to hold alll the form variables and their values. You pass
|
|
this variable to [emph cgi_get()] to retrieve these values. You can also
|
|
store new variables and values, if this is useful (via the plain
|
|
dictionary routines).
|
|
[nl]
|
|
[emph Note:]
|
|
Initialise it to "null()" before calling the routine.
|
|
|
|
[arg_def "integer, intent(out)" luout]
|
|
LU-number for writing output to the web server. Always use this
|
|
LU-number, not "*" to write the output.
|
|
[nl]
|
|
[emph Note:]
|
|
If "standard output" is used in the protocol, then this LU-number is
|
|
set to 6 - this is not completely portable of course.
|
|
|
|
[list_end]
|
|
|
|
|
|
[call [cmd "call cgi_header( type )"]]
|
|
Write the CGI header information
|
|
|
|
[list_begin arg]
|
|
[arg_def "integer, intent(in)" type]
|
|
Type of output that will be written. See above
|
|
[list_end]
|
|
|
|
|
|
[call [cmd "call cgi_end"]]
|
|
Indicate to the server that we are done. The routine stops the program.
|
|
[nl]
|
|
[emph 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 [emph g95] compiler for instance reports any
|
|
memory that has not been freed. Such output may end up in your HTML
|
|
output!
|
|
|
|
|
|
[call [cmd "call cgi_error( msg, template )"]]
|
|
Report a fatal error in the form of HTML text
|
|
|
|
[list_begin arg]
|
|
[arg_def "character(len=*), intent(in)" msg]
|
|
Message to be written
|
|
|
|
[arg_def "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.
|
|
|
|
[list_end]
|
|
|
|
|
|
[call [cmd "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.
|
|
[nl]
|
|
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:
|
|
[example {
|
|
<input type="hidden" name="sessionid" value="(contents of the string)">
|
|
}]
|
|
|
|
[list_begin arg]
|
|
[arg_def "character(len=*), intent(out)" value]
|
|
The unique session ID
|
|
[list_end]
|
|
|
|
|
|
[call [cmd "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.
|
|
[nl]
|
|
If you want to check if a form variable by the name of [term varname]
|
|
actually exists, you can use the [term dict_has_key] function, defined
|
|
by the [term dictionary] module.
|
|
[list_begin arg]
|
|
[arg_def "type(DICT_STRUCT), pointer" dict]
|
|
The dictionary as returned originally by [term cgi_begin] (you may want
|
|
to add new values and variables yourself for easy reference).
|
|
[arg_def "character(len=*), intent(in)" varname]
|
|
The name of the variable to retrieve
|
|
[arg_def "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.
|
|
[list_end]
|
|
|
|
[list_end]
|
|
|
|
|
|
[section NOTES]
|
|
The current implementation assumes that the compiler supports the new
|
|
intrinsic routine [emph 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.
|
|
|
|
[para]
|
|
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.
|
|
|
|
[para]
|
|
The [emph cgi_protocol] module uses the dictionary module underneath.
|
|
For convenience the source code for that module is contained within the
|
|
source directory for the [emph cgi_protocol].
|
|
|
|
[manpage_end]
|