NOTE: These notes were put together by Sarah Yurman, a programmer at Spatial Focus, while setting up her first ACEDB server. She has contributed these notes in the hope that they will help other programmers to avoid the traps that she stumbled into. Another important document to consult is wrpc/SERVER.INSTALLATION, part of the ACeDB source distribution.

Troubleshooting a new ACE Database

Introduction
May 25, 1999

This is a list of things great and small that we have discovered while implementing a new ACE database at Spatial Focus. We are working with ACE in Linux, at the time of this writing we are using Redhat 5.2.

Caveat Emptor

This document is a work in progress. It is being written while we are solving problems. Its primary purpose is to maintain a record for internal use at Spatial Focus. Although we don't deliberately make mistakes, anything in this document could be wrong. Mistakes will be corrected as they are found. We are not responsible for any harm resulting from information we record here.

Merci!

Many thanks to Lincoln Stein and all the folks at the Human Genome Project.

Contents

Environment Description

Installation

ACEDB

Gifaceserver

Models

Editors

White Space

To Do

Environment Description

These notes refer to the following environment:

Installation:
ACEDB

ACEDB and environment variables

Problem

If nothing works, chances are the environment variables haven't been set. The acedb and textdb scripts built by INSTALL wouldn't work due to the differences in shells. acedb sets environment variables called $ACEDB and $DBDIR, and appends your path, then starts the xace graphical interface to ACEDB. textdb sets the environment variables and starts the tace text interface.

Solution

I altered my .bash_profile with the following lines:

ACEDB=[pathname to database]
DBDIR=[pathname to database]/database/
PATH=$PATH:[pathname to ace software directory]/bin
export ACEDB
export DBDIR
(PATH was already exported)

Testing the Solution

Use the echo command to make sure the environment variables are in place. We put our "contacts" database under /home/httpd because that directory is accessible to the web server. This is a requirement of AceBrowser, which we want to use as the primary interface.

A test of the $ACEDB environment variable looks like this:
echo $ACEDB (return)

It returns this:
/home/httpd/database/contacts/

Consequences of the Solution

The NOTES file distributed with this version of ACEDB advises you to move the acedb and textace scripts to /usr/local/bin, and using them to start the program. With your environment variables in place, you can simply use xace or tace instead.

Permissions

Take your permissions seriously. Richard Durbin's Installation Guide is out of date, but gives good advice in this department.

Gifaceserver
Warning: this isn't yet working completely

Problem

Most documentation dealing with this software simply tells you to get it going. The software comes with no documentation whatsoever. No README at all. There is a manual that comes in /acedocs called aceserver.html. Its installation instructions don't work on version 4.7g.

Solution

The best installation information is in the README file for AcePerl-1.54. A few more hints are listed here.

The AcePerl README file implies creating a user called acedb. This creates permissions problems that we haven't solved yet. We are using individual user names instead.

One thing that no documentation mentions is that we had to move gifaceserver.LINUX to /usr/local/bin/gifaceserver. Obvious, but still makes you wonder while you do it.

Inetd.conf

Our individual inetd.conf files were completely commented out, and the daemon stopped because of our dispersed locations. Append the required line to the file, and enter:

Killall -HUP inetd

server.log

The server really wants a server.log file, writable by the user to whom the gifaceserver is assigned in the inetd.conf file. We created one by opening the gifaceserver on a fake port number (12345):

/usr/local/bin/gifaceserver /home/httpd/database/contacts 12345 1200:1200:10

Models

Documentation

The best documentation for models is in /acedocs/exploring/*. The table of contents is in /acedocs/exploring/toc_models.html. Unfortunately, like all the ACEDB documentation, it uses absolute pathnames. We have converted these pathnames to relative ones, and will make the document available for download on the Spatial Focus private web page. Although the document is marked "draft" and dated 1994, it is thorough and simple. Doesn't appear to be significantly out of date.

The moviedb database is the best simple example of a database.

Editors

ACEDB is picky about its ascii. vi works great. Can't vouch for emacs ;-). Don't use anything nasty like a word processor.

White Space

It really likes alignment, and it likes tabs. Combining tabs and spaces kills otherwise perfectly good models every five seconds.

To Do

Solve the mysteries of the failure of AceBrowser. Every other means of access works now.