For a complete description of command line qualifiers, refer to Appendix A, Compiler Command Qualifiers or to the online HELP.

%CXX-s-ident, message-text
                 at line number n in file name

Where:

To be sure your program runs successfully, examine the diagnostic messages, evaluate error severity, and make any necessary corrections.

You can suppress certain information and warning diagnostic messages using the #pragma message preprocessor directive. For information about this directive, see Section 2.1.1.11, “#pragma message Directive ”.

CXXLINK makes use of the OpenVMS Linker Utility's LNK$LIBRARY logical names to specific object libraries as input to the linker. If the CXXLINK command includes the /USERLIBRARY qualifier in any form, an informational message will be displayed and CXXLINK will list any required object libraries in a linker options file.

Because a single CXXLINK command can invoke the OpenVMS Linker utility multiple times, you must not specify user mode (DEFINE/USER_MODE) logical names. If CXXLINK executes a second LINK command, the original DEFINE/USER_MODE logical name is not retained for that second command. Incorrect results can occur.

Note that the CXX$LINK_INIT command procedure defines MYLIB without the /USER_MODE qualifier. This is because the command procedure is executed only once in the spawned process.

When you compile and link programs that use the C++ Standard Library, no special qualifiers are required. The C++ driver automatically includes the Standard Library run-time support on the link command, and automatic template instantiation is the default mode.

$ CXX prog.cxx

For detailed information about the Standard Library, refer to Chapter 8, The C++ Standard Library.

Reusing code is a cornerstone of object-oriented programming. To minimize the time it takes to develop new applications, a set of reusable classes is an essential part of the VSI C++ compiler environment. Class libraries offer a variety of predefined classes that enable you to work more efficiently.

For a detailed explanation of the class library packages supplied with the compiler, see the VSI C++ Class Library Reference Manual, CXX_CLASSLIB.PS, in the SYS$COMMON:[SYSHLP.CXX$HELP] directory.

The Class Library has always been provided in shareable image format. Starting with OpenVMS Version 6.2, the Class Library is also provided in object library format.

Using the Class Library as an object library provides a functional advantage over using the shareable image. When your program redefines the global new and delete operators and uses the Class Library object library, the new and delete calls within the Class Library are directed to the new and delete operators defined by your program. On the other hand, when your program uses the Class Library shareable image, the new and delete calls within the Class Library always call the standard new and delete operators. Linking with the shareable image is the default method.

When you use the Class Library as a shareable image, the Class Library code resides in an image file in SYS$SHARE and is shared by all C++ programs. This process has the advantages of: reducing the size of a program's executable image, decreasing the amount of disk space taken up by the program's image, and letting your program swap in and out of memory faster because of decreased size.

$ CXXLINK/NOSYSSHR my_program.obj

$ CXXLINK/NOSYSSHR/EXE=my_program SYS$SHARE:STARLET.OLB -
_$ /INCLUDE=CXXL_INIT, my_program.obj

$ CXXLINK/NOSYSSHR my_program.obj,SYS$INPUT:/OPT -
_$ SYS$SHARE:CMA$LIB_SHR/SHARE
^Z

If the OpenVMS Linker detects errors while linking object modules, the linker displays messages indicating the cause and severity of error. Because CXXLINK uses the OpenVMS Linker to link your C++ program, CXXLINK displays these linker messages. The linker does not produce an image file if errors or fatal errors occur (conditions with severities of E or F).

For an explanation of linker messages, invoke the HELP/MESSAGE utility.

As system shareable images, these CXXL$ images are part of the system library of shareable images, IMAGELIB.OLB, which is automatically searched by the Linker. Consequently, no special actions are required to link C++ applications against the class or standard library shareable image.

$ CXX PROG.CXX
$ CXXL PROG.OBJ  ! (or LINK PROG.OBJ)
$ RUN PROG.EXE

In addition to being delivered as system shareable images, the C++ class, standard, and language run-time support libraries are also delivered in object form in the system object library STARLET.OLB, thus making it possible to link C++ applications /NOSYSSHARE.

The C++ libraries themselves do not impose any restrictions on linking /NOSYSSHARE. However, because they are layered on top of the C Run-Time Library, the rules for linking an application that references the C Run-Time Library /NOSYSSHARE do apply.

For example, when linking /NOSYSSHARE, you must explicitly include CMA$TIS routines in the link by either linking against the CMA$TIS_SHR.EXE shareable image or forcing the CMA$TIS module from STARLET.OLB in the link. See the VSI C Run-Time Library Reference Manual for OpenVMS Systems for more details.

$ CXXL/NOSYSSHARE PROG.OBJ, SYS$INPUT:/OPT
SYS$SHARE:CMA$TIS_SHR/SHARE
^Z

$ CXXL/NOSYSSHARE prog.obj, -
_$ SYS$SHARE:STARLET.OLB/INCLUDE=CMA$TIS

On x86-64 systems, the C++ Standard Library and standard exception classes, are delivered as system shareable images in SYS$LIBRARY:

LIBCXX.EXE - standard library image

LIBCXXABI.EXE - ABI

They are part of the system library of shareable images, IMAGELIB.OLB, which is automatically searched by the Linker. Consequently, no special actions are required to link C++ applications against the class or standard library shareable images. For example, if PROG.CXX uses a class from the C++ standard library, the following sequence of commands will compile, link, and run the program:

$ CXX PROG.CXX 
$ LINK PROG.OBJ 
$ RUN PROG.EXE 

In addition to being delivered as system shareable images, the C++ Standard libraries are also delivered in object form in SYS$LIBRARY:

LIBCXX.OLB

LIBCXXABI.OLB

Thus, if C++ program needs to be linked against static libraries, you must provide them explicitly, or you can use the SYS$COMMON:[SYSHLP.EXAMPLES]CXX.OPT (or SYS$EXAMPLES:CXX.OPT) file.

For example, if PROG.CXX uses a class from the C++ standard library, the following sequence of commands will compile, link and run the program:

$ CXX PROG.CXX
$ LINK PROG.OBJ,SYS$EXAMPLES:CXX/OPT ! Link against static libraries
$ RUN PROG.EXE

When an error occurs during program execution, the OpenVMS condition handler terminates execution and displays messages and traceback information on the currently defined sys$error device. In the symbolic stack dump traceback message, the condition handler lists the modules that were active when the error occurred, indicating the sequence in which the modules were called.

Traceback information is available at run time only for modules compiled with /DEBUG=TRACEBACK and linked with the /TRACEBACK qualifier in effect (the default for both compiler and linker commands). You should exclude traceback information only from thoroughly debugged program modules.

The traceback information makes reference to numbered lines that are listing lines in your program. If you include header files in the source file using the #include directive, the line numbers do not correspond to the source-file lines. To see the numbers that correspond to those referenced in the traceback information, generate a listing file using the /LIST qualifier to the compiler command.

int main(int argc,
char *argv[ ],
char *envp[ ])
{
. . .
return status;
}

In this syntax, parameter argc is the count of arguments present in the command line that invoked the program, and parameter argv is a character-string array of the arguments. Parameter envp is the environment array, which contains process information such as the user name and controlling terminal. Parameter envp has no bearing on passing command-line arguments; its primary use in C++ programs is during exec and getenv function calls. For more information, see the VSI C Run-Time Library Reference Manual for OpenVMS Systems.

int main()
int main(int argc)
int main(int argc, char *argv[])
int main(int argc, char *argv[], char *envp[])

To pass arguments to the main function, you can use a DCL foreign command to point to the program, or you can define the logical name DCL$PATH to point to an area containing the program.

To make use of DCL$PATH in the previous example, the resulting program executable would have to be named "echo.exe".

You can then place echo.exe into a specific directory and point the logical name DCL$PATH to it.

$ RENAME commarg.exe echo.exe
$ COPY echo.exe sys$login:
$ DEFINE DCL$PATH SYS$LOGIN:

The output would be identical to that shown in the previous example when a foreign command was used. To pass arguments to the main function, you must define the program as a DCL foreign command. When a program is defined and run as a foreign command, the parameter argc is always greater than or equal to 1, and argv[0] always contains the name of the image file.

$ echo == "$ dsk$:commarg.exe" Return

The symbol echo is defined as a foreign command that invokes the image in commarg.exe. The definition of echo must begin with a dollar sign ($) and include a device name.

For more information about the procedure for defining a foreign command, see the VSI OpenVMS DCL Dictionary.

// This program echoes the command-line arguments.

#include <iostream.h>

main(int argc, char *argv[])
{
        int i;
        for (i = 0; i < argc; ++i)
                cout << i << " := >" << argv[i] << "<\n";
        return 0;
}

$ echo  Long  "Day's"  "Journey into Night" Return
0 := >db7:commarg.exe;1<
1 := >long<
2 := >Day's<
3 := >Journey into Night<

DCL converts unquoted arguments on the command line to uppercase letters. However, the C RTL internally parses the altered command line and puts all unquoted arguments back in lowercase. This makes access to arguments in VSI C++ programs compatible with C++ programs developed on other systems.

All arguments in the command line are delimited by spaces or tabs. Arguments with embedded spaces or tabs must be enclosed in quotation marks (" ").

Each time you compile a program, the compiler stores, in a data file, all the program's external symbols in their mangled and demangled forms. If the data file does not exist, the compiler creates the data file. Otherwise, the compiler appends information to the existing data file.

$ DEFINE CXX$DEMANGLER_DB DISK1:[MYDIR]MYCXXDB.DAT

If the CXX$DEMANGLER_DB logical name is not defined, the compiler uses the default file name CXX$DEMANGLER_DB in the writeable repository. Refer to Chapter 6, Using Templates for details on how to specify the writeable repository.

To demangle a symbol name, CXXDEMANGLE must use the same data file as the compiler used when it compiled the program containing the symbol.

Hence, if you defined the CXX$DEMANGLER_DB logical name when you compiled the program, you should also define the logical name when you use the CXXDEMANGLE facility.

Similarly, if you did not define the CXX$DEMANGLER_DB logical name but specified the /REPOSITORY qualifier during compilation, specify the same /REPOSITORY qualifier on your CXXDEMANGLE command.

If you did not specify the /REPOSITORY qualifier on your compile command, the compiler uses the data file in the default writeable repository. To use the CXXDEMANGLE facility in this case, either issue the CXXDEMANGLE command from the same directory where the compile command was issued, or specify the appropriate /REPOSITORY qualifier on your CXXDEMANGLE command.

If CXXDEMANGLE is unable to translate a mangled symbol name, it echoes the mangled symbol name.

Redistribution of this library is only required by those applications which need to be linked during or after installation on an end user target system. If you link your application and ship either a shareable or executable image to your customers, then redistribution of the object library is not necessary. The linking process of your application causes those library modules to be incorporated into your resultant image.

There are two options that you can use to redistribute the DECC$CRTL.OLB object library. The options are based on whether the library is needed after the installation is completed.

The first option is for applications which link during installation, but have no need for the object library once installation is completed. For that set of developers, we recommend placing DECC$CRTL.OLB on your kit, but to link using the copy in VMI$KWD and not issue a PROVIDE_FILE option which would move this file onto the system. In other words, the object library resides only on your kit, is used during installation to link your application, but is not placed onto the end user system.

The second option is for applications which do need the object library after installation is completed. For this class of applications, the object library should be placed in a product specific location on the target system and not in SYS$LIBRARY. The contents of this object library must not be inserted into the SYS$LIBRARY:STARLET.OLB library.

Redistribution of this library is only required by those applications which need to be linked during or after installation on an end user target system. If you link your application and ship either a shareable or executable image to your customers, then redistribution of the object library is not necessary. The linking process of your application causes those library modules to be incorporated into your resultant image.

There are two options that you can be used to redistribute the LIBCXXSTD.OLB object library. The options are based on whether the library is needed after the installation is completed.

The first option is for applications which link during installation, but have no need for the object library once installation is completed. For that set of developers, we recommend placing LIBCXXSTD.OLB on your kit, but to link using the copy in VMI$KWD and not issue a PROVIDE_FILE option which would move this file onto the system. In other words, the object library resides only on your kit, is used during installation to link your application, but is not placed onto the end user system.

The second option is for applications that do need the object library after installation is completed. For this class of applications, the object library should be placed in a product specific location on the target system and not in SYS$LIBRARY. The contents of this object library must not be inserted into the SYS$LIBRARY:STARLET.OLB library.

The #pragma preprocessor directive is a standard method for implementing features that differ from one compiler to the next. This section describes pragmas specifically implemented in the C++ compiler for OpenVMS systems.

This manual displays keywords used with #pragma in lowercase letters. However, these keywords are not case sensitive.

#pragma define_template identifier

#pragma define_template mytempl<arg1, arg2>

#pragma environment command_line
#pragma environment header_defaults
#pragma environment restore
#pragma environment save

#ifdef __PRAGMA_ENVIRONMENT
#pragma __environment save  
#pragma __environment header_defaults 
#pragma member_alignment restore 
#pragma member_alignment save 
#endif
.
.  /* contents of header file */
.
#ifdef __PRAGMA_ENVIRONMENT
#pragma __environment restore
#endif

#pragma extern_model model_spec [attr[,attr]...]

#pragma extern_model relaxed_refdef long
int a;
int b = 6;
#pragma extern_model common_block long
int c;

                      "string"
#pragma extern_prefix save
                      restore

#pragma function (function1[,function2, ...])
#pragma function ()

#pragma include_directory <string-literal>

#pragma inline (id,...)
#pragma noinline (id,...)

#pragma intrinsic (function1[,function2, ...])

abs
fabs
labs
alloca

#pragma member_alignment
#pragma member_alignment save
#pragma member_alignment restore
#pragma nomember_alignment [base_alignment]

#pragma nomember_alignment

struct x {
           char c;
           int b;
           };

#pragma member_alignment

struct y {
          char c;       /*3 bytes of filler follow c */
          int b;
          };

main ()

{
        printf( "The sizeof y is: %d\n", sizeof (struct y) );
        printf( "The sizeof x is: %d\n", sizeof (struct x) );
}

#pragma message disable (message-list)
#pragma message enable (message-list)
#pragma message error (message-list)
#pragma message fatal (message-list)
#pragma message informational (message-list)
#pragma message warning (message-list)
#pragma message restore
#pragma message save

%CXX-W-MISSINGRETURN, Non-void function "name" does not contain a return
 statement

#pragma message disable MISSINGRETURN

...
#if __DECCXX_VER > 60000000
#define uninit used_before_set
#endif

#pragma message disable uninit
int main()
{
  int i,j;

  i=j;
}
#pragma message enable uninit

#pragma message [option] ("message-list")

#pragma module identifier identifier
#pragma module identifier string

#pragma once

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

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

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

#pragma unroll unroll_factor

The compiler predefines __VMS; the C compiler predefines VMS and __VMS. Therefore, C++ programmers who plan to reuse code should check for __VMS.

The compiler predefines __32BITS when pointers and data of type long are 32 bits on Alpha platforms.

On both UNIX and OpenVMS operating systems, programmers should use the predefined macro __alpha for code that is intended to be portable from one system to the other.

#define  __G_FLOAT  1

These macros can assist in writing code that executes conditionally. They can be used in #elif, #if, #ifdef, and #ifndef directives to separate portable and nonportable code in a C++ program. The vms_version, VMS_VERSION, __vms_version, and __VMS_VERSION macros are defined with the value of the OpenVMS version on which you are running (for example, Version 6.0).

The value of __X_FLOAT can be 0 or 1 depending on the floating point mode in effect. You can use the /FLOAT qualifier to change the mode.

For example, the defined value of __VMS_VERSION on OpenVMS Version 6.1 is character string V6.1.

You can use __DECCXX_VER to test that the current compiler version is newer than a particular version and __VMS_VER to test that the current OpenVMS Version is newer than a particular version. Newer versions of the compiler and the OpenVMS operating system always have larger values for these macros. If for any reason the version cannot be analyzed by the compiler, then the corresponding predefined macro is defined but has the value of 0. Releases of the compiler prior to Version 5.0 do not define these macros, so you can distinguish earlier compiler versions by checking to determine if the __DECCXX_VER macro is defined.

#ifdef __DECCXX_VER
    #if __DECCXX_VER >= 50100000
        / *Code */
    #endif
#endif

#ifdef __VMS_VER
    #if __VMS_VER >= 60200000
        /* code */
    #endif
#endif

Numerical limits not described in this list are defined in The Annotated C++ Reference Manual.

The compiler passes arrays, functions, and class objects with a constructor or destructor by reference. All other objects are passed by value.

If a class has a constructor or a destructor, it is not passed by value. In this case, the compiler calls a copy constructor to copy the object to a temporary location, and passes the address of that location to the called function.

On OpenVMS IA-64 and Alpha if the return value of a function is a class that has defined a constructor or destructor or is greater than 64 bits, storage is allocated by the caller and the address to this storage is passed in the first parameter to the called function. The called function uses the storage provided to construct the return value.

On OpenVMS x86-64 if the return value of a function is a class that has defined a constructor or destructor or is greater than 128 bits, storage is allocated by the caller and the address to this storage is passed in the first parameter to the called function.

In the compiler, the dollar sign ($) is a valid character in an identifier.

For each external function with C++ linkage, the compiler decorates the function name with a representation of the function's type.

Nonlocal static objects are initialized in declaration order within a compilation unit and in link order across compilation units. On OpenVMS systems, the compiler uses the lib$initialize mechanism to initialize nonlocal static objects.

When demoting an integer to a signed integer, if the value is too large to be represented the result is truncated and the high-order bits are discarded.

Conversions between signed and unsigned integers of the same size involve no representation change.

When converting an integer to a floating-point number that cannot exactly represent the original value, the compiler rounds off the result of the conversion to the nearest value that can be represented exactly.

When the result of converting a floating-point number to an integer or other floating-point number at compile time cannot be represented, the compiler issues a diagnostic message.

When converting an integral number or a double floating-point number to a floating-point number that cannot exactly represent the original value, rounds off the result to the nearest value of type float.

When demoting a double value to float, if the converted value is within range but cannot exactly represent the original value, the compiler rounds off the result to the nearest representable float value, the compiler performs similar rounding for demotions from long double to double or float.

The type of the sizeof operator is size_t. In the header file, stddef.h, the compiler defines this type as unsigned int, which is the type of the integer that holds the maximum size of an array.

On OpenVMS x86-64 the CXX compiler size_t is defined as unsigned long, that is 64-bit.

A pointer takes up the same amount of memory storage as objects of type int or long (or their unsigned equivalents). Therefore, a pointer can convert to any of these types and back again without changing its value. No scaling occurs and the representation of the value is unchanged.

Conversions to and from a shorter integer and a pointer are similar to conversions to and from a shorter integer and unsigned long. If the shorter integer type was signed, conversion fills the high-order bits of the pointer with copies of the sign bit.

On OpenVMS x86-64 the default size for pointers is 64-bits (same as the size of type long).

You can subtract pointers to members of the same array. The result is the number of elements between the two array members, and is of type ptrdiff_t. In the header file stddef.h, the compiler defines this type as int.

On OpenVMS x86-64 ptrdiff_t is defined as long, that is 64-bit.

The expression E1 >> E2 shifts E1 to the right E2 positions. If E1 has a signed type, the compiler fills the vacated high-order bits of the shifted value E1 with a copy of E1's sign bit (arithmetic shift).

When created by different address expressions, two pointers to members may compare either as equal or as unequal if they produce the same member when applied to the same object.

For variables that are modifiable in ways unknown to the compiler, use the volatile type specifier. Declaring an object to be volatile means that every reference to the object in the source code results in a reference to memory in the object code.

In the compiler, asm declarations produce a compile-time error. As an alternative to asm, you can use built-in functions. See Appendix C, Built-In Functions for more information.

Specifying linkage other than “C++” or “C” generates a compile-time error.

In object files, the compiler decorates with type information the names of functions with C++ linkage. This permits overloading and provides rudimentary type checking across compilation units. The type-encoding algorithm used is similar to that given in §7.2.1c of The Annotated C++ Reference Manual (see Section 2.2.1.1, “External Name Encoding”).

On OpenVMS x86-64, the type-encoding algorithm is based on Itanium C++ ABI. For more information refer to https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangling.

The alignment requirements and sizes of structure components affect the structure's alignment and size. A structure can begin on any byte boundary and occupy any integral number of bytes.

class B1
{
 int x[1];
};
class B2 : virtual B1
{
 int y[2];
 virtual int fl();
};
class B3 : virtual B2, virtual B1
{
 int z[3];
 virtual int f2();
};
class D : B3
{
 int a[4];
 virtual int f1(), f2(), f3();
};

-cc1 -fdump-record-layouts

The compiler allocates storage for virtual function tables (VTBLs) and base class tables (BTBLs) using the common block extern model. All references to VTBLs and BTBLs share a single copy. (The compiler specifies the local (LCL) PSECT attribute for these tables. Thus, one copy of each table exists for each program image file.) This means that you need not be concerned with the associations of these tables during compilation, and the compiler command switch +e supplied in other implementations is not needed for VSI C++ for OpenVMS systems.

Within a class object, base class subobjects are allocated in derivation order; that is, immediate base classes are allocated in the order in which they appear in the class declaration.

Variations in the compiler generation of such temporary objects can adversely affect their reliability in user programs. The compiler avoids introducing a temporary object whenever it discovers that the temporary object is not needed for accurate compilation. Therefore, you should modify or write your programs so as not to depend on side effects in the constructors or destructors of temporary objects.

struct A {
  void print(int i);
  A();
  ~A() { }
};

struct B {
  A* find(int i);
  B(int i);
  B();
  ~B() { }
};

void f() {
  B(8).find(6)->print(6);
  (*(B(5).find(3))).print(3);
  return;
}

struct A {
  A(int);
};
void f(A& ar);

void g() {
  f(5);     // warning!!
}

struct A {
        ~A();
        static void sf();
};

struct B {
        A operator ()() const;
};

void f () {
    B bobj;
    bobj().sf();        // If 'bobj()' is evaluated, a temporary of
                        // type 'A' is created.
}

The #include directive inserts external text into the macro stream delivered to the compiler. Programmers often use this directive to include global definitions for use with compiler functions and macros in the program stream.

On OpenVMS systems, the #include directive may be nested to a depth determined by the FILLM process quota and by virtual memory restrictions. The compiler imposes no inherent limitation on the nesting level of inclusion.

nodename!/device/directory/filename.dat.3

The exclamation point (!) separates the node name from the rest of the specification; slash characters (/) separate devices and directories; periods (.) separate file types and file versions. Because one character separates two segments of the file specification, ambiguity can occur.

The /INCLUDE_DIRECTORY=(pathname,...) qualifier provides an additional level of search for user-defined include files. Each pathname argument can be either a logical name or a legal UNIX style directory in a quoted string. The default is /NOINCLUDE_DIRECTORY.

The qualifier provides functionality similar to the -I option of the cxx command on UNIX systems. This qualifier allows you to specify additional locations to search for files to include. Putting an empty string in the specification prevents the compiler from searching any of the locations it normally searches but directs it to search only in locations you identify explicitly on the command line with the /INCLUDE_DIRECTORY and /LIBRARY qualifiers (or by way of the specification of the primary source file, depending on the /NESTED_INCLUDE_DIRECTORY qualifier).

Unless otherwise defined, searching a location means that the compiler uses the string specifying the location as the default file specification in a call to an RMS system service (that is, a $SEARCH/$PARSE) with a primary file specification consisting of the name in the #include (without enclosing delimiters). The search terminates successfully as soon as a file can be opened for reading.

void f(int);
void f(int *);
class C {void f(int);};
class D {void f(int);};

Yet, linkers cannot interpret overloaded parameter types or classes, and they issue error messages if they find more than one definition of any external symbol. C++ compilers, including VSI C++, solve this problem by assigning a unique mangled name (also called type safe linkage name) to every function. These unique mangled names allow the linker to tell the overloaded functions apart.

The compiler forms a mangled name, in part, by appending an encoding of the parameter types of the function to the function's name, and if the function is a member function, the function name is qualified by the names of the classes within which it is nested.

Alpha and IA-64 only

For example, for the function declarations at the beginning of this section, the compiler might generate the mangled names f__Xi, f__XPi, f__1CXi, and f__1DXi respectively. In these names, i means a parameter type was int, P means “pointer to”, 1C means nested within class C, and 1D means nested within class D.

struct C1 {enum E {red, blue};};
struct C2 {enum E {red, blue};};

extern "C" int printf(const char *, ...);
void f(C1::E x) {printf("f(C1::E)\n");}
void f(C2::E x) {printf("f(C2::E)\n");}

int main()
{
    f(C1::red);
    f(C2::red);
    return 1;
}

In the previous example, the two overloaded functions named f differ only in that one takes an argument of enum type C1::E and the other takes an argument of enum type C2::E. Since the compiler fails to include the names of the classes containing the enum type in the mangled name, both functions have mangled names that indicate the argument type is just E. This causes both functions to receive the same mangled name.

In some cases, the compiler detects this problem at compile-time and issues a message that both functions have the same type-safe linkage. In other cases, the compiler issues no message, but the linker complains about duplicate symbol definitions.

If you encounter such problems, you can recompile using the /DISTINGUISH_NESTED_ENUMS qualifier (Alpha only). This causes the compiler, when forming a mangled name, to include the name of class or classes within which an enum is nested, thereby preventing different functions from receiving the same mangled name.

Because the /DISTINGUISH_NESTED_ENUMS qualifier changes the external symbols the compiler produces, you can get undefined symbol messages from the linker if some modules are compiled with /DISTINGUISH_NESTED_ENUMS and some are compiled without it. Because of this, /DISTINGUISH_NESTED_ENUMS might make it difficult to link against old object files or libraries of code.

If you compile your code with /DISTINGUISH_NESTED_ENUMS and try to link against a library that was compiled without the /DISTINGUISH_NESTED_ENUMS qualifier, you receive an undefined symbol message from the linker if you attempt to call a function from the library that takes an argument of a nested enum type. The mangled name of the function in the library will be different from the mangled name your code is using to call the function.

Note that the /DISTINGUISH_NESTED_ENUMS qualifier has no meaning on IA-64 systems because it modifies the behavior of programs compiled with /MODEL=ARM, and that model is not supported on IA-64 systems.

x86-64 only

OpenVMS x86-64 CXX compiler uses different mechanism for name mangling. For example, for the function declarations at the beginning of this section, the compiler might generate the mangled names _Z1fi, _Z1fPi, _ZN1C1fEi and _ZN1D1fEi. In the second example of this section, OpenVMS x86-64 compiler includes the name of the class containing the enum, thereby it creates different mangled names for two functions "f". Thus the linker message about duplicate symbol definitions is not generated. /DISTINGUISH_NESTED_ENUMS qualifier is not supported on x86-64.

template <class T> void f(T) {
  printf("In template f\n");
}

void f(int);

int main() {
  f(0);      // invokes non-template f
  f<>(0.0);  // invokes template f
  return 0;
}

void f(int) {
  printf("In non-template f\n");
}

Because there is no concept of guiding declaration in the current version of the C++ International Standard, the function f in the example is not regarded as an instance of function template f. Furthermore, there are two functions named f that take an int parameter. A call of f(0) would invoke the former, while a call of f<>(0) would be required to invoke the latter.

To modify header files, use conditional compilation and the extern specifier.

#if defined __cplusplus
    /* If the functions in this header have C linkage, this
     * will specify linkage for all C++ language compilers.
     */
    extern "C" {
#endif

# if defined __DECC || defined __DECCXX 
    /* If you are using pragmas that are defined only
     * with DEC C and DEC C++, this line is necessary
     * for both C and C++ compilers.  A common error
     * is to only have #ifdef __DECC, which causes
     * the compiler to skip the conditionalized
     * code.
     */
     /*  On x86-64 C++, the same check is this: 
        # if defined __DECC || defined __clang__
     */

#   pragma __extern_model __save
#   pragma __extern_model __strict_refdef
    extern const char some_definition [];
#   pragma __extern_model __restore
# endif

 /* ...some data and function definitions go here... */

#if defined __cplusplus
    }   /* matches the linkage specification at the beginning. */
#endif

See The Annotated C++ Reference Manual for more information on linkage specifications.

If your program uses any of the C++ language keywords as identifiers, you must replace them with nonconflicting identifiers. The list of C++ language keywords can be found in this source: https://en.cppreference.com/w/cpp/keyword.

and, and_eq, bitand, bitor, compl, not, not_eq, or, or_eq, xor, xor_eq

Distinctions between ANSI C and C++ include slight differences in rules concerning scope. Therefore, you may need to modify some ANSI C header files to use them with C++.

struct Screen {
  struct _XDisplay *display;
};
typedef struct _XDisplay {
  // …
} Display;

struct Screen s1;
Display      *s2;

main()
{
  s1.display = s2;
}    

struct _XDisplay; // this is the added line
struct Screen {
struct _XDisplay *display;
};
typedef struct _XDisplay {
  // ...
} Display;
// ...

The C compiler special built-in macros defined in the header files <stdarg.h> and <varargs.h>. These step through the argument list of a routine.

Programs that take the address of a parameter, and use pointer arithmetic to step through the argument list to obtain the value of other parameters, assume that all arguments reside on the stack and that arguments appear in increasing order. These assumptions are not valid for VSI C++. The macros in <varargs.h> can be used only by C functions with old-style definitions that are not legal in C++. To reference variable-length argument lists, use the <stdarg.h> header file.

The OpenVMS calling standard mechanism for returning structures larger than 8 bytes by value uses a hidden parameter. The parameter is a pointer to storage in the caller's frame. The va_count macro includes this parameter in its count.

Header files should be directly included by modules that need them. Because several modules may include the same header file, a header file must not contain definitions that would generate multiply defined symbols when all the modules are linked together.

Library source files should be compiled individually and then linked into your application. Because each library source file is compiled only once, the definitions it contains will exist in only one object module and multiply defined symbols are thus avoided.

For example, to create a class called “array” you would create the following two files:

// arrayInt.hxx
#ifndef ARRAY_H
#define ARRAY_H

class arrayInt {
private:
        int curr_size;
        static int max_array_size;
public:
        arrayInt() :curr_size(0) {;}
        arrayInt(int);
};

#endif

// arrayInt.cxx
#include "arrayInt.hxx"

int array::max_array_size = 256;

arrayInt::arrayInt(int size) :  curr_size(size) { ...;  }

cxx/include=[.include] arrayInt.cxx

The resulting object file could either be linked directly into your application or placed in a library (see Section 3.5.4, “Creating Libraries”).

The header file uses header guards, which is a technique to prevent multiple inclusion of the same header file.

With the widespread use of templates in C++, determining the proper place to put declarations and definitions becomes more complicated.

The general rule is to place template declarations and definitions in header files, and to place specializations in library source files.

All these header files should use header guards, to ensure that they are not included more that once either explicitly or by implicit inclusion.

For example, the array class from Section 3.5.1, “Code That Does Not Use Templates”, modified to use templates, would now look as follows:

// array.hxx
#ifndef ARRAY_HXX
#define ARRAY_HXX

template <class T>
class array {
private:
        int curr_size;
        static int max_array_size;
public:
        array() :curr_size(0) {;}
        array(int size,const T& value = T());
};

#endif

// array.cxx
template <class T>
int array<T>::max_array_size = 256;

template <class T>
array<T>::array(int size,const T& value )  {... ; }

// myprog.cxx

#include "array.hxx"

main() {
        array<int> ai;
        // ...
}

Figure 3.1, “Placement of Template Declaration and Definition Files” shows the placement of these files.

cxx/incl=[.include] myprog.cxx

In this case, you do not need to create library source files because the static member data and out-of-line members of the array template class are instantiated at the time you compile myprog.cxx.

Libraries are useful for organizing the sources within your application as well as for providing a set of routines for other applications to use. Libraries can be either object libraries or shareable libraries. Use an object library when you want the library code to be contained within an application's image; use shareable libraries when you want multiple applications to share the same library code.

Creating a library from nontemplate code is straightforward: you simply compile each library source file and place the resulting object file in your library.

Creating a library from template code requires that you explicitly request the instantiations that you want to provide in your library. See Chapter 8, The C++ Standard Library for details.

If you make your library available to other users, you must also supply the corresponding declarations and definitions that are needed at compile time. For nontemplate interfaces, you must supply the header files that declare your classes, functions, and global data. For template interfaces, you must provide your template declaration files as well as your template definition files.

For more information on creating libraries, see the VSI OpenVMS Command Definition, Librarian, and Message Utilities Manual and the VSI OpenVMS Linker Utility Manual.

Achieving source compatibility means that users of your library will not have to make any source code changes when they upgrade to your new library release. Their applications will compile cleanly against your updated header files and will have the same run-time behavior as with your previous release.

Achieving link compatibility means that users of your library can relink an application against your new object or shareable library and not be required to recompile their sources.

What Can Change

What Cannot Change

Because the user may be linking object modules from your previous release with object modules from your new release, the layout and size of class objects must be consistent between releases. Any user-visible interfaces must also remain unchanged; even the seemingly innocent change of adding const to an existing function will change the mangled name and thus break link compatibility.

Designing Your C++ Classes for Link Compatibility

Achieving run compatibility means that users of your library can run an application against your new shareable library and not be required to recompile or relink the application.

This requires that you follow the guidelines for link compatibility as well as any operating system guidelines for shareable libraries. On OpenVMS systems, you need to create an upwardly compatible shareable image using a transfer vector on OpenVMS VAX and a symbol table on OpenVMS. Refer to the VSI OpenVMS Linker Utility Manual for information on creating a shareable image.

The Annotated C++ Reference Manual offers some advice on compatibility issues. Another good reference is Designing and Coding Reusable C++ by Martin D. Carroll and Margaret E. Ellis.

The move from Alpha systems to IA-64 systems may cause some minor differences in certain compiler diagnostics that are signaled from the code generator. As a result, diagnostics for unreachable code and fetches of uninitialized variables might be different on the two platforms. In addition to a change in message text, some conditions detected on one platform might not be detected on the other.

There have also been some changes in the /WARNINGS qualifier for both platforms. These include bug fixes and improved compatibility with the C compiler. For a summary of these changes, see the New and Changed Features section of the Preface.

The C++ compiler for IA-64 systems is built from a different code base than the C++ compiler for Alpha systems, and that code base is larger than the code base for Alpha. Also, IA-64 images tend to be somewhat larger than Alpha images in general. Image size mostly affects working-set size and the amount of pagefile quota needed to execute an image without exhausting virtual memory. If you find that programs that compile and run successfully on Alpha run out of memory on IA-64 systems (either during compilation or when run), you probably need to increase your pagefile quota. There are no specific guidelines at this time. You might start by doubling the quota that was sufficient on Alpha, and then use a "binary-search" approach to arrive at a better quota value for IA-64 systems (doubling again, or halving the increment, until your biggest programs and compilations have just enough memory, and then adding an appropriate safety margin).

Some of the compiler dialects (options to the /STANDARD qualifier) have been updated to reflect the most recent behaviors of the compilers that the dialect is attempting to match. Other changes involve the removal of less significant or undesirable compatibility features.

The object model and the name mangling scheme used by the C++ compiler on IA-64 systems are different from those used on Alpha systems (different from both /MODEL=ARM and /MODEL=ANSI). The IA-64 compiler uses the interface described by the IA-64 Application Binary Interface (ABI).

The C++ compiler has some additional encoding rules that are applied to symbol names after the ABI name mangling is determined. All symbols with C++ linkage have CRC encodings added to the name, are uppercased and shorten to 31 characters if necessary. Since the CRC is computed before the name is uppercased, the symbol name is case-sensitive even though the final name is in uppercase. /NAMES=AS_IS and /NAMES=UPPER are not applicable to these symbols.

All symbols without C++ linkage will have CRC encodings added if they are longer then 31 characters and /NAMES=SHORTEN is specified. Global variables with C++ linkage are treated as if they have non-C++ linkage for compatibility with C and older compilers.

This section describes C++ command-line qualifier differences to be aware of on IA-64 systems.

Qualifiers/Features Not Supported on IA-64 Systems

Changed/Ignored Qualifiers

If you encounter porting problems, compile /WARN=ENABLE=QUALCHANGE to determine if a qualifier change might be affecting your application.

If you wish to clean up your build scripts to remove extraneous qualifiers that are not meaningful on IA-64 systems, you can enable the QUALNA message.

New Qualifiers

This section describes floating-point behavior on IA-64 systems.

IEEE Now the Default

On OpenVMS IA-64 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 IA-64 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 IA-64 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 between VAX floating-point formats and IEEE formats on the IA-64 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 IA-64 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 IA-64 systems.

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, therefore, a non-issue.

You can test an application's behavior with IEEE floating-point values by first 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 IA-64 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 IA-64 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 runtime 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 IA-64 system.

/IEEE_MODE Notes

On Alpha systems, 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 IA-64 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 the following characteristic: its primary effect requires the setting of a runtime status register, and so it needs to be specified on the compilation containing the main program in order to be effective in other compilations.

The C++ built-in functions available on OpenVMS Alpha systems are also available on IA-64 systems, with some differences. Section C.2, “Built-In Functions for IA-64 Systems (IA-64 only)” documents these differences and describes the built-in functions that are specific to IA-64 systems.

On OpenVMS Alpha systems, the C++ compiler uses a proprietary object format specific to OpenVMS.

On OpenVMS IA-64 systems, the compiler generates ELF objects. ELF is an industry standard object format used on many UNIX platforms, including Linux. This change should be transparent to most users; it is primarily of interest to compiler and tools developers. The greatest benefit of this change is that it should make it easier to create development tools that work on OpenVMS and other platforms.

Extensions to ELF have been used as needed to provide functionality unique to OpenVMS. See the Porting Applications from VSI OpenVMS Alpha to VSI OpenVMS Industry Standard 64 for Integrity Servers for more information on ELF.

COMDATS/Group Sections

One feature that ELF provides that is new to OpenVMS is the COMDAT section group — a group of sections in an object file that can be duplicated in one or more other object files. The linker is expected to keep one group and ignore all others. The benefit of this feature is that it permits compilers to generate definitions for symbols for things used in multiple objects without having to worry about creating a single definition in one place. The most notable uses for this feature are templates and inline functions.

New ELF Type for Weak Symbols

A new Executable and Linkable Format (ELF) type was generated to distinguish between the two types of weak symbol definitions.

The Librarian supports both the ELF ABI versions 1 and 2 of the object and image file formats within the same library.

This section describes template instantiation for IA-64 systems.

Implemented using ELF COMDATS/Groups Sections

The Alpha C++ compiler had numerous models for instantiating templates. Each attempted to solve the issue of how to generate one and only one copy of each template. The use of ELF on OpenVMS IA-64 systems provided the compiler with the additional option of using COMDAT section groups. Since this technique is superior to all the models supported on Alpha, this is the only model supported on IA-64 systems.

In this model, templates are instantiated in a COMDAT section group inside every object module that uses them. This is very similar to the /TEMPLATE=LOCAL on Alpha systems, except that when the objects are linked together, the linker removes the duplicate copies. The primary advantage of this technique over /TEMPLATE=LOCAL and /TEMPLATE=IMPLICIT_LOCAL is the reduction in image size.

A secondary advantage is the elimination of distinct data for each template. For example, if a template maintained a list of elements it created, each module would have a separate copy of the list. This behavior does not conform to the standard. If you are currently using /TEMPLATE=LOCAL or /TEMPLATE=IMPLICIT_LOCAL, you will likely experience no difficulty from this change.

Not in Repository

The most visible difference that results from this new instantiation model occurs in models that instantiate templates into the repository (/TEMPLATE=AUTOMATIC|ALL_REPOSITORY|USED_REPOSITORY).

With the new model, no repository is needed. Build procedures that use CXXLINK will work transparently. Builds that attempt to manipulate objects in the repository will fail and will need to be changed. In most cases, the reason for manipulating the repository directly has been eliminated with the new template instantiation model.

Also see Chapter 6, Using Templates.

The command-line option /EXCEPTIONS=NOCLEANUP is not implemented. As a result, you might see destructors being called during cleanup in code previously compiled with this option.

Exception specifications are not implemented. Exception specifications on routine declarations and definitions are accepted syntactically, but their run-time behavior has not yet been implemented.

      #include <exception>
      #include <cstdio>
      #include <cstdlib>
       class C {
       public:
         C() { std::printf("Created\n"); }
         ~C() { std::printf("Destroyed\n"); }
       };
       void announce1() {
         std::printf("In terminate\n");
         exit(0);
       }
       int main() {
         C c;
         std::set_terminate(announce1);
         throw 5;
         return 0;
       }

   Alpha:            I64:
   Created           Created
   In terminate      Destroyed
                     In terminate

extern "C" int printf(const char *,...);
struct killit {
  killit () {}
  ~killit () {
    try {
      throw 11;
    } catch (int i) {
      printf("caught %d\n", i);
    }
  }
};
int main () {
  try {
 killit local;
    throw 33;
  } catch (const int &i) {
    printf("caught int: %d\n", i);
  }
  return 0;
}

caught 11
caught int: 33

extern "C" int printf(const char *,...);
extern "C" int exit(int);
#include <exception>
void announce () {
    printf("Terminated!\n");
    exit(0);
}
class Y {
  public:
    Y () { printf ("construct Y\n"); }
    Y(Y &rhs) {
      printf ("copy Y\n");
      printf ("uncaught_exception = %s\n", std::uncaught_exception() ?
                                           "TRUE" : "FALSE");
      throw 20;
    }
    ~Y () { printf ("destruct Y\n"); }
};

void cxx_func () {
    Y OBJ2;
printf ("In cxx_func\n");
    try {
        throw OBJ2;
    } catch (const Y &) {
        printf("Caught Y &\n");
    } catch (int i) {
        printf("Caught %d\n", i);
    }
    printf ("leaving cxx_func\n");
}
main () {
    std::set_terminate(announce);
    cxx_func();
    printf ("Leaving main\n");
}

construct Y
In cxx_func
copy Y
uncaught_exception = TRUE
Terminated!

construct Y
In cxx_func
copy Y
uncaught_exception = FALSE
Caught 20
leaving cxx_func
destruct Y
Leaving main

#include <exception>
extern "C" void exit(int);
extern "C" int printf(const char *,...);
void announce2 () {
    printf("announce2: Unexpected!\n");
    exit(0);
}
void announce1 () {
    printf("announce1: Terminated!\n");
    exit(0);
}
class C {
public:
   C() { printf("C()\n"); }
  ~C() throw() { std::set_unexpected(announce2); printf("~C()\n"); throw 3; }
};
void foo() {
    C c;
    printf("throwing ...\n");
    throw 5;
}
main() {
    std::set_terminate(announce1);
    foo();
}

C()
throwing ...
~C()
announce2: Unexpected!

C()
throwing ...
~C()
announce1: Terminated!

#include <exception>
#include <cstdlib>
extern "C" int printf(const char *, ...);
void my_unex() {
  printf("In my unex\n");
  throw;
}
void my_term() {
  printf("In my term\n");
  std::exit(0);
}
void foo() throw() {  // spec not checked with second rethrow
  printf("In foo\n");
  throw 7;
}
void bar() throw(int) {  // this spec checked with second rethrow
printf("In bar\n");
  foo();
}
void foo2() throw(std::bad_exception) {  // spec not checked with first rethrow
    printf("In foo2\n");
  throw 5;
}
int main() {
  std::set_unexpected(my_unex);
  std::set_terminate(my_term);
  try {
    foo2();
  } catch (int i) {
    printf("Caught %d\n", i);
} catch (std::bad_exception &) {
    printf("Caught bad_exception\n");
  }
  try {
    bar();
  } catch (int i) {
    printf("Caught %d\n", i);
  } catch (...) {
    printf("Caught ...\n");
  }
  return 0;
}

In foo2
In my unex
Caught bad_exception
In bar
In foo
In my unex
In my term

In foo2
In my unex
Caught 5
In bar
In foo
In my unex
Caught 7

The standard library, language run-time support library, and class library have been reorganized for IA-64 systems.

The language run-time support library no longer validates if a negative value has been specified in a call to operator new. Instead, the value is treated as an unsigned value, and an attempt is made to dynamically allocate the specified memory.

This section describes changes to the C++ standard library.

#ifndef __USE_STD_IOSTREAM
#define __USE_STD_IOSTREAM
#endif
#include <fstream>
using namespace std;
main() {
  cout << "hello, world";
}

%CXX-E-UNDECLARED, identifier "cout" is undefined