The .CGIVARS Command

The .CGIVARS Command

Syntax: .CGIVARS [ConvertXY]

This command allows limited CGI (Common Gateway Interface) programming to be performed using Document Interface commands. It simply converts any variables passed as parameters either in the URL of the document name or as part of an HTML <FORM> into Document Interface variables with the same name.

If a variable's name is passed without a value, the DI sets its value to 1. If an attempt is made to change one of the unmodifiable DI variables, a script error will result.

Variables in the URL

A quick way to pass variables is by adding them onto the end of a URL, usually as part of an <A> tag. The syntax is as follows:

DocumentURL?varname1[=value]&varname2[=value]&varname3[=value] ...

The notation [=value] means that a value is optional, but if present, is preceded by =.

Values must be "URL encoded". This can make passing anything but normal alphanumeric values a real chore. At this point, it's probably easier to use a <FORM> instead:

Characters from A-Z, a-z, and 0-9 can be passed without any conversion.
The space character is translated to a +.
Any other character is converted to its two-digit hexadecimal ASCII value, and preceded by a %. For example, the / character is represented as %2F.

As an example using simple values, let's say you have a document with this link in it:

Click <A HREF="cgitest.shtml?testing&twenty=20">here</A> to test

Here is what cgitest.shtml looks like:

<HTML><HEAD><TITLE>Testing</TITLE></HEAD>
<BODY>
  <H2>CGI variables test</H2>
  <!--.banner off--><!--.controls notop nobottom-->
  <!--.set testing=0--><!--.set twenty=0-->
  <!--.cgivars-->
  <!--.echo "Variables testing=$testing and twenty=$twenty"-->
</BODY></HTML>

Click here to test

The line  is more important than you might think. Normally, if the Document Interface encounters a reference to a variable that has not been defined yet, it produces an error message. If someone looks at the file cgitest.shtml without the CGI variables being passed, the .cgivars command will have no effect, therefore $testing and $twenty will be undefined. By setting them to zero to start with, we are preventing the script from producing an error message (though the .echo command will echo "You entered testing=0 and twenty=0"). If the CGI variables have been passed, then the .cgivars command will set them to the correct values. Another way around this particular problem would be to use the .IFDEF or .IFNDEF command.

After you have clicked on the link above to try out the test, go up to the Location line in your browser, change the values being passed by manually editing the URL, and then press Return. You should see the new values in the resulting Web page.

To make creating this type of link easier, please see the &TOCGI function.

Variables in Forms

Another, more flexible way to pass variables to a document is by using an HTML form. The example above could be rewritten as:

<FORM HREF="cgitest.shtml">
<INPUT TYPE=HIDDEN NAME="testing" VALUE="1">
<INPUT TYPE=HIDDEN NAME="twenty" VALUE="20">
<INPUT TYPE=SUBMIT TEXT="Try Me!">
</FORM>

Here is a more complex example, which actually does something. It uses .RANDOM and .IF commands to produce a guessing game, which asks the user to guess a number from 1 to 100. Try it out by clicking here. The source looks like this:

<HTML>
<HEAD>
  <TITLE>I'm thinking of a number...</TITLE>
  <!--.
  banner off;
  controls notop nobottom;
  made "Dan Wilga";
  maintains "Webmaster" -->
</HEAD>
<BODY>
<!--.
set number=0;                    # DEFAULT VALUES
set guess=0;                     # MAY GET CHANGED BY .cgivars
cgivars;                         # TRANSLATE CGI VARIABLES TO DI VARS
if $guess;                       # HAS THE USER GUESSED BEFORE?
  set number=$number^1234;       # UN-ENCRYPT THE NUMBER
  if $guess>$number;
    echo "<H2 align=center>$guess is too high. Try again.</H2>";
  elsif $guess<$number; 
    echo "<H2 align=center>$guess is too low. Try again.</H2>";
  else;
    echo '<H1 align=center><FONT color="red">You got it!</FONT></H1>';
    set number=0;                # GENERATE A NEW NUMBER BELOW
  endif;
endif;
if !$number;                     # NEED A NEW RANDOM NUMBER
  random 100 number;             # FROM 1 TO 100
  set guess=0;                   # HAVEN'T GUESSED THIS NUMBER YET
endif;
-->
<H3 align=center>
  I'm thinking of a number from 1 to 100.<BR>What is your guess?
</H3>
<CENTER>
<FORM>
<!--.
  set number=$number^1234;       # ENCRYPT THE NUMBER SO IT WON'T BE OBVIOUS IN THE URL
  echo "<INPUT type=hidden name=number maxlength=3 value=\"$number\">";
  if $guess;
    echo "<INPUT type=text name=guess maxlength=3 value=\"$guess\">";
  else;                          # HAVEN'T GUESSED THIS #, SO LEAVE INPUT EMPTY
    echo "<INPUT type=text name=guess>";
  endif;
-->
</FORM>
</CENTER>
</BODY></HTML>

A Note about Images in Forms

If you use an <INPUT TYPE=img> within a <FORM>, the value that is passed to the CGI normally contains both the X- and Y-coordinates of the location within the image where the user clicked the mouse. It does this by creating two separate variables, which the DI translates into name_x and name_y. So, for instance, if you had the code <INPUT TYPE=img NAME="foo" SRC="somefile.gif">, then when the user clicked on this image, the .CGIVARS command would create two variables: foo_x, and foo_y.

But there is nothing created with the name foo, and this may make your code more difficult to write. The way around this is to use the MergeXY option in the .CGIVARS command. This way, the DI will create one variable called foo, and it will have some value (though what that value is is undefined). This allows you to write code that tests to see if the user clicked on the button named foo using the format:

<!--.
cgivars mergexy;

ifdef foo;
   echo "You clicked on the button with the name 'foo'";
endif;
-->