🗐 CGI (Web) Applications in Euphoria
Since these days servers are running with 64-bit operating systems,
usually Linux, you should upload the 64-bit interpreter of
OpenEuphoria to the server's "cgi-bin" directory, instead of the RapidEuphoria 3.1.1 32-bit interpreter.
See also the Archive - Language Tools - 64-bit
interpreters by James Cook.
Note that on your computer you can run Euphoria 3.1.1 also with a 64-bit operating system,
see Instructions for installing Euphoria for more details - especially for Linux.
If you have a Web site, you may be able to set up programs on your server that
visitors to your site can run. Most free Web hosting services do not offer
this capability, but almost all paid services do. If they advertise features
like "cgi-bin", "Perl", "C" etc. then you can most likely run Euphoria
programs as well. The hosting company does not have to install Euphoria. You
can do it yourself quite easily. As far as the host is concerned, you are just
running a program written in C, namely the Euphoria interpreter.
A very simple protocol called CGI (Common Gateway Interface) is supported by
almost all paid Web servers, and you can use almost any programming language
to develop CGI applications. Perl is currently very popular for CGI, but
Euphoria is even better suited than Perl in many ways. Compared to Perl
programs, Euphoria programs start up quicker, run faster, and have better
error diagnostics. Compared to C, Euphoria programs take less effort to
develop, and are easier to change and debug. Euphoria also has much easier
string handling, which is often important in CGI programming.
CGI (Common Gateway Interface)
CGI is a fancy acronym for a very simple protocol. The CGI standard defines
how a Web browser passes information to a program running on a Web server, and
how that program passes information back to the Web browser.
If you have the necessary Web server software, and the approval of your
Internet service provider, you can probably run Euphoria CGI programs right on
your own (home) machine.
However, most people will have to use a Web hosting service that supports CGI.
You can find hosting services that cost anywhere from $3 U.S. per month up to
$50 or more.
RapidEuphoria.com is on a fairly reliable host (addr.com) that costs only $10
U.S. per month. For that price we get 3000 Mb of disk space on a FreeBSD
machine, and 60 Gb of bandwidth per month. Until recently, for the same price,
we were given only 150 Mb of space and 15 Gb of bandwidth. The bandwidth
limitation determines the number of bytes that may be downloaded by visitors
EUforum (on our domain ListFilter.com) is hosted on an even cheaper Linux site
(host-web-site.com) for $4/month. It has 200 Mb of space, and 5 GB of
bandwidth. Until recently, it cost $18/month, so hosting prices seem to be
Installing Euphoria for CGI
Installing Euphoria on a host is fairly simple. You just have to upload the
euphoria directory for the operating system that the host is running. You can
put the euphoria directory into the top level of your own personal space.
There is no need to change anything on the system as a whole. Using telnet (or
ssh) you can experiment, and make sure that you can execute some of the
euphoria\demo programs on the host. You should set up your EUDIR and PATH
variables to point to your euphoria directory. This might involve editing a
.profile file that's executed each time you log in.
The Euphoria CGI programs that you want people to run, must typically be
placed in a special subdirectory of your account, called "cgi-bin". cgi-bin is
often located under a directory called "public_html" which contains all your
publicly-visible HTML files. cgi-bin has special permissions that allow
visitors to your site to execute the programs it contains.
On Linux and FreeBSD, and also on Windows (if the system uses Apache Web
Server), you can use a "shebang" line as the very first line of your main
Euphoria file. It will show the system where the Euphoria interpreter (exu or
exw.exe) is located. e.g.
would say that the interpreter is in the current directory (cgi-bin). If you
upload this file to Linux/FreeBSD, be careful that the line ends with just \n,
Note: on Windows you should use exwc.exe, not exw.exe. exwc handles standard
output better, and that's critical for CGI. You should also say "without
warning" at the top of your main file. Warning messages could cause problems
in properly terminating your program.
On Linux/FreeBSD you must set execute permission on any CGI program. When a
user tries to run your program, a special process on the server actually runs
your program and it needs to find and have access to your Euphoria files. You
should probably set your files so anyone can read or execute them, but only
you can write them. e.g. rwx r-x r-x or chmod 755 myfile.exu. Remember also to
make exu executable by yourself and others.
On a Linux system, if your /tmp directory is not writable, or for other
reasons, you may need to run a non-compressed version of exu. You can get this
from the RDS download page, or by decompressing exu using UPX.
To make your life simple, you may wish to copy all files into cgi-bin that
your program will need. That includes the standard Euphoria files from
euphoria\include, the Euphoria interpreter, and any database files you are
going to access. That way you can avoid the sticky issue of the server process
not having the same environment variables (PATH, EUDIR) as you do, and not
being able to find your Euphoria files.
You can make a simple Web link to your CGI program, and run it by clicking the
link, but normally you will set up a Web page containing an HTML form. This
provides your users with a graphical user interface, where they can supply
information to your CGI program.
There are several places on the RapidEuphoria.com Web site where HTML forms
are used to communicate with CGI programs written in Euphoria. Perhaps the
simplest is the MicroEconomy form at: http://www.rapideuphoria.com/ecoform.htm
You can use Internet Explorer's View / Source to see the HTML code for this
If you page-down a few times, you'll see the start of a form:
<form method="POST" action="cgi-bin/economy.exu">
This creates a form for the user to fill out. When the user clicks the submit
button for the form, the CGI program, economy.exu, stored in cgi-bin, will be
executed on the server.
There are two possible "methods" that you can use. This form uses the "POST"
method. The other method is called the "GET" method.
With the POST method, the user's input data is supplied to the Euphoria
program as its standard input, and can be read with gets() and getc().
With the GET method, the data is supplied to the Euphoria program as an
environment variable called "query_string".
Which method is best? In most cases it doesn't matter which method you use, as
the input data will be the same. Only the method of acquiring that data will
In fact, if you look at the Euphoria program that handles this MicroEconomy
You'll see that procedure read_input() checks which method was used, and grabs
the input data from the appropriate source. Feel free to use read_input() in
your CGI programs.
The form collects data from the user in various ways. One of the simplest ways
is with text input tags such as:
<input type="text" name="name" size="35">
<input type="text" name="city" size="35">
which let the user type in his name and city into two separate boxes. The
values that he types are passed to the Euphoria program, and are labelled as
"name" and "city".
So what does the input data look like?
with the GET method the query_string environment variable (for the first two
fields) will look like:
and you'll be able to see it on the address bar of your Web browser, after a
If the POST method is used, the same string will be available via standard
You will have to parse this input to break out the two fields. The
MicroEconomy program uses parse_input() to do this. You might want to
incorporate parse_input() into your own programs.
Besides simple text boxes, there are many types of user input available in
HTML. You can have single line and multiple line input boxes, password boxes
(dots appear), drop down menus, radio buttons, check boxes, etc. Each attaches
a name to a piece of data supplied by the user, and your CGI program has to
break out this information using parse_input() or some equivalent code. You
can even let the user upload large files.
The Output from Your CGI Program
After examining the query string, your program must generate a reply for the
user. This reply must be in the form of a complete HTML page written to
standard output (Euphoria file 1). The very first line that your program
writes to standard output must be:
That line must then be followed by a bunch of lines that comprise a complete
HTML page. For example, the MicroEconomy program starts off by calling
procedure print_HTMLheader() which does:
puts(1, "Content-type: text/html\n\n")
puts(1, "<html><head><title>Thank You</title></head>\n")
puts(1, "<body bgcolor=\"#FFFFFF\">\n")
Much later, when it's all finished, it writes out the last line of output
which contains </body> </html> to complete the page. If the program fails to
complete the HTML page, the user's browser might not display the page
properly, if at all.
Debugging CGI programs
The first time you run a new CGI program, the chances are quite high that it
will fail in some way. You are likely to see an error page displayed that will
say very little about what went wrong.
The first thing you should do is check for a Euphoria ex.err file in cgi-bin.
If there's one there, it will tell you why your program died. If there is no
ex.err, it could be that your program didn't even run, because it's lacking
the correct permissions, or the shebang line is wrong; or it may have run but
it did not generate a proper HTML page. Be sure that you have the Content-type
line at the start, and you have the proper structure, starting with <html> and
ending with </html>.
If you aren't getting an ex.err, you can generate an ex.pro file, by saying
"with profile" at the start of your program. That will give you an idea of
what statements your program executed before it quit.
You can also try "with trace" and trace(3) to generate a file containing the
last 500 statements that were executed before it quit.
Once your program seems to be working, you might want to add a crash routine
that will send ex.err to you via e-mail. You may discover that your users are
trying to do weird things that you never do, and are encountering crashes.
Speeding up CGI programs
Most CGI programs require little CPU time, and most of that time might be in
the start up, i.e. loading the language interpreter and parsing the program. A
typical CGI program might read a few parameters that a user types into a form,
then access one record in a database, or send one e-mail message, before
displaying a simple HTML acknowledgement page for the user.
For CGI applications that do require a lot of time, you should translate your
Euphoria program to C, and compile it. The resulting executable file can be
used as a CGI program. It will start up faster (no parsing), and run faster.
The only problem is that you won't get a full ex.err file when there's a
crash, however you can use crash_routine() to send yourself an e-mail
containing some of the key variables, such as the query string that led to the