NMR RESERVATION SOFTWARE

This document includes virtually all of the information that you will need to download, install, and configure the reservation software for your facility. If you have already read this information and simply need to download the software, CLICK HERE.

July 15, 1998 - Version 3.7 of the reservation software is now installed on the ftp server. Version 3.6 is still available, but there should be no reason to use 3.6. Version 3.7 fixed a few minor problems and added a mechanism for changing existing reservations and deleting the remaining portion of a reservation that is partially elapsed. This has make files that are good through Solaris 2.4.

May 9, 2002 - Added version 4.2 of the reservation software to the ftp server. In addition to a few minor bug fixes,Version 4.2:

  • Has provision for larger rule bases - This simply increased the size of the sys_rules array definition from 10 to 20 to avoid segmentation faults if there were too many rules defined.
  • has provision for block sizes different from 10 minutes. The only constraint is that an even number of blocks fit into an hour. permissible block sizes are therefore 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, and 60 minutes long. There is an extra column in reserve.conf to specify this block size.
  • has provision for proxy reservations - the master user (usually vnmr1) can make a proxy reservation for any user, without any rule checking. Useful for the administrator that needs to fix problems.
Makefile here is valid for Solaris 2.6 and Solaris 2.7. Have not compiled on Solaris 8 yet.

The reservation software was written to replace the paper sign-up sheets that we had been using at each instrument for reserving instrument time. This has had the benefit of letting the computer be an impartial arbiter of the reservation rules and permitting users to reserve time remotely rather than having to come to the lab to make a reservation. The software is written in C and runs on a UNIX workstation. I originally compiled and tested it under SunOs 4.1.3 and it is currently running under Solaris 2.4. There is no reason that this should not compile on any UNIX platform - there are no Sun-specific features used or needed. The only package required is the curses library, which is normally included with most if not all UNIX systems. Curses is a package that permits using ASCII-based windows on terminals with an addressable cursor in a terminal-independent manner. As long as the terminal used is defined in the terminfo files (or termcap on some BSD systems), the curses library will take care of all the cursor positioning functions so that programs written with curses do not have to include terminal-dependent code. Reserve is written using curses for all user interactions, and makes use of pop-up windows for a number of functions. The package has been compiled using both the Sun cc compiler as well as the Gnu gcc compiler.

The program does not include any mechanism for physically controlling access to instruments (RS-232 interruption, etc.), does not include any provision for billing based on reservations (although the records are stored and could be processed), and does not include provision for comparing time reserved with time actually used, although again the records are there if someone wants to add that code. All of the reservation rule types are embedded in separate C procedures, and there is no mechanism for adding new rule types except to write the procedure and modify the rule structure to allow for the extra conditions required. New ideas for rules to implement are always welcome, although I don't guarantee that they will be added to the code. If nothing else, I will offer advice on how to go about adding a new rule type.

The reservation program itself is controlled by a configuration file (reserve.conf) that defines the instrument systems that will be listed on the main menu. The program runs in two different modes, a user mode and an instrument mode. In the user mode, a user runs the program, makes one or more reservations on one or more systems, and exits. In the instrument mode, the program goes into an infinite loop after an instrument is selected, permitting users to login and make reservations. Users may not exit the program or select a different instrument in the instrument mode. This is intended to run on a dedicated terminal at the instrument so that there is always a display available showing current reservations, and a terminal for users to make reservations at the instrument. The instrument mode can be terminated by the master user for the system. Any time a reservation is made or deleted, a record is made in a transaction log, showing the user, the action, the date and time, and whether the login was remote or local (user mode program or instrument mode). The user interface to the program has provision for making and deleting reservations, examining the owner of a reservation, displaying an instrument status file, displaying a listing of the rules available for making reservations, and displaying a 1 week summary of reservations. In addition, if a user attempts to make a reservation and the system indicates that it is not a valid reservation, the user can ask for an interpretation of the rules, displaying each rule and why it failed.

Making and deleting reservations requires write access to the data base. In order to avoid reservation conflicts, the system obtains a write lock on the reservation file before making or deleting a reservation. In the case of making a reservation, there is a 30 second timer started that will release the write lock if the user has not completed the reservation. This prevents one user from locking the data base and prohibiting anyone else making a reservation. Deleting reservations will not display a time, but will require a write lock. Since the information is obtained from the user before the write lock is requested, there is no particular time constraint problem. Reservations may only be deleted by the user who made the reservation.

The reservation data base has one file per instrument per day. The primary limitation that is imposed by this structure is that a single reservation is limited to a maximum of 24 hours and cannot span midnight. The reservation day is broken into 10 minute blocks for the purpose of making and displaying reservations. A separate rules file, one per instrument, defines the reservation rules for each system. These rules permit the system administrator to define starting and ending times for different rules, a maximum number of 10 minute blocks permitted during a given period, an earliest time when reservations may be made, and a limit to the number of days in advance that a reservation may be made. Representative rules from our systems include:

30 minutes from 8 AM to 10 PM, time between 8 AM and 2 PM may be reserved after 7 AM, time between 2 PM and 10 PM may be reserved after 1 PM, all reservations are same-day only, not days in advance.

Unlimited amount of time between 10 PM and 8 AM, time may be reserved after 2 PM, 3 days in advance.

In addition to a general class of rules for a system, it is possible to write group or user restrictive rules, that are specific to a single group or user and are more restrictive than the general rules. They are used instead of the general rules. It is also possible to write group or user permissive rules, that are less restrictive than the general rules. These rules are used in addition to the general rules. There is a 'readme' file included with many more details and examples for writing reservation rules.

In order for any user to make a reservation on the system, they must login to the reservation system, typically using their INSTRUMENT userid and password. This limits reservations for an instrument to those users authorized to use the system. There are currently three different possibilities for getting user information into a user data base for the reservation system. You can import XL/VXR user data records from Varian 4000 series data systems, using either LimNet or floppy disks with V_HELPER. You can import user data from UNIX based systems, using either the /etc/passwd file (and shadow file if present), or the NIS+ tables with netgroups if you are using that system. Third, you can define your own system, providing a file with user names, passwords and groups. There is a 'readme' file that provides more information about importing user information from the spectrometer. In addition, it is possible for anyone to login to the system with the userid 'browse' and just examine the reservations without the ability to make or delete reservations.

The TAMU FTP server is no longer available for anonymous downloads of software packages. If you are interested in a copy of the current version of the reservation software, just send me an email (gregory.wylie@chem.tamu.edu) and I will email a copy of the tar file to you. The package will now run under RedHat Enterprise Linux - let me know if that is the version you need, since there are a number of changes necessary to make this work.

Once you get the reserve.tar file, place it in the directory you use to store source code and detar it. This will generate the reserve subdirectory with all the goodies. Go to the reserve directory, read the sampledb/readme.sample file for information on the sample data base (sample userid/passwd pairs), and run 'make demo' to compile the package and run the reserve program on the sample data base. 'make install' will install the executables on your system. Read the various readme files and understand how the package works before attempting to install it on your system. The directory sampledb has all of the sample data base files and includes a readme file. The directory scripts has some sample scripts for automating the operation and also includes a readme file.

On my system, I created a UNIX user named reserve, with no password in the password field. This account accesses only the reservation program and permits users without an account on the UNIX workstation to reserve time on one of the spectrometers. This user entry points to a script in /usr/local/autofunctions/reserve instead of a login shell so that only the reservation program may be run. The script for reserve is included in the scripts directory. Also included there is a copy of several of the crontab entries I use to keep the data bases updated automatically.

I hope you find this to be a useful program. Please let me know if you port it to another operating system (and include the modifications necessary for makefile), find any bugs or problems, or have suggestions for enhancements or improvements. Right now I consider this to be a 'finished' program, but I am sure there will be at least minor fixes and changes over the next several months. Information about new versions and updates will be posted here.

Questions, comments, and suggestions are always welcome. Please send them to gregory.wylie@chem.tamu.edu