HP C
User's Guide for OpenVMS Systems

OpenVMS VAX Systems (VAX ONLY)

On OpenVMS VAX systems, representation of double variables defaults to D_floating format if not overridden by another format specified with the /FLOAT or /[NO]G_FLOAT qualifier. There is one exception: if /STANDARD=MIA is specified, G_floating is the default. If you are linking against object-module libraries, a program compiled with G_floating format must be linked with the object library DECCRTLG.OLB. (VAX ONLY)

OpenVMS Alpha Systems (ALPHA ONLY)

On OpenVMS Alpha systems, representation of double variables defaults to G_floating format if not overridden by another format specified with the /FLOAT or /[NO]G_FLOAT qualifier.

If you are linking against object-module libraries, and /PREFIX=ALL is not specified on the command line, then a program compiled with:

• G_FLOAT format must be linked with the object library VAXCRTL.OLB
• D_FLOAT format must be linked with VAXCRTLD.OLB
• IEEE_FLOAT format must be linked with VAXCRTLT.OLB

The VAXCRTLX.OLB, VAXCRTLDX.OLB, and VAXCRTLTX.OLB libraries are used for the same floating-point formats, respectively, but include support for X_FLOAT format (/L_DOUBLE_SIZE=128).

If /PREFIX=ALL is specified, then there is no need to link to the above-mentioned *.OLB object libraries. All the symbols you need are in STARLET.OLB.

I64 Systems (I64 ONLY)

This section describes floating-point support and application porting considerations for I64 systems.

On OpenVMS I64 systems, /FLOAT=IEEE_FLOAT is the default floating-point representation. IEEE format data is assumed and IEEE floating-point instructions are used. There is no hardware support for floating-point representations other than IEEE, although you can specify the /FLOAT=D_FLOAT or /FLOAT=G_FLOAT compiler option. These VAX floating-point formats are supported in the I64 compiler by generating run-time code that converts VAX floating-point formats to IEEE format to perform arithmetic operations, and then converts the IEEE result back to the appropriate VAX floating-point format. This imposes additional run-time overhead and some loss of accuracy compared to performing the operations in hardware on Alpha and VAX systems. The software support for the VAX formats is provided to meet an important functional compatibility requirement for certain applications that need to deal with on-disk binary floating-point data.

On I64 systems, the default for /IEEE_MODE is DENORM_RESULTS, which is a change from the default of /IEEE_MODE=FAST on Alpha systems. This means that by default, floating-point operations may silently generate values that print as Infinity or Nan (the industry-standard behavior), instead of issuing a fatal run-time error as they would when using VAX floating-point format or /IEEE_MODE=FAST. Also, the smallest-magnitude nonzero value in this mode is much smaller because results are allowed to enter the denormal range instead of being flushed to zero as soon as the value is too small to represent with normalization.

The conversion of VAX floating-point formats to IEEE single and IEEE double floating-point types on the Intel Itanium architecture is a transparent process that will not impact most applications. All you need to do is recompile your application. Because IEEE floating-point format is the default, unless your build explicitly specifies VAX floating-point format options, a simple rebuild for I64 systems will use the native IEEE formats directly. For the large class of programs that do not directly depend on the VAX formats for correct operation, this is the most desirable way to build for I64 systems.

When you compile an OpenVMS application that specifies an option to use VAX floating-point on an I64 system, the compiler automatically generates code for converting floating-point formats. Whenever the application performs a sequence of arithmetic operations, this code does the following:

1. Converts VAX floating-point formats to either IEEE single or IEEE double floating-point formats.
2. Performs arithmetic operations in IEEE floating-point arithmetic.
3. Converts the resulting data from IEEE formats back to VAX formats.

Where no arithmetic operations are performed (VAX float fetches followed by stores), no conversion will occur. The code handles such situations as moves.

VAX floating-point formats have the same number of bits and precision as their equivalent IEEE floating-point formats. For most applications the conversion process will be transparent and thus a non-issue.

In a few cases, arithmetic calculations might have different results because of the following differences between VAX and IEEE formats:

• Values of numbers represented
• Rounding rules
• Exception behavior

These differences might cause problems for applications that do any of the following:

• Depend on exception behavior
• Measure the limits of floating-point behaviors
• Implement algorithms at maximal processor-specific accuracy
• Perform low-level emulations of other floating-point processors
• Use direct equality comparisons between floating-point values, instead of appropriately ranged comparisons (a practice that is extremely vulnerable to changes in compiler version or compiler options, as well as architecture)

You can test an application's behavior with IEEE floating-point values by compiling it on an OpenVMS Alpha system using /FLOAT=IEEE_FLOAT/IEEE_MODE=DENORM. If that produces acceptable results, then simply build the application on the OpenVMS I64 system using the same qualifier.

If you determine that simply recompiling with an /IEEE_MODE qualifier is not sufficient because your application depends on the binary representation of floating-point values, then first try building for your I64 system by specifying the VAX floating-point option that was in effect for your VAX or Alpha build. This causes the representation seen by your code and on disk to remain unchanged, with some additional run-time cost for the conversions generated by the compiler. If this is not an efficient approach for your application, you can convert VAX floating-point binary data in disk files to IEEE floating-point formats before moving the application to an I64 system.

/GRANULARITY=option

Controls the size of shared data in memory that can be safely accessed from different threads. The possible size values are BYTE, LONGWORD, and QUADWORD.

Specifying BYTE allows single bytes to be accessed from different threads sharing data in memory without corrupting surrounding bytes. This option will slow run-time performance.

Specifying LONGWORD allows naturally aligned 4-byte longwords to be accessed safely from different threads sharing data in memory. Accessing data items of 3 bytes or less, or unaligned data, may result in data items written from multiple threads being inconsistently updated.

Specifying QUADWORD allows naturally aligned 8-byte quadwords to be accessed safely from different threads sharing data in memory. Accessing data items of 7 bytes or less, or unaligned data, might result in data items written from multiple threads being inconsistently updated. This is the default.

/IEEE_MODE=option

Table 1-10 describes the /IEEE_MODE options.

Table 1-10 /IEEE_MODE Options

Option	Usage
FAST	During program execution, only finite values (no infinities, NaNs, or denorms) are created. Underflows and denormal values are flushed to zero. Exceptional conditions, such as floating-point overflow, divide-by-zero, or use of an IEEE exceptional operand are fatal.
UNDERFLOW_TO_ZERO	Generate infinities and NaNs. Flush denormalized results and underflow to zero without exceptions.
DENORM_RESULTS	Same as UNDERFLOW_TO_ZERO, except that denorms are generated.
INEXACT	Same as DENORM_RESULTS, except that inexact values are trapped. This is the slowest mode, and is not appropriate for any sort of general-purpose computations.

On Alpha systems, the default is /IEEE_MODE=FAST.

On I64 systems, the default is /IEEE_MODE=DENORM_RESULTS.

The INFINITY and NAN macros defined in <math.h> are available to programs compiled with /FLOAT=IEEE and /IEEE_MODE={anything other than FAST}, and in a compiler mode that enables C99 extensions in the headers (any mode other than COMMON or VAXC).

On Alpha sytems, the /IEEE_MODE qualifier generally has its greatest effect on the generated code of a compilation. When calls are made between functions compiled with different /IEEE_MODE qualifiers, each function produces the /IEEE_MODE behavior with which it was compiled.

On I64 systems, the /IEEE_MODE qualifier primarily affects only the setting of a hardware register at program startup. In general, the /IEEE_MODE behavior for a given function is controlled by the /IEEE_MODE option specified on the compilation that produced the main program: the startup code for the main program sets the hardware register according the command-line qualifiers used to compile the main program.

When applied to a compilation that does not contain a main program, the /IEEE_MODE qualifier does have some effect: it might affect the evaluation of floating-point constant expressions, and it is used to set the EXCEPTION_MODE used by the math library for calls from that compilation. But the qualifier has no effect on the exceptional behavior of floating-point calculations generated as inline code for that compilation. Therefore, if floating-point exceptional behavior is important to an application, all of its compilations, including the one containing the main program, should be compiled with the same /IEEE_MODE setting.

Even on Alpha systems, the particular setting of /IEEE_MODE=UNDERFLOW_TO_ZERO has this characteristic: its primary effect requires the setting of a run-time status register, and so it needs to be specified on the compilation containing the main program in order to be effective in other compilations.

/[NO]INCLUDE_DIRECTORY=(pathname[,...])

• OpenVMS file-spec to be used as a default file-spec to RMS file services (example: DISK$:[directory])
• UNIX style pathname in quotation marks (example: "/sys")
• Empty string ("")

If one of the places is specified as an empty string, the compiler does not search any of its conventionally-named places:

DECC$USER_INCLUDE
DECC$SYSTEM_INCLUDE
DECC$LIBRARY_INCLUDE
SYS$COMMON:[DECC$LIB.INCLUDE.*]
DECC$TEXT_LIBRARY
SYS$LIBRARY:DECC$RTLDEF.TLB
SYS$LIBRARY:SYS$STARLET_C.TLB

Instead, it searches only places specified explicitly on the command line by the /INCLUDE_DIRECTORY and /LIBRARY qualifiers (or by the location of the primary source file, depending on the /NESTED_INCLUDE_DIRECTORY qualifier). This behavior is similar to that obtained by specifying -I without a directory name to the Tru64 UNIX cc command.

The basic search order depends on the form of the header-file name (after macro expansion). Additional aspects of the search order are controlled by other command-line qualifiers and the presence or absence of logical name definitions.

Only the portable forms of the #include directive are affected by the pathnames specified on an /INCLUDE_DIRECTORY qualifier:

• In quotes (example: #include "stdio.h" )
• In angle brackets (example: #include <stdio.h> )

However, an empty string also affects the text-module form specific to OpenVMS systems (example: #include stdio ).

Except where otherwise specified, searching a "place" means that the string designating the place is used as the default file-spec in a call to an RMS system service (for example, $SEARCH/$PARSE). The file-spec consists of the name in the #include directive without enclosing delimiters. The search terminates successfully as soon as a file can be opened for reading.

Quoted Form

For the quoted form of inclusion, the search order is:

1. One of the following:
   • If /NESTED_INCLUDE_DIRECTORY=INCLUDE_FILE (the default) is in effect, search the directory containing the file in which the #include directive itself occurred. The directory containing means the RMS resultant string obtained when the file in which the #include occurred was opened, except that the filename and subsequent components are replaced by the default file type for headers (".h", or just "." if /ASSUME=NOHEADER_TYPE_DEFAULT is in effect). The resultant string will not have translated any concealed device logical.
   • If /NESTED_INCLUDE_DIRECTORY=PRIMARY_FILE is in effect, search the default file type for headers using the context of the primary source file. This means that just the file type (".h" or ".") is used for the default file-spec but, in addition, the chain of "related file-specs" used to maintain the sticky defaults for processing the next top-level source file is applied when searching for the include file. This most closely matches the behavior of the VAX C compiler.
   • If /NESTED_INCLUDE_DIRECTORY=NONE is in effect, this entire step (Step 1) is bypassed.
2. Search the places specified in the /INCLUDE_DIRECTORY qualifier, if any. A place that can be parsed successfuly as an OpenVMS file-spec and that does not contain an explicit file type or version specification is edited to append the default header file type specification (".h" or ".").
   A place containing a "/" character is considered to be a UNIX-style name. If the name in the #include directive also contains a "/" character that is not the first character and is not preceded by a "!" character (it is not an absolute UNIX-style pathname), then the name in the #include directive is appended to the named place, separated by a "/" character, before applying the decc$to_vms pathname translation function. The result of the decc$to_vms translation is then used as the filespec to try to open.
3. If DECC$USER_INCLUDE is defined as a logical name, search DECC$USER_INCLUDE:.H, or just DECC$USER_INCLUDE:. if /ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
4. If the file is not found, follow the steps for the angle-bracketed form of inclusion.

Angle-Bracketed Form

For the angle-bracketed form of inclusion, the search order is:

1. Search the place "/". This is a UNIX-style name that can combine only with UNIX names specified explicitly in the #include directive. It causes a specification like <sys/types.h> to be considered first as /sys/types.h, which is translated by decc$to_vms to SYS:TYPES.H.
2. Search the places specified in the /INCLUDE_DIRECTORY qualifier, exactly as in Step 2 for the quoted form of inclusion.
3. If DECC$SYSTEM_INCLUDE is defined as a logical name, search DECC$SYSTEM_INCLUDE:.H, or just DECC$SYSTEM_INCLUDE:. if /ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
4. If DECC$LIBRARY_INCLUDE is defined as a logical name and DECC$SYSTEM_INCLUDE is not defined as a logical name, search DECC$LIBRARY_INCLUDE:.H, or just DECC$LIBRARY_INCLUDE:. if /ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
5. If neither DECC$LIBRARY_INCLUDE nor DECC$SYSTEM_INCLUDE are defined as logical names, then search the default list of places for plain text-file copies of compiler header files as follows:

   SYS$COMMON:[DECC$LIB.INCLUDE.DECC$RTLDEF]*.H
   SYS$COMMON:[DECC$LIB.INCLUDE.SYS$STARLET_C]*.H

   Note The compiler installation does not create these directories of header files. Instead, it creates [DECC$LIB.REFERENCE] for your convenience. But if you choose to create and populate SYS$COMMON:[DECC$LIB.INCLUDE.DECC$RTLDEF] or SYS$COMMON:[DECC$LIB.INCLUDE.SYS$STARLET_C], the compiler will search them.

   
   If the file is not found, perform the text library search described in the next step.
6. Extract the simple filename and file type from the #include specification and use the filename as the module name to search a list of text libraries associated with that file type.
   For any file type, the initial text libraries searched consist of those named on the command line with /LIBRARY qualifiers, searched in left-to-right order.
   If the /INCLUDE_DIRECTORY qualifier contained an empty string, no further text libraries are searched. Otherwise, DECC$TEXT_LIBRARY is searched for all file types.
   If DECC$LIBRARY_INCLUDE is defined as a logical name, then no further text libraries are searched. Otherwise, the subsequent libraries searched for each file type are:
   • For a file type of ".h" or ".":

     SYS$LIBRARY:DECC$RTLDEF.TLB
     SYS$LIBRARY:SYS$STARLET_C.TLB

   • For a file type other then ".h" or ".":

     SYS$LIBRARY:SYS$STARLET_C.TLB

7. If the previous step fails, search the following:

   SYS$LIBRARY:.H

   
   Under /ASSUME=NOHEADER_TYPE_DEFAULT, the default file type is modified as usual.

Text-Module Form

For the text-module (nonportable) form of inclusion, the name can only be an identifier. It, therefore, has no associated file type.

The identifier is used as a module name to search the following:

1. The text libraries named on the command line with /LIBRARY qualifiers, in left-to-right order.
2. The following list of text libraries in the order shown (unless the /INCLUDE_DIRECTORY qualifier contains an empty string, in which case no further text libraries are searched):

   DECC$TEXT_LIBRARY
   SYS$LIBRARY:DECC$RTLDEF.TLB
   SYS$LIBRARY:SYS$STARLET_C.TLB

The default for this qualifer is /NOINCLUDE_DIRECTORY.

/L_DOUBLE_SIZE=option

Specifying /L_DOUBLE_SIZE=64 treats all long double references as G_FLOAT, D_FLOAT, or T_FLOAT, depending on the value of the /FLOAT qualifier.

Specifying /L_DOUBLE_SIZE=128 treats all long double references as X_FLOAT.

The default is /L_DOUBLE_SIZE=128.

/LIBRARY

$ CC ONE + TWO + THREE/LIBRARY[Return]

Files ONE.C and TWO.C can contain references to modules in THREE.TLB. Consider the following example:

$ CC ONE + TWO + THREE/LIBRARY, FOUR[Return]

The file FOUR.C cannot contain references to modules in THREE.TLB since FOUR.C is located in a separate compilation unit separated by a comma. The placement of the library file specification does not matter. The following command lines are equivalent:

$ CC THREE/LIBRARY + ONE + TWO[Return] $ CC ONE + THREE/LIBRARY + TWO[Return] $ CC ONE + TWO + THREE/LIBRARY[Return]

/[NO]LINE_DIRECTIVES

The default is /LINE_DIRECTIVES.

/[NO]LIST[=file-spec]

By default, /LIST creates a listing file with the same name as the source file and with a file extension of .LIS. If you include a file specification with the /LIST qualifier, the compiler uses that specification to name the listing file.

In interactive mode, the default is /NOLIST. In batch mode, the default is /LIST. See the descriptions of the qualifiers /[NO]MACHINE_CODE, and /SHOW for related information. (For example, to suppress compiler messages to the terminal or to a batch log file, use the /SHOW=NOTERMINAL qualifier.)

/[NO]MACHINE_CODE[=option]

On OpenVMS VAX systems, several formats exist to list machine code. Table 1-11 describes the /MACHINE_CODE qualifier options.

Table 1-11 /MACHINE_CODE Qualifier Options (VAX ONLY)

Option	Usage
AFTER	Causes the lines of machine code produced during compilation to print after all the source code in the listing.
BEFORE	Causes lines of machine code produced during compilation to print before any source code in the listing.
INTERSPERSED	Produces a listing consisting of lines of source code followed by the corresponding lines of machine code. This is the default option.

On OpenVMS Alpha sytems, the format of the generated machine code listing is similar to what you would get using the AFTER keyword on OpenVMS VAX systems.

The default is /NOMACHINE_CODE.

/[NO]MAIN=POSIX_EXIT

The default is /NOMAIN.

/[NO]MEMBER_ALIGNMENT

Any use of the #pragma member_alignment or #pragma nomember_alignment directives within the source code overrides the setting established by this qualifier. Specifying /NOMEMBER_ALIGNMENT causes data structure members to be byte-aligned (with the exception of bit-field members).

On OpenVMS Alpha systems, the default is /MEMBER_ALIGNMENT.

On OpenVMS VAX systems, the default is /NOMEMBER_ALIGNMENT.

See the description of #pragma [no]member_alignment in Section 5.4.13.

/[NO]MMS_DEPENDENCIES[=(option[,...])]

object_file_name :<tab><source file name>) object_file_name :<tab><full path to first include file>) object_file_name :<tab><full path to second include file>)

Table 1-12 shows the /MMS_DEPENDENCIES qualifier options.

Table 1-12 /MMS_DEPENDENCIES Qualifier Options

Option	Usage
FILE[=filespec]	Specifies where to save the dependency file. The default file extension for a dependency file is .mms . Other than using this different default extension, /MMS_DEPENDENCY uses the same procedure that the /OBJECT and /LIST qualifiers do for determining the name of the output file.
[NO]SYSTEM_INCLUDE_FILES	Specifies whether or not to include dependency information about system include files (those included with #include < filename> .) If omitted, this option defaults to including dependency information about system include files.
TARGET=string	Specifies the target that appears in the output .mms file. The default is TARGET="" in which case the target is the source file name with a .OBJ extension, as in previous versions of the compiler. If you specify any string other than .OBJ, that string is used as the target. For the special case of .OBJ, the compiler uses the name of the object file (stripped of any version number and path) for the MMS target. Examples: $ CC/MMS/OBJ=OUTPUT T.C This command produces an .mms file with a target of T.OBJ : $ CC/MMS=(TARGET=FOO)/OBJ=OUTPUT T.C This command produces an .mms file with a target of FOO : $ CC/MMS=(TARGET=.OBJ)/OBJ=OUTPUT T.C This command produces an .mms file with a target of OUTPUT.OBJ :

The default is /NOMMS_DEPENDENCY.

/NAMES=(option1,option2)

Table 1-13 /NAMES Qualifier Option1 Values

Option	Usage
UPPERCASE	Converts to uppercase.
AS_IS	Leaves the case as specified in the source.