Path To Perl - Your Basic Guide to Running CGI Perl Scripts

This guide will help you upload and run a CGI script on your website. Ideal if you have your own website and starting to think about running some CGI Scripts but not sure where to start.

Before we start I have made a few assumptions about you and your computer we need to check out first. You will need to have your own website and have been uploading files to using FTP software onto it.

» Why do I need CGI scripts anyway?
» Download the test script and open it
» Finding the Path To Perl
» Finding your cgi-bin on the web server
» Upload the script to your website
» CHMOD script and file
» Running your scripts
» Common CGI script errors
» Difference between Path and URL
» Where to get help and find more scripts

Why do I need CGI scripts anyway?

CGI stands for 'Common Gateway Interface' and quite simply is a way of taking information from one location (like your website) and putting it into another (like your email) with some rules and tasks along the way.

A visitor arrives at your website puts some data into a form and the hits the submit button, the CGI Script will take that data and do what you have requested with it and then send the visitor where you want them to go.

The CGI script will be using Perl on your webserver. The CGI Script sends the requests to the Perl Software that does all the work.

So, your webpage has a request like a form or counter, it sends the data or request to your CGI Script that will use Perl Software to follow the instructions in the CGI Script.

[back to the top]

Download the test script and open it

Now download our test.zip file in WinZip format to your computer, unzip the script and put the file somewhere you can find it.

So you now have a file called test.cgi do not ever open this file using any software other than NotePad, to be sure that is NotePad not WordPad or Word and most definitely not FrontPage. On some UNIX servers your script must be in UNIX format, download a text editor like NOTEPAD++ and then save the script in UNIX format.

If you did accidentally open the file in something other than NotePad please delete the file and unzip it again.

What is the big issue with how you open the files? CGI scripts contain formatting that is invisible to you and me but necessary to run the script. Open it in the wrong software even if you don't change anything will cause the script to stop working.

Now using NotePad open the script, click [file] then [open] change the [files of types] to [all files] find and open the script.

» Download tester.zip

[back to the top]

Finding the Path To Perl

Now you need to change the first line of your script to find the Path to Perl, this is the software on your webserver that the script will be sending the information to.

Your hosting company will tell you what the Path To Perl is, the most common are listed below if you have UNIX hosting.

#!/usr/bin/perl
#!/usr/local/bin/perl
#!/usr/sbin/perl 
#!/usr/lib/perl

If you have Windows hosting then things can get a little tricky, most CGI scripts have been written for UNIX servers. Almost all web hosting is on a UNIX server. On many Windows hosting servers you don't need the Path To Perl at all and you can remove that line of the script, if you do find you need it then it will look something like this c:\perl\bin\perl.exe again your host will let you know what it is.

Okay, so you have changed the first line of the script and saved the file.

[back to the top]

Finding your cgi-bin on the web server

Using your FTP software connect to your website and now we can decide where to transfer the script to.

On most web hosting they will provide you with a cgi-bin to put your CGI Scripts into. On many servers you can not run a CGI script anywhere else but this location.

Each server is set-up in a different way and no two hosting packages are the same. Most however use a format that is similar.

You will find that your hosting is probably going to be one of three types.

1) You will have one directory called httpdocs or something like this for your web files and folders and another directory called cgi-bin for your scripts. In this type of hosting you normally must put all the CGI Scripts in the cgi-bin and cannot run scripts anywhere else. You also may not be allowed to put HTML files in the cgi-bin as it is not a public directory.

2) Or you have one directory with all the web folders and a cgi-bin directory in this folder, in this case you will be expected to run the CGI Scripts in the cgi-bin but may have permission to run them in other locations. You can normally see a HTML file in the cgi-bin with this example.

3) Finally you may just have a folder and nothing in it, in this type of hosting you can normally run the scripts anywhere you like and all folders are viewable using your browser.

However you hosting could be any combination of the examples used so check with your hosting company where you can put the CGI Scripts, if they don't have a help page or instructions for CGI Scripts ask them.

If you have a cgi-bin then this is where you need to transfer the CGI Scripts to, if you don't have one then to make life easier create a directory called cgi-bin on your server. It's worth checking with your hosting company on how they have set-up the rights to use CGI.

[back to the top]

Upload the script to your website

Your FTP software will have three ways to upload files ASCII, BINARY or AUTO. A good FTP software will know that you use ASCII mode to transfer any file that is .cgi or .pl

Always transfer the CGI Script using ASCII mode, check the settings of your FTP software to ensure this is how you are uploading the file.

Now transfer the script using ASCII mode in the same way you did your other files for your website.

[back to the top]

CHMOD script and file

CHMOD stands for 'Cold and Hot My Orange Dog' well actually it doesn't but like most computer talk it's irrelevant anyway.

CHMOD let's you change or modify the permissions that a file has. So that's as clear as mud then! Why has a file got a permission in the first place, and why do you need to change it?

Each file on the internet and your computer has 'permissions' set with it. Some files are 'read only' some files have permission to change other files. You don't want to let a file on your website change or delete other files unless you control the files they are changing or deleting.

As default all the files have a CHMOD of 644 letting anybody read the file. You now need to change your script to CHMOD 755 this will give permission to the script to run on your server and change other files.

On some servers where the cgi-bin is in a non-public location (so you can't type in the URL to see the files) you may need to CHMOD 777. You host can tell you if your server needs 755 or 777. As a general rule if you put a HTML file in the cgi-bin and you can see it, then you need 755.

With most FTP software you can simply right click on the file or push a CHMOD button and then select 755.

So, now CHMOD the test.cgi script 755. You should also check the cgi-bin is also CHMOD 755.

[back to the top]

Running your scripts

Now just type in the URL to the script and if everything has worked you will see the script running. This will tell you that you have got everything right and will show you the full Path to that directory and the URL.

If it did not work then explore the common errors below to find out what went wrong.

[back to the top]

Common CGI script errors

So it's not working then? In 99% of the time it's something very simple and easy to fix. Quick check list, make sure you did all of the following....

1) You only used NotePad to open the script
2) Have you got the Path To Perl right? Check with the hosting company
3) You know you can run CGI scripts from the location you put it in
4) The script was transferred using FTP and ASCII mode
5) The script and directory has CHMOD 755

Okay, let's look at some of the most common error and see how they are caused and what to do to fix them.

Error 404 File can not be found
The URL address you put in your browser is wrong. Check the web site address and the folder name, finally the script name. Remember this is case SenEsitIve. An occasional, if rare error, is if you have created a cgi-bin of your own in your web space however the server may ignore this and use it's own cgi-bin you have not got access to.

Error 500 Internal Server Error
The Path to Perl or CHMOD of your file or directory may be wrong. Try CHMOD all the files and directory again. Your server may not like the CHMOD setting ask you host what you should be using. Check you did not open the script with anything other than notepad. Check your log to find out more. Also try putting the code below directly after your Path to Perl this will stop and report the script error in more detail.

#!/usr/sbin/perl
use CGI::Carp qw(fatalsToBrowser);

Error Premature end of script headers
The CHMOD of your file or directory may be wrong. Try CHMOD all the files and directory again. Check you did not open the script with anything other than notepad.

Error The script just opens so I can see the code
Some servers do not like .pl try changing it to .cgi and some servers don't like .cgi so try .pl Remember to CHMOD the file again!

Error I keep uploading the file but get the same error
Some servers and FTP software can keep a copy of the file before the edit you have made, so delete the file on your server, disconnect from the internet, and restart your computer.

[back to the top]

Difference between Path and URL

Hopefully you got the script running okay and you can now see the test.cgi script results. This information is telling you the Path to the files in that directory and the URL of the files. Also the version of Perl running on your server.

First the Path To Perl is correct. You will need to change the first line of every script you run to the setting you used in this test script.

The path is like the path on your PC to a file, this is an example of a path on my PC C:\My Documents\pathtoperl.co.uk\cgi-bin\ and that is how the path would look on a windows computer, on a UNIX (most internet servers) it would look like this: /home/vhosts/youraccount/cgi-bin/file.txt

Now you know the path to the test.cgi script you can work out the path to other files. On many CGI Scripts you are required to input the Path to files on your server.

Next is more obvious the URL this is the location on the internet of the script. Again on many servers you are requested to input the URL.

[back to the top]

Where to get help and find more scripts

If you need more help with CGI Perl scripts the internet is full of places to find scripts and documentation. A good place to start is the CGI Resource Index or HotScripts where you can find both scripts and help files. If all this CGI has inspired you to try writing some of your own then make a start at CGI 101.

» CGI Resource Index
» Hot Scripts
» Java Script from Internet.com
» CGI 101

[back to the top]