If you have an executable file which only requires data to be piped through it, try the automatic cgi tool which has been developed.

HTML (HyperText Markup Language) is the document style for files which are transmitted over the WWW. Those who have developed personal home pages are already familiar with this language. Within the HTML format, a form may be included which allows browsers to input information. The underlying idea behind GASP is that users should be able to enter data into such a form and have the results of a statistical procedure ran on this data returned to their browser screen.

When a dataset entered into a form is submitted for analysis, it is piped through an executable file (generated by, for instance, a FORTRAN or C program) containing the statistical procedure of interest by means of a CGI (Common Gateway Interface) program. The results from the statistical procedure are returned to the CGI program which then relays the results to the user's browser in HTML format.

Some questions to answer before you get started

Can I include my routine on the GASP initiative?

First things first. You can include routines written in a variety of programming languages like FORTRAN and C as well as applications like Matlab, Maple, and XLispStat. We are still working on Splus, but we are not quite there yet (if you get an Splus routine to work please let us know). If you are working with something else, you must proceed at your own risk. Why not go ahead and give it a try though.

We will include a link to your routine on the GASP homepage as long as you place a link back to GASP. We are willing to include all types of routines from the simple to the complex. Eventually, we will probably divide the routines up into something like basic and research procedures. For now, all you have to do is get your procedure ready and let us know about it.

Do you have access to a WWW server?

If you don't have access to a WWW server then you have no place to put your procedure so that people can access it on the WWW. You can start your own server if you wish. I reccomend the new Apache server. This entails some work but the README file you obtain when downloading the server should provide good documentation.

If you already have a WWW server running in your department, then you need to find out who is responsible for it. You can frequently find this information on the home page which the server provides. You will need to interact with the server administrator because this person may be the only person with write access to certain directories where you need to put stuff (like the cgi-bin for instance). The server administrator may also help you answer the next question.

Is it okay to run processes on the machine which is running the server?

Your procedure will typically run on the same machine which runs the server. For example all procedures made available in our department will run on my Sparc 20. If teh person who owns the machine running the server doesn't appreciate the extra load, you may have a problem. You may use the nice feature in the UNIX environment so that you can run your procedure at a low machine priorty which will not slow the machine owner down. If this turns into a big problem wou might consider starting your own Apache server.

Do you have the necessary software (PERL) ?

The rest of this tutorial will discuss how to implement your procedure using a cgi script written in PERL. You need to where PERL is at on your system. On a UNIX system rty typing which perl at the command line. Make note of this pathway because you will need it later. If you don't have PERL on your system, you can use other languages such as C++, but this tutorial won't be of any help to you then. So if you don't want to work on your own, get PERL. I think it is easier to work with anyway.

The best way to proceed

Once you have answered all of the above questions in the affirmative, you can get down to the nuts and bolts of interfacing your procedure with the WWW.

The rest of the tutorial consists of two main parts; the development of a form within an HTML file and the development of a CGI (Common Gateway Interface) program which takes data entered into such a form and runs a statistical procedure.

The steps that I will discuss here are the exact same as those that I went through to get the change-point procedure up and running on our UNIX system.

Developing a form within an HTML document

Simply cut and paste the following commands within your HTML file.

<FORM METHOD=POST ACTION=http://www.stat.sc.edu/cgi-bin/simple.cgi/ >
Enter your data: <INPUT NAME=data >
<INPUT TYPE=submit VALUE=Test this form >
</FORM >

Try opening the file from your favorite WWW browser. Congratulations, you just included your first form. Now try typing some numbers into the either the above form or your form and clicking on Test this form. What happens? More on the return later.

Let's break down exactly what's going on in the above example form line by line. The first statement in a form always has the basic form of

<FORM METHOD=? ACTION=? >

You have to define values for METHOD and ACTION. METHOD can only take on two possible values, GET or POST. For our purposes, always set METHOD=POST. ACTION should be set equal to the location of the cgi program to which the data is to be sent. In other words, this is the action which is to be taken on the entered data. In the above example, ACTION=http://www.stat.sc.edu/cgi-bin/simple.cgi/. This takes the data entered and submits it to the simple.cgi program which is located in the cgi-bin on our Department of Statistics WWW server here at the University of South Carolina. Once you have written your own cgi program you will want to change http://www.stat.sc.edu/cgi-bin/simple.cgi/ to something like /cgi-bin/file.cgi.

The next line of the example form places the text "Enter your data:" next to a standard type input box. The NAME=data statement within the INPUT statement gives the information which is entered into the box the name data. You probably don't want to change this name just yet.

The standard input region has twenty visible characters although one can input as much information as they like. The region simply scrolls to the right as more data is input. If you want to allow for a larger visible region for data to be entered, you can add a SIZE definition within the INPUT statement. For example, the following syntax:

<FORM METHOD=POST ACTION=/cgi-bin/simple.cgi/ >
Enter your data: <INPUT NAME=data size=50>
<INPUT TYPE=submit VALUE=Test this form >
</FORM >

produces the form below with 50 characters of input space.

The following syntax generates the above form. The basic structure of these statements is similar to the simple forms previously discussed.

<FORM METHOD=POST ACTION=/cgi-bin/simple.cgi/>
Enter your data:
<TEXTAREA name="data" cols=50 rows=10>
</TEXTAREA>
<br>
<INPUT TYPE=submit Value =Test this form>
<INPUT TYPE=reset Value=Clear>
</FORM>

One noticeable difference is that now the input area is defined by the TEXTAREA statement. This statement works like the standard input box discussed previously only the TEXTAREA command allows one to set the number character spaces to allow for within the visible input area. Another difference between the above form and the simpler forms is that another type of INPUT command is used. The INPUT command with TYPE=reset clears the form of any information which has been entered. Try entering and clearing the information in the textarea form.

You should note that multiple input areas can be included within the same FORM statement.

What happens when a form is submitted?

Developing a CGI program with PERL