VOV CGI Procedures

This document describes the Tcl procedures provided by VOV for creating HTML pages using CGI programs. CGI (Common Gateway Interface) is a way of using external programs to dynamically create pages which are returned by your project's vovserver to a user's web browser.

This is greatly simplified by:
  • Writing the CGI script as a Tcl script;
  • Using the VOV procedures described in this document

The CGI programs may be written in any language which can produce an executable program that makes text output.

General-purpose web servers such as Apache and Microsoft IIS support different languages such as Perl, Tcl, Python, Php, Visual Basic and C. The VOV server can also use a CGI programs written in any language, but it is best if your CGI scripts are written in Tcl, because then your programs may use the vtk_* Tcl API functions to interact with the vovserver.

Your Tcl script must generate a correct HTTP reply, considering that VOV already provides the first line which is always:
HTTP/1.0 200 OK
Typically, the script must print to stdout the following data:
Content-Type:  text/html
Content-Length: the length of the HTML pagetext of the HTML page
Note: The blank line following the Content-length: is required for the HTML to be correctly displayed.

When using the VOV CGI procedures, you will not need to be concerned with this type of detail. The VOV CGI procedures help you create the text, and automatically compute the proper length, and close all tags correctly.

HTML is a hierarchical language, where the various types of tags may only appear in certain contexts. For example, it is an error to use the <LI> (list item) tag outside the context of a <UL> (unordered list) or <OL> (ordered list). Each tag <TAG> defines such a context, and must be properly closed by the corresponding </TAG> for the HTML to be correct.

In practice, modern browsers attempt to present even incorrect HTML, so that many simple tags like <P> and <LI> do not need to be closed properly. For tables, however, closing the tags properly is essential for correct presentation. The VOV CGI procedures take care of this chore for you. The scope of each tag begins with the tag's procedure, and finishes with the final closing brace }.

VOV provides procedures to handle a subset of the tags available in the HTML specification, but this set is sufficient to quickly build informative, dynamically- created web pages about your project.

Important: The names of these procedures are mainly taken from the type of HTML tag which they implement, to make them easy to remember for persons familiar with HTML. However, they are not HTML tags; each of the following is a Tcl procedure which takes zero or more arguments, so the script that you write using them must be in valid Tcl syntax.

VOV CGI Procedure Overview

Procedure Descriptions
VOVHTML_START Begin a new HTML page
VOVHTML_FINISH Finish the current page
OUT Insert text in page without newline
OUTLN Insert text in page with newline
HTML Build the HTML part of the page
TITLE Set the page title
BODY Build the main body of the page
COLOR Set color of text
FONT Specify font of text
SPAN Build a span element
FORM Begin an HTML form for user interaction
SCRIPT Insert script code (e.g. Javascript) into page
OPTION Build an option element
SELECT Build a select element
VOV_SET_COOKIE Set a cookie
VOV_GET_COOKIE Retrieve a cookie's value
TABLE Start a new table in the page
TR Start a new row in the current table
TH Insert a table header cell in the current table row
TD Insert a table data cell in the current table row
HREF Insert a hyperlink into the page
BR Begin a new line
HR Insert a Horizontal Rule into the page
H1 Format text as Header1 style (most emphasis)
H2 Format text as Header2 style
H3 Format text as Header3 style
H4 Format text as Header4 style
H5 Format text as Header5 style
H6 Format text as Header6 style (least emphasis)
Other Formatting Items Format text bold, italic, etc.

Example CGI Scripts

This section presents two example scripts written in Tcl. The first is an elaboration of the traditional 'Hello, World!' program, and the second shows how to use VOV's Tcl API to get information about a VOV project from its server.
Example -- Basic "Hello, World" CGI script
This script exploits a difference between the handling of comments in the Tcl language, and C-shell to produce an executable script written in Tcl. The C-shell starts, using -f to specify not reading your ~/.cshrc file, and then immediately executes the VOV 'vovsh' program, which is a Tcl-language shell. That program then receives the remainder of the file as a Tcl script. The Tcl interpreter sees the 'exec' line as a comment, but C-shell does not, and executes it.
Note: The -*- on either side of the word 'Tcl' allows Emacs to recognize the file as a Tcl script.
#!/bin/csh -f
# For the -*- Tcl -*- interpreter the next line is a comment\
exec vovsh -f $0 $*

# This file is provided by the VOV install as $VOVDIR/etc/cgi/ciaobello.cgi
# Once you have created a project using 'vovproject create' and enabled it
# in your shell using 'vovproject enable your-project-name', you may use
#   vovbrowser
# to find the port on which your project's server listens for HTTP requests.
# You may view this CGI program's output by pointing your browser to the URL 
#   http://your-server-host:your-project-port/cgi/ciaobello.cgi

VOVHTML_START                                     ;# start a new page
HTML {                                            ;# begin the page's HTML
    HEAD { TITLE "Ciao bello example" }           ;# set page title
    BODY {                                        ;# begin page body
        H1 { OUT "CIAO BELLO" }                   ;# "Ciao bello" is hello world in Italian
        H3 { OUT "It is now [clock format [clock seconds]]" }
        TABLE {
            TR {                                  ;# first table row is the table hdr
                TH { OUT "Example of a simple CGI script with VOV." } 
            TR BGCOLOR="white" {                  ;# second table row, white background
                TD {                              ;# only 1 table data cell is in this row
                    SMALL {                       ;# make the following text smaller
                        PRE {                     ;# and preformatted in teletype font
                            set fp [open $argv0]  ;# open the file of this script
                            OUT [read $fp]        ;# insert its text into the page
                            close $fp             ;# close file nicely
VOVHTML_FINISH                                    ;# finish the page
Example -- Retrieving VOV Project Information
You can use VOV's Tcl API vtk_* procedures to get information from your project's flow. A nodeid is an integer which is VOV's internal database ID for an object.
Here is a simple example that also shows a way to generate tables.
#!/bin/csh -f
# For the -*- Tcl -*- interpreter the next line is a comment\
exec vovsh -f $0 $*

# This script responds to a URL of type: /cgi/getnode.cgi?nodeid
# see comments in preceding example for how to connect to your project's server
set id [shift]

    HEAD { TITLE "Get Node $id" } 
    BODY {
        H1 { OUT "Node $id" }
        set nodeInfo [vtk_node_get $id]
        TABLE {
            foreach field { status barrier timestamp type } {
                TR {
                    TH { OUT $field }
                    TD { OUT [shift nodeInfo] }
        OUT "CIAO BELLO"