Compaq COBOL for_OpenVMS_Alpha_Systems_____________________ Installation Guide Order Number: AA-PXE7K-TE November 2002 This guide describes how to install Compaq COBOL on an Alpha system running the OpenVMS Alpha operating system. This guide applies to Compaq COBOL Version 2.8 and any maintenance updates for that version. Revision/Update Information: This manual super- sedes the Version 2.7 Compaq COBOL for OpenVMS Alpha Systems Installation Guide. Operating System & Version: OpenVMS Alpha Version 6.2 or higher. Future releases may require higher versions. Software Version: Compaq COBOL for OpenVMS Alpha Version 2.8 Compaq Computer Corporation Houston, Texas __________________________________________________________ © 2002 Compaq Information Technologies Group, L.P. COMPAQ, the Compaq logo, OpenVMS, POLYCENTER, Tru64, VAX, and VMS are trademarks of Compaq Information Technologies Group, L.P. in the U.S. and/or other countries. All other product names mentioned herein may be trademarks of their respective companies. Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. None of Compaq, Hewlett-Packard Company ("HP") or any other direct or indirect subsidiary of HP shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq or HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty. ZK6295 This document was prepared using DECdocument, Version 3.3-1b. ________________________________________________________________ Contents Preface.................................................. v 1 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-4 1.5.2 System Parameters........................ 1-4 1.5.3 Disk Space............................... 1-5 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-6 1.6.2 Changing System Parameter Values with AUTOGEN.................................. 1-6 2 Installing Compaq COBOL 3 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 an OpenVMS Cluster System............................... 3-3 3.4 User Account Privileges...................... 3-5 3.5 Installing Compaq COBOL as a Shared Image.... 3-5 iii 3.6 REFORMAT Utility............................. 3-6 A Sample Installation A.1 Installation of the Run-Time Library and the Compiler on OpenVMS Alpha ................... A-1 A.2 Installation Verification (IVP) Run Separately................................... A-3 A.3 Removal (Deinstallation) of the Run-Time Library and the COBOL Compiler............... A-4 B Recovering from Errors B.1 Failures During Compaq COBOL and Run-Time Library Installations........................ B-1 B.2 Problems During Compaq COBOL Use............. B-3 B.2.1 Run-Time Library Mismatch................ B-4 B.2.2 Other Problems........................... B-4 Tables 1-1 Minimum Required System Parameter Values................................... 1-4 1-2 Disk Space Requirements.................. 1-5 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 Compaq COBOL Reference Manual (revised for this release) o Compaq COBOL User Manual (revised for this release) o Compaq COBOL DBMS Database Programming (revised for this release) o Compaq COBOL Release Notes (see Section 1.1) o Compaq COBOL Help o Read Before Installing or Using Compaq COBOL Version 2.8 for OpenVMS Alpha Systems cover letter You may also find the following documentation useful: 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. $ SET DEFAULT SYS$UPDATE In interactive examples, 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.8, you type ______________________________COBOL028.___________________ vi References DIGITAL COBOL has been 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 for Alpha operating system. Tru64 UNIX was formerly called DIGITAL UNIX or DEC OSF/1. 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 Visit the following World Wide Web address for information about how to order additional documentation: http://www.openvms.compaq.com/doc/ Reader's Comments Compaq welcomes your comments on this manual. Please send comments to either of the following addresses: Internet openvmsdoc@hp.com Mail Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698 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 product. vii 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.8 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. For information about accessing these Release Notes before installing Compaq COBOL, see Chapter 2, step 4. The installed Release Notes for Compaq COBOL will be in the following file: SYS$HELP:COBOL028.RELEASE_NOTES Preparing for Compaq COBOL Installation 1-1 Preparing for Compaq COBOL Installation 1.2 Registering Your Software License 1.2 Registering Your Software License Before you install and run Compaq COBOL Version 2.8 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 your 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. 1-2 Preparing for Compaq COBOL Installation Preparing for Compaq COBOL Installation 1.2 Registering Your Software License 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. 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 o Oracle DBMS o Compaq 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. Preparing for Compaq COBOL Installation 1-3 Preparing for Compaq COBOL Installation 1.5 Installation Procedure Requirements 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 BYPASS o CMKRNL o SYSLCK o SYSPRV 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-4 Preparing for Compaq COBOL Installation Preparing for Compaq COBOL Installation 1.5 Installation Procedure Requirements 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_____26,000________________22,000_____________ 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 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. Preparing for Compaq COBOL Installation 1-5 Preparing for Compaq COBOL Installation 1.6 Standard System Maintenance Procedures 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): $ 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 1-6 Preparing for Compaq COBOL Installation Preparing for Compaq COBOL Installation 1.6 Standard System Maintenance Procedures 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. ________________________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 will take approximately 5 to 10 minutes, depending on your system configuration. If you encounter any failures during installation, see Appendix B. As of Version 2.7, Compaq COBOL for OpenVMS Alpha is in- stalled with the POLYCENTER Software Installation utility (PCSI) instead of VMSINSTAL so that its components will be registered in the PCSI Registry on your system. When the PCSI PRODUCT command is used for later installations of kits, such as for OpenVMS Alpha, which contain components of the Compaq COBOL product (for example, the COBRTL), the PRODUCT command will check in the PCSI Registry to see whether the registered version has a higher version number than the one about to be installed. If so, the PRODUCT command will bypass the installation of that component. Compaq COBOL for OpenVMS Alpha is packaged in three PCSI kits: o A kit for the compiler for any OpenVMS Alpha system Version 6.2 or higher: [COBOL028.KIT]DEC-AXPVMS-COBOL-V0208-1286-1.PCSI o A kit for the run-time library (RTL) for OpenVMS Alpha systems Version 6.2 through Version 7.1-1H2: [COBOL028.KIT]DEC-AXPVMS-COBRTL-V0208-670A-1.PCSI o A kit for the RTL for OpenVMS Alpha systems Version 7.1-2 and higher: [COBOL028.KIT]DEC-AXPVMS-COBRTL-V0208-670B-1.PCSI Installing Compaq COBOL 2-1 Installing Compaq COBOL Thus, you will install two kits: the appropriate RTL kit for your operating system, and then the compiler kit. The RTL kit should be installed first. (Users who install only the RTL will need to install only the RTL kit specified for their operating system.) 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 5. When the system prompts you with a question during the installation procedure, the default answer is listed in brackets ([]). Step-by-Step Instructions 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 Your account must have the BYPASS, CMKRNL, SYSLCK, and SYSPRV privileges enabled. If your process has the SETPRV privilege, you can enable these privileges by typing the following command: $ SET PROCESS/PRIVILEGE=(BYPASS,CMKRNL,SYSLCK,SYSPRV) To check whether you have these privileges enabled, type the following command: $ SHOW PROCESS/PRIVILEGES 2. Ascertain that the license registration PAK is installed on your system. Compaq COBOL utilizes the OpenVMS License Management Facility (LMF). If you have not registered and loaded your PAK or PAKs, you must do so to successfully complete the installation (see Section 1.2). 3. Locate Compaq COBOL on the media CD-ROM. 2-2 Installing Compaq COBOL Installing Compaq COBOL To obtain the kit directory location of the Compaq COBOL distribution files on the appropriate OpenVMS Alpha Software Product Library CD-ROM (media CD-ROM), do one of the following: o Use the CDMENU utility provided on the media CD-ROM. o View the CD-ROM master index file on the media CD- ROM. o Contact the appropriate system manager. For information about using the CDMENU utility and the CD-ROM files, see the Software Product Library CD- ROM User's Guide, which accompanies the media CD-ROM distribution kit. This user guide and the CD-ROM master index file are provided as online files in the [README] directory on the first media CD-ROM. To determine whether the appropriate media CD-ROM is already mounted on your system, type the following command: $ SHOW DEVICE DKA400 ________________________Note ________________________ DKA400 is the device name used in examples in this document to show where the CD-ROM has been mounted. You need to determine the name of the CD-ROM drive on your system. _____________________________________________________ If the media CD-ROM is not mounted, either contact the appropriate system manager or insert the appropriate media CD-ROM (write down the volume label) into an available CD-ROM drive. Type the appropriate MOUNT command (omitting the /FOREIGN qualifier), such as the following: $ MOUNT DKA400 label Where label is the volume label of that media CD-ROM. Installing Compaq COBOL 2-3 Installing Compaq COBOL To check that you have located the correct CD-ROM device and directory, use the following DIRECTORY command: $ DIRECTORY DKA400:[directory]*.PCSI Where directory is [COBOL028]. 4. Invoke PCSI and extract the Release Notes so that you can read them before completing the installation. To extract the online Release Notes, type the following command: $ PRODUCT EXTRACT RELEASE_NOTES COBOL/FILE=SYS$HELP:COBOL028.RELEASE_NOTES - $_/SOURCE=device:[directory] This command will extract the Release Notes into SYS$HELP. Read the Release Notes before continuing with the installation. 5. Use PCSI to install the Run-Time Library, COBRTL. Install the COBRTL before installing the compiler. If you are running OpenVMS Alpha Version 6.2 through Version 7.1-1H2, do the following: First, remove any older version of COBRTL with the following command: $ PRODUCT REMOVE COBRTL If COBRTL has not been previously installed via PCSI, you see the following message: %PCSIUI-I-NOMATCH, no products found matching: COBRTL If you see the following question, answer NO, as follows: %PCSI-E-EXEFAIL, execute statement failed; status returned from DCL follows -SYSTEM-F-ABORT, abort %PCSI-E-OPFAILED, operation failed Terminating is strongly recommended. Do you want to terminate? [YES] NO 2-4 Installing Compaq COBOL Installing Compaq COBOL Second, enter the following command to install COBRTL: $ PRODUCT INSTALL COBRTL/VERSION=2.8-670A - $_/SOURCE=device:[directory] If you get the following question for either DEC$COBRTL or LIBOTS2, answer NO. %PCSI-E-FAILCONF, failed to resolve conflicting requirements Terminating is strongly recommended. Do you want to terminate? [YES] NO If you are running OpenVMS Alpha Version 7.1-2 or higher, do the following: $ PRODUCT INSTALL COBRTL/VERSION=2.8-670B - $_/SOURCE=device:[directory] If the system disk for this installation is shared in your cluster, do the following on the other nodes that share the system disk: $ INSTALL REPLACE SYS$LIBRARY:DEC$COBRTL.EXE $ INSTALL REPLACE SYS$LIBRARY:LIBOTS2.EXE 6. Use PCSI to install the COBOL compiler. Use this command: $ PRODUCT INSTALL COBOL/VERSION=2.8-1286 - $_/SOURCE=device:[directory] If the system disk for this installation is shared in your cluster, do the following on the other nodes that share the system disk: $ INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE Installing Compaq COBOL 2-5 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 or the newly updated version of 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 an OpenVMS Cluster System o Setting user account privileges o Installing Compaq COBOL as a shared image o Running the REFORMAT utility 3.1 Running the Installation Verification Procedure Separately The Installation Verification Procedure (IVP) runs automatically during installation of the COBOL compiler. It requires the installation of the COBOL compiler on your system. If you want to run the IVP separately to ensure the integrity of installed files should system problems occur, in a privileged account use the following command procedure: After Installation 3-1 After Installation 3.1 Running the Installation Verification Procedure Separately $ @SYS$COMMON:[SYSTEST]COBOL$IVP.COM 3.2 Customizing Compaq COBOL Error Messages The PCSI installation automatically copies the Compaq COBOL message file, COBOL$MSG.MSG, into the system directory [SYSUPD]. 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. 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 2. Run the OpenVMS Message utility. 3-2 After Installation After Installation 3.2 Customizing Compaq COBOL Error Messages 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. 3. Enter the LINK command with the /SHARE qualifier to create the shareable image COBOL$MSG.EXE: $ LINK/SHARE COBOL$MSG 4. Install COBOL$MSG.EXE in the system directory [SYSMSG]: $ COPY COBOL$MSG.EXE SYS$COMMON:[SYSMSG]/PROT=W:RE 5. 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 an OpenVMS Cluster System 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. ________________________Note ________________________ If you are using a mixed-architecture (VAX and Alpha) heterogeneous cluster, before executing these commands, make sure the appropriate logical names After Installation 3-3 After Installation 3.3 Making Compaq COBOL Usable on an OpenVMS Cluster System 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-I-OUTPUT, command execution on node NODE1 %SYSMAN-I-OUTPUT, command execution on node NODE2 SYSMAN> DO INSTALL REPLACE SYS$LIBRARY:LIBOTS2.EXE %SYSMAN-I-OUTPUT, command execution on node NODE1 %SYSMAN-I-OUTPUT, command execution on node NODE2 3-4 After Installation After Installation 3.3 Making Compaq COBOL Usable on an OpenVMS Cluster System 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. Invoke the OpenVMS Install utility from a privileged account and install Compaq COBOL as a shared image: $ INSTALL ADD SYS$SYSTEM:COBOL.EXE /OPEN/SHARED/HEADER_RESIDENT Add the following line 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 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 system startup procedure using multiple command files, add the lines to the correct file. To install the message file, use the following commands: $ INSTALL ADD SYS$MESSAGE:COBOL$MSG.EXE After Installation 3-5 After Installation 3.6 REFORMAT Utility 3.6 REFORMAT Utility The PCSI installation automatically includes installation of REFORMAT.EXE, the REFORMAT utility. It is ready to run. 3-6 After Installation A ________________________________________________________________ Sample Installation This appendix contains a sample log of an installation on the OpenVMS Alpha operating system, Version 7.1-2 and higher; a sample log of an installation verification (IVP); and a sample log of a deinstallation of the RTL and the compiler. A.1 Installation of the Run-Time Library and the Compiler on OpenVMS Alpha $ PRODUCT INSTALL COBRTL/VERSION=2.8-670B/SOURCE=SYS$UPDATE: The following product has been selected: DEC AXPVMS COBRTL V2.8-670B Layered Product Do you want to continue? [YES] Configuration phase starting ... You will be asked to choose options, if any, for each selected product and for any products that may be installed to satisfy software dependency requirements. DEC AXPVMS COBRTL V2.8-670B: COBRTL for Compaq COBOL for OpenVMS Alpha Systems Copyright 2002 by Compaq Computer Corporation. This software is the product of Compaq Computer Corporation. No PAKs are used by this COBRTL product. Do you want the defaults for all options? [YES] Do you want to review the options? [NO] Execution phase starting ... The following product will be installed to destination: DEC AXPVMS COBRTL V2.8-670B DISK$YYYYYYSYSDSK:[VMS$COMMON.] The following product will be removed from destination: DEC AXPVMS COBRTL V2.7-603B DISK$YYYYYYSYSDSK:[VMS$COMMON.] Portion done: 0%...30%...50%...70%...90%...100% Sample Installation A-1 Sample Installation A.1 Installation of the Run-Time Library and the Compiler on OpenVMS Alpha The following product has been installed: DEC AXPVMS COBRTL V2.8-670B Layered Product The following product has been removed: DEC AXPVMS COBRTL V2.7-603B Layered Product $ PRODUCT INSTALL COBOL /VERSION=2.8-1286/SOURCE=SYS$UPDATE: The following product has been selected: DEC AXPVMS COBOL V2.8-1286 Layered Product Do you want to continue? [YES] Configuration phase starting ... You will be asked to choose options, if any, for each selected product and for any products that may be installed to satisfy software dependency requirements. DEC AXPVMS COBOL V2.8-1286: Compaq COBOL for OpenVMS Alpha Systems Copyright 2002 by Compaq Computer Corporation. This software is the product of Compaq Computer Corporation. A valid Product Authorization Key (PAK) is required. Do you want the defaults for all options? [YES] Do you want to review the options? [NO] Execution phase starting ... The following product will be installed to destination: DEC AXPVMS COBOL V2.8-1286 DISK$YYYYYYSYSDSK:[VMS$COMMON.] The following product will be removed from destination: DEC AXPVMS COBOL V2.7-1209 DISK$YYYYYYSYSDSK:[VMS$COMMON.] Portion done: 0%...70%...80%...90%...100% The following product has been installed: DEC AXPVMS COBOL V2.8-1286 Layered Product The following product has been removed: DEC AXPVMS COBOL V2.7-1209 Layered Product %PCSI-I-IVPEXECUTE, executing test procedure for DEC AXPVMS COBOL V2.8- 1286 ... %PCSI-I-IVPSUCCESS, test procedure completed successfully A-2 Sample Installation Sample Installation A.2 Installation Verification (IVP) Run Separately A.2 Installation Verification (IVP) Run Separately $ @SYS$TEST:COBOL$IVP.COM Copyright 2002 Compaq Computer Corporation COMPAQ Registered in U.S. Patent and Trademark Office. Confidential computer software. Valid license from Compaq required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Successful test of Compaq COBOL V2.8-1286 $ Sample Installation A-3 Sample Installation A.3 Removal (Deinstallation) of the Run-Time Library and the COBOL Compiler A.3 Removal (Deinstallation) of the Run-Time Library and the COBOL Compiler $ PRODUCT REMOVE COBRTL The following product has been selected: DEC AXPVMS COBRTL V2.8-670B Layered Product Do you want to continue? [YES] The following product will be removed from destination: DEC AXPVMS COBRTL V2.8-670B DISK$AFSCOBSYSDSK:[VMS$COMMON.] Portion done: 0%...10%...100% The following product has been removed: DEC AXPVMS COBRTL V2.8-670B Layered Product $ PRODUCT REMOVE COBOL The following product has been selected: DEC AXPVMS COBOL V2.8-1286 Layered Product Do you want to continue? [YES] The following product will be removed from destination: DEC AXPVMS COBOL V2.8-1286 DISK$AFSCOBSYSDSK:[VMS$COMMON.] Portion done: 0%...10%...20%...30%...40%...50%...60%...70%...100% The following product has been removed: DEC AXPVMS COBOL V2.8-1286 Layered Product A-4 Sample Installation 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 and Run-Time Library Installations If PCSI detects any problems during installation, it notifies you and asks if you want to continue the installation. The following PCSI messages are issued if the PCSI product kit is not found in the specified directory: $ PRODUCT INSTALL /SOURCE=device:[directory] %PCSIUI-I-NOMATCH, no products found matching: COBOL %PCSIUI-E-NOPROD, no products found on which to perform this operation %PCSIUI-E-ABORT, fatal error encountered - operation terminated The following PCSI and RMS messages are issued if the PCSI product kit is not found in the specified directory and you have defined the logical name PCSI$SOURCE: $ PRODUCT INSTALL /SOURCE=device:[directory] %PCSI-E-OPENIN, error opening PCSI$SOURCE:[SYSUPD]*-*-*-%%%%%-*-*.PCSI*; as input -RMS-F-DEV, error in device name or inappropriate device type for operation %PCSI-E-S_OPFAIL, operation failed %PCSIUI-E-ABORT, fatal error encountered - operation terminated The following PCSI messages are issued when the installa- tion and the IVP test procedure execute properly: Recovering from Errors B-1 Recovering from Errors B.1 Failures During Compaq COBOL and Run-Time Library Installations $ PRODUCT INSTALL /SOURCE=device:[directory] . . . The following product has been installed: DEC AXPVMS COBOL V2.8-1286 . . . %PCSI-I-EXETSTOK, end of test procedure; completed with no errors The following PCSI messages are issued when the COBOL installation fails only because the IVP test procedure fails. ________________________Note ________________________ This failure is in the IVP test procedure. After reporting the failure it asks you if you wish to terminate the installation. If you answer YES at this advanced stage (100%), the installation terminates quietly. The product has been installed on the system. _____________________________________________________ $ PRODUCT INSTALL /SOURCE=device:[directory] The PRODUCT INSTALL fails, with the following messages: Portion Done: 10%...30%...40%...70%...80%...90%...100% %PCSI-I-PRCOUTPUT, output from subprocess follows... %LICENSE-F-NOAUTH, DEC COBOL use is not authorized on this node -LICENSE-F-NOLICENSE, no license is active for this software product -LICENSE-I-SYSMGR, please see your system manager %SYSTEM-F-ABORT, abort The IVP test procedure fails, with the following messages: %PCSI-E-EXETSTFAIL, end of test procedure; completed with errors; status returned from DCL follows -SYSTEM-F-ABORT, abort %PCSI-E-OPFAILED, operation failed Terminating is strongly recommended. Do you want to terminate? [YES] y B-2 Recovering from Errors Recovering from Errors B.1 Failures During Compaq COBOL and Run-Time Library Installations The following PCSI messages are issued when the instal- lation fails and you ask PCSI to force completing the installation. In this case a PCSI "execute" statement failed. It is recommended that you terminate the installation in response to the question "Do you want to terminate?" If this message appears under the current setup, something has gone seriously wrong with the installation. Two possibilities are: o One or more necessary files are missing from the kit. o A delete of modules in the STARLET.OLB library has failed in the COBRTL installation, causing the succeeding PCSI update step to fail. If you answer YES or take the default on the question, the installation will be backed out if it has gone less than 100%, and you will see the $ system prompt on the screen. $ PRODUCT INSTALL COBRTL/SOURCE=device:[directory] %PCSI-I-PRCOUTPUT, output from subprocess follows... %SYSTEM-F-ABORT, abort Portion Done: 10% %PCSI-E-EXEFAIL, execute statement failed; status returned from DCL follows -SYSTEM-F-ABORT, abort %PCSI-E-OPFAILED, operation failed Terminating is strongly recommended. Do you want to terminate? [YES] n Portion Done: 30%...40%...70%...80%...90%...100% The following product has been installed: DEC AXPVMS COBRTL V2.8-603 The following product has been removed: DEC AXPVMS COBRTL V2.8-603 %PCSIUI-I-COMPWERR, operation completed after explicit continuation from errors B.2 Problems During Compaq COBOL Use This section describes problems that might occur when you use Compaq COBOL. Recovering from Errors B-3 Recovering from Errors B.2 Problems During Compaq COBOL Use 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 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. B-4 Recovering from Errors Recovering from Errors B.2 Problems During Compaq COBOL Use 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-5