****************************************************************************** * * * 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 in setting up these columns - do NOT use the ! 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.