Applied Research Corporation Page 1 DECUS VAX SIG Tapecopy Submission 28 April 1989 Applied Research Corporation Suite 920 8201 Corporate Drive Landover, Md 20785 (301) 459-8442 Submitted By Don Stevens-Rayburn Director of Computer Services 1 Overview Of This Submission This area contains a variety of user-mode programs and programming utilities that have been written at Applied Research Corporation and that we have found useful. Included is the full source code for each of the programs and utilities along with both object code and, where appropriate, executables. In addition, more-or-less complete user manuals and programmer manuals are included. The major components of the submission are described in the following sections. 1.1 Address Database Management The address database managment system provides a powerful set of software for automating address/telephone lists. This system supports private address databases, group-wide databases and corporate-wide databases. This program is based on the A.R.C. Forms Management System and is completely menu-driven. It has the capability of searching a database on any field or combination of fields, including up to 6 key words that are part of each record in the database. For example, is is a simple matter to request the system to display all of the entries in the database that refer to people who (1) have names beginning with the characters ST and (2) live in the state of Maryland and (3) have the key words "FORTRAN", "MACRO" and "DCL" in their record. Finally, the program can print the selected records in a variety of ways: (1) the complete record; (2) only that part of the record that the U.S. Postal Service needs, formatted for direct printing on mailing label stock; and (3) as a telephone list containing just the name and up to 2 telephone numbers. As well as two standalone programs that implement the system, there are two separate callable interfaces to make it easy to incorporate address database management into larger menu driven systems. Applied Research Corporation Page 2 Overview Of This Submission 28 April 1989 1.2 Documentation Utilities Included are two routines which we use here to assist in maintaining programming documentation. CLEANMEM is a simple program that reads a ".MEM" file produced by Digital Standard Runoff and strips off the imbedded characters that DSR leaves in the file. This is useful when you wish to use multibuffer editing to proofread DSR output. You can put the original ".RNO" file in one buffer and the "cleaned" ".MEM" file in another. The ".MEM" file can be scrolled through and read easily without the distracting control characters at the end of each line and, when you find an error or an edit that you wish to make, you switch to the buffer containing the ".RNO" file and make the change directly. At our site, this routine saves a lot of paper and a lot of wear and tear on the laser printer. DOCUMENT is a routine that searches an entire directory and extracts the comment header blocks from all of the source code files in that directory, formatting them as a DSR input file. This routine assists in maintaining programming documentation. This requires that the programmer use a standardized comment block in each program module. Each source code module in this submission contains such a block and several templates are provided. 1.3 Forms And Menus The Applied Research Corporation Forms Management System is the major part of this submission. The ARC FMS consists of a suite of subroutines and a set of FORTRAN include files contained in a text library. It is designed to assist in the coding of programs that are menu driven and/or rely on forms manipulation for data entry and editing. This set of routines is the basis for all of the menu/forms based programs included in this submission as well as a variety of other systems in production here. The ARC FMS is based on the Digital Screen Management Facility but, for example, allows you to design and manipulate forms and menus with only a few subroutine calls. For example, one can present a form to the user and allow the user to edit any field on the form with a single call to one of the FMS subroutines. 1.4 The Form/Menu Demonstration Program The Form/ Menu Demonstration Program is an example of how the ARC FMS can be used to provide a completely menu-driven system to non-technical users of a VAX. The program presented here is, in fact, a copy of the program that our finance group uses daily. The only modifications that I have made to the program prior to submitting it are to remove any proprietary software that gets run from the system. While it is unlikely that this program will be of direct use at your site, it does provide a framework for a complete menu-driven system. Should you be required to write such a system, you will find this program worth reviewing and you may be able to re-use large chunks of it. Applied Research Corporation Page 3 Overview Of This Submission 28 April 1989 1.5 The Make Facility This is yet another implementation of a Unix-like MAKE facility. It is provided here mainly because we have used it to build all of the executables in this submission and is the easiest way for you to rebuild them if you wish to modify them. MAKE is provided in two forms: first as an executable, with source code and as a DCL command file. 1.6 Portwatch V2.0 Portwatch V2.0 is yet another idle terminal killer. This version is a total rewrite of an idle terminal killer that appeared on an earlier SIG tape submitted by J. B. Fischer. This version maintains a database of each terminal port on the system. For each port, you may specify whether processes running at that terminal are eligible for deletion and at which hours of the day. In addition, you may specify whether or not warning messages are broadcast to the terminal before process deletion. As an example, here we are not so much worried about people tying up terminal lines since (at least for the moment) every terminal has its own port. But we are concerned, for security sake, that everyone log off before leaving for the day. Therefore, most interactive sessions are protected from deletion during the hours 08:00 through 18:00. If you are logged on after 18:00 but inactive, it is assumed that you have gone home and your process becomes eligible for deletion. The major exception to the above is those ports which are connected to modems. Since we only have a few modems and since, if your process is connected to a modem line but has been inactive for more than 30 minutes, it is likely that you have lost the connection and away goes your process. Finally, while it is nice to warn people before killing their process, this is not always possible. For example, if you attempt to warn a process running on a port connected to a Hayes compatible modem (or most other modems) but for which the connection has been lost, all you will accomplish is to set up an interesting dialog of error messages flashing back and forth between the VAX and the modem. In addition, we have a bunch of Professional 350's that function mostly as standalone workstations but which occasionally connect to the VAX via async lines. If the operator of one of these work stations exits the terminal emulator without logging off the VAX, attempting to send a warning sets up a similar dialog. Therefore, Portwatch was written in such a way that you can specify on a port-by-port basis whether to broadcast a warning message prior to process deletion. 1.7 QMS Kiss Driver QMSPRINTV2 is both command-line and a menu-driven interface to one of our laser printers. Again, this routine will probably not be directly useful at your site unless you happen to be running a QMS Kiss laser printer in QUME emulation mode; however, it does provide an example of how to make the full power of a laser printer available to users who have access only to EDT and/or EVE on a dumb terminal. For example, we also have an LN03 driver that was Applied Research Corporation Page 4 Overview Of This Submission 28 April 1989 written in about a day simply by copying the QMSPRINT code to a new directory and modifying it. 1.8 Show Purge There are three small programs that make up this set. First, there is the SHOWPURGE program itself which has a command line interface and which takes most of the same parameters and qualifiers as does the DCL PURGE command. However, it does not actually delete anything; rather it informs you, by default, how many files would be deleted by a PURGE and, optionally, which files. The second and third programs work together as a gentle way of reminding users to purge old versions. The first merely creates an indexed file with room for a username and a quadword time; the second, which is run at login time via SYLOGIN.COM, determines the username of the person logging on. It then looks up that username and time in the ISAM file. If the time recorded for that username is less than a month ago, the program simply closes the database and exits, thus slowing login by only a fraction of a second. On the other hand, if either the username is not in the file or if the time recorded is more than a month ago, the program enters the user name and the current time in the file and closes it. It then searches the user's directory tree and displays a message of the form: Purging ddcn:[directory...]*.* would delete nn files occupying mm blocks. This serves as a gentle reminder about purging outdated files and has met with good success here. 1.9 Telephone TELEPHONE is a autodial routine that dials a modem without the user having to know anything about which port the modem is on or even about what kind of modem it is. It is implemented as a DCL command and does allow the user to specify all of the communications parameters, including baud rate, parity etc. In addition, it can use a variety of terminal emulations/file transfer protocols and even implements a "telephone" book by using DCL symbols. For example, if you were to include the line: $ ARC :== "1-301-nnn-nnnn" in your LOGIN.COM you could issue the command $ TELE[phone] ARC and TELEPHONE would call up our machine. Once a connection has been established, TELEPHONE spawns a subprocess running the terminal emulation system of your choice. When you exit that subprocess, TELEPHONE gets control again. It makes sure that the modem has hung up properly and that it is reset to power-up defaults. The current version of TELEPHONE supports Hayes compatible modems as well as Applied Research Corporation Page 5 Overview Of This Submission 28 April 1989 DEC DF112 modems and works whether or not the port that the modem is on has even minimal modem control lines. 1.10 Time Management System TMSV41 is a time management system that allows you to keep track of what you should do and when you must do it. It also can keep track of what you have done and when you did it. The Time Management System is based on the ARC FMS and has both a command-line interface and a fully menu-driven interface. 1.11 Utilities Finally, there are a collection of utility routines. These include routines in several categories: o CLI routines for parsing the command line. These routines make it easy to determine what the user wants your program to do. o Lexical functions. Included are callable implementations of the following DCL lexicals: o F$EDIT o F$FILE_ATTRIBUTES o F$GETGPI o F$INTEGER o F$LENGTH o F$MODE o F$PARSE o F$PID o F$SEARCH o F$USER o Various functions. A small collection of functions that perform a variety of tasks such as declaring exit and AST handlers. Some of these routines have been modified from routines that others have put on previous SIG tapes. Applied Research Corporation Page 6 Directory Structure 28 April 1989 2 Directory Structure In this section, I will give a road map that explains where to find all of the various pieces of this submission by describing briefly what is contained in each subdirectory. Note that many of the subdirectories are also referred to by logical names and several are rooted directories. To build the logical name structure, execute the command procedure AAASETUP.COM contained in the subdirectory [APPLIED_RESEARCH.COMMAND_FILES]. 2.1 [APPLIED_RESEARCH] The top level directory contains only this AAAREADME file and subdirectories. 2.2 [APPLIED_RESEARCH.CDU_FILES] Logical name ARC_CDU_FILES. Contains command definition files for those routines that have command line interfaces. 2.3 [APPLIED_RESEARCH.COMMAND_FILES] Logical name ARC_COMMAND. Contains command files to assist in building and using the programs that make up the submission. 2.4 [APPLIED_RESEARCH.DOCUMENTATION] Logical name ARC_DOCUMENT. This is a rooted directory. Contains the DSR source for this file as well as subdirectories containing more extensive documentation for the various parts of this submission. 2.4.1 [APPLIED_RESEARCH.DOCUMENTATION.ADBMS] Also known as ARC_DOCUMENT:[ADBMS]. Contains both a user manual and a programmer's manual for the Address Database Management System. 2.4.2 [APPLIED_RESEARCH.DOCUMENTATION.DOCUMENT] Also known as ARC_DOCUMENT:[DOCUMENT]. Contains manuals for the CLEANMEM and DOCUMENT programs. Applied Research Corporation Page 7 Directory Structure 28 April 1989 2.4.3 [APPLIED_RESEARCH.DOCUMENTATION.FMS] Also known as ARC_DOCUMENT:[FMS]. Contains a programmer's manual for the ARC FMS. 2.4.4 [APPLIED_RESEARCH.DOCUMENTATION.INCLUDE] Also known as ARC_DOCUMENT:[INCLUDE]. Contains documentation for all of the modules that are in the text library ARC_LIBRARIES:FORTRAN.TLB. 2.4.5 [APPLIED_RESEARCH.DOCUMENTATION.MAKE] Also known as ARC_DOCUMENT:[MAKE]. Contains manuals for the MAKE program. 2.4.6 [APPLIED_RESEARCH.DOCUMENTATION.MENUSYS] Also known as ARC_DOCUMENT:[MENUSYS]. Contains programmer's manual for the Forms/Menu Demonstration Program. Since this program is not meant to be used at another site without extensive modification, there is no real user's manual. 2.4.7 [APPLIED_RESEARCH.DOCUMENTATION.PORTWATCH_V2] Also known as ARC_DOCUMENT:[PORTWATCH_V2]. Contains a programmer's manual and installation instructions for the Portwatch program. 2.4.8 [APPLIED_RESEARCH.DOCUMENTATION.QMSPRINT] Also known as ARC_DOCUMENT:[QMSPRINT]. Contains manuals for the QMSPRINT laser printer driver. 2.4.9 [APPLIED_RESEARCH.DOCUMENTATION.SHOWPURGE] Also known as ARC_DOCUMENT:[SHOWPURGE]. Contains manuals for the SHOWPURGE programs. 2.4.10 [APPLIED_RESEARCH.DOCUMENTATION.TELEPHONE] Also known as ARC_DOCUMENT:[TELEPHONE]. Contains manuals for TELEPHONE. Applied Research Corporation Page 8 Directory Structure 28 April 1989 2.4.11 [APPLIED_RESEARCH.DOCUMENTATION.TMSV41] Also known as ARC_DOCUMENT:[TMSV41]. Contains manuals for the Time Management System. 2.4.12 [APPLIED_RESEARCH.DOCUMENTATION.UTILITIES] Also known as ARC_DOCUMENT:[UTILITIES]. Contains manuals for the programming utilities. 2.5 [APPLIED_RESEARCH.EXECUTABLES] Logical name ARC_EXECUTE. Contains all of the executables supplied with this submission. 2.6 [APPLIED_RESEARCH.LIBRARIES] Logical name ARC_LIBRARIES. Contains an object library for each part of this submission as well as sharable, linkable images for the ADBMS and FMS facilities. The object library ARC_LIBRARIES:IMAGELIB.OLB contains transfer vectors for these systems. Finally, contains templates for producing programming documentation header blocks. 2.7 [APPLIED_RESEARCH.MENU_DEMO] This directory and its subdirectories are used by the Forms/Menu Demonstration Program. Also includes demonstration databases for the Address Database Management System and the Time Management System. All of the subdirectories are empty but are needed by the demonstration program. 2.8 [APPLIED_RESEARCH.SOURCE] Logical name ARC_SOURCE. This is a rooted directory. Contains a subdirectory for each of the programs that make up this submission. 2.8.1 [APPLIED_RESEARCH.SOURCE.ADBMS] Also known as ARC_SOURCE:[ADBMS]. Contains the source code for the Address Database Management System. Applied Research Corporation Page 9 Directory Structure 28 April 1989 2.8.2 [APPLIED_RESEARCH.SOURCE.DOCUMENT] Also known as ARC_SOURCE:[DOCUMENT]. Contains the source for the CLEANMEM and DOCUMENT programs. 2.8.3 [APPLIED_RESEARCH.SOURCE.FMS] Also known as ARC_SOURCE:[FMS]. Contains the source code for the Forms Management System]. 2.8.4 [APPLIED_RESEARCH.SOURCE.INCLUDE] Also known as ARC_SOURCE:[INCLUDE]. Contains the source code for all of the include modules contained in the text library ARC_LIBRARIES:FORTRAN.TLB. 2.8.5 [APPLIED_RESEARCH.SOURCE.MAKE] Also known as ARC_SOURCE:[MAKE]. Contains the source code for the MAKE utility. 2.8.6 [APPLIED_RESEARCH.SOURCE.MENUSYS] Also known as ARC_SOURCE:[MENUSYS]. Contains the source code for the Forms/Menu Demonstration Program. 2.8.7 [APPLIED_RESEARCH.SOURCE.PORTWATCH_V2] Also known as ARC_SOURCE:[PORTWATCH_V2]. Contains source code for the Portwatch program. 2.8.8 [APPLIED_RESEARCH.SOURCE.QMSPRINT] Also known as ARC_SOURCE:[QMSPRINT]. Contains source code for the QMS Kiss Laser Printer Driver program. 2.8.9 [APPLIED_RESEARCH.SOURCE.SHOWPURGE] Also known as ARC_SOURCE:[SHOWPURGE]. Contains source code for the ShowPurge set of programs. Applied Research Corporation Page 10 Directory Structure 28 April 1989 2.8.10 [APPLIED_RESEARCH.SOURCE.TELEPHONE] Also known as ARC_SOURCE:[TELEPHONE]. Contains source code for the TELEPHONE program. 2.8.11 [APPLIED_RESEARCH.SOURCE.TMSV41] Also known as ARC_SOURCE:[TMSV41]. Contains source code for the Time Management program. 2.8.12 [APPLIED_RESEARCH.SOURCE.UTILITIES] Also known as ARC_SOURCE:[UTILITIES]. Contains source for the callable lexical functions and other programming utilities. 3 Building The Programs With all of the publicity about viruses, worms and Trojan horses that is around these days, I would strongly suggest that you rebuild everything that you find on a SIG tape from sources, after you have examined those sources. I would make no exceptions even for these routines. Therefore, while I have provided both object code and executables, I give here a prescription for rebuilding the whole thing from the source code files. The simplest way to build the programs from sources is to use the MAKE utility, since there are makefiles for each piece of the submission. But, you say, how do I build MAKE without using a pre-existing executable, i.e. MAKE.EXE? The answer is that you do not need MAKE.EXE to build MAKE.EXE or any of the other executables. The MAKE utility exists in two forms on this submission; namely as an executable image and as a DCL command file. If you find MAKE useful at your site for other program development, the executable version is much preferable because is puts much less load on the system; however, if you wish to use it only to MAKE the pieces of this submission, then the command file version in the ARC_COMMAND directory is perfectly adequate. Also in the ARC_COMMAND directory is another command file, REBUILD.COM, which deletes all of the submission that is not in the form of pure ascii text; that is all executables, object modules and libraries, text libraries, etc. It then rebuilds the whole shebang directly from the source files. If you are as worried about security as you should be, this is the way that you should go. Issue the commands: $ SET DEFAULT ddcn:[top-level-directory.APPLIED_RESEARCH.COMMAND_FILES] $ @REBUILD However, even before you do this, you might want to examine the source code files further. While I am confident that these programs left our shop free of viruses, worms, Applied Research Corporation Page 11 Building The Programs 28 April 1989 Trojan horses, etc., I also know that I do not, as a matter of policy, install any software which does not come from a reputable software house unless I have been able to read the source and until I have rebuilt the executables from that source. Therefore, while this might seem like a lot of pain to go through, I have provided the complete sources and also have provided the tools to rebuild the executables. The source code modules are in a variety of languages including FORTRAN, Macro, DCL and TPU. All of these languages come with VMS with the single exception of FORTRAN. If you do not have VAX/FORTRAN on your system, you cannot rebuild this submission from the sources. There is one piece of this submission that the REBUILD command procedure cannot build, namely the TPU section file that is used as the word processing interface for the Forms/Menu Demonstration Program. To build that section file, invoke TPU with the command $ EDIT/TPU/COMMAND=ARC_SOURCE:[MENUSYS]WPSPLUS TPU will read the source file and compile it. From within EVE, press the key to get the TPU command prompt and enter the command: Command: SAVE EXTENDED EVE ARC_LIBRARIES:WPSPLUS.TPU$SECTION This procedure creates a TPU section file that is based on the DEC supplied WPSPlus emulator but with a few nice additions. 4 Running The Menu Demonstration Program NOTE The Forms/Menu Demonstration Program requires VMS V5 and a VT2xx or VT3xx compatible terminal. To run the Forms/Menu Demonstration Program, simply invoke the command procedure ARC_COMMAND:MENU_DEMO. You will then be presented with the main menu. About all you need to know about the program in order to play with it and to see what it will do is how to select a menu option. Simply use the arrow keys to move the cursor to the menu option that you wish to select and press the ,