Use this option to elevate warning-level messages to error-level status.

-warning_severity error

Makes all compiler warning messages error-level instead of warning-level messages.

-warning_severity stderror

Makes standards checking compiler warning messages ( -std option) error-level instead of warning-level messages.

The -what option prints the version string of the Fortran command and compiler. If this option appears on the command line alone, the program will not compile.

3.87 -wsf, -wsf num, and Related Options --- Compile for DIGITAL Parallel Software Environment Execution

Specifying the -wsf option indicates that the executable program will be compiled to execute in parallel on multiple processors (requires the DIGITAL Parallel Software Environment).

If you omit the -wsf option, the executable program will execute in a nonparallel (serial) run-time environment (HPF directives are only checked for correct syntax).

To specify the number of processors on which the program is intended to run, specify the optional num field, such as -wsf 3 . If you omit num and specify -wsf, the compiler generates code that can run on any number of processors. However, better performance occurs if num is used.

When the HPF parallel programs are compiled with the -c option and linked separately, specify -wsf both when compiling and linking the program.

If you specify -wsf or -wsf num , you can specify additional parallel execution options using the -assume nozsize , -nearest_neighbor or -nearest_neighbor num options, -pprof option, -show wsfinfo option, and High Performance Fortran ( !hpf$ ) directives.

For information about using the -wsf (or -wsf num ) option and on parallel HPF programs, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual.

For information about any limitations when you use the -wsf or -wsf num option, see the online DIGITAL Fortran 90 release notes.

3.87.1 -assume bigarrays --- Run-time Checking for Distributed Small Array Dimensions

Specifying the -assume bigarrays option suppresses run-time checking for distributed small array dimensions. This allows for increased run-time performance and reduced compile time when using the -wsf option.

In programs compiled with both the -wsf and -assume bigarrays options, nearest-neighbor computations that reference small arrays will fail. An array is big enough if, for every dimension with BLOCK distribution, the shadow edge width is no bigger than the block size. The default is -assume nobigarrays .

3.87.2 -assume nozsize --- Omit Zero-Sized Array Checking

Specify the -assume nozsize option with the -wsf option to let the compiler know there are no zero-sized arrays or array sections.

An array (or array section) is zero sized when the extent of any of its dimensions takes the value zero or less than zero. When the -wsf option is specified, the compiler ordinarily inserts a series of checks to guard against irregularities (such as division by zero) in its internal computations that zero-sized arrays can cause. Depending upon the particular application, these checks can cause noticeable (or even major) degradation of performance.

The -assume nozsize option causes the compiler to omit these checks for zero-sized arrays and array sections. Specifying the -fast option sets the -assume nozsize option.

Avoid using the -assume nozsize option with -wsf when a program references any zero-sized arrays or array sections. If you compile a program containing zero-sized arrays or array sections with the -assume nozsize option, the resulting executable may fail to execute, or produce incorrect program results.

You can insert a run-time check into your program to ensure that a given line is not executed if an array or array section referenced there is zero sized (see the DIGITAL High Performance Fortran 90 HPF and PSE Manual).

3.87.3 -nearest_neighbor, -nearest_neighbor num, or -nonearest_neighbor --- Nearest Neighbor Optimization

Use the -nearest_neighbor option with the -wsf option control nearest neighbor optimizations. The compiler automatically determines the correct shadow-edge widths on an array-by-array, dimension-by-dimension basis.

When programs are compiled with the -wsf option, the -nearest_neighbor option is active by default.

Use the optional num field to specify a maximum shadow-edge width, which limits how much extra storage the compiler can allocate for nearest-neighbor arrays.

When num is specified, the compiler will only recognize nearest neighbor constructs that need shadow-edge widths less than or equal to the value of num. Constructs needing shadow-edge widths greater than the value of num will not be recognized as nearest-neighbor.

If num is not specified, the compiler uses a num value of ten (10).

You can also set shadow-edge widths manually, using the !HPF$ SHADOW directive (see the DIGITAL High Performance Fortran 90 HPF and PSE Manual).

The -nonearest_neighbor option turns off the nearest-neighbor optimization. It is equivalent to specifying -nearest_neighbor with nn set to 0.

For more information on the -nearest_neighbor option, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual.

3.87.4 -pprof method --- Prepare for Parallel Profiling

Use the -pprof option to prepare a parallel HPF program for subsequent profiling with the pprof profiler. To use the -pprof option, you must:

• Specify the -wsf option.
• Specify one of the -pprof sampling methods:
  • To request interval sampling, use -pprof i
  • To request program counter sampling, use -pprof s .
• Omit the -p1 and -p options.
• If you specify -pprof s , you can:
  • Specify the -non_shared option if you want profiling information for archive libraries
  • Specify -pprof s during linking for existing object files

For more information on -pprof and related options, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual.

3.87.5 -show hpf --- Show HPF Parallelization Information

The -show hpf options show information about HPF parallelization by displaying the information to standard error and to the listing (if one is generated using the -v option). These options are valid only if the -wsf option is specified.

Specifying -show hpf selects a subset of the messages generated by all of the following -show hpf_ options. Try using -show hpf first, with the following variations only when a more detailed listing is needed.

-show hpf_all

This is the same as specifying all the other -show hpf_ options. The obsolete -show wsfinfo option is equivalent to -show hpf_all .

-show hpf_comm

This instructs the compiler to display information about statements that cause interprocessor communication to be generated.

-show hpf_indep

This instructs the compiler to display information about the optimization of loops marked with the INDEPENDENT directive.

-show hpf_nearest

This instructs the compiler to display information about arrays and statements involved in optimized nearest-neighbor computations.

-show hpf_punt

This instructs the compiler to display information about distribution directives that were ignored and statements that were not handled in parallel.

-show hpf_temps

This instructs the compiler to display information about temporaries that were created at procedure interfaces.

The -show option can take only one argument at a time. To mix -show options, use multiple specification. For example:

% f90 -wsf -show hpf_near -show hpf_comm -show hpf_punt foo.f90

For more information on the -show hpf option, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual.

For More Information:

• On Parallel Software Environment installation, setup, system administration, and use, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual
• On f90 options, developing, debugging, and profiling HPF programs using the Parallel Software Environment, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual
• On compiling an HPF global routine that will be linked with a main program that was not compiled with the -wsf option, see Section 3.56.

This chapter describes the following topics related to the DIGITAL UNIX Ladebug Debugger:

• About the Ladebug (formerly DECladebug) and dbx debuggers ( Section 4.1)
• DIGITAL Fortran 90 command options for debugging ( Section 4.2)
• Running and exiting Ladebug ( Section 4.3)
• Sample program and debugging session ( Section 4.4)
• Summary of debugger commands ( Section 4.5)
• Viewing DIGITAL Fortran 90 variables ( Section 4.6)
• Expressions in Debugger Commands ( Section 4.7)
• Debugging mixed-language programs with Ladebug ( Section 4.8)
• Debugging a program that generates an exception ( Section 4.9)
• Locating unaligned data ( Section 4.10)
• Use of alternate entry points during debugging ( Section 4.11)
• Debugging optimized programs ( Section 4.12)

The Ladebug debugger supports DIGITAL Fortran 90 data types, syntax, and use. Ladebug is a source-level, symbolic debugger that lets you:

• Control the execution of individual source lines in a program.
• Set stops (breakpoints) at specific source lines or under various conditions.
• Change the value of variables in your program.
• Refer to program locations by their symbolic names, using the debugger's knowledge of the DIGITAL Fortran 90 language to determine the proper scoping rules and how the values should be evaluated and displayed.
• Print the values of variables and set a trace (tracepoint) to notify you when the value of a variable changes.
• Perform other functions, such as examining core files, examining the call stack, or displaying registers.

The DIGITAL UNIX operating system provides the Ladebug and the dbx debuggers, both of which can be used to debug DIGITAL Fortran 90 programs.

The command names and command syntax used by Ladebug and dbx are almost identical. However, Ladebug provides significantly more DIGITAL Fortran 90 language support than dbx, especially Fortran 90 features not found in the FORTRAN-77 standard. For this reason, this chapter primarily describes the Ladebug debugger.

If you will be using the Parallel Software Environment, before you create a parallel HPF program (specify the -wsf option), you should fully debug the program in scalar (non-parallel) form (omit -wsf ).

For information:

• About debugging parallel HPF programs using the Parallel Software Environment, see the DIGITAL High Performance Fortran 90 HPF and PSE Manual.
• About debugging directed parallel programs see Chapter 6.

The -gnum options control the amount of information placed in the object file for debugging. To use Ladebug, you should specify the -ladebug option along with the -g , -g2 , or -g3 options.

Table 4-1 summarizes the information provided by the -g num options and their relationship to the -onum options.

Table 4-1 Summary of Symbol Table Command Options

Option	Traceback Information	Debugging Symbol Table Information	Effect on -On Options
-g0	No	No	Default is -o4 .
-g1 (default)	Yes	No	Default is -o4 .
-g or -g2 1	Yes	Yes, but for unoptimized code.	Changes default to -o0 .
-g3	Yes	Yes, but for unoptimized code.	Default is -o4 .
-ladebug	Yes	Allows access to Fortran 90 dynamic arrays using standard Fortran 90 syntax, including array sections.	No effect.

Traceback information and symbol table information are both necessary for debugging. As shown in Table 4-1, if you specify -g , -g2 , or -g3 , the compiler provides the symbol table and traceback information needed for symbolic debugging. Unless you specify -g0 , the compiler supplies traceback information in the object file.

To use the Ladebug debugger, you should specify the f90 command option -ladebug along with -g , -g2 , or -g3 .

Likely uses of these options at the various stages of program development are as follows:

• During early stages of program development, use the -g ( -g2 ) option to create unoptimized code (optimization level -o0 ). This option also might be chosen later to debug reported problems from later stages.
• During the later stages of program development, use -g0 or -g1 to minimize the object file size and, as a result, the memory needed for program execution, usually with optimized code (see Chapter 5).

Traceback and symbol table information result in a larger object file. When you have finished debugging your program, you can recompile and relink to create an optimized executable program or remove traceback and symbol table information with the strip command (see strip(1)).

If your program generates an exception, see Section 4.9.

4.3 Running the Debugger

The Ladebug debugger provides the following user interfaces in the DIGITAL UNIX operating system Programmer's Development Toolkit:

• A graphical Ladebug windowing interface. The command name for the windowing interface is dxladebug .
• A character-cell interface. To use the character-cell interface, invoke the ladebug command.

The examples in this chapter show the character-cell interface to the Ladebug debugger.

Figure 4-1 shows an example of Ladebug graphical windowing interface on a DIGITAL UNIX Version 4.0 system.

For more information on the Ladebug debugger windowing interfaces, use online windowing help or the DIGITAL UNIX Ladebug Debugger Manual: Command-Line Interface.

Figure 4-1 Example of the Ladebug Graphical Windowing Interface

Use the f90 command with certain options to create an executable program for debugging. To invoke the debugger, type the debugger shell command and the name of the executable program.

4.3.1.1 Using Ladebug

The following commands create (compile and link) the executable program and invoke the character-cell interface to the Ladebug debugger:

% f90 -g -ladebug -o squares squares.f90 % ladebug squares Welcome to the Ladebug Debugger Version x.x-xx --------------- object file name: squares reading symbolic information ... done (ladebug)

In this example, the f90 command:

• Compiles and links the program squares.f90 .
• Requests symbol table information needed for symbolic debugging and no optimization ( -g and -ladebug ).
• Names the executable file squares instead of a.out ( -o squares).

The ladebug shell command runs the debugger, specifying the executable program squares . The ladebug command accepts various options (see ladebug(1)).

At the debugger prompt ( (ladebug) ), you can enter a debugger command, such as run , print , list , or quit .

4.3.1.2 Using dbx

The following commands create the executable program and invoke the dbx debugger:

% f90 -g -o squares squares.f90 % dbx squares dbx version x.x.x Type 'help' for help. squares: 1 PROGRAM SQUARES (dbx)

In this example, the f90 command:

• Compiles and links the program squares.f90 .
• Requests symbol table information needed for symbolic debugging and no optimization ( -g ). Omit the -ladebug option if you will use dbx.
• Names the executable file squares instead of a.out ( -o squares).

The dbx shell command runs the debugger, specifying the executable program squares . The dbx command accepts various options (see dbx(1)).

At the debugger prompt ( (dbx) ), you can enter a debugger command.

The command names and command syntax used by Ladebug and dbx are almost identical.

4.3.2 Debugger Commands and Breakpoints

To find out what happens at critical points in your program, you need to stop execution at these points and look at the contents of program variables to see if they contain the correct values. Points at which the debugger stops program execution are called breakpoints.

To set a breakpoint, use one of the forms of the stop or stopi commands.

Using the program created in Section 4.3.1, the following debugger commands set a breakpoint at line 4, run the program, continue the program, delete the breakpoint, rerun the program, and return to the shell:

(ladebug) stop at 4 [#1: stop at "squares.for":4 ] (ladebug) run [1] stopped at [squares:4 0x120001880] > 4 OPEN(UNIT=8, FILE='datafile.dat', STATUS='OLD') (ladebug) cont Process has exited with status 0 (ladebug) delete 1 (ladebug) rerun Process has exited with status 0 (ladebug) quit %

1. The stop at 4 command sets a breakpoint at line 4.
   To set a breakpoint at the start of a subprogram (such as calc), use the stop in (such as stop in calc ).
2. The run command begins program execution and stops at the first breakpoint. The program is now active, allowing you to view the values of variables with print commands and perform related functions.
3. The cont (continue) command resumes program execution.
   In addition to the cont command, you can also use the step , next , run , or rerun commands to resume execution.
4. The delete 1 command shows how to delete a previously set breakpoint (with event number 1). For instance, you might need to delete a previously set breakpoint before you use the rerun command.
5. The rerun command runs the program again. Since there are no breakpoints, the program runs to completion.
6. The quit command exits the debugger and returns to the shell.

Other debugger commands include the following:

• To get help on debugger commands, type the help command.
• To display previously typed debugger commands, type the history command.
• To look at the contents of a location, use the print or dump commands.
• You can use the debugger sh command (followed by the desired shell command) to execute a shell command. For instance, if you cannot recall the name of a FUNCTION statement, the following grep shell command displays the lines containing the letters FUNCTION, allowing use of the function name (subsort) in the stop in command:

  (ladebug) sh grep FUNCTION data.for INTEGER*4 FUNCTION SUBSORT (A,B) (ladebug) stop in subsort (ladebug)