Using Euphoria for CGI programming
To Grape Vine et all (warning: long CGI specific post ahead):
I'm glad not to be the only one interested on using Euphoria as a CGI
programming language. I'll try to provide with my limited english
vocabulary what I have learned (empirically) over the past months.
CGI is a way to build on-the-fly HTML files. There are plenty of HTML
tutorial and authoring tools on the net (search Yahoo or Hotbot), so I
won't bother in trying to teach HTML here. There's a great tool named
"HomeSite" from Allaire (www.allaire.com), it's not only the best HTML
editor on the market, but also includes a complete HTML reference. You may
download a 30 days evaluation version (fully functional).
First we need to understand what happens behind the scenes when we type (or
click) a URL on our browser (I'll skip the DNS stuff). The browser tries to
connect to port 80 of the server. If there is a webserver running on the
server (and listening to port 80), a connection is established. The protcol
used in this connection is HTTP. To retrieve an HTML file (page) from the
server, the browser sends a GET command.
What the webserver does with this command is not of the browsers bussiness.
You may configure your webserver in such a way that when a GET one.html is
recieved, the webserver send's page two.html back. I hope it's clear
enough. The point is that the webserver's "file space" is not like a normal
file system, it can be tweaked, one URL doesn't mean one distinct file.
If the URL to retrieve happens to be a CGI, the webserver executes it and
sends back to the browser the output of that program. CGIs are great for
database front-ends. But what *is* a CGI? A CGI is any file that can be
executed. On *nix world that means programs and shell scripts, on Dos/Win
that means .exe, .com, .bat, and .cmd (NT). For security reasons webserver
usually don't allow to just go and execute winword.exe, they must be on a
special directory (generally cgi-bin).
Another question pops in our minds: How does my CGI gets it's input, and
how to output the result? To solve this is that a CGI standard was created.
In escence the CGI get's it's input from stdin, and sends it's output to
stdout. In *nix that's easy, on Windows platforms that's more complicated.
I'll focus on Windows platforms using the Xitami webserver
(www.sitami.net), 'cause there's no Eu4*nix, and 'cause I'm using WinNT
(Xitami also runs on 95/98, and *nix!).
On HTML there are this things called forms. A form is a collection of
related data that can be submited to a CGI for it's processing. A form is
defined with the <FORM> tag. The parameters of the tag specify the CGI URL
where to send the data, the method to be used to submit the data (GET ot
POST), and the encoding type. You can safely ommint the encoding mime type.
<FORM ACTION="_URL_" METHOD="GET|POST" ENCTYPE="MIME type">
</FORM>
Within the form definition you create fields of data. A field can be a
button, checkbox, radiobutton, text line, text area, etc. A field is
defined with the <INPUT> tag.
Here's a form that sends a username and email to the CGI located at
http://some.server/cgi-bin/mycgi.cgi:
<FORM ACTION="http://some.server/cgi-bin/mycgi.cgi" METHOD="POST">
Enter username:<BR>
<INPUT NAME="USERNAME" TYPE="TEXT" SIZE="20"><BR><BR>
Enter email:<BR>
<INPUT NAME="EMAIL" TYPE="TEXT" SIZE="10"><BR><BR>
<INPUT TYPE="SUBMIT">
</FORM>
BTW <BR> is a break of line.
When the user press the "Submit" button on the browser window, the values
of both (username and email) fields are sent to mycgi.cgi. These pair of
values (USERNAME=some_value&EMAIL=some_other_value) can be read by the CGI
from stdin. Xitami makes it a bit more easier by parsing these values for
you and creating one enviormental variable for each field. You can
configure Xitami to prepend to the field name a defined string, by default
it is "FORM_". A CGI under XItami should then read the enviormental
variables FORM_USERNAME and FORM_EMAIL to get the appropiate values.
As I have mentioned before stdin and stdout may be a hassle on Win32, so
Xitami also provides an alternative. It gives you files from where to read
and write, as stdin and stdout alternatives respectivly. The filenames are
available from the enviormental variables CGI_STDIN and CGI_STDOUT. These
files are created by Xitami on the xitami\temp directory. CGI_* filenames
doesn't include a full pathname, so you must "fix" them before opening the
files, usually with "c:\\xitami\\temp\\" & CGI_* (It depends on where you
installed Xitami and how you've configured it). You won't use CGI_STDIN
usually, so don't even bother in reading it.
The output of the CGI should be sent to the above CG_STDOUT file. One
important thing is that the very first line sent must be a mime header,
usually of type text/html, followed by at least one blank line and then the
actual data. Note that the CGI could as well output an image or any other
binary data, as long a your mime header correctly identifies the data sent.
As you see a CGI is just like any other application, the only difference is
where and how to recieve it's input and send it's output.
Now that we know what and how a CGI does, let's see how to do it in Euphoria:
Let's create a small EuCGI (my name for CGIs written with Euphoria), that
processes the above FORM.
[warning: untested code (but should work), directly typed in the mail
client. No warranties are implied ;) ]
--mycgi.exw
sequence username, email, outfile
integer out
--Get output file
outfile = getenv("CGI_STDOUT")
outfile = "c:\\xitami\\temp\\" & outfile
--Get form data
username = getenv("FORM_USERNAME")
email = getenv("FORM_EMAIL")
--Open output file for APPEND
out = open(outfile, "a")
--MIME header
puts(out, "Content-type: text/html\n\n")
--Put the html data
printf(out, "<html><head><title>EuCGI test</test></head><body><center>Your
{username, email})
--Close output file
close(out)
We have just one pending topic. An .exw file ain't directly executable. We
have two choices:
a) Bound it to create an .exe file.
b) Execute exw.exe with the path to the .exw file.
Alternative a) is limited to registred users. I'll show a technique I
"discovered" to perform b). Xitami let's a CGI to be a Perl script. In Perl
the # character marks the begining of a comment (like '--' in Euphoria), so
if you put in the very first line of the script:
#! full_path_to_perl_interpreter
Xitami will spawn the Perl interpreter and pass it as parameter the path of
the script. When the script is interpreted by Perl this first line will be
ignored because it's a comment.
We can't do this directly in our Euphoria source code because # isn't a
comment delimiter in Euphoria. The workaround is to create a dummy text
file that will be used to fool Xitami:
#! full_path_to_exw.exe full_path_to_exw_file
So if you saved mycgi.exw on c:\EuCode, the dummy file should be:
#! c:\euphoria\bin\exw.exe c:\eucode\mycgi.exw
The dummy file can be named whatever you want, but in this example it must
be mycgi.cgi (remember the ACTION=... of the form?), and has to be located
on the cgi-bin directory.
I hope this document clarifies some doughts about CGIs and Euphoria.
Regards,
Daniel Berstein
[ daber at pair.com ]
|
Not Categorized, Please Help
|
|
