WSU Perl Macros (wsumacs.pl)

The following collection of macros can be used in any perl script on the WSU web server www.wsu.edu. You include these macros into your perl script by saying at the top of your perl code:

require "/cgi-bin/wsumacs.pl";

This document is not intended to be an explanation on how to write perl cgi scripts. There is some information available on web tools which could help you learn about cgi scripting.

&INIT_Script

If you are going to be doing authentication, then the first macro must be &INIT_Script. This macro is used to verify that the browser you are using is registered as being able to support SSL and Netscape cookies. Check out the supported browsers page for more information on what browsers are available. You should also read the page on Network ID (NID) security for more information on using your NID on the web at WSU. You would use this macro like this:

require "/cgi-bin/wsumacs.pl";

&INIT_Script;

After calling &INIT_Script, the following variables are set:

$netid

the Network ID the person used to get authenticated

$FORM

all values passed from the client html to this cgi script. See this example for an idea on how pass values into the $FORM array.

$script_name

This is the name of your cgi script

$script_path

The path on the server where your script actually resides

$StartTime

The time of day this script started running

$UTimeout

By default, if the person running this script is idle for 15 minutes or more, then the next time they do run this script, they will be asked to enter their password again to ensure that the person did not walk away and leave the client idle. The 15 minute default is indicated by entering:

$UTimeout = .01042 # which is (15/24*60)

$Timeout

Not likely to be used. This is used to determine how often a kerberos service ticket is obtainted for this service. The default is every 5 minutes. This helps to ensure that somebody cannot steal your service ticket.

$print_cookies

By default, the macro &print_headers will print any cookies that have been set. If for some reason you do not want &print_headers to pass the cookies, then you would say:

$print_cookies = 0;

 

$DoAuthentication

Again, use care with this one. It is used if you do not want to do authentication but you do want the browser checking to be done, and you do want the above variables set. By default, this is turned on. If you do not want authentication, then prior to calling &INIT_Script you would enter:

$DoAuthentication = 0;

$CheckBrowser

Be careful with this one too. By default, this is turned on to verify that the browser that is using this cgi script is registered as able to use cookies and SSL version 3. Check the browser page for more on this. To disable browser checking, then prior to calling &INIT_Script you would enter:

$CheckBrowser = 0;

 

 

&parseParms

This macro is called from &INIT_Script. You only need to call this macro yourself if you are not going to be using &INIT_Script for NID authentication. What the &parseParms macro does is to read in all of the parameters passed from the client to this perl cgi script running on the server.

For example, if in your client html code you want to pass the person's phone number to your program you could say:

<form method="POST" action="https://www.wsu.edu/~jones/cgi-bin/gather.cgi">

<b>Please enter your phone number and press SUBMIT:</b><br>

<center>

<table border=5 cellpadding=5 align=center> 

<tr><td>

<input type="text" name=phone_number size=8 maxlength=9>

</td></tr></table>

</p>

<input type="submit" value="SUBMIT">

<input type="reset" value="RESET">

</center>

</form>

In this example, the value of the parameter called "phone_number" is passed to the cgi script "gather.cgi" which resides on the www.wsu.edu server under the account "jones". Then in your perl cgi script you would say:

 

require "/cgi-bin/wsumacs.pl";

&parseParms;

And then the value of the "phone_number" would be kept in the array called $FORM. You can access this value, after running &parseParms by setting a variable to $FORM:

my($phone) = $FORM{phone_number};

From then on, the variable $phone contains the phone number that was passed.

&open_client

Prior to sending output from the cgi script to the browser, you would enter:

require "/cgi-bin/wsumacs.pl";

&INIT_Script;

&open_client;

&print_header("Title");

print CLIENT "Hello $netid!!!";

&close_client;

&print_header

After opening a connection to the client with &open_client, it is necessary to send some html information to the browser. This is done with &print_header. By default, what is sent is simply

<html><head><title>...</title></head><body>

Where "..." is the title of the resulting html page. For example, if you said:

require "/cgi-bin/wsumacs.pl";

&INIT_Script;

&open_client;

&print_header("Final Page");

print CLIENT "Goodbye $netid!!!";

&close_client;

Then the title that will appear at the top of of this html page will be "Final Page".

It is possible for &print_header to also pass various page definitions in the <body> tag, such as background image, background color, etc. The definitions you can set are:

BACKGROUND

The background to use for this page. You establish this value prior to the call to &print_header:

require "/cgi-bin/wsumacs.pl";

&INIT_Script;

&open_client;

$BACKGROUND = "/images/bg17.jpg"

&print_header("Page with a background image");

Then the image "bg17.jpg" will be used as the background image for this page. You can, of course, use your own image in your own directory. If you are going to do this in your own account, create a directory in your "public_html" directory called "images" and place the image you want to tile in that directory. Assuming then that you also have a "cgi-bin" directory in your public_html directory where this cgi script resides, then you would do something like this:

$BACKGROUND = "../images/myimage.jpg";

BGCOLOR

You can change the background to have a particular color with the BGCOLOR variable. By default, this is turned off. You can set it to a color by entering prior to the &print_header macro the value of this variable using either the color name

$BGCOLOR = "silver";

or the color value:

$BGCOLOR = "#C0C0C0";

LINK

This variable controls the color value of links you have not yet traversed. You can set it prior to the call to &print_header:

$LINK = "red";

ALINK

This variable controls the color value of active links, the ones the user is currently point to. You can set it prior to the call to &print_header:

$ALINK = "yellow";

VLINK

This variable controls the color value of traversed links. You can set it prior to the call to &print_header:

$VLINK = "purple";

&print_meta_refresh_header

This macro is similar to &print_header. It can set the same values of BACKGROUND, BGCOLOR, LINK, ALINK and VLINK. The &print_meta_refresh_header has the additional ability to refresh (repaint) the browser screen after a set amount of time, and then branch to a new URL that you specify. For example,

&print_meta_refresh_header("Page Title",60,"http://www.wsu.edu/");

After sixty seconds, this page will transfer to the WSU homepage at www.wsu.edu.

&close_client

Likewise, when you are finished writing to the client, you should end with a &close_client:

require "/cgi-bin/wsumacs.pl";

&INIT_Script;

&open_client;

&print_header("Title");

print CLIENT "Goodbye $netid!!!";

&close_client;

&GetTime

You can use the &GetTime macro to set a perl variable tohe current time in milliseconds.

my($curren_time) = &GetTime;

&PostStartTime

If you want to send the current time of day as a hidden variable in the html stream that gets sent back to the client, you can use &PostStartTime. The time that is set is the time of day at the moment the macro was called. For example:

require "/cgi-bin/wsumacs.pl";

&INIT_Script;

&open_client;

&print_header("Title");

print CLIENT "<b>Its working!!</b>";

&PostStartTime;

&close_client;

When the next page is read by the subsequent cgi script, the time set by &PostStartTime will be kept in the $FORM array with the index of "Begin_Time". For example,

require "/cgi-bin/wsumacs.pl";

&INIT_Script;

&open_client;

&print_header("Second cgi Script Title");

my($last_script_start_time) = $FORM{Begin_Time};

print CLIENT "The previous cgi script started

    execution at $last_script_start_time";

&close_client;

&parse_client_cookies

This is used mostly for checking the cookies that were set in a previous cgi script that are applicable to the current cgi script. You can check the example in remote authentication to get an idea of how to read these cookies.

&unescape_string

You probably won't need this one, but if you are having trouble with metacharacters, you can create an unescaped string of metacharacters using the &unescape_string macro. The time this might happen is in passing parameters to the cgi script. If you aren't certain about the handling of metacharacters, and when they are translated, you likely don't need this macro.

my($new_string) = &unescape_string($FORM{field1});

&Reauth

Use care with this one. You can force authentication in a cgi script a second time by saying as you leave your cgi script. This might be handy if you wanted to force reauthentication prior to updating some information for somebody.

&Reauth;

return;