Excel4/Excel12

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Call an internal Microsoft Office Excel worksheet function, macro sheet function or command, or XLL-only special function or command, from within a DLL/XLL or code resource.

All recent versions of Excel support Excel4. Only Excel 2007 and later versions support Excel12.

These functions can only be called when Excel has passed control to the DLL/XLL. They can also be called when Excel has passed control indirectly via a call to Visual Basic for Applications (VBA). They cannot be called at any other time. For example, they cannot be called during calls to DllMain or other times when the operating system has called the DLL, or from a thread created by the DLL.

Excel4v and Excel12v accept their arguments as an array, whereas these functions accept their arguments as a variable length list on the stack. In all other respects, Excel4 behaves the same as Excel4v, and Excel12 behaves the same as Excel12v.

int Excel4(int iFunction, LPXLOPER pxRes, int iCount, LPXLOPER argument1, ...);
int Excel12(int iFunction, LPXLOPER12 pxRes, int iCount, LPXLOPER12 argument1, ...);

Parameters

iFunction (int)

A number indicating the command, function, or special function you want to call. For a list of valid iFunction values, see the following "Remarks" section.

pxRes (LPXLOPER or LPXLOPER12)

A pointer to an XLOPER (with Excel4) or an XLOPER12 (with Excel12) that will hold the result of the evaluated function.

iCount (int)

The number of subsequent arguments that will be passed to the function. In versions of Excel up to 2003, this can be any number from 0 to 30. In Excel 2007, this can be any number from 0 to 255.

argument1, ... (LPXLOPER or LPXLOPER12)

The optional arguments to the function. All arguments must be pointers to XLOPERs or XLOPER12s.

Property Value/Return Value

Returns one of the following (int).

Value	Return code	Description
0	xlretSuccess	The function was called successfully. This does not mean that the function did not return an Excel error value; to find that out, you must look at the type and value of pxRes resulting.
1	xlretAbort	The command or function was terminated abnormally (internal abort). This can occur if an XLM macro sheet closes itself by calling CLOSE, or if Excel is out of memory. If you receive this error, you must exit immediately. The DLL is only permitted to call xlFree before exiting. All other calls to the C API are not permitted. The user can save any work interactively using the Save command on the File menu.
2	xlretInvXlfn	An invalid function number was supplied. If you are using constants from XLCALL.H, this should not occur unless you are calling something that is not supported in the version of Excel you are running.
4	xlretInvCount	An invalid number of arguments was entered. In versions up to Excel 2003, the maximum number of arguments any function can take is 30. In Excel 2007, the maximum number is 255. Some require a fixed or minimum number of arguments.
8	xlretInvXloper	An invalid XLOPER or XLOPER12 was passed to the function, or an argument of the wrong type was used.
16	xlretStackOvfl	(Windows only) A stack overflow occurred. Use xlStack to monitor the amount of room left on the stack. Avoid allocating very large local (automatic) arrays and structures on the stack where possible; make them static. (Note that a stack overflow might occur without being detected.)
32	xlretFailed	A command-equivalent function failed. This is equivalent to a macro command displaying the macro error alert dialog box.
64	xlretUncalced	An attempt was made to dereference a cell that has not been calculated yet, because it is scheduled to be recalculated after the current cell. In this case, the DLL should return control to Excel immediately. The DLL is only permitted to call xlFree before exiting. All other calls to the C API are not permitted. For more information about which functions can and cannot access the values of unrecalculated cells, see Excel Commands, Functions, and States.
128	xlretNotThreadSafe	Only returned when running Excel 2007 and only within XLL worksheet functions declared as thread safe. An attempt was made to call a function that is not, or might not be, thread safe during a multithreaded recalculation of the workbook.

Remarks

Valid iFunction values

Valid iFunction values are any of the xlf... or xlc... constants defined in XLCALL.H or any of the following special functions.

xlAbort	xlEnableXLMsgs	xlGetInst	xlSheetNm
xlCoerce	xlFree	xlGetName	xlStack
xlDefineBinaryName	xlGetBinaryName	xlSet	xlUDF
xlDisableXLMsgs	xlGetHwnd	xlSheetId

Different Types of Functions

Excel4 and Excel12 distinguish between three classes of functions. The functions are classified according to the three states in which Excel might be calling the DLL.

Class 1 applies when the DLL is called from a worksheet as a result of recalculation.
Class 2 applies when the DLL is called from within a function macro or from a worksheet where it was registered with a number sign (#) in the type text.
Class 3 applies when a DLL is called from an object, macro, menu, toolbar, shortcut key, ExecuteExcel4Macro, or the Tools/Macro/Run command. For more information, see Excel Commands, Functions, and States.

The following table shows what functions are valid in each class.

Class 1	Class 2	Class 3
Any worksheet function Any XLL-only xl... function except xlSet. xlfCaller	Any worksheet function Any xl... function except xlSet. Macro sheet functions, including xlfCaller, that return a value but perform no action that affects the workspace or any open workbook.	Any function, including xlSet and command-equivalent functions.

Any worksheet function

Any XLL-only xl... function except xlSet.

xlfCaller

Any worksheet function

Any xl... function except xlSet.

Macro sheet functions, including xlfCaller, that return a value but perform no action that affects the workspace or any open workbook.

Any function, including xlSet and command-equivalent functions.

Displaying the Dialog Box for a Command-Equivalent Function

If a command-equivalent function has an associated dialog box, you can set the xlPrompt bit in iFunction. This means that Excel displays the appropriate dialog box before carrying out the command.

Writing International DLLs

If you set the xlIntl bit in iFunction, the function or command is carried out as if it were being called from an International Macro Sheet. This means that the command behaves as it would on the U.S. version of Excel, even if it is running on an international (localized) version.

xlretUncalced or xlretAbort

After receiving one of these return values, your DLL must clean up and return control to Excel immediately. Callbacks into Excel via the C API, except xlFree, are disabled after receiving one of these return values.

Example

This example uses the Excel12 function to select the cell from which it was called.

\SAMPLES\EXAMPLE\EXAMPLE.C.

Note
This function calls a command macro (xlcSelect) and therefore only works if called from an XLM macro sheet.

short WINAPI Excel12Example(void)
{
   XLOPER12 xRes;

   Excel12(xlfCaller, &xRes, 0);
   Excel12(xlcSelect, 0, 1, (LPXLOPER12)&xRes);
   Excel12(xlFree, 0, 1, (LPXLOPER12)&xRes);

   return 1;
}