DosUnwindException

Description

Calls and removes exception handlers from a thread's chain of exception handlers.

Syntax

#define INCL_DOSEXCEPTIONS
#include <os2.h>

PEXCEPTIONREGISTRATIONRECORD    phandler;   /*  A pointer to the exception registration record that describes the exception handler to be unregistered. */
PVOID                           pTargetIP;  /*  A pointer to where DosUnwindException branches after calling all applicable handlers. */
PEXCEPTIONREPORTRECORD          pERepRec;   /*  An optional pointer to an exception record. */
APIRET                          ulrc;       /*  Return Code. */

ulrc = DosUnwindException(phandler, pTargetIP, pERepRec);

Parameters

phandler (PEXCEPTIONREGISTRATIONRECORD) - input

A pointer to the exception registration record that describes the exception handler to be unregistered.

This parameter can have one of the following values:

Address        A pointer to the exception registration record where the unwind operation should stop. 0
0 UNWIND_ALL     An exit unwind operation is performed. This removes all exception handlers from the thread, and ends the thread. -1
-1 END_OF_CHAIN   All exception handlers for the thread are unwound. 

pTargetIP (PVOID) - input

A pointer to where DosUnwindException branches after calling all applicable handlers.

pERepRec (PEXCEPTIONREPORTRECORD) - input

An optional pointer to an exception record.

Set this field to zero if it is not used.

Return Code

ulrc (APIRET) - returns

DosUnwindException returns one of the following values:

• 0 NO_ERROR
• 1 ERROR_INVALID_FUNCTION

Remarks

Note: Do not make Presentation Manager calls from exception handlers.

DosUnwindException "unwinds" (calls and removes) exception handlers from a thread's chain of registered exception handlers. It can unwind up to but not including a specified exception handler, or it can unwind all the exception handlers.

Each exception handler in the linked list from the Thread Information Block (TIB) is called with the unwind bit in the Exception Report Record structure set, indicating an unwind operation. If the call to the exception handler returns, the Exception Registration Record is removed from the linked list, and the next exception handler is processed.

Example Code

This example unwinds all handlers. It does not resolve the exception and causes a SYSTEM ERROR pop-up for the exception to be displayed.

#define INCL_DOSPROCESS       /* DOS process values (for DosSleep) */
#define INCL_DOSEXCEPTIONS    /* DOS exception values */
#define INCL_ERRORS           /* DOS error values     */
#include <os2.h>
#include <stdio.h>

ULONG _System MyTermHandler( PEXCEPTIONREPORTRECORD       p1,
                             PEXCEPTIONREGISTRATIONRECORD p2,
                             PCONTEXTRECORD               p3,
                             PVOID                        pv );

int main (VOID)
{
  EXCEPTIONREGISTRATIONRECORD RegRec  = {0};     /* Exception Registration Record */
  APIRET      rc      = NO_ERROR;   /* Return code                   */

  /* Add MyTermHandler to this thread's chain of exception handlers */

  RegRec.ExceptionHandler = (ERR)MyTermHandler;
  rc = DosSetExceptionHandler( &RegRec );
  if (rc != NO_ERROR) {
     printf("DosSetExceptionHandler error: return code = %u\n",rc);
     return 1;
  }

  printf("Terminate this program using Ctrl-C or Ctrl-Break.\n");
  printf("You will get a System Error popup for the exception.\n");

  rc = DosSleep(60000L);   /* Give user plenty of time to comply... */

  rc = DosUnsetExceptionHandler( &RegRec );
  if (rc != NO_ERROR) {
     printf("DosUnsetExceptionHandler error: return code = %u\n",rc);
     return 1;
  }
  return NO_ERROR;
}
/***************************************************************************/
ULONG _System MyTermHandler( PEXCEPTIONREPORTRECORD       p1,
                             PEXCEPTIONREGISTRATIONRECORD p2,
                             PCONTEXTRECORD               p3,
                             PVOID                        pv )
{
  APIRET  rc = NO_ERROR;

  printf("*** MyTermHandler entered: ExceptionNum = %x\n",p1->ExceptionNum);

  rc = DosUnsetExceptionHandler( p2 );  /* Stop recursive entry to handler */
  rc = DosUnwindException( p2,          /* Exception Registration Record */
                           (PVOID) 0,   /* BAD ADDRESS!!! */
                           p1);         /* Exception Report Record */
  if (rc != NO_ERROR) {
     printf("DosUnwindException error:  return code = %u\n", rc);
  }

  return XCPT_CONTINUE_SEARCH;
}

Related Functions

• DosAcknowledgeSignalException
• DosEnterMustComplete
• DosExitMustComplete
• DosRaiseException
• DosSendSignalException
• DosSetExceptionHandler
• DosSetSignalExceptionFocus
• DosUnsetExceptionHandler