4.1.1 The Dispatch CGI

The DODS dispatch CGI program receives a data request from the DODS client, and dispatches the request to one of several filter programs. The dispatch CGI is stored in a CGI directory on the host machine. Its name is an important detail of its operation. The name should begin with nph-, and end with the letters that distinguish data files containing data formatted with that API from other files.⁸ So, for example, NetCDFdata files are called foo.nc, so the NetCDFdispatch CGI is called nph-nc.  

The dispatch CGI's job is to parse the incoming URL and execute the appropriate filter programs with the arguments enclosed in the URL. The dispatch CGI is also be responsible for the first level of error information that must be returned to the user. These tasks are easily accomplished in any scripting language. On the off chance you wish to use Perl, DODS provides a Perl class designed to make writing the CGI a simple task.

The file DODS_Dispatch.pm contains the definitions of the DODS_Dispatch class. This class provides several methods used to parse the incoming URL, and one method for delivering error messages to the client. The DODS_Dispatch provides the following methods:

 

command()

Returns the command string implied by the input URL. The command string looks like:

command filename -e query-string.

Where command is the DODS filter program to be run, filename is the absolute filename of the dataset on which to run it, and query-string is the constraint expression that was enclosed in the URL. Of the DODS_dispatch methods, many dispatch CGI scripts may only need to use this one and print_error_msg. See figure 4.1.1

 

query()

Returns the query string from the URL. This is the DODS constraint expression.

 

filename()

Returns the absolute filename corresponding to the requested dataset.

 

extension()

Returns the extension on the end of the URL. For DODS, this will be das, dds, dods, info, or ver.

 

cgi-dir()

Returns the absolute pathname of the directory in which the dispatch CGI is stored. This is generally the same as the directory in which the DODS filter programs are stored.

 

script()

Returns the name of the dispatch CGI, minus the nph-, and any suffixes used for a secure server.

 

print_error_message(ver)

This returns an error message to the client, explaining how to use the server. The ver argument should be a string containing the version of the server software. The error message returned is encoded in the DODS_Dispatch.pm file.

 

print_help_message()

This returns a help message to the client. This can be issued in response to a confusing or inadequate URL. The help message returned is encoded in the DODS_Dispatch.pm file.

A sample (simple) DODS dispatch CGI is shown in figure 4.1.1. This is a Perl script using the DODS_Dispatch methods. This script assumes that all data is rooted in the http document directory subtree.⁹

#!/usr/local/bin/perl

use Env;
use DODS_Dispatch;

$dispatch = new DODS_Dispatch;

$command = $dispatch->command();

if ($command ne "") {           # if no error...
    exec($command);
} else {
    my $script_rev = '$Revision: 11906 $ ';
    $script_rev =~ s@\$([A-z]*): (.*) \$@$2@;

    $dispatch->print_error_msg($script_rev);
}