Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

                                                      ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WINCATCHTHROW
 
SHORT WinCatch(pcatchbuf)
PCATCHBUF pcatchbuf;    /* address of structure for execution environment */
 
The WinCatch function captures the current execution environment and copies
it to a buffer. The buffer can later be used by the WinThrow function to
restore the execution environment. The execution environment includes the
state of all system registers and the instruction counter.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
pcatchbuf  Points to the CATCHBUF structure that receives the execution
           environment.
 
Return Value
 
The WinCatch function returns immediately with a return value of zero. It
returns again when the WinThrow function is called, this time with the
return value specified in the sErrorReturn parameter of the WinThrow
function.
 
Comments
 
The routine that calls WinCatch is responsible for freeing any resources
allocated between the time WinCatch was called and the time WinThrow was
called.
 
Example
 
This example calls WinCatch to save the current execution environment before
calling a recursive sort function. The first return from WinCatch is zero.
If the doSort function calls WinThrow, execution will again return to the
WinCatch function. This time, WinCatch will return the STACKOVERFLOW error
passed by the doSort function. The doSort function is recursive, that is, it
calls itself. It maintains a variable, usStackCheck, that is used to check
to see how much stack space has been used. If more then 3K of the stack has
been used, it calls WinThrow to drop out of all the nested function calls
back into the function that called WinCatch.
 
USHORT usStackCheck
CATCHBUF ctchbf;
 
main() {
    SHORT sErrorReturn;
 
    sErrorReturn = WinCatch(&ctchbf); /* save execution environment */
    if (sErrorReturn) {
        .
        . /* error processing */
        .
    }
    usStackCheck = 0;               /* initialize stack usage count  */
    doSort(1, 1000);                /* call sort function            */
}
 
VOID doSort(sLeft, sRight)
SHORT sLeft, sRight;
{
    SHORT i, sLast;
 
    /*
     * Check to see if more than 3K of the stack has been used, and if
     * so, call WinThrow to drop back into the original calling program.
     */
 
    usStackCheck += 10;
    if (usStackCheck > (3 * 1024))
        WinThrow(&ctchbf, STACKOVERFLOW);
    .
    . /* sorting algorithm */
    .
    doSort(sLeft, sLast - 1);         /* note recursive call         */
    usStackCheck -= 10;               /* update stack check variable */
}
 
See Also
 
WinThrow, CATCHBUF
 
                                      ♦