HP C

Order Number: AA-PUNZM-TK

This guide describes using the HP C compiler on OpenVMS systems. It contains information on HP C program development in the OpenVMS environment, HP C features specific to OpenVMS systems, and cross-system portability concerns.

Revision/Update Information: This revised guide supersedes the
Compaq C User's Guide for OpenVMS Systems Order No. AA-PUNZL-TK, Version 6.5.

Operating System and Version: OpenVMS I64 Version 8.2 or higher
OpenVMS Alpha Version 7.3-2 or higher

Software Version: HP C Version 7.1 for OpenVMS Systems

Hewlett-Packard Company Palo Alto, California

© Copyright 2005 Hewlett-Packard Development Company, L.P.

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

UNIX is a registered trademark of The Open Group.

X/Open is a registered trademark of X/Open Company Ltd. in the UK and other countries.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in the US

This document is available on CD-ROM.

This document was prepared using DECdocument, Version V3.3-1e.

Contents

Index

This guide contains the information necessary for developing and debugging HP C (formerly Compaq C) programs on the OpenVMS operating system. HP C provides a conforming implementation of ISO/IEC 9899:1990 [1994], sometimes informally called C89, C90, ANSI C, or standard C. It also provides complete language support for ISO/IEC 9899:1999, informally called C99, although not all run-time library routines are currently implemented, floating-point environment access controls are not effective, and Annex F (the optional __STDC_IEC_559__ extension) is not supported.

HP C is a standard-conforming C compiler for the OpenVMS operating system on VAX, Alpha, and Intel® Itanium® processors and for the Tru64 UNIX® operating system on Alpha processors. HP OpenVMS Industry Standard 64 for Integrity Servers is the full product name of the OpenVMS operating system on Intel Itanium processors. The shortened forms, OpenVMS I64 and I64, are also used throughout this manual.

Through use of command-line options, HP C is compatible with older dialects of C, including common usage C and VAX C.

This guide also includes HP C language features specific to OpenVMS systems, as well as information about porting C programs to and from OpenVMS and other operating systems. For more information about porting programs to and from other operating systems, see the HP C Run-Time Library Reference Manual for OpenVMS Systems.

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

[email protected]

Intended Audience

This guide is intended for experienced programmers who need to develop HP C programs on OpenVMS systems, for users who need to know the difference between HP C and other implementations, and for experienced C users who need to reference language information specific to OpenVMS systems. You should be familiar with one high-level language and should have some familiarity with the Digital Command Language (DCL). If you are not familiar with or need to reference information about the DCL, see Chapter 1.

Document Structure

This guide has the following chapters and appendixes:

• Chapter 1 shows how to create, compile, link, and run a HP C program.
• Chapter 2 describes VAX Record Management Services (RMS).
• Chapter 3 describes interlanguage calling, and OpenVMS System Services, Run-Time Library (RTL) routines, and calling standard conventions.
• Chapter 4 describes data storage and representation on OpenVMS systems.
• Chapter 5 describes the preprocessor directives.
• Chapter 6 describes the predefined macros and the built-in functions.
• Appendix A documents the features that distinguish HP C for OpenVMS Systems from VAX C Version 3.2.
• Appendix B describes common pitfalls when using HP C.
• Appendix C provides an overview of the OpenVMS Debugger, Text Processing Utility (TPU), Language-Sensitive Editor (LSE), Source Code Analyzer (SCA), and CDD/Repository.
• Appendix D lists HP C compiler messages.
• Appendix E describes implementation-specific limits and parameters for HP C on OpenVMS systems.
• The glossary provides an alphabetical listing of key terms.

Associated Documents

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

• DEC C Migration Guide for OpenVMS VAX Systems---To help OpenVMS VAX application programmers migrate from VAX C to HP C. (VAX ONLY)
• HP C Installation Guide for OpenVMS VAX Systems---For OpenVMS system programmers who install the HP C software on VAX systems. (VAX ONLY)
• HP C Installation Guide for OpenVMS Alpha Systems---For OpenVMS system programmers who install the HP C software on Alpha systems. (ALPHA ONLY)
• HP C Language Reference Manual---Provides language reference information for HP C on HP systems.
• HP C Run-Time Library Reference Manual for OpenVMS Systems---Provides information on using the HP C Run-Time Library (RTL) functions and macros, and information about porting programs to and from other operating systems.
• The C Programming Language by Ritchie ---Provides an excellent tutorial of the C language. Because HP C contains features and enhancements to the standard C language, use the HP C User's Guide for OpenVMS Systems and the HP C Language Reference Manual as the reference books for the full description of HP C.
• HP OpenVMS Calling Standard---Describes the concepts used by all OpenVMS languages to invoke routines and pass data between them. It also describes the differences between the OpenVMS VAX, Alpha, and I64 parameter-passing mechanisms.

Conventions Used in this Document

Table 1 lists the conventions used in this guide.

Table 1 Conventions Used in this Guide

Convention	Meaning
HP OpenVMS Industry Standard 64 for Integrity Servers, OpenVMS I64, I64	The variant of the OpenVMS operating system that runs on the Intel Itanium architecture.
OpenVMS systems	Refers to the OpenVMS operating system on all supported platforms, unless otherwise specified.
[Return]	The symbol [Return] represents a single stroke of the Return key on a terminal.
Ctrl/X	The symbol Ctrl/X, where the letter X represents a terminal control character, is generated by holding down the Ctrl key while pressing the key of the specified terminal character.
switch statement fprintf function auto storage class	In syntax definitions, items appearing in monospaced type identify language keywords and the names of OpenVMS and HP C Run-Time Library functions.
arg1	Italic type indicates a placeholder, such as an argument or parameter name, and the introduction of new terms.
$ RUN CPROG [Return]	Interactive examples show user input in boldface type.
float x; . . . x = 5;	A vertical ellipsis indicates that not all of the text of a program or program output is illustrated. Only relevant material is shown in the example.
option,...	A horizontal ellipsis indicates that additional parameters, options, or values can be entered. A comma that precedes the ellipsis indicates that successive items must be separated by commas.
[output-source,...]	Square brackets, in function synopses and a few other contexts, indicate that a syntactic element is optional. Square brackets are not optional, however, when used to delimit a directory name in an OpenVMS file specification or when used to delimit the dimensions of an array in HP C source code.
sc-specifier ::= auto static [extern] register	In syntax definitions, items appearing on separate lines are mutually exclusive alternatives.
{a|b}	Braces surrounding two or more items separated by a vertical bar (|) indicate a choice; you must choose one of the two syntactic elements.

Platform Labels

A platform is a combination of operating system and hardware that provides a distinct environment. This guide contains information applicable to the HP OpenVMS operating system on VAX, Alpha, and Intel Itanium processors.

The information in this guide applies to all of these processors, except when specifically labeled as follows:

Label	Explanation
(ALPHA ONLY)	Specific to an Alpha processor running the OpenVMS operating system.
(VAX ONLY)	Specific to a VAX processor running the OpenVMS operating system.
(I64 ONLY)	Specific to an Intel Itanium processor running the OpenVMS operating system. On this platform, the product name of the operating system is OpenVMS Industry Standard 64 (or its abbreviated forms, OpenVMS I64 or I64).

New and Changed Features

HP C Version 7.1 runs on OpenVMS Alpha and OpenVMS Industry Standard 64 systems. The compiler behaves much the same on both systems, with some differences, primarily in the support for #pragma linkage , built-in functions, default floating-point representation, and predefined macros. These differences are noted in the relevant sections of this manual.

This chapter describes the following information about developing HP C programs on an OpenVMS system:

• Overview of the DIGITAL Command Language (DCL) commands used for program development ( Section 1.1)
• Creating HP C programs ( Section 1.2)
• Compiling HP C programs ( Section 1.3)
• Linking HP C programs ( Section 1.4)
• Running HP C programs ( Section 1.5)
• Passing arguments to the main function ( Section 1.6)
• Using 64-bit addressing ( Section 1.7)

1.1 DCL Commands for Program Development

This section provides a brief overview of the DCL commands used for program development. The following sections provide more detailed information about these topics.

Figure 1-1 shows the basic steps in HP C program development.

Figure 1-1 DCL Commands for Developing Programs

To create an HP C source program at DCL level, you must invoke a text editor. In Figure 1-1, the EDIT command invokes the default editor TPU (OpenVMS Text Processing Utility) to create the source program AVERAGE.C. You can use another editor, such as EDT or the HP Language-Sensitive Editor (LSE). (LSE is a product that must be purchased separately; see Appendix C for more information.) A file type of C is used to indicate that you are creating an HP C source program. C is the conventional file type for all HP C source programs.

When you compile your program with the CC command, you do not have to specify the file type; by default, HP C searches for files with a file type of C.

If your source program compiles successfully, the HP C compiler creates an object file with the file type OBJ.

However, if the HP C compiler detects errors in your source program, the system displays each error on your screen and then displays the DCL prompt. You can then reinvoke your text editor to correct each error.

You can specify command qualifiers on the CC command. Command qualifiers cause the HP C compiler to perform additional actions. In the following example, the /LIST qualifier causes the HP C compiler to produce the listing file AVERAGE.LIS:

$ CC/LIST AVERAGE

For a complete description of all CC command qualifiers, see Section 1.3.4.

After your program has compiled successfully, invoke the OpenVMS Linker to create an executable image file. For example:

$ LINK AVERAGE

The linker uses the object file produced by HP C as input to produce an executable image file as output. (The executable image is a file containing program code that can be run on the system.)

You can specify command qualifiers with the DCL command LINK. For a complete list and explanation of all the command qualifiers available with the LINK command, see Section 1.4.2.

After producing the executable image file, use the RUN command to execute your program.

1.2 Creating an HP C Program

To create and modify an HP C program, you must invoke a text editor. The OpenVMS system provides you with two text editors: EDT and the OpenVMS Text Processing Utility (TPU). The following section discusses TPU. See the OpenVMS EDT Reference Manual for more information on EDT.

1.2.1 Using TPU

TPU is a high-performance, programmable utility. It provides two editing interfaces: the Extensible VAX Editor (EVE), described in the following section, and the TPU EDT Keypad Emulator. You can also create your own interfaces.

Like EDT, TPU provides you with an online help facility that you can access during your editing session. When you invoke TPU to create a file, a journal file is automatically created. You can use this journal file to recover your edits if the system fails during an editing session. To recover your edits, enter the EVE/RECOVER command.

Unlike EDT, TPU provides multiple windows. This feature allows you to view two files on your screen at the same time.

1.2.2 The EVE Interface to TPU

EVE is an interactive text editor that allows you to execute common editing functions using the EVE keypad or to execute more advanced functions by entering commands on the EVE command line. The following command line invokes the EVE editor and creates the file PROG_1.C:

$ EDIT/TPU PROG_1.C

You can define a global symbol for the EDIT/TPU command by placing a symbol definition in your LOGIN.COM file. For example:

$ EVE == "EDIT/TPU"

After this command line is executed, you can type EVE at the DCL prompt followed by the name of the file you want to modify or create.

For more information on using EVE, see the Guide to VMS Text Processing.

1.3 Compiling an HP C Program

The HP C compiler performs the following functions:

• Detects errors in your source program
• Displays each error on your screen or writes the errors to a file
• Generates machine-language instructions from the source
  statements
• Groups these machine-language instructions into an object module for the linker

The following sections discuss the CC command and its qualifiers.

1.3.1 The CC Command

To invoke the HP C compiler, enter the CC command at the DCL prompt ($). The CC command has the following format:

CC[/qualifier...][ file-spec [/qualifier...]],...

/qualifier

An action to be performed by the compiler on all files or specific files listed. When a qualifier appears directly after the CC command, it affects all the files listed. When a qualifier appears after a file specification, it affects only the file that immediately precedes it. However, when files are concatenated, these rules do not apply.

file-spec

An input source file that contains the program or module to be compiled. You are not required to specify a file type if you give your file a .C file extension; the HP C compiler adopts the default file type C.

You can include more than one file specification on the same command line by separating the file specifications with either a comma (,) or a plus sign (+). If you separate the file specifications with commas, you can control which source files are affected by each qualifier. In the following example, the HP C compiler creates an object file for each source file but creates only a listing file for the source files PROG_1 and PROG_3:

$ CC /LIST PROG_1, PROG_2/NOLIST, PROG_3

If you separate file specifications with plus signs, the HP C compiler concatenates each of the specified source files and creates one object file and one listing file. In the following example, only one object file is created, PROG_1.OBJ, and only one listing file is created, PROG_1.LIS. Both of these files are named after the first source file in the list, but contain all three modules.

$ CC PROG_1 + PROG_2/LIST + PROG_3

Any qualifiers specified for a single file within a list of files separated with plus signs affect all the files in the list. See the description of the /PLUS_LIST_OPTIMIZE qualifier for its affect on file concatenation.

A more common use of plus-list concatenation is for specifying text libraries. You can specify the name of a text library on the CC command line to compile a source program. A text library is a file that contains text organized into modules indexed by a table. Text libraries have a .TLB default file extension. In the following example, text libraries A.TLB and B.TLB are made available for searching for text library modules during the compilation of source file TEST.C:

$ CC TEST.C + A.TLB/LIB + B.TLB/LIB

1.3.1.1 Including Header Files

Header files are pieces of source code that typically contain declarations shared among C programs. A header file often declares a set of related functions, as well as defining any types and macros needed for their use.

To make the contents of a header file available to your program, include the header file using the #include preprocessor directive.

The #include directive has three forms. Two of the forms are defined by the C standard and are portable:

• Inclusion using angle brackets to delimit the file to be included:

  #include <file-spec>

• Inclusion using quotation marks to delimit the file to be included:

  #include "file-spec"

The third form is the text-module form. It is specific to OpenVMS systems and is not portable. See Section 5.2.3 for more information on the text-module form of inclusion.

The form of the #include directive used determines where the compiler will look to find the file to be included. Generally, the compiler looks in the following places, in the order listed:

1. Places named on the command line with the /INCLUDE_DIRECTORY qualifier or the /LIBRARY qualifier
2. Places identified through logical names, such as DECC$USER_INCLUDE, DECC$SYSTEM_INCLUDE, DECC$LIBRARY_INCLUDE, and DECC$TEXT_LIBRARY
3. System-defined places such as the SYS$COMMON:[DECC$LIB.INCLUDE.*] directory and the SYS$LIBRARY:DECC$RTLDEF.TLB and SYS$LIBRARY:SYS$STARLET_C.TLB text libraries

You can use the UNUSED message group described in the #pragma message description in Section 5.4.14 to enable messages that report apparently unnecessary #include files (and CDD records). Unlike any other messages, these messages must be enabled on the command line (/WARNINGS=ENABLE=UNUSED), rather than with #pragma message , to be effective.

The HP C preprocessor is usually able to determine if a particular #include file that has already been processed once was guarded by the conventional sequence: #ifndef FILE_SEEN, #define FILE_SEEN, #endif .

When the compiler detects this pattern of use the first time a particular file is included, it remembers that fact as well as the name of the macro. The next time the same file is included, the compiler checks to see if the "FILE_SEEN" macro is still defined and, if so, it does not reopen and reread the file. Note that if the initial test is in the form #if !defined instead of #ifndef , then the pattern is not recognized. In a listing file, #include directives that are skipped because of this processing are marked with an "X" just as if the #include line itself were excluded.

See the /INCLUDE_DIRECTORY qualifier in Section 1.3.4 for a more complete description of the search-order rules that HP C uses to locate included files.

See the HP C Run-Time Library Reference Manual for OpenVMS Systems for information on the header files required to use HP C Run-Time Library (RTL) functions and macros.