QUICK START GUIDE FOR BEGINNERS TO PERL & CGI
What is Perl?
Here is a quick tutorial for individuals that are new to CGI and Perl.
Perl is a program that works with HTML, and enables your web site to function dynamically. Lets take Biz Mail Form for example. You first would configure your HTML form page as shown in the readme files. This form would reside on a page completely written in HTML. This form will contain an html "POST" statement, so when the submit button is clicked information is sent to the script defined in the "POST" action="" statement. In this example, it would be bizmail.cgi. Therefore on submission of the form, the Perl script is called, which will in turn process’s the information entered on the form. In addition, the Biz Mail Form script is configured to send the poster back to a HTML success page.
Note: ALL example Perl Code is colored red.
This tutorial is written in English so it is easy to understand and contains only the technical Jargon you will need to know to setup these scripts.
Firstly all Perl scripts need to start with the path to Perl which is usually:
#!/usr/bin/perl
The path to Perl always needs to be alone on the very first line of each Perl Script with no spaces or characters before the pound sign. This path defines where to find Perl on your server. Check with your host or systems administrator if you are unsure of what the correct path is.
Code in Perl is commented with a (#) pound sign. Commenting is used to make notes in scripts, so if you want to go back and edit a script you created a year ago, you will know what you where trying to accomplish. All commented parts of your script will not show up on your page, or run through the script. When you stop commenting you must hit the enter key and start a new line to start re-coding Perl.
Example:
# THE BELOW VARIABLE IS SET TO VALUE "will run" - #
#(THIS LINE AND THE ABOVE TWO LINES ARE COMMENTED #
#AND WILL NOT SHOW UP OR RUN) #
$variable = "will run";
The escape character in Perl is a (\) back slash.
This is most commonly used to escape characters that declare variables and arrays. When wanting to use a back slash as a regular character and not as code use a (\\) double back slash.
The back slash (\) escape character will be explained more in depth below.
Common problems
Firstly, the (@) sign in Perl represents the start of an Array, which is a list of data.
Here is the problem, since the (@) sign is Perl code, to use it as a regular character, you must use the escape back slash (\) character. So when entering your email address, it must look like this: you\@yourdomain.com
Additionally, when naming a Perl script, all scripts need a .cgi or .pl extension.
Example: script.cgi
For Windows servers that do not run fast cgi, you may need to use an ending file extension of .pl not .cgi.
So for the Biz Mail Form script you would need to rename (bizmail.cgi TO bizmail.pl), as well as all other files with the .cgi extension.
GOING FURTHER (Definitions)
Variables
A variable is comparable to an algebra equation like: X = 3 + 2, Where X would be a variable. In Perl all variables start with the ($) dollar sign.
An example variable would be: $ccto = "you\@yourdomain.com";
Therefore, anywhere in your script that contains $ccto would print you\@yourdomain.com which would convert into you@yourdomain.com, because as stated above, the (@) sign needs to be escaped.
In addition since the ($) dollar sign starts a variable, anything with a ($) dollar sign will be treated as a variable. Therefore, if you want to use a ($) dollar sign as a regular character you must use the escape character before it. Example: \$
Breaking the variable statement down.
1. Declare that you are writing a variable by starting your statement on its own line with the ($) dollar sign.
2. Name the variable. (Variables can be named with: numbers, letters, and underscores.)
Example: $somevariable
3. Set the Variable after the (=) equal sign to the value wanted. This value should be surrounded by (") double quotes and a (;) semi-colon should follow the second (") to end the statement and line.
4. Complete Example: $somevariable = "value";
Other Possible Problems...
Notice each variable is surrounded by two (") double quotes. So what’s the problem? The problem is if you want to include a (") double quote in the value of the variable statement. If you only place a (") double quote, then Perl will think you are trying to end the statement resulting in a "500 Internal Server Error".
The Solution
Remember the (\) back slash escape character. Therefore, when using a (") double quote as part of the variable value, you must escape it: \"
Technical Fact: The above variable in Perl is called a Scalar Variable.
Arrays
An Array is a list of values that can be used latter in the script. We are only going to go over writting an array, not how to retrieve the values from it, since you will need to know how to add values to an array to setup this script.
Sample Arrays:
@somearray = ("value1", "value2");
-or-
@something = ("value1", "value2", "value3");
-or-
@vals = ("value1", "value2", "value3", "value4");
-or-
@okurls = ("http://www.yourdomain.com/", "http://yourdomain.com/", "http://234.322.345.343");
Breaking the Array Statement Down
1. Declare that you are writing an array by starting your statement on its own line with the (@) sign.
2. Name the array. (Arrays can be named with: numbers, letters, and underscores.)
Example: @somearray
3. Set the array equal to a list of values.
4. List array values. The values should start with a (() left bracket followed by all values surround each with a (") double quote and separated each with a coma then space then repeat for each value. Note that on the final variable there should be no characters or spaces after the final (") double quote just the ending );
Example: ("value1", "value2");
5. Complete Array Example: @somearray = ("value1", "value2");
Also note that the end of a declaration statement for any array or variable is the ;
Other Stuff you need to know after you have a complete CGI / Perl Script
Great we have a complete CGI / Perl script, that is fully configured the way I want it... NOW WHAT? Good Question. The first thing you must do is FTP the script onto your server or web space. You must FTP Perl Scripts to your server, online upload pages will not work in almost all cases. The most commonly used FTP client is CUTE FTP. Ok so I have my FTP client and I am logged into FTP with the site I want to run my Perl script, now what? Well Perl scripts as stated in the beginning of this resource are different than HTML pages, although they contain HTML. Now you must upload and CHMOD your script.
How To upload and CHMOD.
1. You must upload your Perl Scripts to your cgi-bin. (With few exceptions but this would depend on your servers configuration).
2. Once uploaded you must set file permissions or CHMOD all scripts to 755, 766, 777. However 755 is the most common to set to AND IS WHAT I RECOMEND YOU TO USE UNLESS YOU HAVE A SPECIFIC REASON. ALSO 777 is generally not a good choice since this creates MAJOR security flaws and gives visitors the ability to write to your Perl script. So if they can find other flaws in your server they could possibly hack your script and/or server. Some people use other permissions but these are the most popular.
What does CHMOD mean?? CHMOD stands for Change Mode which is also referred to as file permissions.
To CHMOD files in Cute FTP simply right click on the file you want to CHMOD, Then left click on CHMOD.. This will pop a "Change File Attributes" box. In the text box to the right of "Manual" Erase the existing number and replace it with number you want to set permissions to. Then click "OK". That's it, follow the same process for each file you want CHMOD.
Setting file permissions on Windows servers can be different, so you may need to contact your host or System Administrator for help.
............................................................................................
File Permissions or CHMOD REFERENCE:
CHMOD 777=
Owner: read, write, execute.
Group: read, write, execute.
World: read, write, execute.
CHMOD 766=
Owner: read, write, execute.
Group: read, write, ---
World: read, write, ---
CHMOD 755=
Owner: read, write, execute.
Group: read, --- , execute.
World: read, --- , execute.
............................................................................................