Tenon Intersystems Please see text links at bottom of page for navigation Please see text links at bottom of page for navigation
Please see text links at bottom of page for navigation Please see text links at bottom of page for navigation Please see text links at bottom for navigation
Please see text links at bottom of page for navigation
Search this site:

Running Perl Scripts Under iTools

Perl scripts are text files containing Perl language statements that generate a stream of text characters when executed. There are Perl statements for assigning integer and string values to variables, statements for prescribing conditional flow through the script, and statements for running other programs. Very sophisticated CGIs can be created by combining different Perl statements. A number of widely available books describing Perl programming are available. "Programming Perl", Third Edition by Larry Wall, Tom Christiansen and Randal L. Schwartz, with Stephen Potter. 2000, O'Reilly & Associates

Perl Shell CGIs are fast and easy to develop

Perl is used for medium-performance, easy-to-develop CGIs. Each Perl program is text. The scripts are interpreted by a Perl interpreter controlled by iTools. Since the interpreter interprets each Perl statement, Perl scripts can consume a lot of memory and use a large number of processing cycles.

Configuring iTools to permit CGIs

In order to run Perl scripts under iTools you will have to add an Apache Handler for executing CGI scripts. You can do this using the iTools Admin.

iTools Admin -> WebSettings -> MIME Settings -> Handlers
In the Handler Name field type:
In the Associated Extensions field type:
    .cgi .pl
Now click "Save".

This will allow files with the .cgi or .pl file extensions to be handled correctly.

For security purposes, you may wish to allow CGI and Perl scripts to reside only in the CGI-Executables folder. This folder is not directly accessible to the end user for uploading scripts. Only a privileged administrator will be allowed to place any scripts in this folder. The location of the folder is: /Library/Tenon/WebServer/CGI-Executables.

If you wish to allow a user to have control over his own scripts, you will need to configure Apache to permit CGI execution of scripts residing in the user's virtual host directory (their DocumentRoot). Under iTools this is simply a matter of selecting the directory where their CGI script lives and toggling on the Execute CGI button.

iTools Admin -> WebSettings -> Access Control
    Browse until the proper directory is visible and click Select
    Check the Execute CGI button on the lower left and click "Save"

Normally your clients will not be able to execute cgi scripts in their virtual host directory unless you authorize it by checking this box. Otherwise, all cgi scripts need to be located in /Library/Tenon/WebServer/CGI-Executables.

If you use Access Control to give a particular web site permission to run CGIs, your Perl file, e.g. mycgi.pl, can be stored directly in that web site directory (/Library/Tenon/WebServer/WebSites/your_web_site.com/cgi-bin). The new CGI can be referenced from a browser with the following URL:

If the Perl script is stored in the CGI-Executables directory, the URL would be:

Writing a CGI program

All of the output from your CGI program must be preceded by a MIME-type header. This is an HTTP header that tells the client what kind of content it is receiving. For example:
      Content-type: text/html

Your output needs to be in HTML, or some other format that a browser will be able to display.

Other than these two restrictions, a CGI program will look like any other program that you might write.

A Perl CGI is a text file that contains commands for the Perl language interpreter.

You can use BBEdit or any editor of your choosing to create a Perl CGI. Perl CGIs are given the suffix ".pl" (e.g., mycgi.pl).

Required Shell Script Content

In addition to creating the text file, there are a few important considerations with respect to the content of the file. First, the top line of the file must contain the text:
This tells iTools that this is a Perl script and that Perl should be used to process the remainder of the file.

Second, you can use Perl print statements to generate text which will be returned to the browser that initiated the URL. The first print command must contain an HTTP header. This header indicates what format or kind of data will be output by the remainder of the print commands. The choices are usually plain text or text that is marked up using the HTML. This first print command puts iTools and the browser in the proper mode to accept everything else.

For Perl scripts that output plain text, use:
    print "Content-type: text/plain \n\n";
For Perl scripts that output HTML statements, use:
    print "Content-type: text/html \n\n";
The print indicates that text/plain or text/html will follow. After that, any text generated with a print command is sent to the originating browser as a response to the URL request.

Printenv.pl Example

Here's an example Perl CGI (printenv.pl). The first few lines of the file establish the mandatory #!/Library/Tenon/Perl/Executables/perl and print Content-type: text/plain requirements for any Perl script. The remaining two Perl statements output a dozen or more lines that contain the values of a family of environment variables. The following is the content of the printenv.pl CGI:


    print "Content-type: text/plain; charset=iso-8859-1\n\n";>
    foreach $var (sort(keys(%ENV))) {>
    $val = $ENV{$var};>
    $val =~ s|\n|\\n|g;>
    $val =~ s|"|\\"|g;>
    print "${var}=\"${val}\"\n";>

When the printenv.pl CGI is referenced by a URL, it produces output similar to this:
    HTTP_USER_AGENT="Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv: Gecko/20081217 Firefox/"
    SERVER_SOFTWARE="Apache/2.2.13 (iTools 9.0.5/Mac OS X) mod_ssl/2.2.13 OpenSSL/0.9.7l DAV/2 mod_fastcgi/2.4.6"


There are four basic things that you may see in your browser when you try to access your CGI program from the web:
  • The output of your CGI program: This means that everything is working correctly!

  • The source code of your CGI program or a "POST Method Not Allowed" message. This means that you have not properly configured iTools Apache to process your CGI program.

  • A message starting with "Forbidden". This means that there is a permissions problem.

  • A message saying "Internal Server Error": If you check the iTools Apache error log (/Library/Tenon/WebServer/Logs/error_log), you will probably find that it says "premature end of script headers:, possible with an error message generated by your CGI program. Something is preventing your CGI program from generating the proper HTTP headers.

File Permissions

Please make sure that any CGI script has permissions to allow "Execute".
-rwxr-xr-x 1 root www 311 Jun 4 09:22 printenv.pl

Program Errors

Make sure your program runs from the command line before testing it via the web server.

For example:

| Tenon Home | Products | Order | Contact Us | About Tenon | Register | Tech Support | Resources | Press Room | Mailing Lists |

Powered By iTools

Copyright©2010 Tenon Intersystems, 232 Anacapa Street, Suite 2A, Santa Barbara, CA 93101. All rights reserved.
Questions about our website - Contact: webmaster@tenon.com.

Tenon Home Tenon Home Tenon Home Tenon HomeProduct Info TenonOrderingContactAboutRegisterSupportResourcesPressMailing Lists