Excel4/Excel12

  • Статья

Область применения: Excel 2013 | Office 2013 | Visual Studio

Вызывает внутреннюю функцию листа Microsoft Excel, функцию или команду листа макросов или специальную функцию или команду только XLL из ресурса DLL/XLL или кода.

Все последние версии Excel поддерживают Excel4. Начиная с Excel 2007 поддерживается Excel12 .

Эти функции можно вызывать только в том случае, если Excel передал управление библиотеке DLL или XLL. Их также можно вызывать, если Excel передал управление косвенно через вызов Visual Basic для приложений (VBA). Они не могут быть вызваны в любое другое время. Например, они не могут вызываться во время вызовов функции DllMain или в других случаях, когда операционная система вызвала библиотеку DLL, или из потока, созданного библиотекой DLL.

Функции Excel4v и Excel12v принимают свои аргументы в виде массива, а функции Excel4 и Excel12 принимают свои аргументы в виде списка переменной длины в стеке. Во всех остальных отношениях Excel4 ведет себя так же, как Excel4v, а Excel12 — так же, как Excel12v.

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

Параметры

iFunction (int)

Число, указывающее команду, функцию или специальную функцию, которую требуется вызвать. Список допустимых значений iFunction см. в следующем разделе Примечания.

pxRes (LPXLOPER или LPXLOPER12)

Указатель на XLOPER (с Excel4) или XLOPER12 (с Excel12), который будет содержать результат вычисляемой функции.

iCount (int)

Число последующих аргументов, которые будут переданы функции. В версиях Excel до 2003 года это может быть любое число от 0 до 30. Начиная с Excel 2007, это может быть любое число от 0 до 255.

argument1, ... (LPXLOPER или LPXLOPER12)

Необязательные аргументы функции. Все аргументы должны быть указателями на значения XLOPER или XLOPER12 .

Возвращаемое значение

Возвращает одно из следующих значений integer (int).

Value (Значение) Код возврата Описание
0 xlretSuccess Функция была вызвана успешно. Это не означает, что функция не вернула значение ошибки Excel. Чтобы найти это, необходимо просмотреть тип и значение результирующего параметра pxRes .
1 xlretAbort Команда или функция была завершена аномально (внутреннее прерывание). Это может произойти, если лист макросов XLM закрывается путем вызова CLOSE или если excel не хватает памяти. Если Excel возвращает эту ошибку, вызывающая функция должна немедленно завершить работу. Библиотеке DLL разрешено вызывать xlFree только перед выходом. Все остальные вызовы API C запрещены. Пользователь может сохранить любую работу в интерактивном режиме с помощью команды Сохранить в меню Файл .
2 xlretInvXlfn Указан недопустимый номер функции. Если вы используете константы из файла заголовка Xlcall.h, это не должно происходить, если вы не вызываете что-то, что не поддерживается в версии Excel, которую вы используете.
4 xlretInvCount Введено недопустимое число аргументов. В версиях до Excel 2003 максимальное число аргументов, которые может принимать любая функция, составляет 30. Начиная с Excel 2007, максимальное число — 255. Для некоторых требуется фиксированное или минимальное количество аргументов.
8 xlretInvXloper В функцию был передан недопустимый XLOPER или XLOPER12 либо использовался аргумент неправильного типа.
16 xlretStackOvfl Произошло переполнение стека. Используйте xlStack для отслеживания объема пространства, остающегося в стеке. Избегайте выделения очень больших локальных (автоматических) массивов и структур в стеке, где это возможно; сделать их статическими. (Обратите внимание, что переполнение стека может произойти без обнаружения.)
32 xlretFailed Сбой функции, эквивалентной команде. Это эквивалентно команде макроса, отображающей диалоговое окно оповещения об ошибке макроса.
64 xlretUncalced Предпринята попытка разыменовать ячейку, которая еще не была рассчитана, так как ее планируется пересчитать после текущей ячейки. В этом случае библиотека DLL должна немедленно вернуть управление в Excel. Библиотеке DLL разрешено вызывать xlFree только перед выходом. Все остальные вызовы API C запрещены. Дополнительные сведения о том, какие функции могут и не могут получать доступ к значениям ячеек, которые не были пересчитаны, см. в разделе Команды, функции и состояния Excel.
128 xlretNotThreadSafe Предпринята попытка вызвать функцию, которая не является потокобезопасной или не может быть потокобезопасной во время многопоточного пересчета книги. Начиная с Excel 2007, это значение возвращается и только в функциях листа XLL объявляется потокобезопасной.
256 xlRetInvAsynchronousContext Недопустимый дескриптор асинхронной функции. Это значение используется только в Excel 2010.
512 xlRetNotClusterSafe Вызов не поддерживается в кластерах. Это значение используется только в Excel 2010.

Замечания

Допустимые значения iFunction

Допустимые значения iFunction — это любая из констант xlf... или xlc..., определенных в файле заголовка Xlcall.h, или любой из следующих специальных функций.

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

Различные типы функций

Excel4 и Excel12 различают три класса функций. Функции классифицируются в соответствии с тремя состояниями, в которых Excel может вызывать библиотеку DLL.

  • Класс 1 применяется, если библиотека DLL вызывается с листа в результате пересчета.
  • Класс 2 применяется при вызове библиотеки DLL из макроса функции или листа, на котором она была зарегистрирована с числового знака (#) в тексте типа.
  • Класс 3 применяется при вызове библиотеки DLL из объекта, макроса, меню, панели инструментов, сочетания клавиш, метода ExecuteExcel4Macro или команды Tools/Macro/Run . Дополнительные сведения см. в разделе Команды, функции и состояния Excel.

В следующей таблице показано, какие функции допустимы в каждом классе.

Класс 1 Класс 2 Класс 3
Любая функция листа
Любая функция xl... , доступная только для XLL, кроме xlSet. xlfCaller		 Любая функция листа
Любая функция xl..., кроме xlSet.
Функции листа макросов, включая xlfCaller, которые возвращают значение, но не выполняют никаких действий, влияющих на рабочую область или любую открытую книгу.		 Любая функция, включая функции xlSet и функции, эквивалентные командам.

Отображение диалогового окна для функции Command-Equivalent

Если функция, эквивалентная команде, имеет связанное диалоговое окно, можно задать бит xlPrompt в iFunction. Это означает, что перед выполнением команды Excel отображает соответствующее диалоговое окно.

Написание международных библиотек DLL

Если задать бит xlIntl в iFunction, функция или команда будет выполняться так, как если бы они были вызваны из международного листа макросов. Это означает, что команда ведет себя так же, как в версии Excel для США, даже если она выполняется в международной (локализованной) версии.

xlretUncalced или xlretAbort

После получения одного из этих возвращаемых значений библиотека DLL должна немедленно очистить и вернуть управление в Excel. Обратные вызовы в Excel через API C, кроме xlFree, отключаются после получения одного из этих возвращаемых значений.

Пример

В следующем примере функция Excel12 используется для выбора ячейки, из которой она была вызвана.

Этот пример кода является частью более крупного примера, приведенного в пакете SDK XLL для Excel 2010 в следующем расположении, где установлен пакет SDK:

\Samples\Example\Example.c.

Примечание.

Эта функция вызывает макрос команды (xlcSelect) и, следовательно, работает только в том случае, если он вызывается из листа макросов XLM.

short WINAPI Excel12Example(void)
{
    XLOPER12 xRes;
    Excel12(xlfCaller, &xRes, 0);
    Excel12(xlcSelect, 0, 1, (LPXLOPER12)&xRes);
    Excel12(xlFree, 0, 1, (LPXLOPER12)&xRes);
    return 1;
}

См. также

Excel4v/Excel12v