DEC_COBOL___________________________________________ Installation Guide for OpenVMS Alpha Systems Order Number: AA-PXE7E-TE October 1996 This guide describes how to install DEC COBOL on an Alpha system running the OpenVMS Alpha operating system. This document applies to DEC COBOL Version 2.4 and any maintenance updates for that version. Revision/Update Information: This manual supersedes the Version 2.3 DEC COBOL Installation Guide for OpenVMS Alpha Operating System & Version: OpenVMS Alpha Version 6.1 or higher. Software Version: DEC COBOL Version 2.4 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ October 1996 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 authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1996. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: ACMSxp, Bookreader, CMS, DEC COBOL, DECdocument, DEC Fortran, DEC FUSE, DECladebug, DECnet, DEC OSF/1, DEC PASCAL, DECset, DECTPU, Digital, OpenVMS, PDP, Professional, VAX, VAX ADA, VAX BASIC, VAX C, VAX CDD, VAXcluster, VAX COBOL, VAX COBOL GENERATOR, VAX DOCUMENT, VAX MACRO, VAX RMS, VAX SCAN, VMS, VT, VT100, VT220, VT300, VT320, VT420, and the DIGITAL logo. The following are third-party trademarks: Display POSTSCRIPT and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated. Micro Focus is a registered trademark of Micro Focus Limited. Oracle Rdb, Oracle CODASYL DBMS, Oracle CDD/Repository, Oracle CDD/Administrator, Oracle RALLY, Oracle TRACE, Oracle Expert, Oracle InstantSQL, Oracle Graphical Schema Editor, Oracle RMU, Oracle RMUwin, Oracle TRACE Collector, Oracle SQL/Services, Oracle DBA Workcenter, and Oracle Module Language are trademarks of Oracle Corporation. OSF/1 and Motif are registered trademarks of the Open Software Foundation, Inc. Transarc and Encina are registered trademarks of Transarc Corporation. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. X/Open is a registered trademark of X/Open Company Ltd. 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 Preface................................................... v 1 Preparing for DEC 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 DEC 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 2 Installing DEC COBOL 2.1 Installation Procedure........................ 2-1 2.2 Run-Time Library Installation Procedure...... 2-10 3 After Installation 3.1 Running the Installation Verification Procedure Separately.......................... 3-1 3.2 Customizing DEC COBOL Error Messages.......... 3-2 3.3 Making DEC COBOL Usable on a VMScluster....... 3-3 3.4 User Account Privileges....................... 3-5 3.5 Installing DEC COBOL as a Shared Image........ 3-5 iii A Sample Installations A.1 Compiler Installation......................... A-1 A.2 RTL Installation.............................. A-3 B Files Installed on Your System C Recovering from Errors C.1 Failures During DEC COBOL Installation........ C-1 C.2 Failures During DEC COBOL Use................. C-2 Examples A-1 Sample DEC COBOL Installation and IVP..... A-1 A-2 Sample DEC COBOL RTL Installation......... A-3 Tables 1-1 Optional Software......................... 1-3 1-2 Minimum Required System Parameter Values.................................... 1-4 1-3 Disk Space Requirements................... 1-5 2-1 Installation Option Designators........... 2-3 B-1 Directories Containing DEC COBOL Installed Files .................................... B-1 iv _________________________________________________________________ Preface This guide describes how to install DEC 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 DEC COBOL for any other reason. Associated Documentation In addition to this guide, the DEC COBOL documentation set includes the following: o DEC COBOL Reference Manual o DEC COBOL User Manual o DEC COBOL DBMS Database Programming o DEC COBOL Release Notes (see Section 1.1) o DEC COBOL Help o Read Before Installing or Using DEC COBOL Version 2.4 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 v Conventions The following conventions are used in this guide: ___________________________________________________________ Convention____________________Meaning______________________ UPPERCASE Uppercase letters indicate the name of a command, a file, a parameter, a procedure, or a DEC COBOL utility. $ @SYS$UPDATE:VMSINSTAL In interactive examples, prompts or displayed text appear in a monospace font. User input appears in bold. $ 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.______ References to OpenVMS Alpha and Digital UNIX In this manual, every use of OpenVMS Alpha means the OpenVMS Alpha operating system and every use of Digital UNIX means the Digital UNIX operating system. Digital UNIX was formerly called 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. vi How To Order Additional Documentation Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825). Reader's Comments Digital 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@casdoc.enet.dec.com o Fax: 603-881-0120 Attn: Languages Documentation, ZKO2-3/K35 o A letter sent to the following address: Digital Equipment Corporation Languages Documentation, ZKO2-3/K35 110 Spit Brook Road Nashua, NH 03062-2698 USA vii 1 _________________________________________________________________ Preparing for DEC 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 Digital representative. Your distribution kit includes a letter titled Read Before Installing or Using DEC COBOL Version 2.4 for OpenVMS Alpha. The letter discusses important information that might not be included in this guide. You should read this letter now. 1.1 Reading the Online Release Notes DEC COBOL provides online release notes. Digital 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 DEC COBOL are in the following file: SYS$HELP:COBOL024.RELEASE_NOTES For information about installing these release notes before installing DEC COBOL, see Table 2-1, Installation Option Designators. You can use the following command to read the release notes after DEC COBOL is installed: $ HELP COBOL RELEASE_NOTES Preparing for DEC COBOL Installation 1-1 1.2 Registering Your Software License Before you install and run DEC COBOL Version 2.4 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 DEC 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 DEC COBOL, review the PAK status and install the PAKs for any prerequisite or optional software before you install DEC COBOL. If you are planning to the use the Oracle DBMS programming capability, you must purchase the DEC COBOL Oracle DBMS programming license option, which includes a license PAK for use of this option. See the DEC COBOL Software Product Description (SPD) for more information on the Oracle DBMS programming license option. You must register and load your license for DEC 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 DEC 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 DEC COBOL Installation For complete information on using LMF, see OpenVMS License Management Utility Manual. 1.3 Optional Software Table 1-1 lists optional software that you can use together with DEC COBOL. Table_1-1_Optional_Software________________________________ Oracle CDD/Repository Version 5.3 or higher Oracle DBMS Version 5.1 or higher DEC Language Sensitive Editor/Source Code Analyzer Version 4.0_or_higher______________________________________________ 1.4 Checks and Requirements for Installing DEC 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 DEC 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 DEC 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 DEC COBOL, you must be logged in to an account that has SETPRV or at least the following privileges: o CMKRNL o WORLD o SYSPRV Preparing for DEC COBOL Installation 1-3 Note that VMSINSTAL turns off BYPASS privilege at the start of the installation. Privileges required for product use are defined in Section 3.4. 1.5.2 System Parameters Table 1-2 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-2_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 DEC COBOL requirements for free disk storage space are different during installation and after installation. Table 1-3 summarizes the storage requirements. 1-4 Preparing for DEC COBOL Installation Table_1-3_Disk_Space_Requirements__________________________ Blocks During Blocks After Kit______________Installation__________Installation________ DEC_COBOL________18,000________________12,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 At the beginning of the installation, VMSINSTAL asks if you have backed up your system disk. Digital recommends that you do a system disk backup before installing any software. Use the backup procedures that are established at your site. For details 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 DEC 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 may use as an approximation of the number of global pagelets needed: $ DIR/SIZE SYS$LIBRARY:DCLTABLES.EXE Preparing for DEC COBOL Installation 1-5 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 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 1-6 Preparing for DEC COBOL Installation When you specify REBOOT, AUTOGEN performs an automatic system shutdown and then reboots the system. Any users logged on to the system are immediately disconnected during the shutdown. The automatic reboot puts the new parameter values into effect. 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 OpenVMS System Manager's Manual. Preparing for DEC COBOL Installation 1-7 2 _________________________________________________________________ Installing DEC 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 C. 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 DEC 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 2. Invoke VMSINSTAL: @VMSINSTAL saveset-name device-name option-list Installing DEC COBOL 2-1 VMSINSTAL is in the SYS$UPDATE directory. The elements that you specify when you invoke the VMSINSTAL command procedure are as follows: saveset-name The installation name for the component. For DEC COBOL, use the following installation name: COBOL02n n represents the minor (point) release number for DEC COBOL. For example, use COBOL024 for Version 2.4. To obtain the directory location of the DEC COBOL save set on the CD, refer to the OpenVMS Alpha Layered Products Compact Disc User's Guide that accompanies the CD distribution kit. Another method is to complete these steps before starting installation: a. Enter the following command to determine whether the CD drive is already mounted: $ 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 specifying the directory file from the previous command: $ DIRECTORY DKA400:[COBOL02n]*.A n represents the minor (point) release number for DEC COBOL. device-name The name of the device on which you plan to mount the media and the directory containing the DEC COBOL save set. For example, DKA400: is the device name used in examples in this guide. The directory is [COBOL02n], where n is the minor (point) release number. To specify the device name on the @VMSINSTAL command line, enter: DKA400:[COBOL02n] 2-2 Installing DEC COBOL 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: 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 fast vice:[directory] 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 notes. Release Notes If you do not include the N option, VMSINSTAL does not ask you about the release notes. You should review the release notes before proceeding with the installation in case they contain additional information about the installation. If you are restarting the installation and have already reviewed the release notes, you may omit the N option. (The DEC COBOL Release Notes will be available regardless, because VMSINSTAL copies them to the SYS$HELP directory.) (continued on next page) Installing DEC COBOL 2-3 Table_2-1_(Cont.)_Installation_Option_Designators________________ Option_Name_____________Description______________________________ R Alternate Root Lets you install DEC COBOL to a system root other than that of the running ________________________system.__________________________________ For detailed information on these software installation options, see OpenVMS System Manager's Manual. If you specify more than one option, separate the options with commas. For example, use: OPTIONS A,N The following example invokes VMSINSTAL to install DEC COBOL and shows the system response. This example uses the OPTIONS N release note option to access the release notes during the installation. $ @VMSINSTAL COBOL02n DKA400:[COBOL02n] OPTIONS N OpenVMS AXP Software Product Installation Procedure V2.n 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. Digital 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. 2-4 Installing DEC COBOL 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. If you omitted the device name on the VMSINSTAL command line, the following prompt appears: * Where will the distribution volumes be mounted: DKA400:[COBOL02n] If this prompt appears, enter the name of the distribution (media) device and directory that contains the DEC 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 DEC 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. Installing DEC COBOL 2-5 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:. 5. Select a release notes option. Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP * Select option [2]: 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. 2-6 Installing DEC COBOL Next, VMSINSTAL displays the following message: +----------------------------------------------------------------------------+ | Installation Command Procedure for | | DEC COBOL V2.n-vvv Compiler. | +----------------------------------------------------------------------------+ © Digital Equipment Corporation 1995, 1996. All rights reserved. . . (additional text eliminated for brevity; see the Sample Installation) . Installing DEC 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, COBOL024). ______________________________________________________ 6. Respond to license registration queries. DEC COBOL utilizes the OpenVMS License Management Facility (LMF). The installation procedure displays license information about DEC 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: Installing DEC COBOL 2-7 Product: COBOL Producer: DEC Version: 2.n Release Date: dd-mmm-yyyy * Does this product have an authorization key registered and loaded?: 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 DEC 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 DEC 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 DEC 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 DEC 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 DEC COBOL. 2-8 Installing DEC 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 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 DEC 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 DEC 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, or enter no to keep them. Also, if you answered yes in response to the prompt that requests a file purge, previous versions of the DEC COBOL files are now purged. 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). Installing DEC COBOL 2-9 If you chose to run the IVP (step 9), VMSINSTAL now invokes the IVP to verify that DEC COBOL was installed successfully. If DEC COBOL was installed successfully, the IVP displays the following: Successful test of DEC COBOL V2.n-vvv completed at hh:mm 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 saveset 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 ([]). 2-10 Installing DEC COBOL To install the DEC 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: 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 elements that you specify when you invoke the VMSINSTAL command procedure are as follows: saveset-name The installation name for the component. For the DEC COBOL Run-Time Library, use the following installation name: COBOLRTL02n n represents the minor (point) release number for DEC COBOL. For example, use COBOLRTL024 for Version 2.4. To obtain the directory location of the DEC 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 DEC COBOL 2-11 3 _________________________________________________________________ After Installation After DEC 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 /TABLES=SYS$LIBRARY:DCLTABLES The following tasks can be performed after DEC COBOL is installed: o Running the Installation Verification Procedure separately o Customizing the DEC COBOL Messages o Making DEC COBOL usable on a VMScluster o Setting User Account Privileges o Installing DEC 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 DEC COBOL Error Messages If you choose to customize the DEC COBOL message file, the installation procedure copies the DEC 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 DEC COBOL. Customized messages are often desirable for international users. You must install DEC COBOL before editing the message file. If you install DEC 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 DEC COBOL. The following steps explain how to edit the DEC COBOL messages and install the customized message file on your system: 1. Run the DEC 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 DEC 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 DEC 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 DEC COBOL is installed as a known image, you must reinstall COBOL$MSG.EXE by entering the following command: $ INSTALL REPLACE SYS$MESSAGE:COBOL$MSG DEC COBOL will now generate your customized error messages. 3.3 Making DEC COBOL Usable on a VMScluster If you want to run DEC 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 DEC COBOL: 1. Issue the LICENSE LOAD command to activate the license on each node in the VMScluster on which DEC 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 DEC COBOL; failure to do so may cause unexpected errors for users. ________________________ Note ________________________ If you are using a dual-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 After Installation 3-3 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 DEC 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 DEC 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 DEC COBOL RTL installation was performed, then compete the following steps: SYSMAN> DO INSTALL REPLACE SYS$SYSTEM:DEC$COBRTL.EXE SYSMAN> DO INSTALL REPLACE SYS$SYSTEM:LIBOTS2.EXE 6. Finally, exit from SYSMAN. SYSMAN> EXIT $ 3-4 After Installation 3.4 User Account Privileges To use DEC 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 DEC COBOL as a Shared Image If you expect DEC 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 DEC COBOL as a shared image on a system that is currently running, use the OpenVMS Install utility (INSTALL). It is recommended that you install DEC 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 DEC 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 DEC 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 DEC 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 DEC COBOL is available as a shared image each time the system is started: $ INSTALL ADD SYS$SYSTEM:COBOL.EXE/OPEN/SHARED/HEADER_RESIDENT EXIT After Installation 3-5 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 INSTALL> ADD SYS$MESSAGE:COBOL$MSG.EXE INSTALL> EXIT When you install DEC COBOL as a shared image, you need to increase the global pagelets and global sections parameters (see Section 1.6.2). 3-6 After Installation A _________________________________________________________________ Sample Installations This appendix contains a two samples: the DEC COBOL compiler installation, and an installation of the RTL. The compiler installation was run on a system that had no previous version of DEC 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 DEC COBOL Version 2.4. Example A-1 Sample DEC COBOL Installation and IVP SYS$COMMON:[SYSUPD] OpenVMS AXP Software Product Installation Procedure V7.0 It is 9-SEP-1996 at 16:16. Enter a question mark (?) at any time for help. %VMSINSTAL-W-NOTSYSTEM, You are not logged in to the SYSTEM account. * Do you want to continue anyway [NO]? yes * Are you satisfied with the backup of your system disk [YES]? The following products will be processed: (continued on next page) Sample Installations A-1 Example A-1 (Cont.) Sample DEC COBOL Installation and IVP COBOL V2.4 Beginning installation of COBOL V2.4 at 16:16 %VMSINSTAL-I-USEANS, The auto-answer file will be used. %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. +----------------------------------------------------------------------------+ | Installation Command Procedure for | | DEC COBOL V2.4-863 Compiler. | +----------------------------------------------------------------------------+ © Digital Equipment Corporation 1994, 1995, 1996. All rights reserved. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to the 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 DEC COBOL and running the IVP requires approximately 5 to 10 minutes depending on your system configuration. Product: COBOL Producer: DEC Version: 2.4 Release Date: 09-SEP-1996 * Does this product have an authorization key registered and loaded? YES 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: (continued on next page) A-2 Sample Installations Example A-1 (Cont.) Sample DEC COBOL Installation and IVP [SYSEXE]COBOL.EXE [SYSEXE]REFORMAT.EXE [SYSMSG]COBOL$MSG.EXE [SYSUPD]COBOL$MSG.MSG [SYSHLP]COBOL024.RELEASE_NOTES [SYSHLP]COBOL024_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 DEC COBOL Installation Verification Procedure © Digital Equipment Corporation 1994, 1995, 1996. All rights reserved. Successful test of COBOL V2.4-863 Installation of COBOL V2.4 completed at 16:18 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]COBOL024.VMI_DATA VMSINSTAL procedure done at 16:18 INSTALL logged out at 9-SEP-1996 16:18:54.81 A.2 RTL Installation Example A-2 shows a sample installation of the DEC COBOL Run-Time Library. Example A-2 Sample DEC COBOL RTL Installation (continued on next page) Sample Installations A-3 Example A-2 (Cont.) Sample DEC COBOL RTL Installation $ set def sys$update $ @vmsinstal cobolrtl024 sys$update: OpenVMS AXP Software Product Installation Procedure V6.1 It is 9-SEP-1996 at 07:28. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? The following products will be processed: COBOLRTL V2.4 Beginning installation of COBOLRTL V2.4 at 07:28 %VMSINSTAL-I-RESTORE, Restoring product save set A ... +----------------------------------------------------------------------------+ | Installation Command Procedure for | | DEC COBOL RTL V2.4-109. | +----------------------------------------------------------------------------+ © Digital Equipment Corporation 1994, 1996. All rights reserved. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to the 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 DEC COBOL RTL requires approximately 5 to 10 minutes depending on your system configuration. No more questions will be asked ... Now applying COBOLRTL024 ... 1) DEC$COBRTL (new image) 2) LIBOTS2 (new image) 3) STARLET (miscellaneous fix) 4) SYSMSG (new image) (continued on next page) A-4 Sample Installations Example A-2 (Cont.) Sample DEC COBOL RTL Installation The installation of [SYSMSG]SYSMSG.EXE will be skipped since the identical version of this file already exists on the system. Installation of the kit continuing ... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of COBOLRTL V2.4 completed at 07:29 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]COBOLRTL024.VMI_DATA VMSINSTAL procedure done at 07:30 Sample Installations A-5 B _________________________________________________________________ Files Installed on Your System The DEC COBOL installation procedure installs a number of files on your system. Table B-1 identifies the directories that contain the installed files. Table_B-1_Directories_Containing_DEC_COBOL_Installed_Files_______ Directory_____File_Name________________File_Content_Summary______ [SYSEXE] COBOL.EXE Compiler image [SYSEXE] REFORMAT.EXE ANSI/Terminal-Format REFORMAT utility [SYSMSG] COBOL$MSG.EXE Message file [SYSUPD] COBOL$MSG.MSG Customizable source for message file[1] [SYSHLP] COBOL02n.RELEASE_NOTES Release notes (ASCII file) [SYSHLP] COBOL02n_RELEASE_ Release notes (POSTSCRIPT NOTES.PS file) [SYSLIB] DEC$COBRTL.EXE DEC COBOL Run-Time Support Library[2] [SYSLIB] LIBOTS2.EXE DEC COBOL Decimal Run-Time Support[2] [SYSLIB] STARLET.OLB Updated with DEC COBOL RTL routines[2] [SYSTEST.COBOLCOBOL$IVP.COM Installation Verification Procedure [1]See_Section_3.2_for_information_on_customizing_the_DEC_COBOL__ message file [2]This file is added or updated if an RTL installation is performed _________________________________________________________________ Files Installed on Your System B-1 C _________________________________________________________________ Recovering from Errors This appendix provides information to help you deal with failures or errors that might occur during product installation or product use. C.1 Failures During DEC 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 DEC COBOL 2.4 has failed. If the IVP fails, you see these messages: The DEC COBOL 2.4 Installation Verification Procedure failed. %VMSINSTAL-E-IVPFAIL, The IVP for DEC COBOL 2.4 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. o The OpenVMS help library is currently in use. Recovering from Errors C-1 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. C.2 Failures During DEC COBOL Use If you encounter a problem while using DEC COBOL, please see the section on Troubleshooting Tips in the Release Notes. If the problem is unresolved, report it to Digital. Depending on the type of support you have and the nature of the problem, take one of the following actions: o If you have a Software Product Services Support Agreement, contact your Digital 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: - The name (OpenVMS Alpha) and the version number of the operating system you are using - The product name (DEC COBOL) and the version number of DEC COBOL you are using - The hardware system you are using, such as a model number - A very brief description of the problem (one sentence if possible) - How critical the problem is When you submit information electronically or are speaking on the phone to the appropriate DEC 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 C-2 Recovering from Errors (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 (floppy diskette or magnetic tape). o If you should find errors in this manual, or if you should wish to comment on the documentation, please send the manual title, order number, and your comments by one of the following methods: - Electronic Internet mail: cobol_docs@casdoc.enet.dec.com - Fax: 603-881-0120 Attn: Languages Documentation, ZKO2-3 /K35 - A letter sent to the following address: Digital Equipment Corporation Languages Documentation, ZKO2-3/K35 110 Spit Brook Road Nashua, NH 03062-2698 USA Recovering from Errors C-3