Introduction

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.

Web Hosts

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 each month.

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 headed down.

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.

#!./exu

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, not \r\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.

HTML Forms

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 page.

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 be different.

In fact, if you look at the Euphoria program that handles this MicroEconomy form: http://www.rapideuphoria.com/economy.txt

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:

"name=John&city=Miami"

and you'll be able to see it on the address bar of your Web browser, after a '?' character.

If the POST method is used, the same string will be available via standard input.

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:

Content-type: text/html

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")

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 crash.