San Diego State University
 Last updated: 9/12/00
Guide To CGI on ROHAN
 Page 2/3


How Do I Set Up a CGI Script on ROHAN?    [ table of contents ]

The steps needed to add a CGI script to your ROHAN-based web page are as follows:

  1. Find or create the script.
  2. Download the script to your PC or directly to your ROHAN account.
  3. Make any necessary changes to the script, such as variables and paths.
  4. Place the script into the proper directory and set permissions.
  5. Produce the HTML to interface with the script on your web page.
That's about all there is to it. If you already know how to upload files to your ROHAN account, you should have no problems setting up a CGI script. Read on for the step-by-step.



Where Can I Find Free CGI Scripts on the Web?    [ top | table of contents ]

There are many sites on the Web offering free CGI scripts and tutorials on writing your own. Yahoo's CGI listings are a good place to start. Matt's Script Archive is another well-known page with many free scripts. SDSU has a free hit-counter script here.

The file you download can be in several different formats. Typically CGI scripts have a .pl, .perl, or .cgi extension and are written in Perl. If the extension is .zip, .tgz, or .tar it is a compressed file and you will have to decompress it on ROHAN. More on this later. If a file has another extension or none at all, it may be a data file used by the main CGI script. Most CGI scripts are in plain-text format, so if you aren't sure try opening the file in your favorite text editor.

The majority of scripts that you will find on the web are written in the Perl language. Perl is relatively simple to learn, especially since many useful routines already exist for dealing with web forms and other CGI issues. If you are planning to use CGI extensively you should consider learning Perl. More on this later.



How do I Upload a CGI Script to ROHAN?    [ top | table of contents ]

If you downloaded s CGI script onto your PC's hard drive you will need to now upload it to ROHAN so that it can be accessed from the Web. ROHAN is configured to allow CGI Scripts anywhere within your public_html directory and it's subdirectories (as long as they have a .cgi extension). This makes your life easier since you can put your script anywhere you like. Some people create a subdirectory specifically to hold their CGIs. This directory is traditionally called cgi-bin. To create this directory with the proper permissions, type the following line at the rohan% prompt:



You can use any FTP program you like to transfer the CGI file from your PC to your public_html or cgi-bin directory on ROHAN. If you already have a web page on ROHAN you should be familiar with this procedure. Important: remember to set the transfer mode to ASCII when transferring plaintext .cgi or .pl files and to BINARY when transferring compressed .tgz, .tar, or .zip files. The ftp command to do this is:



How do I Configure a CGI Script to Run on ROHAN?    [ top | table of contents ]

Read the README that came with the script! If it didn't come with one, find one that did! If your script came without any documentation, it may be very difficult to know what needs to be modified to make it run on ROHAN. The documentation should tell you what, if anything, needs to be modified in the program. Often you will need to edit certain paths to other system programs like sendmail (/usr/lib/sendmail) or date (/bin/date) in your script. In addition, some scripts need you to specify where the script is being kept, and at what web address it can be located.

Keep in mind that the internal directory structure of ROHAN and the URL of your home page are not the same. For example, John's web page is stored under his home directory, at /home/john/public_html/, but to reach that page in your web browser you would type http://www-rohan.sdsu.edu/~john/. In other words, your public_html directory corresponds with your root web directory. Make sure you know which one your script needs.

Every Perl script begins with a line like #!/usr/bin/perl. This line tells the system where the Perl is located and is very important. On ROHAN, the first line of every Perl script must look exactly like that, and must be the only thing on the first line. If the script you downloaded points to something other than #!/usr/bin/perl you have to change it in order for the script to run.

Once your script has been modified and is in the directory where you want it, you must make it executable in order for it to run. To do this use the UNIX chmod command to change the permissions of the file. Change directories to the directory where the CGI script resides, and at the rohan% prompt, type:

This command makes file.cgi readable, writable, and executable by you, and readable and executable by anyone else. (The file must be readable, otherwise the system has no way to determine what the contents are.)

At this point your CGI should be ready to run! If you want to test it from the rohan% prompt before you try it out on the web, enter and it should run. (Replace file.cgi with the name of your script in these examples.) Note that the output may be pretty ugly since the script is expecting to output to a web browser and not the rohan% prompt. The important part is that it runs at all. If you get an error, check the common error codes section to diagnose the problem.



How do I Call My CGI Script from My Web Page?    [ top | table of contents ]

The way in which you interact with a CGI script from your web page depends largely on what the script does. If it produces an entire HTML document, for example a guestbook, then you can link to the script the same way you link to an HTML document:

If your script has simple output such as a counter, a date, or a string of text, it is probably meant to be included within an existing HTML page. The method for achieving this is called SSI, or Server-Side Includes. SSI is a method for parsing HTML documents on the server before they are served to the web browser, as opposed to merely sending the HTML as-is. SSI is a large topic in itself which could take up whole new guide, but for our purposes it is fairly simple.

In order to call a CGI script from within an HTML document on ROHAN, you must first rename the .html file to a .shtml extension (Server-parsed HTML). Renaming an index.html to index.shtml will not affect the way it is treated, it will remain the "home" file for that directory. All you need to worry about is updating any of your links to reflect the new filename. Once the page is renamed, add the follwing line in the HTML where you want the CGI's output to go: Remember to use the correct relative path to your file. For instance, if your CGI is located in public_html/cgi-bin and your HTML is located in public_html, you will need to call the CGI like this: Or, to be extra safe, you could specify the entire path: ...and that's it! Hit Shift-Reload on your browser and if everything is configured correctly, the CGI script should run every time you load the HTML page and output it's results to your web browser. If it doesn't work, don't give up, just click on the next section.



Why Doesn't My Script Work?



© 2000