The RunRev CGI Tutorial

A reoccurring question is "where can I easily look up how to write CGI's with RunRev". Look no further! Of course there are some differences for each platform, but generally speaking you need to do the following:

1. Get a CGI engine. As of version 2.9, you can take the engine from your own Rev installation, found in:
<Rev Folder>/Runtime/Linux/
Alternatively, download the older CGI engine from the Revolution FTP site:
ftp://runrev.com/pub/revolution/downloads/engines/current
Theoretically you can get the old Metacard engines here (but that's not recommended):
ftp://metacard.com/metacard

2. Install the right engine:
You want to install the engine into the cgi-bin folder. Some servers have named this folder differently, so look out. The engine's permission needs executing rights, so set it to "rwx rx rx", respectively "755". The engine needs to be called from the server software, that's why it needs execution rights.

Note about permissions: Normally you would set the permission to 755 or even 700, but if things don't work, try to set the permission to 777, so you're sure that permissions are not the problem.

3. Create your HTML:
There are two ways to access a cgi on a server. I will explain them seperately:

A. You can simply link it, then the CGI wont receive any data, but you can do nifty stuff nonetheless. Write this into your HTML page:
view the <a href="cgi-bin/guestbook.cgi">guestbook</a>.
B1. Use a Form to generate Data to be processed in the CGI. There are two ways of using a form the "GET" method will show your submitted data in the URL, where the "POST" method will send it invisible. I use the "GET" method in my Example, as you can look at the parameters easily that way:
<form action="cgi-bin/guestbook.cgi" method="get">
Make a new guestbook entry:<br>
name:<br><input type="text" size="40" name="name"><br>
text:<br><textarea rows="9" cols="40" name="text"></textarea><br>
<input type="submit"><br>
</form>

4. Create your cgi script:
Now you can write your CGI script. The CGI file must be placed in the CGI-Bin directory, and have a permission to execute (777). Generally a cgi script works like any script in RunRev, but there are some things to be known, so I will explain them using a guestbook script I wrote:

#!rev -ui
//the first line contains #!nameOfEngine, and a parameter
//I renamed the engine to "rev"
//the parameter -ui makes rev not load the ui and run faceless
on startup
//This is the message the CGI gets when called via a URL
  open stack "guestbook"
//I open a stack, which is also in the cgi-bin directory
  get $query_string
//Read submited parameters (using "GET")
  if it <> empty then
    put urldecode(it) into data
//the Data is urlencoded
    split data by "&" and "="
//I put the data into an array, for easier access
    go to last card
    create card
//new data means a new entry in my guestbook
    put the short internet date into field "date"
    put data["name"] into field "name"
    put data["text"] into field "entry"
//see, I told you the array would come in handy!
    replace return with "<br>" in field "entry"
  end if
  put "Content-Type: text/html" & crlf & crlf
//by using put I output stuff to the server,
//and generate the HTML page for the browser
  put "<html><head><title>You are on my iBook!</title></head><body bgcolor=" & quote & "148D00" & quote & ">"
  repeat with x = the number of cards down to 1
    go to card x
    put "<p>date:<br> & field "date"
    put "<br>name:<br>" & field "name"
    put "<br>text:<br>" & field "entry" & "</p><hr>"
  end repeat
  put "</body>"
  save stack "guestbook.rev"
// the directory where a saved stack is, needs
// write permissions for everybody!
  close stack "guestbook"
//if you don't close stacks the cgi won't work
end startup


To clarify I will restate the differences to a normal Script:

1. You need the name of the engine on the first line of the text, like this:
#!revolution -ui
2. You need to use the "on Startup" message, as it gets send when the script executes.
3. Parameters are URLencoded, and in the form of Name1=value1&Name2=value2. You may read eventual parameters submitted with GET using a environment variable:
put $query_string into theQuery
4. You should use the "put" command to output stuff to the browser. Your output should start at least with this:
"Content-Type: text/html charset=ISO-8859-1" & crlf & crlf
5. When Saving a stack, the directory needs write permission for everybody (666)
6. You need to close opened Stacks before the end of the execution.


I hope this enables you to write your own CGI's with RunRev. Fore more details and examples, visit the extensive CGI tutorial by Hyperactive Sowftware.