|
HP OpenVMS SystemsC Programming Language |
|
HP C
|
| Previous | Contents | Index |
If there are errors in your source file when you compile your program, the HP C compiler signals these errors and displays diagnostic messages. Reference the message, locate the error, and, if necessary, correct the error. See Appendix D or the online help for a description of all compiler diagnostic messages.
You can control the issuance of specific compiler diagnostic messages or groups of messages with the /[NO]WARNINGS command-line qualifier ( Section 1.3.4) and the #pragma message preprocessor directive ( Section 5.4.14).
To display a particular compiler diagnostic message online, enter the following command:
$ HELP CC/DECC MESSAGE mnemonic[Return] (VAX ONLY) $ HELP CC MESSAGE mnemonic[Return] (ALPHA, I64) |
To display a list of all message mnemonics, enter the following command:
$ HELP CC/DECC MESSAGE[Return] (VAX ONLY) $ HELP CC MESSAGE[Return] (ALPHA, I64) |
Diagnostic messages have the following format:
|
%CC-s-ident, message-text Listing line number m At line number n in name |
%CC
The facility or program name of the HP C compiler. This portion indicates that the message is being issued by HP C.s
The severity of the error, represented in the following way:
F Fatal error. The compiler stops executing when a fatal error occurs and does not produce an object module. You must correct the error before you can compile the program. E Error. The compiler continues, but does not produce an object module. You must correct the error before you can successfully compile the program. W Warning. The compiler produces an object module. It attempts to correct the error in the statement, but you should verify that the compiler's action is acceptable. Otherwise, your program may produce unexpected results. I Information. This message usually appears with other messages to inform you of specific actions taken by the compiler. No action is necessary on your part. ident
The message identification. This is a descriptive abbreviation (mnemonic) of the message text.message-text
The compiler's message. In many cases, it consists of more than one line of output. A message generally provides you with enough information to determine the cause of the error so that you can correct it.Listing line number m
The integer m, which gives you the line number in the listing file where the error occurs. This information is given when you specify the /LIST qualifier.At line number n in name
The integer n, which gives you the number of the line where the error occurs. The number is relative to the beginning of the file or text library module specified by name. You can use the #line directive to change both the line number and name that appear in the message.
After you compile an HP C source program or module, use the DCL command LINK to combine your object modules into one executable image, which can then be executed by the OpenVMS system. A source program or module cannot run on the OpenVMS system until it is linked.
When you execute the LINK command, the linker performs the following functions:
When using the LINK command on development systems, use the /DEBUG qualifier to link your program module. The /DEBUG qualifier appends to the image all the symbol and line number information appended to the object modules plus information on global symbols, and causes the image to run under debugger control when it is executed.
The LINK command produces an executable image by default. However, you can also use the LINK command to obtain shareable images and system images. The /SHAREABLE qualifier directs the linker to produce a shareable image; the /SYSTEM qualifier directs the linker to produce a system image. See Section 1.4.2 for a complete description of these and other LINK command qualifiers.
For a complete discussion of the OpenVMS Linker, see the HP OpenVMS Linker Utility Manual.
The LINK command has the following format:
|
LINK[/command-qualifier]... {file-spec[/file-qualifier...]},... |
/command-qualifier...
Output file options.file-spec
The input files to be linked./file-qualifier...
Input file options.
If you specify more than one input file, you must separate the input file specifications with a plus sign (+) or a comma (,).
By default, the linker creates an output file with the name of the first input file specified and the file type EXE. If you link more than one file, you should specify the file containing the main program first. Then, the name of your output file will have the same name as your main program module.
The execution of a program will begin at the function whose identifier is main , or, if there is no function with this identifier, at the first function seen by the VMS linker.
Unexpected results might occur if you don't have a function called main . |
The following command line links the object files MAINPROG.OBJ, SUBPROG1.OBJ, and SUBPROG2.OBJ to produce one executable image called MAINPROG.EXE:
$ LINK MAINPROG.OBJ, SUBPROG1.OBJ, SUBPROG2.OBJ |
Unlike VAX C, HP C does not require you to define any LNK$LIBRARY logicals. |
You can use the LINK command qualifiers to modify the linker's output, as well as to invoke the debugging and traceback facilities. Linker output consists of an image file and an optional map file.
The following list summarizes some of the most commonly used LINK command qualifiers. A brief description of each qualifier follows this list. For a complete list of LINK qualifiers, see the HP OpenVMS Linker Utility Manual.
| Command Qualifiers | Default |
|---|---|
| /BRIEF | None. |
| /[NO]CROSS_REFERENCE | /NOCROSS_REFERENCE |
| /[NO]DEBUG | /NODEBUG |
| /[NO]EXECUTABLE[=file-spec] | /EXECUTABLE=name.EXE |
| /FULL | None. |
| /[NO]MAP | /MAP (batch) /NOMAP (interactive) |
| /[NO]SHAREABLE[=file-spec] | /NOSHAREABLE |
| /[NO]TRACEBACK | /TRACEBACK |
/BRIEF
Produces a summary of the image's characteristics and a list of contributing modules. This qualifier is mutually exclusive with /FULL./[NO]CROSS_REFERENCE
Produces cross-reference information for global symbols; /NOCROSS_REFERENCE suppresses cross-reference information. The default is /NOCROSS_REFERENCE./[NO]DEBUG
Includes the OpenVMS Debugger in the executable image and generates a symbol table; /NODEBUG causes the linker to prevent debugger control of the program. The default is /NODEBUG./[NO]EXECUTABLE [=file-spec]
Produces an executable image. /NOEXECUTABLE suppresses production of an image file. The default is /EXECUTABLE./FULL
Produces a summary of the image's characteristics, a list of contributing modules, listings of global symbols by name and by value, and a summary of characteristics of image sections in the linked image. This qualifier is mutually exclusive with /BRIEF./[NO]MAP
Generates a map file; /NOMAP suppresses the map. The default is /MAP in batch mode and /NOMAP in interactive mode./[NO]SHAREABLE[=file-spec]
Creates a shareable image. /NOSHAREABLE generates an executable image. The default is /NOSHAREABLE./[NO]TRACEBACK
Generates symbolic traceback information when error messages are produced; NOTRACEBACK suppresses traceback information. The default is /TRACEBACK.
You can specify the object modules to be included in an executable image in any of the following ways:
Table 1-26 shows the default input file types for the linker.
| File Type | File |
|---|---|
| OBJ | Object module |
| OLB | Library |
| OPT | Options file |
When you enter the LINK command interactively and do not specify any qualifiers, the linker creates only an executable image file. By default, the resulting image file has the same file name as that of the first object module specified with a file type of EXE.
In a batch job, the linker creates both an executable image file and storage map file by default. The default file type for map files is MAP.
To specify an alternative name for a map file or image file or to specify an alternative output directory or device, you can include a file specification on the /MAP or /EXECUTABLE qualifier. In the following example, the LINK command creates the image file [PROJECT.EXE]UPDATE.EXE and the map file [PROJECT.MAP]UPDATE.MAP:
$ LINK UPDATE/EXECUTABLE=[PROJECT.EXE]/MAP=[PROJECT.MAP] |
Linking against object modules (stored in object module libraries) or against shareable images are ways of allowing your program to access data and routines outside of your compilation units. You can either create the object module libraries and the shareable images or use the ones provided by HP. To access data in object modules and shareable images, you can use LINK command qualifiers, OpenVMS logical names, and options files. For more information about object module libraries, see the HP OpenVMS Linker Utility Manual.
The HP C Run-Time Library (RTL) for OpenVMS systems also provides two formats for you to choose from: shareable images or object module libraries. Depending on which type of RTL you want to use and on which type of functions you plan on calling from your programs, you need to supply information to the linker that specifies which versions of the functions to access.
When you use the HP C RTL and its corresponding header files, remember that the HP C RTL ships with the OpenVMS operating system and the header files ship with the HP C compiler. Since the releases of the compiler and of the operating system are not synchronized, there may be compatibility issues that you need to consider to use the RTL properly. See the HP C release notes (by entering HELP CC/DECC RELEASE_NOTES on the DCL command line) for information that may pertain to this issue.
For a description of the various ways to link with the HP C RTL, see the HP C Run-Time Library Reference Manual for OpenVMS Systems.
You can make program modules accessible to other users by storing them in an object module library. To link modules contained in an object module library, use the /INCLUDE qualifier and specify the modules you want to link. The following example links the subprogram modules EGGPLANT, TOMATO, BROCCOLI, and ONION with the main program module GARDEN:
$ LINK GARDEN, VEGGIES/INCLUDE=(EGGPLANT,TOMATO,BROCCOLI,ONION) |
An object module library can also contain a symbol table with the names of each global symbol in the library, and the name of the module in which they are defined. You specify the name of the object module library containing symbol definitions with the /LIBRARY qualifier. When you use the /LIBRARY qualifier during a linking operation, the linker searches the specified library for all unresolved references found in the included modules during compilation.
The following example uses the library RACQUETS to resolve undefined symbols in BADMINTON, TENNIS, and RACQUETBALL:
$ LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY |
You can define an object module library to be your default library by using the DCL command DEFINE LNK$LIBRARY. The linker searches default user libraries for unresolved references after it searches modules and libraries specified in the LINK command. For more information about the DEFINE command, see the HP OpenVMS DCL Dictionary.
For more information about object module libraries, see the HP OpenVMS Linker Utility Manual.
If the linker detects any errors while linking object modules, it displays messages indicating the cause and severity of the error. If any error or fatal error conditions occur (that is, errors with severities of E or F), the linker does not produce an image file.
The messages produced by the linker are descriptive, and you do not usually need additional information to determine the specific error. Some common errors that occur during linking are as follows:
$ LINK OCEAN, REEF, SHELLS |
%LINK-W-NUDFSYMS, 1 undefined symbol %LINK-I-UDFSYMS, SEAWEED %LINK-W-USEUNDEF, module "OCEAN" references undefined symbol "SEAWEED" %LINK-W-DIAGISUED, completed but with diagnostics |
If an error occurs when you link modules, you can often correct it by reentering the command and specifying the correct modules or libraries. If an error indicates that a program module cannot be located, you may be linking the program with the wrong RTL.
For a complete list of linker messages, see the OpenVMS System Messages and Recovery Procedures Reference Manual.
After you link your program, you can use the DCL command RUN to execute it. The RUN command has the following format:
|
RUN [/[NO]DEBUG] file-spec [/[NO]DEBUG] |
/[NO]DEBUG
An optional qualifier. Specify the /DEBUG qualifier to invoke the debugger if the image was not linked with it. You cannot use /DEBUG on images linked with the /NOTRACEBACK qualifier. If the image was linked with the /DEBUG qualifier and you do not want the debugger to prompt you, use the /NODEBUG qualifier. The default action depends on whether the file was linked with the /DEBUG qualifier.file-spec
The file you want to run.
The execution of a program begins at the function whose identifier is main , or, if there is no function with this identifier, at the first function seen by the VMS linker.
Unexpected results might occur if you don't have a function called main . |
The following example executes the image SAMPLE.EXE without invoking the debugger:
$ RUN SAMPLE/NODEBUG |
For more information on debugging programs, see Section C.1.
During execution, an image can generate a fatal error called an exception condition. When an exception condition occurs, the system displays an error message. Run-time errors can also be issued by the operating system or by utilities.
When an error occurs during the execution of a program, the program is terminated and the OpenVMS condition handler displays one or more messages on the currently defined SYS$ERROR device.
A message is followed by a traceback. For each module in the image that has traceback information, the condition handler lists the modules that were active when the error occurred, which shows the sequence in which the modules were called.
For example, if an integer divide-by-zero condition occurs, a run-time message like the following appears:
%SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero
at PC=00000FC3, PSL=03C00002
|
This message is followed by a traceback message similar to the following:
%TRACE-F-TRACEBACK, symbolic stack dump follows module name routine name line rel PC abs PC A C 8 00000007 00000FC3 B main 1408 000002F7 00000B17 |
The information in the traceback message follows:
module name
The name or names of an image module that was active when the error occurred.The first module name is that of the module in which the error occurred. Each subsequent line gives the name of the caller of the module named on the previous line. In this example, the modules are A and B; main called C.
routine name
The name of the function in the calling sequence.line
The compiler-generated line number of the statement in the source program where the error occurred, or at which the call or reference to the next procedure was made. Line numbers in these messages match those in the listing file (not the source file).rel PC
The value of the PC (program counter). This value represents the location in the program image at which the error occurred or at which a procedure was called. The location is relative to the virtual memory address that the linker assigned to the code program section of the module indicated by module name.abs PC
The value of the PC in absolute terms; that is, the actual address in virtual memory representing the location at which the error occurred.
Traceback information is available at runtime only for modules compiled and linked with the traceback option in effect. The traceback option is in effect by default for both the CC and LINK commands. You may use the CC command qualifier /NODEBUG and the LINK command qualifier /NOTRACEBACK to exclude traceback information. However, traceback information should be excluded only from thoroughly debugged program modules.
The main function in an HP C program can accept arguments from the command line from which it was invoked. The syntax for a main function is:
|
int main(int argc, char *argv[ ], char *envp[ ]) {...} |
argc
The number of arguments in the command line that invoked the program.argv
A pointer to an array of character strings that contain the arguments.envp
The environment array. It contains process information such as the user name and controlling terminal. It has no bearing on passing command-line arguments. Its primary use in HP C programs is during exec and getenv function calls. (For more information, see the HP 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 install the program as a DCL foreign command. When a program is installed and run as a foreign command, the argc parameter is always greater than or equal to 1, and argv[0]always contains the name of the image file.
The procedure for installing 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 installed 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, as shown.
For more information about the procedure for installing a foreign command, see the HP OpenVMS DCL Dictionary.
Example 1-1 shows a program called COMMARG.C, which displays the command-line arguments that were used to invoke it.
| Example 1-1 Echo Program Using Command-Line Arguments |
|---|
/* This program echoes the command-line arguments. */
#include <stdio.h>
#include <stdlib.h>
int main(int argc, char *argv[])
{
int i;
/* argv[0] is program name */
printf("program: %s\n",argv[0]);
for (i = 1; i < argc; i++)
printf("argument %d: %s\n", i, argv[i]);
exit (EXIT_SUCCESS);
}
|
You can compile and link the program using the following DCL command lines:
$ CC COMMARG[Return] $ LINK COMMARG[Return] |
A sample output for Example 1-1 follows:
$ ECHO Long "Day's" "Journey into Night"[Return] program: db7:[oneill.plays]commarg.exe;1 argument 1: long argument 2: Day's argument 3: Journey into Night |
DCL converts most arguments on the command line to uppercase letters. HP C internally parses and modifies the altered command line to make HP C argument access compatible with C programs developed on other systems. All alphabetic arguments in the command line are delimited by spaces or tabs. Arguments with embedded spaces or tabs must be enclosed in quotation marks (" "). Uppercase characters in arguments are converted to lowercase, but arguments within quotation marks are left unchanged.
| Previous | Next | Contents | Index |