United States    
COMPAQ
Compaq C

Compaq C

Migration Guide for OpenVMS VAX Systems

Order Number: AA--Q5AVB--TE


November 1999

This guide contains information to assist VAX C application developers in migrating from a VAX C environment to a Compaq C environment on OpenVMS VAX systems.

Revision/Update Information: This revised guide supersedes the
DEC C Migration Guide for OpenVMS VAX Systems (Order No. AA--Q5AVA--TE)

Software Version: Compaq C Version 6.2 or higher for OpenVMS VAX Systems

Compaq Computer Corporation
Houston, Texas


First Printing, May 1994
Revised, November 1999

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.

Copyright ©1994 - 1999 Digital Equipment Corporation

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 are third-party trademarks:

Motif and OSF are registered trademarks of the Open Software Foundation, Inc.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd.

ZK6396

This document is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2-1m.

Contents


Preface

Purpose of this Guide

This guide is provided as an aid to porting VAX C applications to Compaq C on OpenVMS VAX systems. Chapter 1 describes how to migrate your VAX C applications from the VAX C Run-Time Library (RTL) to the Compaq C RTL for their run-time operations. Chapter 2 describes techniques for helping VAX C developers migrate to the Compaq C compiler.

This guide is not intended as a summary of all differences between Compaq C and VAX C. For such a summary, see the New and Changed Features appendix of the Compaq C User's Guide for OpenVMS Systems. This appendix lists the features that distinguish Compaq C for OpenVMS Systems from VAX C Version 3.2.

You may send comments or suggestions regarding this guide, or any Compaq C document, by electronic mail to the following Internet address:

c_docs@zko.dec.com

Intended Audience

This guide is intended as an aid to OpenVMS VAX application developers and users who would like to port their VAX C programs to Compaq C.

Structure of this Document

This guide is organized as follows:

Associated Documents

You may find the following documents useful when programming in Compaq C:

Note

1 Brian W. Kernighan and Dennis M. Ritchie, The C Programming Language, Second Edition (Englewood Cliffs, New Jersey: Prentice Hall, 1988).

Conventions

Table 1 lists the conventions used in this guide.

Table 1 Conventions Used in this Guide
Convention Description
UPPERCASE TEXT Uppercase letters indicate the name of a command, a file, a parameter, a procedure, or utility.
$ @SYS$UPDATE:VMSINSTAL Monospace boldface text represents user input in interactive examples.
$ The dollar sign is used to indicate the DCL prompt. This prompt may be different on your system.
[Ctrl/x] In procedures, 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.
.
.
.
Vertical ellipsis in an example means that information not directly related to the example has been omitted.
file-spec,... Horizontal ellipsis indicates that additional parameters, values, or information can be entered.
[ ] Square brackets indicate that the enclosed item is optional. (Square brackets are not, however, optional in the syntax of a directory name in a file specification or in the syntax of a substring specification in an assignment statement.)


Chapter 1
Migrating to the Compaq C Run-Time Library

This chapter describes why and how to migrate your VAX C applications to use the Compaq C Run-Time Library (RTL) for their run-time operations. It includes several ways to link Compaq C and VAX C code with the Compaq C RTL, descriptions of potential migration concerns and solutions, and interoperability concerns when using multiple C RTLs.

1.1 Why Migrate to the Compaq C RTL

Compaq C introduces a new run-time library (RTL) on OpenVMS VAX systems to supplement the original VAX C RTL. The new Compaq C RTL is designed to be faster and more reliable and maintainable than the VAX C RTL, and to support the new ANSI C conformant Compaq C compiler for OpenVMS VAX systems, as well as the Compaq C++ compiler for OpenVMS VAX systems.

Both the VAX C RTL and the Compaq C RTL can coexist on your OpenVMS VAX system. The VAX C RTL supports existing VAX C applications. The Compaq C RTL supports ANSI-compliant Compaq C and Compaq C++ applications, as well as other components of the OpenVMS environment. You can, however, link your VAX C programs to the Compaq C RTL, as described in the next section.

There are several reasons to port your VAX C application's run-time support to the Compaq C RTL:

You would not want to port a VAX C application's run-time support to the Compaq C RTL for either of the following reasons:

1.2 How to Migrate to the Compaq C RTL

There are three ways to migrate a C application's run-time support from the VAX C RTL environment to the Compaq C RTL:

The method you choose depends on whether your application source code can be changed, or whether the project distributes shareable images.

1.2.1 Migrating Using the Compaq C Compiler

The Compaq C RTL is primarily designed to be used with the Compaq C and Compaq C++ compilers. A program developed with either of these compilers can be linked directly with the Compaq C RTL shareable image DECC$SHR.EXE because the compiler generates the correct symbol names and types to be able to link with DECC$SHR.EXE.

The VAX C compiler cannot generate code that can be linked directly to DECC$SHR.EXE (although, as discussed in Section 1.2.2, VAX C code can be indirectly linked to the Compaq C shareable image using the transfer vectors in VAXC2DECC.EXE and VAXCG2DECC.EXE). The only supported way to link directly to DECC$SHR.EXE is to use the Compaq C or Compaq C++ compilers. By linking directly to DECC$SHR.EXE, the migrating project avoids a number of potential interoperability problems (see Section 1.4).

You can also link your Compaq C or Compaq C++ code to the Compaq C RTL object libraries.

Using the Compaq C compiler to migrate to the Compaq C RTL provides the greatest benefits to the migrating project: easier porting to OpenVMS Alpha and Tru64 UNIX systems, better error checking, bug fixes, faster and better code.

1.2.1.1 Linking with the Compaq C RTL Shareable Images

Most linking needs should be satisfied by using the Compaq C RTL shareable image DECC$SHR.EXE in the SYS$LIBRARY directory. Use this linking method for programs that are written entirely in Compaq C or Compaq C++ code; that is, with no VAX C object modules.

Because DECC$SHR.EXE exports only prefixed universal symbols (ones that begin with DECC$), to successfully link against it make sure you cause prefixing to occur for all Compaq C RTL entry points.

If you use only the Compaq C RTL functions defined in the ANSI C Standard, all entry points will be prefixed.

If you use Compaq C RTL functions not defined in the ANSI C Standard, you must compile in one of two ways to ensure prefixing:

Then link against the shareable image using the standard LINK command. For example:


$ LINK PROG1

Unlike VAX C, Compaq C does not require LNK$LIBRARY logical names or options files.

1.2.1.2 Linking with the Compaq C RTL Object Libraries

You can link Compaq C object modules to the Compaq C RTL object libraries in the same way that you link VAX C object modules to the Compaq C RTL object libraries. See Section 1.2.3.

1.2.2 Migrating VAX C Code Using Shareable Images

Programs currently linked against the VAX C RTL shareable images can be most conveniently migrated to the Compaq C RTL by avoiding recompilation entirely and linking existing VAX C generated object files with the following shareable images:

VAXC2DECC.EXE provides the same transfer vectors and global symbols as VAXCRTL.EXE. VAXCG2DECC.EXE corresponds to VAXCRTLG.EXE. The VAXC2DECC images contain very little code; they consist primarily of transfer vectors into the Compaq C RTL shareable image DECC$SHR.EXE.

To use either of these images, replace the current VAX C RTL shareable image in your linker options file with its corresponding VAXC2DECC image. For example, a program that used to be linked with VAXCRTL.EXE can be migrated to the Compaq C RTL by linking as follows:


$ LINK/EXEC=MYPROG MYMOD1,MYMOD2,SYS$INPUT:/OPTIONS
SYS$LIBRARY:VAXC2DECC/SHARE
[Ctrl/Z]

Because the VAXC2DECC images provide the same application program interface (API) as the VAXCRTL images, they have the same potential for universal symbol and psect name conflicts as the VAXCRTL images. See Section 1.4.2 for more information.

1.2.3 Migrating VAX C Code Using Object Libraries

Programs currently linked against the VAX C RTL object libraries can be migrated to the Compaq C RTL by linking them with the Compaq C RTL object libraries. The Compaq C RTL object libraries provide both the VAX C RTL and Compaq C RTL APIs.

The Compaq C RTL object libraries reside in the SYS$LIBRARY directory, except they use "DECC" in their name instead of "VAXC":

Use them just like you would use the VAX C RTL object libraries. For example, a program that uses the Curses package and links against the VAX C RTL object libraries could use the Compaq C RTL by linking as follows:


$ LINK/EXEC=MYPROG MYMOD1,MYMOD2, -
SYS$LIBRARY:DECCCURSE/LIBRARY,SYS$LIBRARY:DECCRTL/LIBRARY

Note that, as with VAX C, if you specify more than one object library on the LINK command, you must do so in the following order:

  1. DECCCURSE.OLB
  2. DECCRTLG.OLB
  3. DECCRTL.OLB

Notes

  • Use care if you define any LNK$LIBRARY logicals to the Compaq C RTL libraries because doing so will cause all C development (both VAX C and Compaq C) to use the Compaq C object libraries.
  • When linking /NOSYSSHR with the Compaq C RTL object libraries, you must also specify /INCLUDE=CMA$TIS. See Section 1.3 for more information.
  • Because the Compaq C RTL object libraries provide the same API as the VAX C RTL, they have the same potential for universal symbol and psect name conflicts as the VAX C RTL object libraries. See Section 1.4.2 for more information.

1.3 Potential Migration Concerns and Solutions

This section describes migration problems you might encounter when linking /NOSYSSHR with the Compaq C RTL object libraries, or because of differences in the behavior of C RTL routines, obsolete routines, and debugging differences.

Also see Section 1.4 for a description of interoperability concerns when multiple copies of the C RTL are used in the same process.

1.3.1 Linking /NOSYSSHR with the Compaq C RTL Object Libraries

If you need to link your program with the Compaq C RTL object libraries and /NOSYSSHR, or if want to create an image that uses only Compaq C RTL object libraries, you must specify /INCLUDE=CMA$TIS with the object library on the LINK command. Otherwise, the following symbols will be undefined and the resulting image will not execute:


%LINK-I-UDFSYM,         CMA$DECC$G_REENTRANCY 
%LINK-I-UDFSYM,         CMA$TIS_ERRNO_GET_ADDR 
%LINK-I-UDFSYM,         CMA$TIS_ERRNO_SET_ADDR 
%LINK-I-UDFSYM,         CMA$TIS_ERRNO_SET_VALUE 
%LINK-I-UDFSYM,         CMA$TIS_VMSERRNO_GET_ADDR 
%LINK-I-UDFSYM,         CMA$TIS_VMSERRNO_SET_ADDR 

Here is an example of linking /NOSYSSHR to the Compaq C RTL object library:


$ LINK/NOSYSSHR PROG1,SYS$LIBRARY:DECCRTL.OLB/LIBRARY/INCLUDE=CMA$TIS 

1.3.2 Behavior Differences Between the VAX C RTL and Compaq C RTL

This section describes differences in behavior between the Compaq C RTL and the VAX C RTL. Unless specifically mentioned otherwise, each difference was introduced because of the need to comply with the ANSI C Standard:


Next Contents
  

1.800.AT.COMPAQ

privacy and legal statement