Imprints Database Administration Guide
version 0.1 - Mark Pruett
The Imprints Database
The Imprints Administration tool (ImpAdmin) is a web-based tool for maintaining the Retrieval Server database. This database currently consists of one or more Locations tables and three support tables (Geography, Geo Preferences, and Aliases. These tables and their purpose to the Retrieval Server are explained in more detail in the Retrieval Server design document and the Database design document.
The ImpAdmin program, imp_admin.cgi, must be installed in your web server's cgi-bin directory, or some directory beneath it. It's file premission must be set to world-executable so that your web server can run it.
Once installed, the program can be run by pointing a web browser to the appropriate URL:
http://myserver/cgi-bin/imprints/imp_admin.cgiFor ImpAdmin to work properly, the RDB database tools must be installed on the server. This is a set of command-line perl programs for manipulating RDB files. The package is available at ftp://ftp.rand.org/pub/RDB-hobbs/.
The Configuration File
Once installed, you must create an imprints configuration file. Information in this file takes the form:
variable = value
A few configuration variables must be defined for ImpAdmin to work correctly. The first is DB_DIR. This is the directory where the database files are stored. The second required variable is DB_DEF_LOC_FILE, this is the default location table name. This is the table the will be queried if not specific table has been selected. Last is the variable RDBDIR. This is the directory where the RDB tools package (see ImpAdmin Installation, above) has been installed.
The figure below shows a sample configuration file. Notice that white space around the equal signs is ignored, as are blank lines. Also, lines beginning with the "#" symbol are treated as comments and are also ignored.
Figure: Sample Imprints Configuration File.
The data tables used by the Retrieval Server are edited by clicking on the links at the top of every ImpAdmin page. A new page will load, containing two sections: an editing form near the top of the page, and a data table at the bottom.
The editing form let's you add new records, and edit existing ones. To add a record, simply type the appropriate data into the fields, then press the "Add" button. Once the database has been successfully updated, the page will be redisplayed. A message will indicate if the database transaction was successful. If successful, the new record will also be displayed in the data table.
Figure: Tables are selected using the Tables links.
The geography table uses an auto-increment field to automatically generate a unique numeric key (for geo_code) when the record is added. The geo_code field is not editable, and will be displayed as "[auto-increment]" in the editing form. When an existing record has been selected for editing, the geo_code value is displayed, but cannot be changed.
Figure: The Geo Preferences table, showing the Auto-Increment field.
The records for the selected data table are displayed at the bottom of the form. To the right of each record are two links: "edit" and "delete". The edit link reloads the page with the selected record's values displayed in the editing form. The record's values can then be altered, and changes can be saved to the database by pressing the "Edit" button.
Editing and Deleting
When the "Edit" button is pressed, the database is updated and the page is redisplayed. A message will indicate if the update was successful, and the altered data record will appear in the displayed data table.
The "delete" link deletes the selected record from the database. As with the other transactions, a message is displayed, and if the deletion was a success, the record should no longer be in the displayed data table.
Editing the Locations Tables
Editing the Locations tables is handled as described above, but there are some additional features. When the Location link is selected from the table links at the top of the ImpAdmin page, an editing form and data table are displayed for the default Locations table.
But since there can be more than one Locations table, a pull-down list box is available at the top of the editing form. To select an alternate Locations table, select it in the list box and press the "List Records" button (located to the right of the list box). The page will be redisplayed with that Location's records displayed.