Run-Time Subroutine: Provides traceback information. Uses the Intel® 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( ).
USE IFCORE
CALL TRACEBACKQQ ([string] [,user_exit_code] [,status] [,eptr])
string |
(Input; optional) 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 |
(Input; optional) INTEGER(4). An exit code. Two values are predefined:
Any other specified value causes the application to abort execution and return the specified value to the operating system. |
status |
(Input; optional) 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.forin your program to obtain symbolic definitions for the possible return values. A return value of FOR$IOS_SUCCESS (0) indicates success. |
eptr |
(Input; optional) Integer 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 a T_EXCEPTION_POINTERS structure, which is defined in ifcore.f90. This argument is optional and is usually omitted. On Windows systems, T_EXCEPTION_POINTERS is returned by the Windows* API GetExceptionInformation( ), which is usually passed to a C try/except filter function. |
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 Intel 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.
CONSOLE STANDARD GRAPHICS QUICKWIN GRAPHICS WINDOWS DLL LIB
The following example generates a traceback report with no leading header message, from wherever the call site is, and aborts execution:
USE IFCORE
CALL TRACEBACKQQ( )
The following example generates a traceback report with the user-supplied string as the header, and aborts execution:
USE IFCORE
CALL TRACEBACKQQ("My application message string")
The following 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:
USE IFCORE
CALL TRACEBACKQQ(STRING="Bad value for TEMP",USER_EXIT_CODE=123)
Consider the following:
...
USE IFCORE
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 an integer pointer, see Building Applications: Obtaining Traceback Information with TRACEBACKQQ.
Building Applications: Using Traceback Information
Building Applications: Run-Time Message Display and Format
Building Applications: Obtaining Traceback Information with TRACEBACKQQ