VMS Software / Documentation / VSI COBOL Installation Guide

VSI COBOL Installation Guide

Software Version:
VSI COBOL Version 3.2 for OpenVMS x86-64
VSI COBOL Version 3.1 for OpenVMS I64
VSI COBOL Version 3.1 for OpenVMS Alpha
Operating System and Version:
VSI OpenVMS x86-64 Version 9.2-1 or higher
VSI OpenVMS IA-64 Version 8.4-1H1 or higher
VSI OpenVMS Alpha Version 8.4-2L1 or higher

Preface

This guide describes how to install VSI COBOL on systems running VSI OpenVMS.

Keep this document with your distribution kit. You will need it to install maintenance updates or to reinstall VSI COBOL for any other reason.

1. About VSI

VMS Software, Inc. (VSI) is an independent software company licensed by Hewlett Packard Enterprise to develop and support the OpenVMS operating system.

2. Related Documentation

In addition to this guide, the VSI COBOL documentation set includes the following:

Once installed, you can use VSI COBOL online HELP, which describes the command qualifiers, explains compiler messages, and provides a quick-reference summary of language topics. To use online HELP for VSI COBOL, enter the following:

$ HELP COBOL

For help understanding OpenVMS error messages, see the OpenVMS System Messages and Recovery Procedures Reference Manual or the online HELP/MESSAGE facility.

You may also find the following documentation useful:

  • VSI OpenVMS License Management Utility Guide

  • VSI OpenVMS System Manager's Manual

3. OpenVMS Documentation

The full VSI OpenVMS documentation set can be found on the VMS Software Documentation webpage at https://docs.vmssoftware.com.

4. VSI Encourages Your Comments

You may send comments or suggestions regarding this manual or any VSI document by sending electronic mail to the following Internet address: . Users who have VSI OpenVMS support contracts through VSI can contact for help with this product.

5. Conventions

The following product names may appear in this manual:

  • VSI OpenVMS for Integrity servers

  • OpenVMS I64

  • I64

All three names — the longer form and the two abbreviated forms — refer to the version of the OpenVMS operating system that runs on the Intel ® Itanium ® architecture.

The following typographic conventions may be used in this manual:

Ctrl/x

A sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x

A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

...
A horizontal ellipsis in examples indicates one of the following possibilities:

  • Additional optional arguments in a statement have been omitted.

  • The preceding item or items can be repeated one or more times.

  • Additional parameters, values, or other information can be entered.

.
.
.

A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( )

In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.

[ ]

In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.

|

In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.

{ }

In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.

bold type

Bold type represents the name of an argument, an attribute, or a reason.

italic type

Italic type indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER=name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TYPE

Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

monospaceBold monospace type indicates a command line, command verb, or a qualifier.

-

A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

6. References

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.

Chapter 1. Preparing for VSI COBOL Installation

This chapter describes the steps that need to be completed before installing VSI COBOL.

1.1. Reading the Release Notes

VSI strongly recommends that you read the release notes before installing VSI COBOL. They contain information about changes to the installation and use of VSI COBOL.

You can extract the VSI COBOL release notes to a file and type or print them before starting VSI COBOL installation. The VSI COBOL release notes are also installed on your system after installation.

For information about accessing these release notes before installing VSI COBOL, see Section 2.1, “Installation Procedure”, Step 5.

The installed release notes for VSI COBOL can be found in the following file:
SYS$HELP:COBOL0nn.RELEASE_NOTES

1.2. Optional Software

You can use the following optional software together with VSI COBOL:

  • Oracle CDD/Repository

  • Oracle DBMS

  • VSI Language Sensitive Editor/Source Code Analyzer

1.3. License Registration

During the installation, the system asks whether you have registered the VSI COBOL license and loaded the appropriate PAK. Before you start the installation, you must register and load your license for VSI COBOL to be able to run the Installation Verification Procedure (IVP), and for users to be able to run VSI COBOL.

The license registration information you need is contained in the Product Authorization Key (PAK) file. If you are installing VSI COBOL as an update on a node or cluster that is licensed for this software, you have already completed the License PAK registration requirements.

Note

On Alpha systems, the VSI COBOL compiler license is covered by the ALPHA-LP license PAK.

If you are installing prerequisite or optional software along with VSI COBOL, review the PAK status and install the PAKs for any prerequisite or optional software before you install VSI COBOL.

To determine whether the VSI COBOL license is registered on the current system, enter the LICENSE LIST command. If the license is not on the list, you must register it.

If you are planning to use the Oracle DBMS programming capability on OpenVMS Alpha, you must purchase the VSI COBOL Oracle DBMS programming license option, which includes a license PAK for use of this option.

To register the PAK on your system, you have the following options:

  • Copy the zipped license script (provided as part of the license distribution sent to you by a VMS Software manager) to your target system, unzip it there, rename its extension from .TXT to .COM, and execute it as a simple command procedure.

  • Copy the script from the appropriate PDF file (provided as part of the license distribution sent to you by a VMS Software manager) directly into a .COM file on your target system. Execute the created command procedure.

  • Run the SYS$UPDATE:VMSLICENSE.COM command procedure and manually enter the PAK data? or load the PAK through the LICENSE REGISTER command. Refer to the VSI OpenVMS License Management Utility Guide for more information on how to do so.

Next, make sure the license is loaded into the license database using the SHOW LICENSE command.
$ SHOW LICENSE COBOL

Active licenses on node NODE1:

------- Product ID --------    ---- Rating ----- -- Version --
Product            Producer    Units PCL   Activ Version Release    Termination
COBOL              VSI             0  0     1      0.0  (none)      10-MAY-2024

If the license is not found, you will need to load it using the LICENSE LOAD command.

$ LICENSE LOAD COBOL
%LICENSE-I-LOADED, VSI COBOL was successfully loaded with 0 units
$

If you plan to use VSI COBOL on more than one node in a cluster, you will need to perform a license load on the other nodes after you complete this installation. See Section 3.3, “Making VSI COBOL Usable on an OpenVMS Cluster System”.

For complete information on using LMF, see the VSI OpenVMS License Management Utility Guide.

1.4. Checks and Requirements for Installing VSI 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 VSI COBOL.

To eliminate possible installation errors, execute the following command procedure to start up Oracle CDD/Repository on OpenVMS Alpha:
$ @SYS$STARTUP:CDDSTRTUP.COM

Consult the Oracle CDD/Repository documentation on how to start up Oracle CDD/Repository on OpenVMS I64.

1.5. Installation Procedure Requirements

This section describes the requirements for installing VSI COBOL, which include process account quotas, system parameters, disk space, and so on.

1.5.1. Installation Account Privileges and Disk Space Requirements

To install VSI COBOL, your account must have the SETPRV privilege or at least the following privileges enabled:

  • BYPASS

  • CMKRNL

  • SYSLCK

  • SYSPRV

Privileges required for product use are defined in Section 3.4, “User Account Privileges”.

Table 1.1, “Disk Space Requirements” summarizes the amount of free blocks needed for the VSI COBOL installation.
Table 1.1. Disk Space Requirements

Kit

Blocks Required

VSI COBOL for VSI OpenVMS Alpha

26,000

VSI COBOL for VSI OpenVMS I64

48,000

VSI COBOL for VSI OpenVMS x86-64

150,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.2. System Parameters

Installing VSI COBOL requires certain system parameter settings.

The minimum number of free global pagelets (512-byte subpage units) and global sections needed is 3 global sections and 75000 contiguous free global pagelets?, plus a sufficient number of contiguous free global pagelets to contain the file SYS$LIBRARY:DCLTABLES.EXE. (See Section 1.5.2.1, “Calculating the Values for Global Pagelets and Global Sections”.)

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.2.1. Calculating the Values for Global Pagelets and Global Sections

To determine the number of global pagelets required by SYS$LIBRARY:DCLTABLES.EXE, enter the following DCL command: 
$ 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

If the number of free global pagelets or global sections is less than the required value (see Section 1.5.2, “System Parameters”), you must increase the system parameter setting. The following section describes the procedures for increasing these values using AUTOGEN.

1.5.2.2. Changing System Parameter Values with AUTOGEN

If you do not have enough free global pages or free global sections to install VSI BASIC, use the AUTOGEN command procedure to increase the GBLPAGES or GBLSECTIONS system parameters.

AUTOGEN automatically adjusts values for parameters that are associated with the values you reset manually. To change system parameters with AUTOGEN, edit the following file:
SYS$SYSTEM:MODPARAMS.DAT

To change a parameter value listed in this file, delete the current value associated with that parameter and enter the new value.

To add a new parameter, insert a line in the file that includes both the name of the parameter and its value. For example:
WSMAX = 1024
To modify incremental parameters such as GBLPAGES and GBLSECTIONS, use ADD_. The following example increases the global pagelet setting by 2000:
ADD_GBLPAGES = 2000

Note

When you set the page file quota, 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 and reboot the system:
$ @SYS$UPDATE:AUTOGEN GETDATA REBOOT

When you specify REBOOT, AUTOGEN does an automatic system shutdown and then reboots the system. Any users logged in to the system are immediately disconnected during the shutdown. The automatic reboot puts the new parameter values into effect.

AUTOGEN 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 VSI OpenVMS System Manager's Manual, Volume 1: Essentials and VSI OpenVMS System Manager's Manual, Volume 2: Tuning, Monitoring, and Complex Systems.

1.6. Backing Up Your System Disk

VSI 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 VSI OpenVMS System Manager's Manual.

Chapter 2. Installing VSI COBOL

After you register and load the license PAK (including the COBOL DBMS PAK, if you have it), the installation will take approximately 2 to 5 minutes, depending on your system configuration.

If you encounter any failures during installation, see Section 2.2, “Recovering from Installation Errors”.

2.1. Installation Procedure

The installation procedure loads VSI COBOL product distribution files on to the system disk on the system where you perform the installation. The VSI COBOL installation procedure consists of a series of questions and informational messages.

When the system prompts you with a question during the installation procedure, the default answer, if any, is enclosed in brackets "[]".

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 6.

Follow these steps to install VSI COBOL:

  1. Make sure you have downloaded the latest kit file. For example, X86VMS-COBOL-Xnnnn-nnn.ZIP?.

  2. Use the UNZIP utility to extract the installation files.

    The ZIP/UNZIP utility can be found on your system in the following directories:?
    SYS$COMMON:[SYSHLP.UNSUPPORTED.ZIP]
SYS$COMMON:[SYSHLP.UNSUPPORTED.UNZIP]

    To be able to use the UNZIP command, create a foreign command that will run the UNZIP utility, for example:

    $ UNZIP == "$SYS$COMMON:[SYSHLP.UNSUPPORTED.UNZIP]UNZIP.EXE"

    For information on how to use this utility, execute UNZIP.

  3. Log in to a privileged account on the system (or cluster) where you will install VSI COBOL. This account must have the following privileges enabled:

    • BYPASS

    • CMKRNL

    • SYSLCK

    • SYSPRV

    If your process has the SETPRV privilege, you can enable these privileges by entering the following command:

    $ SET PROCESS/PRIVILEGE=(BYPASS,CMKRNL,SYSLCK,SYSPRV)

    To check whether your process has these privileges enabled, enter the following command:

    $ SHOW PROCESS/PRIVILEGES

  4. Set your default device and directory to SYS$UPDATE.

    $ SET DEFAULT SYS$UPDATE
  5. To extract the VSI COBOL online release notes before you install VSI COBOL, enter the following command:
    $ PRODUCT EXTRACT RELEASE_NOTES COBOL /SOURCE=disk:[dir]

    In this command, disk:[dir] is the specification of the disk and directory containing the product installation files. If your process default directory is the directory that contains the VSI COBOL product distribution files, you can specify the /SOURCE directory as /SOURCE=[].

    You can view or print the extracted release notes before you continue with the installation. For example:
    $ TYPE/PAGE COBOL0nn.RELEASE_NOTES

  6. To install the VSI COBOL compiler , enter the following PRODUCT INSTALL command:

    $ PRODUCT INSTALL COBOL /SOURCE=disk:[dir]

    Where disk:[dir] is the specification of the disk and directory containing the product installation files.

    When installation has been completed, the DCL $ prompt reappears.

  7. 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
  8. To obtain a list of files installed, enter the following command:
    $ PRODUCT SHOW OBJECT /PRODUCT=COBOL

    To use other features of the PCSI utility, see the POLYCENTER Software Installation Utility User's Guide.

2.2. Recovering from Installation Errors

Errors can occur during the installation if any of the following conditions exist:

  • The operating system version is incorrect.

  • The privileges or disk space for successful installation are insufficient.

For descriptions of error messages generated by these and related conditions, see the VSI OpenVMS documentation on system messages and software installation or the online HELP/MESSAGE command. Take the appropriate action described in the message.

If your installation is not successful, check for the following possible problems:

  • The appropriate PAK must be available to the user performing the installation. The PAK must be registered and loaded before you can install VSI COBOL. For information about registering a PAK, see Section 1.3, “License Registration”. Then reinstall VSI COBOL.

  • The DCLTABLES.EXE file should be in the SYS$COMMON:[SYSLIB] directory. There should not be a copy of DCLTABLES.EXE in SYS$SPECIFIC:[SYSLIB].

    If a copy of DCLTABLES.EXE is found in a SYS$SPECIFIC root, rename it to DCLTABLES.OLD, do an INSTALL REPLACE SYS$LIBRARY:DCLTABLES, then reinstall VSI COBOL.

  • The system logical name SYS$SYSROOT should not be modified from the preset definition provided by the VSI OpenVMS operating system.

Chapter 3. After Installing VSI COBOL

After VSI 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 VSI COBOL is installed:

  • Running the Installation Verification Procedure separately

  • Customizing the VSI COBOL messages

  • Making VSI COBOL usable on an OpenVMS Cluster System

  • Setting user account privileges

  • Installing VSI COBOL as a shared image

  • Running the REFORMAT utility

  • Removing VSI COBOL

3.1. Running the Installation Verification Procedure Separately

The Installation Verification Procedure (IVP) runs automatically during installation of the VSI COBOL compiler. It requires the installation of the VSI 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:
$ @SYS$COMMON:[SYSTEST]COBOL$IVP.COM

3.2. Customizing VSI COBOL Error Messages

The PCSI installation automatically copies the VSI 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 VSI COBOL. Customized messages are often desirable for international users.

You must install VSI COBOL before editing the message file. If you install VSI 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 VSI COBOL.

The following steps explain how to edit the VSI 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 VSI COBOL to correctly identify the errors, you must not change the following:

    • The 3- to 9-character mnemonic that appears in the first column

    • The sequence in which the error messages appear in the file

    • The severity level of the error message

    • The number, type, and order of the formatted ASCII output (FAO) arguments that appear in the message

  2. Run the OpenVMS Message utility.

    To translate the new message text into a file that VSI 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 VSI COBOL is installed as a known image, you must reinstall COBOL$MSG.EXE by entering the following command:
    $ INSTALL REPLACE SYS$MESSAGE:COBOL$MSG

VSI COBOL will now generate your customized error messages.

3.3. Making VSI COBOL Usable on an OpenVMS Cluster System

If you want to run VSI COBOL on multiple nodes of a VMScluster, first check to see that you have the appropriate software license (see Section 1.3, “License Registration”). Then, perform the following steps after you install VSI COBOL:

  1. Issue the LICENSE LOAD command to activate the license on each node in the VMScluster on which VSI 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 VSI COBOL; failure to do so may cause unexpected errors for users.

    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 VSI 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 VSI 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. Finally, exit from SYSMAN.
    SYSMAN> EXIT
$

3.4. User Account Privileges

To use VSI 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 VSI COBOL as a Shared Image

If you expect VSI 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 VSI COBOL as a shared image on a system that is currently running, use the OpenVMS INSTALL utility. It is recommended that you install VSI 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 VSI 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 VSI 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. 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

3.6. REFORMAT Utility

The PCSI installation automatically includes installation of REFORMAT.EXE, the REFORMAT utility. It is ready to run.

3.7. Removing VSI COBOL

To remove VSI COBOL from the system, use the following command:
$ PRODUCT REMOVE COBOL
1

When you register a license with VMSLICENSE.COM, you can choose an option to load the license automatically to avoid loading the license manually.

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.

2

If your kit file has an extension different from .ZIP, proceed from Step 3.

3

If you cannot find the ZIP/UNZIP utility on your system, you can download it from the following webpage: https://vmssoftware.com/products/zip-tools/.