Compartilhar via

Excel4/Excel12

  • Artigo

Aplica-se a: Excel 2013 | Office 2013 | Visual Studio

Chama uma função de planilha interna do Microsoft Excel, uma função ou comando de planilha de macro ou uma função ou comando especial somente XLL, de dentro de um recurso de DLL/XLL ou código.

Todas as versões recentes do Excel dão suporte ao Excel4. A partir do Excel 2007, há suporte para o Excel12 .

Essas funções só podem ser chamadas quando o Excel passou o controle para a DLL ou XLL. Eles também podem ser chamados quando o Excel passou o controle indiretamente por meio de uma chamada para Visual Basic for Applications (VBA). Eles não podem ser chamados em nenhum outro momento. Por exemplo, eles não podem ser chamados durante chamadas para a função DllMain ou outras vezes em que o sistema operacional chamou a DLL ou de um thread criado pela DLL.

As funções Excel4v e Excel12v aceitam seus argumentos como uma matriz, enquanto as funções Excel4 e Excel12 aceitam seus argumentos como uma lista de comprimento variável na pilha. Em todos os outros aspectos, o Excel4 se comporta da mesma forma que o Excel4v e o Excel12 se comporta da mesma forma que o Excel12v.

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

Parâmetros

iFunction (int)

Um número que indica o comando, a função ou a função especial que você deseja chamar. Para obter uma lista de valores iFunction válidos, consulte a seção Observações a seguir.

pxRes (LPXLOPER ou LPXLOPER12)

Um ponteiro para um XLOPER (com Excel4) ou um XLOPER12 (com Excel12) que manterá o resultado da função avaliada.

iCount (int)

O número de argumentos subsequentes que serão passados para a função. Em versões do Excel até 2003, isso pode ser qualquer número de 0 a 30. A partir do Excel 2007, este pode ser qualquer número de 0 a 255.

argument1, ... (LPXLOPER ou LPXLOPER12)

Os argumentos opcionais para a função. Todos os argumentos devem ser ponteiros para valores XLOPER ou XLOPER12 .

Valor de retorno

Retorna um dos seguintes valores inteiros (int).

Valor Retornar código Descrição
0 xlretSuccess A função foi chamada com êxito. Isso não significa que a função não retornou um valor de erro do Excel; para descobrir isso, você deve examinar o tipo e o valor do parâmetro pxRes resultante.
1 xlretAbort O comando ou função foi encerrado anormalmente (abortar interno). Isso pode ocorrer se uma planilha de macro XLM se fechar chamando CLOSE ou se o Excel estiver sem memória. Se o Excel retornar esse erro, a função de chamada deverá sair imediatamente. A DLL tem permissão para chamar xlFree somente antes de sair. Todas as outras chamadas para a API C não são permitidas. O usuário pode salvar qualquer trabalho interativamente usando o comando Salvar no menu Arquivo .
2 xlretInvXlfn Um número de função inválido foi fornecido. Se você estiver usando constantes do arquivo de cabeçalho Xlcall.h, isso não deve ocorrer a menos que você esteja chamando algo que não tenha suporte na versão do Excel que você está executando.
4 xlretInvCount Um número inválido de argumentos foi inserido. Em versões até o Excel 2003, o número máximo de argumentos que qualquer função pode usar é 30. A partir do Excel 2007, o número máximo é 255. Alguns exigem um número fixo ou mínimo de argumentos.
8 xlretInvXloper Um XLOPER ou XLOPER12 inválido foi passado para a função ou um argumento do tipo errado foi usado.
16 xlretStackOvfl Ocorreu um estouro de pilha. Use xlStack para monitorar a quantidade de espaço deixada na pilha. Evite alocar matrizes e estruturas locais (automáticas) muito grandes na pilha sempre que possível; torná-los estáticos. (Observe que um estouro de pilha pode ocorrer sem ser detectado.)
32 xlretFailed Falha na função equivalente a comando. Isso é equivalente a um comando macro que exibe a caixa de diálogo alerta de erro de macro.
64 xlretUncalced Foi feita uma tentativa de desreferência de uma célula que ainda não foi calculada, pois ela está agendada para ser recalculada após a célula atual. Nesse caso, a DLL deve retornar o controle ao Excel imediatamente. A DLL tem permissão para chamar xlFree somente antes de sair. Todas as outras chamadas para a API C não são permitidas. Para obter mais informações sobre quais funções podem e não podem acessar os valores de células que não foram recalculadas, consulte Comandos, Funções e Estados do Excel.
128 xlretNotThreadSafe Foi feita uma tentativa de chamar uma função que não é, ou pode não ser, thread safe durante um recálculo multithread da pasta de trabalho. A partir do Excel 2007, esse valor é retornado e somente dentro das funções de planilha XLL declaradas como thread safe.
256 xlRetInvAsynchronousContext O identificador de função assíncrona é inválido. Esse valor é usado apenas pelo Excel 2010.
512 xlRetNotClusterSafe A chamada não tem suporte em clusters. Esse valor é usado apenas pelo Excel 2010.

Comentários

Valores iFunction válidos

Os valores iFunction válidos são qualquer uma das constantes xlf... ou xlc... definidas no arquivo de cabeçalho Xlcall.h ou qualquer uma das funções especiais a seguir.

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

Tipos diferentes de funções

Excel4 e Excel12 distinguem entre três classes de funções. As funções são classificadas de acordo com os três estados em que o Excel pode chamar a DLL.

  • A classe 1 se aplica quando a DLL é chamada de uma planilha como resultado do recálculo.
  • A classe 2 se aplica quando a DLL é chamada de dentro de uma macro de função ou de uma planilha em que foi registrada com um sinal de número (#) no texto do tipo.
  • A classe 3 se aplica quando uma DLL é chamada de um objeto, macro, menu, barra de ferramentas, tecla de atalho, método ExecuteExcel4Macro ou o comando Tools/Macro/Run . Para obter mais informações, consulte Comandos, Funções e Estados do Excel.

A tabela a seguir mostra quais funções são válidas em cada classe.

Classe 1 Classe 2 Classe 3
Qualquer função de planilha
Qualquer função xl... somente XLL, exceto xlSet. xlfCaller		 Qualquer função de planilha
Qualquer função xl... exceto xlSet.
Funções de planilha de macro, incluindo xlfCaller, que retornam um valor, mas não executam nenhuma ação que afete o workspace ou qualquer pasta de trabalho aberta.		 Qualquer função, incluindo funções xlSet e equivalentes de comando.

Exibir a caixa de diálogo para uma função de Command-Equivalent

Se uma função equivalente a comando tiver uma caixa de diálogo associada, você poderá definir o bit xlPrompt no iFunction. Isso significa que o Excel exibe a caixa de diálogo apropriada antes de executar o comando.

Gravar DLLs internacionais

Se você definir o bit xlIntl no iFunction, a função ou o comando será realizado como se estivesse sendo chamado de uma Folha de Macro Internacional. Isso significa que o comando se comporta como faria na versão dos EUA do Excel, mesmo que esteja em execução em uma versão internacional (localizada).

xlretUncalced ou xlretAbort

Depois de receber um desses valores retornados, sua DLL deve limpo para cima e retornar o controle ao Excel imediatamente. Os retornos de chamada no Excel por meio da API C, exceto xlFree, são desabilitados após receberem um desses valores retornados.

Exemplo

O exemplo a seguir usa a função Excel12 para selecionar a célula da qual foi chamada.

Este exemplo de código faz parte de um exemplo maior fornecido no SDK xll do Excel 2010, no seguinte local em que você instalou o SDK:

\Samples\Example\Example.c.

Observação

Essa função chama uma macro de comando (xlcSelect) e, portanto, funciona somente se for chamada de uma planilha de macro 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;
}

Confira também

Excel4v/Excel12v