TRACEBACKQQ

Module

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: 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	(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.

Example

In the most simple case, you can generate a stack trace by coding the call to TRACEBACKQQ with no arguments:

CALL TRACEBACKQQ()

This call causes the run-time library to generate a traceback report with no leading header message, from wherever the call site is, and terminate execution.

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.

You can specify arguments that generate a stack trace with the user-supplied string as the header and instead of terminating execution, return control to the caller to continue execution of the application. For example:

CALL TRACEBACKQQ(STRING="Done with pass 1",USER_EXIT_CODE=-1)

By specifying a user exit code of -1, control returns to the calling program. Specifying a user exit code with a positive value requests that specified value be returned to the operating system. The default value is 0, which causes the application to abort execution.

Windows* OS Example:

The following example demonstrates the use of the EPTR argument when calling from a user-defined exception filter function. The premise of the example is a Fortran DLL containing entry points protected by a C try/except construct, such as:

__declspec(dllexport) void FPE_TEST_WRAPPER ()
{
__try {
     /*
     **  call the Fortran code...
     */
     FPE_TEST() ;
     }
__except ( CHECK_EXCEPTION_INFO ( GetExceptionInformation() ) )
     {
     /*
     **  noncontinuable exception handling here, if any.
     */
     }

The C function shown above is guarding against a floating-point divide-by-zero exception. This function calls the user-supplied FPE_TEST (not shown). The Fortran function CHECK_EXCEPTION_INFO shown below (called in the __except filter expression above) can use TRACEBACKQQ to get a stack trace as follows:

  INTEGER*4 FUNCTION CHECK_EXCEPTION_INFO ( ExceptionInfo )
  !DIR$ ATTRIBUTES DLLEXPORT::CHECK_EXCEPTION_INFO
  USE IFWINTY
  !DIR$ ATTRIBUTES REFERENCE :: ExceptionInfo
  TYPE(T_EXCEPTION_POINTERS) ExceptionInfo
  TYPE(T_EXCEPTION_RECORD) erecptr
  TYPE(T_CONTEXT) ctxptr
  POINTER(eptr,erecptr)
  POINTER(ctxp,ctxptr)
  INTEGER(4) EXIT_CODE,STS
  CHARACTER(LEN=70) MYSTR
! Init the arguments to TRACEBACKQQ appropriately for your needs...
  EXIT_CODE=-1
  eptr = ExceptionInfo.ExceptionRecord
  ctxp = ExceptionInfo.ContextRecord
  IF ( erecptr.ExceptionCode .EQ. STATUS_FLOAT_DIVIDE_BY_ZERO ) THEN
         PRINT *, 'Saw floating divide by zero.'
         PRINT '(1x,a,z8.8)', 'ContextRecord.FloatSave.StatusWord = ', &
                 ctxptr.FloatSave.StatusWord
         MYSTR = "FLTDIV EXCEPTION IN MY APPLICATION"
         CALL TRACEBACKQQ(MYSTR,EXIT_CODE,STS, %LOC(ExceptionInfo))
  END IF
  .
  .
  .
  CHECK_EXCEPTION_INFO = 1
  END

To return a pointer to C run-time exception information pointers within a user-defined handler that was established with SIGNALQQ (or directly with the C signal function), you can call the GETEXCEPTIONPTRSQQ routine.