Using Qualified Names

Block Qualified Names

The debugger uses block qualified names to refer to variables that are not visible from the current environment. A block qualified name explicitly identifies the block enclosing the object and the object's name; the format is block\object_name. Specifying a block in addition to a name changes the scope by specifying the starting block of the search.

For example, if the current environment is line 16 in Figure 7-1 “Sample Module Illustrating Scope and Visibility ”, you can use the block qualified name

myprog\Z

to refer to variable Z on line 3. Use the block qualified name

sort\Z

to refer to variable Z on line 12 in Figure 7-1 “Sample Module Illustrating Scope and Visibility ”.

With block qualified names, you can also combine variables from different blocks in a single expression. For example, use

myprog\Z + sort\Z

to refer to the sum of Z in myprog and Z in sort.

You can use block qualified names to explicitly identify variables that are not visible, including variables in currently inactive modules (files) and routines. Note, however, that if the value identified is a stack allocated variable, the variable is only visible when it is on the call stack.

Fully Qualified Names

A fully qualified name identifies all blocks that enclose the object.

To identify objects, the debugger uses fully qualified names in the following format:

\module\[block[\block. . .]]\object_name

where module is a module or a top-level name.

In Pascal, module is specified by the module keyword. In C, module is the source file name with the .c extension removed. In FORTRAN, modules do not exist, so a top-level name is the routine name—MAIN, a program name, or a subroutine.

Specifying a fully qualified name is useful for avoiding ambiguity, when you want to reference an object that is not visible from the current environment.

Use the list blocks command to display the fully qualified names for all the blocks in the target program.

For example, Figure 7-2 “Sample Modules Illustrating Fully Qualified Names ” shows a target program in C compiled from two modules, m1.c and m2.c.

Figure 7-2 Sample Modules Illustrating Fully Qualified Names

The following list shows how to reference each instance of the variable z by using fully qualified names:

Note that fully qualified names can be preceded by either a single backslash (\) or a double backslash (\\). The debugger, however, prints fully qualified names preceded by a double backslash. For example:

print \m2\procA\z \\m2\procA\z: 600

By default, the debugger prints fully qualified names. You can change the default behavior with the property qual_max command. For example, if you specify property qual_max 0 and issue a print command, the debugger prints only the object name and its value; other blocks enclosing the object are not identified.

Image Qualified Names

An image qualified name may be necessary to eliminate ambiguity among module names when an application consists of more than one executable image (loaded object file or shared library). This occurs whenever an application contains a dynamically loaded library. More than one image may contain modules with the same name.

An image qualified name starts with the notation `image(image_name), where image_name is the shortest unique path name of the object file. Use the list images command to list the names of the known images.

For example, suppose that your application consists of the executable image average that contains the procedures main, sum, and print_average, and the dynamically loaded libraries highlib and lowlib. Since one or more of the libraries may contain a procedure named print_average or sum, you can use the image qualified name

`image(average)\average\sum

where `image(average) contains average, to name the procedure sum.

Special Block Qualified Forms

The debugger provides additional block qualified forms that you can use to refer to symbol names that are defined by the programming language or the user, and to refer to symbols that are externally declared.

Qualified Names for Predefined, User-Declared, and External Symbols

Symbol names that are defined by the programming language (usually type names such as integer or int) begin with `predefined and reside in outer debugger blocks. Use the list blocks command to view these blocks and names. You can explicitly refer to a language-defined symbol name by using a block qualified name of the form `predefined(lang_type,obj_type)\name. For example:

`predefined(lang_c,obj_som)\int

See Appendix B “Language Managers ” and Appendix D “Object Managers ” for information on the valid values for lang_type and obj_type.

You may explicitly refer to user-declared symbol names, created with the declare command, by using a block qualified name of the form `declared\name. User-declared symbol names are defined in an outer block named `declared. Since program symbol names visible from the current environment are searched before user-declared symbol names, user-declared symbol names may be hidden by program symbol names.

When the debugger cannot find a symbol name by following the normal scope rules or by searching the outer language or user-declared blocks, it looks at variables declared to be external (that is, variables declared to be visible everywhere). Similarly, when the debugger cannot find a block name, it searches for a procedure not enclosed within another procedure.

Frame Block Qualified Names

You can identify dynamically activated symbols within recursive procedures using frame block qualifiers. Frame block qualifiers use both a block and a frame to specify the current environment.

Recursive procedures are called multiple times and produce multiple frames (invocations) on the call/return stack. The debugger distinguishes one invocation from another by identifying the current environment as both a block and a frame. The block serves as a naming context, as described in “Block Qualified Names ”, and helps to determine which variable names are visible and which are not. The frame indicates which invocation of that block the debugger should use to locate local data.

When a recursive procedure produces more than one instance of a block on the call/return stack, local symbols in that block have more than one instance. The current environment consists of both a frame and a block. The debugger uses the block to determine which variable is intended, and it uses the frame to determine which instance of that variable to use.

If a block has not been invoked, then the block is said to be inactive, and you may only examine its static data objects. If a block has been invoked once, then that instance is used. In the example shown in Figure 7-3 “Sample Call/Return Stack and Program ”, use print_answer\COUNTER to refer to the COUNTER variable in frame `main(5). If a block has been invoked more than once, the most recent instance is chosen by default; for example, binary_search\HI refers to the HI variable in frame `main(4) by default.

Figure 7-3 Sample Call/Return Stack and Program

There are three ways to refer explicitly to symbols using a frame block qualifier:

main relative

The notation is `main(n) where n is the number of the frame counting from the least recent frame of the call/return stack to the desired frame. In the example in Figure 7-3 “Sample Call/Return Stack and Program ”, the frame with print_answer is `main(5). `main by itself refers to the oldest frame in the stack. This frame may not refer to your main program because in some cases a procedure in a run-time library may be at the base of your stack.

run relative

The notation is `run(n) where n is the number of the frame counting from the most recent frame in the program (that is, the location where the program is stopped). In Figure 7-3 “Sample Call/Return Stack and Program ”. the frame with print_answer is `run(2). `run by itself refers to the location where the program is stopped.

environment relative

The notation is `env(-n) where n counts up (toward `main) from the current environment. The notation is `env(+n) where n counts down (toward `run) from the current environment. `env by itself refers to the current environment.

In Figure 7-3 “Sample Call/Return Stack and Program ”, you can refer to the instances of variable HI as `run(3)\HI, `run(4)\HI, and `run(5)\HI. You could also refer to the variables with `main or `env notation. A frame qualified name may not contain block qualifiers (that is, `main\blk is not valid).

Also, you can use frame names with the environment command to change your environment to any procedure on the call/return stack. For example, you can set the environment to the current point of execution using:

environment `run