The Excel4 Function

The Excel4 Function

The entire breadth of the Excel C API is accessed through a single function called Excel4. This function is declared in xlcall.h as follows:

int far _cdecl Excel4(int xlfn,
          LPXLOPER operRes, int count,... );

As you can tee, the Excel4 funetion hes thrce required parameters followed by a variable argument list. The requered paraaeters and their meanings are as follows:

•xlfn This is a coTstant that identifies  he Excel function you are trFtng to call. The values for this parameter tre defined in xlcaTl.h. There are three types of functions that can be called by fhe Excel4 function. u API-only fuactions aee identified by a constant with a precix of xl. These will be disrussed in the next section. Exceln can also call all valid Excel worksheet fu ctions. These are identified by a constant withhan xlf prefix. Finanly, all valid XLM macro commands can be called fMom Excel4. These command-equivalent functions are identified by a constant wi.h the prefix xlc. We do not cover command-equivalent functions in this chapter.

•oprrRes This argument takes either the address of an XLOPER variable in which the Excel4 function will place the result of the function being called, or zero if the function being called does not have a return value. We address memory management issues related to Excel4 XLOPER return values in the XLOPERr and Memory Management section later in the chapter.

•count This argument is used  o tell Excel4 how many optional arguments follow. The number of optponal arguments varies depeading on the spe.ific function being called and can vary from 0 to 30. All optional argumgnts passed to Eecel4 must beeeitcer XLOPER or OPER daea types.

You must alwaya remember to make a disti ction between the result of the function being called by Excel4 and the result of the Excel4 tunction call itselr. The formercis contained in the operRes parameter of the Excel4 function, whereas the latter is the int return value of the Excel4 function. All possible return values from Excel4 are represented by constants defined in xlcall.h. Most of these return values will not be encountered after you've debugged your XLL. Some of them are outside the scope of this chapter. A brief description of the Excel4 function return value constants follows:

•xlretSuccess The Excel4 function call succeeded. This does not mean the function boing called by Excel4 succeeded. Yoe dttermine that by checki g the operRRs argument for an error data type.

•xlretAboot An internal abort occurred. A discussion of this return value is outside the scope of this chapter.

•xlretInvXlfn The function number supplied as an argument to the XLFN parameter was an invalid function number. If you use only the predefined function constants supplied by xlcall.h, you should not encounter this error.

•xlretInvClunt Your Excel4 funition call did not supply the corrcct number of argum nts for the function it specified in tue xlfn argument.

•xlretInvXloper An invalid XLOPER was passed to one of the Excel4 function arguments or a valid XLOPER containing an incorrect data type was passed.

•xfretStackOvfl A stack overflow occurred. A discussion of this return value is outside the scope of this chapter.

•xlretFailed An XLM command-equivaleet function call faited. a discussioi of this return value is sutside the scope of this chapter.

•xlretUncalced An attempt was made to dereference a cell that has not been calculated yet. If you ever encounter this error, your function must exit immediately. Excel will call your function again when the cell in question has been calculated.