DECmigrate_for_DEC_OSF/1_AXP_Systems__________ Installation Guide Order Number: AA-PSHEB-TE July 1993 This document contains instructions for installing DECmigrate for DEC OSF/1 AXP Systems on processors that are running the DEC OSF/1 Version 1.2 or later operating system. Revision/Update Information: This is a revised manual. Operating System & Version: DEC OSF/1 Version 1.2 or later. Future maintenance releases may require later versions. Software Version: DECmigrate Version 1.2 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ Third Printing, November 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. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © 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: AXP, DECmigrate, DEC OSF/1, DECstation, OpenVMS, ULTRIX, VAX, VAX DOCUMENT, and the DIGITAL logo. Open Software Foundation is a trademark of the Open Software Foundation, Inc. PostScript is a registered trademark of Adobe Systems Incorporated. UNIX is a registered trademark of UNIX System Laboratories, Inc. This document is available on CD-ROM. This document was prepared using VAX DOCUMENT, Version 2.1. ________________________________________________________________ Contents Preface.................................................. v 1 Preparing for the DECmigrate Installation 1.1 Release Notes................................... 1-1 1.2 License Registration............................ 1-2 1.3 Checking the Media Software Distribution Kit.... 1-3 1.4 Preinstallation Requirements.................... 1-3 1.4.1 Backing Up Your System Disk .................. 1-3 1.4.2 Checking Login Privileges .................... 1-3 1.4.3 Hardware Requirements ........................ 1-3 1.4.4 Software Requirements ........................ 1-4 1.4.5 Determining Which Subsets to Load ............ 1-4 1.4.6 Determining Disk Space Requirements .......... 1-4 1.4.7 Disk Space Requirements After Installation ... 1-5 1.5 Stopping the Installation....................... 1-6 1.6 Error Recovery.................................. 1-6 1.7 Reporting Problems to Digital................... 1-7 2 Installing DECmigrate 2.1 Starting the Installation Procedure............. 2-1 2.2 Responding to Installation Procedure Prompts.... 2-2 2.2.1 Monitoring Displays During the Subset Loading Process....................................... 2-3 iii 3 Completing the Installation A Sample Listings for DECmigrate Installation and Installation Verification Procedure A.1 Sample Installation............................. A-1 A.2 Installation Verification Procedure............. A-2 B Files Installed on Your System Tables 1-1 Subset Sizes (Disk Space Required) on AXP Processors ................................... 1-5 B-1 Installed DECmigrate Files ................... B-1 iv ________________________________________________________________ Preface This guide describes how to install DECmigrate for DEC OSF/1 AXP Systems, hereafter called DECmigrate, on AXP systems that are running the DEC OSF/1 Version 1.2 operating system. It describes how to prepare the system for installation, install the software, and how to configure the system following software installation. Keep this document with your distribution kit. You will need it to install maintenance updates or to reinstall DECmigrate, should that be necessary. Audience The audience for this guide is anyone installing DECmigrate onto a DEC OSF/1 Version 1.2 operating system using the CD-ROM distribution media. This guide assumes the following: o You or a Digital Field Service representative has checked the hardware to ensure that it works properly. o You have read the documentation supplied with your hardware. o You have read the DEC OSF/1 Release Notes. o You understand how to load and unload installation media and know which disks are needed during the installation. o You know the names and unit numbers of your disk devices. o You have a basic understanding of the file system and commands. v Structure of this Document This manual is structured as follows: o Chapter 1 describes the operating system and hardware required for installing DECmigrate and related proce- dures to be completed before installing DECmigrate. o Chapter 2 describes the procedure for local installa- tions. o Chapter 3 describes any postinstallation procedures that you must complete to use DECmigrate. o Appendix A contains sample listings for DECmigrate installation. o Appendix B contains a list of files installed on your system by the installation. Related Manuals In addition to this guide, the DECmigrate documentation set includes the following manual: DECmigrate for DEC OSF/1 AXP Systems Translating Executables The user guide and installation guide for DECmigrate are available on line in Bookreader format on the DEC OSF/1 Version 1.2 Layered Products Online Documentation CD-ROM. If you want bound copies of the user manual, you must order them separately. In addition to this manual, you can refer to the Guide to Installing DEC OSF/1 Version 1.2 for information concerning the base system installation. Conventions The following conventions are used in this guide: vi __________________________________________________________ Convention_______Meaning__________________________________ % The default user prompt is your system name followed by a right angle bracket (>). In this guide, a percent sign (%) is used to represent this prompt. # A number sign is the default superuser prompt. user input This bold typeface is used in interactive examples to indicate input entered by the user. ... Horizontal ellipsis indicates that the preceding item can be repeated one or more times. It is used in syntax descriptions and function definitions. . Vertical ellipsis indicates that a . portion of an example that would normally . be present is not shown. x A lowercase italic x indicates the generic use of a letter. For example, xxx indicates any combination of three alphabetic letters. Ctrl/x Ctrl/x indicates that you hold down the Ctrl key while you press another key (indicated here by x). 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. system output This typeface is used to indicate system output or the exact name of a command, option, partition, pathname, directory, or file. This typeface is also used in interactive examples to indicate system output as well as in code examples and other screen displays. vii __________________________________________________________ Convention_______Meaning__________________________________ variable This typeface indicates variable information, such as user-supplied information in commands, syntax, or example text. UPPERCASE and The DEC OSF/1 system differentiates lowercase between lowercase and uppercase characters. Literal strings that appear in text, examples, syntax descriptions, and function descriptions must be entered exactly as shown. cat(1) Cross-references to the online reference pages include the appropriate section number in parentheses. For example, a reference to cat(1) indicates that you can find material on the cat command in _________________Section_1_of_the_online_reference_pages._ viii 1 ________________________________________________________________ Preparing for the DECmigrate Installation Before starting the installation procedures described in Chapter 2, complete the preparations outlined in this chapter. This will make your installation run smoothly and help you do the following: o Confirm that the system on which you plan to install DECmigrate meets the hardware, software, and disk space requirements. o Register your License Product Authorization Key (PAK). o Confirm that your distribution kit includes all the components listed on the bill of materials (BOM). o Choose which optional DECmigrate subsets you should install. 1.1 Release Notes DECmigrate provides online release notes as part of the software kit on the Digital Layered Products Software Library for DEC OSF/1 Version 1.2 Systems CD-ROM. The release notes may contain information about changes to the application. Digital strongly recommends that you read the release notes before using the product. If the DEC OSF/1 Release Notes Addendum or Read Before Installing letter is listed on your BOM, please check to see if it contains information about DECmigrate. Preparing for the DECmigrate Installation 1-1 Preparing for the DECmigrate Installation 1.2 License Registration 1.2 License Registration DECmigrate includes support for the DEC OSF/1 License Management Facility (LMF). A License Product Authorization Key (License PAK) must be registered in the License Database in order to use DECmigrate on a newly licensed node. 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. To register a license under the DEC OSF/1 system, first log in as root so you can write to the root directory. You then have a choice of two ways to perform the PAK registration in the License Database: o Interactively Invoke the License Management Facility with the register argument and fill in the appropriate fields using the information supplied with your License PAK. # lmf register o Manually Copy the blank lmf template from /usr/var/adm/lmf /template into a temporary file, and fill in the appropriate fields using the information supplied with your License PAK. Exit the file. Execute the License Management Facility with the register argument and with the temporary file name as input. # lmf register - < filename After you register your license, use the lmf reset command to copy the license details from the License Database to the kernel cache: # lmf reset For complete information on using the License Management Facility, see the lmf(8) reference page. 1-2 Preparing for the DECmigrate Installation Preparing for the DECmigrate Installation 1.3 Checking the Media Software Distribution Kit 1.3 Checking the Media Software Distribution Kit Use the BOM to check the contents of your software distribution kit. The DECmigrate kit is supplied on the two following CD- ROMs: o Digital Layered Products Software Library for DEC OSF/1 Version 1.2 Systems: software, release notes, installation guide o DEC OSF/1 Version 1.2 Layered Products Online Documentation CD-ROM: user manual, installation guide 1.4 Preinstallation Requirements This section discusses preinstallation requirements for installing DECmigrate. Installing DECmigrate on your target system usually takes less than 20 minutes. 1.4.1 Backing Up Your System Disk Digital recommends that you back up your system disk before installing any software. Use the backup procedures established at your site. 1.4.2 Checking Login Privileges You must log in as root on the system where you are installing DECmigrate. Only when you are logged in as root do you have sufficient privileges to install the DECmigrate software. 1.4.3 Hardware Requirements To perform the installation you need access to the system's optical disc drive (CD-ROM drive). The documentation for the disc drive explains how to load the media on the drive. Preparing for the DECmigrate Installation 1-3 Preparing for the DECmigrate Installation 1.4 Preinstallation Requirements 1.4.4 Software Requirements DECmigrate Version 1.2 requires that DEC OSF/1 Version 1.2 or later be installed. 1.4.5 Determining Which Subsets to Load You must choose the DECmigrate subsets you want to load. The DECmigrate subsets have the following titles: o Environment hosted on DEC OSF/1 AXP (DMGMXR120) This subset executes on a DEC OSF/1 Version 1.2 (or later) AXP operating system. It must be present in order to run any translated executables on the DEC OSF/1 AXP system. o Reference pages for the Environment (mxr) and the Translator (mx) (DMGDOC120) This subset contains the reference material for DECmigrate. The mxr(1) reference page refers to the run-time environment for translated executables. The mx(1) reference page refers to the translator. o Translator hosted on DEC OSF/1 AXP (DMGOSF120) This subset executes on a DEC OSF/1 Version 1.2 (or later) AXP operating system. It contains the version of the mx translator that is a DEC OSF/1 AXP executable. It also contains the release notes for this version of DECmigrate. Under normal circumstances, you will want to use all of the subsets. 1.4.6 Determining Disk Space Requirements This section describes the disk space requirements for loading DECmigrate on a DEC OSF/1 Version 1.2 AXP operating system. Table 1-1 gives specific requirements for each subset and shows its location after installation. You will require more disk space after installing DECmigrate to translate programs. See Section 1.4.7. 1-4 Preparing for the DECmigrate Installation Preparing for the DECmigrate Installation 1.4 Preinstallation Requirements Table 1-1 Subset Sizes (Disk Space Required) on AXP __________Processors______________________________________ Subset Subset_Title__________Name________Directory___Size________ Translator (mx) DMGOSF120 /usr/bin 2.0 Mb Environment (mxr) DMGMXR120 /usr/shlib 0.4 Mb /usr/bin 0.6 Mb Reference Pages DMGDOC120 /usr/man 0.2 Mb ____________ Total space required 4.6 Mb on_DEC_OSF/1:_____________________________________________ 1.4.7 Disk Space Requirements After Installation In addition to the space required to install DECmigrate, you will need free disk space to perform translations. The mx translator (subset DMGOSF120) uses a considerable amount of virtual memory during translation. To translate an executable of size n, mx uses up to 20n bytes of virtual memory. Users should configure swap space on their system to handle this virtual memory requirement. While sufficient swap space is necessary for translating large executables, the time taken to translate also depends on the system physical memory and system load. In addition to the memory requirements for the run-time environment on AXP systems (subset DMGMXR120), the memory requirements for translated executables vary with the executable being run. Running a translated program requires an amount of virtual memory equal to the virtual memory used by the original program, plus memory for the translated code and mxr. As a rule, the required virtual memory for the translated program is calculated as the virtual memory requirements for the original program plus 1.4 times the size of the original program's text section to the virtual memory. Preparing for the DECmigrate Installation 1-5 Preparing for the DECmigrate Installation 1.4 Preinstallation Requirements Note that mxr loads the translated executable using mmap. If the interpreter is never used, then the pages corresponding to the MIPS code are never faulted in. Because they are mapped by mmap to the executable, the MIPS code thus consumes neither physical memory nor swap space, just a little pmap space. 1.5 Stopping the Installation You can stop the installation procedure any time by using Ctrl/C. However, files created up to this point are not deleted automatically. You must delete these files interactively. 1.6 Error Recovery If errors occur during the installation, the system displays failure messages. If the installation fails due to insufficient disk space, the following message appears: There is not enough file system space for subset n. DECmigrate n will not be loaded. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o The prerequisite software version is incorrect. o The system parameter values for successful installation are insufficient. o There are previous versions of DECmigrate on the system. For descriptions of error messages generated by these conditions, see the base system documentation on system messages, recovery procedures, and base system software installation. 1-6 Preparing for the DECmigrate Installation Preparing for the DECmigrate Installation 1.7 Reporting Problems to Digital 1.7 Reporting Problems to Digital If an error occurs while DECmigrate is in use and you believe the error is caused by a problem with DECmigrate, take one of the following actions: o If you have a Software Product Services Support Agreement, call your Customer Support Center (CSC). The CSC provides telephone support for high-level advisory and remedial assistance. o If you have a Self-Maintenance Software agreement, you can submit a Software Performance Report (SPR). o If you purchased DECmigrate within the last year and you think the problem is caused by a software error, you can submit an SPR. If you find an error in the documentation, please fill out one of the Reader's Comments forms at the back of the document containing the error and send the form to Digital. Please include the section and page number where the error occurred. When you call in or submit an SPR, please take the following steps: 1. Include in the description the version number of DECmigrate and the name and version number of the operating system being used. Without this information it is difficult or impossible to address the problem. 2. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Demonstrate the problem with specific examples. 3. Reduce the problem to as small a size as possible. If the CSC needs more background, you may be asked to supply the following: o Listings of any command files, include files, relevant data files, and so forth. o A listing of the program. Preparing for the DECmigrate Installation 1-7 Preparing for the DECmigrate Installation 1.7 Reporting Problems to Digital o For programs longer than 50 lines, a copy of the program on machine-readable media (diskette or magnetic tape). If necessary, also submit a copy of the program library used to build the application. For information about copying a program library to machine-readable media, see the tar(1) reference page. Report only one problem per SPR. This will facilitate a faster response. Mail the SPR package to Digital at the address given by the CSC. 1-8 Preparing for the DECmigrate Installation 2 ________________________________________________________________ Installing DECmigrate This chapter describes the installation procedures for DECmigrate. Before you start, read Chapter 1. DECmigrate is installed locally from a CD-ROM. You will be loading the real-time files from a disc located in a CD-ROM drive that belongs to the system where you perform the installation. 2.1 Starting the Installation Procedure Start the installation procedure as follows: 1. Log in as root on the system where you are installing DECmigrate. 2. Enter the following command to ensure that you are at the root (/) directory: # cd / 3. Mount the CD-ROM on the appropriate disc drive. 4. Specify the /mnt directory to be the mount point for the distribution file system on the drive. If your drive is rz4c, enter the following command: # mount -r /dev/rz4c /mnt 5. Enter a setld command that requests the load function and identifies the directory in the mounted file system where DECmigrate subsets are located. For an AXP system running the DEC OSF/1 operating system, the directory location for these subsets is /DMG120/bin: # setld -l /mnt/DMG120/bin Installing DECmigrate 2-1 2.2 Responding to Installation Procedure Prompts This section explains the installation procedure prompts and displays. To install the product, do the following: 1. After you enter the setld command for local (node- specific) installations, the installation procedure displays the names of the DECmigrate subsets and asks you to specify the subsets that you want to load: The subsets listed below are optional: . . [text describing subset display] . 1) Environment hosted on DEC OSF/1 AXP (DMGMXR120) 2) Reference Pages (DMGDOC120) 3) Translator hosted on DEC OSF/1 AXP (DMGOSF120) 4) ALL of the Above 5) CANCEL selections and redisplay menus 6) EXIT without installing any subsets Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6): If you specify more than one number at the prompt, separate each number with a space, not a comma. 2. The script lets you verify your choice. For example, if you enter 4 in response to the previous prompt, you will see the following display: You are installing the following subsets: Environment hosted on DEC OSF/1 AXP (DMGMXR120) Reference Pages (DMGDOC120) Translator hosted on DEC OSF/1 AXP (DMGOSF120) Is this correct? (y/n): If the displayed subsets are not the ones you intended to choose, enter n. In this case, the subset selection menu is again displayed, and you can correct your choice of optional subsets. If the displayed subsets are the ones you want to load, enter y. 2-2 Installing DECmigrate 2.2.1 Monitoring Displays During the Subset Loading Process The procedure displays a message that the installation is proceeding. When the installation is completed, you are returned to the root command line prompt. Chapter 3 discusses the postinstallation requirements specified in the final informational messages from the procedure. If, during the course of the installation, you encounter errors from the setld utility, see the Diagnostics section of the setld(8) reference page for an explanation of the error and the appropriate action to take. Installing DECmigrate 2-3 3 ________________________________________________________________ Completing the Installation This chapter explains what you need to do following the installation to make DECmigrate ready for use. The PAK information must be installed using the License Management Facility before users can access DECmigrate. See Section 1.2. After installing DECmigrate, verify that the software is available on your system. Use the setld command to verify the installation as follows: # setld -v subset subset ... where subset is the identifier of a subset you installed, for example, DMGDOC120. ________________________Note ________________________ The software licensed must be registered before users can access DECmigrate. Refer to Section 1.2 for details. _____________________________________________________ Completing the Installation 3-1 A ________________________________________________________________ Sample Listings for DECmigrate Installation and Installation Verification Procedure This appendix provides sample listings for the following procedures: o An installation of DECmigrate on a DEC OSF/1 AXP system using CD-ROM media o An Installation Verification Procedure (IVP) A.1 Sample Installation Here is a listing from a DECmigrate installation session: # setld -l . The subsets listed below are optional: There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1) Environment hosted on DEC OSF/1 AXP (DMGMXR120) 2) Reference Pages (DMGDOC120) 3) Translator hosted on DEC OSF/1 AXP (DMGOSF120) Or you may choose one of the following options: 4) ALL of the above 5) CANCEL selections and redisplay menus 6) EXIT without installing any subsets Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6): 1 2 3 You are installing the following optional subsets: DECmigrate Installation and Installation Verification Procedure A-1 Environment hosted on DEC OSF/1 AXP (DMGMXR120) Reference Pages (DMGDOC120) Translator hosted on DEC OSF/1 AXP (DMGOSF120) Is this correct? (y/n): y Checking file system space required to install selected subsets: OK Environment hosted on DEC OSF/1 AXP Copying from . (disk) Verifying Reference Pages Copying from . (disk) Verifying Translator hosted on DEC OSF/1 AXP Copying from . (disk) Verifying mx V1.1 on DEC OSF/1 AXP installed on flam03.amt.tay.dec.com at Mon Feb 08 18:42:21 EST 1993 NOTE: A license PAK is required to use mx mxr V1.1 installed on flam03.amt.tay.dec.com at Mon Feb 08 18:42:22 EST 1993 man pages for mx V1.1 installed on flam03.amt.tay.dec.com at Mon Feb 08 18:42:22 EST 1993 A.2 Installation Verification Procedure Here is a listing from an installation verification procedure (IVP) for DECmigrate: # setld -v DMGOSF120 DMGDOC120 DMGMXR120 Translator hosted on DEC OSF/1 AXP (DMGOSF120) Copyright (c) Digital Equipment Corporation, 1992, 1993. mx subset DMGOSF120 verified successfully Reference Pages (DMGDOC120) Copyright (c) Digital Equipment Corporation, 1992, 1993. Environment hosted on DEC OSF/1 AXP (DMGMXR120) Copyright (c) Digital Equipment Corporation, 1992, 1993. mxr subset DMGMXR120 verified successfully # A-2 Sample Listings for DECmigrate Installation and Installation Verification Procedure B ________________________________________________________________ Files Installed on Your System Table B-1 describes the contents of DECmigrate directo- ries. Table_B-1_Installed_DECmigrate_Files______________________ Directory___File________Description_______________________ /usr/bin mx MIPS translator (mx) /usr/bin mxr Run-time environment standalone executable (mxr) /usr/shlib libmxr.so Run-time environment shared library (mxr) /usr/man mx.1 Reference page for translator /usr/man mxr.1 Reference page for run-time ________________________environment_______________________ Files Installed on Your System B-1