option_stopwatch

OPTION_STOPWATCH

sets StopWatch options

SYNOPSIS
subroutine option_stopwatch (default_clock, io_unit_print, io_unit_error, print_errors, abort_errors, print_form, err)

character(len=*), optional, intent(IN) :: default_clock(:)

OR

character(len=*), optional, intent(IN) :: default_clock

integer, optional, intent(IN) :: io_unit_print, io_unit_error

logical, optional, intent(IN) :: print_errors, abort_errors

character(len=*), optional, intent(IN) :: print_form

integer, optional, intent(OUT) :: err

DESCRIPTION
Sets options that control the behavior of StopWatch . All arguments are optional and have intent IN, with the exception of the status code err which has intent OUT. These options are global in nature, and remain in effect until another call to option_stopwatch changes them.

The argument default_clock determines what clocks will be used for all subsequent operations in which the clock argument is omitted. This allows you to specify what clocks you are interested in once and for all, and not have to specify those clocks with every subroutine call. The initial default value is (/'cpu ', 'user', 'sys ', 'wall'/), i.e., all clocks. However, if any clocks are not available in the implementation, they will be automatically removed from the list of default clocks.

Printed output can be redirected to any valid I/O unit number. io_unit_print determines the unit for output from subroutine print_watch. io_unit_error determines the unit for any error messages printed by StopWatch . When an I/O unit is reset by one of these variables, the unit must already be open for writing. The initial default is 6 for both I/O units, which is standard output on many systems.

What to do when an error occurs is controlled by the two logical variables print_errors and abort_errors. If print_errors is TRUE, then an error message will be printed to io_unit_error whenever an error condition occurs. In all cases where an error can be detected, the program can continue to execute, although the behavior of StopWatch might not be as expected. If abort_errors is TRUE, then the program will terminate when an error condition occurs. The initial defaults are TRUE for print_errors and FALSE for abort_errors.

The argument print_form determines the form for printing time when form

is omitted in print_watch. Currently all the forms print the time to .01 seconds. The valid values for print_form are:

'sec',

seconds

'hh:mm:ss',

colon separated hours, minutes and seconds

'[[hh:]mm:]ss',

same as 'hh:mm:ss' except hours and minutes are printed only if nonzero

The default value is 'sec'.

DIAGNOSTICS
If present, the optional intent OUT integer argument err returns a status code. The code is the sum of the values listed below.

The relevant status codes and messages are:

0

No errors; execution successful.

8

Invalid clock type. This occurs if default_clock is present and one of the specified clocks is not supported by the implementation. See inquiry_stopwatch(3) to determine what clocks are available.

16

Too many clocks specified. This occurs when the argument default_clock is an array longer than four.

256

I/O unit is not open for writing. The I/O unit requested for io_unit_print or io_unit_error is not open for writing.

512

Failed to allocate required memory. This error occurs if the Fortran allocate statement returns a nonzero status indicating that memory could not be allocated. Avoid memory leaks by always destroying watches and groups before recreating them, and destroying local variable watches and groups before returning from a subroutine.

1024

Error occurred while deallocating memory. This error occurs if the Fortran deallocate statement returns a nonzero status while deallocating memory. Be aware that other problems could develop as a result of the deallocate error.

2048

Illegal output form. This error occurs if print_form is not one of the strings listed above.

In addition to the run time diagnostics generated by StopWatch , the following problem may arise:

In Fortran 90, the character strings in an array constructor must all have the same length. Pad three letter clock names with a blank on the right to make a four character string, for example, 'cpu '.

EXAMPLES
call option_stopwatch(default_clock='cpu', abort_error=.true.)
call option_stopwatch(io_unit_print=11, io_unit_error=12)

The first call sets the default clock to be the cpu clock and says to terminate the program if an error occurs. The second call reassigns the I/O units.

BUGS
None known.