FUNCTION

Sintaxe

[ STATIC / USER ] FUNCTION <nome da função> [ ( <lista de parâmetros> ) ]

...

<instruções>

...

RETURN <expressão de retorno>

Propósito

O comando FUNCTION declara uma função definida pelo usuário (função de usuário) e os seus parâmetros.

Argumentos

<nome da função >

Define o nome que identificará a função de usuário declarada. Um nome poderá ter qualquer tamanho, mas apenas os 10 primeiros caracteres são usados para identificar a função. Poderão ser utilizados quaisquer caracteres, inclusive números e o underline ( _ ). Contudo, um nome não poderá ser iniciado pelo underline.

<lista de parâmetros>

Declara uma ou mais variáveis para receber os argumentos passados à função. As variáveis especificadas na lista são automaticamente declaradas como locais. Cada nome de variável deve ser separado do seguinte por uma vírgula.

STATIC FUNCTION

Declara uma função de usuário que poderá ser invocada apenas por outras funções declaradas no mesmo programa. Ou seja, no mesmo arquivo .PRW que contém o seu código.

USER  FUNCTION

Declara uma função de usuário específica, que não pertence ao padrão do Protheus. Ela poderá ser invocada por qualquer outra função pertencente ao Protheus.

RETURN <expressão de retorno>

Finaliza a função devolvendo o controle do fluxo de execução à rotina que invocou a função declarada, fornecendo o resultado da expressão de retorno como o valor da função. Cada função de usuário deve ter, no mínimo, um comando RETURN que forneça um valor de retorno.

Diversos comandos RETURN poderão ser incluídos em qualquer ponto dentro do corpo da função, de acordo com a sua estrutura de programação.

Utilização

O comando FUNCTION permite a declaração e a construção de funções definidas pelo próprio usuário, utilizando os recursos da linguagem AdvPL. Este comando praticamente abre a arquitetura da linguagem AdvPL para o usuário, pois através dele é possível expandi-la, criando funções próprias, de acordo com a necessidade.

Além de permitir a definição de funções para atender qualquer necessidade específica de processamento, o comando FUNCTION permite a criação de uma biblioteca própria de funções, que poderá ser utilizada em todas as aplicações desenvolvidas em AdvPL.

Uma função de usuário pode ser entendida como um subprograma compreendido por um conjunto de declarações e comandos que são executados sempre que a respectiva função for invocada. Uma função é identificada pelo seu nome, seguido por um par de abre e fecha parênteses, dentro dos quais poderão ou não ser passados parâmetros.

A definição de uma função inicia-se pelo comando FUNCTION e finaliza-se pelo comando RETURN. Declarações de funções não podem ser intercaladas por outras declarações de funções.

Funções são normalmente utilizadas para conter um bloco de instruções que, uma vez processado, fornece um valor como resultado. Este valor pode ser utilizado em expressões nas quais a função pode ser diretamente incluída.

A utilização de funções aumenta a modularidade e a legibilidade do código, facilita a realização de alterações e ajustes, e permite a construção de aplicações complexas com mais rapidez.

As funções possuem duas classes de visibilidade: públicas e estáticas. As funções públicas são visíveis em qualquer parte de uma aplicação e são declaradas pelo comando FUNCTION. As funções estáticas são visíveis apenas pelas outras funções contidas no mesmo programa (arquivo .PRW). As funções estáticas são declaradas pelo comando STATIC FUNCTION.

Dicas

Uma função de usuário é chamada através da mesma notação que as funções da biblioteca padrão do Protheus:

<nome da função> ( [ <lista de argumentos> ] )

Caso o valor de retorno da função não seja necessário, deve-se utilizar a mesma sintaxe para colocar a função de usuário sozinha em uma linha de instrução do programa. Neste caso, o valor de retorno da função será automaticamente descartado pelo AdvPL.

Uma função também pode ser invocada através de uma expressão precedida por um alias. Por exemplo:

<alias> -> ( <função>(<lista de argumentos>) )

Neste caso, a área de trabalho associada ao alias especificado é automaticamente selecionada e a expressão na qual está contida a função é executada. Ao ser finalizada, a área de trabalho original é novamente selecionada.

As funções recebem os parâmetros na ordem na qual eles são passados. No AdvPL, o números de argumentos passados não precisa ser igual ao números de parâmetros esperados pela função. Quando passados, os argumentos podem ser pulados, deixando o seu lugar vazio na lista de argumentos, ou simplesmente esquecido, deixando de ser especificados à esquerda da lista de parâmetros previstos.

Quando um parâmetro não é recebido, o valor NIL é atribuído automaticamente à variável que o receberia. O parâmetro pode ser enviado por valor ou por referência.

Exemplos

O exemplo abaixo usa a função de usuário Centra() para retornar uma mensagem que será mostrada ao usuário:

MSGALERT( Mensag(“Financeiro”) )

// Função que selecionará a mensagem que deverá ser mostrada ao usuário

FUNCTION Mensag(cTexto)

LOCAL cRet := “”

IF cTexto == “Financeiro”

          cRet := “Baixe o título a receber ou a pagar”

ELSEIF cTexto == “Faturamento”

          cRet := “Fature o Pedido de Venda ou o Pedido de Compra”

ELSEIF cTexto == “Compras”

          cRet := “Inclua um Pedido de Compra”

ELSE

          cRet := “Não há operação disponível”

ENDIF

RETURN cRet

A função Dpc(), mostrada abaixo, fornece, no formato MMM/AA e em português, o nome do mês e o ano da data passada como argumento.

FUNCTION Dpc(dData)

LOCAL nAux := 3 * MONTH(dData) – 2

LOCAL cMes := “JANFEVMARABRMAIJUNJULAGOSETOUTNOVDEZ”

LOCAL cDc := “”

cDc := SUBSTR(cMes, nAux, 3) + SUBSTR(DTOC(dData), 6, 8)

RETURN cDc