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

Commonly Used C API Functions

The functions listed below can only be called from within an XLL using the Excel4 function. They are not available from within Excel. This is not a complete list of these functions, only those that apply most commonly to custom worksheet function projects.

xlFree

The xlFree function is used to tell Excel you are finished with the contents of an XLOPER variable Excel has allocated the memory for and that Excel is now free to reclaim that memory. The xlFree function takes one or more XLOPER variables as parameters to be freed and does not return a value to the operRes parameter of the Excel4 function. We discuss XLOPER memory management in the next section, but for now, here's the basic syntax of an xlFree function call:

XLOPER xlToBeFreed;
// Do something here that causes Excel to allocate
// the xlToBeFreed variable.
Excel4(xlFree, 0, 1, xlToBeFreed);

xlCoerce

The xlCoerce function is used to convert XLOPER structs from one data type to another. For example, you can make a custom worksheet function more robust by using xlCoerce to explicitly convert to a numeric value whatever is passed to an XLOPER parameter that expects a numeric value. The need for this would arise if the user entered something similar to the following for a function whose parameter expected a numeric data type:

=MYFUNC("100")

The default behavior of xlCoerce is to convert a cell reference to any nonreference type, in effect looking up the value of a cell that an XLOPER points to. The syntax of an xlCoerce call looks like the following:

XLOPER xlResult, xlType;
xlType.xltype = xltypeInt;
xlType.val.w = xltypeNum;
Excel4(xlCoerce, &xlResult, 2, pxlInput, &xlType);

The xlCoerce function takes two arguments:

pxlInput
A pointer to an XLOPER (LPXLOPER) that contains the value or reference to be converted.

xlType
A pointer to an XLOPER of type xltypeInt whose val.w member contains a bit mask of types you are willing to accept. This argument is optional. If it is not provided, xlCoerce will convert the pxlInput reference argument into the closest possible data type associated with the value in the referenced cell.

xlGetName

The xlGetName function returns the full path name and filename of your XLL. As you will see in the Registering and Unregistering Custom Worksheet Functions section, this information is required to register and unregister the custom worksheet functions in an XLL.