Digital Extended Math Library for_OpenVMS_Alpha___________________________________ Installation Guide Part Number: AA-PS00F-TE April 1996 This document contains instructions for installing the Digital Extended Math Library on the OpenVMS operating system running on Alpha architectures. Revision/Update Information: This is a revised document. Operating System and Version: OpenVMS Alpha Version 6.2 Software Version: Digital Extended Math Library Version 2.9 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ First Printing, October 1992 Revised, April 1996 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 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. © Digital Equipment Corporation 1992, 1995, 1996. 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: AlphaGeneration, Bookreader, DEC, DECnet, OpenVMS, VAX DOCUMENT, and the DIGITAL logo. All other trademarks and registered trademarks are the property of their respective holders. This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. _________________________________________________________________ Contents Preface................................................... v 1 Preparing to Install DXML 1.1 Required Operating System Components.......... 1-1 1.2 Prerequisite Hardware......................... 1-1 1.3 Prerequisite Software......................... 1-2 1.4 License Registration.......................... 1-2 1.5 Installation Requirements..................... 1-3 1.5.1 Time...................................... 1-3 1.5.2 Privileges................................ 1-3 1.5.3 Disk Space................................ 1-4 1.5.4 System Parameters......................... 1-4 1.5.4.1 Checking System Parameter Values........ 1-4 1.5.4.2 Changing System Parameter Values with AUTOGEN................................. 1-6 1.5.4.3 Changing Dynamic System Parameter Values with SYSGEN............................. 1-7 1.5.5 Process Account Quotas.................... 1-8 1.5.6 VMSINSTAL Requirements.................... 1-8 1.6 Backing Up Your System Disk................... 1-10 2 Installing DXML 2.1 Installation Procedure........................ 2-1 2.2 Error Recovery................................ 2-8 iii 3 After Installing DXML 3.1 Defining the Link Library..................... 3-1 3.2 Installing DXML as a Known Image.............. 3-1 3.3 Starting DXML................................. 3-2 3.4 Global Resources for Known Images............. 3-5 3.4.1 Resources for Known /SHARED Images........ 3-5 3.4.2 Resources for Known /RESIDENT Images...... 3-5 3.5 Running DXML on a Cluster..................... 3-6 3.6 Running the IVP............................... 3-7 3.7 Reviewing Release Notes and Using Help........ 3-7 3.8 Reporting Problems............................ 3-7 A Sample Installation B Installed Files Index Tables 1-1 Required Disk Space ...................... 1-4 1-2 Suggested Values for System Parameters.... 1-4 1-3 Minimum Values for Dynamic Parameters..... 1-7 1-4 Process Account Quotas.................... 1-8 2-1 Error Messages for DXML................... 2-9 3-1 Required Global System Resources for Installed Images - IEEE Floating Format .......................................... 3-4 3-2 Required Global System Resources for Installed Images - G Floating Format ..... 3-4 B-1 Files Installed by the Development Kit.... B-1 B-2 Files Installed by the Run-Time Kit....... B-4 iv _________________________________________________________________ Preface This manual describes how to install the Digital Extended Math Library (DXML) on processors running the OpenVMS operating system on Alpha platforms. For information about the compatibility of other software products with this version of DXML, refer to the Software Product Description (SPD). You can use the SPD to verify which versions of your operating system are compatible with this version of DXML. Intended Audience This manual is intended for anyone who is responsible for any of the following tasks: o Planning the installation of DXML and preparing the system o Installing DXML o Starting DXML To install the software, you must: o Be familiar with VMSINSTAL, the command procedure used to install software products. To locate the description of VMSINSTAL, see the master index of the system documentation set. o Have access to the SYSTEM account on your machine or to an account with the user privilege SETPRV. This manual helps you understand the procedures necessary for installing DXML as a shareable library. Please read this manual before you begin the installation. v Structure of This Manual This manual includes three chapters and two appendixes: o Chapter 1 explains how to plan the installation and prepare your system for the installation. o Chapter 2 explains how to install the software. o Chapter 3 describes tasks you perform after installing DXML. o Appendix A presents the log of a sample installation of DXML. o Appendix B lists the files that make up the DXML product. Associated Documents Please read the release notes before installing the software, in case important information missing from this document has been added to the notes. Application developers should also check the release notes before using the product, in case corrections have been made to the documented performance of the product. The documentation for DXML also includes the Digital Extended Math Library for OpenVMS Alpha Reference Manual. For information on installing software, refer to the following manuals: o OpenVMS System Manager's Manual o Guide to Maintaining a VMS System o OpenVMS License Management Utility Conventions Used in This Manual This manual uses the following conventions: vi ___________________________________________________________ Convention____Meaning______________________________________ Ctrl/x The slash in the key name indicates that you press the two keys simultaneously. In this sequence, hold down the Ctrl key and then press the character key. . Vertical ellipses in an example indicate that . irrelevant information has been omitted. . $ The dollar sign is used to indicate the DCL prompt, which can differ on your system. bold type For online versions, user input is shown in bold. italic type Italic type emphasizes important information ______________and_indicates_complete_titles_of_manuals.____ Sending Digital Your Comments on This Product Digital welcomes your comments on this product and on its documentation. You can send comments to us in the following ways: o Internet electronic mail: dxml@hpc.pko.dec.com o FAX: 508-493-3628 ATTN: DXML Team o A Reader's Comment Form sent to the address on the form. A Reader's Comment Form appears on the next page. o A letter sent to the following address: Digital Equipment Corporation High Performance Computing Group 129 Parker Street PKO3-2/B10 Maynard, Massachusetts 01754-2195 USA Getting Help from Digital If you have a customer support contract and have comments or questions about DXML software, contact Digital's Customer Support Center (CSC), preferably using electronic means such as DSNlink. In the United States, customers can call the CSC at (800) 354-9000. vii Readers Comments Form Use the following form as a template for sending comments about DXML documentation. This form can be sent by Internet mail, FAX, or postal service. --------------------------------------------------------------------- Please complete this survey and send an online version (via Internet) or a hardcopy version (via FAX or postal service) to: Internet mail: dxml@hpc.pko.dec.com FAX: (508) 493-3628 Postal Service: Digital Equipment Corporation, High Performance Computing Group Documentation, PKO3-2/B10 129 Parker Street Maynard, Massachusetts 01754-2195 USA Manual Title: ______________________________________________________ Order Number: ______________________________________________________ Version: ________________________________________________ _____________________________________________________________________ _____________________________________________________________________ We welcome any comments on this manual. Your comments and suggestions help us improve the quality of our publications. 1. If you found any errors, please list them: Page Description ____ _______________________________________________________________ ____ _______________________________________________________________ ____ _______________________________________________________________ 2. How can we improve the content, usability, or otherwise improve our documentation set? _____________________________________________________________________ _____________________________________________________________________ _____________________________________________________________________ _____________________________________________________________________ Your Name/Title ____________________________________ Dept. ________ viii Company _____________________________________________ Date ________ Internet address or FAX number ______________________________________ Mailing address _____________________________________________________ ___________________________________________ Phone _________________ --------------------------------------------------------------------- ix 1 _________________________________________________________________ Preparing to Install DXML This chapter discusses the preparations and requirements for installing DXML software. Your DXML Version 2.9 kit is one of the following: o A development library that allows you to link an application program and then run the resulting executable image. It includes editor support and example source files. o A run-time library that allows you to run an executable image that has been linked to the DXML library on another system. 1.1 Required Operating System Components The OpenVMS operating system comes with a variety of support options, or tailoring classes. Classes include such features as networking and RMS journaling. To use DXML, your system must be running a version of OpenVMS that includes the following classes: o VMS Required Saveset o Programming Support o Utilities 1.2 Prerequisite Hardware For a complete list of supported processors, see the DXML Version 2.9 Software Product Description (SPD). Preparing to Install DXML 1-1 1.3 Prerequisite Software DXML requires Version 6.2 or higher of the OpenVMS Alpha operating system. To compile, link, and run a DXML application program written in a high-level language, you also need the programming language compiler. The SPD contains a complete list of prerequisite software and required version numbers. 1.4 License Registration Before you install and run DXML Version 2.9 on a newly licensed node, you must first register a License Product Authorization Key (License PAK) using the License Management Facility (LMF). The License PAK may be shipped along with the kit if you ordered the license and media together; otherwise, it is shipped separately to a location based on your license order. If your node has a License PAK installed for an earlier version of DXML, it is still valid. You must register and load your license for DXML before you start the installation procedure. Register your License PAK in one of the following ways: o If your license is in the form of a DCL command procedure, execute the procedure. o Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When the procedure prompts you for information, respond with data from your License PAK; otherwise, at the DCL prompt, enter the LICENSE REGISTER command with the qualifiers that correspond to your License PAK information. Load the PAK using the LICENSE LOAD command. If previous versions of the PAK have been loaded on the system, remove the current license from system memory using the following command: $ LICENSE UNLOAD lmf-name Then load the new license, using the following command: $ LICENSE LOAD lmf-name 1-2 Preparing to Install DXML where: o lmf-name = EXT-MATH-LIB for the Development Kit o lmf-name = EXT-MATH-LIB-RT for the Run-Time Kit ________________________ Note ________________________ To update the LICENSE database, you need to have SETPRV privileges. ______________________________________________________ 1.5 Installation Requirements This section describes the minimum requirements for installing DXML: time, privileges, disk storage space, system parameters, process account quotas, and VMSINSTAL requirements. 1.5.1 Time The installation takes about 6 minutes. 1.5.2 Privileges The account you use to install DXML must have the user privilege SETPRV. As one of the first actions, the VMSINSTAL command procedure grants all privileges (except BYPASS) to the process that invokes it. This command succeeds only if the account has SETPRV. The procedures described in this installation guide refer to the SYSTEM account, but they are the same for any account with SETPRV. Preparing to Install DXML 1-3 1.5.3 Disk Space Table 1-1 summarizes DXML's minimum requirements for free disk storage space. To display the number of free disk blocks on the current system disk, enter the following command at the DCL prompt: $ SHOW DEVICE SYS$SYSDEVICE Table_1-1_Required_Disk_Space______________________________ Blocks After Kit___________Blocks_During_Installation____Installation___ Development 50000 42000 Run-time______50000_________________________40000__________ 1.5.4 System Parameters The installation of DXML requires the default system parameter settings. After installation, and depending on whether known shared images are used, lower settings of these parameters are possible. Table 1-2 lists the suggested settings for the installation and execution of DXML. Table_1-2_Suggested_Values_for_System_Parameters___________ System_Parameter___________Minimum_Value___________________ CLISYMTBL 500 GBLPAGES 1000 GBLPAGFIL 64 GBLSECTIONS 50 LOCKIDTBL 1500 LOCKIDTBL_MAX 65535 RESHASHTBL 1064 VIRTUALPAGECNT_____________110000__________________________ 1.5.4.1 Checking System Parameter Values To check the values of your system parameters, enter the following command at the DCL prompt to invoke the System Generation Utility (SYSGEN): 1-4 Preparing to Install DXML $ RUN SYS$SYSTEM:SYSGEN SYSGEN> At the SYSGEN> prompt, enter the SHOW command to display the value of a system parameter. The values displayed should equal or exceed the value of each system parameter listed in Table 1-2. The following example displays the value for the VIRTUALPAGECNT system parameter: SYSGEN> SHOW VIRTUALPAGECNT After checking the parameters with the SHOW command, enter the EXIT command at the SYSGEN> prompt to return to DCL level. Preparing to Install DXML 1-5 1.5.4.2 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 Use an editor to access the file. 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: VIRTUALPAGECNT = 19000 To modify incremental parameters such as GBLPAGES and GBLSECTS, use ADD_. The following example increases the global pagelet setting by 2000: ADD_GBLPAGES = 2000 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 in to the system are immediately disconnected during the shutdown. The automatic reboot puts the new parameter values into effect. The AUTOGEN Utility 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. 1-6 Preparing to Install DXML 1.5.4.3 Changing Dynamic System Parameter Values with SYSGEN Use the System Generation Utility (SYSGEN) to set dynamic parameters. Dynamic parameters changed with the SYSGEN WRITE ACTIVE command become active immediately without any need to reboot your system. In fact, rebooting returns dynamic system parameter values to their previous settings. If you change dynamic parameter values, complete the DXML installation before rebooting the system. After the installation, you can reset the dynamic parameters to their previous values or leave them to be reset automatically the next time you reboot your system. Table 1-3 shows the required dynamic parameter values. Table_1-3_Minimum_Values_for_Dynamic_Parameters____________ Dynamic Parameter________Value_____________________________________ CLISYMTBL 250 LOCKIDTBL________200_______________________________________ Preparing to Install DXML 1-7 If the dynamic parameter values on your system are less than the values listed, use the following series of commands to change the values. This example changes the CLISYMTBL value to 250. $ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE ACTIVE SYSGEN> SET CLISYMTBL 250 SYSGEN> WRITE ACTIVE SYSGEN> EXIT 1.5.5 Process Account Quotas The account you use to install DXML must have sufficient quotas to enable you to perform the installation. Table 1-4 shows the process quotas required for the installing account. Except for PGFLQUOTA, all the process quotas are the default values. Table_1-4_Process_Account_Quotas___________________________ Account_Quota____Minimum_for_DXML__________________________ BYTLM 8192 ENQLM 100 FILLM 20 WSQUOTA 256 WSEXTENT 512 PGFLQUOTA_________40000____________________________________ For more information about how to modify account quotas, see the description of the Authorize Utility in the documentation for system management. 1.5.6 VMSINSTAL Requirements When you invoke VMSINSTAL, it checks whether you have done the following: o Set your default device and directory to SYS$UPDATE o Logged in to a privileged account o Set adequate quotas for installation o Backed up the system disk 1-8 Preparing to Install DXML VMSINSTAL also checks to see whether DECnet is running and whether any users are logged in to the system. VMSINSTAL requires that the installation account have a minimum of the following quotas: ASTLM = 24 BIOLM = 18 BYTLM = 8192 DIOLM = 18 ENQLM = 100 FILLM = 20 If VMSINSTAL detects any problems during the installation, it notifies you and asks if you want to continue the installation. In some instances, you can type Yes to continue. To stop the installation process and correct the situation, type No or press Return. Then, correct the problem and restart the installation. 1.6 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 that are established at your site. For details about how to perform a system disk backup, see the section on the Backup Utility in the System Management Subkit. Preparing to Install DXML 1-9 2 _________________________________________________________________ Installing DXML This chapter explains how to install the Digital Extended Math Library software. Section 2.1 contains a step-by-step description of the installation procedure. ________________________ Note ________________________ DXML provides online release notes and help text. Digital strongly recommends that you read the release notes before performing the installation. For information about how to access the online release notes, see Section 2.1 and Section 3.7. ______________________________________________________ 2.1 Installation Procedure The VMSINSTAL command procedure moves the DXML software from the distribution media to your system disk. The procedure consists of a series of questions and informational messages. Appendix A shows a sample installation. 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. To install DXML Version 2.9 on your OpenVMS system, take the following steps: 1. Invoke VMSINSTAL. To start the installation, run the VMSINSTAL command procedure from a privileged account, such as the SYSTEM account. @SYS$UPDATE:VMSINSTAL saveset-name device-name OPTIONS N Installing DXML 2-1 where: o saveset-name is one of the following: DXMLDVAV029 (Development Kit) DXMLRTAV029 (Run-time Kit) o device-name is the name of the device on which you plan to mount the media. For example, if you are in- stalling the distribution kit from a CD-ROM, the device name is DKA400:[DXMLDVAV029.KIT]. o OPTIONS N is an optional but recommended parameter that causes VMSINSTAL to prompt you about the release notes during the installation procedure. If you do not include the OPTIONS N parameter, VMSINSTAL does not ask you about the release notes. If you have already reviewed the release notes or are restarting the installation, you do not need to specify OPTIONS N. 2-2 Installing DXML In addition to the N option, you can invoke VMSINSTAL with the following options: - 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). - Get save set option (G): Lets you store product save sets temporarily on a magnetic tape or in a disk directory. - File log option (L): Logs all activity to the terminal during installation. - Alternate root option (R): Lets you install the product to a system root other than that of the running system. - Alternate working directory option (AWD =): Places temporary files used during the installation on a disk other than the system disk. This placement proves useful when the system disk is heavily loaded. If you specify more than one option, separate the options with commas (OPTIONS A,N). 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. 2. Confirm other processes. VMSINSTAL checks whether you are logged into the system account and checks for other active processes. If there are other users on the system, VMSINSTAL displays the following inquiry: %VMSINSTAL-W-ACTIVE, The following processes are still active: john_doe . . . * Do you want to continue anyway [NO]? Installing DXML 2-3 The DXML software only affects those currently using DXML. Type Yes to continue. 3. 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, type No to stop the installation. After you back up your system disk, you can restart the installation. 4. Mount the media. VMSINSTAL prompts you to mount the distribution volume on the device you specified when you invoked VMSINSTAL. Insert the compact disc on the device you specified when you invoked VMSINSTAL. VMSINSTAL then asks you if you are ready to continue with the installation. Please mount the first volume of the set on discname:. * Are you ready? Yes When you respond Yes, VMSINSTAL displays a message that the media containing DXML has been mounted on the specified device and that the installation has begun. The following products will be processed: DXMLDVAV V2.9 Beginning installation of DXMLDVAV V2.9 at 09:28 %VMSINSTAL-I-RESTORE, Restoring product save set A... If you entered the wrong device name when you invoked VMSINSTAL and need to restart the installation, type No in response to the "Are you ready?" question. To abort the installation for other reasons, press Ctrl/Y. 5. 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. 2-4 Installing DXML 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]: 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/Y. 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 press Return to send the file to the default output print device or you can enter another queue name. 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. o Select option 4 if you have already reviewed the release notes and are restarting the installation. Next, VMSINSTAL displays the following question: * Do you want to continue the installation [NO]? %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. To continue the installation, type Yes. Otherwise, press Return. In either case, the release notes are copied to the file SYS$HELP:DXML029.RELEASE_NOTES. If you chose to continue the installation, VMSINSTAL begins to access the remaining files in the kit. Installing DXML 2-5 6. Choose the Installation Verification Procedure (IVP) option. The installation procedure asks if you want to run the IVP during the installation procedure. The IVP for DXML links each component of the product. * Do you want to verify the DXML V2.9 library installation [Y]? Digital recommends that you run the IVP during the installation. You can also run the IVP at any time after DXML is installed. 7. Purge files. You now have the option to purge files from previous versions of DXML that are superseded by this installation. * Do you want to keep old copies of the system files for DXML [N]? %%DXMLDVAV-I-INSTOPT Purging is recommended; however, if you need to keep files from the previous version, type Yes in response to the question. 8. Read informational messages. VMSINSTAL tells you that there are no more questions. %DXMLDVAV-I-NOQUEST, No more questions will be asked. Approximately 4 -DXMLDVAV-I-NOQUEST, minutes remain to complete this procedure. At this point, VMSINSTAL verifies the license registration for DXML. The installation procedure stops if the Product Authorization Key (PAK) is not loaded. If you have not done so, stop the installation, register and load your PAK, and then restart the installation. Next, VMSINSTAL checks for installation requirements, such as the minimum values for system parameters. If any value does not meet the minimum requirement, VMSINSTAL stops the installation. Correct the problem and restart the installation. As the installation proceeds, VMSINSTAL displays a number of informational messages that report on the progress of the installation. 2-6 Installing DXML %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSTEST.DXML]. %CREATE-I-EXISTS, VMI$COMMON:[SYSTEST.DXML] already exists %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSTEST.DXML]. %CREATE-I-EXISTS, VMI$COMMON:[SYSTEST.DXML] already exists %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.DXML] %CREATE-I-EXISTS, VMI$COMMON:[SYSHLP.EXAMPLES.DXML] already exists %DXMLDVAV-I-EOINST, The primary installation phase is complete When the files for the product are transferred from the distribution medium to your system, you see the following message: %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... At this time, files in [SYSTEST.DXML] are purged if that directory already exists and if you chose that option. If this is a new installation, VMSINSTAL creates the directory and moves the files into it. Installing DXML 2-7 9. Observe the Installation Verification Procedure (IVP). DXML-I-IVP> DXML Installation Verification Procedure Copyright © Digital Equipment Corporation 1996. All Rights Reserved. When the IVP runs successfully, you see the following display: DXML-I-IVP> Completed successfully Installation of DXMLDVAV V2.9 completed at 10:51 10.End the installation procedure. The following messages indicate that the entire installation procedure is complete: Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]DXMLDVAV029.VMI_DATA VMSINSTAL procedure done at 10:51 You can now log out of the privileged account. 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, log out and log in again. 2.2 Error Recovery If an error occurs during the installation, VMSINSTAL displays the following message: %VMSINSTAL-E-INSFAIL, The installation of DXML V2.9 has failed. If an error occurs when the Installation Verification Procedure (IVP) is running, you see these messages: The DXML V2.9 Installation Verification Procedure failed. %VMSINSTAL-E-IVPFAIL, The IVP for DXML V2.9 has failed. Errors can occur 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. 2-8 Installing DXML o System parameter values for successful installation are insufficient. o The product license has not been registered and loaded. If any of these conditions exist, check the software requirements and the system prerequisites. Table 2-1 lists the error messages, preceded by the kit name (for example, DXMLDVAV029-I-), that are specific to the DXML installation. Failure messages from the verification procedure are not preceded by the kit name, but are identified in the prefix by the character string "IVP". Table_2-1_Error_Messages_for_DXML__________________________ Error Message_______Meaning______________________________________ -VMSBAD Wrong version of OpenVMS. -AXPNODE It is assumed that installation must be done from an Alpha system. -NOSPACE System disk contains too few free blocks. -PGFLQ Process does not have a large enough Paging File Quota. -LICFAIL Improper license. -NOGBLPG GBLPAGES parameter is set below required minimum. -NOGSECT GBLSECTIONS parameter is set below required minimum. -NOSEL No components of the DXML library were chosen ______________for_installation.____________________________ Installing DXML 2-9 3 _________________________________________________________________ After Installing DXML This chapter describes the tasks you perform after installing DXML: o Starting DXML o Making the product usable on a cluster, if necessary o Checking the installation by running the IVP o Reviewing the release notes o Reporting problems 3.1 Defining the Link Library DXML's startup command procedure defines the link library for DXML and adds the new definition to the system logical name table. If one or more link libraries are already defined, the procedure adds the new one to it. The LNK$LIBRARY logical name directs the linker to the appropriate image library. The default definition of LNK$LIBRARY is the image library SYS$LIBRARY:DXML$IMAGELIB_ GS.OLB, indicating the G_floating data type. Whether you use the default definition or change the definition, see Section 3.3 for instructions on starting DXML. 3.2 Installing DXML as a Known Image If you expect all or some of DXML's components to be used extensively, you can reduce the system overhead and memory requirements by installing the components as known images. After Installing DXML 3-1 In addition to the normal installation procedures for /shared images, OpenVMS Alpha allows installation of shareable images as a /resident image. When a shareable image is installed as a /resident image, a larger page size is accessed for each translation buffer reference. With fewer translation buffer misses, the images achieve a higher performance rate than the same image installed as a /shared image. By default, none of the components are installed as known images. DXML provides a startup command procedure that you can edit to specify the components you want installed as known images. See Section 3.3 for instructions on how to edit and invoke the startup procedure. 3.3 Starting DXML This section describes how to edit the startup command procedure and start the DXML software. If you want to use the default startup installation, start at step 4. If you want to change the link library but do not want to install known images, start at step 4b. If you want to install known images, use the following procedure. Digital recommends using this procedure on a system that has been rebooted recently to avoid having fragmented available space in the global page table. 1. Identify the DXML components that are likely to be used by more than one user at a time and would therefore benefit from being installed as known images. Decide whether to use the /shared installation or the /resident installation. 2. Refer to the tables in this section to obtain the total number of global resources required. o If installing these images as a /shared resource, add all relevant entries under the columns "GBLPAGES" and "GBLSECTIONS". Set the total for "GH_RSRVPGCNT" to zero. 3-2 After Installing DXML o If installing these images as a /resident resource, add together all relevant entries under the column "GH_RSRVPGCN7". Set the totals for columns "GBLPAGES" and "GBLSECTIONS" to zero. 3. Verify that the available resources on your system are adequate (see Section 3.4). 4. Edit the DXML command procedure SYS$STARTUP:DXML$STARTUP.COM. The DXML$STARTUP.COM file lists each of the relevant shareable images on a line. The following line lists options for the shareable image for IEEE format programs in BLAS1: $ DO DXML$STS_BLAS1 F R The last two elements on this line represent flags, as follows: o The default value of the first flag is "F", which indicates that this shareable image is not to be installed as a known image. Changing this flag to "T" will cause this shareable image to be installed. o The default value of the second flag is "R", which means that if the image is to be installed, it would be installed as a /resident image. Changing the value of this flag to "S" would cause the image to be installed as a /shared image, if the value of the first flag is "T". a. To make the IEEE floating point library the default link library, change the parameter GS in the following command to TS: $ @SYS$LIBRARY:DXML$SET_LIB GS /SYSTEM b. Invoke the command procedure: $ @SYS$STARTUP:DXML$STARTUP.COM Any component you selected is now available as a known image and the system logical name LNK$LIBRARY is defined. After Installing DXML 3-3 c. Add the following line to the appropriate system startup command file to ensure that DXML is started whenever the system is started: $ @SYS$STARTUP:DXML$STARTUP.COM The default system startup command file is SYS$MANAGER:SYSTARTUP_VMS.COM. Table 3-1 and Table 3-2 list the required global system resources needed for installed images. Table 3-1 Required Global System Resources for Installed __________Images_-_IEEE_Floating_Format____________________ Image_Name_______GBLPAGES___GBLSECTIONS___GH_RSRVPGCNT_____ DXML$STS_BLAS1 110 1 7 DXML$STS_BLAS1E 128 1 8 DXML$STS_BLAS2 599 1 38 DXML$STS_BLAS3 1251 1 79 DXML$STS_COMMON 13 2 1 DXML$STS_LAPACK 4965 1 311 DXML$STS_SIG_ 6592 2 413 PROC DXML$STS_SPARSE 499 1 32 DXML$STS_VLIB 27 2 2 TOTAL:___________14184______12____________891______________ Table 3-2 Required Global System Resources for Installed __________Images_-_G_Floating_Format_______________________ Image_Name_______GBLPAGES___GBLSECTIONS___GH_RSRVPGCNT_____ DXML$FGS_BLAS1 110 1 7 DXML$FGS_BLAS1E 128 1 8 DXML$FGS_BLAS2 599 1 38 DXML$FGS_BLAS3 1251 1 79 (continued on next page) 3-4 After Installing DXML Table 3-2 (Cont.) Required Global System Resources for __________________Installed_Images_-_G_Floating_Format_____ Image_Name_______GBLPAGES___GBLSECTIONS___GH_RSRVPGCNT_____ DXML$FGS_COMMON 13 2 1 DXML$FGS_LAPACK 4964 1 311 DXML$FGS_SIG_ 6587 2 413 PROC DXML$FGS_SPARSE 499 1 32 DXML$STS_VLIB 27 2 2 TOTAL:___________14178______12____________891______________ 3.4 Global Resources for Known Images To install shareable images for DXML as known images, sufficient resources are required. These resources are as follows: o For /shared images, GBLPAGES and GBLSECTIONS o For /resident images, MIN_GH_RSRVPGCNT and ITB_ENTRIES 3.4.1 Resources for Known /SHARED Images These quantities can be shown using the lexical function f$getsyi. Type the following: $ WRITE SYS$OUTPUT f$getsyi ("FREE_GBLPAGES") $ WRITE SYS$OUTPUT f$getsyi ("FREE_GBLSECTS") If either of these parameters is insufficient for your installation, use AUTOGEN to modify their values. 3.4.2 Resources for Known /RESIDENT Images The available GH_REGION quantity can be shown using the DCL command SHOW MEMORY. Type the following to get a map of the granularity hints region: $ SHOW MEMORY /GH_REGIONS After Installing DXML 3-5 If the free code region in this map is insufficient, then the parameter MIN_GH_RSRVPGCNT can be set to the required amount in the file SYS$SYSTEM:MODPARAMS.DAT. The value of ITB_ENTRIES is also set in the MODPARAMS.DAT file and can be adjusted from 1 to 4. A value of 1 will often suffice. As more images are installed using the /resident method, this value may need to be increased. For details about "granularity hints", see the system management documentation. After modifying the MODPARAMS.DAT file, the system may need to be rebooted using AUTOGEN. See Section 1.5.4.2. 3.5 Running DXML on a Cluster If you want to run DXML on multiple nodes of a cluster, first check to see that you have the appropriate software license. Then repeat the following procedure on each node in the cluster licensed to run DXML: 1. Log in to the SYSTEM account or an account that has the SYSPRV privilege. 2. Make sure that the SYSGEN parameters listed in Table 1-2 are properly set. 3. Load the license, as described in Section 1.4. If previous versions of the PAK are still loaded on the system, remove the current license and then load the new license. 4. Start DXML by invoking DXML$STARTUP.COM, as described in Section 3.3. 5. Edit the system startup file to include DXML$STARTUP.COM, as described in Section 3.3. 6. Create the SYSTEST account: $ CREATE/DIRECTORY SYS$SPECIFIC:[SYSTEST.DXML] 7. Execute the IVP: $ @SYS$TEST:DXML$IVP.COM 3-6 After Installing DXML 3.6 Running the IVP You usually run the Installation Verification Procedure (IVP) during installation. To run the IVP after installation to ensure the integrity of installed files if system problems occur, execute the following command procedure: $ @SYS$TEST:DXML$IVP.COM When the IVP runs successfully, you see the following display: DXML-I-IVP> Completed DXML V2.9 Installation Verification Procedure When you install DXML, the IVP test programs are copied to the sys$common:[systest.dxml] directory. For the Development Kit, the IVP checks the installation by first performing the link test, which verifies that all DXML subroutines have been properly installed. The IVP then links and executes a set of sample programs which verify the functionality of DXML. Execution of the Development IVP requires system privileges. 3.7 Reviewing Release Notes and Using Help At any time after the installation, you can enter the following command to review the release notes: $ TYPE SYS$HELP:DXML029.RELEASE_NOTES/PAGE Also, you can enter the following command to get DXML Help: $ HELP DXML 3.8 Reporting Problems If you encounter a problem while using DXML, 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). After Installing DXML 3-7 o Fill out and submit a Reader's Comments form if the problem has to do with the DXML documentation. There is a Reader's Comments form in the Preface of this manual. 3-8 After Installing DXML A _________________________________________________________________ Sample Installation This appendix contains a log of a complete installation of the DXML Development Kit. Your own installation might differ from this example because you can make different choices during the procedure. The following log illustrates questions and answers for an installation of DXML: $ @sys$update:vmsinstal DXMLDVAV029 OVERDO$DKB500:[DXML.KITS] options n OpenVMS AXP Software Product Installation Procedure T6.2-FT3 It is 23-APR-1996 at 11:05. Enter a question mark (?) at any time for help. %VMSINSTAL-W-NOTSYSTEM, You are not logged in to the SYSTEM account. %VMSINSTAL-W-ACTIVE, The following processes are still active: ---- * Do you want to continue anyway [NO]? y * Are you satisfied with the backup of your system disk [YES]? y The following products will be processed: DXMLDVAV V2.9 Beginning installation of DXMLDVAV V2.9 at 11:05 %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]: 4 Sample Installation A-1 * Do you want to continue the installation [NO]? y %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. %VMSINSTAL-I-RESTORE, Restoring product save set B ... +--------------------------------------------------------------------------+ | Copyright Digital Equipment Corporation 1992, 1996. 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. | +--------------------------------------------------------------------------+ Product Name: Digital Extended Math Library 2.9 Product Option: Development Library for OpenVMS Alpha * Do you want to run the IVP to verify the installation? [Y]? y * Do you want to keep old copies of DXML system files? [N]? n %DXMLDVAV-I-NOQUEST, No more questions will be asked. Approximately 2 -DXMLDVAV-I-NOQUEST, minute(s) remain to complete the installation %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSTEST.DXML]. %CREATE-I-EXISTS, VMI$COMMON:[SYSTEST.DXML] already exists %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.DXML]. %CREATE-I-EXISTS, VMI$COMMON:[SYSHLP.EXAMPLES.DXML] already exists %DXMLDVAV-I-EOINST, The primary installation phase is complete %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... DXML$SET-INF> DXML library set to SYS$LIBRARY:DXML$IMAGELIB_GS.OLB DXML-I-IVP> DXML Installation Verification Procedure DXML-I-IVP> Development Kit Copyright © Digital Equipment Corporation 1996. All Rights Reserved DXML-I-IVP> Completed successfully Installation of DXMLDVAV V2.9 completed at 00:18 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]DXMLDVAV029.VMI_DATA VMSINSTAL procedure done at 11:08 $ A-2 Sample Installation B _________________________________________________________________ Installed Files Table B-1 lists the files on your system after you install the DXML Development Kit. Table B-2 lists the Run-Time Kit files. Table_B-1_Files_Installed_by_the_Development_Kit___________ SYS$STARTUP:_______________________________________________ DXML$STARTUP.COM Startup command procedure ___________________________________________________________ SYS$HELP:__________________________________________________ DXML029.RELEASE_NOTES Online release notes DXML_LAPACK_C.TXT DXML_LAPACK_D.TXT DXML_LAPACK_S.TXT DXML_LAPACK_Z.TXT ___________________________________________________________ SYS$TEST:__________________________________________________ DXML$IVP.COM IVP command procedure ___________________________________________________________ SYS$LIBRARY:_______________________________________________ DXML$FGS_BLAS1.EXE DXML routines - G-float DXML$FGS_BLAS1E.EXE DXML$FGS_BLAS2.EXE DXML$FGS_BLAS3.EXE DXML$FGS_COMMON.EXE DXML$FGS_LAPACK.EXE DXML$FGS_SIG_PROC.EXE (continued on next page) Installed Files B-1 Table_B-1_(Cont.)_Files_Installed_by_the_Development_Kit___ SYS$LIBRARY:_______________________________________________ DXML$FGS_SPARSE.EXE DXML$FGS_VLIB.EXE DXML$STS_BLAS1.EXE DXML routines - IEEE-float DXML$STS_BLAS1E.EXE DXML$STS_BLAS2.EXE DXML$STS_BLAS3.EXE DXML$STS_COMMON.EXE DXML$STS_LAPACK.EXE DXML$STS_SIG_PROC.EXE DXML$STS_SPARSE.EXE DXML$STS_VLIB.EXE DXMLDEF.FOR Definition file for signal processing DXMLDEF.H Definition file for signal processing DXMLDEF_OLD.FOR Previous version of DXMLDEF DXMLDEF_OLD.H Previous version of DXMLDEF DXML_EQUIVALENCE_LAPACK.C LINPACK/LAPACK names conversion program DXML$EMACS.ML Editor support DXML$EVE.TPU DXML$IMAGELIB_GS.OLB G_floating point library DXML$IMAGELIB_TS.OLB IEEE floating point library DXML$SET_LIB.COM Library selection procedure ___________________________________________________________ SYS$COMMON:[SYSTEST.DXML]__________________________________ BLAS_BUILD_TEST.GOBJ BLAS_BUILD_TEST.TOBJ IVP_LAPACK_GFLOAT.OBJ IVP_LAPACK_IEEE.OBJ (continued on next page) B-2 Installed Files Table_B-1_(Cont.)_Files_Installed_by_the_Development_Kit___ SYS$COMMON:[SYSTEST.DXML]__________________________________ IVP_SIG_GFLOAT.OBJ IVP_SIG_IEEE.OBJ IVP_SPARSE_B1_GFLOAT.OBJ IVP_SPARSE_B1_IEEE.OBJ IVP_SPARSE_IS_GFLOAT.OBJ IVP_SPARSE_IS_IEEE.OBJ IVP_SPARSE_SKY_GFLOAT.OBJ IVP_SPARSE_SKY_IEEE.OBJ IVP_VLIB_GFLOAT.OBJ IVP_VLIB_IEEE.OBJ LAPACK_BUILD_TEST.GOBJ LAPACK_BUILD_TEST.TOBJ SIG_PROC_BUILD_TEST.GOBJ SIG_PROC_BUILD_TEST.TOBJ SPARSE_BUILD_TEST.GOBJ SPARSE_BUILD_TEST.TOBJ VLIB_BUILD_TEST.GOBJ VLIB_BUILD_TEST.TOBJ ___________________________________________________________ SYS$COMMON:[SYSHLP.EXAMPLES.DXML]__________________________ EXAMPLE_ITSOL_1.C EXAMPLE_ITSOL_1.CXX EXAMPLE_ITSOL_1.FOR EXAMPLE_ITSOL_2.FOR EXAMPLE_ITSOL_3.FOR EXAMPLE_ITSOL_4.FOR EXAMPLE_ITSOL_5.FOR EXAMPLE_LAPACK_1.C (continued on next page) Installed Files B-3 Table_B-1_(Cont.)_Files_Installed_by_the_Development_Kit___ SYS$COMMON:[SYSHLP.EXAMPLES.DXML]__________________________ EXAMPLE_LAPACK_1.FOR EXAMPLE_LAPACK_2.FOR EXAMPLE_SFFT_1D.C EXAMPLE_SFFT_2D.C EXAMPLE_SKYSOL_1.C EXAMPLE_SKYSOL_1.CXX EXAMPLE_SKYSOL_1.FOR EXAMPLE_SKYSOL_2.FOR EXAMPLE_SKYSOL_3.FOR EXAMPLE_SKYSOL_4.FOR EXAMPLES_SIG_PROC.FOR READ_ME.INDEX______________Road_map_for_the_examples_______ Table_B-2_Files_Installed_by_the_Run-Time_Kit______________ SYS$STARTUP:_______________________________________________ DXML$STARTUP.COM Startup command procedure ___________________________________________________________ SYS$HELP:__________________________________________________ DXML029.RELEASE_NOTES Online release notes ___________________________________________________________ SYS$TEST:__________________________________________________ DXML$IVP.COM IVP command procedure ___________________________________________________________ SYS$LIBRARY:_______________________________________________ DXML$FGS_BLAS1.EXE DXML routines - G-float DXML$FGS_BLAS1E.EXE DXML$FGS_BLAS2.EXE DXML$FGS_BLAS3.EXE DXML$FGS_COMMON.EXE DXML$FGS_LAPACK.EXE DXML$FGS_SIG_PROC.EXE DXML$FGS_SPARSE.EXE (continued on next page) B-4 Installed Files Table_B-2_(Cont.)_Files_Installed_by_the_Run-Time_Kit______ SYS$LIBRARY:_______________________________________________ DXML$FGS_VLIB.EXE DXML$STS_BLAS1.EXE DXML routines - IEEE-float DXML$STS_BLAS1E.EXE DXML$STS_BLAS2.EXE DXML$STS_BLAS3.EXE DXML$STS_COMMON.EXE DXML$STS_LAPACK.EXE DXML$STS_SIG_PROC.EXE DXML$STS_SPARSE.EXE DXML$STS_VLIB.EXE ___________________________________________________________ SYS$TEST:DXML$IVP.COM______________________________________ IVP_LAPACK_GFLOAT.EXE IVP_LAPACK_IEEE.EXE IVP_SIG_GFLOAT.EXE IVP_SIG_IEEE.EXE IVP_SPARSE_B1_GFLOAT.EXE IVP_SPARSE_B1_IEEE.EXE IVP_SPARSE_IS_GFLOAT.EXE IVP_SPARSE_IS_IEEE.EXE IVP_SPARSE_SKY_GFLOAT.EXE IVP_SPARSE_SKY_IEEE.EXE IVP_VLIB_GFLOAT.EXE IVP_VLIB_IEEE.EXE__________________________________________ Installed Files B-5 _________________________________________________________________ Index B______________________________ L______________________________ Backing up your system, 1-10 License registration, 1-2 Link library, 3-1 D______________________________ Disk space, 1-4 P______________________________ Privileges, 1-3 E______________________________ Process account quotas, 1-8 Error recovery, 2-8 R______________________________ G______________________________ Reporting problems, 3-7 Global resources, 3-5 Required operating system components, 1-1 H______________________________ Running DXML on a cluster, 3-6 Hardware requirements, 1-1 S _______________________________ I______________________________ Sample installation log, A-1 Installation procedure, 2-1 Software requirements, 1-2 Installation requirements, 1-3 Starting DXML, 3-2 Installed files, B-1 System parameters, 1-4 IVP, 3-7 V _______________________________ K______________________________ VMSINSTAL requirements, 1-8 Known image, 3-1 Index-1