Supervisor Series Release Notes June 1994 This file contains the release notes for Supervisor Series V5.4d. It describes any features, restrictions, changes, or additions made to the Supervisor Series in this release, and includes in- formation that is not provided elsewhere in the Supervisor Series manual set. Revision/Update Information: This is a new manual. Operating System and Version: VMS V5.0 or later Software Version: PHOTO V5.4d SUPERVISOR V5.4d Academic Computing and Research Services Western Kentucky University Bowling Green, Kentucky ________________________ 27 June 1994 Permission is granted to copy and redistribute this document for no commercial gain. The information in this document is subject to change without notice and should not be construed as a commitment by the author. The author assumes no responsibility for any errors that may appear in this document. DISCLAIMER: The software described in this document is provided "as is". No guarantee is made by the author or the author's em- ployer as to the suitability, reliability, security, usefulness, or performance of this software. Neither Western Kentucky University nor Hunter Goatley are respon- sible for any losses that may occur from the use of this software. The following are trademarks of Digital Equipment Corporation: DEC VAX VMS DECnet UCX UIS VMScluster AXP OpenVMS MultiNet is a registered trademark of TGV, Inc. __________ Copyright ©1994 Hunter Goatley. ALL RIGHTS RESERVED. Contents CHAPTER 1 INSTALLATION NOTES 1-1 1.1 COMMANDS 1-1 1.2 ON-LINE HELP 1-2 1.3 INSTALLING OVER SUPERVISOR SERIES V5.1-1 1-2 CHAPTER 2 NEW FEATURES AND BUG FIXES 2-1 CHAPTER 3 HANDIN REFERENCE GUIDE 3-1 3.1 SETTING UP HANDIN 3-1 3.2 HANDIN COMMAND QUALIFIERS 3-2 3.3 RESTRICTIONS IN THIS RELEASE OF HANDIN 3-3 CHAPTER 4 KNOWN BUGS AND RESTRICTIONS 4-1 4.1 THINGS THAT WILL HOPEFULLY BE FIXED NEXT TIME 4-1 4.2 SUPPORTED AND UNSUPPORTED TERMINAL DEVICES 4-2 4.3 PRODUCT INCOMPATIBILITIES 4-3 CHAPTER 5 PROBLEM REPORTS 5-1 iii Chapter 1 Installation Notes This chapter contains items of interest pertaining to the instal- lation of the Supervisor Series. There are four utilities that comprise the Supervisor Series: o SUPERVISOR o PHOTO o HANDIN o PLAYBACK 1.1 Commands The commands used to invoke the utilities can either be defined as foreign symbols or they can be added to the system-wide DCL command tables (SYS$LIBRARY:DCLTABLES.EXE). When the latter method is chosen, the commands are available to all users on the system (though file protections and privileges may prevent them from executing the programs). Installation Notes 1-1 The installation gives you the option of adding the commands to the DCL command tables or not. It is recommended that you do not add the SUPERVISE command to DCLTABLES. Using a foreign symbol lets only those users who need to use the utilities have ready access to them. Because PHOTO may be useful to all users, you probably will want to add the PHOTO command to the system-wide command tables. 1.2 On-line Help During the installation, you will be given the option of installing the help files for the utilities in one of the system help libraries. The system default help library is SYS$SYSROOT:[SYSHLP]HELPLIB.HLB. The installation procedure will give you the option of installing the help files in other li- braries (those defined by the logicals HLP$LIBRARY, HLP$LIBRARY_1, etc.). You may wish to insert the help files in a local library pointed to by one of the HLP$LIBRARY logicals to avoid cluttering the normal VMS help library. The SUPERVISOR help file should not be installed in a system help library if you chose not to add the SUPERVISE command to DCLTABLES. The on-line help files can be found in the directory SUPSER_ ROOT:[DOC]. 1.3 Installing Over Supervisor Series v5.1-1 If you are installing the Supervisor Series V5.4d over a v5.1 or v5.1-1 installation, there are two additional steps that must be performed manually. 1-2 Installation Notes The ADVISOR and OBSERVER utilities were combined into one program called SUPERVISOR in Supervisor Series V5.3. Before or after installing V5.4d, you must delete the ADVISE and OBSERVE verbs from DCLTABLES, if you installed them there. The following command will delete ADVISE and OBSERVE: $ SET COMMAND/DELETE=(ADVISE,OBSERVE)- /TABLES=SYS$COMMON:[SYSLIB]DCLTABLES.EXE- /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE $ INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE NOTE Be sure that you modify the correct copy of DCLTABLES.EXE- the one that's INSTALLed on your system. The file is usu- ally in SYS$COMMON, not SYS$SPECIFIC. Also, be sure you specify SYS$COMMON in the command above. You should also delete the ADVISE and OBSERVE on-line help modules from whichever library you added them. The following will delete the modules from SYS$HELP:HELPLIB.HLB: $ LIBRARY/HELP/DELETE=(ADVISE,OBSERVE) SYS$HELP:HELPLIB.HLB These steps must be performed manually because each site may have customized the command names, not installed them, put the help in different libraries, etc. Installation Notes 1-3 Chapter 2 New Features and Bug Fixes The version of the Supervisor Series that was released to DECUS was version 5.0-D. This document describes V5.4d of the Supervisor Series, as modified by Hunter Goatley, Western Kentucky University (goathunter@WKUVX1.WKU.EDU). The Supervisor Series was originally written by Bob Pasker, Bill Donner, and Terry Way. The following bug fixes were made in the Supervisor Series V5.4d: o Fixed PLAYBACK so it handles the longer records introduced in V5.4c. The following bug fixes were made in the Supervisor Series V5.4c. V5.4d: 1. The terminal port vector table was incorrectly copied, result- ing in system crashes with newer versions of PathWay. This has been corrected. 2. The internal buffer size used for data has been increased from 1024 to 8192 to try to avoid losing data in certain applica- tions. New Features and Bug Fixes 2-1 The following bug fixes were made in the Supervisor Series V5.4b: V5.4d: 1. A problem with the page protection on the P1 memory used by PHOTO occasionally allowed user-mode programs to crash the system. Programs that mismanaged the user stack could end up writing over the memory used by PHOTO. This has been corrected by correctly setting the page protections to not allow user- mode writes. The following bug fixed were made in the Supervisor Series V5.4a: 1. The SUPERVISE command would not accept /NOBROADCAST. This has been corrected. 2. SUPERVISOR was not correctly restoring all of the origi- nal terminal characteristics for the supervising terminal. Specifically, the terminal was left in ``No Broadcast''. This has been corrected. The following new features were added in the Supervisor Series V5.4: 1. A new qualifier, /BROADCAST, was added to SUPERVISOR. This qualifier causes SUPERVISOR to trap all broadcast messages received by the supervising terminal. All such messages are written to a file, whose name can be specified as a value to /BROADCAST. By default, /BROADCAST is enabled; /NOBROADCAST must be specified to prevent the trapping of broadcast mes- sages. Note that the message file is only created if messages are actually received during the session. 2. SUPERVISOR was modified to check the page size of the target terminal and print a warning to the supervising user if the size differs from the page size of the supervising terminal. If the supervising terminal is smaller than the target termi- nal, many screen-oriented applications will not be displayed properly on the supervising terminal. 2-2 New Features and Bug Fixes 3. The modules that comprise SUPERVISOR and PHOTO must be linked in a particular order to produce the correct executable im- ages. While both perform a check to ensure the image was linked properly, the SUPERVISOR check was made after some initial- ization had occurred, causing the system to crash if the image was improperly linked. SUPERVISOR and PHOTO now check for this occurrence before any initialization takes place. This prob- lem only occurred if the Supervisor Series images were rebuilt without using the MMS file. 4. The HANDIN utility has been added to the Supervisor Series. HANDIN creates a log file in a protected directory and, upon HANDIN/OFF, automatically queues the log file to a designated printer (SYS$PRINT, by default). HANDIN was designed with the academic environment in mind: students can run HANDIN to produce printouts of terminal sessions. Because the file is created in a protected directory, the student is unable to edit the log file, ensuring that the printout is an unmodified record of the terminal session. HANDIN is described in more detail in Chapter 3. With this re- lease, HANDIN is not yet an ``official'' Supervisor Series mod- ule, because it doesn't have enough features to be considered ``finished.'' 5. PHOTO is now compatible with VMS POSIX. Previous versions of PHOTO would report an ``internal consistency failure'' if POSIX was started on the system. 6. In previous versions of PHOTO, pressing during PHOTO and PHOTO/OFF could crash the system. This problem has been corrected. 7. PHOTO and HANDIN now check that all necessary privileges are enabled before executing any privileged routines. This eliminates potential problems with privilege-related errors occurring during initialization. New Features and Bug Fixes 2-3 8. A new qualifier, /ABORT, was added to PHOTO. PHOTO/ABORT ter- minates the PHOTO session and automatically deletes the log file. 9. PHOTO now includes error and informational messages that re- flect input-only recording where appropriate. Previously, the messages did not indicate the type of recording. This change affects the messages produced by PHOTO/INPUT, PHOTO/OFF, and PHOTO/STATISTICS. 10.PHOTO now provides a default filename of SYS$DISK:[]PHOTO.LOG. Previous versions of PHOTO did not supply any filename de- faults. 11.PLAYBACK was modified so that /STRIP removes rubout sequences (character, backspace, space, backspace) in addition to null characters. 12.PLAYBACK was modified so that /STRIP and /TYPE=RECORD are the default settings, since PLAYBACK is most often used to convert binary log files to normal RMS text files. 13.Miscellaneous clean-up changes were made to all of the utili- ties to increase reliability and efficiency. 2-4 New Features and Bug Fixes Chapter 3 HANDIN Reference Guide HANDIN is designed to allow students to automatically queue ter- minal session log files to a printer. The default print queue is SYS$PRINT; the user can override the print queue using the /QUEUE qualifier on the HANDIN and HANDIN/OFF command lines: $ HANDIN/QUEUE=LASER If /QUEUE is specified with HANDIN/OFF, that queue overrides the queue set with the HANDIN command. HANDIN automatically prints a flag page as proof that the file came from the SUPSER_HANDIN_LOGS directory (the filename is printed at the bottom of the flag page). 3.1 Setting Up HANDIN HANDIN is installed with SYSPRV and the logs should be created in a directory protected from access by everyone except SYSTEM. This ensures that the files cannot be edited before they are printed. HANDIN uses the logical name SUPSER_HANDIN_LOGS to locate the protected directory. By default, SUPSER_ROOT:[HANDIN] is used. The SUPSER_ROOT:[HANDIN] directory should be created with a command like the following: HANDIN Reference Guide 3-1 $ CREATE/DIR/PROT=(S:RWED,O,G,W) SUPSER_ROOT:[HANDIN] The directory should be located on a disk without disk quotas (see Section 3.3 for more information). The definition of SUPSER_ HANDIN_LOGS should be added to the SUPSER_STARTUP.COM in SUPSER_ ROOT:[COM]. $ define/system/exec supser_handin_logs device:[directory] HANDIN log files are normally deleted immediately after printing. However, the log file can be left in the directory if the user logs out while a HANDIN session is active, for example. You should set up a batch procedure to delete HANDIN logs older than some date. For example, the following command will delete all log files older than 3 days: $ date = f$cvtime("-3-","ABSOLUTE") $ DELETE SUPSER_HANDIN_LOGS:*.*;*/BEFORE='date' 3.2 HANDIN Command Qualifiers The HANDIN command can be defined in SYLOGIN.COM as a foreign command: $ HANDIN :== $SUPSER_ROOT:[EXE]HANDIN.EXE You can also add the command to the system-wide DCLTABLES using the following commands: $ SET COMMAND SUPSER_ROOT:[EXE]HANDIN.CLD- /TABLES=SYS$COMMON:[SYSLIB]DCLTABLES.EXE- /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE $ INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE The HANDIN command accepts the following qualifiers, which are described in the PHOTO Reference Guide: o /ABORT 3-2 HANDIN Reference Guide o /VERSION o /BUFFER_SIZE o /STATISTICS o /QUEUE The /QUEUE qualifier accepts a queue name as a value. The queue must be either a print, terminal, or server queue. 3.3 Restrictions in This Release of HANDIN The following items will be addressed in a future version of HANDIN: o PHOTO can be used to stop a HANDIN session, which will leave the HANDIN log in the log directory. o There is no built-in size limit of a HANDIN log file. The SUPSER_HANDIN_LOGS directory should be created on a disk with no disk quotas; otherwise, all users needing to use HANDIN must have a quota entry on the HANDIN disk. HANDIN Reference Guide 3-3 Chapter 4 Known Bugs and Restrictions This chapter describes the known bugs and restrictions of the Supervisor Series V5.4d. 4.1 Things That Will Hopefully Be Fixed Next Time The following items are limitations of the Supervisor Series V5.4d. These things will, hopefully, be corrected in the next version: o SUPERVISOR data may be lost while SPAWNed. SUPERVISOR V5.4d includes the ability to spawn a subprocess while supervising a terminal. However, terminal I/O on the target terminal is not buffered properly for displaying on the supervising terminal; upon logging out of the subprocess, some of the terminal output may be displayed, along with a message indicating how many characters were missed (though this number isn't necessarily accurate). Spawning a subprocess in SUPERVISOR V5.4d should be done spar- ingly, unless the missed output is not critical. Known Bugs and Restrictions 4-1 o When the supervising terminal toggles XOFF for the target ter- minal, XON must also be toggled from the supervising terminal. The target cannot resume output via . 4.2 Supported and Unsupported Terminal Devices The Supervisor Series V5.4d has been successfully tested with the following terminals: o Normal physical terminal ports (TTAx:, TXAx:, etc.). o LAT terminal devices (LTAx:) created by terminal servers and by the SET HOST/LAT command. o Terminals with virtual terminals (VTAx:) associated with them. o FT devices, which are pseudo-terminals created by FTDRIVER, the pseudo-terminal driver used by DECwindows Motif and included with VMS. o TW devices, which are pseudo-terminals created by PYDRIVER and TWDRIVER, the old DECwindows pseudo-terminal drivers. These drivers are also used by the public domain utilities BOSS and PHOTO (the other one). o MultiNet terminals (NTY devices). MultiNet is an implementation of TCP/IP for VMS. o TN devices, which are network terminals logged in via UCX telnet over TCP/IP. o PCL devices, which are created by PacerLink, an AppleTalk implementation by Pacer. 4-2 Known Bugs and Restrictions The following terminals are not supported: o RT devices, which are network terminals logged in via SET HOST over DECnet. o WT devices, which are UIS VT100 pseudo-terminals (VWS). o VAX 6XXX-series console terminals. The 6xxx-series console subsystem doesn't allow for monitoring like normal termi- nals. The console can be observed, so PHOTO and SUPERVISOR in OBSERVER mode will work. Attempting to start SUPERVISOR in ADVISOR mode on such a console will result in an error message being displayed. 4.3 Product Incompatibilities The Supervisor Series utilities are not compatible with the fol- lowing products and may crash the system, depending on usage: o Session Support Utility (SSU), a DEC layered product o DEC/Test Manager, a DEC layered product o ACMS, a DEC layered product o Terminal Fallback Facility (TFF), a component of VMS o Third-party terminal monitoring utilities, such as those sold by Raxco and Network Dynamics. All of the products listed above modify the terminal UCB in the same manner as the Supervisor Series, but in an incompatible fashion. It is hoped that these restrictions will eventually be eliminated. Known Bugs and Restrictions 4-3 Chapter 5 Problem Reports An electronic mailing list exists to discuss the Supervisor Series software and report problems. The address of the mailing list is SUPSER-L@WKUVX1.WKU.EDU. You can subscribe to this list by sending an E-mail message to MXserver@WKUVX1.WKU.EDU, with the command "SUBSCRIBE SUPSER-L" appearing in the body of the message. Archives of the mailing list are available via anonymous FTP from ftp.spc.edu ([192.107.46.27]) in directory [ANONYMOUS.MACRO32.LISTS]. Problem Reports 5-1