Calling User-Defined Subprograms (GNAT User’s Guide for Native Platforms)

#### 6.1.5 Calling User-Defined Subprograms ¶

An important capability of `GDB` is the ability to call user-defined subprograms while debugging. You do this by simply entering a subprogram call statement in the form:

>     call subprogram-name (parameters)

You can omit the keyword `call` in the normal case where the `subprogram-name` does not coincide with any of the predefined `GDB` commands.

The effect is to invoke the given subprogram, passing it the list of parameters that is supplied. The parameters you specify can be expressions and can include variables from the program being debugged. The subprogram must be defined at the library level within your program and `GDB` will call the subprogram within the environment of your program execution (which means that the subprogram is free to access or even modify variables within your program).

The most important use of this facility that you can include debugging routines that are tailored to particular data structures in your program. You can write such debugging routines to provide a suitably high-level description of an abstract type, rather than a low-level dump of its physical layout. After all, the standard `GDB print` command only knows the physical layout of your types, not their abstract meaning. Debugging routines can provide information at the desired semantic level and are thus enormously useful.

For example, when debugging GNAT itself, it is crucial to have access to the contents of the tree nodes used to represent the program internally. But tree nodes are represented simply by an integer value (which in turn is an index into a table of nodes). Using the `print` command on a tree node would simply print this integer value, which is not very useful. But the `PN` routine (defined in file `treepr.adb` in the GNAT sources) takes a tree node as input and displays a useful high level representation of the tree node, which includes the syntactic category of the node, its position in the source, the descendant nodes and parent node, as well as lots of semantic information. To study this example in more detail, you might want to look at the body of the `PN` procedure in the above file.

Another useful application of this capability is to deal with situations where complex data which are not handled suitably by GDB. For example, if you specify Convention Fortran for a multi-dimensional array, GDB does not know that the ordering of array elements has been switched and will not properly address the array elements. In such a case, instead of trying to print the elements directly from GDB, you can write a callable procedure that prints the elements in the format you desire.