# Specification of CGI Scripts with QDBM

Copyright (C) 2000-2003 Mikio Hirabayashi
Last Update: Thu, 20 Nov 2003 22:44:08 +0900
[Japanese] [Home]

## Table of Contents

1. Overview
2. Building
3. CGI for Database Administration
4. CGI for Full-text Search
5. Configuration of a Web Server

## Overview

Two 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 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

When a series of work finishes, `qadm.cgi' and `qfts.cgi' will be generated.

Install them and their configuration files according to each of the following sections.

## CGI 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 `qadmdb' in the CGI directory. For example, if the CGI directory is `/home/mikio/public_html', the following steps are suggested.

    cp qadm.cgi qadm.conf /home/mikio/public_html
    mkdir /home/mikio/public_html/qadmdb

The directory `qadmdb' 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.

    chmod 1777 /home/mikio/public_html/qadmdb

`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 of QDBM
    dbdir: qadmdb
    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. `dbdir' 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 `qadmdb'. 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 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.

    cp qfts.cgi qfts.conf /home/mikio/public_html
    cd /home/mikio/public_html
    odidx register 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 with QDBM
    index: casket
    prefix: ./
    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. `dbdir' specifies the path of the directory containing database files. `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/'. `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.

## Configuration of Web Server

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 only 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"