Session_Support_Utility_______________________ Installation and User's Guide Order Number: AA-JB84C-TE This document describes how to install and use the Session Support Utility on the VMS operating system. Operating System and Version: VMS Version 5.0 or higher Software Version: Session Support Utility Version 1.3 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ First Printing, April 1989 Revised, March 1990 Revised, April 1991 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1991. All rights reserved. Printed in U.S.A. The Reader's Comments form at the end of this document requests your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: VAX, VAXcluster, VMS, VT, and the DIGITAL logo. This document is available on CDROM. S1630 This document was prepared with VAX DOCUMENT, Version 1.2. ________________________________________________________________ About This Guide This manual provides step-by-step instructions for installing and using the Session Support Utility (SSU) on a VMS system. SSU is a software product that lets users log in to and maintain multiple independent sessions on a VMS system. SSU software is intended for use with Digital's VT330, VT340, and VT420 video terminals. SSU software communicates with the single-line, multiple-session firmware in the terminal. For more information on these terminals, see the VT330/VT340 documentation. Intended Audience This manual is for system managers, operators with system privileges, and users of the Session Support Utility. You should have a working knowledge of the VMS operating system. System managers should read this manual before beginning installation. Document Structure This manual is divided into two chapters. Chapter 1 describes how to install SSU on a VMS system. Chapter 2 describes the commands used to enable SSU. The chapter includes sections on user commands and system manager commands. o Section 2.2, User Commands, describes commands that a user enters to enable SSU on a terminal line. v o Section 2.3, System Manager Commands, describes commands that a system manager uses to associate SSU with certain terminal lines. The chapter also describes known problems with SSU Version 1.3. Associated Documents The following documents may be useful during installation: o Guide to VMS Software Installation o Guide to VMS System Management and Daily Operations o VMS Developers Guide to VMSINSTAL o VMS License Management Utility Reference Manual o Installing and Using the VT330/VT340 Video Terminal Conventions The following conventions are used in this document: __________________________________________________________ Convention_______Meaning__________________________________ UPPERCASE Uppercase characters indicate DCL commands, qualifiers, and parameters. italics Italic characters in command formats indicate that you are to substitute a word or value of your choice. bold For online display, bold is used in examples and command formats to show the characters that you should enter. red In the printed book, red ink is used in examples to show the commands you should _________________enter.___________________________________ vi 1 ________________________________________________________________ Installing SSU Software This chapter describes the procedure for installing the Session Support Utility and its associated device driver on the VMS operating system. The procedure is automated. First, you mount the kit volumes when prompted. Then, you respond to queries issued by the system during the installation process. Read this manual and the Guide to VMS Software Installation before you begin the installation. After you install SSU successfully, inform system users who have VT330, VT340, and VT420 terminals. 1.1 Requirements The following are requirements for performing the installation: o System manager privileges. o VMS Version 5.0 or higher. o Any supported VMS terminal controller or an Ethernet terminal server (LAT). o A minimum of 2000 blocks of free disk space. If there is not enough disk space, the procedure exits and an error message is displayed. o PAK registration. SSU supports the License Management Facility (LMF) provided by VMS, and requires that you register a Product Authorization Key (PAK). Register your PAK with the following command: $ @SYS$UPDATE:VMSLICENSE.COM See the VMS License Management Utility Reference Manual for more information about LMF. Installing SSU Software 1-1 o Approximately 30 minutes of installation time, depending on your type of media and your system configuration. o The Guide to VMS Software Installation. o If you have a previous version of SSU installed on the system, make sure no one is using SSU. Before you install a new version, the system manager must disable SSU on all terminal lines. o To use SSU, a user must have a VT330, VT340, or VT420 terminal. SSU communicates with single-line, multiple-session firmware in the terminal. For more information, see Installing and Using the VT330/VT340 Video Terminal. 1.2 New Features in SSU Version 1.3 VMS Version 5.4 is supported. 1.3 Restrictions SSU is not supported on the OPA0: device, due to internal differences between this device and all other terminal devices on VMS. 1.4 Kit Contents The SSU installation kit consists of the save set SSUnnn.A. The save set contains the following files: o TDDRIVER.EXE o SSU.EXE o SSU$HELP.HLB o SSU.HLP o KITINSTAL.COM o SSUnnn.RELEASE_NOTES o SSU$IVP.COM o SSU$STARTUP.COM This kit conforms to the standards specified in the VMS Developers Guide to VMSINSTAL. 1-2 Installing SSU Software 1.5 Before You Start Before you start the installation, read this section and the entire installation procedure. This section provides the system manager with hints for solving some common installation problems. 1.5.1 Installing SSU on a VAXcluster System On a VAXcluster system with a common system disk, you install SSU on only one node. However, you must execute the startup command file on all nodes. You can either enter the command on each node in the cluster or reboot each node. Before you execute the startup command file, add the following command to the file: $ @SYS$MANAGER:SSU$STARTUP 1.5.2 Reinstalling SSU You cannot reinstall SSU while it is in use or when someone is executing the SSU startup command file. If you do, the system reports an error. You must reboot the system or wait until SSU is no longer in use. 1.5.3 Enabling Virtual Terminals All VMS systems (Version 4.0 and higher) have the virtual terminal capability. If the system manager enables virtual terminals, individual users can enable multiple SSU sessions on their terminals without assistance from the system manager. If virtual terminals are not enabled, users cannot enable SSU until the system manager uses the SSU INSERT command (Section 2.3.1). SSU INSERT associates SSU with a given terminal device. To enable virtual terminals on your system, use the following steps: 1. Connect the VTA0 device: $RUN SYS$SYSTEM:SYSGEN SYSGEN> CONNECT VTA0/NOADAPTER/DRIVER=TTDRIVER Installing SSU Software 1-3 2. Set the terminal lines to /DISCONNECT. You can set individual hardwired or modem lines to /DISCONNECT in the system startup file. However, to set LAT (terminal server) lines to /DISCONNECT by default, you must set the SYSGEN parameter TTY_DEFCHAR2 to include the DISCONNECT characteristic. 1-4 Installing SSU Software To check the current setting, log in to a LAT line and issue a SHOW TERMINAL command. If the current setting is No Disconnect, change the SYSGEN parameter by using the following commands: $ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE CURRENT SYSGEN> SHOW/HEX TTY_DEFCHAR2 ... SYSGEN> SET TTY_DEFCHAR2 SYSGEN> WRITE CURRENT The new parameter settings take effect when you reboot the system. 1.5.4 Changing Default Terminal Characteristics On SSU lines, you cannot use the SET TERMINAL/PERMANENT command to change terminal characteristics. An SSU line is a line that is associated with SSU (SSU INSERT command) or has SSU enabled (SSU ENABLE command). To change the permanent characteristics on an SSU line: 1. Log out of that line. 2. If SSU INSERT was used, use the SSU REMOVE command. 1.5.5 Preventing SSU from Automatically Disabling Sessions SSU normally disables multiple sessions when you log out of your last session. To prevent this, issue the SET TERMINAL/NOHANGUP command before you enable sessions. If your terminal is set to /NOHANGUP, there are two ways to disable sessions: o Select the Disable Sessions feature in the VT330/VT340/VT420 Set-Up Directory. o Use the SSU DISABLE command. Installing SSU Software 1-5 1.5.6 Using TDA Devices If SSU is installed, the DCL SHOW DEVICES command shows some TDA devices. o There is always one master template TD device (TDA0). o There is one TD device for each terminal line that is either associated with SSU or has SSU enabled. o There is one TD device for each session opened on the terminal. 1-6 Installing SSU Software For example, if there is one terminal using SSU with two sessions opened, there are four TD devices. The TD devices for each session are eliminated when the sessions are logged out. The error count displayed by SHOW DEVICES for TD devices represents protocol errors detected during multiple sessions. These errors include using SSU ENABLE when the terminal is not set up for multiple sessions, or turning your terminal off. These errors do not necessarily indicate hardware problems. 1.6 Installation Procedure Install the SSU driver on the VMS system as follows. Before you start, read Section 1.5 and the complete installation procedure. 1. Log in to the system manager's account. 2. Invoke VMSINSTAL by entering the following command: $ @SYS$UPDATE:VMSINSTAL SSUnnn device OPTIONS option_list SSUnnn Is the save set name of the product you are installing. This name contains the product's utility name, version number, and update number. device Identifies the device where the distribu- tion volumes are mounted. OPTIONS Must be included if you specify any options for the installation. option_ Is a list of installation options. list For example, to install Version 1.3 of SSU on device MTA0:, enter the following command: Installing SSU Software 1-7 $ @SYS$UPDATE:VMSINSTAL SSU013 MTA0: OPTIONS N SSU013 Indicates SSU Version 1.3. The 013 corresponds to 1.3. MTA0: Indicates the magnetic tape device. Enter the name of the actual device you plan to use. OPTIONS N Generates a copy of the release notes. You must specify OPTIONS N to print the release notes, display them, or both. The release notes are always copied to SYS$HELP. The VMSINSTAL procedure responds with the following messages: VAX/VMS Software Product Installation Procedure It is 1-FEB-1991 at 14:07 Enter a question mark (?) at any time for help. 1-8 Installing SSU Software 3. A series of questions follow. You must enter Yes (Y), No (N), or a question mark (?) for help. * Are you satisfied with the backup of your system disk [YES]? YES If you are satisfied with the backup, enter Yes. If you enter No, VMSINSTAL aborts the installation procedure. 4. Mount the first kit volume of the utility. Enter Yes when ready. _MTA0: allocated Please mount the first volume of the set on MTA0: * Are you ready? YES %MOUNT-I-MOUNTED, SSU mounted on _MTA0: 5. The procedure continues as follows: The following products will be processed: SSU V1.3 Beginning installation of SSU V1.3 at 14:08 %VMSINSTAL-I-RESTORE, Restoring product saveset A... The procedure checks whether there is enough disk space to install SSU, then ensures that you are running VMS Version 5.0 or higher. If either test fails, the installation procedure issues an error message and exits. Otherwise, the procedure processes the files on the first volume. 6. The procedure lists options, then asks you to choose an option. You should always print a copy of the release notes for reference. The procedure prompts you as follows: Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes Installing SSU Software 1-9 * Select option [3]:2 * Queue name [SYS$PRINT]: Job SSU013 (queue SYS$PRINT, entry 1745) started on LPA0 * Do you want to continue the installation [N]? YES %VMSINSTAL-I-RECMOVED, The product's release notes have been successfully moved to SYS$HELP 1-10 Installing SSU Software 7. The procedure asks you if you want to purge files. During this installation, new files will be provided to replace existing versions. You may purge these older versions to save disk space, or keep them if you feel they may be of use. Purging is recommended. * Do you want to purge files replaced by this installation [YES]? YES If you enter Yes, the procedure deletes all older versions of the utility, replacing them with new files. If you enter No, the old files remain. In either case, the help library is always updated and purged. 8. The procedure asks you if you want to run the Installation Verification Procedure (IVP): Most products provide an Installation Verification Procedure (IVP) which verifies the completeness and accuracy of the installation. You may wish to run the IVP immediately after installation. * Do you want to run the IVP after the installation [YES]? YES 9. The procedure now copies installed files to their proper directories, which completes the installation. 10.If you answered Yes in step 8, the Installation Verification Procedure (IVP) runs. The IVP indicates the terminals on which it is testing SSU. [Testing SSU INSERT on device _OPA0:] ...refused. [Testing SSU INSERT on device _TTA0:] ...refused. [Testing SSU INSERT on device _TTA1:] ...refused. [Testing SSU INSERT on device _TTA2:] ...passed. *** SSU V1.3 passed all tests! *** Installation of SSU V1.3 complete at 14:14. VMSINSTAL procedure done at 14:14 Installing SSU Software 1-11 1.7 Making SSU Software Available to the System After you install SSU on VMS, perform the following steps to make SSU available to the system: 1. To load TDDRIVER.EXE automatically each time the system starts up, include the following command in the SYSTARTUP.COM file: $ @SYS$MANAGER:SSU$STARTUP.COM 2. Create the symbolic name SSU by including the following command in the system login file: $ SSU :== $SYS$SYSTEM:SSU 1.8 Update Releases Digital issues update releases for SSU. Each update includes new distribution media labeled similarly to the media in the original release. To update your system, use the procedure described in Section 1.6 and the cover letter that comes with the media. The following changes are made in each update release: o The version number is incremented. o New versions of all files are supplied. o The release notes file, SSUnnn.RELEASE_NOTES, is updated to include all changes made to the product since the previous release. When you install any SSU update release, you do not need to install previous versions. An SSU update replaces any previous versions. 1-12 Installing SSU Software 2 ________________________________________________________________ Using SSU Software This chapter describes the Session Support Utility commands you use to enable multiple sessions on a terminal line. The way you enable multiple sessions depends on whether or not the system manager has enabled virtual terminals (See Section 1.5.3). 2.1 SSU With or Without Virtual Terminals If virtual terminals are enabled, individual users can enable multiple sessions on their terminals, without assistance from the system manager (Section 2.2). If virtual terminals are not enabled, users cannot enable SSU until the system manager associates SSU with their terminal device (Section 2.3). If there are many multiple- session terminals, the system manager may want to create a command file that associates each terminal device with SSU at system startup. ________________________NOTE ________________________ The command formats described in this manual assume that the system manager has provided a symbolic name for SSU by including the following line in the system login file: SSU :== $SYS$SYSTEM:SSU This command lets users access SSU by entering SSU commands at the DCL prompt. If this symbolic name is not provided in the system login file, users can access SSU by entering the following command at the DCL prompt: Using SSU Software 2-1 $ RUN SYS$SYSTEM:SSU _____________________________________________________ 2.2 User Commands This section describes SSU commands that users may enter to control multiple sessions on their terminals. There are three user commands: ENABLE, DISABLE, and SHOW. 2.2.1 ENABLE The ENABLE command lets you enable multiple sessions on your terminal. The command has one optional parameter, a physical terminal device name. If you do not specify a device name, the command enables multiple sessions on the current terminal. The format of the command is as follows: ENABLE optional-device For example, to enable multiple sessions on the current terminal line, enter the following: $ SSU ENABLE This command works only if you are using a virtual terminal line (VTxx:) or if the system manager has associated SSU with the user's terminal line. (See Section 2.1.) After you enter the ENABLE command, you can use your VT330, VT340, or VT420 terminal to run multiple sessions. ________________________NOTE ________________________ Before you use the ENABLE command, you must set the terminal for single-line, dual-session operation. See Installing and Using the VT330/VT340 Video Terminal for details. _____________________________________________________ 2-2 Using SSU Software 2.2.2 DISABLE The DISABLE command lets you disable the use of multiple sessions on your terminal. The command has one optional parameter, a physical terminal device name. If you do not specify a device name, the command disables multiple sessions on the current terminal. The format of the command is as follows: DISABLE optional-device For example, to disable multiple sessions on the current terminal, enter the following: $ SSU DISABLE After you enter the DISABLE command, you cannot use multiple sessions on that device until you enter another ENABLE command. If any sessions are active when you enter the DISABLE command, they are disconnected or logged out. ________________________NOTE ________________________ You can also disable multiple sessions by using your terminal's setup feature. See the terminal's user guide for details. _____________________________________________________ 2.2.3 SHOW The SHOW command displays the status of SSU on a given terminal device. This command has one optional parameter, a terminal device name. If you do not include a device name, SSU displays the status of the current terminal. The format of the command is as follows: SHOW optional-device For example, to display the status of SSU on the current terminal, enter the following command: $ SSU SHOW If multiple sessions are enabled, SSU displays the following message: Multiple sessions are associated with this line. Using SSU Software 2-3 If multiple sessions are not enabled or not available on the device, SSU displays the following message: Multiple sessions are not associated with this line. If your system does not have virtual terminals enabled, use the SHOW command to check if the system manager has associated multiple sessions with the terminal line. 2.3 System Manager Commands This section describes SSU commands that a system manager uses to associate multiple sessions with a given terminal device. The commands described in this section require system privileges. There are two system manager commands, INSERT and REMOVE. You only have to use these commands if your system does not have virtual terminals enabled (Section 1.5.3). 2.3.1 INSERT The INSERT command lets the system manager associate SSU multiple-session capabilities with a given terminal device. The command requires one parameter, a physical terminal device name. The format of the command is as follows: INSERT device For example, to associate SSU with terminal device TTA1:, enter the following: $ SSU INSERT TTA1: The INSERT and ENABLE commands create devices named TDxx: that are displayed from DCL commands, such as SHOW TERMINAL and SHOW DEVICE. ________________________NOTE ________________________ The system manager does not have to use the INSERT command on systems that have virtual terminals enabled. Users can use SSU on their terminal lines by entering the ENABLE command. (See Section 2.1.) _____________________________________________________ 2-4 Using SSU Software 2.3.2 REMOVE The REMOVE command lets the system manager disassociate SSU multiple-session capabilities from a given terminal device. This command is required only if the system manager used INSERT to associate SSU with the device. The command requires one parameter, a physical terminal device name. The format of the command is as follows: REMOVE device For example, to disassociate SSU from terminal device TTA1:, enter the following: $ SSU REMOVE TTA1: ________________________NOTE ________________________ If the device is currently in use, the REMOVE command does not disassociate the device until the user or system manager disables session management and the user logs out. _____________________________________________________ 2.4 Known Problems with SSU Version 1.3 The following list describes the known problems with Version 1.3 of SSU. o The SSU ENABLE command does not report an error if the terminal is not set up for multiple sessions. If you use the SSU ENABLE command when your terminal is not set up for multiple sessions ( "Sessions on Comm1" not selected in the VT330/VT340/VT420 Global Set-Up screen), you will see some meaningless characters on your terminal. This problem also occurs if you are working on a terminal that does not support SSU (such as a VT100 or VT240). After a timeout period of approximately 12 seconds, you can use your terminal again. Your terminal line is now a TDA device until you log out, as if the system manager had issued the SSU INSERT command. o Using the SSU DISABLE command on a session terminal device can disable the terminal line. Using SSU Software 2-5 If you use the SSU DISABLE command, you should enter the command without any parameters (for your terminal line) or with a physical terminal device name parameter. If you specify a session terminal device (TDAxxx) or its associated virtual terminal (VTAxxx), you may not be able to use the terminal line until the associated process is stopped. Normally, you do not need to use the SSU DISABLE command, since SSU automatically disables multiple sessions when you log out of both sessions. 2-6 Using SSU Software