TITLE
CGI common procedures

SUMMARY
These are common procedure that can be used in CGI programs to make
it easier to write them, without having to remember some of the
technical details of CGI programs.

DOCUMENTATION
Include the module in your program with

do %cgi.r 


If the module is not in the current directory, specify the full name 
either with a drive letter or a UNC name in the REBOL syntax.


Usually, your program will be executed by the web server in response 
to a request from a web browser.  Also usually, there will be data 
availble from some sort of HTML form.  In the HTML form, the INPUT 
items will be identified by the "NAME" attribute.  To get your hands 
on the data from the form, use this procedure:

CGI-GET-INPUT


This procedure detects the proper source of the input data (GET or 
POST) and reads the data, and then assembles it into an object. Each 
data item can be referenced using the "path" syntax of

CGI-INPUT/data-name-1  

where "data-name-1" is the name sepecified in the "NAME" attribute.


After processing any input, your program will display some HTML output. 
There are two main ways of doing that.


What you are going to do in general is build up a full HTML page 
in memory and then "print" it with the "print" function, which will 
cause the page to be sent back to the web server and then the web 
browser.  But before you do that, you must print some special headers 
with this function:

CGI-DISPLAY-HEADER


To build up that HTML page that you will print, there are two ways. 
Each way has the common end point of appending some HTML coding to 
the end of that big page in memory.


The first way is to construct HTML in your program.  You can do this 
a line at a time, or several lines at a time.  The HTML can contain 
rebol words, because it will be reduced.  Build you HTML in a word 
and then do:

CGI-EMIT-HTML data-name-2

Where data-name-2 is that rebol word that contains your HTML line(s).


The second way is to make a separate file of HTML. In this HTML file, 
you may embed rebol code inside <% and %> tags.  This code 
will be evaluated, and the results of the evaluation will replace 
the rebol code and its surrounding tags.  This is sort of what PHP 
does.  The rebol code can reference words in your program, so that 
is how you can get data that is in your program put into HTML.  Do 
this:

CGI-EMIT-FILE file-name-1


Where file-name-1 is the name of that file of HTML code with the 
optional embedded rebol code.


When you have built up a full HTML page, it is your own responsibility 
to send it to the web server with the following command:

print CGI-OUTPUT 


There is another somewhat-related service supplied by this module. 
Sometimes a program is written to display HTML not to be interpreted 
by a browser, but to be shown as HTML.  That can be done with:

data-name-3: CGI-ENCODE-HTML data-name-4


where data-name-4 is an HTML fragment, and data-name-3 is that same 
fragment with the tag markers ("<" and ">") replaced the the 
code that causes them to be shown by the browser.