IUNMR MAG RES README file

This file describes the MAG RES spectrometer reservation system developed by Marty Pagel at the NMR Facility of the Department of Chemistry at Indiana University, Bloomington, IN.

This application is publicly available.
See the DOWNLOAD PAGE for details.

Legal Stuff:

This code is in the public domain. Specifically, we give to the public domain all rights for future licensing of the source code, all resale rights, and all publishing rights.

We ask, but do not require, that the following message be included in all derived works:
"Portions developed at the NMR Facility, Department of Chemistry, Indiana University, Bloomington, Indiana."

INDIANA UNIVERSITY GIVES NO WARRANTY, EXPRESSED OR IMPLIED, FOR THE SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT LIMITATION, WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE.

Contributions or suggestions regarding this effort are encouraged, and can be forwarded to chemnmr@indiana.edu.

Installation:

To successfully install this system, you need a SGI workstation with perl (in /usr/bin/perl, or you can edit all perl scripts to point to your perl location). Other UNIX platforms (with perl) should also work, but non-SGI platforms have not been tested. You also need a web server. We run the NCSA http server, which is now superseded by the Apache server; see http://www.apache.org/ for details.

Complete the form at http://nmr.chem.indiana.edu/MAG_RES/download.html.
AFTER completing the form, download iunmr_magres_v1.0.tar or iunmr_magres_v1.0.tar.Z
If you downloaded the ".Z" file, uncompress this file (type uncompress iunmr_magres_v1.0.tar.Z).
Untar the file (type tar -xvf iunmr_magres_v1.0.tar). This will create two new subdirectories in your current working directory named cgi-bin and htdocs. Each of these subdirectories has a subdirectory named MAG_RES.
Copy the cgi-bin/MAG_RES subdirectory to the cgi-bin directory of your web server (type "cp -r cgi-bin/MAG_RES /cgi-bin/"). Copy the htdocs/MAG_RES subdirectory to the htdocs directory of your web server (type "cp -r htdocs/MAG_RES /htdocs/").
We recommend that you set the ownership of these files to a non-root user and non-sys group (such as a user named "http" and a group named "http"). If this user and group don't exist, create them. Then type "chown -R http:http cgi-bin/MAG_RES htdocs/MAG_RES" from your web server directory.
Edit the .htaccess files. Add passwords to .htpasswd files. See your web server documentation for details.
Copy the htdocs/MAG_RES/spectrometer_example directory to a new directory with your spectrometer name (e.g., "cp htdocs/MAG_RES/spectrometer_example htdocs/MAG_RES/Inova400"). Edit the files in this directory tree to customize MAG_RES for your site.
Edit each file to customize MAG_RES for your site. See comments in each file. Comments specifying required or recommended changes start with the case-sensitive word "EDIT". This will require some work on your part, but it should be straightforward. If you are stuck, feel free to contact us at chemnmr@indiana.edu; we'll try to help on a time-available basis.

Our Approach:

We wanted a system which allows us to reserve blocks of time in 10 minute, 1 hour, 1 day, and multiple day increments. The daily schedules have the first three options. Staff can use the calendar pages to reserve multiple days.
We wanted a system that our users could use on their own (i.e., automatic confirmation or denial of reservation requests without staff intervention). We also wanted our users to have passwords.
We wanted to list as much information on one web browser, to reduce the need to download new pages. The vertical format allows us to list as many as 4 spectrometers on one page.
We wanted to also list on the schedule the type of probe installed and/or the type of nucleus for which the probe was tuned.
We wanted web pages that would load quickly on web browsers using computers and modems that are not state-of-the-art. Java, Java script, or VBscript were not appropriate. The current system can take a few seconds to update the display on very old computers, since the schedule table has 144 entrys/day (10 minute blocks for 24 hours), but this is only a problem on our old Macs and the Indigos---Indys, Sparc 2s, and 100 MHZ Pentiums all work fine, and certainly any workstation more recent than these models work fine too. I also dropped all graphics and most colors, which just slow down browsers.
We wanted a system that was cheap and easy to install, maintain, and manage. Perl cgi scripts, ASCII UNIX files, and html files and were the best answers.
We wanted a system that was easy to modify, that could be written with my limited programming skills and very limited time. Again, Perl cgi scripts, ASCII UNIX files, and html files were the best answers.

Files:

This system resides in two directories: cgi-bin/MAG_RES and htdocs/MAG_RES. Following the standard NCSA httpd web server format, cgi-bin and htdocs exist in the same directory, usually /usr/local/etc/httpd.

cgi-bin directory:

.htaccess (determines web accessibility)
activity.pl (queries the spectrometer to determine current activity)
change_pw.pl (changes a user's password)
extract.pl (extracts information about a user and displays html file)
finger_exp_details.pl (displays experimental details if an acquisition is in progress)
sched_request.pl (processes a reservation request - the heart of the system)
view_cal.pl (shows a calendar page)
view_sched.pl (shows a schedule for a particular day & particular spectrometer)
view_roster.pl (shows roster of users)

cgi-bin/restricted directory:

.htaccess (determines web accessibility)
.htpasswd (passwords for web accessibility)
edit_cal_form.pl (displays form for reserving multiple days via the spectrometer's calendar pages)
edit_calendar.pl (processes a calendar edit request)
rotate_database.pl (run by cron at the beginning of the month to clean logs and update calendars) This script is not included at this time. See below.
remove_sched_locks.csh (manually removes schedule lock files)
add_user.pl (adds user to roster)
del_user.pl (deletes user from roster)
rm_pw.pl (removes a user's password)

htdocs/MAG_RES directory:

.htaccess (determines web accessibility)
change_pw_form.html (html form for changing a user's password)
help.html (html file help information)
index.html (html file introductory page)
roster (file listing users that can reserve time)
sched_all.html (html file specifying frames for each spectrometer, for sites with multiple spectrometers)

htdocs/MAG_RES/restricted directory:

.htaccess (determines web accessibility)
.htpasswd (passwords for web accessibility)
add_user_form.html (html form for adding a user to the roster)
del_user_form.html (html form for deleting a user from the roster)
rm_pw.html (html form for removing a user's password)

htdocs/MAG_RES/ directory:

schedlog (log of reservation activity for that spectrometer)

htdocs/MAG_RES/spectrometer/each month directory:

1 file for each day (html file with schedule for that day)

htdocs/MAG_RES/spectrometer/calendars directory:

1 file for each month (html file with calendar schedule)

Outline of the system:

From the main page (htdocs/MAG_RES/index.html), a user can select:

a schedule for the current day for all spectrometers (htdocs/MAG_RES/sched_all.html)
a schedule for the current day for one particular spectrometer (cgi-bin/MAG_RES/view_sched.pl)
a calendar for one particular spectrometer (cgi-bin/MAG_RES/view_cal.pl)
an application for changing a user's password (htdocs/MAG_RES/change_pw_form.html)
a link to help notes (htdocs/MAG_RES/help.html)
a link to another application to view current activity on our Varian spectrometers (cgi-bin/MAG_RES/activity.pl)

After selecting view_sched.pl or sched_all.html, the user can reserve or unreserve spectrometer time. The user can also select other days or other spectrometers, or jump to a calendar. See the htdocs/MAG_RES/help.html file for additional notes.

Privileged users (i.e., the NMR Facility Staff) can annotate the PROBE column of the schedule by "reserving" time as a special user (e.g., 'bb', 'quad', 'hcn', or other probe name, or 'bb_2H', 'bb_15N', for specific probe tunings). See comments in cgi-bin/MAG_RES/sched_request.pl for additional notes.

When a user requests a reservation, cgi-bin/MAG_RES/sched_request.pl makes a few checks (e.g., you can't delete someone else's request, you have to match your password, etc.). Since there is a chance that two people could request the same reservation at nearly the same time from different locations, the program checks for this and informs the second requestor that he/she was too slow. Finally, it accepts a valid reservation and also updates the calendar page. See the comments in cgi-bin/MAG_RES/sched_request.pl for details.

On rare occasions (twice during the last 9 months), the our web server has crashed while a user was coincidentally making a reservation request. A file named htdocs/MAG_RES/spectrometer/month/daynumber.locked (where 'month' is the name of the month, and 'daynumber' is the number of the date for which the user was attempting to reserve time) will not be automatically removed from the database. This file must be manually removed before anyone else can reserve time. To automatically remove this file, an administrator can run "cgi-bin/restricted/remove_sched_locks.csh".

The database for the reservation system is a directory tree that has a separate directory for each month, and a separate file for each day in each of these month directories. This requires about 5 MBytes of files per spectrometer, but it makes the program a lot faster (it only has to read in 1 file to display 1 day). Also, each day file is a html-format file, so that the file can be quickly downloaded to the browser without requiring pre-processing.

There is also a separate file for each month of the calendar. Anyone can view the calendar and jump to specific days (through cgi-bin/MAG_RES/view_cal.pl), but only privileged users (e.g., the NMR Facility Staff) are allowed to reserve/unreserve multiple days of spectrometer time using the calendar (through cgi-bin/MAG_RES/edit_cal_form.pl and cgi-bin/MAG_RES/edit_cal_form.pl). See comments in these files for details.

The day and month database files are updated each month by a cron function (cgi-bin/restricted/rotate_database.pl) so that only the last month, the current month, and the next 10 months are available. There is also a "schedlog" file for each spectrometer, which records each transaction. rotate_database.pl truncates schedlogs to 5000 lines (approximately 1000 transactions, equal to 84 Kbytes of info, or ~2 months of transactions at our site). See comments in cgi-bin/restricted/rotate_database.pl for details. This script is not included in this distribution at this time. This script contains proprietary information specific for the IUNMR Facility. Even though this proprietary information is not related to the MAG RES system, I need to edit this script before I can add it to the distribution. Until then, schedlog files can be truncated manually, and database files can be created manually. All database files up to Oct 30, 1999, are included in this distribution. I apologize for the inconvenience.

Users can change their passwords using htdocs/MAG_RES/change_pw_form.pl and cgi-bin/MAG_RES/change_pw.pl. Privileged users can add users (using cgi-bin/MAG_RES/restricted/add_user.pl via htdocs/MAG_RES/restricted/add_user.html) and delete users (using cgi-bin/MAG_RES/restricted/del_user.pl via htdocs/MAG_RES/restricted/del_user.html). Privileged users can remove a user's password (using cgi-bin/MAG_RES/restricted/rm_pw.pl via htdocs/MAG_RES/restricted/rm_pw.html); this feature changes the user's password to "xxxxxxxx". See comments in these files for details.

Our Varian spectrometers and datastations can be queried to see if anyone is currently using these instruments (and to see details of the experiment---I've used this feature from home on occasion to troubleshoot problems with incorrect parameter selection that a student is experiencing in lab). Our web server automounts the disks from each spectrometer in order to do the full query via cgi-bin/MAG_RES/activity.pl. See comments in cgi-bin/MAG_RES/activity.pl for details.

These scripts should work past the Year 2000, with one exception. It won't account for the leap year in 2012 or later, but changing a few lines of code will account for future leap years. With any luck, SGI will acquire Microsoft by 2012 and create a better product than this hack.

For the Future:

Functions that may be added in the future, time permitting:

rejection of reservation requests or deletions for time in the past
rejection of reservation requests that are longer than the maximum allowed length (for example, we limit usage on one of our spectrometers to no more than 60 consecutive minutes between 8am and 8pm on weeekdays; therefore, schedule requests could also be limited to 60 consecutive minutes during these periods).
rejection of reservation requests made too far in the future
automatic reservation of recurring periods during weekdays or all days (i.e., we have an "open time" from 11-12 and 3-4 on weekdays on one spectrometer when reservations are not allowed---spectrometer time is 'first-come, first-served'. Currently, this time is indicated on our schedule only after we reserve this time as the "OPEN" user; it can take a while to make these reservations.)
scripts to more easily install and customize this system
change to reservation forms to initiate immediate action when pull-down menu selections are selected. Currently, a user must click on "Submit Request" after a selection is made.
change the format of the roster. Currently, the roster has fields that are used by other functions of the IUNMR web site.
improve password security.
improve file security.

Contributions are encouraged: contact chemnmr@indiana.edu.

Send comments to chemnmr@indiana.edu