HP OpenVMS Systems

This guide describes how to install the Compaq C/C++ Run-Time Components on VAX processors running the OpenVMS operating system. It is intended for system managers.

Keep this guide with your distribution kit. You will need it to install maintenance updates or to reinstall the Compaq C/C++ Run-Time Components kit for any other reason.

If you have any comments or suggestions concerning this guide, you may send them by electronic mail to the following Internet address:

c_docs-at-hp.com

Document Structure

This guide contains four chapters and one appendix:

• Chapter 1 describes the preparations for supporting remote software development and distribution activities.
• Chapter 2 describes how to prepare for Compaq C/C++ Run-Time Components Version 6.0 for OpenVMS VAX installation.
• Chapter 3 describes how to install the Compaq C/C++ Run-Time Components Version 6.0 for OpenVMS VAX.
• Chapter 4 describes postinstallation procedures.
• Appendix A shows a sample installation.

Associated Documentation

For information on the Compaq C/C++ Run-Time Components Version 6.0 for OpenVMS VAX online release notes, see Chapter 2.

For general information on OpenVMS VAX system management, see the OpenVMS operating system documentation set.

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

For additional information about DECthreads, see the Guide to DECthreads.

Conventions Used in This Guide

Table 1 lists the conventions used in this guide.

This chapter discusses the preparations sites must make if they support software development or distribution activities.

1.1 Impact on Software Development and Distribution

The Compaq C/C++ Run-Time Components kit contains shareable image run-time components. When the Compaq C/C++ Run-Time Components kit is installed on OpenVMS VAX Version 5.5, 5.5-1, or 5.5-2 systems, some of the shareable image run-time components replace older versions of existing OpenVMS components. This makes the installation of the Compaq C/C++ Run-Time Components kit similar to an OpenVMS upgrade for sites that develop or distribute software for OpenVMS VAX Version 5.5, 5.5-1, or 5.5-2 systems. Software linked against any of the run-time images provided by the Compaq C/C++ Run-Time Components kit cannot be executed at sites having older versions of the files in their SYS$LIBRARY directories or at sites that do not have the new images available.

Specifically, when executing the image resulting from a software build procedure that links an application against any of the new run-time components provided on this kit (see Table 1-1 and Table 1-2), a user at the installing site will encounter errors if that user subsequently copies the resulting image file to another site (target site) that is running OpenVMS VAX Version 5.5, 5.5-1, or 5.5-2 and does not have the new versions of the run-time components in their SYS$LIBRARY.

For example, consider a software application, VAX APP-XYZ, which has been developed on a cluster named GRAPES::, that is running OpenVMS VAX Version 5.5. As part of the build of VAX APP-XYZ, an executable image named XYZ.EXE is linked against the VAX C Run-Time Library (RTL) executable (SYS$LIBRARY:VAXCRTL.EXE). VAX APP-XYZ has been built and distributed to other OpenVMS VAX sites that have a version of SYS$SYSTEM:VAXCRTL.EXE at least as recent as the one distributed with OpenVMS Version 5.5 and executes properly.

However, if the system manager for the GRAPES:: cluster installs the Compaq C/C++ Run-Time Components kit, one component of the kit is a new version of VAXCRTL.EXE (a more recent version than the version that exists in OpenVMS VAX Version 5.5-2). Installing the Compaq C/C++ Run-Time Components kit places this newer version in SYS$LIBRARY. Subsequently, if the VAX APP-XYZ software developers execute their build procedure, the resulting version of XYZ.EXE will now depend on the new version of VAXCRTL.EXE rather than the old version. If an offsite client takes delivery of the new version of VAX APP-XYZ, users at the remote site will encounter image activation failure while trying to execute XYZ.EXE. The remote user's system issues the following message indicating that the necessary version of SYS$LIBRARY:VAXCRTL.EXE is absent:

$ run xyz
%DCL-W-ACTIMAGE, error activating image VAXCRTL
-CLI-E-IMGNAME, image file SYS$LIBRARY:VAXCRTL.EXE;1
-SYSTEM-F-SHRIDMISMAT, ident mismatch with shareable image

This problem can arise when new components such as DECC$SHR.EXE (the Compaq C Run-Time Library) or CXXL$011_SHR.EXE (the Compaq C++ Class Library) are linked against. It can also occur when existing components like VAXCRTL.EXE (as in this example) are used that have been replaced by newer versions from the Compaq C/C++ Run-Time Components kit. Because the run-time components contained on the Compaq C/C++ Run-Time Components kit are in common use, such problems can arise even for programs that do not use the Compaq C or Compaq C++ compilers.

For simplicity, the rest of this chapter refers to "Compaq C/C++ Run-Time Components software distribution problems" as "distribution problems."

For software developers who want to redistribute software that is developed using systems where the Compaq C/C++ Run-Time Components kit is installed, the options are:

• Link against older versions of the shareable images
• Redistribute the Compaq C/C++ Run-Time Components kit
• Link with object libraries rather than shareable images

The following sections describe these options.

1.1.1 Linking Against Older Versions

Sites that have existing build procedures (that support development and distribution of software linked against the installed version of OpenVMS VAX and want to continue to link against shareable images) must preserve the existing link environment to eliminate the distribution problem without having to modify application build procedures. This requires some preparation and notification on the part of the Compaq C/C++ Run-Time Components installer.

Before installing the Compaq C/C++ Run-Time Components kit, make a copy of the files in the old SYS$LIBRARY directory. After installing Compaq C/C++ Run-Time Components but before executing the standard link operations, applications that need to link with pre-Compaq C/C++ Run-Time Components versions of the shareable images can be supported without change by temporarily defining the appropriate logical name (either SYS$LIBRARY or SYS$SHARE) to point to the old SYS$LIBRARY. With this method, the end user of the application sees no change from the previous, unmodified use of SYS$LIBRARY. The temporary definition of SYS$LIBRARY is not needed at run time.

Whether or not the end-user site has the Compaq C/C++ Run-Time Components installed does not matter if this method is used to build the application. See Section 1.2 for more detailed instructions on preparing for and using this method.

This method does not work for new components (such as DECC$SHR.EXE or CXXL$011_SHR.EXE) not previously supplied on OpenVMS VAX Version 5.5, 5.5-1, or 5.5-2 systems. You can only use these new components with newly developed applications. Applications that encounter the distribution problem from the use of new components on the Compaq C/C++ Run-Time Components kit can only solve the distribution problem by redistributing the Compaq C/C++ Run-Time Components kit itself. See Section 1.6 for the requirements and setup needed for redistribution of the Compaq C/C++ Run-Time Components kit.

1.1.2 Redistributing the Compaq C/C++ Run-Time Components Kit

Redistributing the Compaq C/C++ Run-Time Components kit requires minimal changes to the development system and procedures. It does not sacrifice performance or degrade system resources. It does require that the Compaq C/C++ Run-Time Components kit and this guide be shipped along with the application that requires the use of any of the components contained in it.

When new applications involving new components of the Compaq C/C++ Run-Time Components kit, or new features of existing components, are used and object library usage is either impossible or undesirable, then the distribution problem can only be addressed by supplying the necessary shareable images to the end-user system.

See Section 1.6 for the requirements and setup needed for redistribution of the Compaq C/C++ Run-Time Components kit.

1.1.3 Linking with Object Libraries

Linking with object libraries rather than shareable images eliminates the problem at end-user sites, but slows down the image activation process and consumes system resources.

When an OpenVMS VAX image is linked using object libraries instead of shareable images, all the code and local data for the application are linked directly into the resulting .EXE file (image). This makes the image independent of any shareable images on the linking system; therefore, you can ship the resulting image to any end-user site without the distribution problem occurring. Because the image includes all the necessary run-time code and data needed to execute the program, the image is larger than if shareable images were used.

You can link some (but not all) of the components on the Compaq C/C++ Run-Time Components kit with object libraries. Specifically, the VAX C RTL is available in object library form (VAXCRTL.OLB, VAXCRTLG.OLB, VAXCCURSE.OLB), as is the Compaq C RTL (DECCRTL.OLB, DECCRTLG.OLB, DECCCURSE.OLB). The other components on the Compaq C/C++ Run-Time Components kit are available in shareable image form only. For information on linking with object libraries, see the OpenVMS Linker Utility Manual and the user's guides for VAX C and Compaq C.

1.2 Saving the Old System Development Environment

As discussed in Section 1.1.1, one method of addressing the distribution problem is to save a copy of the existing link-time environment before installing the Compaq C/C++ Run-Time Components kit. Software development and distribution sites often do this before upgrading OpenVMS VAX versions. This approach is simple, but does require sufficient additional disk space to hold the old files, and does require monitoring and deletion when the old environment is no longer required.

To save the old environment, find an alternative device and directory for the files. The alternative directory need not be on the system device. To determine the disk space required to store the old SYS$LIBRARY, enter the following command:

$ DIRECTORY/SIZE=ALL/TOTAL SYS$LIBRARY:*.*;0

Saving the existing environment to an alternative device is simple if sufficient disk space is available to hold all these files. For example, if the new directory is called DISK_D:[ALTSYSLIB], enter the following command to save the old environment:

$ COPY/LOG SYS$LIBRARY:*.*;0 DISK_D:[ALTSYSLIB]

To link against pre-Compaq C/C++ Run-Time Components versions of the files in this saved environment, application build procedures only need to enter one of the following commands immediately before the appropriate LINK commands. If the LINK command uses SYS$LIBRARY, enter the following command:

$ DEFINE/USER SYS$LIBRARY DISK_D:[ALTSYSLIB]

If the LINK command uses SYS$SHARE, enter the following command:

$ DEFINE/USER SYS$SHARE DISK_D:[ALTSYSLIB]

If disk space is limited, you can store only those files replaced by the Compaq C/C++ Run-Time Components kit. Doing this only requires about 1000 blocks but requires using a slightly more complicated logical name assignment at link time. To use the limited file storage method, enter the following COPY command before installing the Compaq C/C++ Run-Time Components kit:

$ COPY/LOG SYS$LIBRARY:CMA$LIB_SHR.EXE,CMA$OPEN_LIB_SHR.EXE,-
CMA$OPEN_RTL.EXE,CMA$RTL.EXE,SMGSHR.EXE,VAXCRTL.EXE,VAXCRTLG.EXE -
DISK_D:[ALTSYSLIB]

This command does not place all the necessary files needed for linking applications in the alternative directory; therefore, you need a more complex logical name definition to link applications with these older files. If the LINK command uses SYS$LIBRARY, enter the following command:

$ DEFINE/USER SYS$LIBRARY DISK_D:[ALTSYSLIB],SYS$SYSROOT:[SYSLIB]

If the LINK command uses SYS$SHARE, enter the following command:

$ DEFINE/USER SYS$SHARE DISK_D:[ALTSYSLIB],SYS$SYSROOT:[SYSLIB]

This command ensures that the linker searches for all the components needed for the linking applications, first in the alternate directory and then in the standard directory. If your site has previously moved SYS$LIBRARY to an alternative disk, make sure you use that directory instead of SYS$SYSROOT:[SYSLIB].

1.3 Notifying Site Users

Before you can proceed to install the Compaq C/C++ Run-Time Components kit, you need to:

• Perform the setup required to support the distribution of dependent products, including saving the Compaq C/C++ Run-Time Components save set and documentation (see Section 1.6).
• Store the old SYS$LIBRARY in an alternative directory (see Section 1.2).

After the installation, notify all site users that the Compaq C/C++ Run-Time Components kit has been installed. Warn users that if they are building applications for execution on other OpenVMS VAX Version 5.5, 5.5-1, or 5.5-2 systems they may encounter the distribution problem. Notify the users of the:

• Location of the saved Compaq C/C++ Run-Time Components kit save set, this reference and installation manual, the read before installing cover letter, and the online release notes files provided by the installation procedure.
• Location of the alternate SYS$LIBRARY directory and the DEFINE command needed to use the components it contains.

In your application's release notes, refer to Chapter 1 of this guide so that software developers can take appropriate action to avoid causing problems for end users who execute on remote sites.

1.4 Diagnosing the Distribution Problem

If a software build procedure has been executed and the application image generated without any record (such as a .MAP file) of how it was linked, you can still determine if the image will encounter problems when the image executes at a remote site. Enter a single DCL command and consult Table 1-1 and Table 1-2. Using this method, software distributors can ensure that any applications they send to their user sites are free of Compaq C/C++ Run-Time Components distribution problems.

To determine if an OpenVMS VAX executable or shareable image will have the distribution problem, enter the following command:

$ ANALYZE/IMAGE/OUTPUT=file-spec.ANL file-spec.EXE

file-spec is the file specification of the image to be examined. Examine the .ANL file with the TYPE command or an editor. At the end of the IMAGE HEADER section, you will see a series of image section descriptors (ISDs). Each ISD describes an image section. Image sections can come from object files, or shareable images that have been used during the LINK process.

Distinguishing such cases is easy: Image sections that come from shareable images appear at the end and contain additional information such as the global section name, match control, and the global section major and minor identifiers. By examining the list of global section names, and the identifiers, and comparing them with Table 1-1 and Table 1-2, you can determine which, if any, of the kit components have been referenced by the link operation.

Table 1-1 lists the new Compaq C/C++ Run-Time Components that have not appeared on any OpenVMS VAX system before Version 6.0. If any of these global section names appear in the ISD list, then that image will encounter the distribution problem when executed at a remote site without the Compaq C/C++ Run-Time Components kit installed.

Table 1-2 lists the new Compaq C/C++ Run-Time Components that replace existing OpenVMS Version 5.5, 5.5-1, or 5.5-2 shareable images and have their minor identifiers incremented. The major and minor identifiers are also listed. By comparing the names and identifiers in the .ANL file with those in Table 1-2, you can tell if any of the new versions were referenced. If there is no match in either table, then the image will not encounter startup problems due to the Compaq C/C++ Run-Time Components kit distribution problem.

If software developers on your system provide a target site with an image file (.EXE) linked against one of the kit components listed in Table 1-1 and Table 1-2, and that target site does not have the Compaq C/C++ Run-Time Components kit installed, the image file will fail to activate. One of the following remedies must be applied:

1. Another version of the image file must be supplied that does not reference any of the kit component image files.
2. The Compaq C/C++ Run-Time Components kit must be supplied, which makes the necessary components available.

The following messages indicate a distribution problem:

$ run xyz
%DCL-W-ACTIMAGE, error activating image VAXCRTL
-CLI-E-IMGNAME, image file SYS$SYSROOT:[SYSLIB]VAXCRTL.EXE;1
-SYSTEM-F-SHRIDMISMAT, ident mismatch with shareable image

VAXCRTL is one of the images listed in Table 1-2.

$ run xyz
%DCL-W-ACTIMAGE, error activating image CMA$TIS_SHR
-CLI-E-IMAGEFNF, image file not found SYS$SYSROOT:[SYSLIB]CMA$TIS_SHR.EXE;

CMA$TIS_SHR is one of the images listed in Table 1-1.

The site supplying the application VAX APP-XYZ is required to provide at least one of the two remedies. If the Compaq C/C++ Run-Time Components kit has been installed without providing an alternative version of SYS$LIBRARY, then remedy 1 cannot be used. To use remedy 1, the older versions of the required files in SYS$LIBRARY must be recovered from a backup of your system device that was performed before installing the Compaq C/C++ Run-Time Components kit.

If the Compaq C/C++ Run-Time Components save set and documentation has not been saved on your system, then remedy 2 cannot be used. In this case, the original source for the Compaq C/C++ Run-Time Components kit will need to be found. If you received the Compaq C/C++ Run-Time Components kit with a Compaq layered product, you will need to obtain the necessary save set and documentation from the media for that layered product. If you received the Compaq C/C++ Run-Time Components kit from another supplier other than Compaq, you will need to obtain it from them.