*4I *4E *5D *5E *5I *5E VAX BASIC Installation Guide Order Number: AA-EY30F-TE February 1990 This document contains instructions for installing VAX BASIC on the VMS operating system. This document also explains how to read the online release notes before or after installing the product. This document applies to VAX BASIC Version 3.4 and all maintenance updates throughout that version. Revision/Update Information: This revised manual supersedes the VAX BASIC Installation Guide, Version 3.3. Operating System and Version: Version 5.0 or higher Software Version: VAX BASIC Version 3.4 DEC GKS FOR VMS Version 2.0 or higher digital equipment corporation maynard, massachusetts -2 U.S.rGovernmenttis subjectptocrestrictionssasoseteforthhin subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1985, 1986, 1987, 1988, 1990. All Rights Reserved. Printed in U.S.A. The postpaid Reader's Comments forms at the end of this docu- ment request your critical evaluation to assist in preparing future documentation. *3D The following are trademarks of Digital Equipment Corporation: CDA MASSBUS VAX RMS DDIF PrintServer 40 VAXstation DEC Q-bus VMS DECnet ReGIS VT DECUS ULTRIX XUI DECwindows UNIBUS DIGITAL VAX LN03 VAXcluster DIGITAL *3E *3I The following are trademarks of Digital Equipment Corporation: ALL-IN-1 EduSystem RT DEC IAS ULTRIX DEC/CMS MASSBUS UNIBUS DEC/MMS PDP VAX DECnet PDT VAXcluster DECmate P/OS VMS DECsystem-10 Professional VT DECSYSTEM-20 Q-bus Work Processor DECUS Rainbow DECwriter RSTS DIBOL RSX DIGITAL *3E The following is a third-party trademark: PostScript is a registered trademark of Adobe Systems, Inc. ZK5442 Contents ________________________________________________________________ Preface .......................................................v. 1 Preparing to Install VAX BASIC................... 1 1.1 Prerequisite Software..................... 1 1.2 Accessing the Online Release Notes...... 2 1.3 Installation Procedure Requirements..... 2 1.4 VMS License Management Facility ......... 3 1.5 Using VMSINSTAL............................ 4 2 Installing VAX BASIC.............................. 6 3 Installing VAX BASIC on a VAXCluster............ 17 4 Running the Installation Verification Procedure Separately.............................. 18 5 After the Installation............................ 19 5.1 Testing VAX BASIC Graphics ............... 20 5.2 Choosing a Default Editor ................ 22 5.3 Disallowing Access to DCL ................ 22 5.4 Adjusting the Working Set in the BASIC Environment................................. 23 5.5 Customizing VAX BASIC Error Messages and Environment Prompts................... 24 6 Error Conditions...................................26 iii 7 Installing VAX BASIC as a Shared Image......... 27 8 Determining and Reporting Problems.............. 30 9 Maintenance Updates............................... 30 10 Sample Installation............................... 31 iv Preface ________________________________________________________________ This document describes how to install VAX BASIC on the VMS operating system. It is intended for system managers. This document applies to VAX BASIC Version 3.4, and may apply to future maintenance updates. 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 it to install maintenance updates or to reinstall VAX BASIC for any other reason. At the back of this document are two Reader's Comments forms. If you have any comments about this document, please fill out one form and mail it. Your comments will be considered for the next revision of the installation guide. For more information about installing VAX BASIC on VMS systems, refer to your processor-specific installa- tion/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. v Defaults appear in brackets ([]) throughout the installation procedure. Text you type is indicated in red. vi ____________________________________________________________ 1 Preparing to Install VAX BASIC 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 it are missing, call your DIGITAL representative. Distribution media must be mounted in numerical order. The installation procedure prompts you to mount the volumes. For more information on how to mount distribution media, refer to your processor-specific installation/operations guide. This guide also details several options to the installation procedure. ____________________________________________________________ 1.1 Prerequisite Software VAX BASIC Version 3.4 requires Version 5.0 or higher. To use VAX BASIC graphics, you must have DEC GKS FOR VMS Version 2.0 or higher installed. If you have the VAX Common Data Dictionary/Plus (CDD/Plus) installed, you must have the file CDDSHR.EXE installed as a protected image to access the dictionary from VAX BASIC. To find out if CDDSHR.EXE is installed as a protected image on your system, enter the following command lines: $ INSTALL LIST SYS$SHARE:CDDSHR If CDDSHR is installed, the system responds with the full file specification of the file CDDSHR.EXE. If CDDSHR is not installed, you receive the following error message: %INS-E-NOKFIFND, no known file entry found If you receive this error message, you must install CDDSHR as a protected image by entering the following command line: $ INSTALL ADD SYS$SHARE:CDDSHR/PROT Note that if you are installing VAX BASIC in a clustered environment, you should install CDDSHR as a protected image on all nodes in the cluster. ____________________________________________________________ 1.2 Accessing the Online Release Notes VAX BASIC provides online release notes. To display or print the release notes before installation, invoke VMSINSTAL with the OPTIONS N parameter. Step 4 of the installation procedure includes a prompt to display or print the release notes. To obtain the release notes after the installation, type or print the file SYS$HELP:BASIC$034.RELEASE_NOTES. Online help also directs you to the release notes file. After the installation, type the following: $ HELP BASIC RELEASE_NOTES ____________________________________________________________ 1.3 Installation Procedure Requirements The VAX BASIC installation procedure takes approximately 15 minutes to 2 hours depending on your type of media and your system configuration. Before you can install VAX BASIC, you must have the following privileges and resources: o SETPRV privileges, or CMKRNL, WORLD, and SYSPRV privi- leges. o A minimum of 1710 blocks of free disk space during the installation. After the installation is complete, VAX BASIC will use a minimum of approximately 1100 blocks of disk space. o If a prior version of VAX BASIC is installed on your system and you have installed the BASIC images as shared known images, the VAX BASIC installation will require 952 available global pages and 4 available global sections. Failure to meet these minimum requirements may cause the DCL tables to become corrupted. o A minimum of 1 global section and 44 global pages for installation of the DECwindows Compiler Interface image. Also, DIGITAL recommends that you make a backup of your system disk before installing any layered products. Refer to the VMS documentation on system management op- erations for information on modifying the GBLPAGES and GBLSECTIONS values and for information on how to use the VMS Authorize Utility to change the resource control fields. ____________________________________________________________ 1.4 VMS License Management Facility The VMS License Management Facility (LMF) is available with Version 5.0 of the VMS operating system. If you are in- stalling VAX BASIC on a VMS Version 5.0 system, you must register your VAX BASIC software license. The License registration information you need is contained in the Product Authorization Key (PAK) that is shipped with VAX BASIC. The PAK is a paper certificate that contains information about the license you have to run a particular piece of software. During the installation procedure, you are asked if you have registered the VAX BASIC license and loaded the appropriate authorization key. You must register and load your license for VAX BASIC before you start the installation in order to run the Installation Verification Procedure (IVP) and use the software. If you have not registered and installed the license prior to installing VAX BASIC, the installation procedure will continue to completion; however, the IVP will not execute and the VAX BASIC software will not be usable. You can register and install the license later, at which time you can then run the IVP and use the software. To register a license under VMS Version 5.0, first log in to the system manager's account, SYSTEM. You then have a choice of two ways to perform the registration: o Invoke the SYS$UPDATE::VMSLICENSE.COM procedure. When it prompts you for information, respond with data from your Product Authorization Key (PAK). o Issue the LICENSE REGISTER DCL command with the appro- priate qualifiers that correspond to information on the PAK. For complete information on using LMF, see the manual on the License Management Utility in the VMS documentation set. ____________________________________________________________ 1.5 Using VMSINSTAL After you log in to a privileged account to install VAX BASIC, set the default to SYS$UPDATE: and then invoke VMSINSTAL, the command procedure that installs this prod- uct. An example of this procedure is shown in Steps 1 and 2 of the Installing VAX BASIC section. $ SET DEFAULT SYS$UPDATE $ @VMSINSTAL BASIC03n ddn: [OPTIONS N] The command parameters are described in the next paragraphs. If you do not supply the first two parameters, VMSINSTAL prompts you for the product and device names. If you wish to be prompted for the product and device names and to display or print the release notes, type the following: $ @SYS$UPDATE:VMSINSTAL "" "" OPTIONS N n Represents the maintenance update of VAX BASIC. Refer to the label on the VAX BASIC distribution kit or the VAX BASIC BIL or BOM for the maintenance update number of your kit. ddn: Represents a device name where the distribution volumes will be mounted for the VAX BASIC installation media, where dd is the device code and n is the unit number. It is not necessary to use the console drive to install VAX BASIC. If you do use the console drive, you should replace any media you removed from the drive. CSA1: is the device name used in examples in this document. 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. Note that VMSINSTAL permits the use of several other options. For more information on the other options, refer to 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 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 then checks whether the following conditions ex- ist. 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, type YES. If you want to stop the installation, press RETURN. VAX BASIC requires manual registration with a Product Authorization Key (PAK). Make sure to register VAX BASIC before starting the installation procedure to ensure a suc- cessful installation. Register the information contained in the PAK that is shipped with VAX BASIC by using either the VMS License command pro- cedure SYS$UPDATE:VMSLICENSE.COM or the LICENSE REGISTER command, as described in VMS License Management Utility Manual. ____________________________________________________________ 2 Installing VAX BASIC This section contains excerpts from the installation pro- cedure and explains each step. Note that defaults appear in brackets throughout the installation procedure. 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 installa- tion procedure after pressing CTRL/Y, you must proceed from step 2. Note that enhancements to VMSINSTAL in future releases of the VMS system may result in additional prompts appearing during the course of the installation. Such prompts may not be documented in this installation guide; however, the installation should proceed as expected. Refer to the Read Before Installing or Using VAX BASIC letter for any notes about installing this product. Step 1: Log in to a privileged account and set your default device and directory to SYS$UPDATE. Username: SYSTEM Password: $ SET DEFAULT SYS$UPDATE Step 2: Invoke VMSINSTAL. *2D $ VMSINSTAL BASIC034 CSA1: OPTIONS N *2E *2I $ @VMSINSTAL BASIC034 CSA1: OPTIONS N *2E VMS Software Product Installation Procedure It is 11-OCT-1989 at 08:35. Enter a question mark (?) at any time for help. * 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, type NO to discontinue the installation. Step 3: Insert the first installation kit volume. To continue the installation, mount volume 1 of the installation kit. Type YES and press RETURN when prompted. Please mount the first volume of the set on CSA1:. * Are you ready? YES %MOUNT-I-MOUNTED, BASIC mounted on _CSA1: The following products will be processed: BASIC V3.4 Beginning installation of BASIC V3.4 at 08:36 %VMSINSTAL-I-RESTORE, Restoring product saveset A... %VMSINSTAL-I-REMOVED, The products release notes have been successfully moved to SYS$HELP. Step 4: Select a release notes option. This step applies only if you specified OPTIONS N in step 2. 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 * Select option [2]: To select a release notes option, enter the number of an option or press RETURN to select the default, option 2. If you select option 1, VMSINSTAL displays the release notes immediately on your terminal screen. You can terminate the display at any time by pressing CTRL/C. If you select option 2, VMSINSTAL prompts you for a queue name with the following prompt: * Queue name [SYS$PRINT]: Job BASIC034 (queue SYS$PRINT, entry 346) started on LPA0 Either enter a queue name or press RETURN to send the file to the default queue on your system. After you select a release notes option, VMSINSTAL asks if you want to continue with the installation: Do you want to continue the installation [NO]?: If you want to continue the installation, type YES and press RETURN. If you type NO or press RETURN, VMSINSTAL stops the installation. Step 5: Select installation options. VAX BASIC V3.4 Installation Procedure There are three possible installation options. They are described as follows: 1. Perform a normal installation of BASIC. 2. Install VMS system definitions text library only (10-45 minutes). 3. Obtain a copy of the BASIC message text for modification. * Which option do you want to use [1]: Enter the number of an option, or press RETURN to select the default, option 1. Option 1 installs VAX BASIC and copies the release notes into the [SYSHLP] directory. Option 1 also gives you the opportunity to: o Install online HELP o Install the VMS system definitions text library o Install the DECwindows Compiler Interface (only applies to systems running VMS Version 5.1 or higher) o Install sample graphics programs o Purge system library files Options 2 and 3 do not install VAX BASIC. Option 2 generates a text library of VAX BASIC source code containing the VMS systems definitions. Users can include this source code in their VAX BASIC programs to define VMS constants and procedure declarations. Choose option 2 if you want to update the VMS system definitions, but do not want to reinstall the VAX BASIC software. You should update the system definitions after installing each functional release of VMS. Option 3 copies the VAX BASIC message file BASIC$MSG.MSG into the [SYSUPD] directory. You can edit BASIC$MSG.MSG to provide customized VAX BASIC environment prompts and error messages. Choose option 3 only after installing VAX BASIC, because the installation procedure supersedes any previous version of BASIC$MSG.MSG. See the section Customizing VAX BASIC Error Messages and Environment Prompts for information on how to edit the VAX BASIC message file. If you choose option 2 or 3, VMSINSTAL displays messages indicating that the option has been installed. For example, if you select option 2, VMSINSTAL displays the following messages: %VMSINSTAL-I-RESTORE, Restoring product saveset D... %VMSINSTAL-I-INSSTARLET, Installing BASIC system definitions %VMSINSTAL-I-INSSTARLET1, Requires approximately 10 to 45 minutes %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of BASIC V3.4 completed at 8:38 VMSINSTAL procedure done at 8:38 Note that when you select option 2 or 3, the last message indicates that the installation of the option is complete, not that the installation of VAX BASIC is complete. VMSINSTAL then ends the installation. You must start the installation procedure over again from step 3 if you want to select another option. Option 1 installs the VAX BASIC software. If you select option 1, VMSINSTAL asks you the following additional questions: * Do you want to install the BASIC HELP files [YES]? The VAX BASIC HELP files use approximately 510 blocks of disk space. DIGITAL recommends that you install the online HELP files as they provide an important documentation resource; however, if your system is low on disk space you can choose not to install online HELP. The VAX BASIC HELP library, [SYSHLP]BASICHELP.HLB, exists in compressed format. If you have available disk space, you may want to expand the help library. Expanding the HELP library will improve performance when the HELP files are accessed. For information on how to expand the HELP library, see the description of the /DATA qualifier in the VMS Librarian Utility documentation. If you want to install the VAX BASIC HELP files, press RETURN. Otherwise, type NO and press RETURN. * Do you want to install the VMS system definitions [NO]? VAX BASIC supports the inclusion of source code from text libraries. Type YES and press RETURN if you want to generate a text library of VAX BASIC source code containing the VMS system definitions. (Note that choosing this option will add approximately 10 to 45 minutes to the installation time.) The generated file will be [SYSLIB]BASIC$STARLET.TLB. This file will require approximately 3100 blocks of disk space. If you do not want to install the VMS system definitions, press RETURN. * Do you want to install the DECwindows Compiler Interface [YES]? VAX BASIC allows you to compile programs by way of the DECwindows Compiler Interface. Note that your system must be running VMS Version 5.1 or higher to use this feature. The files needed to support the DECwindows Compiler Interface use approximately 355 blocks of disk space. Press RETURN if you want to install the DECwindows Compiler Interface. * Do you want to install the sample graphics programs [YES]? VAX BASIC includes graphics support. Press RETURN to install the sample VAX BASIC graphics programs on your system. The sample graphics programs use approximately 130 blocks of disk space. Once the sample programs are installed, you can access the programs in the directory SYS$SYSROOT:[SYSHLP.EXAMPLES.BASIC] to help you get started using VAX BASIC graphics. Note that you must have DEC GKS FOR VMS Version 2.0 or higher installed on your system to use VAX BASIC graphics. If you do not want to install the sample graphics programs, type NO and press RETURN. * Do you want to purge files replaced by this installation [YES]? The installation procedure does not automatically purge files that are replaced during the installation. These are the files residing in SYS$SYSTEM, SYS$LIBRARY, and SYS$HELP which constitute each release of VAX BASIC. To purge, press RETURN. To disable purging, type NO and press RETURN. Note that purging is recommended. After you have answered the preceding questions, proceed to the next step to continue installing the VAX BASIC software. Step 6: Respond to license query After the question on purging files has been answered, the following is displayed: Product: BASIC Producer: DEC Version: 3.4 Release Date: * Does this product have an authorization key registered and loaded? If you have registered and loaded the Product Authorization Key (PAK) for VAX BASIC Version 3.4 prior to this installation, answer YES to the above question. If you have not registered and loaded the PAK for VAX BASIC Version 3.4 prior to this installation, answer NO to the above question. The following message will then be displayed: %VMSINSTAL-W-NOIVP, IVP will not be run since license not installed %VMSINSTAL-I-IVP, It is recommended that the IVP be run after the license has been installed. %VMSINSTAL-I-RUNIVP, To run the IVP, invoke @SYS$SYSROOT:[SYSTEST.BASIC]BASIC$IVP.COM. The installation will then proceed as described in this document, although no one will be able to use the software until the PAK has been installed. The IVP will not be executed if the PAK is not installed, because the IVP invokes VAX BASIC. When the installation has completed and after the PAK is registered and loaded, it is recommended that the IVP be executed by invoking @SYS$SYSROOT:[SYSTEST.BASIC]BASIC$IVP.COM. Step 7: Insert the subsequent installation kit volumes. %BACKUP-I-READYREAD, mount volume 2 on _CSA1: for reading Enter "YES" when ready: YES If your installation kit contains more than one volume, VMSINSTAL prompts you to insert the next volume and waits for you to type YES after inserting it. If you type NO in response to the prompt, VMSINSTAL will display the question again. This prompt is not displayed if your installation kit contains only one volume. Depending on the installation options you choose and the type of media you are using, you may not need to mount all the volumes supplied in your installation kit to install VAX BASIC. For certain types of media, the extra volume is necessary only if you choose the option to edit the VAX BASIC message file. In general, you should read the messages on your terminal. VMSINSTAL will continue to prompt you until you have inserted all the necessary volumes and will tell you when the installation is complete. Step 8: Read informational messages. VMSINSTAL displays informational messages as each saveset is moved onto your system, and if the installation is successful, displays a message indicating that the files comprising VAX BASIC have been moved to their target directory. VMSINSTAL also displays several informational messages verifying that additional installation options have been installed. For example, the following messages are displayed if you answered YES to all the additional installation options: No further questions will be asked. Installation continuing... %VMSINSTAL-I-RESTORE, Restoring product saveset B... %VMSINSTAL-I-SYSDIR, This product creates system disk directory VMI$ROOT:[SYSTEST.BASIC] ************************************************************************ If you have DEC GKS FOR VMS V2.0 or later on your system, VAX BASIC V3.4 allows you to use graphics language statements.The procedure: SYS$SYSROOT:[SYSTEST.BASIC]BASIC$GRAPHICS_IVP.COM will verify that VAX BASIC graphics capabilities work on your system. You must execute this procedure on a terminal with graphics capabilities. ************************************************************************ %VMSINSTAL-I-INSHELP, Installing BASIC Help files %VMSINSTAL-I-RESTORE, Restoring product saveset C... %VMSINSTAL-I-INSTARLET, Installing BASIC system definitions %VMSINSTAL-I-INSTARLT1, Requires approximately 10-45 minutes %VMSINSTAL-I-RESTORE, Restoring product saveset D... %VMSINSTAL-I-INSSAMPLE, Installing sample programs and PICTURE libraries %VMSINSTAL-I-RESTORE, Restoring product saveset E... %VMSINSTAL-I-RESTORE, Restoring product saveset F... %VMSINSTAL-I-SYSDISK, This product creates system disk directory VMI$ROOT:[SYSHLP.EXAMPLES.BASIC] ************************************************************** A number of sample programs demonstrating BASIC graphics statements have been copied to [SYSHLP.EXAMPLES.BASIC]. Read [SYSHLP.EXAMPLES.BASIC]BASIC_EXAMPLES.TXT for information on the sample programs provided. *************************************************************** %VMSINSTAL-I-MOVEFILES, files will now be moved to their target directories... The installation procedure then invokes the Installation Verification Procedure (IVP) to verify that VAX BASIC was successfully installed. If VAX BASIC was successfully installed, VMSINSTAL displays the following messages: %VMSINSTAL-I-RUNIVP, Executing installation verification procedure %VMSINSTAL-I-IVPSUCCESS, VAX BASIC V3.4 Installation test PASSED The BASIC IVP has succeeded Installation of BASIC V3.4 completed at 15:02 If you have support for DEC GKS FOR VMS Version 2.0, the installation provides a separate graphics IVP to test that VAX BASIC graphics support is installed properly. For information on how to invoke the graphics IVP, see the section Testing VAX BASIC Graphics. The following files have potentially been created or modified by the VAX BASIC installation procedure: o [SYSEXE]BASIC.EXE o [SYSHLP]BASIC$DWCI.HLB o [SYSHLP]BASICHELP.HLB o [SYSHLP]BASIC$034.RELEASE_NOTES o [SYSHLP.EXAMPLES.BASIC] and its contents o [SYSLIB]BASIC$STARLET.TLB o [VUE$LIBRARY.USER]BASIC$DWCI.EXE o [VUE$LIBRARY.USER]BASIC$DWCI.UID o [SYSLIB]DCLTABLES.EXE o [SYSMSG]BASIC$MSG.EXE o [SYSTEST.BASIC] and its contents Step 9: End the installation procedure. Enter the products to be installed from the next distribution volume set. * Products [EXIT]: VMSINSTAL procedure done at 8:51 $ LOGOUT SYSTEM logged out at 11-OCT-1989 8:56 When the VAX BASIC installation procedure is complete, you can choose to install another product or end the installation procedure. To end the installation procedure, press RETURN. If you removed any media from the console drive before beginning the installation, you should replace it now. Note that 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 want to restore those symbols, log out and then log back in again. ____________________________________________________________ 3 Installing VAX BASIC on a VAXCluster If you want to run VAX BASIC on multiple nodes of a VAXcluster, first check to see that you have the appropriate software license. Then, follow these steps after installing VAX BASIC: 1.Issue the following command to set up the VAXcluster environment: *2D $ RUN SYS$SYSTEM:SYSMAN SET ENVIRONMENT/NODES=(node1, node2...noden) *2E *2I $ RUN SYS$SYSTEM:SYSMAN SYSMAN> SET ENVIRONMENT/NODES=(node1,node2...noden) *2E *2D Where node1,node2,...noden are the names of the nodes on which you want to activate the VAX BASIC license. *2E *2I where node1,node2,...noden are the names of the nodes on which you want to activate the VAX BASIC license. *2E 2.Issue the following command to load the license on the nodes specified in Step 1: *2D SYSMAN> DO LICENSE LOAD BASIC *2E *2I SYSMAN> DO LICENSE LOAD BASIC *2E 3.Issue the following command to replace the DCL tables on the nodes specified in Step 1: *2D SYSMAN> DO INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE *2E *2I SYSMAN> DO INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE *2E You may then exit from the SYSMAN utility: *2D SYSMAN> EXIT *2E *2I SYSMAN> EXIT *2E $ ____________________________________________________________ 4 Running the Installation Verification Procedure Separately The Installation Verification Procedure (IVP) is usually run at installation. If you want to run the IVP separately to ensure the integrity of installed files if system problems occur, execute the following command procedure: *2D @SYS$SYSROOT:[SYSTEST.BASIC]BASIC$IVP.COM *2E *2I @SYS$SYSROOT:[SYSTEST.BASIC]BASIC$IVP.COM *2E If the IVP fails for any reason, the following message is displayed: The BASIC IVP has failed ____________________________________________________________ 5 After the Installation VAX BASIC is now installed and can be invoked with the DCL command BASIC. This section describes several things you may want to do after installing VAX BASIC. These include verifying that VAX BASIC graphics support is installed properly, choosing a default editor, disallowing user access to DCL, and customizing the VAX BASIC message file. The VAX BASIC installation procedure has modified the DCL command table so that the BASIC command is recognized and processed. However, the old command table is still in effect for those users who are currently logged in. All users who want to use the BASIC command must log out of the system and log in again. If VAX BASIC will be 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. Note that if a prior version of VAX BASIC has already been installed as a shared image, the VAX BASIC installation procedure will automatically install the new version as a shared image as well. For information on how to install VAX BASIC as a shared image, see the section Installing VAX BASIC as a Shared Image. ____________________________________________________________ 5.1 Testing VAX BASIC Graphics VAX BASIC includes graphics support. Graphics support requires DEC GKS FOR VMS Version 2.0 or higher. After you have installed DEC GKS FOR VMS Version 2.0 and VAX BASIC Version 3.4, you can test that VAX BASIC graphics have been installed properly by invoking a graphics Installation Verification Procedure (IVP). To invoke the graphics IVP, use either a graphics terminal or a workstation, and type the following command: $ @SYS$SYSROOT:[SYSTEST.BASIC]BASIC$GRAPHICS_IVP This command causes the following output to appear on your screen: VAX BASIC V3.4 Graphics Verification Procedure You must execute this procedure on a graphics terminal or workstation. Valid devices include: VT125 VT240 VT241 VT330 VT340 VSI VSII VSII/GPX DECwindows What type of graphics device are you using: VT240 Compiling and linking VAX BASIC Graphics IVP NOTE To use the DECwindows graphics capabilities, your system must be running Version 4.0 of DEC GKS FOR VMS. ZK-5547-86 The output on your device should be similar to the output shown here. If you have a color terminal, the output will appear in several different colors. If the output on your device is dissimilar to the output shown here, or if the output fails to appear altogether, check to make sure the following conditions are true: o You entered the full name of the device you are using o Your system has DEC GKS FOR VMS Version 2.0 or later installed If neither of these conditions is the cause of the error, you should contact a DIGITAL field representative. ____________________________________________________________ 5.2 Choosing a Default Editor Once you have successfully installed VAX BASIC, the default text editor in the BASIC environment is VAX EDT. However, you can choose another default text editor for system users by defining the logical name BASIC$EDIT. Besides VAX EDT, VAX BASIC supports the VAX Language-Sensitive Editor (LSE) and the VAX Text Processing Utility (TPU). When you establish a default editor, the name you assign to BASIC$EDIT must be in the form nnn$EDIT, where the characters nnn represent the acronym for the editor. For example, you can make LSE the default editor with the following command: $ ASSIGN "LSE$EDIT" BASIC$EDIT Note that if the logical name BASIC$EDIT translation is not of the form nnn$EDIT, VAX BASIC spawns a subprocess to invoke the editor assigned to BASIC$EDIT. ____________________________________________________________ 5.3 Disallowing Access to DCL By using the $ system-command in the BASIC environment, a user can type and execute a DCL command. If this is not desirable for system security, you can deny a BASIC environment user access to DCL by setting the user's subprocess limit (PRCLM) to zero. If the user's subprocess limit is set to zero, VAX BASIC will signal an error message when that user enters the $ system-command. While in a captive account, a user can execute the EDIT command only if the logical name BASIC$EDIT translates to a callable editor or if BASIC$EDIT is undefined. If BASIC$EDIT translates to an editor not supported by VAX BASIC, the user receives an error message while attempting to invoke an editor. The previous section provides information on selecting a default editor for VAX BASIC users. ____________________________________________________________ 5.4 Adjusting the Working Set in the BASIC Environment Prior to Version 3.2, VAX BASIC automatically performed calls to the system service $ADJWSL in order to limit the size of the working set in the BASIC environment. (The working set is the set of process pages resident in physical memory.) However, if a system did not have memory constraints, this system service call caused the system not to utilize all of its available memory, thus slowing the execution of your VAX BASIC commands. To address this problem, the logical name BASIC$ADJWSL has been added. If BASIC$ADJWSL exists and is assigned to any equivalence name string, VAX BASIC performs automatic working set adjustment in the VAX BASIC environment. You should only define the logical BASIC$ADJWSL if your system has limited memory resources and many interactive BASIC environment users. You can define this logical name with the following command: $ ASSIGN "TRUE" BASIC$ADJWSL BASIC$ADJWSL can be defined at the process, group, job, or system level. By default, if you do not define the logical name BASIC$ADJWSL, automatic working set adjustment is not performed in the VAX BASIC environment. See the VMS documentation on performance management for more information on working sets. ____________________________________________________________ 5.5 Customizing VAX BASIC Error Messages and Environment Prompts Option 3 of the installation procedure copies the VAX BASIC message file BASIC$MSG.MSG into the system directory [SYSUPD]. After you choose this option, you can edit BASIC$MSG.MSG to customize the error messages or environment prompts (such as Ready) that users receive when using VAX BASIC. Customized prompts and messages are often desirable for international users. You must install VAX BASIC before editing the message file. If you install VAX BASIC after editing BASIC$MSG.MSG, the software installation will supersede the revised message file in the [SYSMSG] directory. Also, you must have the VMS Message Utility installed on your system before editing BASIC$MSG.MSG. The edited version of BASIC$MSG.MSG must be processed through the Message Utility before the file can be accessed by VAX BASIC. The following steps explain how to edit the VAX BASIC messages and install the customized message file on your system: 1.Run the VAX BASIC installation procedure and choose option 3. Installation option 3 copies the message file, BASIC$MSG.MSG, into the system directory [SYSUPD]. 2.Edit the message file. Each error message and environment prompt appears on a separate line and is enclosed in angle brackets (<>). You can edit the text portion of the error messages, but for BASIC to correctly identify the errors you must not change the following: o The 3- to 9-character mnemonic that appears in the first column o The sequence in which the error messages appear in the file o The severity level of the error message o The number, type, and order of the formatted ASCII ouput (FAO) arguments that appear in the message 3.Run the VMS Message Utility. To translate the new message text into a file BASIC can access, run the text file through the Message Utility by entering the following command: $ MESSAGE BASIC$MSG The Message Utility creates the object module BASIC$MSG.OBJ. 4.Enter the LINK command with the /SHARE qualifier to create the shareable image BASIC$MSG.EXE: $ LINK/SHARE BASIC$MSG 5.Install BASIC$MSG.EXE in the system directory [SYSMSG]: $ COPY BASIC$MSG.EXE SYS$COMMON:[SYSMSG]/PROT=W:RE 6.If VAX BASIC is installed as a known image, you must reinstall BASIC$MSG.EXE by entering the following command: $ INSTALL REPLACE SYS$MESSAGE:BASIC$MSG VAX BASIC will now generate your customized error messages and environment prompts. ____________________________________________________________ 6 Error Conditions If the installation procedure fails for any reason, a message like the following is displayed: %VMSINSTAL-E-INSFAIL, The installation of VAX BASIC V3.4 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 Prerequisite software version is incorrect o Quotas necessary for successful installation are insufficient (see the Installation Procedure Requirements section) o Process quotas required by VMSINSTAL are incorrect (see the Using VMSINSTAL section) o The VMS HELP library is currently in use o The product was registered incorrectly or not registered For descriptions of the error messages generated by these conditions, see the VMS System Messages and Recovery Procedures Reference Volume, refer to your processor-specific installation/operations guide or the VMS License Management Utility Manual. If you are notified that any of these conditions exist, you should 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 installation procedure from step 2. If the installation fails due to an IVP failure, contact a DIGITAL field service representative. ____________________________________________________________ 7 Installing VAX BASIC as a Shared Image If VAX BASIC will be used extensively on your system, you can reduce the system overhead and memory requirements by installing it as a shared image. To perform the installation on a system that is currently running, use the VMS Install Utility while you are logged in to a privileged account. If errors occur, consult the VMS System Messages and Recovery Procedures Reference Volume. It is recommended that you perform the following steps on a system that has just been bootstrapped, because it is less likely to fragment the space in the global page table. If an error occurs, refer to the VMS documentation on system management operations. Step 1: Invoke the Install Utility. $ INSTALL Step 2: Determine the number of global pages available. INSTALL> LIST/GLOBAL/SUMMARY Type the LIST command line to determine whether there are enough available global pages to install VAX BASIC. This command line lists a summary of the number of global sections used, number of global pages used, and the number of global pages unused. Note the number of global sections used. Then, exit from the Install Utility by typing EXIT. VAX BASIC requires approximately 952 global pages. However, if you choose to install the DECwindows Compiler Interface, you must increase the number of global pages required to install VAX BASIC by 44, because the DECwindows Compiler Interface requires 44 global pages for installation. If there are fewer than 952 unused pages (or 996 unused pages if you choose to install the DECwindows Compiler Interface), you can delete an existing known image with the Install Utility, or increase the GBLPAGES system parameter with the System Generation Utility by using the AUTOGEN.COM procedure. For more information on using the AUTOGEN procedure, refer to the VMS system management documentation. Step 3: Determine the number of global sections available. $ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE CURRENT SYSGEN> SHOW GBLSECTIONS These commands determine whether there are enough global sections available to install VAX BASIC. The first number displayed is the maximum number of global sections. Compare this number to the number of global sections in use displayed by the Install Utility. VAX BASIC requires 4 global sections. However, if you choose to install the DECwindows Compiler Interface as a shared image, you must increase the total number of global sections from 4 to 5, because the DECwindows Compiler Interface requires 1 global section for installation. Therefore, if the amount displayed plus 4 (or plus 5 if you choose to install the DECwindows Compiler Interface) exceeds the system maximum of available global sections, you must increase the number of available global sections before you can install VAX BASIC. To increase the amount, you must increase the GBLSECTIONS parameter with the System Generation Utility by using AUTOGEN.COM. For more information on the AUTOGEN procedure, refer to the VMS documentation on system management operations. If the amount displayed plus 4 (or plus 5 if you choose to install the DECwindows Compiler Interface as a shared image) is less than the system maximum, you can exit from the System Generation Utility and continue. Step 4: Invoke the Install Utility and install VAX BASIC as a shared image. $ INSTALL INSTALL> ADD SYS$SYSTEM:BASIC.EXE/OPEN/SHARED INSTALL> ADD SYS$MESSAGE:BASIC$MSG.EXE/OPEN/SHARED INSTALL> EXIT If you choose to install the DECwindows Compiler Interface as a shared image, you should enter the following commands: $ INSTALL INSTALL> ADD VUE$LIBRARY:BASIC$DWCI.EXE/OPEN/SHARED INSTALL> EXIT Step 5: Update the system startup file to install VAX BASIC. To ensure that VAX BASIC is installed as a shared image each time the system is bootstrapped, include the following lines in SYS$MANAGER:SYSTARTUP_V5.COM (the site-specific startup file): $ INSTALL ADD SYS$SYSTEM:BASIC.EXE/OPEN/SHARED ADD SYS$MESSAGE:BASIC$MSG.EXE/OPEN/SHARED ADD VUE$LIBRARY:BASIC$DWCI.EXE/OPEN/SHARED EXIT ____________________________________________________________ 8 Determining and Reporting Problems If an error occurs while you are using VAX BASIC, and you believe that the error is caused by a problem with VAX BASIC, you should take one of the following actions: 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 representative.) o If you have a Self-Maintenance Software Agreement, you may submit a Software Performance Report (SPR). o If you purchased VAX BASIC within the last 90 days and you think the problem is caused by a software error, you may submit a Software Performance Report (SPR). If you find an error in the VAX BASIC documentation, you should fill out and submit the Reader's Comments Form at the back of the document in which the error was found. If you report a documentation error, specify the section and page number where the error was found. ____________________________________________________________ 9 Maintenance Updates DIGITAL may periodically issue maintenance updates of VAX BASIC. 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, the maintenance update includes new release notes. The release notes describe the changes that have been made to VAX BASIC since the previous release. The updated release notes are provided online. You should read the release notes when you first install VAX BASIC; they are also accessible at any time after the product is installed. For information on reading the release notes when you install VAX BASIC, follow the installation procedure through step 4. To locate the release notes after VAX BASIC is installed, display or print the file SYS$HELP:BASIC$034.RELEASE_NOTES, or type the following: $ HELP BASIC RELEASE_NOTES ____________________________________________________________ 10 Sample Installation This section contains a sample installation of VAX BASIC. 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 Read Before Installing or Using VAX BASIC letter before you install this product. This letter notes any significant changes in the installation that vary from this sample. Username: SYSTEM Password: . . . $ set def sys$update $ @VMSINSTAL BASIC034 CSA1: VAX/VMS Software Product Installation Procedure It is 16-OCT-1989 at 14:23. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? Please mount the first volume of the set on CSA1:. * Are you ready? yes %MOUNT-I-MOUNTED, BASIC mounted on _CSA1: * Enter installation options you wish to use (none): The following products will be processed: BASIC V3.4 Beginning installation of BASIC V3.4 at 14:27 %VMSINSTAL-I-RESTORE, Restoring product saveset A ... %VMSINSTAL-I-REMOVED, The product's release notes have been successfully moved to SYS$HELP. VAX BASIC V3.4 Installation Procedure There are three possible installation options. They are described as follows: 1) Perform a normal installation of BASIC. 2) Install VAX/VMS system definitions text library only (10-45 minutes). 3) Obtain a copy of the BASIC message text for modification. * Which option do you want to use [1]: * Do you want to install the BASIC HELP files [YES]? * Do you want to install the VAX/VMS system definitions [NO]? yes * Do you want to install the DECwindows Compiler Interface [YES]? * Do you want to install the sample graphics programs [YES]? * Do you want to purge files replaced by this installation [YES]? no Product: BASIC Producer: DEC Version: 3.4 Release Date: * Does this product have an authorization key registered and loaded? yes No further questions will be asked. Installation continuing... %VMSINSTAL-I-RESTORE, Restoring product saveset B ... %VMSINSTAL-I-SYSDIR, This product creates system disk directory VMI$ROOT:[SYSTEST.BASIC]. ************************************************************************ If you have DEC GKS FOR VMS V2.0 or later on your system, VAX BASIC V3.4 allows you to use graphics language statements. The procedure: SYS$SYSROOT:[SYSTEST.BASIC]BASIC$GRAPHICS_IVP.COM will verify that VAX BASIC graphics capabilities work on your system. You must execute this procedure on a terminal with graphics capabilities. ************************************************************************ %VMSINSTAL-I-INSHELP, Installing BASIC Help files %VMSINSTAL-I-RESTORE, Restoring product save set C ... %VMSINSTAL-I-INSSTARLET, Installing BASIC system definitions %VMSINSTAL-I-INSSTARLT1, Requires approximately 10 to 45 minutes %VMSINSTAL-I-RESTORE, Restoring product save set D ... %VMSINSTAL-I-INSSAMPLE, Installing sample programs and PICTURE libraries %VMSINSTAL-I-RESTORE, Restoring product save set E ... %VMSINSTAL-I-RESTORE, Restoring product save set F ... %VMSINSTAL-I-SYSDIR, This product creates system disk directory VMI$ROOT:[SYSHLP.EXAMPLES.BASIC]. ********************************************************************* A number of sample programs demonstrating BASIC graphics statements have been copied to [SYSHLP.EXAMPLES.BASIC]. Read [SYSHLP.EXAMPLES.BASIC]BASIC_EXAMPLES.TXT for information on the sample programs provided. ********************************************************************* %VMSINSTAL-I-RESTORE, Restoring product save set G... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... %VMSINSTAL-I-RUNIVP, Executing installation verification procedure %VMSINSTAL-I-IVPSUCCESS, VAX BASIC T3.4 Installation test PASSED The BASIC IVP has succeeded Installation of BASIC V3.4 completed at 15:02 VMSINSTAL procedure done at 15:02