Funções

As informações desta página de ajuda se aplicam tanto a Studio quanto a Desktop Studio.

Uma função é um bloco de código reutilizável que desempenha determinada tarefa. Sempre que precisar da tarefa, você pode usar a função no seu script. Isto economiza tempo e esforço necessários para adicionar código àquela tarefa no seu script toda vez que precisar dela. Isso também mantém seus Scripts mais limpos e menos confusos, reduzindo a quantidade de código no script.

Funções podem:

  • Tomar dados do script, manipulá-los de certa forma e retornar os resultados de volta ao script.
  • Executar uma ação ou uma série de ações e passar os dados resultantes ao script.

Algumas funções são integradas ao Studio para uso em seus scripts. Não é necessário adicionar nada ao seu script para usar uma função integrada. Quando quiser usar uma, você pode simplesmente chamá-la.

Você também pode criar suas próprias funções personalizadas para usar em um script. Isso é útil quando você tem um código que usa frequentemente no seu script. Em vez de adicioná-la ao seu script sempre que precisar dela, você pode criar uma função que contém o código. E, então, quando precisar do código, você pode chamar a função.

Exemplos do uso de funções estão disponíveis para você baixar e importar no Studio.

Sintaxe

Os nomes de função têm um conjunto de parênteses aberto e fechado no final: functionName().

Todo texto dentro dos parênteses são parâmetros, que definem os dados que são passados entre a função e o script: functionName(param1,param2).

Para criar uma função personalizada, use esta sintaxe:

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

Nesta sintaxe:

  • FUNCTION é a palavra-chave obrigatória que inicia todas as instruções de função personalizada.
  • <name> é o nome da função.
  • ([<parameter>] [...]) define quaisquer parâmetros que a função requer.
  • { ... } contém o código da função.
  • [RETURN <data>] é a instrução a ser incluída para passar dados da função para o script principal.

Você pode nomear as suas funções personalizadas como quiser, desde que siga as seguintes diretrizes:

  • Use caracteres alfanuméricos (a-z, A-Z, 0-9).

  • O primeiro nome do caractere deve ser uma letra.
  • Use o caractere de sublinhado ( _ ) e o sinal de dólar ( $ ) em qualquer lugar do name.
  • Não use palavras reservadas ou os nomes de funções internas.

A sintaxe para uma instrução RETURN é:

RETURN ou RETURN <var>

Ao chamar uma função, use uma das seguintes sintaxes:

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Parâmetros e argumentos

Muitas funções precisam usar dados do script. Você pode fazer isso usando parâmetros e argumentos.

Parâmetros são definidos quando uma função é criada. Um parâmetro é um nome de variável que aparece entre parênteses após o nome da função. Uma função pode ter mais que um parâmetro. Cada parâmetro é separado por uma vírgula.Você pode incluir um espaço se quiser, mas isso não é necessário. Por exemplo, a função logn(value, base) tem dois parâmetros, value e base.

Os dados específicos que o script passa à função pelos parâmetros são chamados de argumentos. O exemplo a seguir mostra o uso da função integrada abs(value) em um script.Neste exemplo, -42 é o argumento transmitido para o parâmetro value.

ASSIGN abVal = abs(-42)

No Studio, todos os parâmetros são obrigatórios. Se uma função é definida com um parâmetro, você deve passar um valor quando chama a função. O número de argumentos passados para a função deve corresponder ao número de parâmetros definidos.

O script não verifica se os argumentos são do tipo ou formato correto. No entanto, se o argumento não for do tipo ou formato esperado pela função, a função pode não ser concluída com sucesso, ou os resultados podem não ser precisos.

Se forem passados argumentos em número excessivo ou insuficiente para a função, isso causa um erro de compilação quando você executa o script. Isso pode acontecer com funções internas e funções personalizadas.

Formatação de argumentos

Ao chamar uma função que exige parâmetros, você deve incluir os argumentos que está passando para a função. Siga essas diretrizes para formatar os argumentos:

  • Se o argumento for numérico ou uma variável, não é preciso colocá-lo entre aspas simples ou duplas.
  • Se o argumento for uma variável, não é preciso colocá-lo dentro de chaves.
  • Se o argumento for alfanumérico e não for uma variável, coloque-o dentro de aspas simples ou duplas.

Por exemplo, a dateadd() função requer três parâmetros, unit, date e value.

Unit define a parte da data que você deseja que a função altere, como o ano ou o mês. Date é a data original que você deseja modificar. E value é quanto você deseja que a função aumente a unidade especificada da data original. O exemplo a seguir mostra como cada parte é formatada:

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

O unit é uma string alfanumérica, portanto é formatado com aspas simples. O date neste exemplo é uma variável, portanto não possui aspas. Caso tenha passado uma string de data, ela precisará de aspas. O value não é formatado porque é numérico.

Instruções RETURN

Uma instrução RETURN finaliza uma função e retorna o controle para o script. Ela também pode retornar dados para o script.

RETURN Instruções só podem passar dados para o script como um valor de variável ou uma matriz. Eles não podem passar múltiplos valores, a menos que esses valores façam parte de uma matriz ou de um objeto. Elas não podem passar objetos, a não ser que os objetos sejam primeiro convertidos para JSON. Se necessário, você pode convertê-lo novamente em um objeto no script.

A sintaxe para uma instrução RETURN é:

RETURN ou RETURN <var>

Todas as funções internas que retornam um valor para o script contêm uma instrução RETURN. Nas funções personalizadas que você criar, as instruções RETURN são opcionais. Se não houver uma instrução RETURN, a função não poderá retornar nenhum valor para o script. A única maneira de usar uma função que não tenha uma instrução RETURN é chamando-a como uma instrução.

Se você incluir uma instrução RETURN em uma função, ela deve ser a última linha da função.

Visibilidade variável

O comportamento padrão é que todos os valores na função estão disponíveis e são para uso somente dentro da função. Quando a função termina, todos os valores na função são perdidos.Se a função contiver uma instrução RETURN que retorna um valor de variável para o script, somente os valores passados pela instrução RETURN ficam disponíveis fora da função.

Se você incluir variáveis em uma função personalizada que existem no script principal, essas variáveis terão escopo global. Isso significa que esses valores estarão disponíveis fora da função sem usar uma instrução RETURN. Da mesma forma, se declarar uma variável dentro da função como global, seu valor estará disponível no script principal. Isso é semelhante ao comportamento observado em subscritos.

Quando você usa uma função em uma expressão ou como o valor de uma variável, ela segue o comportamento padrão. No entanto, se chamar uma função como uma instrução, todos os valores na função terão escopo global e estarão disponíveis para uso fora da função. Para funções sem um RETURN, esta é a única maneira pela qual elas podem ser usadas.

Criar funções personalizadas

Você pode criar funções personalizadas quando tiver código que deseja poder usar em vários lugares no script. Uma função personalizada só fica disponível dentro do script onde ela é criada. Se você quiser usar uma função personalizada em um script diferente, deverá copiar o código de definição da função nesse script.

Você pode criar uma função em uma ação Snippet em seu script e, em seguida, chamá-la a partir de outras ações Snippet no mesmo script. Se você depurar o snippet contendo a definição da função, ela estará incluída na depuração. No entanto, a função não será incluída quando você depurar os outros snippets.

A sintaxe para declarar uma função personalizada é:

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTION é uma palavra-chave que informa ao script que o que se segue é uma função personalizada. Nomes de função devem seguir as mesmas diretrizes de nomeação de outras entidades nos scripts:

  • Use caracteres alfanuméricos (a-z, A-Z, 0-9).

  • O primeiro nome do caractere deve ser uma letra.
  • Use o caractere de sublinhado ( _ ) e o sinal de dólar ( $ ) em qualquer lugar do name.
  • Não use palavras reservadas ou os nomes de funções internas.

Se a função exigir parâmetros, coloque-os entre os parênteses no final do nome da função. Se não houver parâmetros, os parênteses podem ser deixados em branco. Separe vários parâmetros com vírgulas.

O código que compõe a função fica entre as chaves. O posicionamento das chaves é flexível. Eles podem ficar na mesma linha que a palavra-chave FUNCTION e o nome, ou podem estar em linhas separadas. Por exemplo, ambas as definições de Função a seguir são válidas:

FUNCTION myFunction() { ASSIGN var = "value" } 
FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

Se a função incluir uma instrução RETURN, ela deve ser a última instrução na função antes da chave de fechamento.

Saiba mais sobre a criação de funções na página de instruções de Declaração.

Funções de chamada em um script

Quando quiser usar uma função no seu script, você deve chamá-la. Há três maneiras de se chamar uma função. Nem todas as opções funcionam para todas as funções. As opções disponíveis para uma determinada função dependem se a função retorna um valor ou não. Você pode chamar uma função:

  • Sozinha como uma instrução. Esta opção funciona com todas as funções.
  • Em um local onde você usaria uma variável ou expressão. Esta opção funciona somente com funções que retornam um valor.
  • Com uma variável usando notação de ponto. Esta opção funciona somente com funções que retornam um valor.

Chamar uma Função como uma instrução

Uma instrução é uma linha de código com uma palavra-chave de comando que informa ao script o que fazer. Você pode usar uma função como uma instrução. Quando você faz isso, não é necessário uma palavra-chave de comando especial, como ocorre com outras declarações em um Snippet. O código na função indica ao script o que fazer.

Você pode chamar qualquer função como uma instrução.Se uma função não contiver uma instrução RETURN, esta é a única forma de chamá-la. Isso ocorre porque uma instrução RETURN passa dados da função de volta para o script. Quando não houver uma RETURN, ser chamada como uma instrução será a única forma que o script terá acesso aos dados na função.

A sintaxe para chamar funções como uma instrução é:

<functionName><([parameter], [parameter], [...])>

O exemplo a seguir mostra a função append() sendo chamada como uma instrução:

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

Use uma Função no lugar de uma Variável

Quando uma função retorna um valor, você pode usá-lo em qualquer lugar em que usaria uma variável ou expressão. O script pode usar o valor que a função retorna como usaria o valor de uma variável ou o resultado da expressão.

As sintaxes para usar uma função no lugar de uma variável são:

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Se desejar que o resultado da função seja atribuído a uma variável, você pode chamar a função como parte de uma instrução ASSIGN. Por exemplo, ASSIGN var = otherVar.function(). No entanto, há um caso em que isso não funciona, que é chamar uma função de membro da GetRESTproxy() função.

A seguir, é apresentado um exemplo que mostra como usar uma função que retorna um valor. Esta é a função de exemplo:

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}			

Esta função substitui o caractere ampersand ( & ) pela palavra and. No exemplo a seguir, a função replaceCharacters() é usada no lugar de uma variável no valor de string da variável stringRes. Quando este código é executado, o valor de stringRes é atualizado para My favorite animals are dogs and cats.

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

Usar uma Função com notação de ponto

Quando as funções retornam um valor, você pode usá-las com variáveis usando notação de ponto. Isso anexa a função à variável, desta forma: variable.function(). Quando você chama uma função dessa forma, o valor da variável é passado para a função.Esta opção funciona somente com funções que retornam um valor.

A sintaxe para usar uma função com notação de ponto:

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

O exemplo a seguir mostra essa abordagem. Esta é a função:

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}	

Este é um loop FOR que usa a função MyAppend com a variável ph:

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}

O resultado do loop FOR é: ph="123456789".

Quando você chama uma função usando a notação de ponto, o valor da variável à qual ela está anexada é passado para a função como o argumento do primeiro parâmetro. No exemplo anterior, o valor inicial de ph é passado para a função MyAppend() como o argumento do parâmetro a. É por isso que a chamada da função inclui apenas um argumento quando a definição da função tem dois parâmetros. O valor inicial de i é passado para a função como o argumento do parâmetro b.

A vantagem de chamar funções com notação de ponto é que isso permite que você adicione a ajuda da dica de ferramenta para a função.