HP OpenVMS Systems

C++ is an evolving language in which new features have recently replaced outmoded constructs. The Compaq C++ compiler supports the language definition as specified in The Annotated C++ Reference Manual, excluding exception handling. If you are using programs developed under an older implementation of C++, the Compaq C++ compiler may issue warnings or errors when it compiles such programs. This manual provides the information you need to successfully run your programs, modified if necessary, on OpenVMS systems.

This chapter provides information about basic steps in developing a Compaq C++ program on an OpenVMS system. These steps are shown in Figure 1-1.

Figure 1-1 Steps in Developing a Compaq C++ Program

To create and modify a Compaq C++ program, you must invoke a text editor. The OpenVMS system provides you with at least two text editors: VAX EDT (EDT) and the DEC Text Processing Utility (DECTPU). Another editor that you can use is the DEC Language-Sensitive Editor (LSE), which is sold separately (see Appendix B for more information on LSE). Use .cxx as the file type to signify that you are creating a Compaq C++ source program.

When you compile your program with the cxx command, you do not have to specify the file type; by default, Compaq C++ first looks for files with the .cxx type.

If the compilation succeeds, the Compaq C++ compiler creates an object file with the type .obj. If the compiler detects errors, the system displays each error detected. You then reinvoke a text editor to make corrections.

When your program compiles successfully, you use the CXXLINK facility to create an executable image. Compiler and linker commands both take qualifiers, as described in Sections 1.2 and 1.3.

When you have an executable image file, use the run command, or define a foreign command, to run your program. See Section 1.4 for more information on running image files.

1.1 Using the DECTPU Text Editor

With DECTPU, you have a choice of two editing interfaces, the Extensible Versatile Editor (EVE) or the DECTPU EDT Keypad Emulator. You can also create your own interfaces with DECTPU. At any time during your editing session you have access to online help.

When you invoke DECTPU to create a file, the editor automatically creates a journal file, which you can use to recover your keyboard entries if the system fails during an editing session. To initiate recovery, use the following command format:

The interactive editor interface, EVE, responds to all the common editing functions, invoked using the editing keypad, and supports more advanced functions that you type as commands on the EVE command line. For more information on using EVE, see the Guide to VMS Text Processing.

1.2 Using the Compaq C++ Compiler

The Compaq C++ compiler detects source program errors and shows each error either in a screen display or in the batch log file, depending on whether you run the compiler interactively or in batch mode. If the compilation succeeds, the compiler generates machine-language instructions from the source statements, and groups these instructions into an object module for the linker.

The Compaq C++ compiler command cxx has the following format:

You use qualifiers to instruct the compiler to perform some action. A qualifier placed immediately after the cxx command affects all the files listed. A qualifier placed immediately after a file specification affects only the preceding file, unless you concatenate your files. A qualifier placed on an individual file specification overrides a qualifier placed immediately after the cxx command.

If you include more than one file specification on the same line, use commas (,) or plus signs (+) as separators. For example:

$ cxx/list prog_1, prog_2, prog_3

A comma instructs the compiler to keep source files separate and to create an object file and a listing file for each source file. A plus sign instructs the compiler to concatenate each of the specified source files, and to create one object file and one listing file. Any qualifier specified for one file within a list of concatenated files affects all these files.

1.2.1 Compiler Command Qualifiers

For a complete description of command line qualifiers, refer to Appendix A. Qualifiers are also described in online HELP.

1.2.2 Compiler Error Messages

If the Compaq C++ compiler detects errors in your source code, the compiler signals these errors by displaying diagnostic messages in the following format:

s

Is the error severity, represented as follows:

F	Fatal error. The compiler stops immediately without producing an object file. You cannot link the program until you correct this error.
E	Error. The compiler proceeds, and possibly generates other messages, but does not produce an object file. You cannot link the program until you correct this error.
W	Warning. The compiler takes some corrective action and produces an object file. However, to avoid unexpected results you must verify that the compiler's action is correct.
I	Information. The compiler informs you of specific actions taken. You need not take any action yourself regarding this message.
S	Success.

ident

Is a mnemonic (abbreviation) of the message text.

message-text

Is the full text of a compiler diagnostic message explaining what happened.

n

Is an integer that gives you the number of the line where the error occurs. The number is relative to the beginning of the file or module in which the error occurs. The number appears on your terminal but not in listing files.

name

Is the name of the file or module in which the error occurs. The name appears on your terminal but not in listing files.

For information on how to read the diagnostic messages from the Compaq C++ compiler, see Appendix C. 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.2.1.6.

1.3 Linking a Compaq C++ Program

After your Compaq C++ program or module successfully compiles, you can use the CXXLINK facility to combine your object modules into one executable image.

The CXXLINK facility is layered on top of the OpenVMS Linker utility and provides the ability to link your C++ application. Besides linking your C++ application, the CXXLINK facility completes the automatic template instantiation process; see Chapter 5 for details. CXXLINK also ensures that the Standard Template Library run-time support and the exception handling run-time support are linked into your application as needed.

CXXLINK accepts the same command line that you would use to invoke the OpenVMS Linker utility; thus, in most cases you can simply replace the link verb with cxxlink in your command procedures. The cxxlink command has the following format:

If you include more than one input file specification, use commas or plus signs as separators. By default, the linker creates an output file with the same name as the first input file and the file type .exe. If you want the output file to take the name of your main program, be sure to specify your main program file first. You also can use the /executable= name .exe qualifier on the cxxlink command line to specify a name for the executable image.

Do not use the linker cluster= option to reference OpenVMS object modules that define global static objects. Using this option prevents the constructors and destructors for global static objects from being run during image activation and exit.

Command Parameters and Qualifiers

The cxxlink command accepts the same parameters and qualifiers as the OpenVMS Linker utility (see Section 1.3.2 for some of the more useful OpenVMS Linker qualifiers). Additionally, the cxxlink command accepts the following qualifiers:

/expand

/noexpand

Controls whether CXXLINK displays unresolved C++ symbols in their mangled or demangled form. By default CXXLINK displays symbols in their demangled form.

/log_file[=filename]

/nolog_file

Directs CXXLINK to display logging information, such as the actual link and compile commands used to invoke the OpenVMS Linker utility and the Compaq C++ compiler. If you specify a file name, CXXLINK writes the logging information to the file you specify. If you specify /log_file without naming a file, the logging information is written to SYS$OUTPUT.

/repository=(writeable_repository [,readonly-repository,...])

Lets you specify the name of your repository directories. The first item in the list is considered the writeable repository, and the remaining items (if any) are considered repositories that are read only.

If you do not specify /repository , CXXLINK uses the default repository, sys$disk:[.cxx_repository] .

/template_prelink

/notemplate_prelink

Controls whether CXXLINK bypasses the template instantiation process. By default, CXXLINK performs at least one partial link to determine if there are any unresolved template symbols that need to be instantiated. If you know that your program does not use templates, then you can specify /notemplate_prelink to bypass this partial link and proceed directly to the final link.

/version

Directs CXXLINK to display its version identification and then exit.

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 Compaq C++. Class libraries offer a variety of predefined classes that enable you to work more efficiently. See the Compaq C++ Class Library Reference Manual for a detailed explanation of the class library packages supplied with Compaq C++.

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

Using the Compaq C++ 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 Compaq C++ Class Library as a shareable image, the Class Library code resides in an image file in SYS$SHARE and is shared by all Compaq 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.

1.3.1.1 Linking Against the Compaq C++ Class Library Object Library

To link against the Compaq C++ Class Library object library on OpenVMS Version 6.2 or higher systems, you need to specify the /nosysshr qualifier on your cxxlink command. For example:

$ cxxlink/nosysshr my_program.obj

If your program defines nonlocal static objects whose constructors or destructors use any part of the Compaq C++ Class Library, you need to ensure that the Class Library is initialized before your objects' constructors are invoked. (Note that this is not an issue when you link against the Class Library shareable image.) To guarantee this order of initialization, specify the Class Library initialization object module CXXL_INIT as the first module in your cxxlink command. To do this, use a cxxlink command similar to the following:

$ cxxlink/nosysshr/exe=my_program SYS$SHARE:STARLET.OLB/INCLUDE=CXXL_INIT, -
_$ my_program.obj

If your program uses the task package, you must explicitly include the CMA shared library when you link /nosysshr , as in the following example:

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

No special action is needed to link with the Compaq C++ Class Library; simply specify the object modules and object libraries that you want to link. The linker automatically finds and resolves any references to objects in the Compaq C++ Class Library when it searches the system-supplied shareable image library, sys$library:imagelib.olb .

1.3.2 Linker Command Qualifiers

You can use qualifiers to modify OpenVMS Linker output and to invoke debugging and traceback facilities. The following list shows some of the most useful link command qualifiers that you can specify on your cxxlink command:

/brief

Displays summary information on image characteristics and lists contributing modules in the map file.

/cross_reference

/nocross_reference (Default)

Determines whether you want to display cross-reference information for global symbols in the map file.

/debug

/nodebug (Default)

Determines whether you want the executable image to run under OpenVMS Debugger control when you execute the file. If you specify the /debug qualifier, the linker appends to the image all the symbol and line number information appended to the object modules, and includes in the symbol table information on global symbols.

/executable [=file-spec]

/noexecutable

Determines whether you want to create an executable image file. By default, the linker creates an output file with the same name as the first input file and the file type .exe.

/full

Displays information on image characteristics and lists contributing modules in the map file. Specifying the /full qualifier also generates a list of global symbols by name and by value, and provides a summary of characteristics of image sections in the linked image.

/map

/nomap

Determines whether the linker generates a map file. By default, the linker generates such a file when it is invoked in batch but not when it is invoked interactively.

/shareable

/noshareable (Default)

Determines whether the linker creates a shareable image.

/traceback (Default)

/notraceback

Determines whether the linker generates symbolic traceback information in the image file for use when application errors occur.

For a full discussion of the OpenVMS Linker, see the OpenVMS Linker Utility Manual.

1.3.3 Linker Error Messages

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

Some problems that commonly occur during linking are as follows:

• You try to link a program without defining every function that the program calls.
  The linker responds by issuing warnings. For example:
  %LINK-W-USEUNDEF symbol-name
  A symbol name that you do not recognize could be a mangled name. Name mangling is the mechanism the Compaq C++ compiler uses to encode exceptionally long identifiers, including C++ function names. By default, CXXLINK displays such symbols in their demangled form. To see a symbol in its mangled form, use the /noexpand qualifier on your cxxlink command. (See Section 1.5 for more information about name demangling.)
• You try to link a module that had warning or error messages during compilation.
  To avoid unexpected results, verify that the linker's action is acceptable.
• You try to link a nonexistent module.
  Check to see if the module exists (in the directory or library you expect it to be in) and is spelled correctly.
• You redefine a DEC C RTL function, or override the global operators new or delete . For more information, see the /[no]prefix_library_entries qualifier in Section 1.2.1.

For a complete list of linker messages, see the OpenVMS System Messages and Recovery Procedures Reference Manual.

1.4 Running a Compaq C++ Program

When your program successfully links, use the DCL command run to execute the image file. The run command has the following format:

/debug

/nodebug

Determines whether you invoke the OpenVMS Debugger during run time. Use the /debug qualifier to invoke the debugger if your image was not linked with the debugger. However, do not use the /debug qualifier on images linked with the /notraceback qualifier. Use the /nodebug qualifier if you linked your image with the /debug qualifier and you do not want the debugger to prompt you. The default is run/debug if you linked your image with the /debug qualifier; otherwise, the default is run/nodebug .

For more information on debugging Compaq C++ programs, see Chapter 8.

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.

1.4.2 Passing Arguments to the main Function

The main function in a Compaq C++ program can accept arguments from the command line from which it was invoked. The syntax for a main function is as follows:

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 Compaq C++ programs is during exec and getenv function calls. For more information, see the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

In the main function definition, the parameters are optional. However, you can access only the parameters that you define. You can define the main function in any of the following ways:

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

The procedure for defining a foreign command involves using a DCL assignment statement to assign the name of the image file to a symbol that is later used to invoke the image. For example:

$ 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 OpenVMS DCL Dictionary.

The following example shows a Compaq C++ program called commarg.cxx , which displays the command-line arguments that were used to invoke it:

// 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;
}

A sample output for this example is as follows:

$ echo == "$ db7:commarg.exe"[Return]
$ 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 DEC C RTL internally parses the altered command line and puts all unquoted arguments back in lowercase. This makes access to arguments in Compaq 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 (" ").

1.5 Name Demangling

Because of the need to provide type-safe linking, Compaq C++ encodes type information in external function names. This encoding is called name mangling.

Compaq C++ mangled names can appear in diagnostic messages from commands such as cxxlink/noexpand or from the OpenVMS Linker utility. To enable users to decode (or demangle) these names, Compaq C++ provides the CXXDEMANGLE facility. The CXXDEMANGLE facility translates mangled names into the names as they originally appeared in C++ source code.

To do the translation, CXXDEMANGLE uses a data file written by Compaq C++ during compilation. The data file contains a mapping of mangled names to their demangled forms.

1.5.1 Creating the Data File

Each time you compile a program, Compaq C++ 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 Compaq C++ compiler creates the data file. Otherwise, the Compaq C++ compiler appends information to the existing data file.

You can specify the name and location of the data file using the logical name cxx$demangler_db . For example, if you want your data file to be named mycxxdb.dat in the disk1:[mydir] directory, define the cxx$demangler_db logical name as follows:

$ define cxx$demangler_db disk1:[mydir]mycxxdb.dat

If the cxx$demangler_db logical name is not defined, Compaq C++ uses the default file name cxx$demangler_db in the writeable repository. Refer to Section 5.2.2 for details on how to specify the writeable repository.

1.5.2 Using the CXXDEMANGLE Facility

To demangle a symbol name, CXXDEMANGLE must use the same data file as the Compaq C++ 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.

CXXDEMANGLE provides both a command-line interface and an interactive interface, as follows:

• To use the command-line interface, enter the cxxdemangle command followed by a comma-separated list of mangled symbol names. CXXDEMANGLE then displays the demangled form of each symbol and exits. The command-line interface has the following syntax:

  CXXDEMANGLE mangled-symbol-name [,...]

  
  The following example shows appropriate use of this syntax:

  $ cxxdemangle COPY__XPIPIPI int * copy(int *, int *, int *) $ cxxdemangle COPY__XPPCPPCPPC, CXX$ADJCNTDFFRNCXPPP9MNS0IUE0NU char ** copy(char **, char **, char **) int * adjacent_difference(int *, int *, int *, minus<int >) $

  
  If you specify a mangled symbol name using the command-line interface and the symbol contains lowercase letters, you must place the symbol within quotes. For example:

  $ cxxdemangle "MyFunction__xic"

• To use the interactive interface, enter the cxxdemangle command without specifying a symbol name. CXXDEMANGLE then waits for you to enter a symbol name in its mangled form. When you enter a symbol, CXXDEMANGLE displays the demangled form of the symbol and waits for you to enter another symbol, and so forth. To exit the interactive interface, enter Ctrl/Z. The syntax for the interactive interface is as following:

  cxxdemangle mangled-symbol-name [...] Ctrl/Z

  
  The following example shows appropriate use of this syntax:

  $ cxxdemangle COPY__XPIPIPI int * copy(int *, int *, int *) COPY__XPPCPPCPPC char ** copy(char **, char **, char **) CXX$ADJCNTDFFRNCXPPP9MNS0IUE0NU int * adjacent_difference(int *, int *, int *, minus<int >) Ctrl/Z $

  
  When you use the interactive interface, quotes are not necessary when entering mangled symbol names that contain lowercase letters.

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

Command Qualifier

The cxxdemangle command accepts a single qualifier, /repository .

/repository=(repository[,...])

Names the repository directories that contain the data files used by CXXDEMANGLE. The /repository qualifier is ignored if you define the cxx$demangler_db logical name. See the preceding text for details.

The following sections decribes features that are available to users of Compaq C++ on OpenVMS Alpha Systems.

1.6.1 OpenVMS Calling Standard Conventions

The OpenVMS Alpha parameter-passing mechanisms are documented in the OpenVMS Calling Standard. Refer to this manual for a description of the concepts used by all OpenVMS languages to invoke routines and pass data among them. This standard specifies the following attributes:

• Register usage
• Stack usage
• Function return value
• Argument list

The calling standard also defines such attributes as the calling sequence, the argument data types and descriptor formats, condition handling, and stack unwinding. These attributes are discussed in detail in the OpenVMS Programming Interfaces: Calling a System Routine.

For more information on the parameter passing mechanism for Compaq C++ classes, see Section 2.2.5.

1.6.2 D-Float Support

The VAX D-floating double-precision floating-point type is minimally supported on OpenVMS Alpha Systems. When compiling with this type, all data transfer is done with the data in D-floating format, but for each arithmetic operation the data is converted first to G-floating format and then back to D-floating format when the operation is complete. Therefore, it is possible to lose three binary digits of precision in arithmetic operations. This floating-point type is provided for compatibility with OpenVMS VAX systems.

1.6.3 Built-In Functions

When compiling on OpenVMS Alpha Systems, built-in functions are available that let you directly access hardware and machine instructions. Appendix D describes these functions.

To access these built-in functions, you must include the <builtins.h> header file in your source program.