Catch

2.x

The Catch function captures the current execution environment and copies it to a buffer. The Throw function can use this buffer later to restore the execution environment. The execution environment includes the state of all system registers and the instruction counter.

Parameters

lpCatchBuf

Points to a memory buffer large enough to contain a CATCHBUF array.

Return Value

The Catch function returns immediately with a return value of zero. When the Throw function is called, it returns again, this time with the return value specified in the nErrorReturn parameter of the Throw function.

Comments

The Catch function is similar to the C run-time function setjmp.

Example

The following example calls the Catch function to save the current execution
environment before calling a recursive sort function. The first return value
from Catch is zero. If the doSort function calls the Throw function, execution will again return to the Catch function. This time, Catch will return the STACKOVERFLOW error passed by the doSort function. The doSort function is recursive—that is, it calls itself. It maintains a variable, wStackCheck, that is used to check to see how much stack space has been used. If more then 3K of the stack has been used, doSort calls Throw to drop out of all the nested function calls back into the function that called Catch.

#define STACKOVERFLOW 1

UINT uStackCheck;
CATCHBUF catchbuf;

{
    int iReturn;
    char szBuf[80];

    if ((iReturn = Catch((int FAR*) catchbuf)) != 0) {
        .
        . /* Error processing goes here. */
        .
    }


    else {
        uStackCheck = 0;       /* initializes stack-usage count */
        doSort(1, 100);        /* calls sorting function        */
    }
    break;
}

void doSort(int sLeft, int sRight)
{
    int sLast;

    /*
     * Determine whether more than 3K of the stack has been
     * used, and if so, call Throw to drop back into the
     * original calling application.
     *
     * The stack is incremented by the size of the two parameters,
     * the two local variables, and the return value (2 for a near
     * function call).
     */

    uStackCheck += (sizeof(int) * 4) + 2;

    if (uStackCheck > (3 * 1024))
        Throw((int FAR*) catchbuf, STACKOVERFLOW);
    .
    . /* A sorting algorithm goes here. */
    .

    doSort(sLeft, sLast - 1);   /* note recursive call          */
    uStackCheck -= 10;          /* updates stack-check variable */
}

See Also

Throw