DECmigrate_for_OpenVMS_AXP__________________________ Installation Guide Order Number: AA-PSGNA-TE June 1993 This document contains instructions for installing DECmigrate for OpenVMS AXP on an OpenVMS AXP system. Revision/Update Information: This manual supersedes the DECmigrate for OpenVMS AXP Version 1.0 Installation Guide. Operating System and Version: OpenVMS AXP Version 1.5 or higher Software Version: DECmigrate Version 1.1 for OpenVMS AXP Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ June 1993 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. © Digital Equipment Corporation 1993. 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: Alpha AXP, AXP, DEC, DEC 4000, DECchip, DECnet, DECmigrate, DECset DECwindows, Digital, OpenVMS, VAX, VAX DOCUMENT, VMS, VMScluster, the AXP logo, and the DIGITAL logo. The following are third-party trademarks. PostScript is a registered trademark of Adobe Systems Incorporated. All other trademarks and registered trademarks are the property of their respective holders. ZK6242 This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents Preface................................................... v 1 Preparing to Install DECmigrate 1.1 Required Operating System Components............. 1-1 1.2 Hardware Requirements............................ 1-1 1.3 Optional Software................................ 1-2 1.4 License Registration............................. 1-2 1.5 Installation Procedure Requirements.............. 1-3 1.5.1 Privileges and Disk Space ..................... 1-4 1.5.2 System Parameters ............................. 1-4 1.5.2.1 Checking System Parameter Values............ 1-5 1.5.2.2 Changing System Parameter Values with AUTOGEN..................................... 1-6 1.5.3 VMSINSTAL Requirements ........................ 1-7 1.5.4 Backing Up Your System Disk ................... 1-8 2 Installing DECmigrate 2.1 The Installation Procedure....................... 2-1 2.2 Error Recovery................................... 2-9 3 After Installing DECmigrate 3.1 Running the Installation Verification Procedure Separately....................................... 3-1 3.2 Editing the System Startup and Shutdown Files.... 3-1 3.3 Modifying System Parameters...................... 3-2 3.3.1 VMScluster Considerations ..................... 3-2 3.4 User Account Requirements........................ 3-2 3.4.1 Privileges .................................... 3-2 3.4.2 User Account Quota Settings ................... 3-2 3.5 Installing DECmigrate as a Shared Image ......... 3-3 iii 3.6 Installing DECmigrate on a Cluster............... 3-4 3.7 Determining and Reporting Problems............... 3-4 A Sample Installation B Installed Files and Logical Names B.1 File Names....................................... B-1 B.2 Logical Names.................................... B-4 Index Tables 1-1 Optional Software ............................. 1-2 1-2 Disk Space Requirements ....................... 1-4 1-3 DECmigrate Global Section and Pagelet Requirements................................... 1-5 3-1 Minimum WSEXTENT and PGFLQUOTA Quota Settings....................................... 3-2 3-2 Requirements for DECmigrate as Shared Image ... 3-3 B-1 DECmigrate Installed Files .................... B-1 B-2 DECmigrate Logical Names ...................... B-4 iv _________________________________________________________________ Preface The DECmigrate for OpenVMS AXP Systems Installation Guide describes how to install DECmigrate for OpenVMS AXP on an OpenVMS AXP system. Intended Audience This guide is intended for system managers who plan to install DECmigrate for OpenVMS AXP. ________________________ Note ________________________ In this guide, the term DECmigrate refers to the DECmigrate for OpenVMS AXP Systems product. ______________________________________________________ Keep this document with your distribution kit. You will need it to install maintenance updates or to reinstall DECmigrate for other reasons. Document Structure This guide contains three chapters and two appendices: o Chapter 1 describes how to prepare for DECmigrate installation. o Chapter 2 describes how to install DECmigrate. o Chapter 3 describes postinstallation procedures. o Appendix A shows a sample installation. o Appendix B describes the DECmigrate files installed on your system and the logical names that are defined. v Associated Documents In addition to this guide, the DECmigrate documentation set includes the manual DECmigrate for OpenVMS AXP Systems Translating Images. For information on the DECmigrate online release notes, see Section 2.1 of this document. For general information about OpenVMS system management, see the OpenVMS operating system documentation set. For descriptions of OpenVMS system error messages, use the online Help Message utility or refer to the OpenVMS system messages documentation. Conventions The following conventions are used in this manual: . . . A horizontal ellipsis in examples indicates one of the following possibilities: o Additional optional arguments in a statement have been omitted. o The preceding item or items can be repeated one or more times. o Additional parameters, values, or other information can be entered. A vertical ellipsis indicates the omission . of items from a code example or command . format; the items are omitted because . they are not important to the topic being discussed. ( ) In format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. vi [ ] In format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in a VMS file specification, or in the syntax of a substring specification in an assignment statement.) boldface text Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason. Boldface text is also used to show user input in Bookreader versions of the manual. 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), command lines (for example, /PRODUCER=name), and command parameters in text. UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. - A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows. x A lowercase italic x indicates the generic use of a letter. For example, xxx indicates any combination of three alphabetic letters. Ctrl/x The Ctrl/x sequence indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. vii n A lowercase italic n indicates the generic use of a number. For example, 19nn indicates a 4-digit number in which the last 2 digits are unknown. numbers All numbers in text are assumed to be decimal, unless otherwise noted. Nondecimal radixes-binary, octal, or hexadecimal-are explicitly indicated. viii 1 _________________________________________________________________ Preparing to Install DECmigrate This chapter discusses the preparations and requirements necessary for installing DECmigrate. This manual applies to Version 1.1 of DECmigrate and all subsequent maintenance releases up to the next major product release. DECmigrate 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, item 4. 1.1 Required Operating System Components DECmigrate Version 1.1 for OpenVMS AXP Systems requires OpenVMS AXP Version 1.5 or higher. The OpenVMS operating system comes with a variety of support options, or classes. You can use the VMS Tailoring utility (VMSTAILOR) to customize the size of the OpenVMS operating system by deleting or adding optional classes. (See the OpenVMS System Manager's Manual: Essentials for a description of VMSTAILOR.) Classes include such features as networking and RMS journaling. To use DECmigrate, your system should be running a version of OpenVMS that includes at least the programming support class. 1.2 Hardware Requirements DECmigrate runs on any OpenVMS AXP system. In addition, the DECmigrate commands FLOWGRAPH and DSTGRAPH generate PostScript output. To view the output you must either print it on a PostScript printer or use the CDA Viewer application to display it on a workstation screen. 1-1 Preparing to Install DECmigrate 1.2 Hardware Requirements The CDA Viewer application is part of the DECwindows Motif for OpenVMS AXP product (see Section 1.3). The size of the PostScript output that FLOWGRAPH and DSTGRAPH generate depends on the size of the images you are translating and the type of output you request. For larger images and PostScript files, Digital recommends that you use a fast PostScript printer, such as the LPS40 Plus. 1.3 Optional Software Table 1-1 provides information on optional software that you can use together with DECmigrate. Table_1-1_Optional_Software________________________________ Optional_Products___Purpose________________________________ DECset for OpenVMS The DECset layered product includes AXP Version 11.0 the DECmodule management system (MMS). The DECmigrate command VEST/DEPENDENCY creates an MMS description file. Using the DECmigrate command file called VEST_MMS_DRIVER.COM, you can submit the description file to MMS, which then issues VEST commands to translate a set of OpenVMS VAX images in the correct order. DECwindows Motif The CDA Viewer, a DECwindows for OpenVMS AXP application, allows you to view Version_1.1_________DECmigrate_PostScript_output_online.___ 1.4 License Registration Before you install and run DECmigrate 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 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 you are installing DECmigrate as an update on a node or cluster already licensed for this software, you have already completed the License PAK registration requirements. 1-2 Preparing to Install DECmigrate 1.4 License Registration If you have not registered the product's license, the installation will fail and display the following messages: %VEST-E-NOLICENSE, DECMigrate installation requires a valid license %VEST-E-NOLICENSE, Install a Product Authorization Key (PAK) and retry. %VEST-E-RETRY, Please correct the reported problem(s) before reinstalling. DECmigrate V1.1 for OpenVMS Alpha installation aborted. %VMSINSTAL-E-INSFAIL, The installation of VEST V1.1 has failed. 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 PAK. o At the DCL prompt, enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to PAK information. If you plan to use DECmigrate on more than one node in a VMScluster, you will need to perform a license load on the other nodes after you complete this installation. See Section 3.3.1. For complete information on using LMF, see the manual on the License Management Facility in the OpenVMS documentation set. 1.5 Installation Procedure Requirements This section and those that follow discuss various requirements for installing DECmigrate. The installation takes approximately 2 to 10 minutes, depending on your system configuration and load. Installing DECmigrate and running the Installation Verification Procedure (IVP) on a standalone DEC 3000 Model 500 system takes 2 minutes. 1-3 Preparing to Install DECmigrate 1.5 Installation Procedure Requirements 1.5.1 Privileges and Disk Space To install DECmigrate, you must be logged in to an account that has SETPRV or at least the following privileges: o CMKRNL o WORLD o SYSPRV Note that VMSINSTAL turns off BYPASS privilege at the start of the installation. DECmigrate checks during installation to ensure that there are 13,000 free blocks on the install disk. If the space is not available, installation fails. The DECmigrate requirements for free disk storage space are different during installation and after installation. Table 1-2 summarizes the storage requirements. The figures shown do not include the size of the DECmigrate save sets. Table_1-2_Disk_Space_Requirements__________________________ Blocks During Blocks After Kit______________Installation__________Installation________ DECmigrate 13,000 9,000 Version_1.1________________________________________________ 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 1.5.2 System Parameters The system parameters set by the AUTOGEN.COM command procedure on your system should be sufficient for installing DECmigrate. Table 1-3 shows the global section and pagelet requirements for the message files installed with DECmigrate. If necessary, compare the values shown with your current settings for the GBLPAGES and GBLSECTIONS system parameters. 1-4 Preparing to Install DECmigrate 1.5 Installation Procedure Requirements Table 1-3 DECmigrate Global Section and Pagelet __________Requirements_____________________________________ Message_File_____Global_Sections__Pagelets_________________ VEST$MSG 1 24 FLOWGRAPH$MSG____1________________2________________________ The following sections show you how to: o Check system parameter values o Calculate values for the GBLPAGES and GBLSECTIONS system parameters o Change parameter values with the VMS AUTOGEN command procedure 1.5.2.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): $ RUN SYS$SYSTEM:SYSGEN SYSGEN> At the SYSGEN> prompt, enter the SHOW command to display the value of a system parameter. The following example displays the value for the GBLPAGES system parameter: SYSGEN> SHOW GBLPAGES After checking the parameters with the SHOW command, enter the EXIT command at the SYSGEN> prompt to return to DCL level. To install and run DECmigrate, 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. If the value of free global pagelets or global sections is less than you need, you must increase the system parameter setting. Section 1.5.2.2 describes the procedures for increasing these values using AUTOGEN. 1-5 Preparing to Install DECmigrate 1.5 Installation Procedure Requirements 1.5.2.2 Changing System Parameter Values with AUTOGEN If you do not have enough free global pagelets or free global sections to install DECmigrate, you can do either of the following: o Delete an existing known image using the OpenVMS Install utility. o Use the AUTOGEN command procedure to increase the GBLPAGES or GBLSECTIONS system parameters. AUTOGEN automatically adjusts values for parameters that are associated with the values you reset manually. To change system parameters with AUTOGEN, edit the following file: SYS$SYSTEM:MODPARAMS.DAT To change a parameter value listed in this file, delete the current value associated with that parameter and enter the new value. To add a new parameter, add a line to the file that includes both the name of the parameter and its value. For example: WSMAX = 8096 To modify incremental parameters such as GBLPAGES and GBLSECTIONS, use the ADD_ prefix before the parameter name. The following example increases the virtual page count by 20,000: ADD_VIRTUALPAGECNT = 20000 After you make all your changes, exit from the editor, then execute the AUTOGEN procedure to recalculate your system parameters. The following command recalculates your system parameters and reboots the system: $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT When you specify REBOOT, AUTOGEN does an automatic system shutdown and then reboots the system. Any users logged on to the system are immediately disconnected during the shutdown. The automatic reboot puts the new parameter values into effect. 1-6 Preparing to Install DECmigrate 1.5 Installation Procedure Requirements The AUTOGEN command 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 Manager's Manual: Tuning, Monitoring, and Complex Systems. 1.5.3 VMSINSTAL Requirements When you invoke VMSINSTAL, it checks the following: o Have you set your default device and directory to SYS$UPDATE? o Are you logged in to a privileged account? o Have you adequate quotas for installation? o Is DECnet running? o Are any users logged in to the system? Note that the VMSINSTAL requires that the installation account have a minimum of the following quotas: ASTLM = 24 BIOLM = 18 BYTLM = 18,000 DIOLM = 18 ENQLM = 30 FILLM = 20 Use the OpenVMS Authorize utility to change the process quotas for the installation account in the user authorization file (UAF). (Some sites may restrict the use of the OpenVMS Authorize utility to certain accounts or people.) For instance, to change the BYTLM quota for the account-name installation account, you might enter the following command sequence: $ RUN SYS$SYSTEM:AUTHORIZE UAF> MODIFY account-name /BYTLM = 18000 UAF> SHOW account-name UAF> EXIT $ LOGOUT 1-7 Preparing to Install DECmigrate 1.5 Installation Procedure Requirements After the quotas for the installation account have been changed, log out of the installation account and log in again for the new quotas to take effect. You can then proceed with the installation. 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 enter YES to continue. To stop the installation process and correct the situation, enter NO or press RETURN. Then, correct the problem and restart the installation. 1.5.4 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 backup the system disk before installing any software. Use the backup procedures that are established at your site. For details on performing a system disk backup, see the section on the Backup Utility in the OpenVMS System Manager's Manual: Essentials. 1-8 2 _________________________________________________________________ Installing DECmigrate This chapter explains how to install DECmigrate. Section 2.1 contains a step-by-step description of the installation procedure. 2.1 The Installation Procedure The DECmigrate installation procedure consists of a series of questions and informational messages. See Appendix A for a sample installation. If it is not already inserted, place the Compact Disc (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. 1. Log in to a privileged account. 2. Invoke VMSINSTAL. @SYS$UPDATE:VMSINSTAL saveset-name device-name option- list To start the installation, invoke the VMSINSTAL command procedure from a privileged account, such as the SYSTEM account. VMSINSTAL is in the SYS$UPDATE directory. The following list defines the elements of the VMSINSTAL command procedure: saveset-name The installation name for the component. For DECmigrate, use the following installation name: VEST 2-1 Installing DECmigrate 2.1 The Installation Procedure To obtain the directory location of the DECmigrate saveset on the CD, refer to the OpenVMS AXP Layered Products Disc User's Guide booklet that accompanies the CD distribution kit, or before starting installation, complete these steps: To determine whether the CD drive is already mounted (MOUNT command), type following command: $ SHOW DEVICE DKA400: If it is not mounted, type the appropriate MOUNT command to mount the CD (omit the /FOREIGN qualifier). To obtain the directory name, type the following command: $ DIRECTORY DKA400:[000000]*VEST*.dir Directory DKA400:[000000] VEST011.DIR;1 To obtain the saveset name, use a DIRECTORY command specifying the directory file from the previous command: $ DIRECTORY DKA400:[VEST011] device-name The name of the device on which you plan to mount the media and the directory containing the DECmigrate savset. For example, DKA400: is the device name used in examples in this document. To specify the device name on the @VMSINSTAL command line, type: DKA400:[VEST011] option-list The word OPTIONS followed by one or more of the following option designators: A, G, L, N, R. o Auto_answer option (A) Initially creates a file that contains your answers to VMSINSTAL questions and prompts. You can then use the option (and the answer file) to save time during a reinstallation (typically after upgrading your system). 2-2 Installing DECmigrate 2.1 The Installation Procedure 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. o Display or print the release notes (N) Indicates that you want to see the installation question on release notes. If you do not include the N option, 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 N option. (Even if you omit the N option when you invoke VMSINSTAL, the DECmigrate release notes are copied automatically to the SYS$HELP directory.) o Alternate root option (R) Lets you install the product to a system root other than that of the running system. See the VMS documentation on software installation in the VMS System Management Subkit for detailed information on these options. If you specify more than one option, separate the options with commas, such as: OPTIONS A,N The following example invokes VMSINSTAL to install DECmigrate from the CD driver DKA400: and shows the system response. This example uses the OPTIONS N release note parameter. $ @SYS$UPDATE:VMSINSTAL VEST011 DKA400:[VEST011] OPTIONS N OpenVMS Alpha Software Product Installation Procedure V1.5 It is 20-MAY-1993 at 13:15. Enter a question mark (?) at any time for help. 2-3 Installing DECmigrate 2.1 The Installation Procedure If you do not supply either the product name or the device name, VMSINSTAL prompts you for this information later in the installation procedure. 3. Confirm system backup. * Are you satisfied with the backup of your system disk [YES]? VMSINSTAL asks if you are satisfied with your system backup. You should always back up your system disk before performing an installation. If you are satisfied with the backup of your system disk, press RETURN. Otherwise, enter NO to discontinue the installation. After you back up your system disk, you can restart the installation. If you omitted the device name on the VMSINSTAL command line, the following prompt appears: * Where will the distribution volumes be mounted: DKA400:[VEST011] If this prompt appears, type the name of the distribution (media) device and directory that contains the DECmigrate kit (save set). For example, if the media is contained on a CD located on unit DKA400:, type DKA400:[VEST011] in reply to this question. Depending on the type of device and whether the device is already mounted, the following prompt may or may not appear. Please mount the first volume of the set on DKA400:. * Are you ready? YES %MOUNT-I-MOUNTED, DKA400: mounted If you have not already done so, you should now insert the distribution volume on the device you specified when you invoked VMSINSTAL. The device name appears in the line preceding the question. VMSINSTAL then asks you if you are ready to continue with the installation. If you respond "Yes" to indicate that you are ready, VMSINSTAL displays a message that the media containing DECmigrate has been mounted on the specified device and that the installation has begun. If you entered the wrong device name when you invoked VMSINSTAL and need to restart the installation, respond "No" to the "Are you ready?" question. To stop (abort) the installation for other reasons, press Ctrl/Y. 2-4 Installing DECmigrate 2.1 The Installation Procedure 4. Select a release notes option. Release notes included with this kit are always copied to SYS$HELP. Additional Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above * Select option [2]: If you specified OPTIONS N when you invoked VMSINSTAL, you are now asked to choose one of the four options for reviewing the release notes. 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: * 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 restarting the installation. To continue the installation, enter YES. Otherwise, press RETURN. In either case, the release notes are copied to a file in the SYS$HELP directory: SYS$HELP:VEST011.RELEASE_NOTES After the installation, you can use the Help facility to get information on how to access the release notes: $ HELP VEST RELEASE_NOTES 2-5 Installing DECmigrate 2.1 The Installation Procedure 5. Choose the Installation Verification Procedure (IVP) option. * Do you want to run the IVP after the installation [YES]? The installation procedure now asks if you want to run the IVP. The IVP for DECmigrate checks to be sure that the installation is successful. It is recommended that you run the IVP. After DECmigrate is installed, you can run the IVP independently to verify that the software is available on your system. You might need to run the IVP after a system failure to make sure that users can access DECmigrate. 6. Purge files. * Do you want to purge files replaced by this installation [YES]? You have the option to purge files from previous versions of DECmigrate that are superseded by this installation. Purging is recommended; however, if you need to keep files from the previous version, enter NO in response to the question. 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: No further questions will be asked. The DECmigrate installation will now continue for several minutes, depending on your type of media and your system configuration. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.VEST]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSTEST.VEST]. 2-6 Installing DECmigrate 2.1 The Installation Procedure *************************************************************** * * * If this installation is performed on a cluster, you must * * execute * * * * $ @SYS$STARTUP:VEST$STARTUP.COM * * * * on all other nodes in the cluster. In addition, you must * * add the above line to your site specific startup procedure: * * * * SYS$MANAGER:SYSTARTUP_VMS.COM * * * *************************************************************** %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... 8. Observe the Installation Verification Procedure (IVP). If you chose to run the IVP, VMSINSTAL runs it now. When the IVP runs successfully, you see the following display: +---------------------------------------+ | Installation Verification Procedure | | for DECMigrate V1.1 | +---------------------------------------+ 2-7 Installing DECmigrate 2.1 The Installation Procedure VEST$IVP => Checking for presence of IVP files VEST$IVP => Translating shareable image %VEST-I-SHAREABLE, Input is a shareable image -- writing IIF file SYS$COMMON:[SYSTEST.VEST]IVP$SHARE.IIF; VEST$IVP => Checking for output files VEST$IVP => Translating test image VEST$IVP => Checking for output files Hello from main routine Hello from routine A Hello from routine B VEST$IVP => Testing Flowgraph GRAPH 1: 4 nodes 3 arcs ACYCLIC 1 page written. GRAPH 2: 0 nodes 0 arcs ACYCLIC 0 pages written. GRAPH 3: 9 nodes 8 arcs ACYCLIC 1 page written. VEST$IVP => Testing DSTgraph 1 modules, 0 items, 0 selected, 0 skewed, 0 unaligned: 0 pages. +-----------------------------------------------------+ | DECmigrate V1.1 IVP has completed successfully | +-----------------------------------------------------+ Installation of VEST V1.1 completed at 16:13 9. The installation procedure prints a few more messages and ends. Installation of VEST 1.1 completed at 13:20 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]VEST011.VMI_DATA VMSINSTAL procedure done at 13:20 The previous messages indicate that the entire installation procedure is complete. You can now log out of the privileged account: $ LOGOUT SYSTEM logged out at 13:20:45 Note that VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the system manager's account and you want to restore these symbols, you should log out and log in again. 2-8 Installing DECmigrate 2.2 Error Recovery 2.2 Error Recovery VEST displays an error message if it encounters an error while the Installation Verification Procedure (IVP) is running. An IVP notification then follows: VEST$IVP => Error while translating test image +------------------------------------+ | DECmigrate V1.1 IVP has failed | +------------------------------------+ %NONAME-F-NOMSG, Message number number %VMSINSTAL-E-IVPFAIL, The IVP for VEST V1.1 has failed. The number displayed in the %NONAME-F-NOMSG message is the number of the preceding VEST error message. Other errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o Quotas necessary for successful installation are insufficient. o System parameter values for successful installation are insufficient. o The OpenVMS help library is currently in use. o The product license has not been registered and loaded. For descriptions of the error messages generated by these conditions, see the VMS documentation on system messages, recovery procedures, and VMS software installation. If you are notified that any of these conditions exist, you should take the appropriate action as described in the message. For information on installation requirements, see Chapter 1. 2-9 3 _________________________________________________________________ After Installing DECmigrate The following tasks take place after installing DECmigrate: o Running the Installation Verification Procedure separately (Section 3.1) o Editing the system startup and shutdown file (Section 3.2) o Modifying system parameter settings (Section 3.3) o Making the product usable on a VMScluster or VAXcluster (Section 3.3.1) o Setting user account quotas (Section 3.4) o Installing DECmigrate as a Shared Image (Section 3.5) o Reporting problems (Section 3.7) 3.1 Running the Installation Verification Procedure Separately You usually run the Installation Verification Procedure (IVP) during installation. If you want to run the IVP separately to ensure the integrity of installed files should system problems occur, execute the following command procedure: $ @SYS$TEST:VEST$IVP 3.2 Editing the System Startup and Shutdown Files You must edit the system startup file to provide for automatic startup of DECmigrate when your system is rebooted. Add the command line that starts DECmigrate to the system startup file, SYS$MANAGER:SYSTARTUP_VMS.COM. 3-1 After Installing DECmigrate 3.3 Modifying System Parameters 3.3 Modifying System Parameters The VAX Environment Software Translator (VEST), a DECmigrate utility, uses significant amounts of memory. It may be necessary to adjust the WSMAX and VIRTUALPAGECNT system parameters to accommodate required WSEXTENT and PGFLQUOTA user account quotas, which are discussed in Section 3.4.2. See Section 1.5.2.2 for information on changing system parameters. 3.3.1 VMScluster Considerations You must perform license loads on each node in the VMScluster on which users plan to access the product. Instructions for loading licenses are in Section 1.4. 3.4 User Account Requirements To work with DECmigrate, the user accounts on your system must have certain privileges and quotas. The next two sections contain information on these requirements. 3.4.1 Privileges Using DECmigrate requires no special privileges. 3.4.2 User Account Quota Settings Table 3-1 lists the minimum settings for the WSEXTENT and PGFLQUOTA user quotas for any account used to run the VEST utility. Table_3-1_Minimum_WSEXTENT_and_PGFLQUOTA_Quota_Settings____ WSEXTENT 10,240 pagelets PGFLQUOTA_____________100,000_pagelets_____________________ VEST requires a working set of about 5000 pagelets to translate a 100-block executable image. Translating larger programs requires increasingly larger amounts of memory, although the increase is not necessarily linear. You must ensure that the page files are large enough, otherwise the required PGFLQUOTA quota will not work. Furthermore, the SYSGEN parameter VIRTUALPAGECNT should be adjusted accordingly. 3-2 After Installing DECmigrate 3.4 User Account Requirements VEST performance can degrade significantly if these parameters are set incorrectly. If VEST runs out of virtual memory while translating an image, try increasing the amount of available virtual memory. Translations of extremely large images can require 900,000 to 1,000,000 pagelets. See Section 1.5.2 for a description of how to verify and change account quotas. 3.5 Installing DECmigrate as a Shared Image If you expect DECmigrate to be used extensively on your system, you can reduce the system overhead and memory requirements by installing it as a shared image. To install DECmigrate as a shared image on a system that is currently running, use the OpenVMS Install utility (INSTALL). It is recommended that you install DECmigrate as shared on a system that has been rebooted recently because the available space in the global page table is less likely to be fragmented. Table 3-2 notes that DECmigrate use of global sections and global pagelets when it is installed as a shared image. Table_3-2_Requirements_for_DECmigrate_as_Shared_Image______ Product_______________Global_Sections__Global_Pagelets_____ DECmigrate____________4________________6200________________ To install DECmigrate as a shared image, first, determine the number of available global pagelets and global sections on your system. See Section 1.5.2.1 for information on how to verify and modify the number of global pagelets and global sections. Once you have reset the system parameter values, invoke the OpenVMS Install utility from a privileged account and then install DECmigrate as a shared image: $ INSTALL INSTALL> ADD SYS$SYSTEM:VEST$MAIN_TV.EXE /OPEN/SHARED INSTALL> EXIT 3-3 After Installing DECmigrate 3.5 Installing DECmigrate as a Shared Image Now, add the following lines to the VEST$STARTUP.COM command file so that DECmigrate is available as a shared image whenever that command file is executed. $ INSTALL INSTALL> ADD SYS$SYSTEM:VEST$MAIN_TV.EXE /OPEN /SHARED INSTALL> EXIT 3.6 Installing DECmigrate on a Cluster If this installation is performed on a cluster, you must execute the following startup procedure on all other nodes in the cluster: $ @SYS$STARTUP:VEST$STARTUP.COM 3.7 Determining and Reporting Problems If you encounter a problem while using DECmigrate, 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 If your software contract or warranty agreement entitles you to telephone support, call Digital. o Submit a Software Performance Report (SPR). o If the problem is related to DECmigrate documentation, fill out and submit a Reader's Comments form, located at the back of each manual. Use the form from the manual in which you found the error. Include the section and page number. When you submit an SPR, please take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include in the description the version numbers of the DECmigrate product and the OpenVMS operating system 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, information files, relevant data files, and so forth. 3-4 After Installing DECmigrate 3.7 Determining and Reporting Problems 4. Provide a listing of the program including machine code generated by the compiler and a linker map file that has been generated with the /FULL qualifier. 5. Provide a copy of the executable program on machine- readable media (floppy diskette, magnetic tape, or CD-ROM). 6. If the program is longer than 50 lines, submit a copy of it on machine-readable media (floppy diskette, magnetic tape, or CD-ROM). If necessary, also submit a copy of the program library used to build the application and the executable image being translated. 7. Report only one problem per SPR. This will facilitate a faster response. 8. Mail the SPR package to Digital. Experience shows that many SPRs do not contain enough information to duplicate or identify the problem. Concise, complete information helps Digital give accurate and timely service to software problems. 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. 3-5 A _________________________________________________________________ Sample Installation This appendix contains a sample installation. This sample was run on a system that had no previous version of DECmigrate installed. Depending on which layered products you have on your system, you might see additional messages and questions when you perform your installation. OpenVMS ALPHA Software Product Installation Procedure V1.5 It is 20-MAY-1993 at 13:15. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? * Where will the distribution volumes be mounted: DKA400:[VEST011] Enter the products to be processed from the first distribution volume set. * Products: vest * Enter installation options you wish to use (none): The following products will be processed: VEST V1.1 Beginning installation of VEST V1.1 at 13:15 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. %VMSINSTAL-I-RESTORE, Restoring product save set B ... Beginning installation of DECmigrate for OpenVMS AXP V1.1 at 13:17 COPYRIGHT (c) DIGITAL EQUIPMENT CORPORATION 1993. ALL RIGHTS RESERVED. The installation can be aborted at any time by typing CTRL/Y. This kit contains an Installation Verification Procedure (IVP) to verify the correct installation of DECmigrate. It can be run prior to the conclusion of this procedure by answering "yes" to the IVP prompt or invoked after the installation as follows: A-1 Sample Installation @SYS$TEST:VEST$IVP * Do you want to run the IVP after the installation [YES]? * Do you want to purge files replaced by this installation [YES]? No further questions will be asked. The DECmigrate installation will now continue for several minutes, depending on your type of media and your system configuration. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.VEST]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSTEST.VEST]. *************************************************************** * * * If this installation is performed on a cluster, you must * * execute * * * * $ @SYS$STARTUP:VEST$STARTUP.COM * * * * on all other nodes in the cluster. In addition, you must * * add the above line to your site specific startup procedure: * * * * SYS$MANAGER:SYSTARTUP_VMS.COM * * * *************************************************************** Installation of DECmigrate for OpenVMS AXP V1.1 completed at 13:19 %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... +---------------------------------------+ | Installation Verification Procedure | | for DECMigrate V1.1 | +---------------------------------------+ A-2 Sample Installation VEST$IVP => Checking for presence of IVP files VEST$IVP => Translating shareable image %VEST-I-SHAREABLE, Input is a shareable image -- writing IIF file SYS$COMMON:[SYSTEST.VEST]IVP$SHARE.IIF; VEST$IVP => Checking for output files VEST$IVP => Translating test image VEST$IVP => Checking for output files Hello from main routine Hello from routine A Hello from routine B VEST$IVP => Testing Flowgraph GRAPH 1: 4 nodes 3 arcs ACYCLIC 1 page written. GRAPH 2: 0 nodes 0 arcs ACYCLIC 0 pages written. GRAPH 3: 9 nodes 8 arcs ACYCLIC 1 page written. VEST$IVP => Testing DSTgraph 1 modules, 0 items, 0 selected, 0 skewed, 0 unaligned: 0 pages. +-----------------------------------------------------+ | DECmigrate V1.1 IVP has completed successfully | +-----------------------------------------------------+ Installation of VEST V1.1 completed at 13:20 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]VEST011.VMI_DATA Enter the products to be processed from the next distribution volume set. * Products: Ctrl/Z A-3 B _________________________________________________________________ Installed Files and Logical Names The DECmigrate 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 Table B-1 lists all the files created on your system when DECmigrate is installed. Table_B-1_DECmigrate_Installed_Files_____________________________ Location______File____________________Description________________ SYS$HELP: VEST01n_RELEASE_ The release notes in NOTES.PS PostScript format. VEST01n.RELEASE_NOTES The release notes in ASCII format. VEST.HLP The VEST help file. FLOWGRAPH.HLP The FLOWGRAPH help file. DSTGRAPH.HLP The DSTGRAPH help file. DECMIGRATE.MSGHLP$DATA An unsupported file used to view DECmigrate messages using the OpenVMS AXP HELP/MESSAGE utility. See Release Notes for details. SYS$LIBRARY: (continued on next page) B-1 Installed Files and Logical Names B.1 File Names Table_B-1_(Cont.)_DECmigrate_Installed_Files_____________________ Location______File____________________Description________________ DSTGRAPH$PREDST.PS A PostScript prefix file used by the DSTGRAPH command. FLOWGRAPH$PREGRAPH.PS A PostScript prefix file used by the FLOWGRAPH command. COBRESTVA.OBJ A COBOL OpenVMS VAX object file to be linked with COBOL programs that include either the CANCEL verb or the IS INITIAL phrase of the PROGRAM-ID paragraph. SYS$MESSAGE: VEST$MSG_TV.EXE The VEST message file. FLOWGRAPH$MSG_TV.EXE The FLOWGRAPH message file. SYS$STARTUP: VEST$STARTUP.COM The VEST startup command file. SYS$SYSROOT:[SYSHLP.EXAMPLES.VEST] BUILD_MYMATH_AXP.COM Command files used to build BUILD_MYMATH_VAX.COM the translated and native shareable images used as examples in the DECmigrate for OpenVMS AXP Systems Translating Images manual. BUILD_MYMATH_JACKET_ AXP.COM BUILD_MYMATH_JACKET_ VAX.COM GIRDLE_TV.EXE The GIRDLE command program, an unsupported feature. See release notes for a description of GIRDLE. (continued on next page) B-2 Installed Files and Logical Names B.1 File Names Table_B-1_(Cont.)_DECmigrate_Installed_Files_____________________ Location______File____________________Description________________ GIRDLE.CLD The GIRDLE command line definition file. See release notes, unsupported features. HELLO_WORLD.EXE A sample OpenVMS VAX image. MYJACKET.C Example program source MYMAIN.C files and transfer vectors MYMATH.C for the main and shareable MYMATH_STUB.MAR images built by the MYVEC.MAR BUILD*.COM files listed MYVEC_JACKET.MAR above. SIEVE.EXE The Sieve of Eratosthenes, a sample OpenVMS VAX image. SIF2OPT.C Example program for SIF2OPT_TV.EXE converting symbol information file (.SIF file) entries to OpenVMS AXP symbol vector entries. SYS$SYSROOT:[SYSTEST.VEST] IVP$SHARE.EXE An Installation Verification Procedure (IVP) file. IVP$TEST.EXE An Installation Verification Procedure (IVP) file. SYS$SYSTEM: VEST_MMS_DRIVER.COM A command file to execute MMS and VEST. VEST$MAIN_TV.EXE The VEST program. FLOWGRAPH$MAIN_TV.EXE The FLOWGRAPH program. DSTGRAPH$MAIN_TV.EXE The DSTGRAPH program. SYS$TEST: (continued on next page) B-3 Installed Files and Logical Names B.1 File Names Table_B-1_(Cont.)_DECmigrate_Installed_Files_____________________ Location______File____________________Description________________ VEST$IVP.COM The Installation Verification Procedure ______________________________________(IVP)_command_file.________ In addition, the installation procedure creates the following two directories: SYS$SYSROOT:[SYSHLP.EXAMPLES.VEST] SYS$SYSROOT:[SYSTEST.VEST] The following two command definition files are installed in the file SYS$LIBRARY:DCLTABLES.EXE: DSTGRAPH.CLD VEST.CLD FLOWGRAPH.CLD B.2 Logical Names Table B-2 lists the logical names entered into the system logical name table when DECmigrate is installed. These names are defined in the VEST$STARTUP.COM file. Table_B-2_DECmigrate_Logical_Names_________________________ Logical_Name__________Description__________________________ DSTGRAPH$MAIN Points to the DSTGRAPH$MAIN image location (DSTGRAPH$MAIN_TV in the current release). FLOWGRAPH$MAIN Points to the FLOWGRAPH$MAIN image location (FLOWGRAPH$MAIN_TV in the current release). VEST$INCLUDE Points to the standard image information file locations. VEST$MAIN Points to the VEST$MAIN image location (VEST$MAIN_TV in the current ______________________release).____________________________ B-4 _________________________________________________________________ Index A Device name _______________________________ of CD, 2-2 Account requirements specifying, 2-4 after installation, 3-2 Directory Authorize utility specifying, 2-4 changing process quotas, 1-7 Disk space requirements, 1-4 DKA400: B______________________________ device name in examples, 2-2 Backing up system disk, 1-8, E 2-4 _______________________________ Editing system startup files, C______________________________ 3-1 CD Error recovery, 2-9 device name of, 2-2 describing problem, 3-4 distribution, 2-2 reporting problems, 3-4 mounting, 2-2 submitting Software CDA Viewer, 1-2 Performance Report (SPR), Checking system parameters, 3-4 1-5 telephone support, 3-4 Classes, 1-1 F Cluster _______________________________ installing on a, 3-4 Files installed by installation, D______________________________ B-1 DEC/Module Management System purging after installation, (MMS) 2-6 See MMS FLOWGRAPH command DECwindows Motif, 1-2 PostScript output Describing problem in error requirements, 1-2 reports, 3-4 Free disk space determining, 1-4 Index-1 IVP (cont'd) G______________________________ running separately, 3-1 GBLPAGES system parameter, 1-4 changing, 1-6 K______________________________ requirements for shared image Kit , 3-3 obtaining location of, 2-2 GBLSECTIONS system parameter, 1-4, 1-5 L______________________________ changing, 1-6 Length of installation, 1-3 requirements for shared image License , 3-3 using VMSLICENSE.COM to GLBPAGES system parameter, 1-5 register, 1-3 H______________________________ License Management Facility Hardware requirements, 1-1 See LMF License registration I______________________________ See LMF Informational messages, 2-6 LMF Installation license registration, 1-2 end of, 2-8 Logical names defined, B-4 files installed, B-1 M length of, 1-3 _______________________________ sample, A-1 Messages tasks after, 3-1 failure, 2-9 Installation procedure, 2-1 informational, 2-6 Installation requirements, 1-3 MMS Installation verification and VEST/DEPENDENCY command, procedure (IVP) 1-2 See IVP description file, 1-2 Installing MOUNT command preparations for, 1-1 using to mount CD, 2-2 requirements for, 1-1 O Installing as shared image, _______________________________ 3-3 Obtaining saveset location, INSTALL utility 2-2 installing as shared image, Operating system components 3-3 required, 1-1 Invoking VMSINSTAL, 2-1 Optional software requirements IVP , 1-2 display, 2-7 OPTIONS parameter, 2-2 option, 2-6 running during installation, 2-6 Index-2 Requirements (cont'd) P______________________________ disk space, 1-4 PAK global section, 1-4 registering, 1-2 hardware, 1-1 Parameter installation, 1-1 VMSINSTAL OPTION, 2-2 installation procedure, 1-3 PGFLQUOTA user account quota optional software, 1-2 settings for, 3-2 pagelet, 1-4 Privileges PostScript printer, 1-1 after installation, 3-2 privileges, 1-4 Privileges required, 1-4 support options, 1-1 Process quotas system parameter, 1-4 changing, 1-7 user account, 3-2 minimum for VMSINSTAL, 1-7 user privileges after Process symbol tables installation, 3-2 changes by VMSINSTAL, 2-8 VMSINSTAL, 1-7 Product Authorization Key Requirements for shared image see PAK global section, 3-3 Programming support pagelet, 3-3 required class, 1-1 S Purging files, 2-6 _______________________________ Sample installation, A-1 Q______________________________ Saveset Quotas obtaining location of, 2-2 changing process, 1-7 obtaining name of, 2-2 minimum for VMSINSTAL, 1-7 Shared image installing as, 3-3 R Software _______________________________ requirements for optional Recovery software, 1-2 error, 2-9 Software Performance Report Registering See SPR PAK (Product Authorization Specifying device and Key), 1-2 directory, 2-4 Registering license SPR using VMSLICENSE.COM, 1-3 submitting, 3-4 Release notes Starting VMSINSTAL, 2-1 accessing, 2-5 Startup VMSINSTAL questions, 2-2, logical names defined at, 2-5 B-4 Reporting errors, 3-4 Startup procedure, 3-4 Requirements Submitting SPR, 3-4 checking system parameter, 1-5 classes, 1-1 Index-3 Support options VMSLICENSE.COM procedure, 1-3 required, 1-1 VMSTAILOR SYSTARTUP_VMS.COM using, 1-1 editing, 3-1 System disk W______________________________ backing up, 1-8 WSEXTENT user account quota System parameter requirements, settings for, 3-2 1-4 WSMAX system parameter System parameters adjusting, 3-2 adjusting VIRTUALPAGECNT, 3-2 adjusting WSMAX, 3-2 changing, 1-6 checking, 1-5 modifying, 3-2 requirements for shared image , 3-3 System startup file editing, 3-1 T______________________________ Telephone support for error reporting, 3-4 U______________________________ User account quotas PGFLQUOTA, 3-2 WSEXTENT, 3-2 Using VMSTAILOR, 1-1 V______________________________ VEST$STARTUP_VMS.COM modifying for shared image, 3-4 VIRTUALPAGECNT system parameter adjusting, 3-2 VMSINSTAL failure messages, 2-9 invoking, 2-1 OPTIONS parameter, 2-2 requirements for, 1-7 Index-4