Compaq C
User's Guide for OpenVMS Systems

The parameter option2 must be one of the following keywords:

• save ---Saves the current state of which messages are enabled and disabled.
• restore ---Restores the previous state of which messages are enabled and disabled.

The save and restore options are useful primarily within header files.

5.4.13.3 #pragma message (quoted-string)

This form of #pragma message is provided for compatibility with Microsoft's #pragma message directive.

The #pragma message (quoted-string) form of this directive emits the specified string as a compiler message. For example, when the compiler encounters the following line in the source file:

#pragma message ("hello")

It emits:

#pragma message ("hello") ................^ %CC-I-SIMPLEMESSAGE, hello at line number 1 in file DISK1$:[SMITH]TEST.C;1

This form of the pragma is subject to macro replacement. For example, the following is allowed:

#pragma message ("Compiling file " __FILE__)

5.4.14 #pragma module Directive

When you compile source files to create an object file, the compiler assigns the first of the file names specified in the compilation unit to the name of the object file. The compiler adds the .OBJ file extension to the object file. Internally, the OpenVMS system (the debugger and the librarian) recognizes the object module by the file name; the compiler also gives the module a version number of 1. For example, given the object file EXAMPLE.OBJ, the debugger recognizes the EXAMPLE object module.

To change the system-recognized module name and version number, use the #pragma module directive. The #pragma module directive is specific to Compaq C for OpenVMS systems and is not portable.

You can find the module name and the module version number listed in the compiler listing file and the linker load map.

The #pragma module directive is equivalent to the VAX C compatible #module directive. The #pragma module directive may be used when compiling in any mode. Use #module only when compiling with the /STANDARD=VAXC qualifier.

The #pragma module directive has the following formats:

#pragma module identifier identifier #pragma module identifier string

The first parameter must be a valid Compaq C identifier. It specifies the module name to be used by the linker. The second parameter specifies the optional identification that appears on listings and in the object file. It must be either a valid Compaq C identifier of 31 characters or less, or a character-string constant of 31 characters or less.

Only one #pragma module directive can be processed per compilation unit, and that directive must appear before any C language text. The #pragma module directive can follow other directives, such as #define , but it must precede any function definitions or external data definitions.

The parameters in a #pragma module directive are subject to text replacement and can, therefore, contain references to identifiers defined in previous #define directives. The replacement occurs before the parameters are processed.

5.4.15 #pragma names Directive

The #pragma names preprocessor directive provides the same kinds of control over the mapping of external identifiers' object-module symbols as does the /NAMES command-line qualifier, and it uses the same keywords (except that the lowercase keyword is not supported). But as a pragma, the controls can be applied selectively to regions of declarations.

This pragma should only be used in header files and is intended for use by developers who supply libraries and/or header files to their customers.

The pragma has a save / restore stack that is also managed by #pragma environment , and so it is well-suited for use in header files. The effect of #pragma environment header_defaults is to set NAMES to uppercase,truncated , which is the compiler default.

The #pragma names directive has the following format:

#pragma names stack-option #pragma names case-option[, length-option] #pragma names length-option[, case-option]

Where stack-option is one of the following keywords:

• save - save the current names state
• restore - restore a saved names state

case-option is one of the following keywords:

• uppercase - uppercase external names
• as_is - do not change case

length-optionis one of the following keywords:

• truncated - truncate at 31 characters
• shortened - shorten to 31 using CRC

An important use for this feature is to make it easier to use the command-line option /NAMES=AS_IS. Both the C99 standard and the C++ standard require that external names be treated as case-sensitive, and 3rd party libraries and Java native methods are starting to rely on case-sensitivity (C99 requires a minimum of 31 characters significant, while C++ requires all characters significant). Therefore, the use of /NAMES=AS_IS is expected to become more widespread.

The Compaq C run-time library is implemented with all symbols duplicated, spelled both in uppercase and lowercase, to allow C programs compiled with any of the /NAMES= settings to work. But traditional practice on OpenVMS systems, combined with compiler defaults of /NAMES=UPPER, has resulted in nearly all existing object libraries and shared images to contain all uppercase names (both in references and in definitions), even though C source code using these libraries typically declares the names in lowercase or mixed case. Usually, the header files to access these libraries contain macro definitions to replace lowercase names by uppercase names to allow client programs to be compiled /NAMES=AS_IS. But macro definitions are problematic because every external name has to have a macro.

The new pragma allows header files to specify just once that the external names they declare are to be uppercased in the object module, regardless of the NAMES setting used in the rest of the compilation. The NAMES setting in effect at the first declaration of an external name is the one that takes effect; therefore, the setting specified in a header file is not overridden by a subsequent redeclaration in the user's program (which might specify a different NAMES setting). Note that the automatic Prologue/Epilogue header-file inclusion feature described in Section 1.7.4 (in connection with pointer_size pragmas) can also be used to specify the NAMES setting for all headers in a given directory or text library, without having to edit each header directly.

5.4.16 #pragma optimize Directive (ALPHA ONLY)

The #pragma optimize preprocessor directive sets the optimization characteristics of function definitions that follow the directive. It allows optimization-control options that are normally set on the command line for the entire compilation to be specified in the source file for individual functions.

The #pragma optimize directive has the following format:

#pragma optimize settings #pragma optimize save #pragma optimize restore #pragma optimize command_line

Where settings is any combination of the following:

• level settings
  These set the optimization level. Specify the level as follows:

  level=n

  
  Where n is an integer from 0 to 5.

• unroll settings
  These control loop unrolling. Specify as follows:

  unroll=n

  
  Where n is a nonnegative integer.

• ansi-alias settings
  These control ansi-alias assumptions. Specify one of the following:

  ansi_alias=on ansi_alias=off

• intrinsic settings
  These control recognition of intrinsics: Specify one of the following:

  intrinsics=on intrinsics=off

Whitespace is optional between the setting clauses and before and after the "=" in each clause. The pragma is not subject to macro replacement.

For more information on the optimization settings, see Table 1-16 in the description of the /OPTIMIZE qualifier in Section 1.3.4.

Example:

#pragma optimize level=5 unroll=6

The save and restore options save and restore the current optimization state (level, unroll count, ansi-alias setting, and intrinsic setting).

The command_line option sets the optimization settings to what was specified on the command line.

5.4.17 #pragma pack Directive

The #pragma pack preprocessor directive specifies the byte boundary for packing members of C structures.

The #pragma pack directive has the following format:

#pragma pack n #pragma pack ()

The n specifies the new alignment restriction in bytes:

1	align to byte
2	align to word
4	align to longword
8	align to quadword
16	align to octaword

A structure member is aligned to either the alignment specified by #pragma pack or the alignment determined by the size of the structure member, whichever is smaller. For example, a short variable in a structure gets byte-aligned if #pragma pack 1 is specified, but word-aligned if #pragma pack 2 , 4 , or 8 is specified.

When #pragma pack is specified without a value or with a value of 0, packing reverts to the /[NO]MEMBER_ALIGNMENT qualifier setting (either explicitly specified or by default) on the command line. Note that when specifying #pragma pack without a value, you must use parentheses: #pragma pack () .

Compaq C also supports the Microsoft Visual C++ enhanced syntax of this pragma:

#pragma pack ( { [ {push|pop} [ ,identifier ] [ ,n ] ] | [ n ] } )

With this enhanced syntax, you can save and restore packing alignment values across program components. This allows you to combine components into a single translation unit even if they specify different packing alignments:

• Every occurrence of pragma pack with a push argument stores the current packing alignment value on an internal compiler stack. If you provide a value for n, that value becomes the new packing value. If you specify an identifier, a name of your choosing, it is associated with the new packing value.
• Every occurrence of a pragma pack with a pop argument retrieves the value at the top of the stack and makes that value the new packing alignment. If an empty stack is popped, the alignment value defaults to the /[NO]MEMBER_ALIGNMENT command-line setting, and a warning is issued. If you specify a value for n, that value becomes the new packing value.
  If you specify an identifier, all values stored on the stack are removed from the stack until a matching identifier is found. The packing value associated with the identifier is also removed from the stack, and the packing value that was in effect just before the identifier was pushed becomes the new packing value. If no matching identifier is found, the packing value reverts to the command-line setting, and a warning is issued.

The enhanced syntax of pragma pack lets you write header files that ensure that packing values are the same before and after the header file is encountered. Consider the following example:

// File name: myinclude.h // #pragma pack( push, enter_myinclude ) // Your include-file code ... #pragma pack( pop, enter_myinclude ) // End of myinclude.h

In this example, the current packing value is associated with the identifier enter_myinclude and pushed on entry to the header file. Your include code is processed. The #pragma pack at the end of the header file then removes all intervening packing values that might have occurred in the header file, as well as the packing value associated with enter_myinclude , thereby preserving the same packing value after the header file as before it.

The enhanced pragma pack syntax also lets you include header files that might set packing alignments different from the ones set in your code. Consider the following example:

#pragma pack( push, before_myinclude ) #include <myinclude.h> #pragma pack( pop, before_myinclude )

In this example, your code is protected from any changes to the packing value that might occur in <myinclude.h> by saving the current packing alignment value, processing the include file (which may leave the packing alignment with an unknown setting), and restoring the original packing value.

5.4.18 #pragma pointer_size Directive (ALPHA ONLY)

The #pragma pointer_size preprocessor directive can be used throughout a program to control whether pointers are 32-bit pointers or 64-bit pointers.

This directive has the same effect as the #pragma required_pointer_size directive, except that #pragma pointer_size is enabled only when the /POINTER_SIZE command-line qualifier is specified. If /POINTER_SIZE is omitted from the command line, #pragma pointer_size is ignored. (The #pragma required_pointer_size directive always takes effect, whether or not /POINTER_SIZE is specified.)

The #pragma pointer_size directive has the following format:

#pragma pointer_size keyword

The keyword is one of the following:

{ short |32}	32-bit pointer
{ long |64}	64-bit pointer
system_default	32-bit pointers on OpenVMS systems; 64-bit pointers on Tru64 UNIX systems
save	Saves the current pointer size
restore	Restores the current pointer size to its last saved state

The #pragma required_pointer_size preprocessor directive is intended for use by developers of header files to control the size of pointers within a header file in those cases where the pointers are architecturally required to be a particular size, and must not be altered by the user's use of pointer-size controls.

This directive has the same effect as the #pragma pointer_size directive, except that a #pragma required_pointer_size always takes effect, even if /POINTER_SIZE is omitted from the command line. (The #pragma pointer_size directive is ignored if /POINTER_SIZE is omitted.)

The #pragma required_pointer_size directive has the following format:

#pragma required_pointer_size keyword

The keyword is one of the following:

{ short |32}	32-bit pointer
{ long |64}	64-bit pointer
system_default	32-bit pointers on OpenVMS systems; 64-bit pointers on Tru64 UNIX systems
save	Saves the current pointer size
restore	Restores the current pointer size to its last saved state