257 lines
8.8 KiB
HTML
257 lines
8.8 KiB
HTML
<! -- -*- flibs -*- doctools manpage
|
|
-->
|
|
<html><head>
|
|
<title>cgi_protocol - flibs </title>
|
|
</head>
|
|
<! -- Generated from file 'cgi_protocol.man' by tcllib/doctools with format 'html'
|
|
-->
|
|
<! -- Copyright © 2008 Arjen Markus <arjenmarkus@sourceforge.net>
|
|
-->
|
|
<! -- CVS: $Id$ cgi_protocol.n
|
|
-->
|
|
|
|
<body>
|
|
<h1> cgi_protocol(n) 1.0 "flibs"</h1>
|
|
<h2><a name="name">NAME</a></h2>
|
|
<p>
|
|
<p> cgi_protocol - Module for supporting the Internet CGI protocol
|
|
|
|
|
|
|
|
|
|
<h2><a name="table_of_contents">TABLE OF CONTENTS</a></h2>
|
|
<p> <a href="#table_of_contents">TABLE OF CONTENTS</a><br>
|
|
<a href="#synopsis">SYNOPSIS</a><br>
|
|
<a href="#description">DESCRIPTION</a><br>
|
|
<a href="#data_types_and_routines">DATA TYPES AND ROUTINES</a><br>
|
|
<a href="#notes">NOTES</a><br>
|
|
<a href="#copyright">COPYRIGHT</a><br>
|
|
<h2><a name="synopsis">SYNOPSIS</a></h2>
|
|
<p>
|
|
<table border=1 width=100% cellspacing=0 cellpadding=0><tr bgcolor=lightyellow><td bgcolor=lightyellow><table 0 width=100% cellspacing=0 cellpadding=0><tr valign=top ><td ><a href="#1"><b class='cmd'>dict_struct</b> </a></td></tr>
|
|
<tr valign=top ><td ><a href="#2"><b class='cmd'>dict_data</b> </a></td></tr>
|
|
<tr valign=top ><td ><a href="#3"><b class='cmd'>call cgi_begin( html, dict, luout )</b> </a></td></tr>
|
|
<tr valign=top ><td ><a href="#4"><b class='cmd'>call cgi_header( type )</b> </a></td></tr>
|
|
<tr valign=top ><td ><a href="#5"><b class='cmd'>call cgi_end</b> </a></td></tr>
|
|
<tr valign=top ><td ><a href="#6"><b class='cmd'>call cgi_error( msg, template )</b> </a></td></tr>
|
|
<tr valign=top ><td ><a href="#7"><b class='cmd'>call cgi_get_session( dict, value )</b> </a></td></tr>
|
|
<tr valign=top ><td ><a href="#8"><b class='cmd'>call cgi_get( dict, varname, value )</b> </a></td></tr>
|
|
</table></td></tr></table>
|
|
<h2><a name="description">DESCRIPTION</a></h2>
|
|
<p>
|
|
|
|
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 <em>cgi_protocol</em> module seeks to take
|
|
care of.
|
|
|
|
<p>
|
|
The global structure of a program that uses this module to
|
|
communicate with the web server is basically:
|
|
|
|
<ul>
|
|
<li>
|
|
Get the data from the web server, via <em>cgi_begin</em>
|
|
<br><br>
|
|
<li>
|
|
Handle these input data and write the corresponding HTML-file
|
|
<br><br>
|
|
<li>
|
|
Notify the web server the result is available and stop
|
|
</ul>
|
|
|
|
<h2><a name="data_types_and_routines">DATA TYPES AND ROUTINES</a></h2>
|
|
<p>
|
|
The module defines the following data types:
|
|
|
|
<dl>
|
|
|
|
<dt><a name="1"><b class='cmd'>dict_struct</b> </a><dd>
|
|
|
|
A derived type holding a list of keyword-value pairs. Each value is of the
|
|
type "dict_data" (see below). The routine <em>cgi_begin</em> fills such a
|
|
structure to hold all form variables and their values.
|
|
|
|
<br><br>
|
|
<dt><a name="2"><b class='cmd'>dict_data</b> </a><dd>
|
|
|
|
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).
|
|
|
|
</dl>
|
|
|
|
The module defines the following routines:
|
|
|
|
<dl>
|
|
|
|
<dt><a name="3"><b class='cmd'>call cgi_begin( html, dict, luout )</b> </a><dd>
|
|
|
|
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.
|
|
|
|
<br><br>
|
|
<dl>
|
|
|
|
<dt>integer, intent(in) <i class='arg'>html</i><dd>
|
|
Type of output that will be written. Should be one of the following
|
|
parameters:
|
|
<br><br>
|
|
<ul>
|
|
<li>
|
|
output_html - the output will be HTML text (the corresponding CGI header
|
|
is written by this routine)
|
|
<br><br>
|
|
<li>
|
|
output_text - the output will be plain ASCII text (the corresponding CGI
|
|
header is written by this routine)
|
|
<br><br>
|
|
<li>
|
|
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 <em>cgi_header</em>
|
|
to write the appropriate header later.
|
|
<br><br>
|
|
<li>
|
|
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.
|
|
</ul>
|
|
|
|
<dt>type(dict_struct), pointer <i class='arg'>dict</i><dd>
|
|
Variable to hold alll the form variables and their values. You pass
|
|
this variable to <em>cgi_get()</em> to retrieve these values. You can also
|
|
store new variables and values, if this is useful (via the plain
|
|
dictionary routines).
|
|
<br><br>
|
|
<em>Note:</em>
|
|
Initialise it to "null()" before calling the routine.
|
|
|
|
<br><br>
|
|
<dt>integer, intent(out) <i class='arg'>luout</i><dd>
|
|
LU-number for writing output to the web server. Always use this
|
|
LU-number, not "*" to write the output.
|
|
<br><br>
|
|
<em>Note:</em>
|
|
If "standard output" is used in the protocol, then this LU-number is
|
|
set to 6 - this is not completely portable of course.
|
|
|
|
</dl>
|
|
|
|
|
|
<dt><a name="4"><b class='cmd'>call cgi_header( type )</b> </a><dd>
|
|
|
|
Write the CGI header information
|
|
|
|
<br><br>
|
|
<dl>
|
|
<dt>integer, intent(in) <i class='arg'>type</i><dd>
|
|
Type of output that will be written. See above
|
|
</dl>
|
|
|
|
|
|
<dt><a name="5"><b class='cmd'>call cgi_end</b> </a><dd>
|
|
|
|
Indicate to the server that we are done. The routine stops the program.
|
|
<br><br>
|
|
<em>Note:</em>
|
|
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 <em>g95</em> compiler for instance reports any
|
|
memory that has not been freed. Such output may end up in your HTML
|
|
output!
|
|
|
|
|
|
<br><br>
|
|
<dt><a name="6"><b class='cmd'>call cgi_error( msg, template )</b> </a><dd>
|
|
|
|
Report a fatal error in the form of HTML text
|
|
|
|
<br><br>
|
|
<dl>
|
|
<dt>character(len=*), intent(in) <i class='arg'>msg</i><dd>
|
|
Message to be written
|
|
|
|
<br><br>
|
|
<dt>character(len=*), intent(in), optional <i class='arg'>template</i><dd>
|
|
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.
|
|
|
|
</dl>
|
|
|
|
|
|
<dt><a name="7"><b class='cmd'>call cgi_get_session( dict, value )</b> </a><dd>
|
|
|
|
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.
|
|
<br><br>
|
|
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:
|
|
<p><table><tr><td bgcolor=black> </td><td><pre class='sample'>
|
|
<input type="hidden" name="sessionid" value="(contents of the string)">
|
|
</pre></td></tr></table></p>
|
|
|
|
<br><br>
|
|
<dl>
|
|
<dt>character(len=*), intent(out) <i class='arg'>value</i><dd>
|
|
The unique session ID
|
|
</dl>
|
|
|
|
|
|
<dt><a name="8"><b class='cmd'>call cgi_get( dict, varname, value )</b> </a><dd>
|
|
|
|
Get the value of a variable defined in the HTML form. If the variable is
|
|
not actually present, the value is left unchanged.
|
|
<br><br>
|
|
If you want to check if a form variable by the name of <em>varname</em>
|
|
actually exists, you can use the <em>dict_has_key</em> function, defined
|
|
by the <em>dictionary</em> module.
|
|
<br><br>
|
|
<dl>
|
|
<dt>type(DICT_STRUCT), pointer <i class='arg'>dict</i><dd>
|
|
The dictionary as returned originally by <em>cgi_begin</em> (you may want
|
|
to add new values and variables yourself for easy reference).
|
|
<br><br>
|
|
<dt>character(len=*), intent(in) <i class='arg'>varname</i><dd>
|
|
The name of the variable to retrieve
|
|
<br><br>
|
|
<dt>character(len=*)|real|integer|logical, intent(inout) <i class='arg'>value</i><dd>
|
|
The value (if the variable exists) - it can be a string, (single
|
|
precision) real, integer or logical.
|
|
</dl>
|
|
|
|
</dl>
|
|
|
|
|
|
<h2><a name="notes">NOTES</a></h2>
|
|
<p>
|
|
The current implementation assumes that the compiler supports the new
|
|
intrinsic routine <em>get_environment_variable</em>. 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.
|
|
|
|
<p>
|
|
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.
|
|
|
|
<p>
|
|
The <em>cgi_protocol</em> module uses the dictionary module underneath.
|
|
For convenience the source code for that module is contained within the
|
|
source directory for the <em>cgi_protocol</em>.
|
|
|
|
<h2><a name="copyright">COPYRIGHT</a></h2>
|
|
<p>
|
|
Copyright © 2008 Arjen Markus <arjenmarkus@sourceforge.net><br>
|
|
</body></html>
|
|
|