Overview and Contents

This document describes some of the metadata used by the DLXS middleware. The dlxs database contains metadata about the collections and the collection groups.

Contents:

• Database schema
• Database fields
• IMPORTANT: Interaction between database rows, users, DLXS Middleware and collmgr
  • Two rows: Release and Production
  • Three or more rows: Release, Production and individual developers

Database schema

The Collection Manager (collmgr program) maintains all collection and group information in tables. These tables are the following:

These tables serve to identify and locate the various modules, objects, and search restrictions that are used by the class middleware to serve each collection available in the various classes. See more on the tables in the database in the collmgr documentation.

Some of the columns contain data that are required; others contain optional data. Multiple values, which are allowed in some fields, are entered through collmgr, into the appropriate fields one value per line.

User IDs

All but the DbStructure and Version tables have a field called userid. userid can take on several values with very specific meaning. One is that of the dlxsadm. The other important value is production. Finally, another value might be that of a specific developer logged into collmgr, say smith. These are explained here.

The userid dlxsadm is referred to as the release user. The middleware will read rows keyed by userid dlxsadmn from these tables when the following are true:

• the userid is dlxsadm
• the environment variable DLPS_DEV is set to 1
• a DLXS CGI program is being run from the release directory; e.g; $DLXSROOT/b/bib/.

The userid production is referred to as the production user. The middleware will read rows keyed by userid production from these tables when:

• when the environment DLPS_DEV is not set

The userid smith, for example, is referred to as the development user. The middleware will read rows keyed by this userid when:

• the userid is smith
• when the environment DLPS_DEV is set to smith
• the executable used to run the middleware is located in smith's development directory which corresponds to the value of the DLXSROOT environment variable (e.g., /l1/dev/smith) normally set by smith's virtual host, e.g. smith.dev.umdl.umich.edu

This will allow smith to perform testing based on collections and groups of his choice that he can set up using the Collection Manager. Most institutions will not need to use this third type of user because there will not be a need to have several users work against the same collections. For those institutions, it will only be necessary to log in to the Collection Managmer as dlxsadm. All data management can happen through that userid.

Additional privilege for dlxsadm

In addition to being able to delete, add, or edit collections and groups associated with the dlxsadm user, this administrative login userid has other privileges. The dlxsadm will be able to add fields to classes, and delete fields from classes. This will change the structure of the tables associated with the classes, and will update the DbStructure table to reflect the new schema.

Note that when the userid dlxsadm deletes a collection or group, a backup of the deleted collection or group is kept in the appropriate backup tables.

The user dlxsadm also has privileges to release classes to production. "Releasing to production" effectively copies every dlxsadm row to a row keyed by the userid production. This distinction between dlxsadm and production, allows you to work on collections and groups independent of the collections and groups that are accessible by the version of the middleware that is running in production.

Database fields

For information on the individual fields, please see the help file used by the Collection Manager (collmgr).

Interaction between database rows, users, DLXS Middleware and the Collection Manager

Two rows: Release and Production

Most users of DLXS Middleware will likely have the following situation. A collection manager will be making changes to the collection information database, changing, adding or deleting collections. Then at some point, the new set of collections to be delivered will need to go into production. The database holds both sets of rows.

• One set of rows containing collections and groups as they are tested in a development environment. When ready, these will be moved to production.
• One set of rows containing collections and groups that are used by the production environment.

Middleware

The middleware can be set to look at either the release rows (for testing and subsequent release) or the production rows (rows actually being used by the production system). This is accomplished through the setting of the environment variable DLPS_DEV. If set to 1, the release rows and their values are used by the middleware. If set to 0 or not present, the production rows are used by the middleware.

Therefore, two environments need to be set up: one for release and one for production. These can be set up as separate virtual hosts on a web server, each defining its own environment variables, or as servers on two separate machines. At DLPS, we have a separate development machine and more than one production machine, but it seems to be the case that most DLXS partners have one machine where both development and production are done.

In either case, the situation is that there are two sets of rows in the database and two servers (whether they are virtual hosts or actual separate physical hosts is irrelevant). (In addition there is an extension to this scheme whereby each individual developer can have his/her own set of rows in order to develop without disturbing the database values in the release and production rows.)

For example, assume there is one machine with two virtual hosts (dev.domain.edu and prod.domain.edu). The configuration for the virtual host dev.domain.edu should have a SetEnv directive setting DLPS_DEV to 1. The configuration for the prod.domain.edu virtual host should not include this environment variable setting.

When the dev.domain.edu server is asked to run the middleware it will access the release rows in the database and use their values.

Note: As mentioned, if you want to run the cgi programs on the command line or within a debugger, you'll need to set your own shell environment to include a DLPS_DEV variable set to 1.

Likewise, the production rows and their values will be used for any cgi call to the prod.domain.edu virtual host because the user that the web server runs as (e.g., nobody) will not have the DLPS_DEV environment variable set. This is because no SetEnv directive in the prod.domain.edu's virtual host configuration will have been set.

Collection Manager

When running the Collection Manager cgi, you should log in as user dlxsadm in order to add, remove, edit rows that are the release rows. When you want the working production system to actually use your changes, the Collection Manager lets you "move release rows to production", which actually copies the rows keyed by the user dlxsadm to rows keyed by the user production. You cannot directly manipulate the production rows. This layer of protection is something akin to "checking in" data. Click here for more on the collmgr workflow.

Three or more rows: Release, Production and individual developers

If you do work where different users require individualized versions of the database rows, as we do at DLPS, the databases can also be set up with, in addition to the release and production rows described above, rows keyed by username. In addition to the material below, please refer also to the instructions related to configuring this username extension.

Here, there are at least three sets of rows: the same two as before, but with additional sets for individual developers. A user can:

• check out rows from release (essentially a copy of the rows from those marked as release, creating or overwriting the user's previous rows for those collections)
• view or edit rows keyed by his/her user name
• check in rows to release (essentially a copy of the rows from those keyed by the user name, overwriting release's previous rows for those collections)
• later, using the Collection Manager, logged in as dlxsadm, one can "move" release to production as described above

Middleware

The middleware can be set to use the release rows or the user name rows. This is accomplished by:

• Having the DLPS_DEV variable set to 1, as in the two row scenario explained above. If running through a browser, the host web server will have to be configured to have the DLPS_DEV variable set, or if on a command line or in a debugger, the user will have to have the variable set in his/her environment.
• Running the middleware CGI programs.

The middleware can also be set to use the user specific rows. This is generally done to test new functionality in the middleware or to try out potential changes to the database field values. This is accomplished by:

• Having the DLPS_DEV variable set to username. If running through a browser, the developer's virtual host will have to have been configured to have the DLPS_DEV variable set, or if on a command line or in a debugger, the user will have to have the variable set in his/her environment.

Collection Manager

When running the Collection Manager cgi, in order to make changes to the rows keyed by your user name, you should log in as username. This allows you to check out rows from the release rows, view and edit your own rows, and check them back in to release. Click here for more on the Collection Manager workflow.

Imagine your username is smith. When you log in to the Collection Manager cgi, you can check out rows from the release rows (they are copied) to rows that are keyed by the userid smith. You can make changes to these rows so that when you access them through the middleware (running under a virtual host with DLPS_DEV set to smith and DLXSROOT set to smith's copy of the code tree under development), the values from those rows will be used. If or when you check them back in, the values you entered/changed in the smith-keyed rows will be copied into the corresponding release rows.

Later, when ready, logging in as dlxsadm, one can "move" release to production.