HP OpenVMS systems documentation

The following examples show the use of the EXAMINE and DEPOSIT commands with the /ASCII:n type qualifier.

When used with the DEPOSIT command, this qualifier enables you to deposit an ASCII string of length n into an arbitrary program location. In the example, the location has a symbolic name (I) and, therefore, is associated with a compiler-generated integer type. The command syntax is as follows:

DEPOSIT/ASCII:n address-expression = "ASCII string of length n"

The default value of n is 4 bytes.

DBG> DEPOSIT I = "abcde" ! I has compiler-generated integer type. %DEBUG-W-INVNUMBER, invalid numeric string 'abcde' ! So, it cannot deposit string into I. DBG> DEP/ASCII:5 I = "abcde"! /ASCII qualifier overrides integer ! type to deposit 5 bytes of ! ASCII data. DBG> EXAMINE . ! Display value of I in compiler- MOD3\I: 1146048327 ! generated integer type. DBG> EXAM/ASCII:5 . ! Display value of I as 5-byte MOD3\I: "abcde" ! ASCII string. DBG>

To enter several DEPOSIT/ASCII commands, you can establish an override ASCII type with the SET TYPE/OVERRIDE command. Subsequent EXAMINE and DEPOSIT commands then have the effect of specifying the /ASCII qualifier with these commands. For example:

DBG> SET TYPE/OVER ASCII:5! Establish ASCII:5 as override type. DBG> DEPOSIT I = "abcde" ! Can now deposit 5-byte string into I. DBG> EXAMINE I ! Display value of I as 5-byte MOD3\I: "abcde" ! ASCII string. DBG> CANCEL TYPE/OVERRIDE ! Cancel ASCII override type. DBG> EXAMINE I ! Display I in compiler-generated type. MOD3\I: 1146048327 DBG>

4.5.2.3 User-Declared Types

The following examples show the use of the EXAMINE and DEPOSIT commands with the /TYPE=(name) qualifier. The qualifier enables you to specify a user-declared override type when examining or depositing.

For example, assume that a Pascal program contains the following code, which declares the enumeration type COLOR with the three values RED, GREEN, and BLUE:

. . . TYPE COLOR = (RED,GREEN,BLUE); . . .

During the debugging session, the SHOW SYMBOL/TYPE command identifies the type COLOR as it is known to the debugger:

DBG> SHOW SYMBOL/TYPE COLOR data MOD3\COLOR enumeration type (COLOR, 3 elements), size: 1 byte DBG>

The next example displays the value at address 1000, which is not associated with a symbolic name. Therefore, the value 0 is displayed in the type longword integer, by default.

DBG> EXAMINE 1000 1000: 0 DBG>

The next example displays the value at address 1000 in the type COLOR. The preceding SHOW SYMBOL/TYPE command indicates that each enumeration element is stored in 1 byte. Therefore, the debugger converts the first byte of the longword integer value 0 at address 1000 to the equivalent enumeration value, RED (the first of the three enumeration values):

DBG> EXAMINE/TYPE=(COLOR) 1000 1000: RED DBG>

The following DEPOSIT command deposits the value GREEN into address 1000 with the override type COLOR. The EXAMINE command displays the value at address 1000 in the default type, longword integer:

DBG> DEPOSIT/TYPE=(COLOR) 1000 = GREEN DBG> EXAMINE 1000 1000: 1 DBG>

The following SET TYPE command establishes the type COLOR for locations, such as address 1000, that do not have a symbolic name. The EXAMINE command now displays the value at 1000 in the type COLOR:

DBG> SET TYPE TYPE=(COLOR) DBG> EXAMINE 1000 1000: GREEN DBG>

Symbolic debugging enables you to specify variable names, routine names, and so on, precisely as they appear in your source code. You do not need to use numeric memory addresses or registers when referring to program locations.

In addition, you can use symbols in the context that is appropriate for the program and its source language. The debugger supports the language conventions regarding data types, expressions, scope and visibility of entities, and so on.

To have full access to the symbols that are associated with your program, you must compile and link the program using the /DEBUG command qualifier.

Under these conditions, the way in which symbol information is passed from your source program to the debugger and is processed by the debugger is transparent to you in most cases. However, certain situations might require some action.

For example, when you try to set a breakpoint on a routine named COUNTER, the debugger might display the following diagnostic message:

DBG> SET BREAK COUNTER %DEBUG-E-NOSYMBOL, symbol 'COUNTER' is not in the symbol table DBG>

You must then set the module where COUNTER is defined, as explained in Section 5.2.

The debugger might display the following message if the same symbol X is defined (declared) in more than one module, routine, or other program unit:

DBG> EXAMINE X %DEBUG-E-NOUNIQUE, symbol 'X' is not unique DBG>

You must then resolve the symbol ambiguity, perhaps by specifying a path name for the symbol, as explained in Section 5.3.

This chapter explains how to handle these and other situations related to accessing symbols in your program.

The chapter discusses only the symbols (typically address expressions) that are derived from your source program:

• The names of entities that you have declared in your source code, such as variables, routines, labels, array elements, or record components
• The names of modules (compilation units) and shareable images that are linked with your program
• Elements that the debugger uses to identify source code---for example, the specifications of source files, and source line numbers as they appear in a listing file or when the debugger displays source code

The following types of symbols are discussed in other chapters:

• The symbols you create during a debugging session with the DEFINE command are covered in Section 13.4.
• The debugger's built-in symbols, such as the period (.) and %PC, are discussed throughout this manual in the appropriate context and are defined in Appendix B.

Also, see Section 4.1.11 for information about how to obtain the memory addresses and register names associated with symbolic address expressions and how to symbolize program locations.

To take full advantage of symbolic debugging, you must compile and link your program with the /DEBUG qualifier as explained in Section 1.2.

The following sections describe how symbol information is created and passed to the debugger when compiling and linking.

5.1.1 Compiling

When you compile a source file using the /DEBUG qualifier, the compiler creates symbol records for the debug symbol table (DST records) and includes them in the object module being created.

DST records provide not only the names of symbols but also all relevant information about their use. For example:

• Data types, ranges, constraints, and scopes associated with variables
• Parameter names and parameter types associated with functions and procedures
• Source-line correlation records, which associate source lines with line numbers and source files

Most compilers allow you to vary the amount of DST information put in an object module by specifying different options with the /DEBUG qualifier. Table 5-1 identifies the options for most compilers (see the documentation supplied with your compiler for complete information).

Table 5-1 Compiler Options for DST Symbol Information

Compiler Command Qualifier	DST Information in Object Module
/DEBUG 1	Full
/DEBUG=TRACEBACK 2	Traceback only (module names, routine names, and line numbers)
/NODEBUG 3	None

The TRACEBACK option is a default for most compilers. That is, if you omit the /DEBUG qualifier, most compilers assume /DEBUG=TRACEBACK. The TRACEBACK option enables the traceback condition handler to translate memory addresses into routine names and line numbers so that it can give a symbolic traceback if a run-time error has occurred. For example:

$ RUN FORMS . . . %PAS-F-ERRACCFIL, error in accessing file PAS$OUTPUT %PAS-F-ERROPECRE, error opening/creating file %RMS-F-FNM, error in file name %TRACE-F-TRACEBACK, symbolic stack dump follows module name routine name line rel PC abs PC PAS$IO_BASIC _PAS$CODE 00000192 00001CED PAS$IO_BASIC _PAS$CODE 0000054D 000020A8 PAS$IO_BASIC _PAS$CODE 0000028B 00001DE6 FORMS FORMS 59 00000020 000005A1 $

Traceback information is also used by the debugger's SHOW CALLS command.

5.1.2 Local and Global Symbols

DST records contain information about all of the symbols that are defined in your program. These are either local or global symbols.

Typically, a local symbol is a symbol that is referenced only within the module where it is defined; a global symbol is a symbol such as a routine name, procedure entry point, or a global data name, that is defined in one module but referenced in other modules.

A global symbol that is defined in a shareable image and is referenced in another image (for example the main, executable image of a program) is called a universal symbol. When creating a shareable image, you must explicitly define any universal symbols as such at link time. See Section 5.4 for information about universal symbols and shareable images.

Generally, the compiler resolves references to local symbols, and the linker resolves references to global symbols.

The distinction between local and global symbols is discussed in various parts of this chapter in connection with symbol lookup and with shareable images and universal symbols.

5.1.3 Linking

When you enter the LINK/DEBUG command to link object modules and produce an executable image, the linker performs several functions that affect debugging:

• It builds a debug symbol table (DST) from the DST records contained in the object modules being linked. The DST is the primary source of symbol information during a debugging session.
• It resolves references to global symbols and builds a global symbol table (GST). The GST duplicates some of the global symbol information already contained in the DST, but the GST is used by the debugger for symbol lookup under certain circumstances.
• It puts the DST and GST in the executable image.
• It sets flags in the executable image that cause the image activator to pass control to the debugger when you enter the DCL command RUN (see Section 1.2).

Section 5.4 explains how to link shareable images for debugging, including how to define universal symbols (global symbols that are defined within a shareable image and referenced from another image).

Table 5-2 summarizes the level of DST and GST information passed to the debugger depending on the compiler or LINK command option. The compiler command qualifier controls the level of DST information passed to the linker. The LINK command qualifier controls not only how much DST and GST information is passed to the debugger but also whether the program can be brought under debugger control (see Section 1.2).

Table 5-2 Effect of Compiler and Linker on DST and GST Symbol Information

Compiler Command Qualifier1	DST Data in Object Module	LINK Command Qualifier2	DST Data Passed to Debugger	GST Data Passed to Debugger3
/DEBUG	Full	/DEBUG	Full	Full
/DEBUG=TRACE	Traceback only	/DEBUG	Traceback only	Full
/NODEBUG	None	/DEBUG	None	Full
/DEBUG	Full	/DSF 4	Full	Full 5
/DEBUG=TRACE	Traceback only	/DSF 4	Traceback only	Full 5
/NODEBUG	None	/DSF 4	None	Full 5
/DEBUG	Full	/TRACE 6	Traceback only	Full
/DEBUG=TRACE	Traceback only	/TRACE	Traceback only	Full
/NODEBUG	None	/TRACE	None	Full
/DEBUG	Full	/NOTRACE 7

If you specify /NODEBUG with the compiler command and subsequently link and execute the image, the debugger issues the following message when the program is brought under debugger control:

%DEBUG-I-NOLOCALS, image does not contain local symbols

The previous message, which occurs whether you linked with the /TRACEBACK or /DEBUG qualifier, indicates that no DST has been created for that image. Therefore, you have access only to global symbols contained in the GST.

If you do not specify /DEBUG with the LINK command, the debugger issues the following message when the program is brought under debugger control:

%DEBUG-I-NOGLOBALS, some or all global symbols not accessible

The previous message indicates that the only global symbol information available during the debugging session is stored in the DST.

These concepts are discussed in later sections. In particular, see Section 5.4 for additional information related to debugging shareable images.

5.1.4 Controlling Symbol Information in Debugged Images

Symbol records occupy space within the executable image. After you debug your program, you might want to link it again without using the /DEBUG qualifier to make the executable image smaller. This creates an image with only traceback data in the DST and with a GST.

The LINK/NOTRACEBACK command enables you to secure the contents of an image from users after it has been debugged. Use this command for images that are to be installed with privileges (see the OpenVMS System Manager's Manual and the HP OpenVMS System Management Utilities Reference Manual). When you use the /NOTRACEBACK qualifier with the LINK command, no symbolic information (including traceback data) is passed to the image.

5.1.5 Creating Separate Symbol Files (Alpha Only)

On Alpha systems, you can LINK your program with the /DSF qualifier to create a separate file that contains symbol information. By default, the symbol file has the same file name as the executable file created by the LINK utility, and has file type .DSF. For example:

$ CC/DEBUG/NOOPTIMIZE TESTPROGRAM.C $ LINK/DSF TESTPROGRAM $ DEFINE DBG$IMAGE_DSF_PATH SYS$DISK:[] $ DEBUG/KEEP TESTPROGRAM

This example does the following:

1. Compiles TESTPROGRAM.C
2. Creates TESTPROGRAM.EXE and TESTPROGRAM.DSF
3. Defines logical name DBG$IMAGE_DSF_PATH as the current directory
4. Invokes the kept debugger

This procedure allows you to create smaller executable files and still have global symbol information available for debugging. Certain applications, such as installed resident files, require that the executable not contain symbol tables. In addition, .DSF files allow you to deliver executable files without symbol tables to customers, but retain separate .DSF files for future debugging needs.

Debugging an executable file that has a separate symbol (.DSF) file requires the following:

• The name of the .DSF file must match the name of the .EXE file being debugged.
• You must define DBG$IMAGE_DSF_PATH to point to the directory that contains the .DSF file.

See the HP OpenVMS Linker Utility Manual for more information about using the /DSF qualifier.

5.2 Setting and Canceling Modules

You need to set a module if the debugger is unable to locate a symbol that you have specified (for example, a variable name X) and issues a message as in the following example:

DBG> EXAMINE X %DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table DBG>

This section explains module setting, and the conditions under which you might need to set or cancel a module, using the SET MODULE and CANCEL MODULE commands.

When you compile and link your program using the /DEBUG command qualifier, as explained in Section 5.1, complete symbol information is passed from the program's source code to its executable image.

Symbol information is contained in the debug symbol table (DST) and global symbol table (GST) within the executable image. The DST contains detailed information about local and global symbols. The GST duplicates some of the global symbol information contained in the DST.

To facilitate symbol searches, the debugger loads symbol information from the DST and GST into a run-time symbol table (RST), which is structured for efficient symbol lookup. Unless symbol information is in the RST, the debugger does not recognize or properly interpret the associated symbol.

Because the RST takes up memory, the debugger loads it dynamically, anticipating what symbols you might want to reference in the course of program execution. The loading process is called module setting, because all symbol information for a given module is loaded into the RST at one time.

When your program is brought under debugger control, all GST records are loaded into the RST, because global symbols must be accessible throughout the debugging session. Also, the debugger sets the module that contains the main program (the routine specified by the image transfer address, where execution is paused at the start of a debugging session). You then have access to all global symbols and to any local symbols that should be visible within the main program.

Subsequently, whenever execution of the program is interrupted, the debugger sets the module that contains the routine in which execution is paused. (For Ada programs, the debugger also sets any module that is related by a with-clause or subunit relationship, as explained in the debugger's online help. Type Help Language_Support_Ada.) This enables you to reference the symbols that should be visible at that program location (in addition to the global symbols). This default mode of operation is called dynamic mode. When setting a module dynamically, the debugger issues a message such as the following:

%DEBUG-I-DYNMODSET, setting module MOD4

If you try to reference a symbol that is defined in a module that has not been set, the debugger warns you that the symbol is not in the RST. You must then use the SET MODULE command to set the module containing that symbol explicitly. For example:

DBG> EXAMINE X %DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table DBG> SET MODULE MOD3 DBG> EXAMINE X MOD3\ROUT2\X: 26 DBG>

The SHOW MODULE command lists the modules of your program and identifies which modules are set.

When a module is set, the debugger automatically allocates memory as needed by the RST. This can eventually slow down the debugger as more modules are set. If performance becomes a problem, you can use the CANCEL MODULE command to reduce the number of set modules, which automatically releases memory. Or you can disable dynamic mode by entering the SET MODE NODYNAMIC command. When dynamic mode is disabled, the debugger does not set modules automatically. Use the SHOW MODE command to determine whether dynamic mode is enabled or disabled.

For additional information about module setting specific to Ada programs, see the debugger's online help (type Help Language_Support_Ada).

Section 5.4 explains how to set images and modules when debugging shareable images.