TRACEBACKQQ

Module

USE IFCORE

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

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* 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.