Appendix 1: Setting up an empty database

The most effective way to learn about ACeDB is to modify models and enter data into a database. However, this should not be done with the distribution version of a database if you plan on relying on the information in it! It is better to establish several independent databases before beginning serious curatorial work.

First, you will probably install one or more publicly available distributions (for example, the C. elegans database) as a source of ideas. It is best to choose one that uses the most recent version of the ACeDB software unless there is an interest in special features available only in modified (non-standard) ACeDBs. Use these databases as benchmarks for "normal" database behavior and do not change them in any way.

Second, set up least one database on which to experiment. This is an expendable database which can be destroyed--deliberately or by accident--with no serious loss.

Third, as you begin to customize the models and accumulate valuable data, set up another database as a safe haven for your work, i.e., a development database which will be modified only after careful testing.

Finally, establish a production version for distribution to your users.

Installing ACeDB: a very brief description

Some publicly released databases come with installation scripts. Others are simply supplied as compressed archives of the main database directory and its subdirectories. Each database should include explicit instructions for setup.

The minimum configuration for ACEDB is a directory (called the "main" database directory) and at least two subdirectories. These are "wspec" and "database". There may also be other subdirectories which provide documentation or support additional features, but ACEDB will run without them:

The "database" subdirectory is where data is stored once it is loaded into ACeDB. It contains a file called "ACEDB.wrm" plus the database itself (one or more "block.wrm" files) and other files. ACEDB.wrm has a special role. If it is missing, ACEDB assumes it should reinitialize the database. This process permanently destroys any data and opens a fresh, empty database.

"wspec" contains the configuration files you will modify to adapt ACeDB to a new organism. This is where models.wrm is located. If "wspec" is missing, ACeDB will not run.

For convenience, establish a "rawdata" subdirectory within the main directory. ACEDB looks for a directory with this name by default when loading data. The ".ace" files in this directory are not synonymous with the database. Destroying this directory and its contents may cause you great personal inconvenience, but will not affect ACeDB in any way.

To set up an empty copy of an existing database (here called "testdb"), follow the steps below.

For example, assuming you have already edited passwd.wrm:

% mkdir testdb
% mkdir testdb/database
% mkdir testdb/wspec
% mkdir testdb/rawdata
% cp acedb/wspec/* testdb/wspec
% setenv ACEDB /the/full/path/to/testdb
% set path=(/the/path/to/xace $path)
% /usr/local/bin/xace &
Some curators prefer to launch ACEDB via a shell script or an alias. Upon startup this message should appear:

If you have not established the main database directory with the correct structure, or the environment variable ACEDB is not properly defined, you will be alerted with the message below and the database will not initialize:

If you did not register your username (login name) in wspec/passwd.wrm, the messages below will appear. See also these special notes on write access if there is a problem.

If the database starts without reinitializing, then check the following:

ACEDB will only reinitialize if the file database/ACEDB.wrm is missing.

If reinitialization is successful, you will see something like this:

Creating a generic database

It is possible to initialize a completely generic database.

The change to displays.wrm forces "TestDB" to appear in the title bar of the main window. Why is this important? If you have several ACeDBs running at the same time, it will help you identify this particular database unambiguously. This step is highly recommended; it may save hours of remorse.

Save the original files, especially if you are a new curator. Note that many specialized ACEDB displays, such as for genetic maps and sequences, must be supported by specific models and the appropriate entries in options.wrm. The generic database will not drive these displays. However, it does permit the use of keysets, query tools, text windows, on-line help and other basic "non-biological" displays.

The reinitialized generic database now looks like this (with the Model class selected to show some of ACEDB's built-in classes):

Possible Problems