Order Number: AA--Q5AVB--TE

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

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

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:

• Chapter 1 describes how to migrate from the VAX C Run-Time Library (RTL) to the Compaq C RTL.
• Chapter 2 describes how to port your VAX C applications to Compaq C.

Associated Documents

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

• Compaq C Installation Guide for OpenVMS VAX Systems---For OpenVMS system programmers who install the Compaq C software on VAX systems.
• Compaq C User's Guide for OpenVMS Systems---Provides C programmers with information on using Compaq C for OpenVMS Systems. This guide contains a New and Changed Features appendix that you might find useful. This appendix summarizes the features that distinguish Compaq C for OpenVMS Systems from VAX C Version 3.2.
• Compaq C Language Reference Manual---Provides language reference information for Compaq C on Compaq systems.
• Compaq C Run-Time Library Reference Manual for OpenVMS Systems---Provides information on using the Compaq C RTL functions and macros, and information about porting programs to and from other operating systems.
• The C Programming Language¹---Provides an excellent tutorial of the ANSI Standard C language.
• Release Notes---Please read the following release notes for additional information and last-minute bulletins about Compaq C and the Compaq C RTL:
  • Compaq C Version 6.2 for OpenVMS VAX Release Notes
  • Release Notes for your version of OpenVMS VAX
  • Compaq C/C++ Run-Time Components for OpenVMS VAX Version 6.0-1 Release Notes

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

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:

• The VAX C RTL will remain unchanged from its Version 5.5-2 release.
• New features, functions, and bug fixes are available only with the Compaq C RTL. Some of these include:
  • ANSI C Standard conformance
  • Improved performance
  • Support for DECthreads
  • Improved routine reentrancy
  • Resolution of many VAX C RTL bugs
• Using the Compaq C RTL provides better portability. Because the Compaq C RTL conforms to the ANSI C Standard, you can develop ANSI C conformant programs that can be ported to any other platform that has an ANSI C conformant environment. Also, the Compaq C RTL on OpenVMS VAX systems is almost the same as the Compaq C RTL on OpenVMS Alpha systems. Therefore, a project that ports to OpenVMS Alpha is better able to have a common code base if it migrates to the Compaq C RTL on OpenVMS VAX systems.

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:

• The application is not under active development.
• The application is tied to VAX C behavior that is incompatible with Compaq C behavior.

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

• Migrating using the Compaq C compiler ( Section 1.2.1)
• Migrating VAX C code using shareable images ( Section 1.2.2)
• Migrating VAX C code using object libraries ( Section 1.2.3)

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:

• Compile with the /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES qualifier.
• Compile with the /STANDARD=VAXC or /STANDARD=COMMON qualifier; you get /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES as the default.

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
• VAXCG2DECC.EXE

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":

• DECCRTL.OLB replaces VAXCRTL.OLB
• DECCRTLG.OLB replaces VAXCRTLG.OLB
• DECCCURSE.OLB replaces VAXCCURSE.OLB

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

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:

• The ANSI C Standard-defined behavior for negated scansets in the scanf function is different from the VAX C RTL behavior. The ANSI C Standard requires at least one character to match a negated scanset; the VAX C RTL allowed no characters to match. For example, the following code fails if it encounters an empty line:

  /* read lines and throw away the newline */ fscanf("%[^\n]%*c", &string);

  
  The Compaq C RTL requires the code to be implemented as follows:

  /* read lines and throw away the newline */ if (fscanf("%[^\n]%*c", &string) == 0 ) fscanf("%*c"); /* swallow blank-line newline */

• The ANSI C Standard padding rules for the printf routines are different than the VAX C RTL behavior. Table 1-1 shows examples of the new and old behavior.
• The ANSI C Standard rules for the output of floating-point numbers is different from the (VAX C RTL behavior, so that a digit of precision can be lost. Table 1-1 shows examples of the old and new behavior.
• The ANSI C Standard requires that an empty precision value in a printf format specifier be treated as a zero precision. The VAX C RTL ignores an empty precision value. Table 1-1 shows an example of the new behavior.

  Table 1-1 Changes in printf Behavior Required by ANSI

  Example	VAX C RTL	Compaq C RTL
  printf("%04.2d", 77)	"0077"	" 77"
  printf("%6.4d", 77)	" 77"	" 0077"
  printf("%.2g", 9.876e+2)	"9.88e+02"	"9.9e+02"
  printf("%-.s", "hello")	"hello"	""

• Exit handlers established by atexit are not executed when abort is called.
• Files containing binary data that are opened with stream I/O must specify "ctx=bin" on the open , fopen , or creat call. (This is a bug fix, not an ANSI C requirement.)
• Files opened in append mode always have writes forced to End-of-File (EOF). With the VAX C RTL, the behavior of files opened in append mode was to start at EOF and, thereafter, write at the current file position.
• Files opened for write access default to exclusive file sharing mode. With VAX C, files are opened with the "shr=get" option set by default.
• A call to ungetc clears the EOF flag for the file.
• A call to a file position routine (for example, fseek ) clears the EOF flag for the file.
• The EOF flag for a file is always cleared when the file is first opened. The VAX C RTL sets the EOF flag to true if the file opened was empty.
• A call to a file position routine (for example, fseek ) now causes the character pushed back by a call to ungetc to be lost.
• The C signal SIGABRT is defined to be equal to the SIGIOT signal rather than to SIGILL as in the VAX C RTL. Programs that look for the SS$_OPCDEC exception to prevent an abort from occurring will fail. The exception to look for is now SS$_OPCCUS.
• The value of the Compaq C RTL constant BUFSIZ is 8192, compared with 512 for VAX C. This changes the behavior of setvbuf and setbuf for both Compaq C and VAX C:
  • setvbuf ignores buffers smaller than BUFSIZ. This results in the user's buffer not being used; the previous buffer or default buffer gets used.
  • A program that links with the Compaq C RTL and calls setbuf with a pointer to a buffer smaller than 8192 bytes will not execute properly because the Compaq C RTL writes past the end of the buffer. VAX C programs that link to the Compaq C RTL using VAXC2DECC.EXE or VAXCG2DECC.EXE will execute properly but will not benefit from the larger buffer size.
  
  This change was made to improve Compaq C RTL I/O performance.
• The gets and fgets functions no longer null-terminate the input buffer when EOF is encountered and no characters have been read since the last read operation.
• The Compaq C RTL I/O functions allow the writing of 0-length records. Passing a length of 0 to write and fwrite now results in an empty record; the VAX C RTL would do nothing. This change was requested by users.
• The signal function now returns SIG_ERR on error. This should not affect the behavior of programs that check for --1.
• If the parameter to fflush is NULL, all buffers associated with all currently open files are flushed.
• File positioning (for example, fseek ) is now allowed on files opened in append mode.
• ftell now reports a file position that takes into account the character pushed back by a call to ungetc .
• The Compaq C RTL will not accept uppercase versions of printf and scanf format specifiers. That is, the Compaq C RTL will not accept "%D" as a format specifier, whereas the VAX C RTL accepts "%D" as a synonym for the "%d" format specifier. The Compaq C RTL prints the letter encountered; for example, "%D" produces the letter 'D' in the output stream rather than being processed as an output source.
• The Compaq C RTL allows file positioning calls to seek to an arbitrary byte with fixed-length record files. The VAX C RTL treats fixed-length record files like all record files and only allows file positioning to record boundaries. This change was requested by users.
• In Compaq C, the sleep function wakes prematurely if a signal is received.

privacy and legal statement