CGI Beta Docs/Help, v.1.1

If you're here, it's for one of three reasons:

1. You want to learn more about putting CGI/Perl scripts on Tripod.
2. You don't know how to write CGI/Perl scripts and you want to learn.
3. You want to find out where to get freely-available CGI/Perl scripts to use on Tripod.

Scroll down and we'll help you out with each of these.

Putting CGI/Perl scripts on Tripod

Contents:
1. Introduction to the Service
2. Putting up your Scripts
3. Using Modules
4. Limitations
5. Debugging
6. Examples

Introduction to the Service

Tripod's new cgi-bin service lets you put Perl scripts into your Tripod directory, where they can be executed to do all sorts of things. Many of the scripts that you use will probably be CGI scripts, which basically means scripts that can receive information from a form on a page, and have the script do whatever you tell it to do with the information.

With Perl scripts, you can:

* Create a message board
* Allow other people to add information to your pages
* Put a customized quiz or poll on your site
* Write a game
* Set and read cookies
* And more!

Many of Tripod's own services - the Homepage Mover, even the old Homepager- are written entirely in Perl. That should give you some indication of how powerful the language is, particularly for writing applications for the Web. Who knows - maybe you'll create the next big thing that turns the Web upside down (if you do, don't forget us)!

Putting up your Scripts

There are three different ways that you can put scripts into your directory on Tripod: Script Editor, Filemanager, and FTP.

The Script Editor is Tripod's tool for composing and editing scripts from within your Web browser. Script Editor is a good choice if you want to write scripts from scratch and save them directly to Tripod. It's also a good place to make quick changes to scripts you've already put up on Tripod, but that still need some tweaks.

Tripod's Filemanager will let you upload scripts from your hard drive to your Tripod directory, just as it lets you upload HTML, images, and other files. You'll want to use the Filemanager if you write your own scripts offline, or if you have copied scripts from another site to your hard drive and now want to put them on Tripod with an easy-to-use method for uploading files.

FTP will also let you upload scripts from your hard drive to your Tripod directory. FTP requires that you have an FTP client, like CuteFTP (for Windows) or Fetch (for Macintosh). People who have scripts on their hard drive may find FTP to be a more convenient way to transfer files than Filemanager if they have a slow connection, if they are transferring large numbers of files, or are just familiar and comfortable with their FTP client.

You will find that you have a special subdirectory in your directory called cgi-bin. The cgi-bin directory is the only place within your directory where scripts will run, so be sure that all the scripts that you put on Tripod are put into this area (or into one of its subdirectories). Scripts that are put into other parts of your directory will just be displayed as code on the screen when they are accessed.

You should also want to make sure that all scripts you put up have either a .pl or .cgi extension on the end. This is how the server knows that the script should get executed, instead of simply being displayed on the screen. So if, for example, you have received a script from somebody and that script is named superscript, be sure to rename it as superscript.cgi or superscript.pl when you put it on Tripod. Filemanager has a handy Rename function for doing this, and most FTP clients will let you do this, too.

Note that Windows systems can be tricky about the way they name files. The problem is that the little title that you see underneath a Windows file isn't necessarily the same as the name the program gives to the file internally. Many people run into problems when they create a file under Notepad or Wordpad, and the file gets saved as a text file; Windows forces a .txt extension onto your file, but you can't see it. If you run into this problem, try renaming the file in Filemanager or through your FTP client.

Once you've put up your CGI script, you can access it through any of these URLs:

http://your_member_name.tripod.com/cgi-bin/your_script_name http://members.tripod.com/your_member_name/cgi-bin/your_script_name http://beta.tripod.com/your_member_name/cgi-bin/your_script_name

Perl scripts all begin with a header that looks something like:

  #!/usr/local/bin/perl

Don't worry about what your particular header says - it doesn't matter, because we ignore it! You don't have to specify where Perl is located because our servers already know and fill in this information for you.

Also, if you have done scripting in a Unix environment before, you are probably used to needing to set permissions on scripts (using the 'chmod' command) before they will execute. This is not necessary when using the Tripod CGI service, and in fact it isn't possible. Our servers assume that all scripts ending in .pl or .cgi and residing in your cgi-bin directory are executable.

Some people have asked what the root directory for the scripts is. It's actually your cgi-bin directory itself - so if you need to fill in a root or base directory for one of your scripts, that directory will be '/' (assuming that the script is in the cgi-bin itself).

Using Modules

One great thing about Perl is that it allows you to use modules to encapsulate commonly-used functions. Tripod's cgi-bin fully supports modules - just put them into your cgi-bin directory, and your scripts will find them. Additionally, we provide you with a couple of special Tripod modules pre-required into your scripts, so that you can start using them with a minimum of fuss. To find out more about modules, take a look in the new Modules subdirectory in your cgi-bin - there's a readme.html file that can tell you more.

Limitations

The most important limitation to bear in mind is that only pure Perl scripts will work. You can't run shell scripts, or C/C++ code, or anything else. You also can't embed non-Perl commands in your Perl by using system or exec or the like - those commands will be ignored, and any portion of the rest of your script that relies on them will break.

Another limitation is that forms which post to cgi scripts need to either use METHOD="GET", like this:

  <FORM ACTION="script.cgi" METHOD="GET">

Or, alternately, they need to specify the beta.tripod.com server as the ACTION of the form, like this:

  <FORM ACTION="http://beta.tripod.com/your_member_name/script.cgi" METHOD="POST">

We hope to change this limitation soon.

There are also certain Perl commands which we've disabled for security reasons. This is to prevent people from doing malicious things, like trying to read your private directories. Most of these commands are very rarely used by people who are doing programming for their Web sites, but there are a few more common ones that you might want to know about. These are:
  system
  exec
  fork
  chown
  chmod
  sleep
  unlink
  kill
  eval
  all commands involving sockets
Currently, this means that there is no mail program available for you to use. We recognize that this is a serious limitation, and hope to offer some mail system soon. We don't offer one currently because it is certain that it would be abused by spammers, but we are working on a system that would work for normal mail but not for spam-mail. We will let you know if such a system becomes available.

We've also limited how many system resources are available to each script. For example, a script can only use up to one second of CPU time before it is deemed to be causing problems and is terminated. This makes sure that people don't accidentally - or purposefully - write scripts which run endlessly and eat up all of the server's resources, making it so that nobody else's scripts work. It's unlikely that you will run into system resource constraints unless you are running a script which requires an exceptional amount of processing time or memory in order to do its thing.

One other detail: While you can choose to make the cgi-bin directory and its subdirectories private from within Filemanager, if you create new subdirectories from within one of your scripts, these will not be automatically private. So if you need to keep your data private, be sure to make the subdirectory private in File Manager beforehand - then your script can safely output data there.

We've recently discovered that the old Homepage Builder does not deal with the cgi-bin directory. This effectively removes WebTV users from the beta test, because WebTV users can only access files through the old Homepage Builder. We are sorry for the oversight, and will work to correct the problem.

Debugging

Debugging scripts works a little differently on Tripod compared to how it works on some services. If your script has a fatal error in its execution, it will output the error message in a Web page which will then be displayed within your browser window. If you want to make sure that one of your error messages is displayed in this way, you should use Perl's "die" function, like this:
  die("<B>This is my error message, in bold.</B>\n");
You may also find it useful to print information out to STDERR when debugging your scripts. If you redirect STDERR to a file at the beginning of your script, you can make sure that all of the messages you print to STDERR will get collected for you to look at later. Make sure to put that redirect in a BEGIN block; this makes sure that the redirection occurs before any run-time errors are produced. Redirecting STDERR in a BEGIN block would look like this:
  #!/usr/local/bin/perl

  BEGIN {
	open (STDERR, '>> my_error_file.txt');
  }
This will cause the script to tack any error output to the end of my_error_file.txt.

Learning About CGI/Perl

While we aren't experts on teaching people about CGI or Perl, there are lots of people out there who are. What's more, many of them won't charge you a penny for their help.

Start out with Webmonkey's articles on the subject:

http://www.hotwired.com/webmonkey/backend/backend_more.html#cgi

In particular, we recommend the "Intro to CGI" and "CGI Scripts for Fun and Profit" articles, as well as "Give the Gift of CGI" articles. The "Perl Scripts for Beginners" article is also good, although it's probably a little more advanced than its title would suggest.

If that's not enough information for you, try these directories of information:

On Lycos:
http://dir.lycos.com/Computers/Programming/Internet/CGI/
http://dir.lycos.com/Computers/Programming/Languages/Perl/
On Tripod:
http://www.tripod.com/explore/computers_internet/Programming/CGI/
http://www.tripod.com/explore/computers_internet/Programming/Perl/
On HotBot:
http://directory.hotbot.com/Computers/Programming/Internet/CGI/&MT=cgi&BT=H
http://directory.hotbot.com/Computers/Programming/Languages/Perl/WWW/

Finally, while it's cool to get by with free information online, sometimes nothing beats a good book - especially if you plan on writing a lot of your own scripts. Here at Tripod, we rely almost exclusively on O'Reilly Books for our Perl programming needs. Four excellent books from O'Reilly are (in order of difficulty):
Learning Perl: http://shop.barnesandnoble.com/booksearch/isbnInquiry.asp?srefer=&isbn=1565922840
Perl in a Nutshell: http://shop.barnesandnoble.com/booksearch/isbnInquiry.asp?srefer=&isbn=1565922867
Programming Perl: http://shop.barnesandnoble.com/booksearch/isbnInquiry.asp?srefer=&isbn=1565921496
Perl Cookbook: http://shop.barnesandnoble.com/booksearch/isbnInquiry.asp?srefer=&isbn=1565922433

Finding Free Scripts to Use

There are hundreds, if not thousands, of sites out there that offer free scripts. Rather than trying to list them individually, we'll just mention the same directories we mentioned above, which contain lots of free script sites as well as help sites.

On Lycos:
http://dir.lycos.com/Computers/Programming/Internet/CGI/
http://dir.lycos.com/Computers/Programming/Languages/Perl/
On Tripod:
http://www.tripod.com/explore/computers_internet/Programming/CGI/
http://www.tripod.com/explore/computers_internet/Programming/Perl/
On HotBot:
http://directory.hotbot.com/Computers/Programming/Internet/CGI/&MT=cgi&BT=H
http://directory.hotbot.com/Computers/Programming/Languages/Perl/WWW/

Most scripts that you find out there will run just fine on Tripod, with no modifications. However, if you run into problems, check out the Putting up your Scripts and Limitations sections above. You might find that you need to modify your script slightly to make it work on Tripod - or you may occasionally find that the script doesn't work at all, because it uses an insecure function call, sockets, or the like. These problems should be few and far between, but they can happen. In this situation, your best bet is probably to look around for some other script that serves a similar function and see if it avoids the problem posed by the previous script.
Make your own free website on Tripod.com