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