| ActivePerl User Guide |

# Web Programming (CGI and PerlIS)

- NAME
- DESCRIPTION
  - What is HTTP, and how do I get more information on it?
  - What is CGI, and how do I get more information on it?
  - How do I return a graphics file from a CGI script?
  - My CGI scripts don't seem to run right under PerlIS.
  - How does my script know if it's running under ActivePerl or
  - What CGI modules run with ActivePerl?
  - How do I use redirection in my script?
  - What are cookies and how do I use them?
  - How do I get the e-mail address of the user?
  - I need a CGI script to do a certain task. Has anyone done it before?
  - How do I test my CGI programs that take arguments without running
  - The Content-Type: header field I output from my CGI script shows up
  - When I try to run a CGI script from my browser, it tries to
- AUTHOR AND COPYRIGHT

## NAME

ActivePerl-faq7 - Web Programming (CGI and PerlIS)

## DESCRIPTION

Web development with ActivePerl

## What is HTTP, and how do I get more information on it?

HTTP (HyperText Transfer Protocol) is the protocol that web browsers use to talk to web servers. The official specification for the HTTP standard is available on the W3 Consortium web server at:

        http://www.w3.org/pub/WWW/Protocols/

Some more readable introductions can be found on the Yahoo HTTP page at:

        http://www.yahoo.com/Computers_and_Internet/Internet/World_Wide_Web/HTTP/

## What is CGI, and how do I get more information on it?

CGI (Common Gateway Interface) is a protocol used by web servers to run server programs. Scripts that support the CGI protocol are sometimes called ``CGI scripts''; this leads to the unfortunate misperception that CGI is a language of its own.

The classic information on CGI is available on the NCSA server at:

        http://hoohoo.ncsa.uiuc.edu/cgi/

If you haven't read this, read it now. If it doesn't click for you, you can check the Yahoo CGI page at:

        http://dir.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/Server_Side_Scripting/Common_Gateway_Interface__CGI_/

(All one URL)

Try also the following URL for CGI programming in Perl:

        http://www.perl.com/CPAN-local/doc/FAQs/cgi/perl-cgi-faq.html

If you still don't get it, try one of the ``get-rich-quick-by-writing-CGI-scripts'' books at your local bookstores.

## How do I return a graphics file from a CGI script?

One of the big differences between UNIX and Win32 platforms is that on Win32 there's a difference between text or ASCII files and binary file. To return a graphics file, you need to specify that the file is a binary file, and that the standard output stream should accept binary data. Try something like this:

        $MY_FILE_NAME = 'Penelope.jpg';
        $CHUNK_SIZE = 4096;

        open( MY_FILE, "<$MY_FILE_NAME" )
            or die( "Can't open $MY_FILE_NAME: $!\n" );

        print "Content-type: image/jpeg\r\n";
        print "\r\n";

        binmode( MY_FILE ); # These are crucial!
        binmode( STDOUT );

        while ( $cb = read( MY_FILE, $data, $CHUNK_SIZE ) ) {
            print $data;
        }

        close( MY_FILE );

## My CGI scripts don't seem to run right under PerlIS.

Earlier versions of Perl for ISAPI did not output headers correctly, and this caused Perl for ISAPI scripts to misbehave. You could work around this in earlier versions of PerlIS by sending the headers at the beginning of your script like this:

        print <<"END";
        HTTP/1.0 200 OK
        Content-Type: text/html

        END

This is no longer necessary with the current version of Perl for ISAPI, as Perl for ISAPI sends the correct headers. The Registry value that governs this is `EnableCGIHeader`, a REG_DWORD value that is set to 1 by default. This value is stored under the Registry key HKEY_LOCAL_MACHINE\SOFTWARE\ActiveState\PerlIS. If you need to turn off the automatic generation of the header, set this value to 0.

## How does my script know if it's running under ActivePerl or Perl for ISAPI?

Perl for ISAPI sets an environment variable, `PERLXS`, for scripts that are executed under Perl for ISAPI.

        my $running_under_perlis = $ENV{PERLXS} eq 'PerlIS';

## How does my script know if it's running under ActivePerl or Perl for WebSite?

Perl for WebSite sets an environment variable, `PERLXS`, for scripts that are executed under Perl for WebSite.

        my $running_under_perlws = $ENV{PERLXS} eq 'PerlWS';

## What CGI modules run with ActivePerl?

The CGI.pm module works with ActivePerl. It's included with ActivePerl, and you can use it in your program with the statement `use CGI`. Complete documentation for the CGI module is embedded in the module, and can be read with `perldoc CGI`.

## How do I use redirection in my script?

You can use redirection to point the client browser to another file or script, usually in a way that's invisible to the user. The CGI module provides the `redirect()` function for this purpose. The following code redirects the client browser to http://www.perl.com and works with both CGI or PerlIS:

        use CGI qw(:standard);
        print redirect('http://www.perl.com');

## What are cookies and how do I use them?

Cookies are packets of data that a server can give to a client, such as a browser, to maintain information even after the browser has left this site. This can be used to to identify the client in future interactions or to store user preferences. Cookies were first defined by Netscape, and the definition of cookies can be found at:

        http://home.netscape.com/newsref/std/cookie_spec.html

The CGI module provides support for managing cookies. See What CGI modules run with ActivePerl? for information about the CGI module, including the location of online documentation.

## How do I get the e-mail address of the user?

It's not, in general, possible to get the e-mail address of a user without asking them for it. If you need an e-mail address, provide the user with a form to fill in an address.

The HTTP specification (see What is HTTP, and how do I get more information on it?) defines an HTTP request header field, `From:`, that can contain the e-mail address of the user making the connection. Your script can retrieve it using the environment variable HTTP_FROM. However, it's rarely provided and can't really be counted on.

There are all kinds of sneaky ways to determine where requests come from -- like checking the IP address that was used to connect -- but you can't figure out the e-mail address of the user this way.

Generally, it's considered a violation of the user's privacy to get their e-mail address without their knowledge. Perhaps that's why it's so difficult.

## I need a CGI script to do a certain task. Has anyone done it before?

There are several CGI script archives on the web. You may not be able to find exactly the script you want, but you will probably find something that can be adapted to your needs.

Two of the most famous script pages are:

- Jenda's pages: www24.brinkster.com/jenda

- The Perl Monks: www.perlmonks.org

- Matt's script replacements: nms-cgi.sourceforge.net

- Dave Doyle's Script Archive: www.davedoyle.com/help/scripts.html

Note that most script archives have UNIX-targeted scripts, and you may have to make some adaptations to them to make them run (see How do I make a UNIX-based script work?).

This is one of the most common questions on the Perl-Win32-Users list. Occasionally it's phrased more like "I have a program to write. Here are the specs. Please e-mail it to me by Friday." Hopefully the reader can understand why these messages are usually answered rudely, if they are answered at all.

## How do I test my CGI programs that take arguments without running them through the web server?

The hard way to test your CGI programs from the command line is to set up environment variables and a standard input stream just like a web server would (see the CGI 1.1 specification for more details on this -- see What is CGI, and how do I get more information on it?).

The easy way is to use `CGI.pm`, the Perl module for CGI programming. It provides an easy mechanism to run CGI programs, with arguments, from the command line. See What CGI modules run with ActivePerl?.

## The Content-Type: header field I output from my CGI script shows up in the web browser.

You are using an older version of Perl for ISAPI as your Perl interpreter on an IIS web server, but it's not outputting an HTTP status line. You should be able to fix this by installing the most recent version of Perl and PerlIS. See My CGI scripts don't seem to run right under Perl for ISAPI. for more details.

## When I try to run a CGI script from my browser, it tries to download a file of type "application/x-perl" instead.

Your web server has been misconfigured. It doesn't know that it should execute your Perl program, so it's just returning it to the browser. See the perlwin32faq6 manpage for details on how to configure your particular web server to know that Perl scripts should be executed.

## AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Web Programming (CGI and PerlIS)