One of the easiest ways to program with Perl is to use someone else's library. A library is a collection of subroutines. A subroutine is a little section or snippet of code or a mini program that does a specific task.

Subroutines are great for handling simple common tasks that you might need to do more than once in your script. For example, if you know that you're going to read data from a file several times in your script, instead of having basically the same code in several different places in your script, you can create one subroutine and use it each time you need to read information from a file.

As I mentioned before, a library is a collection of subroutines, but the great part is that it's a collection of subroutines already written by someone else! You don't have to know and understand exactly what they do and how they do it to use them. All you need to know is how to use them. I don't know exactly how my laptop works, but I know how to turn it on and use it!

Now let's get started...

First let's learn how to write a Perl script that will take a user's e-mail address from an HTML form and write that address to a mailing list file. I'll only include the most basic elements needed to do the job. In future tutorials, I'll build upon and improve this basic script.

I'll list the script first and then include a line-by-line explanation.

By the way, this tutorial is geared towards programming in a Unix environment with an Apache web server.

Here's the script:
--------------------------------------------------
#!/usr/bin/perl

# Full path to your mailing list file
$mail_list = '/usr/www/yourserver/mail_list.txt';

# URL to a "Thank You" page to send the user to after they
# submit the form
$thank_you = "http://www.yourserver.com/thankyou.html";

##################
# Actual script starts here

require "subs.pl";

# Parse the data from the input form
&p;

# Add the e-mail address to the list
&op_ap($mail_list, $FM{email}, e2, op_ap);

# Print the "Thank You" page
&pr_lc($thank_you, e2, pr_lc);

exit;
--------------------------------------------------

Now let's take a look at what each line does:

#!/usr/bin/perl -

Is the path to Perl on your server. If a script doesn't work right, this is one of the first places to look for problems.

You can find the path to perl for your server by typing "whereis perl" from a telnet prompt if you have telnet access to your server. Otherwise, if you don't know the path, you'll need to contact your host support to find out.

# Full path to your mailing list file -

This line is a comment. All comment lines begin with the pound sign '#'. This line is a comment describing the line below it.

$mail_list = '/usr/www/yourserver/mail_list.txt'; -

This line sets the variable, '$mail_list', to hold the value of the path to your mailing list file. You would need to change the path to match the actual path to the file on your server. Be careful to leave all punctuation exactly as you see it!

(For those of you who might be asking "What's a variable?", here's an explanation. If you have information that you want to use in several places in your script, like the path to your mailing list, instead of typing the whole thing several times, you can assign a placeholder with a shorter name to hold or equal the value of the path.)

They're called variables because although the name of the variable stays the same, you can change the value, the information stored in the variable, anywhere in the script. This type of variable is called a scalar variable. They can hold numbers, strings (letters), or references. They begin with a dollar sign followed by one or more letters, numbers or underscores.) Although we don't use the variables in this script more than once, it's a good idea to learn how to start using them.

# URL to a "Thank You" page to send the user to after they # submit the form -

These lines are more comments describing the line below them.

$thank_you = "http://www.yourserver.com/thankyou.html"; -

This line sets the variable '$thank_you' to equal the path to an HTML thank you page you would like users to see after they subscribe to your mailing list.

##################
# Actual script starts here -

Just another comment line.

require "subs.pl"; -

This line makes the script require the library of subroutines. All the subroutines are contained in the file named 'subs.pl'. This line allows this script to use the subroutines without actually having to include them in the script. The 'subs.pl' file must be in the same directory that you put the script in. (I'll let you know at the end of my article how to obtain the 'subs.pl' file.)

# Parse the data from the input form -

Another commenting letting you know what the next line does...you can never have too many comments!

&p; -

This line is where we actually start using the subroutines I've been talking about. This line calls or runs the subroutine named 'p'. Note perl is case sensitive. This means that '&p;' and '&P;' are NOT the same thing. Also $mail_list and $Mail_List are entirely different variables.

# Add the e-mail address to the list -

Yep...another comment.

&op_ap($mail_list, $FM{email}, e2, op_ap); -

This line calls the subroutine 'op_ap' which stands for open_append. We want to open your mailing list file and append the user's e-mail address to it. This time we need to send the subroutine some information to work with.

As I said earlier, the great thing is that you don't need to understand how the subroutine works, you just need to know which information it needs and what order to send it in. If the subroutine is sent the right info in the correct order, it knows what to do with it. The information or data is sent in the parenthesis ($mail_list, $FM{email}, e2, op_ap).

The first part '$mail_list' is the variable which contains the path to your mailing list file. This tells the subroutine which file to open and append.

The second part is another special variable which holds the e-mail address of the user. This variable was created by the subroutine 'p' which we called earlier. This line assumes that there is a text box in your submittal form named 'email' for users to enter their e-mail address in. If your form used a different name like 'address' for this field, you would use '$FM{address}' in place of '$FM{email}'. (Remember - $fm{email} is NOT the same as $FM{email}!).

The next part 'e2' is the name of another subroutine, it's an error subroutine that returns an error message if the script runs into any problems. I'll explain more about the error subroutines in future tutorials.

The last part 'op_ap' is just the name of the subroutine that you're calling. This is also used in error reporting to help track down where the error is at.

# Print the "Thank You" page -

The last comment line!

&pr_lc($thank_you, e2, pr_lc); -

Here we call another subroutine. Yep, you guessed it, it stands for 'print_location'. Again, we send it some information to work with. '$thank_you' tells it the URL to print, 'e2' is the name of the error subroutine to use if it needs to and 'pr_lc' is just the name of the sub.

exit; -

We're done with the script so we just tell it to 'exit'!

__________

That's it! That's the entire script!

Enjoy!

Troy McKenna

To download a copy of the "subs.pl" file, click here.  Remember, both the script above and the "subs.pl" file should be in the same directory and should be chmoded 0755 or rwx-rx-rx and your mailing list file should be chmoded 0777 or rwx-rwx-rwx.