DEC_Pascal____________________________________ Installation Guide for OpenVMS Systems Order Number: AA-PXSPB-TK July 1995 This guide explains how to install the DEC Pascal compiler and related software components on an OpenVMS Alpha or OpenVMS VAX system. Revision/Update Information: This is a updated guide. Operating System: OpenVMS Alpha Version 6.1 or higher. OpenVMS VAX Version 5.2 or higher. Future maintenance releases may require higher versions. Software Version: DEC Pascal Version 5.4 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ June 1993 Revised, July 1995 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1995. All Rights Reserved. The postpaid Reader's Comments forms at the end of this document request the user's critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: CDD/Repository, DEC, DECset, DECsupport, Digital, OpenVMS, VAX, VAX DOCUMENT, VMS, VMScluster, and the DIGITAL logo. ZK6141 This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. ________________________________________________________________ Contents Preface.................................................. v 1 Preparing to Install DEC Pascal 1.1 Required Operating System Components......... 1-1 1.2 Optional Software............................ 1-2 1.3 License Registration......................... 1-2 1.4 Multiple Version Support..................... 1-3 1.5 Installation Procedure Requirements.......... 1-4 1.5.1 Installation Account Privileges and Disk Space.................................... 1-4 1.5.2 System Parameters........................ 1-6 1.5.2.1 Calculating the Values for GBLPAGES and GBLSECTIONS............................ 1-8 1.5.2.2 Changing System Parameter Values with AUTOGEN................................ 1-9 1.5.3 Backing Up Your System Disk.............. 1-11 1.6 Stopping the Installation.................... 1-11 2 Installing DEC Pascal 2.1 Installation Procedure....................... 2-1 2.2 Error Recovery............................... 2-12 3 After Installing DEC Pascal 3.1 Running the Installation Verification Procedure (IVP) Separately................... 3-1 3.2 User Account Requirements.................... 3-2 3.2.1 Privileges............................... 3-2 3.2.2 Quotas................................... 3-2 3.3 Editing System Files......................... 3-2 iii 3.4 Enhancing DEC Pascal Performance............. 3-2 3.4.1 Using Multiple Environment Files On OpenVMS VAX systems only................. 3-2 3.4.2 Installing DEC Pascal as a Shared Image.................................... 3-3 3.4.3 Improving DEC Pascal Compilation Performance on OpenVMS Alpha Systems..... 3-3 3.4.3.1 Required Virtual Memory................ 3-6 3.4.3.2 Required Physical Memory............... 3-7 3.4.3.3 Effects of Physical Memory............. 3-9 3.5 Determining and Reporting Problems........... 3-9 Tables 1-1 Disk Space Requirements.................. 1-5 iv ________________________________________________________________ Preface This guide explains how to: o Install DEC Pascal on an OpenVMS Alpha or OpenVMS VAX system o Read the online release notes This guide applies to DEC Pascal Version 5.4 and all subsequent maintenance releases up to the next major product release. Intended Audience This guide is intended for the system manager who installs DEC Pascal. Keep this guide with your distribution kit. You will need it to install maintenance updates or to reinstall DEC Pascal for any other reason. At the back of this guide are two Reader's Comments forms. If you have any comments about this document, fill out one form and mail it. Your comments will be considered for the next revision of the installation guide. Document Structure This guide contains the following chapters: o Chapter 1 describes the hardware and software requirements for DEC Pascal installation and related procedures that you complete before installing DEC Pascal. o Chapter 2 describes the DEC Pascal installation procedure. v o Chapter 3 describes the DEC Pascal Installation Verification Procedure (IVP) and any postinstallation procedures you must complete to use DEC Pascal. Associated Documents In addition to this guide, the DEC Pascal documentation set includes the following books: o DEC Pascal User Manual for OpenVMS Systems o DEC Pascal Language Reference Manual For general information on OpenVMS system management, see the OpenVMS operating system documentation set. For help understanding OpenVMS system error messages, see the OpenVMS System Messages and Recovery Procedures Reference Manual or the online HELP/MESSAGE facility. vi Conventions This guide uses the following documentation conventions: vii viii __________________________________________________________ Convention____________Meaning_____________________________ $ The dollar sign ($) is the default DCL prompt. In code examples, an enclosed symbol indicates that you must press the named key on the keyboard. Ctrl/Y In interactive examples, this symbol indicates that you must press the Ctrl key while you simultaneously press another key (in this case, Y). Username: In interactive examples, prompts @SYS$UPDATE:VMSINSTAL or displayed text appears in a monospace font. User input appears in bold monospace font. UPPERCASE In syntax descriptions and interactive examples, uppercase letters indicate the name of a command, a file, a parameter, a procedure, or a utility. lowercase Lowercase letters indicate variable information such as a file name or a device name. file-spec,... Horizontal ellipses indicate that you can enter additional parameters, values, or information. [YES] Square brackets indicate that the enclosed item is a default value in a VMSINSTAL prompt. Also, square brackets serve as delimiters for a directory name in a file specification. VMS system All references to VMS system refer to the OpenVMS Alpha or the OpenVMS VAX operating system. On OpenVMS Alpha This guide uses labels to indicate systems only information that applies to one or On OpenVMS VAX more platforms. systems only n In some code examples, version numbers are given as n. When you install DEC Pascal, the actual version numbers appear on your ix ______________________screen._____________________________ Unless otherwise noted, press the Return key after entering commands and responses to command prompts. x 1 ________________________________________________________________ Preparing to Install DEC Pascal This chapter discusses the preparations and requirements necessary for installing DEC Pascal Version 5.4. Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or if you find that parts of it are missing, contact your Digital representative. DEC Pascal provides online release notes, which are copied to the following file during installation: SYS$HELP:PASCAL05n.RELEASE_NOTES Digital strongly recommends that you read the release notes before proceeding with the installation. For information on accessing the online release notes, see Section 2.1. Your distribution kit includes a "Read First" cover letter . Please read this cover letter for information that is important for you to know before installing DEC Pascal. This information may not be included in this installation guide or in the release notes. 1.1 Required Operating System Components DEC Pascal Version 5.4 requires OpenVMS Alpha Version 6.1 or higher, or OpenVMS VAX Version 5.2 or higher. Future DEC Pascal releases may require higher versions of the OpenVMS operating system, as described in the online release notes or the Read First cover letter for your operating system. Preparing to Install DEC Pascal 1-1 The OpenVMS operating system comes with a variety of support options or components. For a complete list of the required components, see the Software Support Addendum (SSA), which comes with the DEC Pascal Software Product Description (SPD). 1.2 Optional Software The following is a list of optional software that you can use together with DEC Pascal: o CDD/Repository o DECset For a complete list of optional software products and their required version numbers for DEC Pascal, see the System Software Addendum (SSA), which is included in your kit. 1.3 License Registration You must register the DEC Pascal license through the OpenVMS License Management Facility (LMF) in accordance with the license agreement signed by your site. The license registration information you need is contained in the Product Authorization Key (PAK) that is shipped with DEC Pascal if you ordered the license and media together; otherwise, the PAK is shipped separately to a location based on your license order. The PAK is a paper certificate that contains information about the license to run a particular piece of software. If you are installing DEC Pascal as an update on a node or cluster that is licensed for this software, you have already completed the License PAK registration requirements. During the installation, the system asks whether you have registered the DEC Pascal license and loaded the appropriate PAK. Before you start the installation, you must register and load your license for DEC Pascal to be able to run the Installation Verification Procedure (IVP) and for users to be able to run DEC Pascal. 1-2 Preparing to Install DEC Pascal To register a license, first log in to the system manager's account (username: 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 License PAK. o At the DCL prompt ($), enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to License PAK information. For complete information on using LMF, see the manual on the License Management Utility in the OpenVMS documentation set. 1.4 Multiple Version Support DEC Pascal provides support for using multiple versions of the compliler on the same OpenVMS system. During installation, you have the opportunity to save the current version of the compiler for later use. If chosen, the installation copies the current compiler before installing the new compiler. The kit provides 3 command files to display and control which DEC Pascal compiler is used. o SYS$SYSTEM:PASCAL$SHOW_VERSIONS.COM is used to display all DEC Pascal compilers saved on the system and their version numbers. It also shows the current settings for process, job, group, and system-wide compiler settings. This command file has no parameters. o SYS$SYSTEM:PASCAL$SET_VERSION.COM is used to select a DEC Pascal compiler other than SYS$SYSTEM:PASCAL.EXE. If invoked without parameters, it will display the currently available compilers and ask for a filename to use for the process-wide compiler setting. It has 2 optional parameters. The first parameter can be PROCESS, JOB, GROUP, or SYSTEM. This selects the level of visibility for the selected compiler. The second parameter can be a filename to use instead of being prompted for a file. This allows you to place a compiler selection in a LOGIN.COM or some other command file. All saved compilers are located in SYS$SYSTEM:. Preparing to Install DEC Pascal 1-3 o SYS$SYSTEM:PASCAL$DEFAULT_VERSION.COM is used to select the default DEC Pascal compiler when SYS$SYSTEM:PASCAL$SET_VERSION.COM has not be used. The installation always provides a new SYS$SYSTEM:PASCAL.EXE and copies existing compilers. You can use this command file to select one of the saved compil- ers to be SYS$SYSTEM:PASCAL.EXE and rename the existing SYS$SYSTEM:PASCAL.EXE for later use via SYS$SYSTEM:PASCAL$SET_VERSION.COM. 1.5 Installation Procedure Requirements The installation of DEC Pascal takes approximately 5 to 45 minutes, depending on your system configuration. 1.5.1 Installation Account Privileges and Disk Space To install DEC Pascal, you must be logged in to an account that has SETPRV or at least the following privileges: o CMKRNL o WORLD o SYSPRV ________________________Note ________________________ VMSINSTAL turns off the BYPASS privilege at the start of the installation. _____________________________________________________ DEC Pascal's requirements for free disk storage space are different during installation and after installation. Table 1-1 summarizes the storage requirements. 1-4 Preparing to Install DEC Pascal Table_1-1_Disk_Space_Requirements_________________________ Number of Blocks Required During After Kit_____________________Installation__Installation________ DEC Pascal Version 5.4 12,500 12,000 On OpenVMS Alpha systems only DEC Pascal Version 5.4 3,500 3,000 On OpenVMS VAX systems only DEC Pascal STARLET 11,500 10,000 files DEC_Pascal_examples______150___________150________________ Preparing to Install DEC Pascal 1-5 To determine the number of free disk blocks on the current system disk, enter the following DCL command: $ SHOW DEVICE SYS$SYSDEVICE ________________________Note ________________________ The DEC Pascal STARLET files (STARLET.PAS, PASCAL$xxxROUTINES.PAS, and so on) are built during the DEC Pascal installation from a file shipped with the OpenVMS operating system kit. This allows the same DEC Pascal kit to produce STARLET files that reflect the version of OpenVMS being used on the system. Since updating the version of OpenVMS may add new definitions, the peak and net block count requirements for installing DEC Pascal (see Table 1-1) may not always be accurate. The values in Table 1-1 are meant to accommodate the larger definition files. _____________________________________________________ 1.5.2 System Parameters Installing DEC Pascal requires certain system parameter settings. The minimum number of free global pagelets (512- byte subpage unit) and global sections needed for the installation depends on whether SYS$SYSTEM:PASCAL.EXE was previously installed as a shared image, as follows: o If not previously installed as a shared image: - One global section and a sufficient number of contiguous free global pagelets to contain the file SYS$LIBRARY:DCLTABLES.EXE. o If previously installed as a shared image or will be subsequently installed with the PASCAL%STARTUP command file (Section 3.4.2) - Two global sections and a sufficient number of contiguous free global pagelets to contain the file SYS$LIBRARY:DCLTABLES.EXE. 1-6 Preparing to Install DEC Pascal - 6,500 additional global pagelets on OpenVMS Alpha systems. - 1,500 additional global pagelets on OpenVMS VAX systems. These values represent the number of free global pagelets and global sections required for the installation, not the total number you need to run your system and other software. Preparing to Install DEC Pascal 1-7 ________________________Note ________________________ If you do not ensure that your system has the necessary global pagelets and global section SYSGEN parameters for the installation, the DCL tables can become corrupted in some situations. _____________________________________________________ 1.5.2.1 Calculating the Values for GBLPAGES and GBLSECTIONS To install and run DEC Pascal, you must have sufficient free contiguous global pagelets and global sections. To determine the number of global pagelets required by SYS$LIBRARY:DCLTABLES.EXE, enter the following DCL command: $ DIR/SIZE SYS$LIBRARY:DCLTABLES.EXE This command returns the size (in blocks) of SYS$LIBRARY:DCLTABLES.EXE. As an approximation, use this figure as the number of global pagelets for the file. To find the number of free contiguous global pagelets and free global sections, use the WRITE command with the F$GETSYI lexical function. The following example shows how to get this information at your terminal (the default for SYS$OUTPUT): $ WRITE SYS$OUTPUT F$GETSYI("CONTIG_GBLPAGES") 15848 $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLSECTS") 24 If the value of free global pagelets or global sections is less than the required value (see Section 1.5.2), you must increase the system parameter setting. Section 1.5.2.2 describes the procedures for increasing these values using AUTOGEN. 1-8 Preparing to Install DEC Pascal 1.5.2.2 Changing System Parameter Values with AUTOGEN If you do not have enough free global pagelets or free global sections to install DEC Pascal, you can do either of the following: o Delete an existing known image using the OpenVMS Install Utility. o Use the AUTOGEN command procedure to increase the GBLPAGES or GBLSECTIONS system parameters. AUTOGEN automatically adjusts values for parameters that are associated with the values you reset manually. To change system parameters with AUTOGEN, edit the following file: SYS$SYSTEM:MODPARAMS.DAT To change a parameter value listed in this file, delete the current value associated with that parameter and enter the new value. To add a new parameter, insert a line in the file that includes both the name of the parameter and its value. For example: WSMAX = 1024 To modify incremental parameters such as GBLPAGES and GBLSECTIONS, use ADD_. The following example increases the global pagelet setting by 2000: ADD_GBLPAGES = 2000 ________________________Note ________________________ When you set the page file quota, do not use a value that exceeds the amount of page file space available on the system. _____________________________________________________ After you make all your changes, exit from the editor and then execute the AUTOGEN procedure to recalculate your system parameters. Enter the following command at the DCL prompt to recalculate your system parameters and to reboot the system: Preparing to Install DEC Pascal 1-9 $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT When you specify REBOOT, AUTOGEN does an automatic system shutdown and then reboots the system. Any users logged on to the system are immediately disconnected during the shutdown. The automatic reboot puts the new parameter values into effect. AUTOGEN automatically adjusts some of the SYSGEN parameters, based on the consumption of resources since the last reboot. If you do not want to take advantage of this automatic adjustment, include the /NOFEEDBACK qualifier on the AUTOGEN command line. For more information about using AUTOGEN, see the OpenVMS System Management Subkit. 1-10 Preparing to Install DEC Pascal 1.5.3 Backing Up Your System Disk At the beginning of the installation, VMSINSTAL asks if you have backed up your system disk. Digital recommends that you do a system disk backup before installing DEC Pascal or any other software. Use the backup procedures that are established at your site. For details on performing a system disk backup, see the section on the Backup Utility in the OpenVMS system management documentation. 1.6 Stopping the Installation To stop the installation procedure at any time, use Ctrl/C. However, files created up to that point are not deleted. You must then delete these files interactively. Chapter 2 lists the directories and files created during the DEC Pascal installation. Preparing to Install DEC Pascal 1-11 2 ________________________________________________________________ Installing DEC Pascal This chapter explains how to install DEC Pascal: o Section 2.1 contains a step-by-step description of the installation procedure. o Section 2.2 describes error recovery considerations. 2.1 Installation Procedure The DEC Pascal installation procedure consists of a series of questions and informational messages. If you have not already done so, insert the Compact Disc (CD) or tape media into the CD drive or tape drive. 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 exits. You can then start the installation again. When the system prompts you with a question during the installation procedure, the default answer, if any, is enclosed in brackets ([]). To start the installation: 1. Invoke the VMSINSTAL command procedure. You should invoke the VMSINSTAL command procedure from privileged account, such as the SYSTEM account. The VMSINSTAL procedure is in the SYS$UPDATE directory. For example: Username: SYSTEM Password: $ SET DEFAULT SYS$UPDATE $ @SYS$UPDATE:VMSINSTAL (saveset-name) (device-name) [option-list] Installing DEC Pascal 2-1 The following list defines the elements of the VMSINSTAL procedure: saveset-name The installation name for the component. For DEC Pascal, use the following installation name: PASCAL05n To obtain the directory location of the DEC Pascal saveset on the CD, refer to the OpenVMS Alpha Layered Products Disc User's Guide that accompanies the CD distribution kit. Or, you can do the following before starting the installation: o To determine whether the CD drive is already mounted, enter the following command: $ SHOW DEVICE DKA400: If it is not mounted, enter the appropriate MOUNT command to mount the CD (omit the /FOREIGN qualifier). o To obtain the directory name, enter the following command: $ DIRECTORY DKA400:[000000]*pascal*.dir Directory DKA400:[000000] PASCAL05n.DIR;1 o To obtain the saveset name, use the DIRECTORY command specifying the directory file from the previous command: $ DIRECTORY DKA400:[PASCAL05n.KIT]*.A device-name The name of the device on which you plan to mount the media and the directory containing the DEC Pascal save set. In the following example, the device name is DKA400: and the directory is [PASCAL05n.KIT]. For tape installations, just enter the name of the tape device. 2-2 Installing DEC Pascal To specify the device name on the @VMSINSTAL command line, enter: DKA400:[PASCAL05n.KIT] DKA400: is the name of the CD drive used in the rest of the examples in this guide. option-list The word OPTIONS followed by one or more of the following option designators: A, L, N, R. Their meanings are as follows: o Auto_answer option (A) Initially creates a file that contains your answers to VMSINSTAL questions and prompts. You can then use the option (and the answer file) to save time during a reinstallation (typically after upgrading your system). o File log option (L) Logs all activity to the terminal during installa- tion. o Display or print the release notes (N) Indicates that you want to see the installation question on release notes. If you do not include the OPTIONS N parameter, VMSINSTAL does not ask you about the release notes. You should review the release notes before proceeding with the installation in case they contain additional information about the installation. If you are restarting the installation and have already reviewed the release notes, you do not need to specify OPTIONS N. ________________________Note ________________________ Even if you omit the N option when you invoke VMSINSTAL, the DEC Pascal release notes are copied automatically to the SYS$HELP directory. _____________________________________________________ o Alternate root option (R) Installing DEC Pascal 2-3 Allows you to install the product to a system root other than that of the running system. For detailed information on these VMSINSTAL options, see the OpenVMS documentation on software installation in the OpenVMS System Management Subkit. If you specify multiple options, use commas to separate the options, for example: OPTIONS A,N When you invoke VMSINSTAL, it checks the following: o Whether you are 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 sufficient quotas for installation This following example invokes VMSINSTAL to install DEC Pascal and shows the system response. This example uses the OPTIONS N release note option. $ @SYS$UPDATE:VMSINSTAL PASCAL05n DKA400:[PASCAL05n.kit] OPTIONS N OpenVMS Software Product Installation Procedure Vn.n It is dd-mmm-yyyy at hh:mm. Enter a question mark (?) at any time for help. If you do not supply the product name or the device name, VMSINSTAL prompts you for this information later in the installation procedure. VMSINSTAL does not prompt you for any options, so be sure to include whatever option you want on the VMSINSTAL command line. 2. Confirm system backup. * Are you satisfied with the backup of your system disk [YES]? VMSINSTAL asks if you are satisfied with your system backup. You should always back up your system disk before performing an installation. If you are satisfied with the backup of your system disk, press the Return key. Otherwise, enter NO to discontinue the 2-4 Installing DEC Pascal installation. After you back up your system disk, you can restart the installation. If you fail to include the device name of the VMSINSTAL command line, the following prompt is displayed: * Where will the distribution volumes be mounted: If this prompt is displayed, type the name of the distribution (media) device and directory that contains the DEC Pascal kit (save set). For example, if the media is contained on a CD located on unit DKA400:, type DKA400:[PASCAL05n.KIT] in reply to this question, as shown in the following example: * Where will the distribution volumes be mounted:DKA400:[PASCAL05n.KIT] Installing DEC Pascal 2-5 3. Verify the product being installed. The following products will be processed: PASCAL V5.n Beginning installation of PASCAL V5.n at hh:mm %VMSINSTAL-I-RESTORE, Restoring product saveset A... The product name and version are displayed. The first save set (A) is restored to a subdirectory of SYS$UPDATE. 4. Select a release notes option. Release notes included with this kit are always copied to SYS$HELP. 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]: If you specified OPTIONS N when you invoked VMSINSTAL, you are now asked to choose one of the four options for reviewing the release notes: o If you select option 1, VMSINSTAL displays the release notes immediately on the console terminal. You can terminate the display at any time by pressing Ctrl/C. o If you select option 2, VMSINSTAL prompts you for the name of the print queue that you want to use: * Queue name [SYS$PRINT]: You can then enter a queue name or press Return to send the file to the default output print device. o If you select option 3, VMSINSTAL displays the release notes immediately on the console terminal and then prompts you for a queue name for the printed version of the release notes. 2-6 Installing DEC Pascal o If you choose option 4, the release notes are not displayed or printed but are still copied to the following file in the SYS$HELP directory: SYS$HELP:PASCAL05n.RELEASE_NOTES Installing DEC Pascal 2-7 You can later use the HELP command to find the location of the release notes in the Help facility: $ HELP PASCAL RELEASE_NOTES Whichever option you choose, VMSINSTAL next asks the following question: * Do you want to continue the installation [NO]?: YES %VMSINSTAL-I-RELMOVED, The product's release notes have been successfully moved to SYS$HELP. To continue the installation, enter YES. Otherwise, press Return. In either case, the release notes are copied to a file in the SYS$HELP directory: SYS$HELP:PASCAL054.RELEASE_NOTES ________________________Note ________________________ The name of the release notes file installed by VMSINSTAL consists of the current product name (in this case, PASCAL) and version number (in this case, 054 for Version 5.4). Do not delete release notes for previous versions of DEC Pascal. _____________________________________________________ 5. Install the compiler. * Do you want to install the DEC Pascal compiler [YES]? The DEC Pascal kit contains the compiler, message files, command line definition, and help files. 6. Install STARLET. * Do you want to install the DEC Pascal definition files [YES]? The DEC Pascal kit contains definition files for OpenVMS System Services and several run-time library facility codes. These system definition files are built using information shipped with the OpenVMS operating system. The installation procedure determines whether DEC Pascal definition files already exist. If the files do not exist, the installation procedure notifies you of this and advises you to create the definition files. 2-8 Installing DEC Pascal If the DEC Pascal definition files exist, but the OpenVMS-supplied system definitions, which are the basis for the DEC Pascal definition files, have been modified since the last time the DEC Pascal definition files were created, the installation procedure advises you to recreate the files. If the DEC Pascal definition files exist and if the OpenVMS-supplied system definitions have not been modified since the last time the DEC Pascal definition files were created, the procedure tells you that it is not necessary to recreate the definition files. 7. Install the examples. * Do you want to install the DEC Pascal example programs [YES]? The DEC Pascal kit contains a set of example programs using many features of DEC Pascal and OpenVMS. The ex- amples are installed in the directory SYS$COMMON:[SYSHLP.EXAMPLES.PASCAL]. You can access them using the logical PASCAL$EXAMPLES, if you run the optional startup file SYS$STARTUP:PASCAL$STARTUP.COM (see Section 3.3). 8. Save previous compiler. * Do you want to save your existing DEC Pascal compiler [NO]? The DEC Pascal kit contains support to save your existing DEC Pascal compiler for access later. The installation provides various command files to display and select the saved DEC Pascal compilers. See Section 1.4 for more information. 9. Purge files. * Do you want to purge files replaced by this installation [YES]? You have the option to purge files from previous versions of DEC Pascal that are superseded by this installation. Purging is recommended. If you answered YES to question 8, you can answer YES to this question with no danger of deleting any saved compilers. 10.Choose the Installation Verification Procedure (IVP) option. Installing DEC Pascal 2-9 The installation procedure now asks if you want to run the IVP. The IVP for DEC Pascal checks that the installation is successful. Digital recommends that you run the IVP. * Do you want to run the IVP after the installation [YES]? This kit contains an IVP that is used to verify the correct installation of the DEC Pascal compiler. The IVP is located in: SYS$TEST:PASCAL$IVP.COM After DEC Pascal is installed, you can run the IVP independently to verify that the software is available on your system. You might need to run the IVP after a system failure to make sure that users can access DEC Pascal. 2-10 Installing DEC Pascal 11.Respond to license registration queries. Product: PASCAL Producer: DEC Version: 5.4 Release Date: dd-mmm-yyyy * Does this product have an authorization key registered and loaded? The installation procedure displays license information about your product and then asks if you have registered and loaded your Product Authorization Key (PAK). If you have not registered and loaded your PAK, you must answer NO to this question. You must register and load your PAK to successfully complete the installation. If you have not done so, you should stop the installation, register and load your PAK, and then start the installation procedure again. 12.Read informational messages. At this point, the installation procedure displays a number of informational messages that report on the progress of the installation. There are no further questions. If the installation procedure has been successful up to this point, VMSINSTAL moves the new or modified files to their target directories, updates help files, and updates DCL tables, if necessary. If you chose to have files purged, that work is done now. The following message is displayed: %VMSINSTAL-I-MOVEFILES, files will now be moved to their target directories... 13.Observe the Installation Verification Procedure (IVP). If you chose to run the IVP, VMSINSTAL runs it now. When the IVP runs successfully, you see the following messages displayed: ** Successful Installation of DEC Pascal V(n.n) on dd-mmm-yyyy at 20:19 ** ** Successful Installation of DEC Pascal STARLET Libraries ** Installing DEC Pascal 2-11 14.End the installation procedure. Installation of DEC Pascal V(n.n) completed at hh:mm VMSINSTAL procedure done at hh:mm These messages indicate that the entire installation procedure is complete. You can now log out of the privileged account: $ LOGOUT SYSTEM logged out at dd-mmm-yyyy 20:20:02 ________________________Note ________________________ 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.2 Error Recovery If errors occur during the installation itself or when the Installation Verification Procedure (IVP) is running, VMSINSTAL displays failure messages. If the installation fails, you see the following message: %VMSINSTAL-E-INSFAIL, The installation of DEC Pascal V(n.n) has failed. If the IVP fails, you see these messages: The DEC Pascal V(n.n) Installation Verification Procedure failed. %VMSINSTAL-E-IVPFAIL, The IVP for DEC Pascal V(n.n) has failed. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o Quotas necessary for successful installation are insufficient. o System parameter values for successful installation are insufficient. o The OpenVMS help library is currently in use. 2-12 Installing DEC Pascal o The product license has not been registered and loaded. For descriptions of the error messages generated by these conditions, see the OpenVMS documentation on system messages, recovery procedures, and OpenVMS software installation. If you are notified that any of these conditions exist, you should take the appropriate action as described in the message. For information on installation requirements, see Section 1.5. Installing DEC Pascal 2-13 3 ________________________________________________________________ After Installing DEC Pascal DEC Pascal is now installed and can be invoked by all users with the PASCAL command. The following tasks can be performed after installing DEC Pascal: o Running the Installation Verification Procedure (IVP) separately o Editing the system startup and shutdown files o Making the product usable on a VMScluster o Enhancing performance o Reporting problems The following sections describe these tasks in detail. 3.1 Running the Installation Verification Procedure (IVP) Separately You usually run the Installation Verification Procedure (IVP) during installation. If you want to run the IVP separately to ensure the integrity of installed files should system problems occur, execute the following command procedure: $ @SYS$TEST:PASCAL$IVP.COM If the IVP fails for any reason, the following message is displayed: DEC PASCAL VERSION V5.n TEST FAILED After Installing DEC Pascal 3-1 3.2 User Account Requirements Several products cannot be used unless certain privilege and quota requirements are met by user accounts. The following sections describe the privilege and quota requirements needed to work with DEC Pascal. 3.2.1 Privileges DEC Pascal does not require any special privileges. There is no benefit from installing the DEC Pascal compiler with privileges. 3.2.2 Quotas See Section 3.4 for information. 3.3 Editing System Files You can edit the system startup file to provide for automatic startup of DEC Pascal when your system is rebooted. Use the optional startup file to define the PASCAL$EXAMPLES logical name and to install DEC Pascal as a shared image (see Section 3.4.2). Edit the system startup file SYSSTARTUP_VMS.COM (or SYSTARTUP_V5.COM on OpenVMS VAX V5.n systems) to include the following line: $ @sys@startup:pascal$startup.com 3.4 Enhancing DEC Pascal Performance This section includes information on system tuning and explains how to install DEC Pascal as a shared image. 3.4.1 Using Multiple Environment Files On OpenVMS VAX systems only If you intend to use multiple DEC Pascal environment files, you can increase the compilation speed by modifying the FILLM quota of those processes that run the compiler. The DEC Pascal compiler will keep more than one environment file open during the compilation (with a maximum of 50 environment files). If you inherit more than 3-2 After Installing DEC Pascal 50 environment files, the compiler will close some of them in order to open other files. 3.4.2 Installing DEC Pascal as a Shared Image If you expect DEC Pascal to be used extensively on your system, you can reduce the system overhead and memory requirements by installing it as a shared image. To install DEC Pascal as a shared image on a system that is currently running, use the optional DEC Pascal startup file: SYS$STARTUP:PASCAL$STARTUP.COM Digital recommends, that you install DEC Pascal as shared on a system that has been rebooted recently because the available space in the global page table is less likely to be fragmented. The requirements for additional global pages and global sections are listed in section Section 1.5.2. 3.4.3 Improving DEC Pascal Compilation Performance on OpenVMS Alpha Systems For many user applications, the DEC Pascal for OpenVMS Alpha compiler requires significantly more system resources than DEC Pascal for OpenVMS VAX. The compiler will sometimes fail with a "%LIB-E-INSVIRMEM, insufficient virtual memory" error. Also, for very large programs (greater than 10,000 lines) there could be a report of an extremely long compile time. The following sections explain why DEC Pascal for OpenVMS Alpha systems requires more memory, and suggests actions to be taken to avoid resource problems. The Alpha architecture is a RISC (Reduced Instruction Set Computer) architecture. The VAX architecture is a CISC (Complex Instruction Set Computer) architecture. The main distinguishing characteristic of a RISC machine is that it has few instructions, and each instruction does a small amount of work. A CISC machine generally has many instructions, most of which perform many complicated operations in one step. After Installing DEC Pascal 3-3 By reducing the amount of work that is done in each instruction (and by reducing the number of instructions), the complexity of the hardware is reduced. This reduction in complexity allows the hardware designers to raise the clock speed (and thus the number of instructions per second that can be completed). This results in better overall system performance. Another characteristic of RISC systems is that compilers for these architectures generally must do a great deal more work than a corresponding compiler for a CISC architecture. For example, the compiler must compute the best way to use all of the functional units of the processor, and it must determine how to make the best use of registers and on-chip data cache because reads and writes to main memory are generally slow compared to the speed of the processor. The DEC Pascal for OpenVMS Alpha compiler is a globally optimizing compiler. The compiler constructs an internal representation of the entire Pascal program, and repeatedly traverses this structure at compile time, so that it can produce the most efficient machine code for the program. This results in high performance code, but the drawback is that the compiler requires more resources than the DEC Pascal for OpenVMS VAX compiler. 3-4 After Installing DEC Pascal The DEC Pascal for OpenVMS Alpha compiler will always require more resources than the DEC Pascal for OpenVMS VAX compiler because it must do more work. However, there are some things that can be done to reduce system resource usage: o Use the /NOOPTIMIZE qualifier when "checking" programs. The optimizer is one of the biggest users of system resources in the Pascal compiler and is turned on by default. Also, the higher the optimization level, the more memory required by the compiler. o Check system tuning. Since the Pascal compiler often needs a great deal of virtual memory, increase working-set limits for developers that use the compiler. This results in decreased paging and improvements in compile time. o Check program sizes. The bigger the program is, the more resources it requires. Section 3.4.3.1 and Section 3.4.3.2 provide basic guidance about memory requirements for DEC Pascal programs on OpenVMS Alpha systems. In many tuning exercises, it is instructive to work with a relatively quiet system, submit batch jobs, and retain the log files for later analysis. ________________________Note ________________________ The guidance in the following section is based on a study of a set of large modules. Please note that your results may differ. _____________________________________________________ For detailed information on OpenVMS tuning, see the OpenVMS System Manager's Manual, sections "Managing System Parameters" and "Managing System Page, Swap, and Dump Files". After Installing DEC Pascal 3-5 3.4.3.1 Required Virtual Memory If there is not enough virtual memory, the compile command may fail with the message "insufficient virtual memory". OpenVMS has two parameters that control the amount of virtual memory available to a process: o The system generation parameter VIRTUALPAGECNT, which sets an upper bound on the number of pagelets of virtual memory for any process in the system. o The AUTHORIZE parameter PGFLQUOTA, which determines the number of pagelets a process can reserve in the system's page file(s). After an "insufficient virtual memory" error, issue the following DCL command to see the Peak virtual size used by the process, or look at the Peak page file size at the end of a batch job's log: SHOW PROCESS/ACCOUNTING If the peak size is at the system generation parameter VIRTU you will need to raise this value. If the peak size is below VIRTUALPAGECNT, and at or above PGFLQUOTA, run AUTHORIZE to increase PGFLQUOTA for the Pascal users. Peak size can exceed PGFLQUOTA because some virtual memory, such as read-only image code, is not allocated page file space. It is difficult to predict precisely how much virtual memory will be required for a compilation, but a starting point for system tuning can be computed by either of the following: o Multiply 250 times the size of the largest program in disk blocks (including all INCLUDE files referenced). o Multiply 25 times the number of lines in the program (including all INCLUDE files. The resulting figure can then be used as a starting point for the system generation parameter VIRTUALPAGECNT. Place a line in the parameter file SYS$SYSTEM:MODPARAMS.DAT. For example, if you estimate 370,000 pages, add the following line in MODPARAMS, run AUTOGEN and reboot. 3-6 After Installing DEC Pascal MIN_VIRTUALPAGECNT = 400000 If the compilation now completes successfully, use the command SHOW PROCESS/ACCOUNTING to determine the Peak Virtual Size; if the actual peak is significantly less than the value computed above, you can reduce VIRTUALPAGECNT. When modifying VIRTUALPAGECNT and PGFLQUOTA, you may also need to increase the size of the page file. 3.4.3.2 Required Physical Memory When dealing with physical memory you must know: o If there enough memory on the system o If enough available to the process running the compilation If the physical memory on the system is too small, the command LOGOUT/FULL (which is automatically issued at the end of a batch job) will show a high number of faults, for example, > 100,000 for a single compilation, and an "Elapsed time" that greatly exceeds the "Charged CPU time", as the system waits for disk I/Os to resolve page faults. In this situation, tuning attempts may be of limited benefit. If the physical memory on the system is adequate, but the physical memory allotted to the process running the compilation is too small, you may still observe a large number of faults, but elapsed time may remain closer to CPU time. This is because OpenVMS resolves page faults from the page caches (free list, modified list) whenever possible, avoiding the relatively slow disk I/Os. In this situation, basic tuning may also be beneficial. The amount of physical memory required will vary, but it should be a large fraction of the process peak virtual size-as close to 1.0 as practical. The reason for this is that the compiler makes multiple passes over the internal representation of the program; therefore a page which falls out of the working set in one pass is probably going to be needed again on the very next pass. After Installing DEC Pascal 3-7 The physical memory present on the system can be determined by the command SHOW MEMORY/PHYSICAL. The physical memory used by the compilation is reported as "Peak working set size" by the command SHOW PROCESS /ACCOUNTING or at the end of a batch log file. More physical memory can be made available to a process by minimizing the number of competing processes on the system (for example, by compiling one module at a time, or scheduling large compiles for off hours.) It can also be made available to a process (if it is present on the machine) by adjusting the system generation parameter WSMAX and the corresponding WSEXTENT (in AUTHORIZE). Such adjustments must be attempted with great caution, as the system may hang if memory is oversubscribed and you create a situation where OpenVMS effectively has no options to reclaim memory. The following guidelines have been found useful: o Set the Pascal users' WSEXTENT (in AUTHORIZE or INITIALIZE/QUEUE) to match WSMAX. o Keep WSQUOTA (in AUTHORIZE or INITIALIZE/QUEUE) low. Make sure that no process or batch queue has a WSQUOTA of more than about 20% of physical memory. The difference between WSEXTENT and WSQUOTA allows OpenVMS to manage memory to meet varying demands. o Use AUTOGEN. AUTOGEN will attempt to make a consistent set of changes that do not interfere with each other. By default, AUTOGEN will set the maximum working set (system generation parameter WSMAX) to 25% of physical memory. This value is reasonable for a workstation or multi-user system with many active processes. o WSMAX can be increased to a somewhat larger value by editting MODPARAMS.DAT. For a system with 64 MByte of physical memory, try setting WSMAX to no more than about 40% of physical memory, or 52000 pagelets. With 128 MByte or more of physical memory, a setting of 50% of physical memory can be attempted. 3-8 After Installing DEC Pascal 3.4.3.3 Effects of Physical Memory The effects of physical memory on compilation time were studied for a set of seven large modules. The modules ranged in size from about 1600 to 3300 disk blocks. Your results may differ; but to help to give a rough appreciation for the effect of physical memory on compilation time, the following can be noted: o When the amount of physical memory available to the processes matched the amount of virtual memory, the elapsed times were close to the CPU times. o As the physical memory was reduced, CPU times rose only slightly, about ten percent. o As the physical memory was reduced, elapsed times were elongated, at the rate of about one hour for each 100MB of difference between Peak Virtual Size and the actual memory available. For example, when compiling a program that used a Peak Virtual Size of 947760 pagelets, or 463MB (1MB = 2048 pagelets), on a system where about 180MB of physical memory was available to user processes, the compile required about three hours longer than on a 512MB system. Your results will be strongly affected by the speed of the devices that are used for paging. Both virtual memory and physical memory requirements can be reduced by breaking large modules up into smaller modules. 3.5 Determining and Reporting Problems If an error occurs while using DEC Pascal and you believe the error is caused by a problem with DEC Pascal, take one of the following actions: o If you have a basic or DECsupport Software Agreement, call your Customer Support Center (CSC). The CSC provides telephone support for high-level advisory and remedial assistance. o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). After Installing DEC Pascal 3-9 o If you purchased DEC Pascal within the last 90 days and you think the problem is caused by a software error, you can submit an SPR. If you find an error in the DEC Pascal documentation, please fill out one of the Reader's Comments forms at the back of the document containing the error and send the form to Digital. Please include the section and page number where the error occurred. When you submit an SPR, please take the following steps: 1. Describe as accurately as possible the state of the system and the circumstances when the problem occurred. Include in the description the version number of DEC Pascal being used. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 3. Provide a listing of the program. Remember to include listings of any command files, relevant data files, and so forth. 4. If the program is longer than 50 lines, submit a copy of the program on machine-readable media (floppy diskette or magnetic tape). If necessary, also submit a copy of the program library used to build the application. 5. Report only one problem per SPR. This will facilitate a faster response. 6. Mail the SPR package to Digital. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps Digital give accurate and timely service to software problems. 3-10 After Installing DEC Pascal