Compaq COBOL for_OpenVMS_Alpha_Systems___________________________ Installation Guide Order Number: AA-PXE7H-TE August 1999 This guide describes how to install Compaq COBOL (formerly known as DIGITAL COBOL or DEC COBOL) on an Alpha system running the OpenVMS Alpha operating system. This guide applies to Compaq COBOL Version 2.6 and any maintenance updates for that version. Revision/Update Information: This manual supersedes the Version 2.5 DIGITAL COBOL Installation Guide for OpenVMS Alpha Systems Operating System & Version: OpenVMS Alpha Version 6.2 or higher. Future releases may require higher versions. Software Version: Compaq COBOL Version 2.6 Compaq Computer Corporation Houston, Texas ________________________________________________________________ August 1999 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorizied only pursuant to a valid written license from DIGITAL or an authorized sublicensor. © Digital Equipment Corporation 1994, 1999. All Rights Reserved. Compaq and the Compaq logo are registered in the United States Patent and Trademark Office. The following are trademarks of Digital Equipment Corporation: Alpha, DEC, DECnet, DIGITAL, DIGITAL UNIX, OpenVMS, VAX, VAX COBOL, VAX DOCUMENT, VMS, VMScluster, and the DIGITAL logo. The following are third-party trademarks: DBAPack, Hot Standby, Oracle CDD/Administrator, Oracle CDD/Repository, Oracle CODASYL DBMS, Oracle DBA Workcenter, Oracle Enterprise Manager, Oracle Expert, Oracle Graphical Schema Editor, Oracle InstantSQL, Oracle Rally, Oracle Rdb, Oracle RMU, Oracle RMUwin, Oracle SQL/Services, Oracle Trace, Oracle Trace Collector, and Rdb7 are trademarks of Oracle Corporation. OSF/1 and Motif are registered trademarks of The Open Group in the U.S. and other countries. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. X/Open is a trademark of X/Open Company Limited. All other trademarks and registered trademarks are the property of their respective holders. ZK6295 This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. ______________________________________________________________ Contents ................................................... v Preparing for Compaq COBOL Installation 1.1 Reading the Online Release Notes.............. 1-1 1.2 Registering Your Software License............. 1-2 1.3 Optional Software............................. 1-3 1.4 Checks and Requirements for Installing Compaq COBOL......................................... 1-3 1.5 Installation Procedure Requirements........... 1-3 1.5.1 Privileges................................ 1-3 1.5.2 System Parameters......................... 1-4 1.5.3 Disk Space................................ 1-4 1.5.4 Backing Up Your System Disk............... 1-5 1.6 Standard System Maintenance Procedures........ 1-5 1.6.1 Calculating the Values for Global Pagelets and Global Sections....................... 1-5 1.6.2 Changing System Parameter Values with AUTOGEN................................... 1-6 Installing Compaq COBOL 2.1 Installation Procedure........................ 2-1 2.2 Run-Time Library Installation Procedure....... 2-10 After Installation 3.1 Running the Installation Verification Procedure Separately.......................... 3-1 3.2 Customizing Compaq COBOL Error Messages....... 3-2 3.3 Making Compaq COBOL Usable on a VMScluster.... 3-3 3.4 User Account Privileges....................... 3-5 3.5 Installing Compaq COBOL as a Shared Image..... 3-6 iii A Sample Installations A.1 Compiler Installation......................... A-1 A.2 RTL Installation.............................. A-4 B Recovering from Errors B.1 Failures During Compaq COBOL Installation..... B-1 B.2 Problems During Compaq COBOL Use.............. B-2 B.2.1 Run-Time Library Mismatch................. B-2 B.2.2 Other Problems............................ B-2 Examples A-1 Sample Compaq COBOL Installation and IVP....................................... A-1 A-2 Sample Compaq COBOL RTL Installation...... A-4 Tables 1 Telephone and Direct Mail Orders.......... vii 1-1 Minimum Required System Parameter Values.................................... 1-4 1-2 Disk Space Requirements................... 1-4 2-1 Installation Option Designators........... 2-3 iv _________________________________________________________________ Preface This guide describes how to install Compaq COBOL on Alpha processors that are running the OpenVMS Alpha operating system. Keep this document with your distribution kit. You will need it to install maintenance updates or to reinstall Compaq COBOL for any other reason. Associated Documentation In addition to this guide, the Compaq COBOL documentation set includes the following: o DIGITAL COBOL Reference Manual (not revised for this release) o DIGITAL COBOL User Manual (not revised for this release) o DIGITAL COBOL Multiplatform Overview & Compatibility Guide o DIGITAL COBOL DBMS Database Programming o Compaq COBOL Release Notes (see Section 1.1) o Compaq COBOL Help o Read Before Installing or Using Compaq COBOL Version 2.6 for OpenVMS Alpha Systems cover letter You may also find the following documentation useful: o Guide to Software License Management o Guide to Sharing Software on a Local Area Network o OpenVMS License Management Utility Manual o OpenVMS System Manager's Manual v Conventions The following conventions are used in this guide: ___________________________________________________________ Convention____________________Meaning______________________ [YES] Default answers to system [NO] questions are framed in square brackets. Simply press to accept the default response. UPPERCASE In text, uppercase letters indicate the name of a command, a file, a parameter, a procedure, or a Compaq COBOL utility. $ @SYS$UPDATE:VMSINSTAL In interactive examples, saveset-name prompts or displayed text appear in a monospace font. User input appears in bold monospace. Lowercase indicates a name that you supply. Uppercase is to be typed as shown. $ The dollar sign is used to indicate the DCL prompt. This prompt may be different on your system. In procedures, a sequence such as indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. n The minor (point) release of Compaq COBOL in examples is shown by n, as in COBOL02n. For Version 2.6, you type ______________________________COBOL026.____________________ vi References As of Version 2.6, DIGITAL COBOL is renamed Compaq COBOL. In this manual, every use of OpenVMS Alpha and OpenVMS AXP means the OpenVMS Alpha operating system and every use of Tru64 UNIX means the Tru64 UNIX operating system. Tru64 UNIX was formerly called DEC OSF/1. As of Version 4.0F, the DIGITAL UNIX name is changed to Compaq Tru64 UNIX. In this manual, every use of Oracle CDD/Repository means the Oracle CDD/Repository product of Oracle Corporation, every use of Oracle DBMS means the Oracle CODASYL DBMS product of Oracle Corporation, and every use of Oracle Rdb means the Oracle Rdb product of Oracle Corporation. How to Order Additional Documentation Use Table 1 to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-ATCOMPA. Table_1_Telephone_and_Direct_Mail_Orders___________________ Location_______Call/Fax____Write___________________________ U.S.A. 800- Compaq Computer Corporation ATCOMPA P.O. Box CS2008 Fax: Nashua, NH 03061 800-234- 2298 Puerto Rico 809-781- Compaq Computer Caribbean, Inc. 0505 3 Digital Plaza, 1st Street, Fax: Suite 200 809-749- P.O. Box 11038 8300 Metro Office Park San Juan, Puerto Rico 00910-2138 (continued on next page) vii Table_1_(Cont.)__Telephone_and_Direct_Mail_Orders__________ Location_______Call/Fax____Write___________________________ Canada 800-267- Compaq Computer of Canada, Ltd. 6215 Box 1300 Fax: 100 Herzberg Road 613-592- Kanata, Ontario, Canada K2K 2A6 1946 Attn: DECdirect Sales International - Local Compaq subsidiary or approved distributor Internal DTN: 264- U.S. Software Supply Business Orders 4446 Compaq Computer Corporation 603-884- 8 Cotton Road 4446 Nashua, NH 03063-1260 Fax: 603-884- _______________3960________________________________________ viii Reader's Comments Compaq appreciates your comments. If you find errors or want to comment about this manual, please send the manual title, order number, and your comments by one of the following methods: o Electronic Internet mail: cobol_docs@bookie.enet.dec.com o Fax: 603-884-0120 Attn: Languages Documentation, ZKO2-3/K35 o A letter sent to the following address: Compaq Computer Corporation Languages Documentation, ZKO2-3/K35 110 Spit Brook Road Nashua, NH 03062-2698 USA Field Test Sites The Compaq COBOL team would like to acknowledge the contributions of our field test sites in improving our products. The people at these sites provided us with invaluable information, which ultimately resulted in a higher quality, more useful COBOL compiler. ix 1 _________________________________________________________________ Preparing for Compaq COBOL Installation Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or if you find that parts of it are missing, contact your Compaq representative. Your distribution kit includes a letter titled Read Before Installing or Using Compaq COBOL Version 2.6 for OpenVMS Alpha Systems. The letter discusses important information that might not be included in this guide. You should read this letter before beginning the installation. 1.1 Reading the Online Release Notes Compaq COBOL provides online release notes. Compaq strongly recommends that you read the release notes before installing the product. The release notes may contain information about changes to the application. The release notes for Compaq COBOL are in the following file: SYS$HELP:COBOL026.RELEASE_NOTES For information about installing these release notes before installing Compaq COBOL, see Table 2-1, Installation Option Designators. You can use the following command to read the release notes after Compaq COBOL is installed: $ HELP COBOL RELEASE_NOTES Preparing for Compaq COBOL Installation 1-1 1.2 Registering Your Software License Before you install and run Compaq COBOL Version 2.6 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 Compaq COBOL as an update on a node or cluster already licensed for this software, you have already completed the License PAK registration requirements. If you are installing prerequisite or optional software along with Compaq COBOL, review the PAK status and install the PAKs for any prerequisite or optional software before you install Compaq COBOL. If you are planning to use the Oracle DBMS programming capability, you must purchase the Compaq COBOL Oracle DBMS programming license option, which includes a license PAK for use of this option. See the Compaq COBOL Software Product Description (SPD) for more information on the Oracle DBMS programming license option. You must register and load your license for Compaq COBOL before you start the installation in order to run the Installation Verification Procedure (IVP) and to use the software. To register a license on OpenVMS, first log in to the system manager's SYSTEM account. You then have a choice of two ways to perform the registration: o Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, respond with data from your License PAK. o At the DCL prompt, enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to License PAK information. If you plan to use Compaq COBOL 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-2 Preparing for Compaq COBOL Installation For complete information on using LMF, see the OpenVMS License Management Utility Manual. 1.3 Optional Software You can use the following optional software together with Compaq COBOL: o Oracle CDD/Repository Version 5.3 or higher o Oracle DBMS Version 5.1 or higher o DIGITAL Language Sensitive Editor/Source Code Analyzer Version 4.5 or higher 1.4 Checks and Requirements for Installing Compaq COBOL If you are installing Oracle Rdb or Oracle CDD/Repository, you should make certain that they have been successfully installed before you begin to install Compaq COBOL. To eliminate possible installation errors, execute the following command procedure to start up Oracle CDD/Repository: $ @SYS$STARTUP:CDDSTRTUP.COM 1.5 Installation Procedure Requirements This section describes the requirements for installing Compaq COBOL, which include process account quotas, system parameters, disk space, and so on. Standard procedures for checking and setting various parameters are described in Section 1.6. 1.5.1 Privileges To install Compaq COBOL, 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. Preparing for Compaq COBOL Installation 1-3 Privileges required for product use are defined in Section 3.4. 1.5.2 System Parameters Table 1-1 lists the minimum required system parameter values for the installation. Depending on the kinds of programs and applications running at your site, you might need higher values for some settings. Table_1-1__Minimum_Required_System_Parameter_Values________ Minimum System_Parameter_________Value_____________________________ Contiguous free global 7000 pagelets[1] Global sections[1] 3 [1]These_values_represent_the_number_of_free_global________ pagelets and global sections required for the installation, not the total number you need to run your system and other software. ___________________________________________________________ ________________________ Note ________________________ If you do not ensure that your system has the necessary global pagelets and global section SYSGEN parameters for the installation, the DCL tables can become corrupted in some situations. ______________________________________________________ 1.5.3 Disk Space The Compaq COBOL requirements for free disk storage space are different during installation and after installation. Table 1-2 summarizes the storage requirements. Table_1-2__Disk_Space_Requirements_________________________ Blocks During Blocks After Kit______________Installation__________Installation________ Compaq_COBOL_____18,000________________16,000______________ 1-4 Preparing for Compaq COBOL Installation 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.4 Backing Up Your System Disk At the beginning of the installation, VMSINSTAL asks if you have backed up your system disk. Compaq recommends that you do a system disk backup 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 backing up the system disk in the OpenVMS System Manager's Manual. 1.6 Standard System Maintenance Procedures This section explains how to do various standard procedures: o Calculate values for global pagelets and global sections. o Change parameter values with the OpenVMS AUTOGEN command procedure. 1.6.1 Calculating the Values for Global Pagelets and Global Sections You must have an adequate number of free global pagelets and global sections to install and run Compaq COBOL. First, determine how many free global pagelets and sections you have on your system, then use AUTOGEN to increase the global pagelets and global sections system parameters as necessary. The following DCL command will return a figure that you can use as an approximation of the number of global pagelets needed: $ DIR/SIZE SYS$LIBRARY:DCLTABLES.EXE You can use the WRITE command with the F$GETSYI lexical function to find the number of free global pagelets and global sections on your system. The following example shows how to get this information at your terminal (the default for SYS$OUTPUT): Preparing for Compaq COBOL Installation 1-5 $ WRITE SYS$OUTPUT F$GETSYI("CONTIG_GBLPAGES") 15848 $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLSECTS") 24 Section 1.6.2 describes the procedures for increasing these values using AUTOGEN. 1.6.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 SYS$SYSTEM:MODPARAMS.DAT 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: WSMAX = 8096 To modify incremental parameters such as free global pagelets and global sections, use ADD_. The following example increases the global page setting by 2000: ADD_GBLPAGES = 2000 Note that when you set the page file quota, you do not use a value that exceeds the amount of page file space available on the system. After you make all your changes, exit from the editor and execute the AUTOGEN procedure to recalculate your system parameters. The following command recalculates your system parameters and reboots the system: $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT When you specify REBOOT, AUTOGEN performs an automatic system shutdown and then reboots the system. 1-6 Preparing for Compaq COBOL Installation ________________________ Note ________________________ Any users logged on to the system are immediately disconnected during the shutdown. ______________________________________________________ The automatic reboot puts the new parameter values into effect. The AUTOGEN 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. For more information about using AUTOGEN, see the OpenVMS System Manager's Manual. Preparing for Compaq COBOL Installation 1-7 2 _________________________________________________________________ Installing Compaq COBOL After you register and load the license PAK (including the COBOL DBMS PAK, if you have it), the installation can take approximately 10 minutes, depending on your system configuration. If you encounter any failures during installation, see Appendix B. 2.1 Installation Procedure 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 to DCL level. To retry the installation procedure after pressing Ctrl/Y, proceed from Step 2. When the system prompts you with a question during the installation procedure, the default answer is often listed in brackets ([]). To install Compaq COBOL, perform the following steps: 1. Log in to a privileged account and set your default device and directory to SYS$UPDATE: Username: SYSTEM Password: $ SET DEFAULT SYS$UPDATE Installing Compaq COBOL 2-1 2. Invoke VMSINSTAL: @VMSINSTAL saveset-name device-name option-list saveset-name The installation name for the component. For Compaq COBOL, use the following installation name: COBOL02n n represents the minor (point) release number for Compaq COBOL. For example, use COBOL026 for Version 2.6. device-name The name of the device on which you plan to mount the media and the directory containing the Compaq COBOL save set. DKA400: is the device name used here. For example: DKA400:[cobol02n.kit] If you are uncertain which CD contains the COBOL save set, or which version of COBOL is on it, you can find out as follows: o Refer to the OpenVMS Alpha Layered Products Compact Disc User's Guide that accompanies the CD distribution kit. o Or complete these steps before starting installation: a. Enter the command SHOW DEVICE device-name to determine whether the CD drive is already mounted. For example: $ SHOW DEVICE DKA400: b. If it is not mounted, enter the appropriate MOUNT command to mount the CD (omit the /FOREIGN qualifier). c. To obtain the save-set name, use a DIRECTORY command: $ DIRECTORY DKA400:[COBOL02*.KIT]*.A option-list The word OPTIONS followed by one or more of the option designators A, G, L, N, R, as shown in Table 2-1. 2-2 Installing Compaq COBOL Table_2-1_Installation_Option_Designators__________________ Option_Name_____________Description________________________ A Auto_answer 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). G Get saveset Copies kit save set(s) to G de- device:[directory]. Specifying a vice:[directory] fast system storage device could speed up installations, if you install from there. Or, this could be a group distribution resource. L File Log Logs all activity to the terminal during installation. N Display or Indicates that you want to see the Print the installation question on release Release Notes 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 may omit the N option. (The Compaq COBOL Release Notes will be available regardless because VMSINSTAL copies them to the SYS$HELP directory.) R Alternate Root Lets you install Compaq COBOL to a system root other than that of the ________________________running_system.____________________ For detailed information on these software installation options, see the OpenVMS System Manager's Manual. If you Installing Compaq COBOL 2-3 specify more than one option, separate the options with commas. For example, use: OPTIONS A,N The following example invokes VMSINSTAL to install Compaq COBOL and shows the system response. This example uses the OPTIONS N release note option to access the release notes during the installation. $ @VMSINSTAL COBOL02nDKA400:[COBOL02n.KIT] OPTIONS N OpenVMS AXP Software Product Installation Procedure V7 It is dd-mmm-yyyy at hh:mm. Enter a question mark (?) at any time for help. If you do not supply either the product name or the device name, VMSINSTAL prompts you for this information later in the installation procedure. When you invoke VMSINSTAL, it checks whether you are logged in to a privileged account. Compaq recommends that you install software from the system manager's account with your default device and directory set to SYS$UPDATE. VMSINSTAL then checks to determine whether any users are logged in to the system. If users are logged in, VMSINSTAL asks whether you want to continue the installation: * Do you want to continue anyway [NO]? If you want to continue, enter yes. If you want to stop the installation, press Return. 3. Confirm system backup. * Are you satisfied with the backup of your system disk [YES]? If you are satisfied with the backup of your system disk, press Return. Otherwise, enter no to discontinue the installation. After you back up your system disk, you can restart the installation. 2-4 Installing Compaq COBOL If you omitted the device name on the VMSINSTAL command line, the following prompt appears: * Where will the distribution volumes be mounted: DKA400:[COBOL02n.KIT] If this prompt appears, enter the name of the distribution (media) device and directory that contains the Compaq COBOL kit (save set). For example, if the media is contained on a CD located on unit DKA400:, enter DKA400:[COBOL02n] in reply to this question (where n is the minor version number). 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 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 Compaq COBOL 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, enter no in response to the "Are you ready?" question. To abort the installation for other reasons, press Ctrl/Y. 4. Verify the product being installed. The following products will be processed: COBOL 2.n Beginning installation of COBOL 2.n at hh:mm %VMSINSTAL-I-RESTORE, Restoring product saveset A... The product name and version are displayed. The first save set (A) is restored to a subdirectory of SYS$UPDATE:. Installing Compaq COBOL 2-5 5. Select a release notes option. Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above * Select option [2]: Compaq strongly recommends that you read the release notes before completing the installation. If you specified options N when you invoked VMSINSTAL, you are now asked to choose one of the options for reviewing the release notes. All options copy the release notes to SYS$HELP. 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. Either supply the name of the print queue that you want to use or press Return to send the file to the default output print device. For example: * Queue name [SYS$PRINT]: CLUSTER_PRINT 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. If you select option 4, the installation procedure only copies the release notes to the SYS$HELP directory. Next, VMSINSTAL displays the following message: +-------------------------------------------------------------------+ | Installation Command Procedure for | | Compaq COBOL V2.n-vvvv Compiler. | +-------------------------------------------------------------------+ 2-6 Installing Compaq COBOL © Digital Equipment Corporation 1994, 1999. All rights reserved. . . (additional text eliminated for brevity; see the Sample Installation) . Installing Compaq COBOL and running the IVP requires approximately 5 to 10 minutes depending on your system configuration. The release notes are copied to the following file in the SYS$HELP directory (where n is the minor version number): SYS$HELP:COBOL02n.RELEASE_NOTES After the installation, you can enter the following command to view the location of the release notes through the Help facility: $ HELP COBOL RELEASE_NOTES ________________________ Note ________________________ The name of each release notes file (installed by VMSINSTAL) begins with the current product name and version number (for example, COBOL026). ______________________________________________________ 6. Respond to license registration queries. Compaq COBOL utilizes the OpenVMS License Management Facility (LMF). The installation procedure displays license information about Compaq COBOL. It asks whether you have registered and loaded your authorization key for each product. The following is an example of the information and the queries presented by the installation procedure: Product: COBOL Producer: DEC Version: 2.n Release Date: dd-mmm-yyyy * Does this product have an authorization key registered and loaded?: Installing Compaq COBOL 2-7 If you have not registered and loaded your PAK or PAKs, you must answer no to this question. You have to register and load your PAK to successfully complete the installation (see Section 1.2). If you have not done so, you must stop the installation, register and load your PAK, and then restart the installation. 7. Install the REFORMAT utility. Depending on your use of Compaq COBOL, you may want to install the optional REFORMAT utility. The ANSI/Terminal-Format REFORMAT utility may optionally be installed. * Do you want the REFORMAT utility installed [YES]? 8. Respond to the message file query. This query enables you to edit the Compaq COBOL message file (COBOL$MSG.MSG). Customized messages are often desirable for international users. If you plan to edit the message file, type yes and press Return. If you do not want to edit the message file, press Return. For more information, see Section 3.2. * Do you want to save the COBOL message file for modification [NO]? 9. Choose the Installation Verification Procedure (IVP) option. The installation procedure now asks if you want to run the IVP. The IVP for Compaq COBOL checks to be sure that the installation is successful. It is strongly recommended that you run the IVP. * Do you want to run the IVP after the installation [YES]? After Compaq COBOL 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 Compaq COBOL. 10.Read informational messages. At this point, the installation procedure displays informational messages that report on the progress of the installation. If the installation procedure has been successful up to this point, VMSINSTAL moves the new or 2-8 Installing Compaq COBOL modified files to their target directories, updates help files, and updates DCL tables, if necessary. The new and modified files consist of the following: [SYSEXE]COBOL.EXE [SYSEXE]REFORMAT.EXE [SYSMSG]COBOL$MSG.EXE [SYSUPD]COBOL$MSG.MSG [SYSHLP]COBOL02n.RELEASE_NOTES [SYSHLP]COBOL02n_RELEASE_NOTES.PS [SYSLIB]DCLTABLES.EXE [SYSTEST.COBOL]COBOL$IVP.COM The SYS$HELP:HELPLIB.HLB and SYS$LIBRARY:DCLTABLES.EXE files are updated to include the new versions of the Compaq COBOL help text and the COBOL command-line definition. 11.Purge files. * Do you want to purge files replaced by this installation [YES]? The directories SYS$HELP, SYS$LIBRARY, SYS$MESSAGE, SYS$SYSTEM, and SYS$TEST may contain previous versions of Compaq COBOL files. These files are replaced during the installation with new files, but the old files are not automatically purged. Purging is recommended. In response to the purging prompt, press Return or enter yes to purge the files now, or enter no to keep them. The end of the installation is indicated by the following message: %VMSINSTAL-I-MOVEFILES, files will now be moved to their target directories... 12.Observe the Installation Verification Procedure (IVP). If you chose to run the IVP (Step 9), VMSINSTAL now invokes the IVP to verify that Compaq COBOL was installed successfully. If Compaq COBOL was installed successfully, the IVP displays the following: Successful test of Compaq COBOL V2.n-vvvv completed at hh:mm Installing Compaq COBOL 2-9 13.End the installation procedure. Installation of COBOL V2.n completed at hh:mm VMSINSTAL procedure done at hh:mm Depending on whether you specified parameters on the VMSINSTAL command line, the * Products: prompt or the DCL prompt ($) may appear. If the * Products: prompt appears, you can return to the DCL prompt ($) by pressing Ctrl/Z. VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the installation account (such as SYSTEM) and you want to restore these symbols, you should log out and log in again. 2.2 Run-Time Library Installation Procedure The latest features and bug fixes incorporated in the RTL are documented in the SPD and Release Notes. The RTL save set is included in the kit. If you choose to install the RTL, you may do this with the following procedure. 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 to DCL level. To retry the installation procedure after pressing Ctrl/Y, proceed from Step 2. When the system prompts you with a question during the installation procedure, the default answer is often listed in brackets ([]). To install the Compaq COBOL Run-time Library, perform the following steps: 1. Log in to a privileged account and set your default device and directory to SYS$UPDATE: 2-10 Installing Compaq COBOL Username: SYSTEM Password: $ SET DEFAULT SYS$UPDATE 2. Invoke VMSINSTAL: @VMSINSTAL saveset-name device-name option-list VMSINSTAL is in the SYS$UPDATE directory. The element that you specify when you invoke the VMSINSTAL command procedure is as follows: saveset-name The installation name for the component. For the Compaq COBOL Run-Time Library, use the following installation name: COBOLRTL02n n represents the minor (point) release number for Compaq COBOL. For example, use COBOLRTL026 for Version 2.6. To obtain the directory location of the Compaq COBOL RTL save set on the CD, refer to the OpenVMS Alpha Layered Products Compact Disc User's Guide that accompanies the CD distribution kit. Refer to Section A.2, RTL Installation for a complete sample RTL installation. Installing Compaq COBOL 2-11 3 _________________________________________________________________ After Installation After Compaq COBOL is installed, it can be invoked by all users with the COBOL command. The installation procedure modifies the DCL command table so that the COBOL command is recognized and processed. However, the previous command table is still in effect for those users who are currently logged in. All logged-in users who want to use the COBOL command must log out and log in again, or use the following DCL command: $ SET COMMAND /TABLE=SYS$LIBRARY:DCLTABLES The following tasks can be performed after Compaq COBOL is installed: o Running the Installation Verification Procedure separately o Customizing the Compaq COBOL messages o Making Compaq COBOL usable on a VMScluster o Setting user account privileges o Installing Compaq COBOL as a shared image 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, use the following command procedure: $ @SYS$COMMON:[SYSTEST.COBOL]COBOL$IVP.COM After Installation 3-1 3.2 Customizing Compaq COBOL Error Messages If you choose to customize the Compaq COBOL message file, the installation procedure copies the Compaq COBOL message file COBOL$MSG.MSG into the system directory [SYSUPD]. After the file is copied to the system directory, you can edit COBOL$MSG.MSG to customize the error messages that users receive when using Compaq COBOL. Customized messages are often desirable for international users. You must install Compaq COBOL before editing the message file. If you install Compaq COBOL after editing COBOL$MSG.MSG, the software installation will supersede the revised message file in the [SYSMSG] directory. Also, you must have the OpenVMS Message utility installed on your system before editing COBOL$MSG.MSG. The edited version of COBOL$MSG.MSG must be processed through the Message utility before the file can be accessed by Compaq COBOL. The following steps explain how to edit the Compaq COBOL messages and install the customized message file on your system: 1. Run the Compaq COBOL installation procedure and answer yes to the question "Do you want to save the COBOL message file for modification." The installation procedure copies the message file, COBOL$MSG.MSG, into the system directory [SYSUPD]. 2. Edit the message file. Each error message appears on a separate line and is enclosed in angle brackets (< >). You can edit the text portion of the error messages, but for Compaq COBOL to correctly identify the errors, you must not change the following: o The 3- to 9-character mnemonic that appears in the first column o The sequence in which the error messages appear in the file o The severity level of the error message o The number, type, and order of the formatted ASCII output (FAO) arguments that appear in the message 3. Run the OpenVMS Message utility. 3-2 After Installation To translate the new message text into a file that Compaq COBOL can access, run the text file through the Message utility by entering the following command: $ MESSAGE COBOL$MSG The Message utility creates the object module COBOL$MSG.OBJ. 4. Enter the LINK command with the /SHARE qualifier to create the shareable image COBOL$MSG.EXE: $ LINK/SHARE COBOL$MSG 5. Install COBOL$MSG.EXE in the system directory [SYSMSG]: $ COPY COBOL$MSG.EXE SYS$COMMON:[SYSMSG]/PROT=W:RE 6. If Compaq COBOL is installed as a known image, you must reinstall COBOL$MSG.EXE by entering the following command: $ INSTALL REPLACE SYS$MESSAGE:COBOL$MSG Compaq COBOL will now generate your customized error messages. 3.3 Making Compaq COBOL Usable on a VMScluster If you want to run Compaq COBOL on multiple nodes of a VMScluster, first check to see that you have the appropriate software license (see Section 1.2). Then, perform the following steps after you install Compaq COBOL: 1. Issue the LICENSE LOAD command to activate the license on each node in the VMScluster on which Compaq COBOL is to be executed. 2. Use the OpenVMS System Management utility (SYSMAN) to execute a set of commands on all cluster nodes, whether or not the nodes are licensed to use Compaq COBOL; failure to do so may cause unexpected errors for users. After Installation 3-3 ________________________ Note ________________________ If you are using a mixed-architecture (VAX and Alpha) heterogeneous cluster, before executing these commands, make sure the appropriate logical names have been set to define the scope of the SYSMAN DO commands. For more information, see the OpenVMS system management documentation. ______________________________________________________ While logged in as SYSTEM, or as another user name that has the SETPRV privilege or the CMKRNL and SYSPRV privileges, use the SYSMAN utility to update the version of DCLTABLES.EXE available, as follows: $ RUN SYS$SYSTEM:SYSMAN SYSMAN> SET ENVIRONMENT/CLUSTER %SYSMAN-I-ENV, current command environment: Clusterwide on local cluster Username SYSTEM will be used on nonlocal nodes SYSMAN> DO INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE %SYSMAN-I-OUTPUT, command execution on node NODE1 %SYSMAN-I-OUTPUT, command execution on node NODE2 The SYSMAN utility will cause each DO command to be executed on all nodes of the local cluster. 3. If Compaq COBOL is installed as a known image, then also do the following: SYSMAN> DO INSTALL REPLACE SYS$SYSTEM:COBOL.EXE %SYSMAN-I-OUTPUT, command execution on node NODE1 %SYSMAN-I-OUTPUT, command execution on node NODE2 4. If the Compaq COBOL messages file is installed as a known image, then also do the following: SYSMAN> DO INSTALL REPLACE SYS$MESSAGE:COBOL$MSG.EXE %SYSMAN-I-OUTPUT, command execution on node NODE1 %SYSMAN-I-OUTPUT, command execution on node NODE2 5. If the Compaq COBOL RTL installation was performed, then complete the following steps: SYSMAN> DO INSTALL REPLACE SYS$LIBRARY:DEC$COBRTL.EXE SYSMAN> DO INSTALL REPLACE SYS$LIBRARY:LIBOTS2.EXE 3-4 After Installation 6. Finally, exit from SYSMAN. SYSMAN> EXIT $ 3.4 User Account Privileges To use Compaq COBOL, each user account must have at least TMPMBX and NETMBX privileges. Use the OpenVMS Authorize utility to determine whether users have the privileges they require. 3.5 Installing Compaq COBOL as a Shared Image If you expect Compaq COBOL 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 Compaq COBOL as a shared image on a system that is currently running, use the OpenVMS Install utility (INSTALL). It is recommended that you install Compaq COBOL 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. Before you install Compaq COBOL as a shared image, do the following: 1. Determine the number of available (free) global pagelets and global sections on your system and the number of each needed to install and run Compaq COBOL (see Section 1.6.1). 2. If necessary, increase the current number of global pagelets and global sections parameters (see Section 1.6.2). Once you have reset the system parameter values and they have taken effect, invoke the OpenVMS Install utility from a privileged account and install Compaq COBOL as a shared image: $ INSTALL INSTALL> ADD SYS$SYSTEM:COBOL.EXE /OPEN/SHARED/HEADER_RESIDENT INSTALL> EXIT Add the following lines to the appropriate system startup command file so that Compaq COBOL is available as a shared image each time the system is started: $ INSTALL ADD SYS$SYSTEM:COBOL.EXE/OPEN/SHARED/HEADER_RESIDENT EXIT The default operating system startup command file, for example, is SYS$MANAGER:SYSTARTUP_VMS.COM (previously named SYSTARTUP_V5.COM). If your site has modularized the 3-5 After Installation system startup procedure using multiple command files, add the lines to the correct file. To install the message file, use the following commands: $ INSTALL INSTALL> ADD SYS$MESSAGE:COBOL$MSG.EXE INSTALL> EXIT When you install Compaq COBOL as a shared image, you need to increase the global pagelets and global sections parameters (see Section 1.6.2). After Installation 3-6 A _________________________________________________________________ Sample Installations This appendix contains two samples: the Compaq COBOL compiler installation and an installation of the RTL. The compiler installation was run on a system that had no previous version of Compaq COBOL installed. (Depending on which layered products you have on your system, you might see additional messages and questions when you perform your installation.) The sample compiler installation assumes that DECnet has been shut down, that no users are logged on to your system, and that OPTIONS N is specified to print the release notes. The Installation Verification Procedure (IVP) runs at the end of the compiler installation. A.1 Compiler Installation Example A-1 shows a sample installation and verification of Compaq COBOL Version 2.6. Example A-1 Sample Compaq COBOL Installation and IVP $ @vmsinstal cobol026 DKA400:[COBOL026.KIT] options n OpenVMS AXP Software Product Installation Procedure V7.1 It is 30-MAY-1999 at 14:41. (continued on next page) Sample Installations A-1 Example A-1 (Cont.) Sample Compaq COBOL Installation and IVP 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: DCE$RPCD DCOM$RPCSS UCX$PORTM * Do you want to continue anyway [NO]? y * Are you satisfied with the backup of your system disk [YES]? The following products will be processed: COBOL V2.6 Beginning installation of COBOL V2.6 at 14:41 %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 * Do you want to continue the installation [NO]? y %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. +-------------------------------------------------------------------+ | Installation Command Procedure for | | Compaq COBOL V2.6-1060 Compiler. | +-------------------------------------------------------------------+ © Digital Equipment Corporation 1994, 1999. 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. (continued on next page) A-2 Sample Installations Example A-1 (Cont.) Sample Compaq COBOL Installation and IVP Installing Compaq COBOL and running the IVP requires approximately 5 to 10 minutes depending on your system configuration. Product: COBOL Producer: DEC Version: 2.6 Release Date: 07-MAY-1999 * Does this product have an authorization key registered and loaded? y The ANSI/Terminal-Format REFORMAT utility may optionally be installed. * Do you want the REFORMAT utility installed [YES]? * Do you want to save the COBOL message file for modification [NO]? * Do you want to run the IVP after the installation [YES]? This installation procedure creates a new version of, or updates some or all of the following files: [SYSEXE]COBOL.EXE [SYSEXE]REFORMAT.EXE [SYSMSG]COBOL$MSG.EXE [SYSUPD]COBOL$MSG.MSG [SYSHLP]COBOL026.RELEASE_NOTES [SYSHLP]COBOL026_RELEASE_NOTES.PS [SYSLIB]DCLTABLES.EXE [SYSTEST.COBOL]COBOL$IVP.COM * Do you want to purge files replaced by this installation [YES]? No more questions will be asked during this installation. %VMSINSTAL-I-RESTORE, Restoring product save set B ... To invoke the IVP, enter @SYS$COMMON:[SYSTEST.COBOL]COBOL$IVP.COM %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Start of Compaq COBOL Installation Verification Procedure © Digital Equipment Corporation 1994, 1999. All rights reserved. (continued on next page) Sample Installations A-3 Example A-1 (Cont.) Sample Compaq COBOL Installation and IVP 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. Successful test of Compaq COBOL V2.6-1060 Installation of COBOL V2.6 completed at 14:43 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]COBOL026.VMI_DATA VMSINSTAL procedure done at 14:43 $ lo INSTALL logged out at 30-MAY-1999 14:43:49.59 A.2 RTL Installation Example A-2 shows a sample installation of the Compaq COBOL Run-Time Library. Example A-2 Sample Compaq COBOL RTL Installation $ @vmsinstal cobolrtl026 DKA400:[COBOL026.KIT] OpenVMS AXP Software Product Installation Procedure V7.2 It is 16-MAY-1999 at 11:38. (continued on next page) A-4 Sample Installations Example A-2 (Cont.) Sample Compaq COBOL RTL Installation Enter a question mark (?) at any time for help. %VMSINSTAL-W-ACTIVE, The following processes are still active: TCPIP$FTP TCPIP$FTPC00001 * Do you want to continue anyway [NO]? y * Are you satisfied with the backup of your system disk [YES]? The following products will be processed: COBOLRTL V2.6 Beginning installation of COBOLRTL V2.6 at 11:38 %VMSINSTAL-I-RESTORE, Restoring product save set A ... +-----------------------------------------------------+ | Installation Command Procedure for | | Compaq COBOL V2.6-470 RTL. | +-----------------------------------------------------+ © Digital Equipment Corporation 1994, 1999. 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. Installing Compaq COBOL RTL requires approximately 1 to 5 minutes depending on your system configuration. No more questions will be asked during this installation. %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of COBOLRTL V2.6 completed at 11:38 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY (continued on next page) Sample Installations A-5 Example A-2 (Cont.) Sample Compaq COBOL RTL Installation Creating installation data file: VMI$ROOT:[SYSUPD]COBOLRTL026.VMI_DATA VMSINSTAL procedure done at 11:39 $ A-6 Sample Installations B _________________________________________________________________ Recovering from Errors This appendix provides information to help you with failures or errors that might occur during product installation or product use. B.1 Failures During Compaq COBOL 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. If errors occur during the installation itself or when the Installation Verification Procedure (IVP) is running, VMSINSTAL displays failure messages. If the installation fails, you see the following message: %VMSINSTAL-E-INSFAIL, The installation of Compaq COBOL Version 2.6 has failed. If the IVP fails, you see these messages: The Compaq COBOL Version 2.6 Installation Verification Procedure failed. %VMSINSTAL-E-IVPFAIL, The IVP for Compaq COBOL Version 2.6 has failed. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o A prerequisite software version is incorrect. o Quotas necessary for successful installation are insufficient. o System parameter values for successful installation are insufficient. Recovering from Errors B-1 o The OpenVMS Help library is currently in use. o The product license has not been registered and loaded. For descriptions of the error messages generated by these conditions, see the OpenVMS documentation on system messages, recovery procedures, and OpenVMS software installation. If you are notified that any of these conditions exist, you should take the appropriate action as described in the message. For information on installation requirements, see Chapter 1. B.2 Problems During Compaq COBOL Use This section describes problems that might occur when you use Compaq COBOL. B.2.1 Run-Time Library Mismatch The system issues a severe error message if there is a mismatch in RTL versions between the compiled program and the RTL installed on the system where the program is run. In this situation, the program exits after the message is issued. B.2.2 Other Problems If you encounter a problem while using Compaq COBOL, see the section on Troubleshooting Tips in the Release Notes. If the problem is unresolved, report it to Compaq. If you have a Software Product Services Support Agreement, contact your Compaq Customer Support Center (CSC), either by telephone or using the electronic means provided with your support agreement (such as DSNlink). The CSC provides telephone support for high-level advisory and remedial assistance. When you initially contact the CSC, please indicate the following: o The name (OpenVMS Alpha) and the version number of the operating system you are using o The product name (Compaq COBOL) and the version number of Compaq COBOL you are using o The hardware system you are using, such as a model number B-2 Recovering from Errors o A very brief description of the problem (one sentence if possible) o How critical the problem is When you submit information electronically or are speaking on the phone to the appropriate Compaq COBOL support specialist, you can provide more detailed information. The information should include the specific commands used to compile and link the program, the error messages displayed, and relevant detailed information (possibly including source program listings). Please attempt to narrow the cause of the problem to a specific module or lines of code. CSC personnel may ask for additional information, such as listings of any command files, INCLUDE and COPY files, relevant data files, and so forth. If the program is longer than 50 lines, submit a copy of it electronically or provide machine-readable media (diskette or magnetic tape). Recovering from Errors B-3