Meu primeiro fonte

[section_title title=Funções]

O AdvPL é uma linguagem de programação estruturada, composta por um conjunto de comandos, funções e objetos.

Um programa AdvPL é composto por uma ou mais rotinas. Uma rotina consiste numa série de instruções (comandos, funções e objetos) que seguem regras de sintaxe definidas pela linguagem AdvPL, com o objetivo de realizar determinadas operações no computador. Um típico programa pode possuir vários tipos de instruções diferentes, entre elas:

Comandos;
Declarações;
Execução de funções;
Execução de procedimentos;
Diretivas para o pré-processador;
Estruturas de controle de fluxo de execução e de decisão;
Atribuição de valores;
Comentários.

Um programa é armazenado em um arquivo do tipo texto, que normalmente é gravado com a extensão .PRW. Este arquivo é criado por meio de um ambiente de desenvolvimento chamado TDS (TOTVS Developer Studio).

Espaços em branco e tabulações são ignorados pelo compilador do AdvPL, permitindo que as linhas do programa sejam formatadas para facilitar a sua leitura e compreensão. Um ou é interpretado como o final de uma linha de instrução do programa.

Portanto, um programa é um arquivo texto contendo diversas rotinas (procedimentos ou funções) escritas em AdvPL, cada uma executando uma determinada operação, de acordo com a natureza e os objetivos do aplicativo desenvolvido. Uma aplicação normalmente contém diversos programas, conforme exemplo demonstrado na figura abaixo.

[section_title title=Comandos]

Comandos

Cada comando será apresentado através de diversos tópicos, relacionados na tabela abaixo.

Tópico	Conteúdo
Comando	Palavra-chave ou nome que identifica o comando.
Sintaxe	Define, de maneira esquemática, a forma e as regras para a utilização do comando.
Propósito	Descreve o objetivo principal ou propósito do comando.
Argumentos	Define o significado e a forma de utilizar cada cláusula ou argumento do comando.
Utilização	Apresenta conceitos para a aplicação do comando e descreve como utilizá-lo.
Dicas	Apresenta dicas e sugestões interessantes para a aplicação do comando.
Exemplo	Exemplos genéricos, úteis para o entendimento da aplicação e utilização do comando.
Veja também	Apresenta uma lista de outros comandos ou funções relacionados para consulta.

Notação e convenções de sintaxe

Para a apresentação e explicação dos comandos e funções do AdvPL, usaremos um tipo de notação padronizada e tradicional. Apresentamos abaixo as convenções e símbolos desta notação:

As palavras-chave que identificam os comandos e funções do AdvPL são sempre escritas em letras maiúsculas. Por exemplo: BEGIN SEQUENCE
Diretivas para o compilador são sempre apresentadas em letras minúsculas, precedidas pelo símbolo # (numeral). Por exemplo: #include
A parte dos comandos que deverá ser informada pelo leitor aparecerá entre os sinais menor e maior ( < > ) e estará em letras minúsculas. Por exemplo: IF <condição>Os argumentos das funções que devem ser informados pelo leitor são especificados entre parênteses ( ), separados por vírgulas e sempre estarão em letras minúsculas. Por exemplo: SQRT(<expressão numérica>)
- Os sinais < e > não fazem parte da sintaxe do comando ou função, sendo utilizados apenas para representar a informação que deve ser suprida pelo leitor.
As cláusulas opcionais de alguns comandos ou argumentos opcionais de algumas funções são apresentados entre colchetes [ ]. Isto significa que o leitor poderá ou não incluir esta parte do comando ou função, pois ela é opcional. Com exceção da declaração de arrays, os colchetes não fazem parte da sintaxe dos comandos ou funções, sendo utilizados apenas para representar a parte que pode ser opcionalmente informada pelo leitor.
Um bloco de código ou matriz são representados entre chaves { }. Por exemplo:A lista de argumentos utilizados em blocos de código deve ser especificada entre barras verticais | |.
- { | x | x + 1 }
- aMat := { 1, 2, 3 }
A vírgula será utilizada para separar múltiplas cláusulas ou argumentos contidos na sintaxe de comandos ou funções.
O símbolo arroba ( @ ) indicará que um argumento deve ser passado por referência para uma função.
As opções alternativas de alguns comandos serão indicadas através da barra inclinada ( / ).
Cláusulas repetitivas ou extensas serão indicadas por reticências ( … ). Por exemplo: IF … ELSEIF … ELSEIF … ELSE … ENDIF.
Os nomes das rotinas definidas pelo programador, ou seja, funções não pertencentes ao AdvPL, terão a primeira letra do seu nome apresentada em letra maiúscula e as restantes em letras minúsculas. Por exemplo: Calcmed().
Comandos ou funções obsoletos serão apresentados com um asterisco após o seu nome. Por exemplo: RECCOUNT()*
Os nomes de arquivos serão apresentados em letras maiúsculas. Por exemplo: MATA020.PRW
Extensões de nomes de arquivos serão iniciadas por um ponto e escritas em letras maiúsculas. Por exemplo: .PRW

O AdvPL possui várias funções pré-programadas extremamente úteis e necessárias ao desenvolvimento de aplicações sofisticadas. As funções constituem o grande poder do AdvPL, sendo consideradas até como um recurso mais importante do que os comandos.

[section_title title=Funções]

Funções

Todas as funções da biblioteca padrão do AdvPL possuem a seguinte forma:

FUNÇÃO(<lista de argumentos>)

FUNÇÃO define o nome que identifica a função e a lista de argumentos, entre parênteses, são os seus argumentos, separados por vírgulas.

Os argumentos das funções são valores com os quais a função executará alguma operação e fornecerá um resultado. Os argumentos podem ser constituídos por cadeias de caracteres, variáveis, números, valores lógicos, datas, expressões válidas de qualquer tipo, arrays, elementos de arrays, blocos de código, objetos, etc.

Algumas funções possuem apenas um argumento, outras possuem várias e existem algumas funções que não possuem argumentos, apenas fornecem valores ou executam determinadas instruções.

Assim como os comandos, as funções são apresentadas através dos seguintes tópicos:

Tópico	Conteúdo
Função	Identifica o nome da função
Sintaxe	Define a sintaxe para a sua utilização
Propósito	Define o seu propósito principal
Argumentos	Especifica a lista dos argumentos que a função utiliza
Utilização	Descreve como a função deve ser utilizada
Dicas	Fornece informações úteis para a utilização das funções
Exemplo	Apresenta alguns exemplos práticos da aplicação da função
Veja também	Lista outras funções e comandos relacionados à função apresentada, que também devem ser consultados

Notação e convenções de sintaxe

Para a apresentação e explicação das funções do AdvPL, usaremos um tipo de notação padronizada e tradicional. Apresentamos abaixo as convenções e símbolos desta notação:

As palavras-chave reservadas que identificam os nomes das funções do AdvPL são sempre escritas em letras maiúsculas, acompanhadas de um abre e fecha parênteses. Por exemplo: SQRT() – função raiz quadrada
Os argumentos que deverão ser informados pelo leitor aparecerão entre os sinais menor e maior ( < > ) e estarão em letras minúsculas. Por exemplo: SQRT(<expressão numérica>)
- Os sinais < e > não fazem parte da sintaxe da função, sendo utilizados apenas para representar a informação que deve ser suprida pelo leitor.
Os argumentos opcionais de algumas funções são apresentados entre colchetes [ ]. Isto significa que o leitor poderá ou não incluir estes argumentos quando utilizar a função, pois eles são opcionais. Com exceção da declaração de arrays, os colchetes não fazem parte da sintaxe das funções, sendo utilizados apenas para representar a parte que pode ser opcionalmente informada pelo leitor. Por exemplo:As opções alternativas de algumas funções serão indicadas através da barra inclinada ( / ).
- STR(<expressão caracter> [, <expressão numérica 1> ] [, <expressão numérica 2> ])
Os nomes das funções definidas pelo programador, ou seja, funções não pertencentes ao AdvPL, terão a primeira letra do seu nome apresentada em letra maiúscula e as restantes em letras minúsculas. Por exemplo: Calcmed().
Os nomes de arquivos serão apresentados em letras maiúsculas. Por exemplo: MATA020.PRW

[section_title title=Boas praticas]

Boas Práticas

As boas práticas tem como objetivo definir convenções, padrões, práticas e técnicas que melhoraram a qualidade e a manutenção dos softwares criados utilizando a linguagem ADVPL e o Microsiga Protheus.

Capitulação de palavras-chaves

A capitulação de palavras é mais um aditivo que se usado corretamente facilita a leitura do código-fonte, principalmente com comandos de palavras compostas, e auxilia na identificação do tipo de comando.

<span style="font-family: arial, helvetica, sans-serif;">Local cMyName            := ""
Local nMemAge            := 30
Local dMyBirthday        := CToD("01/01/2001")
Local aValidNames        := {}
Local nABCType           := 1</span>

<span style="font-family: arial, helvetica, sans-serif;">Local cMyName := ""

Local nMemAge := 30

Local dMyBirthday := CToD("01/01/2001")

Local aValidNames := {}

Local nABCType := 1</span>

A formatação vertical representa a distância entre as declarações de importação, variáveis, funções, e assim em diante. Para melhor visualização é importante que se separe de acordo com o tipo de comando. Nós conseguimos uma leitura mais rápida e clara quando enxergamos pequenos blocos e cada bloco com o conteúdo de mesmo tipo. Para melhor visualização, deixaremos o bloco de declaração de variáveis separado dos comandos. Exemplo:

Todas as separações devem ter um espaço de distância, esta separação faz com que se enxergue cada bloco de uma vez. Assim, você não precisa procurar por toda função para verificar se foi declarada a variável, pois se a mesma não estiver no bloco de variáveis, não estará em outro lugar.

Identação do fonte

Para uma leitura fácil de um fonte é preciso que ele esteja bem legível, seja fazendo a captulação das variáveis, funções e comandos, quanto alinhá-lo. Abaixo irei exemplificar duas formas, sendo que a primeira é a mais aceitável e legível.

User Function Funcao()
    Local nTotal  := 10
    Local nConta  := 0

    For nConta := 1 to nTotal
       Alert(nConta)
    Next
Return
User Function Funcao()
Local nTotal  := 10
Local nConta  := 0
For nConta := 1 to nTotal
Alert(nConta)
Next
Return

User Function Funcao()

Local nTotal := 10

Local nConta := 0

For nConta := 1 to nTotal

Alert(nConta)

Return

User Function Funcao()

Local nTotal := 10

Local nConta := 0

For nConta := 1 to nTotal

Alert(nConta)

Return

[section_title title=Comentarios]

Comentários

Comentar o fonte é muito importante, pois ajuda outros ou até mesmo você a saber exatamente do que se trata o seu fonte.

Temos duas formas de comentar os fontes:

*Comentar a linha

//Comentar a linha

Comentar um bloco

Local nSoma := 0 // Inicializa a variável com zero para a soma

Assim como a Totvs faz, criamos um bloco de comentários onde identificamos o fonte, descrevemos sobre ele, informamos o nome e data o criou e/ou modificou.

Exemplo formato Totvs:

Comentário padrão Totvs

Outra forma de identificação do fonte:

[section_title title=notacao]

Notação Húngara

A Notação Húngara visa facilitar o reconhecimento do tipo da variável em um código-fonte. A adoção deste critério de nomeação é bastante prática e intuitiva, sendo a ideia básica nomear todos os tipos de variáveis, visando-se simplificar o entendimento. Para isso, deve-se adicionar um prefixo ao nome da variável. Esse prefixo será em letra minúscula e de acordo com o tipo de conteúdo da mesma. Notações:

“a” – Array;
“b” – Bloco de código;
“c” – Carácter;
“d” – Data;
“l” – Lógico;
“n” – Numérico;
“o” – Objeto;
“u” – Indefinido.

Exemplo:

Local aArray             := {}
Local bFormula           := {||}
Local cName              := ""
Local dData              := CToD("01/01/01")
Local lLogical           := .T.
Local nNumeric           := 0
Local oObject            := Nil
Local uUndefined         := Nil

Local aArray := {}

Local bFormula := {||}

Local cName := ""

Local dData := CToD("01/01/01")

Local lLogical := .T.

Local nNumeric := 0

Local oObject := Nil

Local uUndefined := Nil

As variáveis nunca devem ser declaradas na mesma linha, independente da quantidade ou de serem todas do mesmo tipo. Isso garante uma melhor visualização e um espaço para comentários. Portanto, as variáveis devem se declaradas juntas verticalmente mas em linha separadas.

A posição das variáveis é importantíssima, todas devem ficar unidas verticalmente mas separadas por pelo menos um espaço na parte inferior; Isso fará com que formem um único bloco de variáveis, fácil de achar. A posição do bloco deve ser no inicio da função ou estrutura de condição/repetição.

Todas as variáveis devem ser inicializadas na sua declaração. Por padrão os seguintes tipos de variáveis devem ser inicializados com os seguintes conteúdos:

Array = {}

Bloco de código = {||}

Carácter = “”

Data = CToD(“//”)

Lógico = .F. ou .T.

Numérico = 0

Objeto = Nil

Indefinido = Nil

[section_title title=Nomes longos]

Nomes longos

A linguagem ADVPL suporta para nomes de funções, métodos, variáveis, comandos de pré-processamento o tamanho máximo de 10 caracteres. A única exceção é nome de classe que não tem limite.

Para minimizar o impacto dessa limitação, não recomendamos que a nome seja abreviado, recomendamos a inversão do nome, para que a palavra que diferencia duas funções esteja no começo do nome

[section_title title=Comecando]

Diretivas para o compilador

Diretivas são instruções fornecidas para o compilador do AdvPL que afetam a forma como o programa será compilado, mas não a forma como a aplicação será executada.

As diretivas para o compilador iniciam sempre com o símbolo numeral ( # ), seguido pela correspondente instrução ao compilador em letras minúsculas.
Neste tópico apresentamos as diretivas para o compilador do AdvPL.

#define

Utilização

Essa diretiva define um nome identificador e, opcionalmente, associa-lhe um texto de substituição. Se o texto de substituição for especificado, o compilador substituirá a constante pelo texto sempre que a encontrar numa linha do código-fonte do arquivo de programa (.PRW) no qual ela foi definida.

Os nomes identificadores especificados através da diretiva #define seguem quase todas as regras de nomenclatura de variáveis do AdvPL. A principal exceção é que os identificadores definidos pela diretiva #define são case-sensitives, ou seja, diferenciam letras maiúsculas de minúsculas. Portanto, o identificador

ident1 é diferente do identificador IDENT1, por exemplo.

Por convenção, os identificadores definidos pela diretiva #define são sempre especificados em letras maiúsculas, para serem facilmente distinguidos dos outros identificadores de um programa. Além disso, convenciona-se também que os identificadores #define são iniciados por uma ou duas letras padronizadas como prefixo, com o objetivo de agrupar determinados tipos de identificadores, além de garantir a sua unicidade.

O arquivo cabeçalho PROTHEUS.CH, contido no diretório INCLUDE abaixo do diretório raiz do Protheus, é um bom exemplo da utilização da diretiva #define para definir identificadores que facilitam o uso de diversas funções padrão do AdvPL.

Cada definição feita pela diretiva #define deve ocorrer isoladamente em uma linha de instrução. Embora uma única definição possa ser continuada por diversas linhas físicas, através do ponto-e-vírgula, o AdvPL não permite que uma única linha lógica de instrução contenha mais de uma definição #define. Cada diretiva #define deve ser colocada numa linha de instrução própria, sendo seguida por um ou mais espaços em branco, ou tabulações, por um único nome identificador e opcionalmente pelo texto de substituição. Entretanto, definições podem ser intercaladas. Isto é, um identificador pode definir outro.

Um identificador definido através da diretiva #define é válido apenas para as funções contidas no arquivo de programa (.PRW) no qual foi definido. Uma vez definido, o identificador torna-se visível a partir da linha de instrução que o definiu até a última linha do arquivo de programa (.PRW) ou até que seja cancelado, por meio da diretiva #undef, ou redefinido.

Identificadores já definidos pela diretiva #define poderão ser cancelados ou redefinidos. Para redefini-los, basta executar uma nova diretiva #define com o mesmo nome identificador, atribuindo-lhe um novo texto de substituição. Neste caso, uma mensagem de advertência do compilador será apresentada. Porém, ela não constituirá um erro, mas apenas um aviso para chamar a atenção sobre a redefinição efetuada.

Para cancelar um identificador deve se utilizar a diretiva #undef, tendo como seu argumento o nome do identificador a ser cancelado.

A diretiva #define possui três propósitos básicos:

Definir um identificador de controle para as diretivas #ifdef e #ifndef;
Definir uma constante, ou seja, um identificador para representar um valor constante dentro do programa;
Definir uma pseudofunção para o compilador.

Identificadores para o compilador

Este tipo de identificador é definido através da diretiva #define sem a especificação do texto de substituição. É normalmente utilizado no teste de existência de um identificador efetuado pelas diretivas #ifdef e #ifndef.

Estas diretivas permitem a determinação de compilações condicionais, baseadas na existência ou não de um identificador, causando a inclusão ou a exclusão de um determinado trecho do código-fonte no processo de compilação.

Constantes

Neste caso, a diretiva #define é utilizada para atribuir um nome identificador para um determinado valor constante que será utilizado pelo programa. Sempre que este identificador for encontrado pelo compilador numa linha do programa, será substituído pelo valor constante especificado. A utilização típica deste tipo de identificador é exemplificada abaixo:

#define K_ESC     27
  ...
  &lt;instruções&gt;
  ...

IF LASTKEY() == K_ESC
   RETURN
ENDIF

#define K_ESC 27

...

<instruções>

...

IF LASTKEY() == K_ESC

RETURN

ENDIF

Neste exemplo, o identificador K_ESC representa o valor constante 27, que corresponde ao código da função INKEY() para a tecla <Esc>. Portanto, quando o compilador encontrar o identificador K_ESC, ele o substituirá pelo valor constante 27, que será efetivamente processado durante a execução do programa.

Embora este tipo de problema possa ser resolvido através da utilização de variáveis de memória normais para armazenar os valores constantes, há uma série de vantagens na utilização de identificadores definidos através da diretiva #define para a representação de valores constantes. Entre estas vantagens podemos citar:

O compilador gera um código mais compacto e mais rápido;
O programa utilizará menos memória durante a sua execução;
O programa será executado com mais rapidez;
Não ocorrerá mais um erro conceitual normalmente cometido quando se usa uma variável para armazenar um valor constante;
O AdvPL fornece uma série de arquivos cabeçalho (header files) que já definem um conjunto de identificadores para representar os valores constantes utilizados por diversas funções. A inclusão destes arquivos cabeçalho, através da diretiva #include, facilita muito a utilização das funções em termos de programação;
A clareza e a legibilidade dos programas é sensivelmente melhorada com o uso de identificadores que seguem as convenções dos arquivos cabeçalho definidos pelo AdvPL. Por exemplo, ao invés de decorar todos os códigos das teclas, é melhor ler o nome dos identificadores: K_ESC ao invés de 27, K_RETURN ao invés de 13, e assim por diante;
A manutenção dos programas torna-se mais rápida, pois a definição dos identificadores de constantes fica localizada num mesmo ponto;
As definições dos identificadores de constantes e de outros identificadores podem ser agrupadas em arquivos específicos: os arquivos cabeçalho. Estes podem ser “incluídos” num determinado programa, através da diretiva #include, permitindo que as mesmas definições sejam utilizadas por diversos programas, grupos de programas ou aplicações inteiras. Esta técnica gera uma maior padronização, organização e otimização do seu código-fonte;
A utilização de identificadores para constantes torna o programa mais independente do seu ambiente operacional e até do equipamento utilizado.

Pseudofunções

A diretiva #define também pode definir pseudofunções durante a fase de compilação. Uma pseudofunção corresponde basicamente a um identificador que é substituído por uma expressão. Por exemplo:

#define RCUB(nX)                      (nX ^ 1 / 3)                    // Raiz cúbica

#define ARET(nLarg, nComp)     (nLarg * nComp)          // Área de um retângulo

#define ATRI(nBase, nAltura)     (nBase * nAltura / 2)     // Área de um triângulo

#define RCUB(nX) (nX ^ 1 / 3) // Raiz cúbica

#define ARET(nLarg, nComp) (nLarg * nComp) // Área de um retângulo

#define ATRI(nBase, nAltura) (nBase * nAltura / 2) // Área de um triângulo

Durante a fase de compilação, sempre que o compilador encontra uma chamada a uma função que coincide com a definição de uma pseudofunção, ele substitui a pseudofunção pela expressão correspondente. Por exemplo:

MSGALERT( RCUB(9) )          // É substituída por (9 ^1 / 3)

MSGALERT( ARET(5, 10) )     // É substituída por (5 * 10)

MSGALERT( ATRI(10, 5) )      // É substituída por (10 * 5 / 2)

MSGALERT( RCUB(9) ) // É substituída por (9 ^1 / 3)

MSGALERT( ARET(5, 10) ) // É substituída por (5 * 10)

MSGALERT( ATRI(10, 5) ) // É substituída por (10 * 5 / 2)

Ao se utilizar a diretiva #define na definição de pseudofunções e ao se utilizar as pseudofunções definidas, algumas regras devem ser observadas:

A expressão que corresponde à função e fornecerá o seu resultado deve ser especificada entre parênteses;
Na utilização de pseudofunções, todos os argumentos devem ser obrigatoriamente especificados;
O nome das pseudofunções é diferenciado pela utilização de letras maiúsculas ou minúsculas (case sensitive). Por exemplo, a pseudofunção RCUB foi definida, mas rcub não existe.

Pseudofunções devem ser utilizadas com cuidado e profissionalismo. Apesar de otimizarem o código executável, elas dificultarão a manutenção dos programas, pois possuem um escopo diferente das funções normais: são case sensitive e não permitem a omissão de argumentos. Por estes motivos, na maioria dos casos deve-se dar preferência à utilização de funções de usuário normais ou à definição de pseudofunções através da diretiva #translate. Neste último caso, as vantagens em termos de otimização do código são mantidas, a nomenclatura das pseudofunções seguirá as regras normais do AdvPL e argumentos poderão ser omitidos.

[section_title title=New page title]

#include

Utilização

A diretiva #include insere o conteúdo de outro arquivo de código-fonte, tradicionalmente denominado arquivo cabeçalho (header file), no arquivo de programa (.PRW) que estiver sendo compilado, a partir da linha na qual for encontrada pelo compilador. Os arquivos cabeçalho recebem a extensão padrão .CH e podem conter qualquer tipo de instrução. Entre elas, as principais são funções genéricas e diretivas #define para o compilador.

As constantes e pseudofunções definidas através de diretivas #define são válidas apenas para o arquivo de programa (.PRW) corrente, a partir da linha na qual a definição foi feita até o final do programa. Por esse motivo, todas as definições feitas pelas diretivas #define devem estar no topo do arquivo de programa. Como os arquivos cabeçalho incluídos pela diretiva #include normalmente contém definições feitas por diretivas #define, eles devem ser incluídos no topo ou no cabeçalho dos arquivos de programa.

[section_title title=New page title]

#ifdef

Utilização

A diretiva #ifdef … #endif permite a realização de compilações condicionais. A compilação condicional permite que um determinado trecho de código-fonte seja ou não compilado, dependendo da existência ou não de um identificador. Um identificador pode ser definido pela diretiva #define.

Se a cláusula #else for especificada e o identificador existir, o trecho de código entre o #ifdef e o #else será compilado. Se o identificador não existir, o trecho de código entre o #else e o #endif é que será compilado.

Se a cláusula #else não for especificada e o identificador existir, o trecho de código entre o #ifdef e o #endif será compilado. Se o identificador não existir, esse trecho de código não será compilado.

Dicas

A compilação condicional é útil principalmente quando for necessária a manutenção de várias versões diferentes do mesmo programa. Para cada versão poderá ser compilado um determinado trecho de código diferente, de acordo com os identificadores que forem especificados.

[section_title title=New page title]

#ifndef

Utilização

A diretiva #ifndef … #endif permite a realização de compilações condicionais. A compilação condicional permite que um determinado trecho de código-fonte seja ou não compilado, dependendo da inexistência ou não de um identificador. Um identificador pode ser definido pela diretiva #define.

Se a cláusula #else for especificada e o identificador não existir, o trecho de código entre o #ifndef e o #else será compilado. Se o identificador existir, o trecho de código entre o #else e o #endif é que será compilado.

Se a cláusula #else não for especificada e o identificador não existir, o trecho de código entre o #ifndef e o #endif será compilado. Se o identificador existir, esse trecho de código não será compilado.

Dicas

A diretiva #ifndef … #endif é o inverso da diretiva #ifdef … #endif

[section_title title=New page title]

#undef

Utilização

A diretiva #undef cancela a definição de um identificador feita pela diretiva #define. Após a execução da diretiva #undef, o identificador especificado torna-se indefinido.

Dicas

A diretiva #undef é normalmente utilizada para cancelar um identificador antes que ele seja novamente redefinido, evitando assim que o compilador apresente uma mensagem de advertência. Além disso, a diretiva #undef também pode ser utilizada em conjunto com as diretivas #define, #ifdef … #endif e #ifndef … #endif para controlar a compilação condicional.

[section_title title=New page title]

Assim como a linha física, delimitada pela quantidade de caracteres que pode ser digitado no editor de textos utilizado, existe uma linha considerada linha lógica. A linha lógica, é aquela considerada para a compilação como uma única linha de comando.

A princípio, cada linha digitada no arquivo texto é diferenciada após o pressionamento da tecla <Enter>. Ou seja, a linha lógica, é a linha física no arquivo. Porém algumas vezes, por limitação física do editor de texto ou por estética, pode-se “quebrar” a linha lógica em mais de uma linha física no arquivo texto. Isto é efetuado utilizando-se o sinal de ponto-e-vírgula (;).

If !Empty(cNome) .And. !Empty(cEnd) .And. ;   
   !Empty(cTel)  .And. !Empty(cFax) .And. ;   
   !Empty(cEmail)

   GravaDados(cNome,cEnd,cTel,cFax,cEmail)

Endif

If !Empty(cNome) .And. !Empty(cEnd) .And. ;

!Empty(cTel) .And. !Empty(cFax) .And. ;

!Empty(cEmail)

GravaDados(cNome,cEnd,cTel,cFax,cEmail)

Endif

Neste exemplo existe uma linha de comando para a checagem das variáveis utilizadas. Como a linha torna-se muito grande, pode-se dividí-la em mais de uma linha física utilizando o sinal de ponto-e-vírgula. Se um sinal de ponto-e-vírgula for esquecido nas duas primeiras linhas, durante a execução do programa ocorrerá um erro, pois a segunda linha física será considerada como uma segunda linha de comando na compilação. E durante a execução esta linha não terá sentido.

[section_title title=meuprimeirofonte]

Ufa! Finalmente vamos ao que interessa. Agora que já conhece algumas informações básicas para iniciar o desenvolvimento, vamos começar.

Vamos criar a primeira função para rodar no Protheus.

#include "Protheus.ch"
User Function Funcao()
    Local cMensagem := "Olá Mundo!"
    Alert(cMensagem)
Return

#include "Protheus.ch"

User Function Funcao()

Local cMensagem := "Olá Mundo!"

Alert(cMensagem)

Return

A primeira linha, informamos a diretiva #include, pois informamos ao compilador a biblioteca que será utilizada, é semelhante a diretiva Import utilizada por exemplo em C# e VB.Net

A segunda linha, é como começamos uma função de usuário que o Protheus irá visualizar e executar

A terceira linha, foi declarado uma variável e já incluo um texto nela

A quarta linha, chamo a função Alert() que é uma função que exibirá o texto contido na variável.

A quinta e última linha, finalizamos o nosso fonte.

/*
+------------------+---------------------------------------------------------+
!Modulo            ! Diversos                                                !
+------------------+---------------------------------------------------------+
!Nome              ! fAllTec                                                 !
+------------------+---------------------------------------------------------+
!Descricao         ! Função para retornar o codigo de todos os tecnicos do   !
!                  ! sistema                                                 !
+------------------+---------------------------------------------------------+
*/
User Function fAllTec()
	Local cUserTC   := "" 
	dbSelectArea("AA1")
	AA1-&gt;(dbSetOrder(1))
	AA1-&gt;(dbGoTop())

   	Do While AA1-&gt;(!Eof()) .AND. AA1-&gt;AA1_FILIAL==xFilial("AA1") 
		If AA1-&gt;AA1_MSBLQL=='2' .and. !Empty(AA1-&gt;AA1_CODUSR)
	    	     cUserTC += ',' + AA1-&gt;AA1_CODUSR	    	
		Endif
 		AA1-&gt;(DbSkip())
   	EndDo
   	                                     
Return(cUserTC)

+------------------+---------------------------------------------------------+

!Modulo ! Diversos !

+------------------+---------------------------------------------------------+

!Nome ! fAllTec !

+------------------+---------------------------------------------------------+

!Descricao ! Função para retornar o codigo de todos os tecnicos do !

! ! sistema !

+------------------+---------------------------------------------------------+

User Function fAllTec()

Local cUserTC := ""

dbSelectArea("AA1")

AA1->(dbSetOrder(1))

AA1->(dbGoTop())

Do While AA1->(!Eof()) .AND. AA1->AA1_FILIAL==xFilial("AA1")

If AA1->AA1_MSBLQL=='2' .and. !Empty(AA1->AA1_CODUSR)

cUserTC += ',' + AA1->AA1_CODUSR

Endif

AA1->(DbSkip())

EndDo

Return(cUserTC)

Neste blog, você encontrará outros fontes, no qual poderá ir se acostumando com o ADVPL.

[section_title title=finalizando]

Resumindo…

Estrutura de um Programa

Apesar de não ser uma linguagem de padrões rígidos com relação à estrutura do programa, é importante identificar algumas de suas partes. Considere o programa de exemplo abaixo:

/*
+===========================================+
| Programa: Cálculo do Fatorial             |
| Autor   : Microsiga Software S.A.         |
| Data    : 02 de outubro de 2001           |
+===========================================+
*/
 
Local nCnt
Local nResultado := 1  // Resultado do fatorial
Local nFator     := 5 // Número para o cálculo
 
// Cálculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
 
// Exibe o resultado na tela, através da função alert
Alert("O fatorial de " + cValToChar(nFator) + ;
      " é " + cValToChar(nResultado))
 
// Termina o programa
Return

+===========================================+

| Programa: Cálculo do Fatorial |

| Autor : Microsiga Software S.A. |

| Data : 02 de outubro de 2001 |

+===========================================+

Local nCnt

Local nResultado := 1 // Resultado do fatorial

Local nFator := 5 // Número para o cálculo

// Cálculo do fatorial

For nCnt := nFator To 1 Step -1

nResultado *= nCnt

Next nCnt

// Exibe o resultado na tela, através da função alert

Alert("O fatorial de " + cValToChar(nFator) + ;

" é " + cValToChar(nResultado))

// Termina o programa

Return

Pode-se classificar um programa em AdvPl em quatro partes básicas:

Área de Identificação
Área de Ajustes Iniciais
Corpo do Programa
Área de Encerramento

A Área de Identificação

Esta é uma área que não é obrigatória e é dedicada a documentação do programa. Quando existente, contém apenas comentários explicando a sua finalidade, data de criação, autor, etc, e aparece no começo do programa, antes de qualquer linha de comando.

O formato para esta área não é definido. Pode-se colocar qualquer tipo de informação desejada e escolher a formatação apropriada.

/*
+==========================================+
| Programa: Cálculo do Fatorial            |
| Autor   : Microsiga Software S.A.        |
| Data    : 02 de outubro de 2001          |
+==========================================+
*/

+==========================================+

| Programa: Cálculo do Fatorial |

| Autor : Microsiga Software S.A. |

| Data : 02 de outubro de 2001 |

+==========================================+

Opcionalmente pode-se incluir definições de constantes utilizadas no programa ou inclusão de arquivos de cabeçalho nesta área.

A Área de Ajustes Iniciais

Nesta área geralmente se fazem os ajustes iniciais, importantes para o correto funcionamento do programa. Entre os ajustes se encontram declarações de variáveis, inicializações, abertura de arquivos, etc. Apesar do AdvPl não ser uma linguagem rígida e as variáveis poderem ser declaradas em qualquer lugar do programa, é aconselhável fazê-lo nesta área visando tornar o código mais legível e facilitar a identificação de variáveis não utilizadas.

Local nCnt
Local nResultado := 0  // Resultado do fatorial
Local nFator     := 10 // Número para o cálculo

Local nCnt

Local nResultado := 0 // Resultado do fatorial

Local nFator := 10 // Número para o cálculo

O Corpo do Programa

É nesta área que se encontram as linhas de código do programa. É onde se realiza a tarefa necessária através da organização lógica destas linhas de comando. Espera-se que as linhas de comando estejam organizadas de tal modo que no final desta área o resultado esperado seja obtido, seja ele armazenado em um arquivo ou em variáveis de memória, pronto para ser exibido ao usuário através de um relatório ou na tela.

// Cálculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt

// Cálculo do fatorial

For nCnt := nFator To 1 Step -1

nResultado *= nCnt

Next nCnt

A Área de Encerramento

É nesta área onde as finalizações são efetuadas. É onde os arquivos abertos são fechados, e o resultado da execução do programa é utilizado. Pode-se exibir o resultado armazenado em uma variável ou em um arquivo ou simplesmente finalizar, caso a tarefa já tenha sido toda completada no corpo do programa. É nesta área que se encontra o encerramento do programa. Todo programa em AdvPl deve sempre terminar com a palavra chave return.

// Exibe o resultado na tela, através da função alert
Alert("O fatorial de " + cValToChar(nFator) + ;
      " é " + cValToChar(nResultado))
 
// Termina o programa
Return

// Exibe o resultado na tela, através da função alert

Alert("O fatorial de " + cValToChar(nFator) + ;

" é " + cValToChar(nResultado))

// Termina o programa

Return

Meu primeiro fonte

Comandos

Funções

Boas Práticas

Identação do fonte

Comentários

Diretivas para o compilador

#define

#include

#ifdef

#ifndef

#undef

A Área de Identificação

A Área de Ajustes Iniciais

O Corpo do Programa

A Área de Encerramento

Categorias

Assinar blog por e-mail

Últimas atualizações

Meu primeiro fonte

Comandos

Funções

Boas Práticas

Identação do fonte

Comentários

Notação Húngara

Nomes longos

Diretivas para o compilador

#define

#include

#ifdef

#ifndef

#undef

Estrutura de um Programa

A Área de Identificação

A Área de Ajustes Iniciais

O Corpo do Programa

A Área de Encerramento

Categorias

Assinar blog por e-mail

Últimas atualizações

Tags