Introdução

O intuito desse documento é explicar o uso da linguagem de programação AdvPL, a sua estrutura, os seus comandos e as suas funções na Linha Microsiga Protheus.

Essas informações permitirão que os usuários ou profissionais de informática conheçam a linguagem AdvPL e se capacitem no desenvolvimento de programas e funcionalidades que rodarão na Linha Microsiga Protheus

 
Os capítulos estão estruturados para que o leitor incremente o seu conhecimento gradualmente.

Uma das aplicações mais frequentes e úteis dos computadores e dos sistemas de informação é o armazenamento, o controle e o processamento de bases de dados. Uma linguagem de programação permite que esses dados sejam recuperados, processados, transformados em outras informações por meio de cálculos, gravados e mostrados aos usuários por meio de consultas ou relatórios.

Um dos sistemas de informação mais utilizados atualmente nas empresas é o ERP (Enterprise Resource Planning). Por meio de um ERP, todas as áreas de uma empresa são integradas, compartilhando as suas informações e permitindo maior agilidade e precisão na geração e na transmissão de informações entre as áreas e departamentos da empresa. Por exemplo, quando a área de Faturamento emite uma Nota Fiscal, automaticamente o sistema gera os respectivos títulos à receber na área Financeira.

O AdvPL é uma linguagem de programação completa para o desenvolvimento de aplicações no ERP Protheus, desenvolvido e comercializado pela TOTVS. A sua origem é baseada nas linguagem do padrão xBase.

O AdvPL é uma linguagem muito poderosa, flexível e completa. Por meio dela, é possível desenvolver novas aplicações para a Linha Microsiga Protheus, além de adaptar alguns processos às necessidades de cada empresa.

Com o AdvPL é possível desenvolver aplicações para:

• Criar, relacionar e organizar um conjunto de dados;
• Manipular os dados por meio de operações de inclusão, alteração e exclusão. Além disso, é possível visualizá-los de forma seletiva e de acordo com as especificações dos usuários;
• Realizar operações matemáticas, lógicas e de decisão com os dados, gerando novos dados ou extraindo informações;
• Criar telas para a manutenção e a visualização dos dados pelo usuário;
• Criar relatórios para a visualização dos dados pelo usuário;
• Permitir a interação do usuário com as aplicações por meio de páginas Web e de e-mails.

Com a linguagem AdvPL é possível trabalhar com diversos bancos de dados, tanto pagos quanto gratuito, como Microsoft SQL Server, Oracle, IBM DB2, IBM Informix, Postgres, MySql, entre outros.

Variáveis

 Durante o processamento de um programa existem determinadas informações que necessitam ser armazenadas na memória do computador, para serem utilizadas à medida que as operações são executadas. Estas informações são armazenadas por meio de nomes identificadores, denominados variáveis, pois podem ter o seu conteúdo modificado durante o fluxo do processamento.

Portanto, uma variável é qualquer referência ou valor armazenado temporariamente na memória do computador por meio de um nome, e cujo conteúdo pode variar durante o processamento.

O nome da variável pode conter letras, algarismos ou o símbolo sublinhado. Pode ser formado por até 10 caracteres, sendo que o primeiro deve, obrigatoriamente, ser uma letra. Para tornar o programa mais claro e legível, uma das convenções das boas práticas de programação é iniciar o nome da variável com a letra que representa o tipo de dado que ela conterá. Essa convenção é explicada e aprofundada no item correspondente às Boas práticas de programação, contido nessa documentação.

Durante a execução de uma aplicação, é possível atribuir um mesmo nome para diferentes variáveis, desde que elas estejam em rotinas diferentes. Entretanto, recomenda-se enfaticamente que essa prática seja evitada. Caso contrário, o risco de ambiguidades dentro do programa será alto, impedindo que o compilador gere um código eficiente. Além disso, o programa poderá ficar tão confuso que, provavelmente, até o programador que o criou terá dificuldade para entendê-lo.

Para evitar ambiguidades e permitir que o compilador gere um código otimizado, referências a campos das tabelas de dados devem ser feitas explicitamente precedendo o seu nome com o operador de alias ( -> ), conforme exemplo abaixo:

// Nome do campo que armazena a quantidade do item da Nota Fiscal de Saída (Venda)
SD2->D2_QUANT

Esta sintaxe refere-se a um campo de uma tabela aberta na área de trabalho e designada pelo alias SD2.

Desta forma, qualquer ambiguidade é explicitamente evitada e uma variável poderá possuir, por exemplo, o mesmo nome de um campo de uma tabela de dados.

O AdvPL permite a definição de diferentes tipos de variáveis, conforme a natureza do dado armazenado nela. Além disso, as variáveis são organizadas em classes que determinam como a variável é armazenada, por quanto tempo ela estará ativa e onde, dentro de um programa, ela poderá ser utilizada (será visível). Cada classe de variável possui um comando específico que declara o seu nome e a cria durante a execução do programa.

Tipos de Variáveis

Com o propósito da utilização em expressões, cada dado no AdvPL é identificado como um tipo. Dessa forma, para cada variável, constante, função ou campo de tabela é associado um tipo de dado, que depende da forma como cada um destes itens foi criado. Por exemplo, o tipo de dado de uma variável depende do valor nela armazenado, o tipo de dado de uma função depende do valor por ela fornecido e o tipo de dado de um campo depende da estrutura da tabela de dados correspondente.

Os tipos de dados possíveis na linguagem AdvPL são:

• Caracter
• Memo
• Data
• Numérico
• Lógico
• NIL (ausente)
• Array
• Bloco de Código

Caracter

Quando os valores armazenados formam cadeias de tamanho fixo, compostas por dígitos numéricos (0 - 9), letras alfabéticas(a - z ou A - Z) ou símbolos especiais (@, +, *, -, /, %, $, &, etc.), trata-se de um dado do tipo caracter.

Um dado do tipo caracter é formado por uma cadeia contendo de zero à 65.535 (64 Kbytes) caracteres da tabela ASCII. O conjunto completo de dados tipo caracter do AdvPL corresponde aos códigos ASCII 0 (nulo), 32 à 126 (caracteres imprimíveis) e 128 à 255 (caracteres gráficos).

Os valores ou constantes armazenados devem ser circunscritos por um par de delimitadores (abre e fecha), que pode ser aspas (" ") ou apóstrofos (' ').

O valor vazio para esse tipo de dado é o caracter ASCII 0 (nulo). Para representá-lo deve-se utilizar dois delimitadores contíguos. Ou seja, "" ou ''.

Dados tipo caracter são ordenados de acordo com o valor do seu código da Tabela ASCII.

Exemplos de dados do tipo caracter:

"O AdvPL é uma poderosa linguagem de programação"
"A taxa de juros é de 0,99 % ao mês, condicionada ao valor mínimo de R$ 100,00 da prestação"

Memo 

Um dado tipo memo é equivalente ao dado tipo caracter. A única diferença é que um dado tipo memo não tem tamanho definido. Essa característica é possível porque os dados desse tipo são gravados em arquivos de dados.

O código que identifica o dado tipo memo é gravado no arquivo de dados proprietário da informação, como o Cadastro de Clientes, de Fornecedores, etc. Esse código identificador possui 10 posições e é responsável por identificar o conteúdo da informação gravado no arquivo de dados SYP.

No AdvPL, a função padrão MSMM() é responsável pela gravação e recuperação de dados do tipo memo.

Esse tipo de dado é importante para os casos em que a informação não pode se restringir em um determinado tamanho. Por exemplo, observações, laudos, etc.

Data

Este tipo de dado representa datas do calendário e permite a realização de várias operações com elas, como, por exemplo, a obtenção da diferença  entre duas datas, em número de dias, e a obtenção de uma nova data após a soma ou a subtração por um determinado número de dias.

Esse tipo de dado armazena os valores com 8 posições, constituídas por 8 dígitos numéricos de 0 até 9, intercalados por barras "/", no formato 99/99/9999.

Para a definição de dados tipo data é obrigatória a utilização da função CTOD(), que transforma dados tipo caracter em dados tipo data. Por exemplo:

// Trata datas no formato dia/mês/ano
dNascim := CTOD("14/05/2012")

Com exceção dos campos tipo data das tabelas de dados, a única forma de se definir um dado tipo data é por meio da função CTOD().

Tanto os formatos americano quanto brasileiro são representados da seguinte forma:

• O símbolo dd representa o dia. Dependendo do mês, deve estar entre 01 e 31.
• O símbolo mm representa o mês. Deve estar entre 01 e 12.
• O símbolo ss representa o século do ano. Deve estar entre 00 e 29.
• O símbolo aaaa representa o ano. Deve se um ano válido.

Nos Bancos de Dados, o armazenamento das datas é feito no formato texto: ssaammdd. O software de interface entre o Protheus e os Bancos de Dados, chamado de Top Connect, converte essa informação de texto para data, conforme a configuração vigente no Protheus, quando a aplicação necessita da informação.

Na Linha Microsiga Protheus, a exibição da data pode ser configurada para o formato americano, representado pelos símbolos mm/dd/aa ou mm/dd/aaaa, ou para o formato adotado no Brasil, representado por dd/mm/aa ou dd/mm/aaaa.

Como padrão, o AdvPL trabalha com datas do século XX, suprimindo a sua indicação. Isto é, a indicação do século, representada pelo símbolo ss, não é apresentada.

Para que o AdvPL os aceite, os dados do tipo data devem ser datas válidas, compreendidas entre 01/01/0100 e 31/12/2999. O valor vazio para os dados tipo data é uma data em branco ou uma data vazia, que deve ser representada pelos comandos CTOD(""), CTOD(SPACE(8)) ou CTOD("  /  /  "). A função CTOD aceita somente datas válidas como argumento. Caso seja apresentada uma data inválida como argumento, o comando a converterá numa data nula.

Exemplos de datas inválidas:

• 32/12/2012
• 23/13/2012
• 23/12/0099
• 29/02/2012

Numérico

Quando um dado possui na sua composição somente algarismos numéricos de 0 até 9, os sinais + (mais) ou - (menos) e o ponto decimal, ele é do tipo numérico. Este tipo de dado destina-se à realização de cálculos matemáticos.

Por meio deste tipo de dado, o AdvPL é capaz de processar valores numéricos entre 10^-308 e 10³⁰⁸. Um arquivo de dados pode armazenardados numéricos com no máximo 32 posições (30 algarismos numéricos, o sinal + ou - e o ponto decimal), com até 16 casas decimais de precisão garantida. Portanto, podemos ter um número com 32 posições inteiras, sem casas decimais, até um número com 15 posições inteiras, o ponto decimal e 16 casas decimais.

Um dado numérico não pode ser delimitado por nenhum símbolo. Caso contrário, será considerado caracter. O valor vazio ou nulo para um dado numérico é o valor zero ( 0 ).

O valor numérico no AdvPL segue o formato americano: o ponto decimal é representado pelo ponto ( . ) e a separação dos valores inteiros pela vírgula ( , ). Segue alguns exemplos baseados em valores monetários:

• 43.53 (quarenta e três reais e cinquenta e três centavos)
• 0.05 (cinco centavos)
• 1,000,000.00 (um milhão)
• 1.815 (um real e oitocentos e quinze milésimos)

Porém, no momento de exibir a informação para o usuário, seja na tela ou em relatório, é possível converter o valor numérico para o formato adotado no Brasil, onde o ponto decimal é representado pela vírgula ( , ) e a separação dos valores inteiros pelo ponto ( . ). Vejamos os mesmos exemplos acima no formato adotado no Brasil:

• 43,53 (quarenta e três reais e cinquenta e três centavos)
• 0,05 (cinco centavos)
• 1.000.000,00 (um milhão)
• 1,815 (um real e oitocentos e quinze milésimos)

Lógico

Um dado do tipo lógico representa apenas dois estados possíveis, chamados de valores booleanos: falso ou verdadeiro. O seu conteúdo poderá ser apenas:

• .T. ou .t. (True ou Verdadeiro)
• .F. ou .f. (False ou Falso)

Os dados lógicos são, obrigatoriamente, delimitados por pontos, que equivalem aos delimitadores dos dados tipo caracter. Por exemplo:

• lRetorno := .T.  // Verdadeiro
• lRetorno := .F.  // Falso

NIL ou valores nulos

O tipo NIL permite a manipulação de variáveis declaradas, mas não iniciadas com a atribuição de algum valor. A representação deste tipo de dado é a sigla NIL, sem delimitadores.

Pode-se interpretar NIL como sendo ausência de dado, pois quando um valor não for atribuído para uma variável, array, elemento de array ou parâmetro esperado de uma função, o AdvPL automaticamente atribuirá o valor NIL.

A única classe de variáveis para a qual não se pode atribuir o valor NIL são os campos das tabelas de dados.

Array e Vetores

No AdvPL, matrizes e vetores podem ser considerados como um tipo de dado porque uma referência a uma matriz pode ser atribuída a uma variável, fornecida por uma função ou passada como argumento. Uma referência é um endereço da memória do computador no qual se localiza uma matriz. Devido às suas particularidades, trataremos esse tipo de dado mais adiante em um capitulo especifico.

Bloco de Código

São trechos de código compilado que, assim como os arrays, podem ser considerados como um tipo de dado porque uma referência a um bloco de código pode ser atribuída a uma variável, fornecida por uma função ou passada como argumento. Uma referência é um endereço da memória do computador no qual se localiza um bloco de código. Devido às suas particularidades, trataremos esse tipo de dado mais adiante em um capitulo especifico.