| United States |
|
|
Order Number: AA--Q0XBB--TK
This guide contains instructions for installing the Compaq C/C++ Run-Time Components on OpenVMS VAX systems. It also contains important information on distributing applications that are linked to Compaq C/C++ Run-Time Components. This guide applies to Compaq C/C++ Run-Time Components Version 6.0 for OpenVMS VAX and all maintenance updates throughout that version.
Revision/Update Information: This is a new guide.
Operating System & Version:
OpenVMS VAX Version 5.5 or higher.
Future maintenance releases may
require higher versions.
Software Version: Compaq C/C++ Run-Time Components Version 6.0 for OpenVMS VAX
Compaq Computer Corporation
Houston, Texas
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.
Compaq, the Compaq logo, Alpha, DEC, DECnet, DECtalk, DECthreads, DIGITAL, OpenVMS, RMS, Tru64 UNIX, VAX, VAX C, CDD/Repository, VMS, and the DIGITAL logo are registered in the U.S. Patent and Trademark Office.
The following is a third-party trademark:
PostScript is a registered trademark of Adobe Systems Inc.
ZK6363
This document is available on CD-ROM.
This document was prepared using VAX DOCUMENT, Version V3.2-1m.
| Contents |
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@zko.dec.com
This guide contains four chapters and one appendix:
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.
Table 1 lists the conventions used in this guide.
| Convention | Meaning |
|---|---|
| UPPERCASE TEXT | Uppercase text indicates the name of a command, a file, a parameter, a procedure, or utility. |
| $ @SYS$UPDATE:VMSINSTAL | In interactive examples, prompts or displayed text appears in a monospace font. User input appears in bold monospace font. |
| Ctrl/ x | In interactive examples, 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; for example, Ctrl/C or Ctrl/Z. |
| [YES] | Square brackets indicate that the enclosed item is a default value in a VMSINSTAL prompt. Also, square brackets serve as delimiters for a directory name in a file specification. |
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.
Any application that links directly or indirectly against a version of VAXCRTL.EXE, VAXCRTLG.EXE, CMA$RTL.EXE, CMA$OPEN_RTL.EXE, CMA$LIB_SHR.EXE, or CMA$OPEN_LIB_SHR.EXE is affected by this problem. A linkage is indirect if a shareable image that references any of these images is linked into the application. |
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:
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:
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:
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.
| Image Name | Major Identifier | Minor Identifier |
|---|---|---|
| CMA$TIS_SHR | 1 | 1 |
| CXXL$011_SHR_ nnn 1 | 1 | 1 |
| DECC$SHR | 2 | 0 |
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.
| Image Name | Major Identifier | Minor Identifier |
|---|---|---|
| VAXCRTL | 4 | 5 |
| VAXCRTLG | 4 | 5 |
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:
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.
| Next | Contents |
|
