______________________________________________ VAX APL Installation Guide AA-P143H-TE June 1991 June 1991 June 1991 This document contains instructions for installing VAX APL on the VMS operating system. This document also explains how to read the online release notes before or after installing the product. This is a revised Revision Update Information: Revision Update Information: Revision Update Information: document. VAX VMS Version 5.4 Operating System: Operating System: Operating System: Version 4.0 Software Version: Software Version: Software Version: digital equipment corporation digital equipment corporation digital equipment corporation maynard,massachusetts maynard,massachusetts maynard,massachusetts __________________________________________________________ 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 June 1991. All rights reserved. The Reader's Comments form at the end of this document requests your critical evaluation to assist in preparing future documentation. DEC, DECnet, DECwindows, DECterm, VAX, VAXcluster, VAXstation, VT200, VT300, VT102, VMS, Digital and the Digital logo are trademarks of Digital Equipment Corporation. HDSAVT, HDS201 and HDS221 are trademarks of Human Design Systems, Inc. Tektronix is a trademark of Tektronix, Inc. ________________________________________________________________ Contents Contents Contents Preface Preface Preface .................................................. v 1 Preparing to Install VAX APL................. 1 1.1 Prerequisite Software.................... 1 1.2 Accessing the Online Release Notes....... 1 1.3 Installation Procedure Requirements...... 2 1.4 User Account Quotas and Privileges....... 4 1.5 VMS License Management Facility.......... 5 1.6 Using VMSINSTAL.......................... 6 2 Installing VAX APL........................... 7 2.1 Installing VAX APL on a VAXcluster....... 16 2.2 Installing VAX APL on a VAXstation....... 17 3 After the Installation....................... 20 3.1 PCDRIVER, the Terminal Driver Software... 20 3.2 Control Character Keywords............... 21 3.3 Modifiable Files......................... 22 3.4 Moving the QAPL Application.............. 22 4 Running the Installation Verification Procedure Separately......................... 24 5 Error Conditions............................. 24 6 Installing VAX APL as a Shared Image......... 25 7 Maintenance Updates.......................... 26 8 Determining and Reporting Problems........... 27 9 Sample Installation.......................... 28 iii ________________________________________________________________ Preface Preface Preface This document describes how to install VAX APL on the VMS operating system. It is intended for system managers. This document applies to VAX APL V4.0. A major version number is represented by the digits to the left of the decimal point, and the maintenance update version number is indicated by the digits to the right of the decimal point. Keep this document with your distribution kit. You will need this document if you need to reinstall VAX APL. For more information about installing VAX APL on VMS systems, see your processor-specific installation /operations guide. The installation procedure is described step-by-step and is, for the most part, self-explanatory. The system prompts you to answer questions and to change volumes, and waits for you to tell it to continue. This installation guide contains samples from an installation of VAX APL. These samples may not be exact replications of your installation output. Conventions Used in This Document Conventions Used in This Document Conventions Used in This Document The following conventions are used in this supplement. v __________________________________________________________ __________________________________________________________ Conventions Meaning Conventions Meaning Conventions Meaning UPPERCASE Uppercase words and letters, used in format examples, indicate that you should type the word or letter exactly as shown. Color Color in examples shows user input. Ctrl/x The phrase Ctrl/x indicates that you must press the key labeled Ctrl while you simultaneously press another key; for example, Ctrl/c, Ctrl/y, Ctrl/z. [option] Brackets indicate that the enclosed item is optional. (Brackets are not optional in the syntax of a directory name in a file __________________________________________________________ specification.) You should press the Return key after entering a command or responding to a prompt. vi 1 Preparing to Install VAX APL 1 Preparing to Install VAX APL 1 Preparing to Install VAX APL Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to check the contents of your kit against this information. If your kit is damaged or if you find that parts of the kit are missing, call your Digital customer services representative. The installation procedure prompts you to mount the volumes. For more information on how to mount distribution media, see your processor-specific installation/operations guide, which also details several options to the installation procedure. 1.1 Prerequisite Software 1.1 Prerequisite Software 1.1 Prerequisite Software VAX APL V4.0 requires VAX VMS V5.4. Contact your Digital customer services representative if you have questions about the compatibility of other software products with this version of VAX APL. ________________________ ________________________ Note Note Note If you are using a VAXstation and accessing a host VAX system to run VAX APL, VAX APL must be installed on both the host VAX system and the VAXstation. _____________________________________________________ 1.2 Accessing the Online Release Notes 1.2 Accessing the Online Release Notes 1.2 Accessing the Online Release Notes VAX APL provides online release notes. The prompt to display or print the release notes during the installation appears in step 5 of the installation procedure when you invoke VMSINSTAL with the OPTIONS N parameter. To obtain the release notes after the installation, type or print the file SYS$HELP:APL040.RELEASE_NOTES. Online help also directs you to the release notes file. After the installation, enter the following command: $ help apl release_notes 1 1.3 Installation Procedure Requirements 1.3 Installation Procedure Requirements 1.3 Installation Procedure Requirements The installation of VAX APL takes approximately 10 to 45 minutes, depending on the type of media and your system configuration. Before installing VAX APL, you must have the following privileges and resources: o SETPRV privileges, or CMKRNL, WORLD, and SYSPRV privileges o A minimum of 7000 blocks of free disk space during installation; 5200 to 6100 blocks are used after installation depending on the optional files selected during installation o A minimum of 20 contiguous free global pages and 4 global sections to install APLSHR.EXE as a protected shared image (required) o A minimum of 950 contiguous free global pages and 2 global sections to install APL.EXE as a known shared image (optional) o A minimum of 930 contiguous free global pages and 2 global sections to install QAPL.EXE as a known shared image (optional) o A minimum of 100 contiguous free global pages and 1 global section to install APLMSG.EXE as a known shared image (optional) o Enough disk space (in number of disk blocks) for a copy of the file SYS$LIBRARY:DCLTABLES.EXE o Buffered I/O byte count (BYTLM) of 8192 bytes (minimum) and subprocess creation quota of 1 (minimum) to prevent failure of the Installation Verification Procedure (IVP) ________________________ ________________________ Note Note Note You must ensure that your system has the necessary global page and global section SYSGEN quotas for the installation. Failure to do so could cause the DCL tables to be corrupted in some situations. _____________________________________________________ 2 To determine the number of available global pages on your system, invoke the VMS Install utility by entering the following command: $install :== $install/command_mode $install Then, enter the following command: INSTALL>list/global/summary Summary of Local Memory Global Sections ?? Global Sections Used, ???/???? Global Pages Used/Unused INSTALL>exit When you issue these commands, the system displays a summary of the number of global sections used, the number of global pages used, and the number of global pages unused. To exit from the VMS Install utility, enter the EXIT command and press Return. VAX APL requires the following global pages: o APLSHR: approximately 20 global pages (required) o APL: approximately 950 global pages (optional) o QAPL: approximately 930 global pages (optional) o APLMSG: approximately 100 global pages (optional) If fewer pages are available, delete an existing known im- age with the VMS Install utility, or increase the GBLPAGES system parameter with the VMS System Generation utility (SYSGEN), editing the file SYS$SYSTEM:MODPARAMS.DAT and then invoking the AUTOGEN command procedure, SYS$UPDATE:AUTOGEN.COM. For more information on the AUTOGEN command procedure, see your processor-specific installation/operations guide. You can determine the number of available global sections by invoking SYSGEN as follows: 3 $run sys$system:sysgen SYSGEN>use current SYSGEN>show gblsections SYSGEN>exit The last number displayed is the maximum number of global sections. Compare this number to the number of global sections in use displayed by the VMS Install utility. If the number of global sections used plus the number needed by VAX APL exceeds the maximum number of global sections, you must increase the number of available global sections before you can install VAX APL. To increase the number, increase the GBLSECTIONS system parameter by editing the file SYS$SYSTEM:MODPARAMS.DAT and then invoking the SYS$UPDATE:AUTOGEN.COM procedure. For more information on the AUTOGEN.COM procedure, see your processor-specific installation/operations guide. If the number of global sections used plus the number needed to install VAX APL is less than the maximum number of global sections, you can exit from SYSGEN and continue. 1.4 User Account Quotas and Privileges 1.4 User Account Quotas and Privileges 1.4 User Account Quotas and Privileges To use VAX APL, each account must have TMPMBX and NETMBX privileges and the following requirements: o AST limit (ASTLM) 10 (minimum) o Buffered I/O quota (BIOLM) 10 (minimum) o Buffered I/O byte count quota (BYTLM) 8192 (minimum) o Direct I/O quota (DIOLM) 10 (minimum) o Enqueue quota (ENQLM) 10 (minimum) o Open file limit (FILLM) 10 (minimum) o Paging file quota (PGFLQUOTA) 2500 pages (minimum) o Subprocess creation quota (PRCLM) 3 (minimum) o Working set size (WSDEF) 250 pages (minimum) 500 or more pages recommended 4 Use the VMS Authorize utility (AUTHORIZE) to compare the current values of these quotas with the requirements for VAX APL. For example, the account used in the following example is the SYSTEM account: $set default sys$system $run authorize UAF>show system To change the values of these quotas, use the VMS Authorize utility MODIFY command. For more information, see the . ___ _________ _______ ______ VMS Authorize Utility Manual 1.5 VMS License Management Facility 1.5 VMS License Management Facility 1.5 VMS License Management Facility You must register your VAX APL software license. To use VAX APL with the vector processor, the APL-HPO license must be registered. The license registration information you need is contained in the Product Authorization Key (PAK) that is shipped with VAX APL. The PAK is a paper certificate that contains information about the license you have to run a particular piece of software. To register a license, first log in to the system manager's account, SYSTEM. You have a choice of two ways to perform the registration: o Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When the system prompts you for information, respond with data from your Product Authorization Key (PAK). o Issue the LICENSE REGISTER DCL command with the appropriate qualifiers that correspond to information on the PAK. For complete information on using LMF, see the ___ _______ VMS License in the VMS documentation set. __________ _______ ______ Management Utility Manual 5 1.6 Using VMSINSTAL 1.6 Using VMSINSTAL 1.6 Using VMSINSTAL After you log in to a privileged account to install VAX APL, invoke VMSINSTAL, the command procedure that installs this product. An example of this procedure is shown in steps 1 and 2 of Section 2. The VMSINSTAL command procedure has the following syntax: $ @SYS$UPDATE:VMSINSTAL APL040 [OPTIONS N] _____ ddcu: VMSINSTAL prompts you for the product and device names if you do not supply these first two parameters. If you wish to be prompted for the product and device names and to display or print the release notes, enter the following: $@sys$update:vmsinstal You can also enter an asterisk (*) in place of APL040. If you are installing from magnetic tape, you can use the asterisk to save installation time; the asterisk causes VAX APL to be installed with a minimum of tape passes. _____ ddcu: ddcu: ddcu: Represents a device name where the distribution volumes will be mounted for the VAX APL installation media, where is the device code, is the controller code, and is __ _ _ dd c u the unit number. It is not necessary to use the console drive to install VAX APL. If you do use the console drive, after the installation, you should replace any media you removed from the drive. MUA0: is the device name used in examples in this document. OPTIONS N OPTIONS N OPTIONS N Is an optional parameter you should provide if you want to be prompted to display or print the release notes. If you do not include the OPTIONS N parameter, VMSINSTAL does not prompt you to display or print the release notes. VMSINSTAL permits the use of several other options. For more information on the other options, see your processor- specific installation/operations guide. When you invoke VMSINSTAL, it checks the following: o Whether you logged in to a privileged account. Digital recommends that you install software from the 6 system manager's account with your default device and directory set to SYS$UPDATE. o Whether you have adequate quotas for installation. VMSINSTAL checks for the following quota values: _ ASTLM = 24 _ BIOLM = 18 _ BYTLM = 18000 _ DIOLM = 18 _ ENQLM = 30 _ FILLM = 20 VMSINSTAL checks whether the following conditions exist. If so, discontinue the conditions before resuming the installation procedure. o Whether DECnet is up and running o Whether any users are logged in to the system If VMSINSTAL detects either of these conditions, you will be asked whether you want to continue the installation. If you want to continue, enter Y and press Return. If you want to stop the installation, enter N and press Return. 2 Installing VAX APL 2 Installing VAX APL 2 Installing VAX APL This section contains excerpts from the installation procedure and explains each step. Defaults appear in brackets ([]) throughout the installation procedure. To use the default response, press Return. To abort the installation procedure at any time, press Ctrl/y. When you press Ctrl/y, the installation procedure deletes all files it has created up to that point and then returns you to DCL level. If you want to retry the installation procedure after pressing Ctrl/y, you must proceed from step 2. 7 Step 1: Log in to a privileged account and set your Step 1: Log in to a privileged account and set your Step 1: Log in to a privileged account and set your default device and directory to SYS$UPDATE. default device and directory to SYS$UPDATE. default device and directory to SYS$UPDATE. Username:system Password: $set default sys$update Step 2: Invoke VMSINSTAL. Step 2: Invoke VMSINSTAL. Step 2: Invoke VMSINSTAL. $@sys$update:vmsinstal apl040 mua0: options n VAX/VMS Software Product Installation Procedure Vx.x It is dd-mmm-yyyy at hh:mm. Enter a question mark (?) at any time for help. Use the VMSINSTAL command procedure to install the product. %VMSINSTAL-W-ACTIVE, The following processes are still active: processname processname * Do you still want to continue anyway [NO]? y If non-system processes are running, VMSINSTAL will list the active processes. If you want to continue the installation, enter Y and press Return. Press Return to stop the installation procedure. * Are you satisfied with the backup of your system disk [YES]? If you are satisfied with the backup of your system disk, press Return. Otherwise, enter N and press Return to discontinue the installation. 8 Step 3: Insert the installation kit volume. Step 3: Insert the installation kit volume. Step 3: Insert the installation kit volume. Please mount the first volume of the set on MUA0:. * Are you ready? y %MOUNT-I-MOUNTED, APL mounted on _APLSYS$MUA0: The following products will be processed: APL V4.0 Beginning installation of VAX APL V4.0 at hh:mm %VMSINSTAL-I-RESTORE, Restoring product saveset A... To indicate that you want to continue the installation, mount the volume, enter Y, and press Return. Step 4: Choose a release notes option. Step 4: Choose a release notes option. Step 4: Choose a release notes option. This step applies only if you specified OPTIONS N in step 2. Additional Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above * Select option [2]: Choose the appropriate option by entering the option number and pressing Return. If you choose option 1, VMSINSTAL displays the release notes on line immediately. You can terminate the display at any time by pressing Ctrl/c. If you choose option 2, VMSINSTAL prompts you for a queue name. Either enter a queue name or press Return to send the file to the default output print device. * Queue name [SYS$PRINT]: 9 If you choose option 3, VMSINSTAL displays the release notes on line immediately. Press Ctrl/c at any time to terminate the display. VMSINSTAL then prompts you for a queue name. Either enter a queue name or press Return to send the file to the default output print device. If you choose option 4, VMSINSTAL continues with the installation. ________________________ ________________________ Note Note Note This version of the release notes file installed by VMSINSTAL is labeled with the current product name and version number. Take care not to delete release notes for previous versions of VAX APL. _____________________________________________________ Next, VMSINSTAL displays the following prompt: * Do you want to continue the installation [N]?: y If you want to continue the installation, enter Y and press Return. If you press Return, VMSINSTAL stops the installation. The installation copies the release notes to SYS$HELP and displays the following message. %VMSINSTAL-I-REMOVED, Product's release notes have been moved to SYS$HELP. Step 5: Respond to License Registration Queries. Step 5: Respond to License Registration Queries. Step 5: Respond to License Registration Queries. The installation procedure displays license information about your product and then asks if you have registered and loaded your authorization key for VAX APL. The following example shows that information: Product: APL Producer: DEC Version: 4.0 Release Date: 29-JUL-1991 * Does this product have an authorization key registered and loaded?y Enter Y and press Return if you have registered and loaded your authorization key. 10 If you have not registered and loaded your authorization key, you must answer N to this question. You have to register and load your product authorization key to successfully complete the installation. If you have not done so, you should stop the installation, register and load your product authorization key, and then restart the installation, beginning with step 2. During the installation procedure, the VAX APL LMF key is invoked. The VAX APL-HPO key will be invoked for installations using the vector processor. Step 6: Select installation options. Step 6: Select installation options. Step 6: Select installation options. This kit contains an Installation Verification Procedure (IVP) to verify the correct installation of the VAX APL interpreter. It can be run prior to the conclusion of this procedure by answering "YES" to the IVP prompt or invoked after the installation as follows: $ APL/TERM=TTY/SILENT SYS$COMMON:[SYSTEST.APL]APL$IVP * Do you want to run the IVP after the installation [YES]? The Installation Verification Procedure (IVP) runs tests to check whether the installation procedure was successful. Press Return to run the IVP after the installation. If you do not want to run the IVP, enter N and press Return in response to the prompt. * Do you want VMS Workstation Software (VWS) fonts [NO]? The VMS Workstation Software fonts are optionally available for installation. The workstation fonts are needed to support APL character display on VAXstations running VMS Workstation Software V4.1 Press Return if you do not want to install the VMS Workstation Software fonts. Enter Y and press Return if you want to install the VMS Workstation Software fonts. This version of VAX APL can display the APL characters on the DECwindows terminal. To do this, the APL fonts must be installed on the DECwindows server and the server must be restarted after the VAX APL installation finishes. * Do you want DECwindows fonts [YES]? 11 If you want to display the APL characters on the DECwindows terminal, the fonts must be installed. Press Return to install the DECwindows fonts. If you do not want to install the DECwindows fonts, enter N and press Return. Along with the 75 dpi fonts, you can optionally install the 100 dpi fonts. * Do you want 100 dpi video fonts installed [NO]? Optionally, the 100 dpi(dots per inch) fonts for the DECwindows terminal can be installed on the DECwindows server. If you want to install the 100 dpi fonts, enter Y and press Return. If you do not want the 100 dpi fonts installed, press Return. This kit contains tools which read and write APL workspaces in WSIS (Workspace Interchange Standard) format to allow the transportation of workspaces between VAX APL and other APL implementations. It is your option to place WSIS in your [SYSLIB] area. * Do you want WSIS [YES]? Tools to read and write APL workspaces in WSIS (Workspace Interchange Standard) format are optionally available with this installation. To install the WSIS tools, press Return. Enter N and press Return if you do not want to install the WSIS tools. This kit contains annotated versions of the tools which read and write APL workspaces in WSIS (Workspace Interchange Standard) format. It is your option to place WSINCOM and WSOUTCOM in your [SYSLIB] area. * Do you want WSINCOM and WSOUTCOM [NO]? The annotated versions of the tools that read and write APL workspaces in WSIS (Workspace Interchange Standard) format are optionally available for installation. If you want to install the annotated versions of these tools, enter Y and press Return. If you do not want to install these tools, press Return. 12 This kit contains the APL meta-functions It is your option to place METAFNC in your [SYSLIB] area. * Do you want the APL meta-functions [NO]? The APL meta-functions are optionally available for installation on your system. To install the meta- functions, enter Y and press Return. Press Return if you do not want to install the APL meta-functions. * Do you want to purge files replaced by this installation [YES]? The directories SYS$LIBRARY and SYS$SYSTEM may contain previous versions of VAX APL files. These files are replaced during the installation with new files, but the old files are not automatically purged. Purging is recommended. In response to the purging prompt, press Return to purge the files or enter N and press Return to keep them. Step 7: Read informational messages. Step 7: Read informational messages. Step 7: Read informational messages. The VAX APL installation procedure produces a number of informational messages that report on the progress of the installation. %VMSINSTAL-I-RESTORE, Restoring product save set B . . . The APL help file will now be installed in the help library. If any user attempts to access online help during this time, the installation may fail. If the procedure fails, you must restart the installation procedure. You may want to notify any users not to access online help until this step of the procedure is completed. * Enter Y when you are ready to continue? y The APL help file has been successfully installed in the help library. Users can now access online help without endangering this installation procedure. To indicate that you are ready to continue the installa- tion, enter Y and press Return. 13 No further questions will be asked. %VMSINSTAL-I-RESTORE, Restoring product saveset C . . . %VMSINSTAL-I-RESTORE, Restoring product saveset D . . . %VMSINSTAL-I-RESTORE, Restoring product saveset E . . . The following files will be left on disk: SYS$SYSTEM:APL.EXE [new] SYS$MESSAGE:APLMSG.EXE [new] SYS$HELP:HELPLIB.HLB [modified] SYS$LIBRARY:DCLTABLES.EXE [modified] SYS$SYSTEM:QAPL.EXE [new] SYS$HELP:VAXAPL.HLB [new] SYS$LIBRARY:VAXAPL.HLP [new] SYS$LIBRARY:APL.CLD [new] SYS$LIBRARY:APL.HLP [new] SYS$HELP:APL040.RELEASE_NOTES [new] SYS$LIBRARY:APL$VT220_FONT.FNT [new] SYS$LIBRARY:APL$VT240_FONT.FNT [new] SYS$LIBRARY:APL$VT240_FONT_132.FNT [new] SYS$LIBRARY:APL$VT320_FONT.FNT [new] SYS$LIBRARY:APL$VT320_FONT_132.FNT [new] SYS$LIBRARY:APL$VT330_FONT.FNT [new] SYS$LIBRARY:APL$VT330_FONT_132.FNT [new] SYS$LIBRARY:APL$VT340_FONT.FNT [new] SYS$LIBRARY:APL$VT340_FONT_132.FNT [new] SYS$COMMON:[SYSFONT.DECW.USER_75DPI]APL_TERMINAL*.DECW$FONT [new] SYS$COMMON:[SYSFONT.DECW.USER_75DPI]APL_SESSION*.DECW$FONT [new] SYS$LIBRARY:DECW$MOTIF$DXMSHR.EXE [copied if no previous version] SYS$LIBRARY:DECW$MOTIF$XMSHR.EXE [copied if no previous version] SYS$LIBRARY:DECW$MOTIF$DXTSHR.EXE [copied if no previous version] SYS$LIBRARY:APLSHR.EXE [new] SYS$LIBRARY:APLSYS.OBJ [new] SYS$LIBRARY:APLDISP.OBJ [new] SYS$LOADABLE_IMAGES:PCDRIVER.EXE [copied if no previous version] SYS$LIBRARY:PCDRIVER.OBJ [new] SYS$LIBRARY:PCLOADER.COM [new] SYS$LIBRARY:SMG.AAS [new] SYS$LIBRARY:GKS.AAS [new] SYS$COMMON:[SYSTEST.APL]APL$IVP.APL [new] SYS$COMMON:[SYSTEST.APL]APL$IVPKIT.COM [new] SYS$STARTUP:APL$STARTUP.COM [new] SYS$LIBRARY:APLTAP.EXE [optional WSIS] 14 SYS$LIBRARY:WSIN.APL [optional WSIS] SYS$LIBRARY:WSOUT.APL [optional WSIS] SYS$LIBRARY:WSINCOM.AAS [optional annotated WSIS] SYS$LIBRARY:WSOUTCOM.AAS [optional annotated WSIS] SYS$LIBRARY:METAFNC.AAS [optional meta-functions] SYS$LIBRARY:QWDFMT.AAS [optional meta-functions] SYS$COMMON:[SYSEXE]APL$SM_CCT.EXE [new] SYS$COMMON:[SYSEXE]APL$SM_DECW.EXE [new] SYS$COMMON:[SYSLIB]WSPRINT.APL [new] The SYS$HELP:HELPLIB.HLB and SYS$LIBRARY:DCLTABLES.EXE files are updated to include the new versions of the VAX APL Help text and the APL command line definition. If you entered Y in response to the VMS Workstation Software fonts option in step 6, the UIS$LOAD_FONT_APL.COM and DVWS*.VWS$*FONT files will be put into SYSFONT if it exists. If SYSFONT does not exist, they will be put in SYS$LIBRARY. A sample startup command procedure, APL$STARTUP.COM is put in SYS$STARTUP. This procedure is also used to insure that APLSHR.EXE is correctly installed before running the IVP. The success of the installation is indicated by the following message: %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... If the installation procedure is successful, the new or modified files are moved to their target directories. If you entered Y in response to the prompt that requests a file purge at step 6, previous versions of the VAX APL files are now purged. Step 8: Observe the Installation Verification Procedure. Step 8: Observe the Installation Verification Procedure. Step 8: Observe the Installation Verification Procedure. If you chose to run the IVP in step 6, VMSINSTAL now calls the IVP to verify that VAX APL was installed successfully. If the IVP was successful, the following messages appear on the screen: VAX APL V4.0 Installation Verification Procedure completed successfully. Installation of APL V4.0 completed at hh::mm 15 Step 9: End the installation procedure. Step 9: End the installation procedure. Step 9: End the installation procedure. VMSINSTAL procedure done at hh:mm $ logout SYSTEM logged out at dd-mmm-yyyy hh:mm:ss.ss When the product installation procedure is complete, you can choose to install more products or to log out (as shown here). If you removed any media from the console drive before beginning the installation, you should replace it now. VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the system manager's account and you want to restore these symbols, you should log out and log in again. 2.1 Installing VAX APL on a VAXcluster 2.1 Installing VAX APL on a VAXcluster 2.1 Installing VAX APL on a VAXcluster If you want to run VAX APL on multiple nodes of a VAXcluster, first check to see that you have the appropriate software license. Then, follow these steps after installing VAX APL: 1. Issue the LICENSE LOAD command to activate the license on each node in the VAXcluster on which VAX APL is to be executed as described in the ___ _______ __________ VMS License Management ). _______ ______ Utility Manual 2. Run SYS$STARTUP:APL$STARTUP.COM on each node of the cluster that has a software license. $ @sys$startup:apl$startup 3. If APL character support for Digital VT200 series ter- minals, Digital VT300 series terminals, HDS terminals and VAXstations is wanted, run SYS$MANAGER:PCLOADER.COM on each node of the cluster. $ @sys$manager:pcloader 16 4. To use the product on other nodes in the VAXcluster, you must replace the version of the DCL tables that is installed on the other VAXcluster nodes. To do this, perform the following steps: a. Log in to a node on the cluster. b. Run INSTALL and enter the following command at the INSTALL> prompt: INSTALL> replace sys$library:dcltables.exe c. Repeat Steps a and b for each node of the cluster. 2.2 Installing VAX APL on a VAXstation 2.2 Installing VAX APL on a VAXstation 2.2 Installing VAX APL on a VAXstation If you want to run VAX APL on a VAXstation, first check that you have the appropriate software license. Then, follow the instructions in the Section 2 section. ________________________ ________________________ Note Note Note If you are using a VAXstation and accessing a host VAX system to run VAX APL, VAX APL must be installed on both the host VAX system and the VAXstation. _____________________________________________________ For installations on a VAXstation running DECwindows, skip to the Section 3 section. (The rest of this section contains information needed for installations on VAXstations running VMS Workstation Software.) If you are installing VAX APL on a VAXstation running VMS Workstation Software, follow the steps below after installing VAX APL as explained in the Section 2 section. UIS$VT_ENABLE_OSC_STRINGS Logical UIS$VT_ENABLE_OSC_STRINGS Logical UIS$VT_ENABLE_OSC_STRINGS Logical The system logical name UIS$VT_ENABLE_OSC_STRINGS must be defined as "TRUE" to enable VAX APL to support the APL character set and keyboard on the VAXstation. If the system logical name is not defined as "TRUE", characters will display in ASCII as if APL support had not been enabled. 17 Use the SHOW command to determine if the logical is defined as "TRUE" by entering the following command: $ show logical uis$vt* If the logical is defined as "TRUE," skip to the APL Character Font Files section. If the system message indicates that the logical is not defined or is not defined to be "TRUE," then follow the steps below. 1. Define the system logical name UIS$VT_ENABLE_OSC_ STRINGS to be "TRUE" by entering the following command: $ define/system/exec uis$vt_enable_osc_strings true 2. Edit SYS$MANAGER:UIS$SETUP_VT240.COM to add the system logical name defined above. This will ensure that when the system is rebooted, the system logical name will be defined as "TRUE." ________________________ ________________________ Note Note Note This logical enables many facilities in the VAXstation terminal emulator and only affects terminal windows created after its value is defined. _____________________________________________________ APL Character Font Files APL Character Font Files APL Character Font Files If you entered "YES" in response to the VMS Workstation Software fonts question in step 6 of the Section 2 section, the following files are placed on the VAXstation. The files that contain the APL character fonts are placed in SYS$FONT if it exists; otherwise in SYS$LIBRARY. o UIS$LOAD_FONT_APL.COM is placed in SYS$FONT. This file loads the APL fonts into font memory at system startup. o DVWSVT0I03WK00GG001TKZZZZ02A000.VWS$FONT the VAXstation APL 80-wide normal font o DVWSVT0G03CK00GG001TKZZZZ02A000.VWS$FONT the VAXstation APL 132-wide normal font o DVWSVT0I03WK00GG001TKZZZZ02A000.VWS$VAFONT the GPX APL 80-wide normal font 18 o DVWSVT0G03CK00GG001TKZZZZ02A000.VWS$VAFONT the GPX APL 132-wide normal font UIS$VT_SPACING and UIS$VT_POINT Logicals UIS$VT_SPACING and UIS$VT_POINT Logicals UIS$VT_SPACING and UIS$VT_POINT Logicals The VT200 terminal emulator allows the user to select different fonts based on character size by defining the UIS$VT_SPACING and UIS$VT_POINT logicals. If these logicals are not defined with the default settings, then the VT220 terminal emulator will use an MCS font corresponding to the size specified by the user. The user will see the APL keyboard, but will not see the APL font. Verify with the following command, that the logicals are defined with the default settings shown below: $ show logical uis$vt_* __________________________________________________________ __________________________________________________________ Logical Default Setting Logical Default Setting Logical Default Setting UIS$VT_SPACING_DEF 9 UIS$VT_SPACING_132 7 UIS$VT_SPACING_80 9 UIS$VT_POINT_DEF 14 UIS$VT_POINT_132 12 __________________________________________________________ UIS$VT_POINT_80 14 If the logical names are not defined to the default settings, edit SYS$MANAGER:UIS$SETUP_VT240.COM to change the logical settings. Execute the command file with the following command: $ @sys$manager:uis$setup_vt240 19 3 After the Installation 3 After the Installation 3 After the Installation VAX APL is now installed and can be invoked by all users with the APL command. The installation procedure modifies the DCL command table so that the APL command is recognized and processed. However, the previous command table is still in effect for those users who are currently logged on. All users who want to use the APL command must log out of the system and log on again. If VAX APL is used extensively on your system, you can reduce system overhead and memory requirements by installing it as a shared image using the VMS Install utility. For more information, see Section 6. 3.1 PCDRIVER, the Terminal Driver Software 3.1 PCDRIVER, the Terminal Driver Software 3.1 PCDRIVER, the Terminal Driver Software PCDRIVER supports the APL character set on Digital VT200 series terminals, Digital VT300 series terminals, Human Designed System terminals (HDSAVT, HDS201, and HDS221) and VAXstations. If PCDRIVER is not already installed, the terminal driver software is installed automatically by the APL installation. Verify that PCDRIVER is running by entering the following command: $show device pc If VMS reports NO SUCH DEVICE, follow the steps below to start the PCDRIVER. 1. PCDRIVER.EXE is not a shareable image. Use the following command to make sure that the file is installed with the /NOSHARED qualifier: $install list/summary sys$loadable_images:pcdriver If the PCDRIVER.EXE file is not installed as a shareable image, go to step 2. If the PCDRIVER.EXE file is installed as a shared image, use the following command to change the installation: $install replace/noshare sys$loadable_images:pcdriver 20 2. Start the PCDRIVER by entering the following command: $@sys$library:pcloader 3. SYS$LIBRARY:PCLOADER should be invoked from the site- specific system startup procedure, SYS$STARTUP:SYSTARTUP_ V5.COM. Edit the startup command procedure to add the following command: $ @sys$library:pcloader 3.2 Control Character Keywords 3.2 Control Character Keywords 3.2 Control Character Keywords A feature of VMS V4.0 and subsequent releases is that keywords can be displayed when certain control characters are entered. By default, the following keywords are displayed for the control characters listed: __________________________________________________________ __________________________________________________________ Control Character Keyword Control Character Keyword Control Character Keyword Ctrl/y Interrupt Ctrl/c Cancel __________________________________________________________ Ctrl/z Exit These keywords are enabled on a system-wide basis. VMS displays keywords even if the terminal is not in the ASCII character set. A site that uses VT102 terminals for APL may wish to modify these keywords so that they display correctly on both ASCII and APL terminals. The easiest way to accomplish this is to use keywords entirely in lowercase letters. They will display as lowercase letters on an ASCII terminal and as APL letters on a key- or bit-paired APL terminal. See the for more ___ ______ __________ _______ ______ VMS System Generation Utility Manual information. Edit the file SYS$EXAMPLES:SYSGTTSTR.MSG to modify the keywords to Ctrl/y, Ctrl/c, and others. The file contains instructions for the editing procedure and to activate the new definitions. 21 3.3 Modifiable Files 3.3 Modifiable Files 3.3 Modifiable Files Certain files may be modified after installation if desired. o VAXAPL.HLP, the source text of the VAX APL Help function file, is in SYS$LIBRARY. You can add new text to the help library. Enter )HELP HOW-TO-BUILD while using VAX APL for instructions on creating the help file. o APL.CLD, the VAX APL DCL command line, is in SYS$LIBRARY. o APL.HLP, the VAX APL DCL Help file, is in SYS$LIBRARY. APL.HLP is the file used to update the DCL Help file. Refer to the for ___ _________ _______ ______ VMS Librarian Utility Manual instructions on modifying the DCL Help file. 3.4 Moving the QAPL Application 3.4 Moving the QAPL Application 3.4 Moving the QAPL Application QAPL.EXE, the execute-only runtime support for APL applications, is installed on SYS$SYSTEM. This support facility can be used to execute APL applications but cannot be used to develop APL applications. It may be moved to any valid VAX/VMS system, free of charge, whether it is licensed for VAX APL or not. To move the execute-only runtime APL to a VMS system where it does not exist, follow these instructions: 1. Copy the following files from the VMS system on which they are installed to the target system area specified. o QAPL.EXE to SYS$SYSTEM: o APLMSG.EXE to SYS$MESSAGE: o APLSYS.OBJ to SYS$LIBRARY: o APLDISP.OBJ to SYS$LIBRARY: o PCLOADER.COM to SYS$LIBRARY: o APL$VT220_FONT.FNT to SYS$LIBRARY: o APL$VT240_FONT.FNT to SYS$LIBRARY: o APL$VT240_FONT_132.FNT to SYS$LIBRARY: o APL$VT320_FONT.FNT to SYS$LIBRARY: 22 o APL$VT320_FONT_132.FNT to SYS$LIBRARY: o APL$VT330_FONT.FNT to SYS$LIBRARY: o APL$VT330_FONT_132.FNT to SYS$LIBRARY: o APL$VT340_FONT.FNT to SYS$LIBRARY: o APL$VT340_FONT_132.FNT to SYS$LIBRARY: o APL.CLD to SYS$LIBRARY: o VAXAPL.HLB (optional) to SYS$HELP: If PCDRIVER is not available on the target system, copy the following two files: o PCDRIVER.OBJ to SYS$LIBRARY: o PCDRIVER.EXE to SYS$LOADABLE_IMAGES: 2. Edit and execute a command file to facilitate linking the QAPL object modules into a program image as shown in this example: $edit link_qapl.com $link/protect/nosysshr/nodebug/nomap/notrace/- share=sys$library:aplshr.exe sys$library:aplsys.obj,- sys$input/options,sys$system:sys.stb/selective cluster=transfer_vector,,,sys$library:apldisp.obj gsmatch=lequal,1,1 Ctrl/z $@link_qapl 3. If the PCDRIVER is not available on the QAPL system, edit and execute a command file to facilitate linking the PCDRIVER object module into a program image as shown in this example: $edit link_pcdriver.com $link/nodebug/nomap/notraceback/exe=sys$loadable_images:pcdriver.exe- sys$library:pcdriver.obj,sys$input/options,sys$system:sys.stb base=0 ident="apl v4.0" Ctrl/z $@link_pcdriver 23 4. Use the following DCL command to install the APL command on the target system (you must have SYSPRV privileges to change the DCL command table): $set com/table=sys$library:dcltables/output=sys$library:dcltables apl.cld 5. Use the INSTALL utility to replace the system's DCLTABLES. Users that log on after the DCLTABLES have been replaced will be able to access the APL command. $run sys$system:install INSTALL>replace sys$library:dcltables.exe 4 Running the Installation Verification Procedure Separately 4 Running the Installation Verification Procedure Separately 4 Running the Installation Verification Procedure Separately The Installation Verification Procedure (IVP) is usually run at installation. The IVP files, APL$IVP.APL and APL$IVPKIT.COM are put in SYS$COMMON:[SYSTEST.APL] so that the IVP may be run after the installation is completed. If you want to run the IVP separately to ensure the integrity of installed files if system problems occur, execute the following command procedure: $apl/term=tty/silent sys$common:[systest.apl]apl$ivp If the IVP fails for any reason, the following messages are displayed: The VAX APL V4.0 Installation Verification Procedure failed. %VMSINSTAL-E-IVPFAIL, The IVP for VAX APL V4.0 has failed. 5 Error Conditions 5 Error Conditions 5 Error Conditions If the installation procedure fails for any reason, a message like the following one is displayed: %VMSINSTAL-E-INSFAIL, The installation of VAX APL V4.0 has failed. An error during the installation can occur if one or more of the following conditions exist: o Operating system version is incorrect. o Quotas necessary for successful installation are insufficient (see Section 1.3). 24 o Process quotas required by VMSINSTAL are incorrect (see Section 1.6). o The VMS Help library is currently in use. o The product is registered incorrectly or not regis- tered. For descriptions of the error messages generated by these conditions, see the ___ ______ ________ ___ ________ VMS System Messages and Recovery , your processor-specific __________ _________ ______ Procedures Reference Volume installation/operations guide, or the ___ _______ VMS License . __________ _______ ______ Management Utility Manual If you are notified that any of these conditions exists, take the appropriate action as described in the message. You may need to change a system parameter or increase an authorized quota value. If the installation fails, you must restart the instal- lation procedure from step 2. If the installation fails due to an IVP failure, contact a Digital customer services representative. 6 Installing VAX APL as a Shared Image 6 Installing VAX APL as a Shared Image 6 Installing VAX APL as a Shared Image If VAX APL will be used extensively on your system, you can reduce the system overhead and memory requirements by installing VAX APL as a shared image. To perform the installation on a system that is currently running, use the VMS Install utility while you are logged on to a privileged account. If errors occur, see the ___ ______ VMS System . ________ ___ ________ __________ _________ ______ Messages and Recovery Procedures Reference Volume First, determine the number of available global pages and global sections on your system. See Section 1.3 for information on how to do this. Then, invoke the VMS Install utility and install VAX APL as a shared image by entering the following commands. ________________________ ________________________ Note Note Note APLSHR.EXE must be installed as a protected, shareable image. APL.EXE, QAPL.EXE and APLMSG.EXE installations are optional. _____________________________________________________ 25 $run sys$system:install INSTALL>add sys$library:aplshr.exe/open/shared/header/prot INSTALL>add sys$system:apl.exe/open/shared/header_resident INSTALL>add sys$system:qapl.exe/open/shared/header_resident INSTALL>add sys$message:aplmsg.exe/open/shared INSTALL>exit To ensure that VAX APL is installed as a shared image each time the system is bootstrapped, include the following lines in the site-specific startup file (SYS$MANAGER:SYSTARTUP_V5.COM): $install add sys$library:aplshr.exe/open/shared/header_/prot add sys$system:apl.exe/open/shared/header_resident add sys$system:qapl.exe/open/shared/header_resident add sys$message:aplmsg.exe/open/shared exit ________________________ ________________________ Note Note Note APLSHR.EXE must be installed as a protected, shareable image. APL.EXE, QAPL.EXE and APLMSG.EXE installations are optional. _____________________________________________________ 7 Maintenance Updates 7 Maintenance Updates 7 Maintenance Updates Digital may periodically issue maintenance updates of VAX APL. Each update consists of an installation kit. You should install this kit as described in this document or in any documentation that may accompany the maintenance update. Each time a maintenance update is released, the version number changes. For example, if the current version is 1.0, the version number of the first maintenance update will be 1.1. In addition, each maintenance update includes new release notes. The release notes describe the changes that have been made to VAX APL since the previous release. 26 The updated release notes are provided on line. You should read the release notes when you first install VAX APL. They are also accessible at any time after the product is installed. For information on reading the release notes at the time that you install VAX APL, follow the installation procedure through step 5. To locate the release notes after VAX APL is installed, display or print the file SYS$HELP:APL040.RELEASE_NOTES or enter the following command: $help apl release_notes 8 Determining and Reporting Problems 8 Determining and Reporting Problems 8 Determining and Reporting Problems If an error occurs while you are using VAX APL and you believe that the error is caused by a problem with VAX APL take one of the following actions: o If you purchased VAX APL within the past 90 days and you think the problem is caused by a software error, you can submit a Software Performance Report (SPR). o If you have a Basic or DECsupport Software Agreement, you should call your Customer Support Center. With these services you receive telephone support that provides high-level advisory and remedial assistance. For more information, contact your local Digital customer services representative. o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). If you find an error in the VAX APL documentation, you should fill out and submit a Reader's Comments form from the back of the document in which the error was found. Include the section and page number where the error was found. 27 9 Sample Installation 9 Sample Installation 9 Sample Installation This section contains a sample installation of VAX APL. Note that this is only a sample. Sometimes the installation procedure is modified in maintenance updates of this product. Because this installation guide is not usually revised for maintenance updates, be sure to read the ) letter ____ ______ __________ __ _____ ___ ___ Read Before Installing or Using VAX APL before you install this product. This letter notes any significant changes in the installation that vary from this sample. Username: system Password: $ set default sys$update $ @sys$update:vmsinstal apl040 ddcu: options n VAX APL V4.0 Software Product Installation Procedure It is 25-JUL-1991 at 11:02. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? The following products will be processed: APL V4.0 Beginning installation of APL V4.0 at 11:02 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. Product: APL Producer: DEC Version: 4.0 Release Date: 29-JUL-1991 * Does this product have an authorization key registered and loaded? y 28 This kit contains an Installation Verification Procedure (IVP) to verify the correct installation of the VAX APL interpreter. It can be run prior to the conclusion of this procedure by answering "YES" to the IVP prompt or invoked after the installation as follows: @SYS$COMMON:[SYSTEST.APL]APL$IVP * Do you want to run the IVP after the installation [YES]? * Do you want VMS Workstation Software (VWS) fonts [NO]? This version of VAX APL can display the APL characters on the DECwindows terminal. To do this, the APL fonts must be installed on the DECwindows server and the server must be restarted after the VAX APL installation finishes. * Do you want DECwindows fonts [YES]? Along with the 75 dpi fonts, you can optionally install the 100 dpi fonts. * Do you want 100 dpi video fonts installed [NO]? This kit contains tools which read and write APL workspaces in WSIS (Workspace Interchange Standard) format to allow the transportation of workspaces between VAX APL and other APL implementations. It is your option to place WSIS in your [SYSLIB] area. * Do you want WSIS [YES]? This kit contains the annotated versions of the tools which read and write APL workspaces in WSIS (Workspace Interchange Standard) format. It is your option to place WSINCOM and WSOUTCOM in your [SYSLIB] area. * Do you want WSINCOM and WSOUTCOM [NO]? This kit contains the APL meta-functions It is your option to place METAFNC in your [SYSLIB] area. * Do you want the APL meta-functions [NO]? * Do you want to purge files replaced by this installation [YES]? %VMSINSTAL-I-RESTORE, Restoring product save set B ... 29 The APL help file will now be installed in the help library. If any user attempts to access online help during this time, the installation may fail. If the procedure fails, you must restart the installation procedure. You may want to notify any users not to access online help until this step of the procedure is completed. * Enter Y when you are ready to continue? y The APL help file has been successfully installed in the help library. Users can now access online help without endangering this installation procedure. No further questions will be asked. %VMSINSTAL-I-RESTORE, Restoring product save set C ... %VMSINSTAL-I-RESTORE, Restoring product save set D ... %VMSINSTAL-I-RESTORE, Restoring product save set E ... The following files will be left on disk: SYS$SYSTEM:APL.EXE [new] SYS$MESSAGE:APLMSG.EXE [new] SYS$HELP:HELPLIB.HLB [modified] SYS$LIBRARY:DCLTABLES.EXE [modified] SYS$SYSTEM:QAPL.EXE [new] SYS$HELP:VAXAPL.HLB [new] SYS$LIBRARY:VAXAPL.HLP [new] SYS$LIBRARY:APL.CLD [new] SYS$LIBRARY:APL.HLP [new] SYS$HELP:APL032.RELEASE_NOTES [new] SYS$LIBRARY:APL$VT220_FONT.FNT [new] SYS$LIBRARY:APL$VT240_FONT.FNT [new] SYS$LIBRARY:APL$VT240_FONT_132.FNT [new] SYS$LIBRARY:APL$VT320_FONT.FNT [new] SYS$LIBRARY:APL$VT320_FONT_132.FNT [new] SYS$LIBRARY:APL$VT330_FONT.FNT [new] SYS$LIBRARY:APL$VT330_FONT_132.FNT [new] SYS$LIBRARY:APL$VT340_FONT.FNT [new] SYS$LIBRARY:APL$VT340_FONT_132.FNT [new] SYS$COMMON:[SYSFONT.DECW.USER_75DPI]APL_TERMINAL*.DECW$FONT [new] SYS$LIBRARY:DECW$MOTIF$DXMSHR.EXE [copied if no previous version] SYS$LIBRARY:DECW$MOTIF$XMSHR.EXE [copied if no previous version] SYS$LIBRARY:DECW$MOTIF$XTSHR.EXE [copied if no previous version] SYS$LIBRARY:APLSHR.EXE [new] SYS$LIBRARY:APLSYS.OBJ [new] 30 SYS$LIBRARY:APLDISP.OBJ [new] SYS$LOADABLE_IMAGES:PCDRIVER.EXE [copied if no previous version] SYS$LIBRARY:PCDRIVER.OBJ [new] SYS$LIBRARY:PCLOADER.COM [new] SYS$LIBRARY:SMG.AAS [new] SYS$LIBRARY:GKS.AAS [new] SYS$COMMON:[SYSTEST.APL]APL$IVP.APL [new] SYS$COMMON:[SYSTEST.APL]APL$IVP.COM [new] SYS$STARTUP:APL$STARTUP.COM [new] SYS$COMMON:[SYSEXE]APL$SM_CCT.EXE [new] SYS$COMMON:[SYSEXE]APL$SM_DECW.EXE [new] SYS$COMMON:[SYSLIB]WSPRINT.APL [new] ******************************************************************************* If this installation is being done on a cluster, you must do @SYS$STARTUP:APL$STARTUP.COM on all other nodes. In addition, be sure to have your system manager add @SYS$STARTUP:APL$STARTUP.COM to your system startup file. If you intend to use DECterm or the VT200 or VT300 series of terminals, you should also insure that @SYS$LIBRARY:PCLOADER.COM is in your system startup file, If you installed the DECwindows fonts, the DECwindows server must be restarted to activate the fonts. ******************************************************************************* %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Beginning the VAX APL V4.0 Installation Verification Procedure. VAX APL V4.0 Installation Verification Procedure completed successfully. Installation of APL V4.0 completed at 11:17 VMSINSTAL procedure done at 11:17 $ logout SYSTEM logged out at 26-JUL-1991 13:52:30:52 31