xlAbort

This function yields the processor to other tasks in the system and checks whether the user has pressed ESC to cancel a macro.

Returns TRUE (xltypeBool) if the user has pressed ESC.

Syntax

Excel4(xlAbort, LPXLOPER pxRes, 1, LPXLOPER pxRetain)

pxRetain (xltypeBool)

If FALSE, this function will also clear any pending abort (if you want to continue despite the user abort). This argument is optional; if omitted, this function will check for a user abort without clearing it.

Remarks

Frequent Calls May Be Needed

Functions that will likely take a long time must call this function frequently to yield the processor to other tasks in the system.

Avoid Sensitive Language

Microsoft recommends against using the term "Abort" in your user interface. Use "Cancel," "Halt," or "Stop."

Example

The following code repetitively moves the active cell on a sheet until one minute has elapsed or until you press ESC. It calls the function xlAbort occasionally. This yields the processor, allowing cooperative multitasking.

\SAMPLES\FRAMEWRK\GENERIC.C

int WINAPI fDance(void)
{
    DWORD dtickStart;
    XLOPER xAbort, xConfirm;
    int boolSheet;
    int col=0;
    char rgch[32];

    // Check what kind of sheet is active. If it is
    // a worksheet or XLM macro sheet, this function will
    // move the selection in a loop to show activity.
    // In any case, it will update the status bar
    // with a countdown.

    // Call xlSheetId; if that fails the current sheet
    // is not a macro sheet or worksheet. Next, get the
    // time at which to start. Then start a while loop
    // that will run for one minute. During the while loop,
    // check if the user has pressed ESC. If true, confirm
    // the abort. If the abort is confirmed, clear the message
    // bar and return; if the abort is not confirmed, clear
    // the abort state and continue. After checking for an
    // abort, move the active cell if on a worksheet or macro.
    // Then update the status bar with the time remaining.

    // This block uses TempActiveCell(), which creates a
    // temporary XLOPER. The XLOPER contains a reference to
    // a single cell on the active sheet.
    // This function is part of the framework library.

    boolSheet = (Excel4(xlSheetId, 0, 0) == xlretSuccess);

    dtickStart = GetTickCount();

    while (GetTickCount() < dtickStart + 60000L)
    {
        Excel(xlAbort, &xAbort, 0);
        if (xAbort.val.bool)
        {
            Excel(xlcAlert, &xConfirm, 2,
                TempStr(" Are you sure you want to cancel?"),
                TempNum(1));

            if (xConfirm.val.bool)
            {
                Excel(xlcMessage, 0, 1, TempBool(0));
                return 1;
            }
            else
            {
                Excel(xlAbort, 0, 1, TempBool(0));
            }
        }

        if (boolSheet)     
        {
            Excel(xlcSelect, 0, 1, TempActiveCell(0,(BYTE)col));
            col = (col + 1) & 3;
        }
        wsprintf(rgch," 0:%lu",
            (60000 + dtickStart - GetTickCount()) / 1000L);
        Excel(xlcMessage, 0, 2, TempBool(1), TempStr(rgch));
    }
    Excel(xlcMessage, 0, 1, TempBool(0));

    return 1;
}