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.
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.
`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.
`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.
`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.
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.