DEC_Ada_______________________________________ Installation Guide for OpenVMS Alpha Systems Order Number: AA-PW1VB-TE February 1995 This guide contains instructions for installing DEC Ada Version 3.2 on OpenVMS Alpha systems. It also explains how to read the online release notes before or after installing the product. This guide applies to DEC Ada Version 3.2 and all maintenance updates throughout that version. Revision/Update Information: This revised guide supersedes the Installation Guide for OpenVMS AXP Systems (Order No.: AA-PW1VA-TE). Operating System & Version: OpenVMS Alpha Version 6.1 or higher Software Version: DEC Ada Version 3.2 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ First Printing, January 1993 Second Printing, February 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 your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: DEC, DEC Ada, DECnet, DECwindows, Digital, OpenVMS, VAX, VAX DOCUMENT, VMS, VMScluster, VAXstation, and the DIGITAL logo. ZK6255 This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. ________________________________________________________________ Contents Preface.................................................. vii 1 Preparing for DEC Ada Installation 1.1 Required Operating System and Prerequisite Hardware and Software........................ 1-1 1.2 License Registration......................... 1-2 1.3 VMScluster Considerations.................... 1-3 1.4 Installation Procedure Requirements.......... 1-3 1.4.1 Privileges and Disk Space................ 1-3 1.4.2 System Parameters........................ 1-4 1.4.2.1 Checking UAF Parameters................ 1-4 1.4.2.2 Calculating the Values for GBLPAGES and GBLSECTIONS............................ 1-5 1.4.2.3 Changing System Parameter Values with AUTOGEN................................ 1-5 1.4.3 Process Account Quotas................... 1-6 1.4.4 VMSINSTAL Requirements................... 1-8 1.4.5 Backing Up Your System Disk.............. 1-8 2 Installing DEC Ada 2.1 The Installation Procedure................... 2-1 2.1.1 Invoke VMSINSTAL......................... 2-2 2.1.2 Confirm System Backup.................... 2-4 2.1.3 Mount the Media.......................... 2-4 2.1.4 Select a Release Notes Option............ 2-5 2.1.5 Choose the Installation Verification Procedure Option......................... 2-6 2.1.6 Select Installation Options.............. 2-6 2.1.7 Read Informational Messages.............. 2-7 iii 2.1.8 Observe the Installation Verification Procedure................................ 2-8 2.1.9 End the Installation Procedure........... 2-8 2.2 Error Recovery............................... 2-9 2.3 Keeping the Currently Existing Compiler Available.................................... 2-10 2.3.1 Saving the Currently Existing HELP File..................................... 2-13 2.4 Installing DEC Ada on a VMScluster........... 2-13 2.5 Postinstallation Notes....................... 2-14 3 After Installing DEC Ada 3.1 Running the Installation Verification Procedure Separately......................... 3-1 3.2 Error Conditions............................. 3-1 3.3 Maintenance Updates.......................... 3-2 3.4 Determining and Reporting Problems........... 3-3 A Sample Installation B Files and Logical Names Installed on Your System B.1 File Names................................... B-1 B.2 Logical Names................................ B-2 C Tuning OpenVMS Alpha Systems C.1 Improving Product Performance................ C-1 C.1.1 ASTLM.................................... C-2 C.1.2 ENQLM.................................... C-3 C.1.3 FILLM.................................... C-3 C.1.4 PRCLM.................................... C-4 C.1.5 TQELM.................................... C-4 C.1.6 Virtual Memory Usage..................... C-5 C.1.7 Batch Queue Parameters................... C-8 C.1.8 WSMAX.................................... C-8 C.1.9 Channel Count Parameters................. C-9 C.1.10 Program Library Networking Effects....... C-9 C.2 Relevant File Quotas and Cache Sizes......... C-10 C.2.1 Caching Files............................ C-11 C.2.2 Caching File Headers..................... C-11 iv C.2.3 Caching Directory Files.................. C-13 C.3 Using DECRam on OpenVMS Systems.............. C-13 Figures 1 Documentation Reading Path for Related Documents................................ vii 2 Documentation Reading Path for DEC Ada Documentation............................ viii Tables 1 Conventions Used in This Guide........... ix 1-1 Minimum Required System Parameter Values................................... 1-4 1-2 Process Account Quotas for the Installing Account.................................. 1-7 B-1 DEC Ada Logical Names and Locations...... B-2 v ________________________________________________________________ Preface This guide explains how to install DEC Ada Version 3.2 on OpenVMS Alpha systems. Keep this guide with your distribution kit. You need it to install maintenance updates or to reinstall DEC Ada for any other reason. At the back of this guide are two Reader's Comments forms. If you have any comments about this guide, fill out a form and mail it. Your comments will be considered for the next revision of this installation guide. Intended Audience This guide is intended for the system manager who installs DEC Ada software. Documentation Reading Path Figures 1 and 2 show the relationship of the Ada documentation set to other documentation that may be helpful. Figure 1 Documentation Reading Path for Related Documents vii Figure 2 Documentation Reading Path for DEC Ada Documentation viii Document Structure This guide contains the following chapters and appendixes: o Chapter 1 describes the operating system and hardware requirements for DEC Ada installation and related procedures that you complete before installing DEC Ada. o Chapter 2 describes the step-by-step instructions for the installation. o Chapter 3 describes postinstallation actions and considerations. o Appendix A contains the output from a sample DEC Ada installation. o Appendix B contains a list of files installed and logicals defined as a result of the installation procedure. o Appendix C describes how to tune your system after you have installed DEC Ada. Conventions Table 1 shows the conventions used in this guide. Table_1_Conventions_Used_in_This_Guide____________________ Convention_______Description______________________________ $ A dollar sign ($) represents the VMS DCL system prompt. In interactive examples, a label enclosed in a box indicates that you press a key on the terminal, for example, . Ctrl/x The key combination Ctrl/x indicates that you must press the key labeled Ctrl while you simultaneously press another key, for example, Ctrl/Y or Ctrl/Z. (continued on next page) ix Table_1_(Cont.)_Conventions_Used_in_This_Guide____________ Convention_______Description______________________________ boldface In interactive examples, boldface monospace text monospace text represents user input. file-spec . . . A horizontal ellipsis following a parameter, option, or value in syntax descriptions indicates that additional parameters, options, or values can be entered. n A lowercase italic n indicates the generic use of a number. . . . A horizontal ellipsis in an Ada example or figure indicates that not all of the statements are shown. . A vertical ellipsis in an interactive . figure or example indicates that not all . of the commands and responses are shown. italic text Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number.) UPPERCASE TEXT Uppercase indicates the name of a command, routine, parameter, procedure, utility, file, file protection code, or _________________the_abbreviation_for_a_system_privilege._ x 1 ________________________________________________________________ Preparing for DEC Ada Installation This chapter discusses the preparations and requirements necessary for installing DEC Ada on OpenVMS Alpha systems. 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. ________________________Note ________________________ DEC Ada provides online 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. _____________________________________________________ 1.1 Required Operating System and Prerequisite Hardware and Software DEC Ada Version 3.2 requires OpenVMS Version 6.1 or higher. For a complete list of the required operating system com- ponents, current hardware requirements, and prerequisite and optional software and their required version numbers, see the Software Product Description (SPD). Preparing for DEC Ada Installation 1-1 1.2 License Registration If you are installing DEC Ada Version 3.2 on a newly licensed node or cluster, you must first register a License Product Authorization Key (License PAK) using the License Management Facility (LMF). The License PAK can be shipped along with the kit if you ordered the license and media together. Otherwise, the PAK is shipped separately to a location based on your license order. If you are installing DEC Ada Version 3.2 as an update on a node or cluster already licensed for this software, you must register the Service Update PAK (SUP) that is included in your Service Update Kit. If you already registered a License PAK or a SUP for this product on this node or cluster, you do not need to register the SUP. If you are installing an update of DEC Ada but lack a service contract, call your Digital representative for instructions on how to get a License PAK. If you are installing prerequisite or optional software along with DEC Ada, review the PAK status and install the PAKs for any prerequisite or optional software before you install DEC Ada. You must register and load your license for DEC Ada before you start the installation. To register a license under OpenVMS, 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 License PAK. o At the DCL prompt ($), enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to License PAK information. If you plan to use DEC Ada on more than one node in a VMScluster, you need to perform a license load on the other nodes after you complete this installation. For complete information on using LMF, see the OpenVMS License Management Utility Manual. 1-2 Preparing for DEC Ada Installation 1.3 VMScluster Considerations If you are running DEC Ada on a VMScluster, VMSINSTAL automatically installs new versions as known or shared images only on the machine on which the installation is actually performed. You must manually install new versions as known or shared images on other ma- chines using the OpenVMS Install Utility or invoke SYS$STARTUP:ADA$STARTUP.COM on each of the other cluster members. 1.4 Installation Procedure Requirements This section and those that follow discuss various requirements for installing DEC Ada on OpenVMS Alpha systems. 1.4.1 Privileges and Disk Space To install DEC Ada, you must be logged in to an account that has SETPRV or at least the following privileges: o CMKRNL o WORLD o SYSPRV VMSINSTAL turns off BYPASS privilege at the start of the installation. The installation checks the system disk for the space it requires to install DEC Ada. For a summary of the storage requirements, refer to the SPD. To determine the number of free disk blocks on the current system disk, enter the following command at the DCL prompt ($): $ SHOW DEVICE SYS$SYSDEVICE If DEC Ada has been previously installed and if you wish to save the previous installation, the product requires 71,000 blocks of disk space for full installation. If DEC Ada has not been installed previously, it requires 103,000 blocks for full installation. Preparing for DEC Ada Installation 1-3 1.4.2 System Parameters Installing DEC Ada requires certain system parameter settings. Table 1-1 lists the minimum required system parameter values for the installation. Depending on the type of programs and applications running at your site, you might need higher values for some settings. Table_1-1_Minimum_Required_System_Parameter_Values________ System_Parameter___________Minimum_Value__________________ GBLPAGES[1] 11000 + DCLTABLES GBLSECTIONS[1] 10 __________________________________________________________ [1]The values listed for these system parameters 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. __________________________________________________________ To use DEC Ada, each account or batch queue that invokes the DEC Ada compiler must have TMPMBX and NETMBX privileges. The following sections show you how to: o Check UAF parameters o Calculate values for the GBLPAGES and GBLSECTIONS system parameters o Change parameter values with the AUTOGEN command procedure 1.4.2.1 Checking UAF Parameters Before you install DEC Ada, you should check whether your account has sufficient quotas to perform the installation. You can check the quotas by entering the following command at the DCL prompt to invoke the AUTHORIZE Utility: $ RUN SYS$SYSTEM:AUTHORIZE UAF> SHOW SYSTEM After checking your quotas, enter the EXIT command at the UAF> prompt to return to DCL level. 1-4 Preparing for DEC Ada Installation 1.4.2.2 Calculating the Values for GBLPAGES and GBLSECTIONS To install and run DEC Ada, you must have sufficient free global pagelets and global sections. You must first find out how many free global pagelets and sections you have on your system. Then use AUTOGEN if you need to increase the GLBPAGES and GBLSECTIONS system parameters. For example, you can use the WRITE command with the F$GETSYI lexical function to find the number of free global pagelets and global sections. The following example shows how to get this information at your terminal (the default for SYS$OUTPUT): $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLPAGES") 15848 $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLSECTS") 24 If the values the system displays are greater than the values in Table 1-1, you do not need to increase the values for these parameters. If the value of free global pagelets or global sections is less than the value in Table 1-1, you must increase the system parameter setting. Section 1.4.2.3 describes the procedures for increasing these values using AUTOGEN. 1.4.2.3 Changing System Parameter Values with AUTOGEN Use the AUTOGEN command procedure to change 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, add a line to the file that includes both the name of the parameter and its value. For example: WSMAX = 1024 Preparing for DEC Ada Installation 1-5 To modify incremental parameters such as GBLPAGES and GBLSECTS, use ADD_. The following example increases the global page setting by 2000: ADD_GBLPAGES = 2000 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 execute the AUTOGEN procedure to recalculate your system parameters. Enter the following command at the DCL prompt: $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT When you specify REBOOT, AUTOGEN performs 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. The AUTOGEN command procedure 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.4.3 Process Account Quotas The account you use to install DEC Ada must have suffi- cient quotas to enable you to perform the installation. Table 1-2 summarizes the process quotas required for the installation account. For more information about these process quotas and the relationships among them, see Appendix C. 1-6 Preparing for DEC Ada Installation Table 1-2 Process Account Quotas for the Installing __________Account_________________________________________ Account_Quota_____Value___________________________________ ASTLM 24 BIOLM 18 BYTLM 18000 DIOLM 18 ENQLM 300 FILLM 100 __________________________________________________________ User account quotas are stored in the file SYSUAF.DAT. Use the Authorize Utility (AUTHORIZE) to verify and change user account quotas. First set your directory to SYS$SYSTEM and then run AUTHORIZE: $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> At the UAF> prompt, enter the SHOW command with an account name to check a particular account. For example: UAF> SHOW SMITH To change a quota, enter the MODIFY command. The following example changes the FILLM quota for the SMITH account and then exits from the utility: UAF> MODIFY SMITH /FILLM=50 UAF> EXIT After you exit from the utility, the system displays messages indicating whether or not changes were made. Once the changes have been made, you must log out and log in again for the new quotas to take effect. For more information on modifying account quotas, see the description of the Authorize Utility in the OpenVMS System Management Subkit. Preparing for DEC Ada Installation 1-7 1.4.4 VMSINSTAL Requirements When you invoke VMSINSTAL, it checks the following: o Whether you are logged in to a privileged account o Whether any users are logged in to the system o Whether you have adequate quotas for installation If problems are detected during installation, in some instances you can enter YES to continue. If you do not wish to continue, enter NO or press Return to stop the installation process. Then correct the problem and restart the installation. 1.4.5 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 any software. Use the backup procedures established at your site. For details on performing a system disk backup, see the section on the OpenVMS Backup Utility in the OpenVMS System Management Subkit. 1-8 Preparing for DEC Ada Installation 2 ________________________________________________________________ Installing DEC Ada This chapter explains how to install DEC Ada on OpenVMS Alpha systems. Section 2.1 contains a step-by-step description of the installation procedure. ________________________Note ________________________ Previous versions of DEC Ada contained four savesets. DEC Ada Version 3.2 (ADA032) contains three savesets (A, B, and C). _____________________________________________________ 2.1 The Installation Procedure The DEC Ada installation procedure consists of a series of questions and informational messages. See Appendix A for the output from a sample installation. If it is not already inserted, place the compact disk (CD) media into the CD 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 is often listed in brackets ([]). Installing DEC Ada 2-1 2.1.1 Invoke VMSINSTAL To start the installation, invoke the VMSINSTAL command procedure from a privileged account, such as the SYSTEM account. The command format is as follows: @SYS$UPDATE:VMSINSTAL saveset-name device-name OPTIONS N VMSINSTAL is in the SYS$UPDATE directory. To install DEC Ada, enter the following command: $ SYS$UPDATE:VMSINSTAL ADA03n DKA100: OPTIONS N 2-2 Installing DEC Ada The following defines the elements of the VMSINSTAL command procedure: saveset-name The installation name for the component. For DEC Ada, use the installation name ADA03n. n The letter n represents the maintenance update of DEC Ada. See the label on the DEC Ada distribution kit or the bill of materials for the maintenance update number of your kit. For DEC Ada Version 3.2, the maintenance update is 2. device-name The name of the device on which you plan to mount the media. OPTIONS N An optional parameter that indicates that you want to be asked to choose one of the four options for reviewing the release notes. (See Section 2.1.4). 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. You can select several other options when you invoke the VMSINSTAL command procedure: o Auto_answer option (A): Initially creates a file that contains your answers to VMSINSTALL 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 Get save set option (G): Lets you store product save sets temporarily on a magnetic tape or in a disk directory. o File log option (L): Logs all activity to the terminal during installation. Installing DEC Ada 2-3 See the OpenVMS documentation on software installation in the OpenVMS System Management Subkit for detailed information on these options. If you specify more than one option, separate the options with commas (OPTIONS A,N). The following example invokes VMSINSTAL to install DEC Ada from disk drive DKA100: and shows the system response. This example uses the OPTIONS N release note parameter. $ @SYS$UPDATE:VMSINSTAL ADA03n DKA100: OPTIONS N OpenVMS AXP Software Product Installation Procedure Vm.n It is dd-mmm-yyyy at hh:mm. Enter a question mark (?) at any time for help. If you do not supply either the product name or the device name, VMSINSTAL prompts you for options. 2.1.2 Confirm System Backup VMSINSTAL asks if you are satisfied with your system backup. * Are you satisfied with the backup of your system disk [YES]? You should always back up your system disk before performing an installation. If you are satisfied with the backup of your system disk, press Return. Otherwise, enter NO to discontinue the installation. After you back up your system disk, you can restart the installation. 2.1.3 Mount the Media If you omitted the device name on the VMSINSTALL command line, the following prompt appears: * Where will the distribution volumes be mounted: If this prompt appears, enter the name of the distribution (media) device and directory that contains the DEC Ada kit (save set). For example, if the media is contained on a CD located on unit DKA100:, enter DKA100:[ADA03n] in reply to this question (where n is the minor version number). 2-4 Installing DEC Ada 2.1.4 Select a Release Notes Option 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. 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 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. If you select option 2, VMSINSTAL prompts you for the name of the print queue that you want to use to print the release notes: * Queue name [SYS$PRINT]: You can press Return to send the file to the default output print device or you can enter another queue name. 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. Select option 4 if you have already reviewed the release notes and are continuing the installation. Next VMSINSTAL displays the following question: * Do you want to continue the installation [N]?: 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 if you want to stop the installation to read the release notes. In either case, the release notes are copied to a file in the SYS$HELP directory: Installing DEC Ada 2-5 SYS$HELP:ADA03n.RELEASE_NOTES.* 2.1.5 Choose the Installation Verification Procedure Option The installation procedure now asks if you want to run the Installation Verification Procedure (IVP). * Do you want to run the IVP after the installation [YES]? The IVP for DEC Ada checks to be sure that the instal- lation is successful. It is recommended that you run the IVP. (For more information on IVP, see Section 3.1.) After installing DEC Ada, you can run the IVP indepen- dently 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 Ada. 2.1.6 Select Installation Options DEC Ada provides support for the DEC Source Code Analyzer (SCA). SCA is an optional, interactive, multilanguage, source code cross-reference and static analysis tool. The information in the SCA library for the predefined units allows you to query SCA about symbols, declarations, and subprograms contained in the predefined units. If you have SCA installed on your system and intend to use it to analyze DEC Ada programs, type YES in response to the prompt. If you are not going to use SCA or you are concerned about saving disk space, type NO in response to the prompt. * Do you want to include SCA analysis data file for the predefined units [YES]? If you need to know how much disk space this library will take before you can answer the prompt, type a question mark (?) to obtain specific information on disk space requirements before typing YES or NO. If you typed YES or pressed Return, an SCA analysis data file for the DEC Ada predefined units (ADA$SCA_PREDEFINED.ANA) is copied to the SYS$LIBRARY directory during installa- tion. To make this information available, you must create an SCA library and load the data from the file into the library. 2-6 Installing DEC Ada If the current version of DEC Ada on your system is different from the version you are installing, the installation procedure allows you to save the currently existing version. If you want to save the currently existing compiler, answer YES. If not, answer NO to the prompt. * Do you want to save the currently existing compiler [YES]? If you need to know exactly which files are saved, then type a question mark (?) to obtain specific information before typing YES or NO. 2.1.7 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 messages are displayed: There will be no further questions. %VMSINSTAL-I-RESTORE, Restoring product save set B ... After the installation is complete, you need to add the following command to the site-specific system startup command file, SYS$MANAGER:SYSTARTUP_VMS.COM: $ @SYS$STARTUP:ADA$STARTUP %VMSINSTAL-I-RESTORE, Restoring product save set C ... The success of the installation is indicated by the following message: %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... If the installation procedure is successful, the procedure moves the files created to their target directories. Installing DEC Ada 2-7 At this point, an informational message notifies you when the new files are moved to their target directories. If you are installing DEC Ada on a system that has close to the minimum amount of free disk space, the created files are moved to their target directories as they are processed, and no message is issued when the files are moved. For information on the files that the installation procedure creates or modifies, see Appendix B. 2.1.8 Observe the Installation Verification Procedure If you chose to run the IVP, VMSINSTAL runs it at this point. When the IVP runs successfully, you see the following display: Beginning the (DEC Ada) installation verification procedure. %ACS-I-CL_LIBCRE, Library CDD$DJA0:[SYS0.SYSUPD.ADA032.ADALIB] created %ACS-I-CL_LIBIS, Current program library is CDD$DJA0:[SYS0.SYSUPD.ADA032.ADALIB] DEC Ada 3.n installation verification test Testing, testing, 1, 2, 3, 4 Testing, testing DEC Ada 3.n installation verification PASSED After the IVP has completed successfully, the temporary program library and any files generated during the IVP are deleted. 2.1.9 End the Installation Procedure The following messages indicate that the entire installa- tion procedure is complete. Installation of DEC Ada 3.n completed at hh:mm VMSINSTAL procedure done at hh:mm You can now log out of the privileged account: $ LOGOUT SYSTEM logged out at dd-mmm-yyyy hh:mm:ss.ss 2-8 Installing DEC Ada When the product installation procedure is complete, you can choose to install more products or to log out (as shown here.) If you removed any media from the console drive before beginning the installation, you should replace it now. VMSINSTAL deletes or changes entries in the process symbol tables during the installation. 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 Ada 3.n has failed. If the IVP fails, you see the following messages: The DEC Ada 3.n Installation Verification Procedure failed. %VMSINSTAL-E-IVPFAIL, The IVP for DEC Ada 3.n has failed. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o A prerequisite software 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. 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 Installing DEC Ada 2-9 action as described in the message. For information on installation requirements, see Chapter 1. 2.3 Keeping the Currently Existing Compiler Available The installation procedure installs the compiler and program library manager on the kit as the default compiler and program library manager. When you enter an ADA or ACS command, the newly installed compiler and program library manager are invoked. The DEC Ada kit is designed to let you have continued access to your previously existing compiler while you are using the newly installed compiler. During the installation, you are asked if you want to save the currently existing compiler. If you answer YES and the version of the currently existing compiler is not the same as the version of the compiler that you are installing, the installation procedure creates a subdirectory of SYS$SYSTEM. The subdirectory is named ADA$ident_string.DIR, where ident_string is the identifying string of the currently existing compiler. The installation procedure then copies the currently existing versions of the following files to that subdirectory: o Compiler (ADA.EXE) o Program library manager (ACS.EXE) o Command definition file (ADACLD.CLD) o Run-time library (ADARTL.EXE) o Message file (ADAMSG.EXE) o Library of predefined units (ADALIB.DIR) In addition, the installation procedure places the following command procedures in SYS$SYSTEM: o ADA$USE_ident_string.COM o ADA$USE_INSTALLED.COM When invoked, ADA$USE_ident_string.COM defines the appropriate logical names needed to access the previously existing compiler. ADA$USE_INSTALLED.COM defines the appropriate logical names to access the installed compiler. 2-10 Installing DEC Ada For example if you install Version 3.2 as the default compiler and you want to access the Version 3.0 compiler, you enter the following command: $ @SYS$SYSTEM:ADA$USE_V3_0.COM Subsequently, when you enter an ADA or ACS command, the Version 3.0 compiler or program library manager is invoked. If you want the old version of the DEC Ada compiler to be the default, modify SYS$STARTUP:ADA$STARTUP.COM by replacing the current logical definitions with the ones from SYS$SYSTEM:ADA$USE_ident_string.COM, where the ident_ string represents the old version of the compiler. Use the /SYSTEM and /EXECUTIVE qualifiers in the logical name definitions. When you are using a version of the program library manager (ACS.EXE) that is not the default version and an ACS command creates a command procedure to perform an operation, unexpected results from using a different version of DEC Ada may occur in the following cases: o If the command procedure is submitted to a batch queue by a /SUBMIT qualifier on the ACS command o If you later submit the command procedure to a batch queue using the DCL SUBMIT command Because the program library manager does not transmit knowledge about the current version of the compiler when the command procedure is created, the submitted command procedure (by default) uses the default version of the compiler. For example, if you invoke @SYS$SYSTEM:ADA$USE_ INSTALLED.COM and then use an ACS command that creates a command procedure for batch submission, the Version 3.2 compiler will be used during the execution of the command procedure. To override this behavior, you can modify your LOGIN.COM file so that it invokes the command procedure that redefines the desired compiler and environment. Installing DEC Ada 2-11 If you expect to switch frequently between compilers, you may want to modify SYS$STARTUP:ADA$STARTUP.COM or SYS$STARTUP:SYLOGIN.COM to define global OpenVMS symbols to represent the invocations of the command procedure. For example: $ V30 == "@SYS$SYSTEM:ADA$USE_V3_0.COM" $ V32 == "@SYS$SYSTEM:ADA$USE_INSTALLED.COM" Program libraries generated or modified by a Version 3.2 compiler are not accepted by older compilers. During the installation, the system command table (SYS$LIBRARY:DCLTABLES.EXE) is updated to include the new command files associated with the version being installed. Because the changes in the command files are upward compatible, Version 3.n commands are accepted by a [Version 2.n] compiler and program library manager. If you use a new Version 3.n qualifier or option with a Version 2.n compiler, the qualifier or option is ignored. If this behavior is not acceptable, you can make use of the fact that the command definition file (ADACLD.CLD) associated with the saved compiler is also in the subdirectory that holds the saved compiler. You can use the DCL SET COMMAND command to modify your process's command tables so that the saved compiler's command file is used. For example, if the system command table contains the command definition associated with Version 3.2 but you have redefined your environment so that the Version 3.0 compiler is being used, you can enter the following command to use the Version 3.0 compiler command definition: $ SET COMMAND SYS$COMMON:[SYSEXE.ADA$V3_0]ADACLD.CLD This technique works only as long as you remain in the current process context. When a spawned subprocess is created (for example, you enter a DCL SPAWN, LSEDIT COMPILE command or you enter an ACS COMPILE, ACS COMPILE /WAIT, ACS RECOMPILE, ACS RECOMPILE/WAIT, ACS LOAD, or ACS LOAD/WAIT command) the process's current command tables are not copied from the parent process. Instead, the system command table that contains the installed version's command files is used. 2-12 Installing DEC Ada To reinstall an older version of the compiler, you should perform the installation using the original kit and VMSINSTAL, even if the older version of the compiler has been saved in a subdirectory. Unexpected problems may occur if the files saved in the subdirectory are copied or renamed to the appropriate places. 2.3.1 Saving the Currently Existing HELP File If you chose to keep the currently existing compiler available (in Section 2.1.6), you may also want to save the currently existing HELP file. The DEC Ada installation procedure does not automatically save the currently existing HELP file. To save the currently existing HELP file, you need to extract the file from the system HELP library (SYS$LIBRARY:HELPLIB.HLB) and insert it into a newly created user HELP library before installing the new HELP file. For example: $ LIBRARY/EXTRACT/ADA/OUTPUT=USER:[SMITH]V3_nADAHELP.HLP - _$ SYS$HELP:HELPLIB.HLB $ LIBRARY/CREATE/HELP USER:[SMITH]V3_nADAHELP.HLB - _$ USER:[SMITH]V3_nADAHELP.HLP Once you have saved the existing HELP file, you can access it by using the /LIBRARY qualifier with the HELP command and specifying the user HELP library instead of the default system library. For example: $ HELP/LIBRARY=USER:[SMITH]V3_nADAHELP.HLB 2.4 Installing DEC Ada on a VMScluster If you want to run DEC Ada on multiple nodes of a VMScluster, first check to see that you have the appropriate software license. Then follow these steps after installing DEC Ada: 1. Enter the LICENSE LOAD command to activate the license on each node in the VMScluster on which DEC Ada is to be executed as described in the OpenVMS License Management Utility Manual. Installing DEC Ada 2-13 2. If the other nodes share a common system disk with the installation node, install DEC Ada on the other nodes by running the command procedure SYS$STARTUP:ADA$STARTUP.COM on each node of the cluster that has a software license. You must also update the SYS$LIBRARY:DCLTABLES.EXE file on each of the other nodes by executing the following commands on each node: $ INSTALL INSTALL> REPLACE SYS$LIBRARY:DCLTABLES.EXE These commands modify the DCL command tables on the other nodes so that the ADA and ACS commands are recognized and processed. 3. If the other nodes do not share a common system disk with the installation node, you must run a separate installation on each node. 2.5 Postinstallation Notes DEC Ada is now installed, and the DEC Ada compiler can be invoked by all users with the ADA command. The DEC Ada program library manager can be invoked with ACS commands. The installation procedure modifies the DCL command table so that the ADA and ACS commands are recognized and processed. However, the previous command table is still in effect for those users who are currently logged in. Users who want to use the ADA or ACS commands must log out of the system and log in again. Be sure to add the following command to the SYS$MANAGER:SYSTARTUP_ VMS.COM file, as requested in Section 2.1.7: @SYS$STARTUP:ADA$STARTUP To ensure device independence when backing up and restoring DEC Ada program libraries, verify that concealed-device logical names have been assigned to all public devices on your system. For information on concealed device logical names, see the OpenVMS DCL Dictionary and the Guide to OpenVMS File Applications. 2-14 Installing DEC Ada For information on using concealed device logical names with DEC Ada program libraries, see Developing Ada Programs on OpenVMS Systems. Installing DEC Ada 2-15 3 ________________________________________________________________ After Installing DEC Ada This chapter discusses the following tasks, which can take place after installing DEC Ada: o Running the Installation Verification Procedure separately o Error Conditions o Maintenance Updates o Determining and Reporting problems 3.1 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 should system problems occur, execute the following command procedure: $ @SYS$TEST:ADA$IVP.COM 3.2 Error Conditions If the DEC Ada installation procedure or DEC Ada IVP fails for any reason when you are running VMSINSTAL, the following message is displayed: %VMSINSTAL-E-INSFAIL, The installation of DEC Ada V3.2 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 Section 1.4.2). After Installing DEC Ada 3-1 o Process quotas required by VMSINSTAL are incorrect (see Section 1.4.3). o The OpenVMS 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 OpenVMS System Messages and Recovery Procedures Reference Manual, your processor-specific installation guide, or the OpenVMS 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 instal- lation procedure from the beginning. If the installation fails due to an IVP failure and the product's License PAK has been registered and loaded, contact your Digital representative. 3.3 Maintenance Updates Digital may periodically issue maintenance updates of DEC Ada. 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 3.0, the version number of the first maintenance update may be 3.1. Each maintenance update also includes new release notes. The release notes describe the changes that have been made to DEC Ada since the previous release. The update release notes are provided on line. You should read the release notes when you first install DEC Ada. They are also accessible at any time after the product is installed. 3-2 After Installing DEC Ada For information on reading the release notes at the time that you install DEC Ada, follow the installation procedure through step 6. To locate the release notes after DEC Ada is installed, display or print the file SYS$HELP:ADA03n.RELEASE_NOTES (where n is the number of the current maintenance update). 3.4 Determining and Reporting Problems If you encounter a problem while using DEC Ada, report it to Digital. Depending on the nature of the problem and the type of support you have, you can take one of the following actions: o Call Digital if your software contract or warranty agreement entitles you to telephone support. o Submit a Software Performance Report (SPR). o Fill out and submit a Reader's Comments form if the problem has to do with the DEC Ada documentation. There are Reader's Comments forms at the back of each manual. Use the form from the manual in which you found the error. Include the section and page number. Review the Software Product Description (SPD) and Warranty Addendum for an explanation of warranty. If you encounter a problem during the warranty period, report the problem as indicated above or follow alternate instructions provided by Digital for reporting SPD nonconformance problems. When you prepare to submit an SPR, please take the following steps: 1. Describe as accurately as possible the state of the system and the circumstance when the problem occurred. Include in the description the version number of DEC Ada being used. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 3. Remember to include listings of any command files, relevant data files, and so on. 4. Provide a listing of the program. After Installing DEC Ada 3-3 5. 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. Use the OpenVMS Backup Utility to copy the program library to the machine-readable media. 6. Report only one problem per SPR. This facilitates a more rapid response. 7. Mail the SPR package to Digital. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Complete and concise information helps Digital give accurate and timely service to software problems. 3-4 After Installing DEC Ada A ________________________________________________________________ Sample Installation This appendix contains a sample installation of DEC Ada on an OpenVMS Alpha system. This sample was run on a system that had no previous version of DEC Ada installed. Depending on which layered products you have on your system, you might see additional messages and questions when you perform your installation. The sample installation assumes that DECnet has been shut down, that no users are logged in to your system, and that OPTIONS N is specified to print the release notes. The Installation Verification Procedure (IVP) runs at the end of the installation. 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 DEC Ada Version 3.2 on OpenVMS Alpha Systems letter before you install this product. This letter notes any significant changes in the installation that vary from this sample. $ @SYS$UPDATE:VMSINSTAL ADA032 DKA100: OPTIONS N OpenVMS AXP Software Product Installation Procedure Vm.n It is 18-NOV-1994 at 10:05. Enter a question mark (?) at any time for help. * Do you want to continue anyway [NO]? YES * Are you satisfied with the backup of your system disk [YES]? YES The following products will be processed: ADA V3.2 Beginning installation of ADA V3.2 at 10:10 Sample Installation A-1 %VMSINSTAL-I-RESTORE, Restoring product save set A ... 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]: 2 * Do you want to continue the installation [NO]? YES %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. * Do you want to run the IVP after the installation [YES]? YES * Do you want to include SCA analysis data for the predefined units [YES]? YES * Do you want to save the currently existing compiler [YES]? NO There will be no further questions. %VMSINSTAL-I-RESTORE, Restoring product save set B ... After the installation is complete, you need to add the following command to the site-specific system startup command file, SYS$MANAGER:SYSTARTUP_VMS.COM: $ @SYS$STARTUP:ADA$STARTUP %VMSINSTAL-I-RESTORE, Restoring product save set C ... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Beginning the DEC Ada installation verification procedure. © Digital Equipment Corporation 1992, 1994. All rights reserved. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt. III, as applicable. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Please note that this installation verification procedure requires that a valid license for DEC Ada has been installed on your system. A-2 Sample Installation %ACS-I-CL_LIBCRE, Library G$DKB100:[SYS0.SYSUPD.ADA032.ADALIB] created %ACS-I-CL_LIBIS, Current program library is G$DKB100:[SYS0.SYSUPD.ADA032.ADALIB] DEC Ada V3.2 installation verification test Testing, testing, 1, 2, 3, 4 Testing, testing DEC Ada V3.2 installation verification PASSED %ACS-I-CL_LIBDEL, Library G$DKB100:[SYS0.SYSUPD.ADA032.ADALIB] deleted Installation of ADA V3.2 completed at 10:19 Creating installation data file: VMI$ROOT:[SYSUPD]ADA032.VMI_DATA VMSINSTAL procedure done at 10:19 Sample Installation A-3 B ________________________________________________________________ Files and Logical Names Installed on Your System The DEC Ada on OpenVMS Alpha systems installation procedure installs a number of files on your system and defines some logical names. Section B.1 lists the files installed. Section B.2 lists the logical names that are added to the system logical name table. B.1 File Names The installation procedure creates or modifies the following files. However, they do not appear in the installation messages. SYS$SYSTEM:ADA.EXE (new) SYS$SYSTEM:ACS.EXE (new) SYS$STARTUP:ADA$STARTUP.COM (new) SYS$LIBRARY:DCLTABLES.EXE (modified) SYS$SHARE:ADACLD.CLD (new) SYS$COMMON:[SYSLIB.ADALIB] and contents (new) SYS$COMMON:[SYSLIB]ADA$SCA_PREDEFINED.ANA (new) SYS$COMMON:[SYSHLP.EXAMPLES.ADA] and contents (new) SYS$HELP:ADA03n.RELEASE_NOTES.PS (new) SYS$HELP:ADA03n.RELEASE_NOTES.TXT (new) SYS$TEST:ADA$IVP.COM (new) If you saved the currently existing compiler in Section 2.1.6, the installation procedure also creates the following files: Files and Logical Names Installed on Your System B-1 SYS$COMMON:[SYSEXE.ADA$ident_string] and contents (new) SYS$SYSTEM:ADA$USE_ident_string.COM (new) SYS$SYSTEM:ADA$USE_INSTALLED.COM (new) ident_string represents the version number of the currently installed DEC Ada compiler. B.2 Logical Names Table B-1 lists the logical names that are entered into the system logical name table when you install DEC Ada. These names are stored in the product's startup file. They are automatically entered into the system logical name table whenever the system reboots or whenever the software is invoked. Table_B-1_DEC_Ada_Logical_Names_and_Locations_____________ Logical_Name_______________Location_______________________ ADA$EXAMPLES SYS$COMMON:[SYSHLP.EXAMPLES.ADA] ADA$PREDEFINED ADA$PREDEFINED_ROOT:[ADALIB] ADA$PREDEFINED_ROOT Defined as a concealed device logical name that is equivalent to SYS$COMMON:[SYSLIB]. __________________________________________________________ B-2 Files and Logical Names Installed on Your System C ________________________________________________________________ Tuning OpenVMS Alpha Systems When configuring a system to handle DEC Ada compilations, you need to consider all of the activities that you wish to perform. For example, you need to consider the amount of parallel compilation that the system can support as well as considering the amount of memory you need. In general, a process used for compiling DEC Ada programs should have a WSEXTENT quota of at least 20,000. If you are performing compilations interactively, this quota should be specified as a SYSUAF quota. For compilations done in a batch queue, it is possible for the system manager to set the WSEXTENT attribute for the batch queue. In that case, the system should be configured with enough memory to let the maximum desired number of concurrent compilations reach their maximum working set simultaneously. Otherwise, the system may start paging or swapping excessively. C.1 Improving Product Performance This section gives detailed information on how to improve the performance of the DEC Ada compiler and program library manager. Every effort was made to provide the appropriate parameters for tuning your system. However, you may gain better performance by adjusting some of the parameters upwards or downwards to suit your particular system configuration. System Generation Utility (SYSGEN) and User Authorization File (UAF) parameters are described, and suggested minimum values are noted. The parameters discussed are those for which DEC Ada requires larger values than the OpenVMS defaults or for which the values are larger than those required for other OpenVMS programming languages. Tuning OpenVMS Alpha Systems C-1 The OpenVMS operating system controls resource usage through two primary sets of parameters: systemwide parameters and per-process parameters. You can use the SYSGEN utility to define and modify systemwide parameters (SYSGEN parameters). Per-process parameters are controlled on a per-user-name basis by quotas and defaults that are contained in the User Authorization File (UAF parameters). You use the Authorize Utility to modify UAF entries. A complete description of OpenVMS resources, SYSGEN, and UAF parameters is contained in the OpenVMS System Manager's Manual. You should be familiar with the proce- dures described there for modifying SYSGEN parameters. The recommended procedure is to add site-specific parameters to the file SYS$SYSTEM:MODPARAMS.DAT and then invoke the SYS$UPDATE:AUTOGEN command procedure. The AUTOGEN command procedure computes the optimal value for all parameters. See the OpenVMS System Manager's Manual for information on how to use AUTOGEN and how to specify parameter values before invoking AUTOGEN. Digital recommends that you run AUTOGEN with feedback about one week after installing DEC Ada or after the DEC Ada load changes significantly. Whenever possible, modify the MODPARAMS.DAT file to include MIN_parameter or ADD_ parameter instead of hard-coding values into this file. C.1.1 ASTLM The UAF AST queue limit (ASTLM) parameter limits the sum of the following: o The number of asynchronous system trap (AST) requests that a user's process can have outstanding at one time o The number of scheduled wakeup requests that a user's process can have outstanding at one time The DEC Ada delay statement is implemented as a call to the OpenVMS SYS$SETIMR system service, which executes an AST routine. DEC Ada also provides facilities for calling OpenVMS system routines that execute AST routines. For example, the package STARLET provides the system services SYS$QIO and SYS$QIOW both of which let you specify an AST service routine. The routines in the package TASKING_ C-2 Tuning OpenVMS Alpha Systems SERVICES execute ASTs as well (although the execution and handling of the ASTs is hidden by the package). The suggested OpenVMS value for ASTLM is 24. This should be sufficient for most DEC Ada programs. If your programs involve tasks that could execute many delay statements simultaneously or if you use a high number of calls to OpenVMS system routines that execute AST routines, you may want to increase this value. See the DEC Ada Run-Time Reference Manual for OpenVMS Systems for more information on ASTs in DEC Ada programs, especially programs that use tasks. C.1.2 ENQLM The UAF enqueue quota (ENQLM) parameter limits the number of locks that a process and its subprocesses can own. Record Management Services (RMS) uses locks to synchronize access to shared files and records. The DEC Ada compiler and program library manager use RMS to access the DEC Ada program library index file, ADALIB.ALB. Up to eight locks can be used for each library or sublibrary that is open. When a sublibrary is opened, usually its parent and its ancestors are also opened. If you are using a sublibrary that has a parent and a grandparent, up to 24 (3 * 8) locks may be needed. Commands such as ACS COPY UNIT can have two libraries or sublibraries open at the same time, which doubles the number of locks. Since the ENQLM parameter is inexpensive to use, setting this parameter on the high side is preferable to setting it too low. A suggested value for the ENQLM parameter is 300. C.1.3 FILLM The UAF open file limit (FILLM) parameter limits the number of files that a user's process can have open at one time. This limit includes the number of network logical links that can be active at the same time. Tuning OpenVMS Alpha Systems C-3 The DEC Ada compiler and program library manager, and the OpenVMS Linker use the value of FILLM to limit the total number of files open at one time. If a compilation involves a large number of units and FILLM is set too low to allow all the files involved to be opened at the same time, the compilation can take a long time. For example, if a unit depends directly or indirectly on 99 additional units and if FILLM is set to 20, the compilation is slower than if FILLM had been set to 100. FILLM is a pooled limit with a suggested value of 20. This value is not sufficient for most DEC Ada compilations. The recommended minimum value for DEC Ada users is 50. The value of FILLM must always be lower than the value of the SYSGEN channel count (CHANNELCNT) parameter. If you increase the value of the FILLM parameter, you may also want to increase the value of the UAF BYTLM parameter. The general rule for the relationship between these two parameters is that the value of BYTLM should be at least 100 times the value of FILLM. C.1.4 PRCLM The UAF subprocess creation limit (PRCLM) parameter limits the number of subprocesses that a user's process can create. The DEC Ada program library manager creates a subprocess to run the linker or the DEC Ada compiler for the ACS LINK/WAIT, COMPILE/WAIT, LOAD/WAIT, and RECOMPILE/WAIT commands. Only one subprocess is created, and the creating process waits for the termination of the subprocess. In general, the default value for PRCLM set by AUTOGEN is adequate for most DEC Ada programs. C.1.5 TQELM The UAF timer queue entry limit (TQELM) parameter limits the sum of the following: o The number of entries that a user's process can have in the timer queue o The number of temporary common flag clusters that a user's process can have C-4 Tuning OpenVMS Alpha Systems The DEC Ada delay statement is implemented as a call to the OpenVMS SYS$SETIMR system service, which adds an entry to the timer queue. The suggested OpenVMS value for TQELM is 20. This value should be sufficient for most Ada programs. If your programs involve tasks that could execute many delay statements simultaneously, you may want to increase this value. See the DEC Ada Run-Time Reference Manual for OpenVMS Systems for more information on the interaction of the TQELM parameter with DEC Ada tasking programs. C.1.6 Virtual Memory Usage Various SYSGEN and user parameters should be set so that a DEC Ada compilation can use up to 20,000 pagelets (10 megabytes) of virtual memory. The following sections describe working set parameters that should be adjusted to provide good performance for such large virtual address spaces. o VIRTUALPAGECNT The SYSGEN VIRTUALPAGECNT parameter sets the maximum number of virtual pagelets that can be mapped for any one process. The OpenVMS default (65,536 pagelets, or 32 megabytes) should be adequate for compilations of most DEC Ada programs. Tuning OpenVMS Alpha Systems C-5 o PGFLQUOTA The UAF paging file quota (PGFLQUOTA) parameter limits the number of pagelets that your process can use in the system paging file. It limits the amount of read /write working storage that the compiler can use. PGFLQUOTA should be set to a value consistent with VIRTUALPAGECNT. The suggested OpenVMS value of 50,000 for PGFLQUOTA is recommended. You should also make sure that the system page file is large enough to accommodate processes with large page file quotas. In general, you can use AUTOGEN to establish the correct size for the system page file. o System Paging File The system paging file (SYS$SYSTEM:PAGEFILE.SYS) determines the amount of paging space available for system processes and RMS global buffers. The paging file size should be greater than the maximum paging file quota (UAF PGFLQUOTA parameter) for an individual. It should also be greater than the virtual page count (SYSGEN VIRTUALPAGECNT parameter). For example, if the value of VIRTUALPAGECNT is 20,000 pagelets, then a paging file of at least 30,000 blocks is needed. If the paging file size is not properly adjusted with respect to these two parameters, system processing could appear to be suspended, and the following messages is displayed: %SYSTEM-W-PAGEFRAG, Page file badly fragmented, system continuing %SYSTEM-W-PAGECRIT, Page file space critical, system trying to continue It is recommended that you use the Digital-supplied AUTOGEN command procedure to suggest the size of the system paging file after adjusting the values of VIRTUALPAGECNT and PGFLQUOTA. See the OpenVMS System Manager's Manual for information on how to use AUTOGEN and how to specify parameter values before invoking AUTOGEN. C-6 Tuning OpenVMS Alpha Systems See the OpenVMS System Manager's Manual for information on the OpenVMS default value of PGFLQUOTA. See the VMS System Generation Utility Manual for more information on the OpenVMS default value of VIRTUALPAGECNT. o WSQUOTA and WSEXTENT The UAF working set quota (WSQUOTA) parameter specifies the maximum size to which a user's physical memory size can grow on a typically loaded system. The system guarantees the user that WSQUOTA physical pagelets are available to the user's process. The UAF working set extent (WSEXTENT) parameter specifies the maximum size to which a user's physical memory can grow, independent of system load. WSEXTENT should be greater than or equal to WSQUOTA. If WSEXTENT is greater than WSQUOTA, the OpenVMS operating system attempts to provide additional physical pagelets to a process that is page-faulting heavily. On a lightly loaded system, the user's working set can grow beyond WSQUOTA up to WSEXTENT. A DEC Ada compilation should have a working set of 2500 pagelets or more. If a user is going to do DEC Ada compilations interactively or in a subprocess (COMPILE/WAIT), the user's UAF entry should specify WSQUOTA=2500. Many sites may not permit large working sets for interactive jobs. In this case, a batch queue should be established for DEC Ada compilations. The DEC Ada batch queue can define values for WSQUOTA and WSEXTENT that override the UAF values. Compilations done in the batch queue can have much larger working sets, resulting in better compile times and better use of system resources. Tuning OpenVMS Alpha Systems C-7 C.1.7 Batch Queue Parameters A batch queue with large working set parameters should be provided for DEC Ada compilations. This batch queue minimizes the number of concurrent DEC Ada compilations so that each compilation completes efficiently without inducing excessive system overhead. You should define the logical name ADA$BATCH in the system logical name table. The DEC Ada program library manager submits ACS COMPILE and RECOMPILE commands to the queue named by ADA$BATCH. If ADA$BATCH is not defined, these jobs are submitted to SYS$BATCH. A typical DEC Ada batch queue that is designed to handle two concurrent compilations should be initialized with the following values: $INITIALIZE/QUEUE/BATCH- /BASE_PRIORITY=4/JOB_LIMIT=2- /WSQUOTA=2500/WSEXTENT=40000 ADA_BATCH $ ASSIGN/SYSTEM ADA_BATCH ADA$BATCH C.1.8 WSMAX The SYSGEN working set maximum number of pagelets (WSMAX) parameter sets the maximum number of pagelets for any working set on a system-wide basis. The value of WSMAX should be as great as the maximum WSEXTENT value assigned to any user or batch queue. The OpenVMS default WSMAX of 12,288 pagelets is too low for DEC Ada. A value of at least 20,000 is recommended. Consequently, you want to add the following line to your MODPARAMS.DAT file: MIN_WSMAX = 20000 C-8 Tuning OpenVMS Alpha Systems C.1.9 Channel Count Parameters The SYSGEN channel count (CHANNELCNT) parameter specifies the maximum number of channels for each process in an OpenVMS system. The UAF file and logical link limit (FILLM) parameter specifies the maximum number of files that can be open at one time, including active network logical links. The DEC Ada compiler and program library manager, and the OpenVMS Linker use the value of FILLM to limit the total number of open files at one time. They close files as necessary to avoid exceeding that value. The compiler and program library manager assume that the value of FILLM (which has a default value of 20) is less than the value of CHANNELCNT (which has a default value of 127). You may need to raise the value of FILLM to accommodate DEC Ada compilations that involve a large number of compilation units. You should be careful not to raise the value of FILLM above the value of CHANNELCNT. C.1.10 Program Library Networking Effects There are several SYSGEN and DECnet parameters (on both the local and remote nodes) that can affect the availability of compilation units or files accessed over DECnet. For example, every time a file is opened on a remote node, a temporary connection, called a logical link, is made from the local node to the remote node. The total number of logical links allowed at one time is controlled by DECnet and can be set by the Network Control Program (NCP) Utility with the following command: NCP> SET EXECUTOR MAX LINKS X The X in this command is the maximum number of logical links. This number represents the system (not process) quota. Each connection between two nodes deducts one from the quota total. When setting this value, note that both the DEC Ada compiler and program library manager use the per-process FILLM (file and logical link limit) quota, not the system quota, to limit the total number of open files at one time. Tuning OpenVMS Alpha Systems C-9 Limiting the total number of files open at one time also reduces the potential number of logical links created to the remote node. A logical link is only required for files that are not accessed locally. Since the creation of a logical link may also involve the creation of a process on the remote node, you may need to increase (or at least monitor) the values of the SYSGEN parameters MAXPROCESSCNT and BALSETCNT. This allows more processes to be created for libraries for network servers (FALs). If you are expecting to access a number of files or compilation units over DECnet, you may want to increase the value of the UAF buffered input-output byte count limit (BYTLM) parameter on your system. The value of this parameter affects the efficiency of program library operations performed over DECnet. Other parameters may also have an effect. DECnet parameters are documented in the DECnet for OpenVMS Guide to Networking. C.2 Relevant File Quotas and Cache Sizes The following sections describe how to estimate the sizes that the various OpenVMS caches should be set to. The relevant system manuals should be consulted to de- termine whether the resulting cache sizes are supportable (perhaps after installing more physical memory). The major classes of data that must be read from the disks are as follows: o The files themselves, especially the ADALIB.ALB and the .ACU files o The file headers from within INDEXF.SYS that describe where the files themselves reside o The directory files that describe where the file headers reside, given a file name C-10 Tuning OpenVMS Alpha Systems C.2.1 Caching Files Each time DEC Ada performs a compilation or ACS operation, the following disk files are cached into memory as needed: o DEC Ada compiler o DEC Ada program library manager o Contents of all necessary .ACU files For both small and large programs, caching can save time when performing compilations or ACS operations by avoiding unnecessary disk accesses. You can maximize the benefits of caching by: o Invoking the program library manager interactively. For example: $ ACS ACS> o Specifying more than one unit with the DCL ADA or ACS command, whenever possible. For example: ACS> COMPILE UNITA, UNITB, UNITC C.2.2 Caching File Headers The OpenVMS system uses file header caches to greatly reduce the time needed to open files. The size of the cache is controlled by the SYSGEN parameter ACP_HDRCACHE. OpenVMS sets a default value of 128 pages for ACP_HDRCACHE, but this value may be too small for the typical DEC Ada program running on your system. Because of the way the DCL ADA and ACS commands access files, it is important that the value of ACP_HDRCACHE is large enough to keep all the accessed file headers cached. If the cache is not large enough, the potential performance benefits of the cache are generally not realized. To estimate the value needed for ACP_HDRCACHE, you need to sum the total number of files that a typical DEC Ada program may require in order to compile, link, and run successfully. The following lists the files that you need when estimating a value for ACP_HDRCACHE: o Total number of .ACU files in your program library Tuning OpenVMS Alpha Systems C-11 o Total number of .OBJ files in your program library o Total number of .ADA source files in your program o Total number of .ALB files in your program library o Total number of directories that must be accessed, including any subdirectories that are accessed o Total number of system files that your program accesses o Total number of other files that your program accesses o Some for other users on the system You must include units from the predefined library in your estimates. You do not need to add the total number of .ADC files (copied source files) to your estimate because they are typically not accessed. Suppose the typical DEC Ada program on your system is as follows: o Contains 220 .ACU files, 220 .OBJ files, and 100 .ADA files (For this example, the predefined units are considered part of the 220 .ACU files.) o Located in two sublibraries and one parent library (making for a total of three .ALB files) o Accesses 5 directories o Accesses 15 system files o Accesses 8 other files The following example shows the calculation for the preceding program: 220 .ACU files 220 .OBJ files 100 .ADA files 3 .ALB files 5 Directories 15 System files + 8 Other files ----------------------- 571 Estimate for ACP_HDRCACHE C-12 Tuning OpenVMS Alpha Systems It is not unusual to have an estimated value for ACP_HDRCACHE that is over 500. One way to increase the value of ACP_HDRCACHE is to modify the MODPARAMS.DAT file and run AUTOGEN. For example, suppose you wanted to increase the value of ACP_HDRCACHE by more than the amount you estimated. To do this, enter the following line in the MODPARAMS.DAT file: ADD_ACP_HDRCACHE = 600 For the new value of ACP_HDRCACHE to take effect, you must run AUTOGEN. In addition if you run AUTOGEN with feedback, it increases the size of the file header cache in small increments if the header cache is too small. However, when the system load can be predicted, it is better to modify the MODPARAMS.DAT file than to use AUTOGEN with feedback. C.2.3 Caching Directory Files In general, the program library manager accesses directory files in a random order. Consequently, the ACP_DIRCACHE parameter should be set to the sum of the sizes of all the directories needed to be accessed when compiling and linking your programs. Unlike the ACP_HDRCACHE, this number gives steady improvement as it gets better, rather than a dramatic improvement as it crosses a threshold. C.3 Using DECRam on OpenVMS Systems Using pseudo-disks, such as DECRam, can be a very effective way of reducing disk traffic. For example, you can locate your current program library and any other frequently accessed libraries on the DECRam disk. You can also use a DECRam disk to place the copy (use ACS COPY) of a library so that you can access those files quickly. Once you create a copy of the units in the new library, any updates to the original library can cause the new library and the original library to be out of synchronization. If you do not have enough space on your DECRam disk for all the units in your DEC Ada program, consider placing only the specifications of the units on the DECRam disk. Tuning OpenVMS Alpha Systems C-13 Most of the units that are accessed during a compilation are specifications. C-14 Tuning OpenVMS Alpha Systems