******************************************************************************
* *
* VAX VMS Terminal reservation program *
* *** *** ******** *********** ******* *
* *
* This program will allow users to reserve a fixed number of 1/2 hour *
* slots on any available terminal. The program uses two files to store *
* user and terminal data, and automatically maintains the database to *
* be current to the latest half-hour. Many of the operating parameters *
* may be varied by adjusting the commented constants at the head of the *
* program. *
* *
* Written by: Mark Resmer - Academic Computer Center Manager *
* Box 248 *
* Vassar College *
* Poughkeepsie *
* NY 12601 *
* *
* Language: PASCAL version 2.5 *
* *
* Operating System: VMS version 3.7 *
* *
* Copyright (C) 1984 Mark Resmer - permission is hereby granted for the *
* reproduction of this software, on condition that this copyright notice *
* is included in the reproduction, and that such reproduction is not for *
* purposes of profit or material gain. *
* *
******************************************************************************
Implementation Notes
************** *****
The following program files are provided:
RESERVE.PAS - Pascal source for program
RESERVE.OBJ - Object form of RESERVE - for sites without
PASCAL compiler.
RESERVE.EXE - Executable image linked under VMS Version 3.4
WHO.WHR - Specimen terminal location file from
Vassar College. Use as an example in
creating your own file.
RESERVE.HLP - VMS Help module for system Help library
RESERVE.DOC - Description of program
IMPLEMENT.TXT - This file
To implement the program on your VMS system, you should be logged in under
the SYSTEM account (UIC [1,4]).
Basic implementation:
***** **************
The simplest implementation consists simply of copying the .EXE file to
SYS$SYSTEM or some other directory where user-written utilities are normally
kept, and defining the VMS foreign command:
$ RESERVE=="$dev:[directory]RESERVE"
in the system-wide login file.
In addition, the program MUST be installed with SYSPRV privilege, and should
probably also be installed OPEN and SHARE since it will be a heavily-used
utility. The commands to do this are:
$ MCR INSTALL
INSTALL> dev:[directory]RESERVE/PRIV=SYSPRV/OPEN/SHARE
INSTALL> /EXIT
The program requires three external files, WHO.WHR, USERS.DAT, and TTYS.DAT.
These files reside in the SYS$MANAGER directory.
The file WHO.WHR contains details of the device names and locations of all
terminals on the system. This file is a regular text file, and may be created
using any standard editor. Each line contains the entry for one terminal, in
the following format:
columns 1-5: ID code (e.g. TTA0)
columns 6-25: Location (e.g. VT100 Comp Ctr)
column 26: Reservability (an "*" means terminal is not reservable)
You must use the <space> in setting up these columns - do NOT use the <tab>!
A specimen WHO.WHR file is provided on the distribution tape to clear up any
remaining questions.
You should create WHO.WHR before attempting to use the reservation program,
otherwise you will receive a fatal error message from RESERVE.
The .DAT files will be created by the program the first time it is run. Once
this has been done, protection on the files should be set to dis-allow world
access of any kind. This prevents unauthorized tampering with the contents, but
still allows RESERVE to modify the files, since it is installed with SYSPRV.
Use the commands:
$ SET DEFAULT SYS$MANAGER
$ SET PROTECTION=W USERS.DAT,TTYS.DAT
to do this.
The only remaining chores in a basic installation are the initialization of
the TTYS.DAT file to reflect the contents of WHO.WHR, and the inclusion of
a help text into the system help library.
To initialize the TTYS.DAT file, run the reservation program, and use the "@"
command from the main menu. This command is not listed in the menu, and is
a "secret" key which gives access to the maintainance routines in the program.
These routines are only available from the UIC [1,4], to prevent unauthorized
tampering with the program. In response to the maintainance menu which should
appear on the screen at this point, specify "U" for Update. Depending on the
number of terminals on your system, the program will now take a few minutes
to create the TTYS.DAT file. Periodic messages will be issued as terminals
are added to the file. Do not be upset by the apparent slowness of the
program at this point - this is the only time it will ever be so slow - the
indexed file which is being built at this point is complex, and takes a long
time to construct!
To include the help text in the systemwide help library, use the command:
$ LIBR/HELP SYS$HELP:HELPLIB RESERVE
Your installation is now complete, and you may start using the program.
Rebuilding the program:
********** *** *******
Under some circumstances, it may be necessary to rebuild the program. There
are two ways to do this:
1. If you are installing the program under a version of VMS other than 3.4,
it may be necessary for the program to be re-linked to take account of changes
in the run-time library. To do this you can create a new .EXE file by giving
the command:
$ LINK/NOTRACE/NODEBUG RESERVE
After this, you can proceed as for a basic installation (see above).
2. To rebuild the program from scratch - i.e. in the event of modifications
made to the source code, customization of constants, etc., you will need
access to the VMS Pascal compiler, in a version of at least 2.0. The following
commands should be given:
$ PASCAL RESERVE
$ LINK/NOTRACE/NODEBUG RESERVE
After this you can proceed as for a basic installation (see above).
Customization:
*************
The program has a number of operating features which may be customized on a
site-dependent basis. These are accessible as commented constants at the
beginning of the file RESERVE.PAS. The parameters are divided into two
categories, Static and Dynamic. Dynamic parameters are those which may be
changed without rebuilding the database, i.e. as operating requirements alter.
Static parameters should be set before the program is implemented, since if
they are changed subsequently, the data files must be deleted and the whole
database re-initialized.
Dynamic parameters:
------- ----------
As supplied, the program is configured for three classes of user, determined
by UIC group. Additional classes could quite readily be added - see comments in
the source code. The first group of parameters sets the operating values for
each class:
classN Type = String Default Values = 'Faculty', 'Student', 'Courses'
Permitted values: any legal string
Names of the different classes of user.
classNl Type = Octal Integer Default Values = 1, 100, 200
Permitted values: Minimum = 0 Maximum = 377
Lower end of UIC range for each class of user.
classNu Type = Octal Integer Default Values = 77, 177, 377
Permitted values: Minimum = 0 Maximum = 377
Upper end of UIC range for each class of user.
maxN Type = Integer Default values = 20, 4, 10
Permitted values: Minimum = 1 Maximum < Maxslots
Number of outstanding reservations allowed at any time.
leadtimeN Type = Integer Default values = 21, 7, 14
Permitted values: Minimum = 1 Maximum < Maxdays
Number of days that reservations may be made in advance.
lastN Type = Integer Default values = 1, 2, 2
Permitted values: Minimum = 0 Maximum < leadtime*24
Number of hours immediately prior to a reservation that no
changes may be made.
The remaining dynamic parameters are unlikely to need changes. They are:
console Type = Integer Default value = 96
VMS device number for a VT100.
asterisk Type = Integer Default value = 26
The column in WHO.WHR which contains the no-reserve asterisk.
timoutmax Type = Integer Default value = 30
Number of seconds to wait before timing out if two users
attempt to write the same record.
Static Parameters:
------ ----------
ttnamlen Type = Integer Default value = 5
Permitted values: must be maximum VMS tty physical name
without any leading underscores or colon
Length of a terminal physical device name without punctuation.
usernamlen Type = Integer Default value = 9
Permitted values: Minimum = longest username in use.
Maximum = 12
Length of a username. At many sites usernames are no longer
than 9 characters to allow usernames and directory names to
be identical. VMS allows up to 12 characters.
N.B. PAST, SYSRES and BLANKS9 need to be altered if you change
USERNAMLEN.
maxslots Type = Integer Default value = 21
Permitted values: Minimum > largest maxN
Maximum = 63, but data file size and
system response are proportional
to this parameter, so keep as low
as possible.
Maximum number of slots that any user is allowed to reserve.
maxdays Type = Integer Default value = 22
Permitted values: Minimum > largest leadtimeN
Maximum = 63, but data file size and
system response are proportional
to this parameter, so keep as low
as possible.
Number of days covered by the system.
Internals:
*********
The source code is very fully commented and should be readily modifiable. This
section will describe general principles of operation of the program, and
detail the nature of the files created by it.
The program stores details of outstanding reservations in two indexed files.
In general all reservation information is stored in both files - giving
considerable redundancy. The eventual objective is provide routines to
allow the database to be completely recreated if either of the master
files were to become corrupt. These routines are not provided in the current
version of the program.
USER file:
---- ----
The USER file is a single-key Prologue 3 file keyed on Username. This file is
used by the program to retrieve user-specific information. All the information
in this file should also be present in the TTYS file in another form. Each user
record contains the following information:
Username - a field of USERNAMLEN characters
Slot - a sub-record corresponding to a single reservation. There are MAXSLOTS
slots in each user record. Slots are scanned whenever a reservation is made
and the first available slot is used for the new reservation. If no free slots
are available, this signifies that the user has made the maximum number of
reservations permitted at any time.
Each slot has the following fields:
TTY - the terminal code for a particular reservation
Date - the VMS absolute format date of the reservation
Time - in the format HH:MM of the reservation
Individual users' records are created the first time they use the program, and
then updated as the user adds or deletes reservations. Expired reservations
are deleted immediately prior to any attempted update - no automatic updating
takes place on a scheduled basis.
TTYS file:
---- ----
The TTYS file is triple-key Prologue 1 file. This file is used by the program
to retrieve terminal-specific, and date-specific information. Whilst most of
the information in this file is duplicated in the USER file, there are some
reservations - namely system block bookings and system reservations which
do not have any corresponding USER file entries. Each ttys record contains
the data for one day's reservations on a single terminal. The following fields
are present:
Keysymbol - this is an internally generated 5 character code that creates a
unique primary key for each terminal/day record. The code is obtained by
substituting an ASCII character (starting with character 66 - "B") for the
first letter of the terminal device code (e.g. BTA0, CTA0, DTA0 etc. for
consecutive dates of TTA0). Given the VMS coding for terminal device names,
this generates a compact code, which does not lose any significant information
from the device name.
Date - is an encoded form of date which can be sorted in alphabetical order
and yield chronological dates.
TTY - is the full device name of the terminal - in case future changes in
VMS naming conventions make the first character significant.
Slots - this is an array of 48 usernames. The elements of the array represent
successive half-hour periods during the day. An element may contain blanks -
if the terminal is available at a given time, or it may contain a username
if reserved.
TTY records are only created and removed using the maintainance routines of the
program. Updating is automatically performed by the first user to use the
program after midnight on any given day. If the program has not been used for
a while, successive updates will be performed until the database is current.
The updating procedure is complex, and deserves some further explanation. When
the program is first initialized, the TTY file slots are allocated in ascending
date order. For example if the program were initialized on 1-OCT-1983, the
keysymbols would be:
1-OCT-1983 BTA0, BTA1, BTA2 etc.
2-OCT-1983 CTA0, CTA1, CTA3 etc.
3-OCT-1983 DTA0, DTA1, DTA2 etc.
etc.
After the first nightly update has taken place, the expired date is removed
from the file, and its place taken by the new date at the end of the
reservation period which has just become legal. Thus, assuming a three-week
reservation period, after the update on 2-OCT-1983, the database would look
like this:
22-OCT-1983 BTA0, BTA1, BTA2 etc.
2-OCT-1983 CTA0, CTA1, CTA3 etc.
3-OCT-1983 DTA0, DTA1, DTA2 etc.
etc.
To allow correct indexing into these slots, a special reserved record with
the keysymbol $LOCK is provided in the file. This record serves to indicate
the current validity of the database, as well as holding the most recent value
of the index into the slot coding, and indicating to any other users on the
system whether the database is currently being updated - thus preventing
several users from trying to update the database simultaneously.
The coding of the $LOCK reserved record is as follows:
Keysymbol - $LOCK
Date - a coded form of the most recent date when the database was successfully
updated. The coding used is the same as that for all the other TTYS date
fields. This field can be checked by the program against the current date
to verify that the database is still current when updates are made.
TTY - contains one of the reserved symbols $LOCK or $OPEN. These indicate
whether the database is currently being updated or not.
Slot[1] - contains the ASCII character which currently points to the first
chronological slot in the TTYS file. This is updated with the rest of the
TTYS file.
The remaining slots in the $LOCK record are reserved for future expansion.
Multi-user access of data:
---------- ------ -- ----
The program makes extensive use of RMS record-locking facilities to ensure
data integrity despite simultaneous use of the system by multiple users.
In general, one of two courses is taken by the program when a locked record
is encountered. If the record is vital to the success of an operation, the
program enters a retry loop, and attempts to access the file at one second
intervals for a period determined by the constsnt TIMOUTMAX. If the operation
is not successful at the end of this time, an error message is displayed and
the program exits. If the operation requiring a locked record is not vital,
the program continues despite it. An example of this is when listing free
terminals - it is possible for a terminal which is actually free to be
absent from the listing if its record is currently being written by another
user.
Daily updates are likewise done in stages, and will abort without any error
message being generated in the event of record locks being encountered. Any
update which has been done up to the point of the lock is preserved, and the
next user to use the system will continue the update procedure automatically
until all records in the TTYS file have been successfully updated.
There are one or two procedures in the maintainance routines menu which demand
full completion for success. These include removal of terminals, and block
reservations. For this reason, the routines mentioned will wait indefinitely
on encountering a locked record, until the record is released by the other
user(s). For this reason, maintainance functions should normally be used
when the anticipated number of other users of the reservation system is
reasonably low.