TRACEBACKQQ

Run-Time Subroutine: Provides traceback information. Uses the Visual Fortran run-time library traceback facility to generate a stack trace showing the program call stack as it appeared at the time of the call to TRACEBACKQQ( ).

Module: USE DFLIB

Syntax

CALL TRACEBACKQQ ([string] [, user_exit_code] [, status] [, eptr])

string
(Optional; input) CHARACTER*(*). A message string to precede the traceback output. It is recommended that the string be no more than 80 characters (one line) since that length appears better on output. However, this limit is not a restriction and it is not enforced. The string is output exactly as specified; no formatting or interpretation is done.

If this argument is omitted, no header message string is produced.

user_exit_code
(Optional; input) INTEGER(4). An exit code. Two values are predefined:

• A value of -1 causes the run-time system to return execution to the caller after producing traceback.
• A value of zero (the default) causes the application to abort execution.

Any other specified value causes the application to abort execution and return the specified value to the operating system.

status
(Optional; input) INTEGER(4). A status value. If specified, the run-time system returns the status value to the caller indicating that the traceback process was successful. The default is not to return status.

Note that a returned status value is only an indication that the "attempt" to trace the call stack was completed successfully, not that it produced a useful result.

You can include the file iosdef.for in your program to obtain symbolic definitions for the possible return values. A return value of FOR$IOS_SUCCESS (0) indicates success.

eptr
(Optional; input) Cray pointer. It is required if calling from a user-specified exception filter. If omitted, the default in null.

To trace the stack after an exception has occurred, the runtime support needs access to the exception information supplied to the filter by the operating system.

The eptr argument is a pointer to T_EXCEPTION_POINTERS, returned by the Win32 API GetExceptionInformation( ), which is usually passed to a C try/except filter function. This argument must be null if you are not passing a valid pointer to T_EXCEPTION_POINTERS. For more information, see Obtaining Traceback Information with TRACEBACKQQ in the Programmer's Guide.

The TRACEBACKQQ routine provides a standard way for an application to initiate a stack trace. It can be used to report application detected errors, debugging, and so forth. It uses the stack trace support in the Visual Fortran run-time library, and produces the same output that the run-time library produces for unhandled errors and exceptions.

The error message string normally included by the run-time system is replaced with the user-supplied message text, or omitted if no string is specified. Traceback output is directed to the target destination appropriate for the application type, just as it is when traceback is initiated internally by the run-time system.

Compatibility

CONSOLE STANDARD GRAPHICS QUICKWIN GRAPHICS WINDOWS DLL LIB

See Also: GETEXCEPTIONPTRSQQ, Obtaining Traceback Information with TRACEBACKQQ, Using Traceback Information, Run-Time Message Display and Format

Examples

Consider the following:

  CALL TRACEBACKQQ( )

This example generates a traceback report with no leading header message, from wherever the call site is, and aborts execution.

The following is another example:

  CALL TRACEBACKQQ("My application message string")

This example generates a traceback report with the user-supplied string as the header, and aborts execution.

The following is another example:

  CALL TRACEBACKQQ(STRING="Bad value for TEMP",USER_EXIT_CODE=123)

This example generates a traceback report with the user-supplied string as the header, and aborts execution, returning a status code of 123 to the operating system.

The following is another example:

  ...
  INTEGER(4) RTN_STS
  INCLUDE 'IOSDEF.FOR'
  ...
  CALL TRACEBACKQQ(USER_EXIT_CODE=-1,STATUS=RTN_STS)
  IF (RTN_STS .EQ. FOR$IOS_SUCCESS) THEN
    PRINT *,'TRACEBACK WAS SUCCESSFUL'
  END IF
  ...

This example generates a traceback report with no header string, and returns to the caller to continue execution of the application. If the traceback process succeeds, a status will be returned in variable RTN_STS.

For more examples, including one showing a Cray pointer, see Obtaining Traceback Information with TRACEBACKQQ in the Programmer's Guide.