CGI Mode

The mkhtmidx utility has a special mode which supports the Common Gateway Interface (CGI). When used with a web server that supports CGI, mkhtmidx can search an index database and generate HTML search result pages. It can generate multiple search pages with a fixed number of items per page.

In CGI mode, the list of files and directories that can appear in the index is obtained from an index database file which is generated by the "mkhtmidb" utility. The index database file, "index.db", must be located in the current working directory or one of its parents (up to 4 levels down). The actual list of links that appear in the generated index is determined by the CGI parameters which define the matching criteria. The index generated by the "mkhtmidx" utility is sent to stdout instead of being written to the file "index.htm", and contains the appropriate content-type header line.

To use CGI mode, you must first copy "mkhtmidx.exe" to the appropriate CGI bin directory used by your web server. Then you must place a configuration file named "mkhtmcgi.ini" in the CGI bin directory. The mkhtmidx utility checks for the existance of the "mkhtmcgi.ini" file whenever it runs, and enables CGI mode if it finds the file in the same directory as "mkhtmidx.exe".

The "mkhtmcgi.ini" file should contain the CGI Mode Options, and any other options necessary to set the CGI configuration.

CGI parameters

The following CGI parameters are supported in CGI mode:

  config    Configuration name (see CGI Configuration File below)

  query    Query search expression

  type Type of links. The value can be either a (all, default), d (directories only), or f (files only)

  id    Cache identifier. This string (up to 31 characters) is required to enable the search results cache.

  first Offset from the first match to use as the first element in the index (default = 0 = first match)

  count Number of links (maximum) to include on each page of the index (default = unlimited)

`config`	Configuration name (see CGI Configuration File below)
`query`	Query search expression
`type`	Type of links. The value can be either a (all, default), d (directories only), or f (files only)
`id`	Cache identifier. This string (up to 31 characters) is required to enable the search results cache.
`first`	Offset from the first match to use as the first element in the index (default = 0 = first match)
`count`	Number of links (maximum) to include on each page of the index (default = unlimited)

CGI Configuration File

Unlike the standard mode, there is only one configuration file in CGI mode. The CGI configuration file must be named "mkhtmcgi.ini" and it must be located in the same directory as the "mkhtmidx.exe" file. There are no master or local configuration files. The CGI configuration file contains the same options that the master and local configuration files normally do, but with some minor differences.

The CGI configuration file may contain multiple sections, each with a unique title enclosed in square brackets, as shown in the following example:

   indexDB=index.db
   startDir=C:\pictures
   startURL=/pictures
   workingDir=C:\pictures\Search
   backLink=/pictures/Search/index.htm
   index=formatted
   slides=window
   links=standard
   configFile=makeindx.bat
   embed=avi
   embed=mov
   embed=mpg
   embed=mpeg
   embed=rm
   reservedFile=bigthumb.jpg

   [list]
   format=list
   thumbnails=no

   [thumb1]
   format=compact

   [thumb0]
   layout=thumbnail

   [bigthumb1]
   thumbFile=bigthumb.jpg
   format=<CENTER><?A>${thumb attrib="BORDER=0"}</A><BR>{{<B>${title}</B>}<?BR>
          {<SMALL>[${info}]</SMALL>}}<BR>&nbsp;</CENTER>
   columns=4
   body=BGCOLOR=WHITE
   indexDB=btindex.db

   [bigthumb0]
   workingDir=C:\pictures\cgi-bin
   layout=thumbnail
   format=<?A>${thumb attrib="BORDER=0"}</A>
   thumbFile=bigthumb.jpg
   columns=4
   body=BGCOLOR=WHITE
   indexDB=btindex.db

Each section begins with a line that contains a title in square brackets, and ends with the title of the next section (or the end of the file). There may be an unnamed section at the beginning (with no section title) which contains options that are common to all sections.

When the configuration file is read, any unnamed section at the beginning is read first. Then a named section is read based on the title specified in the "config" parameter of the CGI request. If no "config" parameter is specified or if a section with the specified name does not exist, a named section will not be read. Named sections may contain options that override options in the unnamed section at the beginning.

Search Results Cache

A cache may be used to speed up access to multiple page searches. The cache stores the results of the last search, along with the CGI search parameters (config, query, type, and id). This option currently supports only a single global cache file, and is not re-entrant. Do not enable this option in multiple client configurations.

The cache will be used if all of the following conditions are met:

The cacheDir configuration option is used
The cache file exists
The CGI "id" parameter is specified
The CGI search parameters (config, query, type, and id) match the ones stored in the cache.
The index database file has not been changed since the cache was created.

Otherwise, a new search will be performed using the index database, and a new cache will be created.

The Cache Identifier

The cache "id" parameter is used to force cache updates. The value of the Cache Identifier is not used except to detect changes. To guarantee that a new cache is created for each new search, the cache "id" parameter should be different each time a new search is performed. The HTML search form should use a hidden "id" field and JavaScript to perform this function. In the form, the default field value for the "id" field should be a non-empty string (in case the user disables JavaScript on his browser). The following JavaScript code shows the recommended method to set the "id" field:

   document.form.id.value = (new Date()).getTime();

This code should be executed when the form is submitted. It uses the current time to supply a different "id" each time the form is submitted.

cgiserver

A simple command-line web server called "cgiserver" is distributed as part of the ImajSite package. This web server can be used with mkhtmidx to test CGI functionality or query image databases on your local computer. To start it, perform the following steps:

Open a "MS-DOS Prompt" window
Change to the drive where your files are located (e.g. "D:")
Type "cgiserver /L"

To stop it, press Ctrl/C or Ctrl/Break in the MS-DOS Prompt window.

This web server has the minimum functionality required to use mkhtmidx in CGI mode. It does not implement most of the features of a standard web server. For a complete description of this server, type "cgiserver /?" at the command line.

Warning: This web server allows access to any file on the drive that it is run from. It also allows any program to be executed on that drive. Because of that security risk, it is recommended that the /L option be used unless remote client access is explicitly desired. The /L option restricts access to the local computer only, and does not allow remote clients to access files via the web server. If you want to access files from remote clients, it is recommended that you used a different web server such as Apache.

Table of Contents