Declare and describe an add-in function
[C++]
IMPLEMENT_XLLFN2(
LABEL nmEntryPoint,
const char* pszArgTemplate,
const char* pszName,
const char* pszCategory,
const char* pszArgNames,
const char* pszHelpText,
const char* pszArgHelpText,
const char* pszExt,
int usAvailability
);
Name of the 'C' function. Note that the function name is not in quotes - it is a label, not a string. Most of the other arguments to the macro are strings, so they can be either string literals (such as "RB") or references to strings (e.g. CMyXllApp::m_pszDefCategory).
The type text of the function, containing the data type of the return value and data types of the arguments. The first letter of the type text specifies the return value. Subsequent letters, starting with the second, specify the data types of the arguments, in order. For a list of data types and the letters used to represent them see Data types. Thus if, for example, if the string is "AB", it represents a function that returns a Boolean result and takes one double argument. See the table in Data types for a full list of the data types supported.
In addition, the string can be terminated by one or both of the characters '#' and '!'. The hash symbol ('#') indicates that resolution of the function's arguments is delayed. Experienced SDK programmers will appreciate the occasional utility of this option. See the Excel 97 Developer's Kit (Microsoft Press) for more information.
The '!' suffix makes the function volatile. Volatile functions are resolved every time any part of a worksheet is recalculated, or when the F9 function key is pressed or when Application.Calculate() is invoked. This option is useful when the results of functions are determined by outside factors (such as the current time, or data held in a database) in addition to the value of their arguments.
Name of function as exported to Excel. This is the function's name as you will use it in Excel - it does not need to be the same as the 'C' name of the function.
The category under which the function will appear in the Excel Function Wizard.
This argument is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Category for more information.
The names of the function's arguments, separated by commas. For example, "Arg1,Arg2".
See pszExt below for information on localizing the argument name.
The description of the function which will appear in the Excel Function Wizard.
This help text is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Help text for more information.
The descriptions of the function's arguments which will appear in the Excel Function Wizard. Each description should be separated from the next by a null character ("\0"). An extra null character should terminate the string. Thus a function that concatenates its two arguments might have argument help text as follows: "Left-hand string\0Right-hand string\0\0".
Each of the arguments' help texts is transformed with XllTranslateString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Help text for more information.
The extended properties used by the add-in function's arguments. These can include, for instance, the fact that an argument is a vector or matrix of a specific type, it's bounds, and various other flag settings. These extended properties are read and written by the XLL+ Function Wizard, and are used to generate code to read and translate the arguments. They are ignored by the run-time library, with the exception of argument resource IDs, as described below.
If the extension for an argument contains a resource ID, as entered into the ResID column of the XLL+ Function Wizard, then it is transformed with XllLoadString before it is sent to Excel. Any numeric string resource IDs will be translated to strings from the resource file, if available. See International : Argument names for more information.
Flag indicating from where the function may be invoked. 1 indicates that the function is available only from Excel worksheets; 2 that it is available only from Excel macro sheets; 3 that it is available in both. No other values are acceptable.
The IMPLEMENT_XLLFN2 macro manages the registration of a 'C' function as an Excel add-in function.
It is supported by the XLL Plus Function Wizard, which can be used to maintain the code for both the macro and the function definition. Note that several of the string arguments to the macro accept
resource ID strings
which are loaded from the application resource file at run-time. The macro defines a static instance of a 'C' structure (XLLFN) which contains the details that define the add-in function.
It also defines another 'C' structure (XLLFN_INIT) whose constructor function will add the address of the XLLFN
to a global chain intitialised at DLL load time, before any other methods or call-back functions are invoked. When the function AddStaticFns() is called during the DLL's InitInstance() method,
the functions defined in the global chain are added to the CXllApp object's function list.
During the XllLoad operation invoked by Excel when the XLL is opened,
this list of functions is registered with Excel using the SDK xlfRegister entry-point.
Header: xllplus.h