Author: Mikio Hirabayashi
Description: specifications of CGI of QDBM
Keywords: QDBM, DBM, database, CGI

# Specifications of CGI Scripts of QDBM

Copyright (C) 2000-2006 Mikio Hirabayashi
Last Update: Thu, 26 Oct 2006 15:00:20 +0900
[Japanese]

## Table of Contents

1. Overview
2. Building
3. CGI Script for Database Administration
4. CGI Script for File Upload
5. CGI Script for Full-text Search
6. Configuration of Web Servers

## Overview

Three CGI scripts are included in the package of QDBM, as utilities or sample applications. The first administers databases of Depot, Curia, and Villa. The second helps you to upload files, with utilities of Cabin. The third realizes a full-text search system with a database of Odeum.

## Building

Change the current working directory to the sub directory named `cgi'.

    cd cgi

Run the configuration script.

    ./configure

Build programs.

    make

Install programs. This operation must be carried out by the root user.

    make install

When a series of work finishes, the following files will be installed. As for the rest, documents will be installed under `/usr/local/share/qdbm/cgi'.

    /usr/local/libexec/qadm.cgi
    /usr/local/libexec/qupl.cgi
    /usr/local/libexec/qfts.cgi
    /usr/local/share/qdbm/cgi/qadm.conf
    /usr/local/share/qdbm/cgi/qupl.conf
    /usr/local/share/qdbm/cgi/qfts.conf

Install CGI scripts and their configuration files to a public directory of WWW, according to each of the following sections.

## CGI Script for Database Administration

`qadm.cgi' is a CGI script to administer database files of Depot, Curia, and Villa. Database files can be administered with it via WWW. Contents of the key and the value of each record should be character strings. The comparing function of the advanced API is lexical ordering. The available operations are listing databases, creating a database, removing a database, downloading a database, listing records, storing a record and deleting a record.

To install `qadm.cgi', perform the following steps. Copy `qdbm.cgi' and `qadm.conf' into a directory where CGI is available. And, create a directory `qadmdir' in the CGI directory. For example, if the CGI directory is `/home/mikio/public_html', the following steps are suggested.

    cd /home/mikio/public_html
    cp /usr/local/libexec/qadm.cgi .
    cp /usr/local/share/qdbm/cgi/qadm.conf .
    mkdir qadmdir

The directory `qadmdir' should be granted the permission of reading, writing, and execution. Being most easily, the following steps are suggested. As for the rest, you can grant the CGI script setuid bit, or you can use a so-called suExec mechanism.

    cd /home/mikio/public_html
    chmod 1777 qadmdir

`qadm.conf' is the configuration file. As the default contents are the following, you can modify them arbitrarily.

    encoding: UTF-8
    lang: en
    title: Administration CGI
    datadir: qadmdir
    keychop: true
    valchop: false

`encoding' specifies the character encoding of the shown page and the records of database files. `lang' specifies the language of the shown page. `title' specifies the title of the shown page. `datadir' specifies the path of the directory containing database files. `keychop' and `valchop' specifies whether to normalize keys or values. If one is `true', white spaces at the end of each content are removed, and the contents can not contain linefeed codes.

Access the URL of `qadm.cgi' with a web browser. Then, follow the navigation of the page and administer the database.

For automatic agents to retrieve a stored record, the mechanism to get the as-is contents of the value of a records specified with a URL is provided. For example, if the URL of the CGI script is `http://a.b.c/qadm.cgi' and the name of the database is `staff' and the key is `mikio', the agent should access `http://a.b.c/qadm.cgi/staff/mikio'. That is, separated with '/', the URL of the CGI script entails the database name (without any suffix), which entails the key.

If you want to administer existing database files, you should place them in the directory `qadmdir'. And, the database files of the basic API should have the suffix `.dp'. The database directories of the extended API should have the suffix `.cr'. The database files of the advanced API should have the suffix `.vl'. For example, they are `foo.dp', `bar.cr' or `baz.vl'. Moreover, each database file or directory should be writable and readable by the CGI script.

## CGI Script for File Upload

`qupl.cgi' is a CGI script to upload files, with Cabin. You can upload arbitrary files to your web server. You can perform downloading and deleting also.

To install `qupl.cgi', perform the following steps. Copy `qupl.cgi' and `qupl.conf' into a directory where CGI is available. And, create a directory `qupldir' in the CGI directory. For example, if the CGI directory is `/home/mikio/public_html', the following steps are suggested.

    cd /home/mikio/public_html
    cp /usr/local/libexec/qupl.cgi .
    cp /usr/local/share/qdbm/cgi/qupl.conf .
    mkdir qupldir

The directory `qupldir' should be granted the permission of reading, writing, and execution. Being most easily, the following steps are suggested. As for the rest, you can grant the CGI script setuid bit, or you can use a so-called suExec mechanism.

    cd /home/mikio/public_html
    chmod 1777 qupldir

`qupl.conf' is the configuration file. As the default contents are the following, you can modify them arbitrarily.

    encoding: UTF-8
    lang: en
    title: Administration CGI
    datadir: qupldir
    quota: 67108864

`encoding' specifies the character encoding of the shown page and the records of database files. `lang' specifies the language of the shown page. `title' specifies the title of the shown page. `datadir' specifies the path of the directory containing database files. `quota' specifies the limit of the total size of uploaded files.

Access the URL of `qupl.cgi' with a web browser. Then, follow the navigation of the page and administer the files.

## CGI Script for Full-text Search

`qfts.cgi' is a CGI script to perform full-text search with a database of Odeum. It realizes full-text search system of a web site. Generating a database of the index is performed with the command `odidx'. Searching the index is performed with `qfts.cgi'. Search methods have two kinds: `AND search' retrieves documents which include all search words, `OR search' retrieves documents which include at least one of search words. Search results are ordered by scores.

To install `qfts.cgi', perform the following steps. Copy `qfts.cgi' and `qfts.conf' into a directory where CGI is available. And, create an index `casket' in the CGI directory. For example, if the CGI directory is `/home/mikio/public_html', the following steps are suggested.

    cd /home/mikio/public_html
    cp /usr/local/libexec/qfts.cgi .
    cp /usr/local/share/qdbm/cgi/qfts.conf .
    odidx register casket
    odidx relate casket

If directories of search targets are not under the directory including CGI scripts, you can make symbolic links to the target directories there.

When your site is updated, the index also shuld be updated with the following steps. These operations are suggested to be automated with `crontab' and so on.

    cd /home/mikio/public_html
    odidx register casket
    odidx purge casket
    odidx relate casket
    odmgr optimize casket

`qfts.conf' is the configuration file. As the default contents are the following, you can modify them arbitrarily.

    encoding: ISO-8859-1
    lang: en
    title: Full-text Search CGI
    index: casket
    prefix: ./
    diridx: index.html
    decuri: false
    help: <h1>Full-text Search CGI</h1>
    help: <p>Input search words into the above form and push the [Search] button.</p>
    help: <p>This is a sample application of the inverted API of QDBM.</p>

`encoding' specifies the character encoding of the shown page and the records of database files. `lang' specifies the language of the shown page. `title' specifies the title of the shown page. `index' specifies the path of the index. `prefix' specifies the prefix to be attached on the URI of each document. For example, if `prefix' is `http://x.y.z/foo/', `./bar/baz.html' and `bar/baz.html' are shown as `http://x.y.z/foo/bar/baz'. `diridx' specifies the name of a file standing for a directory. For example, if `diridx' is `index.html', `./foo/index.html' is shown as `./foo/'. `decuri' specifies that, if the value is `true', URIs of documents are expressed with decoded. `help' specifies the help message shown at the first page.

Access the URL of `qfts.cgi' with a web browser. Then, follow the navigation of the page and perform full-text search.

For more information about the command `odidx' to generate the index, refer to the fundamental specifications of QDBM. If your site is large-sized, to reduce size of the index, you should consider building QDBM with ZLIB enabled.

## Configuration of Web Servers

To use CGI scripts, configuration of your web server should permit CGI execution. If CGI scripts are deployed with usual contents, configuration of Apache is like the following.

    Options ExecCGI
    AddHandler cgi-script .cgi

Altanatively, if you set up an exclusive directory for CGI scripts, configuration of Apache is like the following.

    ScriptAlias /~mikio/cgi-bin/ "/home/mikio/public_html/cgi-bin"

If the library path of your web server does not contain `/usr/local/lib', you may have to define it explicitly. Configuration of Apache is like the following.

    SetEnv LD_LIBRARY_PATH "/lib:/usr/lib:/usr/local/lib"

On Microsoft IIS, the directory including a CGI script and the current directory on runtime are defferent. Since the latter is the root of a virtual directory, each configuration file should be deployed there.