|
United States |
|
| ||
| ||
| ||
| ||
 | ||
|
||
|
||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Chapter 1
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
edit/tpu/recover file-spec |
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.
The 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 compiler command cxx has the following format:
|
cxx[/qualifier...][ file-spec [/qualifier...]],... |
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.
For a complete description of command line qualifiers, refer to the online HELP .
If the compiler detects errors in your source code, the compiler signals these errors by displaying diagnostic messages in the following format:
|
%CXX-s-ident, message-text at line number n in file name |
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 what you wanted. 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.
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.8.
After your program or module successfully compiles, you must use the CXXLINK facility to combine your object modules into one executable image.
The CXXLINK facility is layered on 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, you can simply replace the link verb with cxxlink in your command procedures. The cxxlink command has the following format:
|
cxxlink[/command-qualifier]... {file-spec[/file-qualifier...]},... |
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.
The OpenVMS Linker expects a function whose identifier is main. If a C++ program lacking a definition of main is inadvertently linked, then program execution begins at the first function seen by the linker. |
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.
In addition to the following qualifiers, the cxxlink command accepts the same parameters and qualifiers as the OpenVMS Linker utility (see Section 1.3.5 for some of the more useful OpenVMS Linker qualifiers). CXXLINK-specific qualifiers are stripped off prior to calling the OpenVMS Linker utility and therefore have no effect on default device or directory specifications applied by the OpenVMS Linker facility.
| Command Qualifiers | Defaults |
|---|---|
| /[no]log_file[=filename] | /nolog_file |
| /preinst | /preinst |
| /prelink=(option[,option2]) | See HELP. |
| /repository=(writeable-repository | |
| [,readonly-repository,...]) | See HELP. |
| /use_link_input[=filename] | /nouse_link_input |
| /version | None. |
For more information about cxxlink qualifiers and parameters, type HELP CXXLINK.
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.
You should check command procedures that perform link operations of code generated by the C++ compiler for any /USER_MODE logical names that are intended to be in effect during a LINK operation. If you find any, you can modify the procedures CXXLINK in one of the following ways:
$ DEFINE/USER MYLIB MYAREA:MYLIB.OLB $ LINK A,B,SYS$INPUT:/OPT MYLIB/LIB $ |
$ CREATE CXX$LINK_INIT.COM $ DEFINE MYLIB MYAREA:MYLIB.OLB $EOD $ DEFINE/USER CXX$LINK_INIT SYS$DISK:[]CXX$LINK_INIT.COM $ LINK A,B,SYS$INPUT:/OPT MYLIB/LIB $! $ DELETE CXX$LINK_INIT.COM; |
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 switches 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.
For example, to build a program called prog.cxx that uses the Standard Library, you enter the following command:
cxx prog.cxx |
For detailed information about the Standard Library, refer to Chapter 7.
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 Compaq 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 Compaq C++ Class Library Reference Manual .
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.
To link against the 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 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 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 Class Library when it searches the system-supplied shareable image library, sys$library:imagelib.olb .
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. For a full discussion of the OpenVMS Linker, see the OpenVMS Linker Utility Manual.
| Command Qualifiers | Defaults |
|---|---|
| /brief | None. |
| /[no]cross_reference | /nocross_reference |
| /[no]debug | /nodebug |
| /[no]executable[=file-spec] | /executable=first-object-file-name.exe |
| /full | None. |
| /[no]map | /nomap (interactive) /map (batch) |
| /[no]shareable | /noshareable |
| /[no]traceback | /traceback |
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:
For an explanation of linker messages, invoke the HELP/MESSAGE utility.
When your program successfully links, use the DCL command run to execute the image file. The run command has the following format:
|
run [/[no]debug] file-spec |
/debug
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 .
/nodebugFor more information on debugging 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.
The main function in a C++ program can accept arguments from the command line from which it was invoked. The syntax for a main function is as follows:
|
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 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 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.
For example:
$ 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 exaple 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.
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 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 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 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 (" ").
Because of the need to provide type-safe linking, Compaq C++ encodes type information in external function names. This encoding is called name mangling.
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, the compiler 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 the compiler during compilation. The data file contains a mapping of mangled names to their demangled forms.
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.
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, the compiler uses the default file name cxx$demangler_db in the writeable repository. Refer to Chapter 5 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.
CXXDEMANGLE provides both a command-line interface and an interactive interface, as follows:
|
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 >) $ |
$ cxxdemangle "MyFunction__xic" |
|
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 $ |
If CXXDEMANGLE is unable to translate a mangled symbol name, it echoes the mangled symbol name.
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 decribe features that are available to users of the compiler on OpenVMS Alpha systems.
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:
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 Classes, see Section 2.1.5.
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.
When compiling on OpenVMS Alpha systems, built-in functions are available that let you directly access hardware and machine instructions. Appendix C describes these functions.
To access these built-in functions, you must include the <builtins.h> header file in your source program.
The compiler provides the following performance optimization options:
/[no]ansi_alias
Specifies whether the compiler assumes the ANSI C aliasing rules to generate better optimized code.If a program does not access the same data through pointers of a different type (and for this purpose, signed and qualified versions of an otherwise same type are considered to be the same type), then assuming ANSI C aliasing rules allows the compiler to generate better optimized code.
If a program does access the same data through pointers of a different type (for example, by a "pointer to int" and a "pointer to float"), you must not allow the compiler to assume ANSI C aliasing rules, because these rules can result in the generation of incorrect code.
Per the C++ language rules, the default is /ansi_alias .
/assume=[no]pointers_to_globals
Controls whether the compiler can safely assume that global variables have not had their addresses taken in code that is not visible to the current compilation.The default is /assume=pointers_to_globals , which directs the compiler to assume that global variables have had their addresses taken in separately compiled modules and that, in general, any pointer dereference could be accessing the same memory as any global variable. This is often a significant barrier to optimization.
While the /ansi_alias option allows some resolution based on data type, /assume=nopointers_to_globals provides significant additional resolution and improved optimization in many cases.
The /assume=pointers_to_globals option tells the compiler that any global variable accessed through a pointer in the compilation must have had its address taken within that compilation. The compiler can see any code that takes the address of an extern variable. If it does not see the address of the variable being taken, the compiler can assume that no pointer points to the variable.
Note that incorrect use of /assume=nopointers_to_globals can generate bad code.
/assume=[no]trusted_short_alignment
Allows the compiler additional assumptions about the alignment of short types that, although naturally aligned, may cross a quadword boundary. The trusted_short_alignment option indicates that the compiler should assume any short type accessed through a pointer is naturally aligned. This generates the fastest code, but can silently generate the wrong results when an unaligned short object crosses a quadword boundary. The notrusted_short_alignment option tells the compiler that short objects may not be naturally aligned. The compiler generates slightly larger (and slower) code that will give the correct result, regardless of the actual alignment of the data. This is the default. Note that the notrusted_short_alignment option does not override the __unaligned type qualifier option or the /assume=noaligned_objects) option./assume=[no]whole_program
Tells the compiler that except for "well-behaved library routines", the whole program consists only of the single object module being produced by this compilation. The optimizations enabled by /assume=whole_program include all those enabled by /assume=nopointer_to_globals and possibly other optimizations.The default is /assume=nowhole_program .
Partitioning a large application into several shared libraries, which are then linked into an executable, is a useful technique for reducing link times during development. See Section 3.4 for more information.
The Compaq C++ kit contains two Run-Time Library components that you might need to redistribute with your applications:
The next sections describe the method that developers must use to redistribute Run-Time Library components to user systems. Redistribution of other components on the Compaq C++ kit is prohibited. The redistribution rights set forth in the Software Product Description do not apply to the DECC$CRTL.EXE or DECC$CRTL.README files which are distributed with this kit.
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.
| Previous | Next | Contents | Index |
 |
privacy statement and legal notices |
