APPENDIX D: 
Debugging


The SPP preprocessor, xc, recognizes many syntax errors. Needless to 
say, not all programming errors will be caught this way. Since SPP is pre-
processed into Fortran, it is useful to know a bit about the resulting Fortran 
code in order to find programming errors. The most instructive way to 
understand the code is to look at it. Use the -f option of xc to preserve the 
Fortran output. Many times errors are apparent in the Fortran code without 
having to use a source-level debugger at all.

Identifier Mapping

Since the Fortran produced by xc is Fortran 66, identifier names must be 
six characters or fewer, with no special characters such as underscores. SPP 
however, permits longer identifier names with the underscore character. 
The xc preprocessor maps such names by first removing underscores and 
using up to the first five characters of the identifier and the last character. 
The xc preprocessor writes a table of the original SPP identifiers and the 
mapped Fortran names at the end of the output Fortran as comments. If dif-
ferent SPP identifiers map to the same Fortran identifier, xc issues a warn-
ing that the identifier mapping is not unique and creates a unique identifier 
by replacing the last character with a digit in one case.

Dynamic Memory

It is possible to examine the values of dynamically allocated memory. 
These are treated as a Fortran common block, with all of the Mem arrays 
equivalenced to a single array. The relevant Fortran code generated is 
shown in Example D.1.

<PostScript figures omitted>
Example D.1: Fortran Code for Handling Dynamically Allocated Memory.

VMS

The VAX/VMS debugger permits examining the Mem arrays. Keep in 
mind the manner in which the array was allocated, however. The pointer is 
an arbitrary offset into virtual memory. The elements of your array are 
located relative to the pointer. The debugger will not know the size of the 
array, but you can specify a range of elements to examine. Once the pointer 
is dereferenced by passing to a procedure, it is treated as a normal Fortran 
array. However, be particularly careful of arrays declared in procedures 
with ARB. ARB is a macro that translates into a very large number. If you 
examine an array declared ARB without specifying a range of elements, the 
debugger will try and list what it thinks are all of the elements of the array. 
Remember to specify a range of array elements.

Unix

In the Unix dbx debugger, it is a bit more tedious to examine the con-
tents of a dynamically allocated arrays. You need to specify the memory 
location (pointer address) and the data type to display. For example, if a 
pointer to Memr is in a variable called line, then the following dbx com-
mand will display the first element: 

print (line-1)*4/f 

To look at the nth element, add n to the word location: 

print ((line-1)*4+10)/f 

will show the 10th element. The following dbx initialization file defines 
command aliases to help examine contents of the Mem buffers. It may be 
placed in the file .dbxinit in the Unix root directory. 

<PostScript figures omitted>
Example D.2: Unix .dbxinit Debugging File.

The commands are used by specifying the symbol name of the memory 
pointer. For example if the SPP code contained: 

        call malloc (buf, npix, TY_REAL) 

        call myproc (Memr[buf], npix) 

Then you could examine the first element of the memory buffer pointed to 
by buf with the dbx command:

        memr buf

Task

The single line SPP task statement results in a very large amount of 
Fortran code. This implements a single procedure called sys_runtask, 
which is mapped to the Fortran name SYSRUK. This is because there is a 
great deal of processing dealing with selecting tasks and handling errors. 
Normally, there is no need to look at the preprocessed code for the task. 
When your task is compiling, you will see this procedure being compiled. 
Be aware also that when you are debugging, your top-level applications 
procedure is a subroutine of the task, which is, in turn, a subroutine of the 
IRAF main procedure. The top level IRAF main is part of the IRAF kernel 
and therefore written in C. Most debuggers will somehow make it known 
that they are trying to debug C code. This is usually not important.