Download (direct link):
#define NUM_COMMANDS 1
char *CommandExports[NUM_COMMANDS] =
// Name in code Name that Excel uses
int stdcall xlAutoOpen(void)
for(int i = 0 ; i < NUM_COMMANDS; i++) register_cmdID[i] = register_command(
A bug prevents the function and command IDs from being used for their intended purpose of unregistering functions. Therefore the above code can be replaced with:
int stdcall xlAutoOpen(void)
for(int i = 0 ; i < NUM_COMMANDS; i++)
register_command(CommandExports [i], CommandExports[i]);
8.6.1 Accessing XLL commands
There are a number of ways to access commands that have been exported and registered as described above.
1. Via custom menus. (See section 8.11 Working with Excel menus, page 249.)
2. Via custom toolbars. (See section 8.12 Working with toolbars, page 266.)
3. Via a Custom Button on a toolbar. (See below.)
4. Directly via the Macro dialog. (See below.)
Accessing Excel Functionality Using the C API
5. Via a VB module. (See below.)
6. Via one of the C API event traps. (See section 8.14 Trapping events, page 277.)
In addition, there are a number of C API functions that take a command reference (the name of the command as registered with Excel), for example xlfCancelKey.
To assign a command (or macro as Excel often refers to commands) to a custom button, you need to drag a new custom button onto the desired toolbar from the Jools/ Customize.. ./Commands dialog under the Macro category. Still with the customisation dialog showing, right-clicking on the new button shows the properties menu which enables you to specify the appearance of the button and assign the macro (command) to it.
To access the command directly from the Macro dialog, you need simply to type the command’s name as registered. The command will not be listed in the list box as Excel treats XLL commands as if they had been defined on a hidden macro sheet, and therefore are themselves hidden.
One limitation of current versions of Excel is the inability to assign XLL commands directly to control objects on a worksheet. You can, however, access an XLL command in any VB module, subject to scope, using the Application.Run ("CmdName") VB statement. If you wish to associate an XLL command with worksheet control, you simply place this statement in the control’s VB code.
8.6.2 Breaking execution of an XLL command
The C API provides two functions xlAbort and xlfCancelKey. The first checks for user breaks (the Esc key being pressed in Windows) and is covered in section 8.7.7 Yielding processor time and checking for user breaks: xlAbort, on page 206.
The second disables/enables interruption of the currently executing task. If enabled, xlfCancelKey also permits the specification of another command to be run on interruption. This second command is intended to be used to do any necessary cleaning up before control is returned to Excel.
The function takes 2 arguments: (1) a Boolean specifying whether interruption is permitted (true) or not (false), and (2) a command name registered with Excel as a string. If the function is called with the first argument set to true, then the command will be terminated by the user pressing the Esc key. This is the default state when Excel calls a command, so it is not necessary to call this function except, to explicitly disable or re-enable user breaks.
8.7 FUNCTIONS DEFINED FOR THE C API ONLY
8.7.1 Freeing Excel-allocated memory within the DLL: xlFree
Overview: Frees memory allocated by Excel during a call to Excel4()
or Excel4v() for the return xloper value. This is only necessary where the returned xloper type involves the allocation of memory by Excel. There are only 3 xloper types that can have memory associated with them in this way, xltypeStr, xltypeRef and xltypeMulti, so it is only
Excel Add-in Development in C/C++
necessary to call xlFree if the return type is or could be one
of these. It is always safe to call this function even if the
xloper is not one of these types. It is not safe to call this function on an xloper that was passed in to the DLL as a function argument from Excel, or that has been initialised by the DLL with either static or dynamic memory.
(See Chapter 7 Memory management on page 161 for an explanation of the basic concepts and more examples of the use of xlFree.)
Enumeration value: 16384 (x4000)
Callable from: Commands, worksheet and macro sheet functions.
Return type: Void.
Arguments: Takes from 1 to 30 arguments, each of them the address of an
xloper that was passed to Excel in a call to Excel4() or Excel4v() to contain the return value.
Warning: Where the type is xltypeMulti you do not need to (and must not) call
xlFree for any of the elements, whatever their types. Doing this will confuse and
Note: Where an Excel-allocated xloper is being returned (via a pointer) from a DLL function, it is necessary to set the xlbitXLFree bit in the xltype field to alert Excel to the need to free the memory.