Professional Excel Development [Electronic resources] : The Definitive Guide to Developing Applications Using Microsoft® Excel and VBA® نسخه متنی

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 see, the Excel4 function has three required parameters followed by a variable argument list. The required parameters and their meanings are as follows:

xlfn
This is a constant that identifies the Excel function you are trying to call. The values for this parameter are defined in xlcall.h. There are three types of functions that can be called by the Excel4 function. C API-only functions are identified by a constant with a prefix of xl. These will be discussed in the next section. Excel4 can also call all valid Excel worksheet functions. These are identified by a constant with an xlf prefix. Finally, all valid XLM macro commands can be called from Excel4. These command-equivalent functions are identified by a constant with the prefix xlc. We do not cover command-equivalent functions in this chapter.

operRes
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 XLOPERs and Memory Management section later in the chapter.

count
This argument is used to tell Excel4 how many optional arguments follow. The number of optional arguments varies depending on the specific function being called and can vary from 0 to 30. All optional arguments passed to Excel4 must be either XLOPER or OPER data types.

You must always remember to make a distinction between the result of the function being called by Excel4 and the result of the Excel4 function call itself. The former is 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 being called by Excel4 succeeded. You determine that by checking the operRes argument for an error data type.

xlretAbort
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.

xlretInvCount
Your Excel4 function call did not supply the correct number of arguments for the function it specified in the 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.

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

xlretFailed
An XLM command-equivalent function call failed. A discussion of this return value is outside 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.