VMS Software / Documentation / VSI C++ Installation Guide

VSI C++ Installation Guide

Document Number: DO-DVCXIG-01A
Publication Date: May 2024
Software Version:
VSI C++ Version 10.1-1 for OpenVMS x86-64
Operating System and Version:
VSI OpenVMS x86-64 Version 9.2-1 or higher

Preface

This guide describes how to install VSI C++ on OpenVMS x86-64 operating system.

Keep this guide with your distribution kit. You will need it to install maintenance updates or to reinstall VSI C++ 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. Intended Audience

This guide is intended for system managers who install VSI C++ for OpenVMS.

3. Related Documents

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

Once installed, you can use VSI C++ 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 C++, enter the following command:

$ HELP CXX

For help understanding CXX system error messages, see the https://releases.llvm.org/10.0.0/tools/clang/docs/index.html.

4. OpenVMS Documentation

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

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

6. Conventions

The following typographic conventions may be used in this manual:

Convention

Meaning

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

-

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.

numbers

All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes – binary, octal, or hexadecimal – are explicitly indicated.

Vn.nIn this guide, some version numbers are given as Vn.n. When you install VSI C++, the actual version number appears on your screen.

Chapter 1. Preparing to Install VSI C++

This chapter discusses the preparations and requirements necessary for installing VSI C++.

1.1.  Reading the Release Notes

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

For information about reading the online release notes before installation, use the following command: 
PRODUCT EXTRACT RELEASE_NOTES

VSI strongly recommends that you read the release notes before installing VSI C++. They contain information about changes to the installation and use of VSI C++, such as the minimum version of the VSI OpenVMS operating system required for this release of VSI C++.

After installation, the release notes are installed as text in:

SYS$HELP:CXX.RELEASE_NOTES

1.2. License Registration

Before you start the installation, you must register and load your license for VSI C++ to be able to run the Installation Verification Procedure (IVP), and for users to be able to run VSI C++.

Note

If you do not have the license registered and loaded, the installation will proceed and fail at the IVP phase. VSI C++ will be installed, but you can only utilize it once the license has been loaded.

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

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

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 CXX-V

Active licenses on node NODE1:

------- Product ID --------    ---- Rating ----- -- Version --
Product            Producer    Units PCL   Activ Version Release    Termination
CXX-V             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 CXX-V
%LICENSE-I-LOADED, VSI CXX-V was successfully loaded with 0 units
$

For complete information on using LMF, see the VSI OpenVMS License Management Utility Guide or the online HELP LICENSE utility.

1.3. Installation Procedure Requirements

After you have registered and loaded the license PAK and read the appropriate parts of this Installation Guide, the installation takes few seconds, depending on your system configuration.

1.3.1. Installation Account Privileges and Disk Space

To install VSI C++, you must be logged in to an account that has the SETPRV privilege or at least the following privileges enabled:

  • BYPASS

  • CMKRNL

  • SYSLCK

  • SYSPRV

Table 1.1 summarizes the storage requirements.
Table 1.1. Disk Space Requirements

Kit Component

During Installation

After Installation

VSI C++ for OpenVMS x86-64 systems

350000

350000

To determine the number of free disk blocks on the current system disk, enter the following DCL command: 
$ SHOW DEVICE SYS$SYSDEVICE

1.3.2. System Parameters

Installing C++ requires certain system parameter settings.

The minimum number of free global pagelets (512-byte subpage units) and global sections needed is 6 global sections, and approximately 350000 contiguous free global pagelets, plus a sufficient number of contiguous free global pagelets to contain the file SYS$LIBRARY:DCLTABLES.EXE. (See Section 1.3.2.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.3.2.1. Calculating Values for GBLPAGES and GBLSECTIONS

To determine the number of global pagelets required by SYS$LIBRARY:DCLTABLES.EXE, enter the following DCL command:

$ DIR/SIZE SYS$LIBRARY:DCLTABLES.EXE

This command returns the size (in blocks) of SYS$LIBRARY:DCLTABLES.EXE. As an approximation, use this value as the number of global pagelets for the file.

You can use the WRITE command with the F$GETSYI lexical function to find the number of free contiguous global pagelets and free global sections. 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.3.2), you must increase the system parameter setting. The following section describes the procedures for increasing these values using AUTOGEN.

1.3.2.2. Changing System Parameter Values with AUTOGEN

If you do not have enough free global pages or free global sections to install VSI C++, 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.

Chapter 2. Installing VSI C++

This chapter explains how to install VSI C++ with a step-by-step description of the installation procedure. It also covers error recovery considerations.

2.1. Installation Procedure

The VSI C++ installation procedure consists of a series of questions and informational messages.

To stop the installation procedure at any time, use Ctrl/C. However, files created up to that point are not deleted. You must then delete these files interactively.

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

Follow these steps to install VSI C++:

  1. Make sure you have downloaded the latest kit file. The filename is VSI-X86VMS-CXX-Vnnnn-n-1.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 C++. 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)

    You can check what privileges are enabled for your process by entering the following command:

    $ SHOW PROCESS/PRIVILEGES
  4. To extract the C++ online release notes before you install VSI C++, enter the following command:
    $ PRODUCT EXTRACT RELEASE_NOTES CXX /SOURCE=disk:[dir] -
_$/FILE=CXX.RELEASE_NOTES

    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 C++ product distribution files, you can specify the /SOURCE directory as /SOURCE=[].

    You can view or print the file CXX.RELEASE_NOTES before you continue with the installation. For example:
    $ TYPE/PAGE CXX.RELEASE_NOTES

  5. To install the VSI C++ compiler, enter the following PRODUCT INSTALL command:

    $ PRODUCT INSTALL CXX /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.

  6. To obtain a list of files installed, enter the following command:
    $ PRODUCT SHOW OBJECT /PRODUCT=CXX

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

2.2. Error Recovery

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 the error messages generated by these conditions, see the VSI OpenVMS documentation on system messages, recovery procedures, and VSI OpenVMS software installation. If you are notified that any of these conditions exist, you should take the appropriate action as described in the message.

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

  • 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 C++.

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

For information on installation requirements, see Section 1.3.

Chapter 3. After Installing VSI C++

This chapter describes the user account requirements needed to work with VSI C++ and the tasks that can be performed after VSI C++ is installed. It also contains guidelines on how to remove VSI C++.

3.1. Running the Installation Verification Procedure (IVP) Separately

The VSI C++ Installation Verification Procedure (IVP) runs automatically during VSI C++ installation. If system problems occur, you must run the VSI C++ IVP separately to ensure the integrity of the installed files. To run the IVP, enter the following command:
$ @SYS$TEST:CXX$IVP.COM

For information about what to do if you have trouble, see Section 2.2.

3.2. Modifying the System-Wide Startup Command Procedure

Add the following line to the system-wide startup file (if you have not done so previously), such as the file SYS$MANAGER:SYSTARTUP_VMS.COM or a command procedure that it invokes:

$ @SYS$STARTUP:CXX$STARTUP

This command procedure installs VSI C++ images in memory and performs related actions.

The C++ startup procedure line does not take any parameters (arguments).

3.3. Making the Product Usable on a VMScluster

If you want to run VSI C++ 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 VSI C++:

  1. Issue the LICENSE LOAD command, as described in the VSI OpenVMS License Management Utility Guide, to activate the license on each node in the VMScluster on which VSI C++ is to be executed.

  2. The commands in this step should be executed on all cluster nodes, whether or not they are licensed to use VSI C++; failure to do so may cause unexpected errors for users.

  3. While logged in as SYSTEM, or as another username that has the CMKRNL and SYSPRV privileges enabled, use the OpenVMS SYSMAN utility to make the new versions of shareable images 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

    If any of the INSTALL commands fail, reboot the affected node.

    The SYSMAN utility will cause each DO command to be executed on all nodes of the local cluster.

  4. The SYS$STARTUP:CXX$STARTUP.COM file installs the compilers as a known image. This command procedure file should be executed on all cluster nodes using the following DO command:

    SYSMAN> DO @SYS$STARTUP:CXX$STARTUP
%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. Making the CXX Command Available After Installation

VSI C++ is now installed and can be invoked by all users with the CXX command.

The installation procedure modifies the DCL command table so that the CXX commands are 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 CXX command must log out and log in again, or use the following DCL command:

$ SET COMMAND /TABLES=SYS$LIBRARY:DCLTABLES

3.5. Setting User Account Quotas

No special privileges are needed to use VSI C++. There is no benefit from installing the compilers with privileges.

To use VSI C++, a user account does not need to meet any special quota requirements. However, for users who will be compiling very large programs (many program units compiled together) or running very large performance-critical programs, consider adjusting the working set (WSDEF, WSQUOTA, WSEXTENT) and page file (PGFLQUOTA) account quotas to improve performance.

Use the OpenVMS AUTHORIZE Utility from a suitably privileged account to change the process quotas in the user authorization file (UAF). Some sites may restrict the use of the AUTHORIZE Utility to certain accounts or people.

After the quotas for the account have been changed, the user should log out of the account and log in again for the new quotas to take effect.

For information on using the AUTHORIZE Utility, see the VSI OpenVMS System Manager's Manual, Volume 1: Essentials.

3.6. Enhancing VSI C++ Performance

After you install VSI C++, you might want to adjust your system to enhance performance or lower the use of some system resources.

If users will be compiling very large programs (many program units compiled together) or running very large performance-critical programs, consider the following:

  • Check that adequate page file space exists. Large programs need more virtual memory during compilation and execution than small programs. Use the INSTALL command to extend an existing page file or create one or more new page files.

  • The SYSGEN parameter virtual page count is related to the total amount of page file space. If you create more page file space, review the virtual page count parameter and increase it if necessary.

  • The SYSGEN parameter maximum working set (WSMAX) might also be checked if a larger process working set is needed.

For more information on page file use and SYSGEN parameters, see the VSI OpenVMS System Manager's Manual, Volume 2: Tuning, Monitoring, and Complex Systems. For information about system tuning and performance investigation, see the Guide to OpenVMS Performance Management.

3.7. Removing VSI C++

To remove VSI C++ from the system, use the following command:

$ PRODUCT REMOVE CXX

After removing VSI C++ from the system, remove the call to SYS$STARTUP:CXX$STARTUP.COM from your system startup procedure.

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.

2

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