Criar Funções De Fórmula Personalizada

Last modified: November 09, 2021

Crie funções personalizadas que podem ser acessadas por meio do alteryx designer em qualquer lugar que exista um editor de E xPression, como a ferramenta fórmula, ferramenta fórmula de várias linhas, ferramenta de filtro ou outros. As funções personalizadas são feitas por:

Escrevendo um arquivo XML, que encapsula parâmetros em outras chamadas de função.
Escrevendo uma DLL de estilo C.

Independentemente do método de criação, as funções são disponibilizadas ao designer usando um arquivo de função de fórmula XML, que deve conter os seguintes atributos:

: Um nome exclusivo que aparece na lista de funções.
: O número de parâmetros que a função aceita.
: A categoria de função que exibe a função. Isso pode ser uma nova categoria ou um já existente.
: O texto clichê que é inserido no editor de expressão quando a função é usada.
: Uma descrição que é exibida quando a função é pairada sobre.

Compilar usando XML

Ao criar uma função usando apenas XML, a estrutura do arquivo segue a do exemplo abaixo.

XML


    

            <?xml version="1.0" encoding="utf-8"?>
<FormulaAddIn>
  <Function>
    <Name>Sample_XML</Name>
    <NumParams variable="false">3</NumParams>
    <Category>Sample</Category>
    <InsertText>Sample_XML(Num1, Num2, Num3)</InsertText>
    <Description>Obtains the average of three numbers.</Description>
    <Formula>((P1+P2+P3)/3)</Formula>
  </Function>
</FormulaAddIn>

    <?xml version="1.0" encoding="utf-8"?>
<FormulaAddIn>
  <Function>
    <Name>Sample_XML</Name>
    <NumParams variable="false">3</NumParams>
    <Category>Sample</Category>
    <InsertText>Sample_XML(Num1, Num2, Num3)</InsertText>
    <Description>Obtains the average of three numbers.</Description>
    <Formula>((P1+P2+P3)/3)</Formula>
  </Function>
</FormulaAddIn>

O elemento Numparams tem uma variávelde atributo. O atributo é definido como false porque o número de parâmetros aceitos é corrigido. Ao usar apenas XML para criar uma função, o número de parâmetros aceitos é sempre corrigido.

O elemento Formula contém a fórmula que realmente executa o trabalho. O conteúdo não é visível para o usuário. Os parâmetros são sempre referenciados como P1, P2, P3e assim por diante, independentemente do texto apresentado no InsertText.

Para adicionar uma segunda função ao mesmo arquivo XML, crie outro elemento Function dentro do elemento formulaaddin .

Compilar usando uma DLL e XML

Para utilizar uma DLL, escreva a função pretendida e, em seguida, exportá-lo da DLL. Supondo que a função exportada é definida como:

XML


    

            struct FormulaAddInData{
	int nVarType;		// 1 for double, 2 for wchar_t
	int isNull;		// 1 if NULL, 0 if valid
	double dVal;		// valid if nVarType==1 && isNull==0
	const wchar_t * pVal;	// valid if nVarType==2 && isNull==0
};

    struct FormulaAddInData{
	int nVarType;		// 1 for double, 2 for wchar_t
	int isNull;		// 1 if NULL, 0 if valid
	double dVal;		// valid if nVarType==1 && isNull==0
	const wchar_t * pVal;	// valid if nVarType==2 && isNull==0
};

A função exportada tem a assinatura:

typedef long (_stdcall * FormulaAddInPlugin)(int nNumArgs, FormulaAddInData *pArgs, FormulaAddInData *pReturnValue);

Nnumargs contém o número real de argumentos na chamada.

Pargs aponta para uma matriz dos argumentos reais.

A função deve retornar um 1 para sinalizar o sucesso e um 0 para sinalizar a falha.

pReturnValue retorna o resultado calculado se a chamada for bem-sucedida ou uma mensagem de erro de cadeia de caracteres se a chamada não tiver êxito. Todas as cadeias de caracteres retornadas devem ser alocadas com GlobalAlloc, e Alteryx designer gerencia liberando a seqüência de caracteres.

Com a DLL configurada com êxito, você precisa referenciar a DLL do arquivo XML.

XML


    

            <?xml version="1.0" encoding="utf-8"?>
<FormulaAddIn>
  <Function>
    <Name>AddInData</Name>
    <NumParams variable="true">3</NumParams>
    <Category>Sample</Category>
    <InsertText>AddInData(VarType, isNull, double)</InsertText>
    <Description>Verifies data type before adding data.</Description>
    <Dll>
    	<Name>AddInData</Name>
    	<EntryPoint>FormulaAddInData</EntryPoint>
    </Dll>
  </Function>
</FormulaAddIn>

    <?xml version="1.0" encoding="utf-8"?>
<FormulaAddIn>
  <Function>
    <Name>AddInData</Name>
    <NumParams variable="true">3</NumParams>
    <Category>Sample</Category>
    <InsertText>AddInData(VarType, isNull, double)</InsertText>
    <Description>Verifies data type before adding data.</Description>
    <Dll>
    	<Name>AddInData</Name>
    	<EntryPoint>FormulaAddInData</EntryPoint>
    </Dll>
  </Function>
</FormulaAddIn>

O elemento Numparams tem uma variávelde atributo. O atributo é definido como true porque o número de parâmetros aceitos é variável. Ao usar um número variável de parâmetros, o valor deve ser igual ao número mínimo necessário.

O elemento dll contém dois elementos filho que fornecem as informações necessárias sobre a dll.

: O nome do arquivo DLL.
: O nome da função exportada que está sendo usada.

Funções de acesso no designer

Para disponibilizar as funções no Alteryx designer, vá para a pasta RuntimeData na instalação do Alteryx designer. Verifique se há uma pasta intitulada \FormulaAddIn. Se a pasta não existir, crie-a.

Exemplo XML em FormulaAddIn

A pasta contém Sample. xml, um arquivo que está configurado corretamente. Adicione uma categoria, salve o arquivo e reinicie o Alteryx designer para ver a função de exemplo.

C:\Arquivos de Programas\alteryx Bin\runtimedata\formulaaddin

Guarde o ficheiro XML para o directório \Formulaaddin . Se estiver usando DLL, salve o arquivo DLL relacionado no mesmo local. Convenção de nomenclatura padrão é nomear o arquivo DLL e XML para corresponder.