Programação Advpl2 p10 2009

Todos os direitos reservados.
0800 709 8100

totvs.com

P
PR RO OG GR RA AM MA A O O
A
A
D
D
V
V
P
P
L
L I
I
I
I

Todos os direitos reservados. 0800 709 8100
totvs.com

1. OBJETIVOS DO CURSO........................................................................................ 6
2. MDULO 04: DESENVOLVENDO APLICAES EM ADVPL................................... 7
3. A LINGUAGEM ADVPL....................................................................................... 7
4. ESTRUTURA DE UM PROGRAMA ADVPL ............................................................. 9
2.1 reas de um Programa ADVPL.............................................................................. 12
5. DECLARAO E ATRIBUIO DE VARIVEIS ....................................................... 15
2.2 Tipo de Dados.............................................................................................................. 15
2.3 Declarao de variveis............................................................................................ 16
2.4 Escopo de variveis.................................................................................................... 17
2.5 Entendendo a influncia do escopo das variveis ......................................... 23
6. REGRAS ADICIONAIS DA LINGUAGEM ADVPL.................................................... 24
2.6 Palavras reservadas.................................................................................................... 24
2.7 Pictures de formatao disponveis..................................................................... 25
7. PROGRAMAS DE ATUALIZAO......................................................................... 26
2.8 Modelo1() ou AxCadastro()..................................................................................... 27
2.9 Mbrowse()...................................................................................................................... 30
2.9.1 AxFunctions()................................................................................................................ 37
2.9.2 FilBrowse() ..................................................................................................................... 39
2.9.3 EndFilBrw()..................................................................................................................... 39
2.9.4 PesqBrw() ....................................................................................................................... 40
2.9.5 BrwLegenda () .............................................................................................................. 40
2.10 MarkBrowse() ............................................................................................................... 44
2.10.1 Funes de Apoio....................................................................................................... 45
2.11 Modelo2() ...................................................................................................................... 50
2.11.1 Componentes de uma tela no formato Modelo 2......................................... 50
2.11.2 Estrutura de um programa utilizando a Modelo2()....................................... 58
2.11.3 Funo Modelo2() ...................................................................................................... 73
2.12 Modelo3() ...................................................................................................................... 77
2.12.1 Estrutura de um programa utilizando a Modelo3()....................................... 81
2.12.2 Funo Modelo3() ...................................................................................................... 92
8. ARQUIVOS E NDICES TEMPORRIOS ................................................................. 97
Programao ADVPL II e Guia de Referncia Pgina 3
2.13 Utilizao de arquivos e ndices temporrios.................................................. 97
2.14 Funes para manipulao de arquivos e ndices temporrios................ 97
2.14.1 CriaTrab() ....................................................................................................................... 97
2.14.2 dbUseArea() .................................................................................................................. 97
2.14.3 IndRegua() ..................................................................................................................... 98
2.15 Funes Auxiliares para Arquivos de Trabalho e Temporrios ................. 99
9. RELATRIOS NO GRFICOS ........................................................................... 103
2.16 Funes Utilizadas para Desenvolvimento de Relatrios..........................103
2.16.1 SetPrint() ......................................................................................................................103
2.16.2 SetDefault() .................................................................................................................104
2.16.3 RptStatus()...................................................................................................................105
2.16.4 CABEC().........................................................................................................................106
2.16.5 RODA() ..........................................................................................................................107
2.16.6 Pergunte()....................................................................................................................107
2.16.7 AjustaSX1() ..................................................................................................................107
2.16.8 PutSX1() ........................................................................................................................109
2.17 Estrutura de Relatrios Baseados na SetPrint() .............................................111
10. MANIPULAO DE ARQUIVOS I ....................................................................... 123
2.18 Gerao e leitura de arquivos em formato texto .........................................123
2.18.1 1 Famlia de funes de gravao e leitura de arquivos texto..............124
2.18.2 2 Famlia de funes de gravao e leitura de arquivos texto..............136
11. OFICINA DE PROGRAMAO I ......................................................................... 142
2.19 Interfaces com sintaxe clssica............................................................................142
2.20 Rguas de processamento....................................................................................146
2.20.1 RptStatus()...................................................................................................................146
2.20.2 Processa().....................................................................................................................151
2.20.3 MsNewProcess(). .......................................................................................................155
2.20.4 MsAguarde(). ..............................................................................................................159
2.20.5 MsgRun()......................................................................................................................161
2.21 ListBox() ........................................................................................................................164
2.21.1 ListBox simples ..........................................................................................................164
2.21.2 ListBox mltiplas colunas.......................................................................................167
2.22 ScrollBox()....................................................................................................................171
2.23 ParamBox() ..................................................................................................................176
MDULO 05: INTRODUO A ORIENTAO OBJETOS.......................................... 184
Pgina 4 Programao ADVPL II e Guia de Referncia
12. CONCEITOS DE ORIENTAO OBJETOS .......................................................... 184
2.24 Definies.................................................................................................................... 184
2.25 Conceitos Bsicos..................................................................................................... 187
2.26 O Modelo de Objetos (OMT)............................................................................... 189
2.26.1 Objetos e Classes ..................................................................................................... 189
2.26.2 Atributos...................................................................................................................... 190
2.26.3 Operaes e Mtodos............................................................................................ 191
2.26.4 Sugestes de desenvolvimento.......................................................................... 192
13. ORIENTAO A OBJETOS EM ADVPL .............................................................. 193
2.27 Sintaxe e operadores para orientao a objetos ......................................... 193
2.28 Estrutura de uma classe de objetos em ADVPL............................................ 196
2.29 Implementao dos mtodos de uma classe em ADVPL ......................... 197
MDULO 06: ADVPL ORIENTADO OBJETOS I .................................................... 203
14. COMPONENTES DA INTERFACE VISUAL DO ADVPL........................................... 203
2.30 Particularidades dos componentes visuais..................................................... 211
2.30.1 Configurando as cores para os componentes .............................................. 211
15. APLICAES COM A INTERFACE VISUAL DO ADVPL.......................................... 212
2.31 Captura de informaes simples (Multi-Gets) .............................................. 213
2.31.1 Enchoice().................................................................................................................... 214
2.31.2 MsMGet()..................................................................................................................... 216
2.32 Captura de mltiplas informaes (Multi-Lines) .......................................... 219
2.32.1 MsGetDB()................................................................................................................... 220
2.32.2 MsGetDados()............................................................................................................ 225
2.32.3 MsNewGetDados()................................................................................................... 230
2.33 Barras de botes....................................................................................................... 242
2.33.1 EnchoiceBar() ............................................................................................................. 243
2.33.2 TBar()............................................................................................................................. 245
2.33.3 ButtonBar .................................................................................................................... 247
2.33.4 Imagens pr-definidas para as barras de botes ........................................ 251
APNDICE.............................................................................................................. 252
BOAS PRTICAS DE PROGRAMAO ....................................................................... 252
16. ARREDONDAMENTO....................................................................................... 252
17. UTILIZAO DE IDENTAO............................................................................ 253
18. CAPITULAO DE PALAVRAS-CHAVE............................................................... 254
2.34 Palavras em maisculo........................................................................................... 255
19. UTILIZAO DA NOTAO HNGARA............................................................. 256
20. TCNICAS DE PROGRAMAO EFICIENTE .......................................................... 256
GUIA DE REFERNCIA RPIDA: FUNES E COMANDOS ADVPL........................ 269
Converso entre tipos de dados ............................................................................................ 269
Matemticas................................................................................................................................... 272
Anlise de variveis ..................................................................................................................... 276
Manipulao de arrays............................................................................................................... 277
Manipulao de blocos de cdigo........................................................................................ 288
Manipulao de strings ............................................................................................................. 291
Manipulao de data / hora .................................................................................................... 306
Manipulao de variveis numricas.................................................................................... 314
Manipulao de arquivos.......................................................................................................... 318
Manipulao de arquivos e ndices temporrios............................................................. 350
Manipulao de bases de dados............................................................................................ 352
Controle de numerao seqencial ...................................................................................... 400
Validao 401
Manipulao de parmetros do sistema............................................................................. 404
Controle de impresso............................................................................................................... 407
Controle de processamentos................................................................................................... 421
Utilizao de recursos do ambiente ERP............................................................................. 434
Componentes da interface visual........................................................................................... 465
Interfaces de cadastro................................................................................................................ 473
Interfaces visuais para aplicaes .......................................................................................... 477
Recursos das interfaces visuais............................................................................................... 480


1. Objetivos do Curso

Objetivos especficos do curso:

Ao final do curso o treinando dever ter desenvolvido os seguintes conceitos,
habilidades e atitudes:

a) Conceitos a serem aprendidos

estruturas para implementao de relatrios e programas de atualizao
estruturas para implementao de interfaces visuais
princpios do desenvolvimento de aplicaes orientadas a objetos

b) Habilidades e tcnicas a serem aprendidas

desenvolvimento de aplicaes voltadas ao ERP Protheus
anlise de fontes de mdia complexidade
desenvolvimento de aplicaes bsicas com orientao a objetos

c) Atitudes a serem desenvolvidas

adquirir conhecimentos atravs da anlise dos funcionalidades
disponveis no ERP Protheus;
estudar a implementao de fontes com estruturas orientadas a objetos
em ADVPL;
embasar a realizao de outros cursos relativos a linguagem ADVPL


2. MDULO 04: Desenvolvendo aplicaes em ADVPL

3. A linguagem ADVPL
A Linguagem ADVPL teve seu incio em 1994, sendo na verdade uma evoluo na
utilizao de linguagens no padro xBase pela Microsiga Software S.A. (Clipper, Visual
Objects e depois FiveWin). Com a criao da tecnologia Protheus, era necessrio criar
uma linguagem que suportasse o padro xBase para a manuteno de todo o cdigo
existente do sistema de ERP Siga Advanced. Foi, ento, criada a linguagem chamada
Advanced Protheus Language.

O ADVPL uma extenso do padro xBase de comandos e funes, operadores,
estruturas de controle de fluxo e palavras reservadas, contando tambm com funes e
comandos disponibilizados pela Microsiga que a torna uma linguagem completa para a
criao de aplicaes ERP prontas para a Internet. Tambm uma linguagem orientada
a objetos e eventos, permitindo ao programador desenvolver aplicaes visuais e criar
suas prprias classes de objetos.

Quando compilados, todos os arquivos de cdigo tornam-se unidades de inteligncia
bsicas, chamados APOs (de Advanced Protheus Objects). Tais APOs so mantidos em
um repositrio e carregados dinamicamente pelo PROTHEUS Server para a execuo.
Como no existe a linkedio, ou unio fsica do cdigo compilado a um determinado
mdulo ou aplicao, funes criadas em ADVPL podem ser executadas em qualquer
ponto do ambiente Advanced Protheus.

O compilador e o interpretador da linguagem ADVPL o prprio servidor PROTHEUS
(PROTHEUS Server), e existe um ambiente visual para desenvolvimento integrado
(PROTHEUSIDE) onde o cdigo pode ser criado, compilado e depurado.

Os programas em ADVPL podem conter comandos ou funes de interface com o
usurio. De acordo com tal caracterstica, tais programas so subdivididos nas
seguintes categorias:

Programao Com Interface Prpria com o Usurio

Nesta categoria entram os programas desenvolvidos para serem executados atravs do
terminal remoto do Protheus: o Protheus Remote. O Protheus Remote a aplicao
encarregada da interface e da interao com o usurio, sendo que todo o
processamento do cdigo em ADVPL, o acesso ao banco de dados e o gerenciamento
de conexes efetuado no Protheus Server. O Protheus Remote o principal meio de
acesso a execuo de rotinas escritas em ADVPL no Protheus Server, e por isso permite
executar qualquer tipo de cdigo, tenha ele interface com o usurio ou no. Porm,
nesta categoria, so considerados apenas os programas que realizam algum tipo de
interface remota utilizando o protocolo de comunicao do Protheus.

Podem-se criar rotinas para a customizao do sistema ERP Microsiga Protheus, desde
processos adicionais at relatrios. A grande vantagem aproveitar todo o ambiente
montado pelos mdulos do ERP Microsiga Protheus. Porm, com o ADVPL, possvel
at mesmo criar toda uma aplicao, ou mdulo, desde o comeo.

Todo o cdigo do sistema ERP Microsiga Protheus escrito em ADVPL.

Programao Sem Interface Prpria com o Usurio

As rotinas criadas sem interface so consideradas nesta categoria porque geralmente
tm uma utilizao mais especfica do que um processo adicional ou um relatrio novo.
Tais rotinas no tm interface com o usurio atravs do Protheus Remote, e qualquer
tentativa nesse sentido (como a criao de uma janela padro) ocasionar uma exceo
em tempo de execuo. Estas rotinas so apenas processos, ou Jobs, executados no
Protheus Server. Algumas vezes, a interface destas rotinas fica a cargo de aplicaes
externas, desenvolvidas em outras linguagens, que so responsveis por iniciar os
processos no servidor Protheus atravs dos meios disponveis de integrao e
conectividade no Protheus.

De acordo com a utilizao e com o meio de conectividade utilizado, estas rotinas so
subcategorizadas assim:

E Programao por Processos

Rotinas escritas em ADVPL podem ser iniciadas como processos individuais (sem
interface) no Protheus Server atravs de duas maneiras: Iniciadas por outra rotina
ADVPL atravs da chamada de funes como StartJob() ou CallProc() ou iniciadas
automaticamente na inicializao do Protheus Server (quando propriamente
configurado).

E Programao de RPC

Atravs de uma biblioteca de funes disponvel no Protheus (uma API de
comunicao), podem-se executar rotinas escritas em ADVPL diretamente no Protheus
Server, atravs de aplicaes externas escritas em outras linguagens. Isto o que se
chama de RPC (de Remote Procedure Call, ou Chamada de Procedimentos Remota).

O servidor Protheus tambm pode executar rotinas em ADVPL em outros servidores
Protheus atravs de conexo TCP/IP direta, utilizando o conceito de RPC. Do mesmo
modo, aplicaes externas podem requisitar a execuo de rotinas escritas em ADVPL
atravs de conexo TCP/IP direta.

E Programao Web

O Protheus Server pode tambm ser executado como um servidor Web, respondendo a
requisies HTTP. No momento destas requisies, pode executar rotinas escritas em
ADVPL como processos individuais, enviando o resultado das funes como retorno
das requisies para o cliente HTTP (como por exemplo, um Browser de Internet).
Qualquer rotina escrita em ADVPL que no contenha comandos de interface pode ser
executada atravs de requisies HTTP. O Protheus permite a compilao de arquivos
HTML contendo cdigo ADVPL embutido. So os chamados arquivos ADVPL ASP, para
a criao de pginas dinmicas.

E Programao TelNet

TelNet parte da gama de protocolos TCP/IP que permite a conexo a um computador
remoto atravs de uma aplicao cliente deste protocolo. O PROTHEUS Server pode
emular um terminal TelNet, atravs da execuo de rotinas escritas em ADVPL. Ou seja,
pode-se escrever rotinas ADVPL cuja interface final ser um terminal TelNet ou um
coletor de dados mvel.

4. Estrutura de um Programa ADVPL

Um programa de computador nada mais do que um grupo de comandos
logicamente dispostos com o objetivo de executar determinada tarefa. Esses comandos
so gravados em um arquivo texto que transformado em uma linguagem executvel
por um computador atravs de um processo chamado compilao. A compilao
substitui os comandos de alto nvel (que os humanos compreendem) por instrues de
baixo nvel (compreendida pelo sistema operacional em execuo no computador). No
caso do ADVPL, no o sistema operacional de um computador que ir executar o
cdigo compilado, mas sim, o Protheus Server.

Dentro de um programa, os comandos e funes utilizados devem seguir regras de
sintaxe da linguagem utilizada. Caso contrrio, o programa ser interrompido por erros.
Os erros podem ser de compilao ou de execuo.

Erros de compilao so aqueles encontrados na sintaxe que no permitem que o
arquivo de cdigo do programa seja compilado. Podem ser comandos especificados de
forma errnea, utilizao invlida de operadores, etc..

Erros de execuo so aqueles que acontecem depois da compilao, quando o
programa est sendo executado. Podem ocorrer por inmeras razes, mas geralmente
se referem s funes no existentes, ou variveis no criadas ou inicializadas, etc..

Linhas de Programa

As linhas existentes dentro de um arquivo texto de cdigo de programa podem ser
linhas de comando, linhas de comentrio ou linhas mistas.

E Linhas de Comando

Linhas de comando possuem os comandos ou instrues que sero executadas. Por
exemplo:

Local nCnt
Local nSoma := 0
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt

E Linhas de Comentrio

Linhas de comentrio possuem um texto qualquer, mas no so executadas. Servem
apenas para documentao e para tornar mais fcil o entendimento do programa.
Existem trs formas de se comentar linhas de texto. A primeira delas utilizar o sinal de
* (asterisco) no comeo da linha:

* Programa para clculo do total
* Autor: Microsiga Software S.A.
* Data: 2 de outubro de 2001
Todas as linhas iniciadas com um sinal de asterisco so consideradas como comentrio.
Pode-se utilizar a palavra NOTE ou dois smbolos da letra "e" comercial (&&) para
realizar a funo do sinal de asterisco. Porm, todas estas formas de comentrio de
linhas so obsoletas e existem apenas para compatibilizao com o padro xBase. A
melhor maneira de comentar linhas em ADVPL utilizar duas barras transversais:

// Programa para clculo do total
// Autor: Microsiga Software S.A.
// Data: 2 de outubro de 2001

Outra forma de documentar textos utilizar as barras transversais juntamente com o
asterisco, podendo-se comentar todo um bloco de texto sem precisar comentar linha a
linha:

/*
Programa para clculo do total
Autor: Microsiga Software S.A.
Data: 2 de outubro de 2001
*/

Todo o texto encontrado entre a abertura (indicada pelos caracteres /*) e o fechamento
(indicada pelos caracteres */) considerado como comentrio.

E Linhas Mistas

O ADVPL tambm permite que existam linhas de comando com comentrio. Isto
possvel adicionando-se as duas barras transversais (//) ao final da linha de comando e
adicionando-se o texto do comentrio:

Local nCnt
Local nSoma := 0 // Inicializa a varivel com zero para a soma
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt

E Tamanho da Linha

Assim como a linha fsica, delimitada pela quantidade de caracteres que pode ser
digitado no editor de textos utilizado, existe uma linha considerada linha lgica. A linha
lgica, aquela considerada para a compilao como uma nica linha de comando.

A princpio, cada linha digitada no arquivo texto diferenciada aps o pressionamento
da tecla <Enter>. Ou seja, a linha lgica, a linha fsica no arquivo. Porm, algumas
vezes, por limitao fsica do editor de texto ou por esttica, pode-se "quebrar" a linha
lgica em mais de uma linha fsica no arquivo texto. Isto efetuado utilizando-se o
sinal de ponto-e-vrgula (;).

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

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

Endif

Neste exemplo existe uma linha de comando para a checagem das variveis utilizadas.
Como a linha torna-se muito grande, pode-se divid-la em mais de uma linha fsica
utilizando o sinal de ponto-e-vrgula. Se um sinal de ponto-e-vrgula for esquecido nas
duas primeiras linhas, durante a execuo do programa ocorrer um erro, pois a
segunda linha fsica ser considerada como uma segunda linha de comando na
compilao. E durante a execuo esta linha no ter sentido.

2.1 reas de um Programa ADVPL

Apesar de no ser uma linguagem de padres rgidos com relao estrutura do
programa, importante identificar algumas de suas partes. Considere o programa de
exemplo abaixo:

#include protheus.ch

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

User Function CalcFator()

Local nCnt
Local nResultado := 1 // Resultado do fatorial
Local nFator := 5 // Nmero para o clculo

// Clculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt

// Exibe o resultado na tela, atravs da funo alert
Alert("O fatorial de " + cValToChar(nFator) + ;
" " + cValToChar(nResultado))

// Termina o programa
Return

A estrutura de um programa ADVPL composta pelas seguintes reas:

E rea de Identificao
- Declarao dos includes
- Declarao da funo
- Identificao do programa

E rea de Ajustes Iniciais
- Declarao das variveis

E Corpo do Programa
- Preparao para o processamento
- Processamento

E rea de Encerramento

rea de Identificao

Esta uma rea que no obrigatria e dedicada documentao do programa.
Quando existente, contm apenas comentrios explicando a sua finalidade, data de
criao, autor, etc., e aparece no comeo do programa, antes de qualquer linha de
comando.

O formato para esta rea no definido. Pode-se colocar qualquer tipo de informao
desejada e escolher a formatao apropriada.


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

User Function CalcFator()

Opcionalmente podem-se incluir definies de constantes utilizadas no programa ou
incluso de arquivos de cabealho nesta rea.

rea de Ajustes Iniciais

Nesta rea geralmente se fazem os ajustes iniciais, importantes para o correto
funcionamento do programa. Entre os ajustes se encontram declaraes de variveis,
inicializaes, abertura de arquivos, etc.. Apesar do ADVPL no ser uma linguagem
rgida e as variveis poderem ser declaradas em qualquer lugar do programa,
aconselhvel faz-lo nesta rea visando tornar o cdigo mais legvel e facilitar a
identificao de variveis no utilizadas.

Local nCnt
Local nResultado := 0 // Resultado do fatorial
Local nFator := 10 // Nmero para o clculo

Corpo do Programa

nesta rea que se encontram as linhas de cdigo do programa. onde se realiza a
tarefa necessria atravs da organizao lgica 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 variveis de
memria, pronto para ser exibido ao usurio atravs de um relatrio ou na tela.

nResultado *= nCnt
Next nCnt

A preparao para o processamento formada pelo conjunto de validaes e
processamentos necessrios antes da realizao do processamento em si.

Avaliando o processamento do clculo do fatorial descrito anteriormente, pode-se
definir que a validao inicial a ser realizada o contedo da varivel nFator, pois a
mesma determinar a correta execuo do cdigo.

nFator := GetFator()
// GetFator funo ilustrativa na qual a varivel recebe a informao do usurio.

If nFator <= 0
Alert(Informao invlida)
Return
Endif

nResultado *= nCnt
Next nCnt

rea de Encerramento

nesta rea que as finalizaes so efetuadas. onde os arquivos abertos so
fechados, e o resultado da execuo do programa utilizado. Pode-se exibir o
resultado armazenado em uma varivel 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, atravs da funo alert
Alert("O fatorial de " + cValToChar(nFator) + ;
" " + cValToChar(nResultado))

// Termina o programa
Return

5. Declarao e Atribuio de Variveis

2.2 Tipo de Dados

O ADVPL no uma linguagem de tipos rgidos (strongly typed), o que significa que
variveis de memria podem receber diferentes tipos de dados durante a execuo do
programa.

As variveis podem tambm conter objetos, mas os tipos primrios da linguagem so:

Numrico

O ADVPL no diferencia valores inteiros de valores com ponto flutuante, portanto
podem-se criar variveis numricas com qualquer valor dentro do intervalo permitido.
Os seguintes elementos so do tipo de dado numrico:

2
43.53
0.5
0.00001
1000000

Uma varivel do tipo de dado numrico pode conter um nmero de dezoito dgitos
incluindo o ponto flutuante, no intervalo de 2.2250738585072014 E308 at
1.7976931348623158 E+308.

Lgico

Valores lgicos em ADVPL so identificados atravs de .T. ou .Y. para verdadeiro e .F. ou
.N. para falso (independentemente se os caracteres estiverem em maisculo ou
minsculo).

Caractere

Strings ou cadeias de caracteres so identificadas em ADVPL por blocos de texto entre
aspas duplas (") ou aspas simples ('):

"Ol mundo!"
'Esta uma string'
"Esta 'outra' string"

Uma varivel do tipo caractere pode conter strings com no mximo 1 MB, ou seja,
1048576 caracteres.

Data

O ADVPL tem um tipo de dados especfico para datas. Internamente as variveis deste
tipo de dado so armazenadas como um nmero correspondente data Juliana.

Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim atravs
da utilizao de funes especficas, como, por exemplo, CTOD() que converte uma
string para data.

Array

O Array um tipo de dado especial. a disposio de outros elementos em colunas e
linhas. O ADVPL suporta arrays unidimensionais (vetores) ou multidimensionais
(matrizes). Os elementos de um array so acessados atravs de ndices numricos
iniciados em 1, identificando a linha e a coluna para quantas dimenses existirem.

Arrays devem ser utilizadas com cautela, pois se forem muito grandes podem exaurir a
memria do servidor.

Bloco de Cdigo

O bloco de cdigo um tipo de dado especial. utilizado para armazenar instrues
escritas em ADVPL que podero ser executadas posteriormente.

2.3 Declarao de variveis

Variveis de memria so um dos recursos mais importantes de uma linguagem. So
reas de memria criadas para armazenar informaes utilizadas por um programa
para a execuo de tarefas. Por exemplo, quando o usurio digita uma informao
qualquer, como o nome de um produto, em uma tela de um programa esta informao
armazenada em uma varivel de memria para posteriormente ser gravada ou
impressa.

A partir do momento que uma varivel criada, deixa de ser necessrio se referenciar
ao seu contedo, sendo o nome a referncia principal.

O nome de uma varivel um identificador nico o qual deve respeitar um mximo de
10 caracteres. O ADVPL no impede a criao de uma varivel de memria cujo nome
contenha mais de 10 caracteres. Porm, apenas os 10 primeiros sero considerados
para a localizao do contedo armazenado.

Portanto, se forem criadas duas variveis cujos 10 primeiros caracteres forem iguais,
como nTotalGeralAnual e nTotalGeralMensal, as referncias a qualquer uma delas no
programa resultaro o mesmo, ou seja, sero a mesma varivel:

nTotalGeralMensal := 100
nTotalGeralAnual := 300
Alert("Valor mensal: " + cValToChar(nTotalGeralMensal))

Quando o contedo da varivel nTotalGeralMensal exibido, o seu valor ser de 300.
Isso acontece porque, no momento que esse valor foi atribudo varivel
nTotalGeralAnual, o ADVPL considerou apenas os 10 primeiros caracteres (assim como
o faz quando deve exibir o valor da varivel nTotalGeralMensal), ou seja, considerou-as
como a mesma varivel. Assim o valor original de 100 foi substitudo pelo de 300.

2.4 Escopo de variveis

O ADVPL no uma linguagem de tipos rgidos para variveis, ou seja, no
necessrio informar o tipo de dados que determinada varivel ir conter no momento
de sua declarao, e o seu valor pode mudar durante a execuo do programa.

Tambm no h necessidade de declarar variveis em uma seo especfica do seu
cdigo fonte, embora seja aconselhvel declarar todas as variveis necessrias no
comeo, tornando a manuteno mais fcil e evitando a declarao de variveis
desnecessrias.

Para declarar uma varivel deve-se utilizar um identificador de escopo, que uma
palavra chave que indica a que contexto do programa a varivel declarada pertence. O
contexto de variveis pode ser local (visualizadas apenas dentro do programa atual),
pblico (visualizadas por qualquer outro programa), entre outros.

O Contexto de Variveis dentro de um Programa

As variveis declaradas em um programa ou funo, so visveis de acordo com o
escopo onde so definidas. Como, tambm, do escopo depende o tempo de existncia
das variveis. A definio do escopo de uma varivel efetuada no momento de sua
declarao.

Local nNumero := 10

Esta linha de cdigo declara uma varivel chamada nNumero indicando que pertence
ao escopo Local.

Os identificadores de escopo so:

E Local
E Static
E Private
E Public

O ADVPL no rgido em relao declarao de variveis no comeo do programa. A
incluso de um identificador de escopo no necessria para a declarao de uma
varivel, contanto que um valor lhe seja atribudo.

nNumero2 := 15

Quando um valor atribudo uma varivel em um programa ou funo, o ADVPL
criar a varivel caso ela no tenha sido declarada anteriormente. A varivel ento
criada como se tivesse sido declarada como Private.

Devido a essa caracterstica, quando se pretende fazer uma atribuio a uma varivel
declarada previamente, mas, escreve-se o nome da varivel de forma incorreta, o
ADVPL no gerar nenhum erro de compilao ou de execuo. Pois, compreender o
nome da varivel escrito de forma incorreta como se fosse a criao de uma nova
varivel. Isto alterar a lgica do programa, e um erro muitas vezes difcil de
identificar.

Variveis de escopo local

Variveis de escopo local so pertencentes apenas ao escopo da funo onde foram
declaradas e devem ser explicitamente declaradas com o identificador LOCAL, como no
exemplo:

Function Pai()
Local nVar := 10, aMatriz := {0,1,2,3}
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)

Neste exemplo, a varivel nVar foi declarada como local e atribuda com o valor 10.
Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada.
Quando a execuo da funo Pai terminar, a varivel nVar destruda. Qualquer
varivel com o mesmo nome no programa que chamou a funo Pai no afetada.

Variveis de escopo local so criadas automaticamente cada vez que a funo onde
forem declaradas for ativada. Elas continuam a existir e mantm seu valor at o fim da
ativao da funo (ou seja, at que a funo retorne o controle para o cdigo que a
executou). Se uma funo chamada recursivamente (por exemplo, chama-se a si
mesma), cada chamada em recurso cria um novo conjunto de variveis locais.

A visibilidade de variveis de escopo locais idntica ao escopo de sua declarao, ou
seja, a varivel visvel em qualquer lugar do cdigo fonte em que foi declarada. Se
uma funo chamada recursivamente, apenas as variveis de escopo local, criadas na
mais recente ativao, so visveis.

Variveis de escopo static

Variveis de escopo static funcionam basicamente como as variveis de escopo local.
Mas, mantm seu valor atravs da execuo e devem ser declaradas explicitamente no
cdigo com o identificador STATIC.

O escopo das variveis static depende de onde so declaradas. Se forem declaradas
dentro do corpo de uma funo ou procedimento, seu escopo ser limitado quela
rotina. Se forem declaradas fora do corpo de qualquer rotina, seu escopo afeta a todas
as funes declaradas no fonte. Neste exemplo, a varivel nVar declarada como static
e inicializada com o valor 10:

Function Pai()
Static nVar := 10
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)

Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada.
Diferente de variveis declaradas como LOCAL ou PRIVATE, nVar continua a existir e
mantm seu valor atual quando a execuo da funo Pai termina. Entretanto, somente
pode ser acessada por execues subseqentes da funo Pai.

Variveis de escopo private

A declarao opcional para variveis privadas. Mas podem ser declaradas
explicitamente com o identificador PRIVATE.

Adicionalmente, a atribuio de valor a uma varivel no criada anteriormente
automaticamente cria a varivel como privada. Uma vez criada, uma varivel privada
continua a existir e mantm seu valor at que o programa ou funo onde foi criada
termine (ou seja, at que a funo onde foi criada retorne para o cdigo que a
executou). Neste momento, automaticamente destruda.

possvel criar uma nova varivel privada com o mesmo nome de uma varivel j
existente. Entretanto, a nova (duplicada) varivel pode apenas ser criada em um nvel
de ativao inferior ao nvel onde a varivel foi declarada pela primeira vez (ou seja,
apenas em uma funo chamada pela funo onde a varivel j havia sido criada). A
nova varivel privada ir esconder qualquer outra varivel privada ou pblica (veja a
documentao sobre variveis pblicas) com o mesmo nome enquanto existir.

Uma vez criada, uma varivel privada visvel em todo o programa, enquanto no for
destruda automaticamente. Quando a rotina que a criou terminar ou uma outra
varivel privada com o mesmo nome for criada em uma subfuno chamada (neste
caso, a varivel existente torna-se inacessvel at que a nova varivel privada seja
destruda).
Em termos mais simples, uma varivel privada visvel dentro da funo de criao e
todas as funes chamadas por esta, a menos que uma funo chamada crie sua
prpria varivel privada com o mesmo nome.

Por exemplo:

Function Pai()
Private nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)

Neste exemplo, a varivel nVar criada com escopo private e inicializada com o valor
10. Quando a funo Filha executada, nVar ainda existe e, diferentemente de uma
varivel de escopo local, pode ser acessada pela funo Filha. Quando a funo Pai
terminar, nVar ser destruda e qualquer declarao de nVar anterior se tornar
acessvel novamente.


No ambiente ERP Protheus, existe uma conveno adicional a qual
deve ser respeitada que variveis em uso pela aplicao no sejam
incorretamente manipuladas. Por esta conveno deve ser adicionado
o caracter _ antes do nome de variveis PRIVATE e PUBLIC. Maiores
informaes avaliar o tpico: Boas Prticas de Programao.

Exemplo: Private _dData

Variveis de escopo public

Podem-se criar variveis de escopo public dinamicamente no cdigo com o
identificador PUBLIC. As variveis deste escopo continuam a existir e mantm seu valor
at o fim da execuo da thread (conexo).

possvel criar uma varivel de escopo private com o mesmo nome de uma varivel de
escopo public existente. Entretanto, no permitido criar uma varivel de escopo
public com o mesmo nome de uma varivel de escopo private existente.

Uma vez criada, uma varivel de escopo public visvel em todo o programa onde foi
declarada at que seja escondida por uma varivel de escopo private criada com o
mesmo nome. A nova varivel de escopo private criada mascara a varivel de escopo
public existente, e esta se tornar inacessvel at que a nova varivel private seja
destruda.

Por exemplo:

Function Pai()
Public nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)

Neste exemplo, nVar criada como public e inicializada com o valor 10. Quando a
funo Filha executada, nVar ainda existe e pode ser acessada. Diferentemente de
variveis locais ou privates, nVar ainda existe aps o trmino da a execuo da funo
Pai.

Diferentemente dos outros identificadores de escopo, quando uma varivel declarada
como pblica sem ser inicializada, o valor assumido falso (.F.) e no nulo (nil).


No ambiente ERP Protheus, existe uma conveno adicional deve ser
respeitada que determina que variveis em uso pela aplicao no
sejam incorretamente manipuladas. Por esta conveno, deve ser
adicionado o caracter _ antes do nome de variveis PRIVATE e
PUBLIC. Para mais detalhes, veja o tpico: Boas Prticas de
Programao.

Exemplo: Public _cRotina

2.5 Entendendo a influncia do escopo das variveis

Considere as linhas de cdigo de exemplo:

nResultado := 250 * (1 + (nPercentual / 100))

Se esta linha for executada em um programa ADVPL, ocorrer um erro de execuo
com a mensagem "variable does not exist: nPercentual", pois esta varivel est sendo
utilizada em uma expresso de clculo sem ter sido declarada. Para solucionar este
erro, deve-se declarar a varivel previamente:

Local nPercentual, nResultado

Neste exemplo, as variveis so declaradas previamente utilizando o identificador de
escopo local. Quando a linha de clculo for executada, o erro de varivel no existente,
no mais ocorrer. Porm, variveis no inicializadas tm sempre o valor default nulo
(Nil) e este valor no pode ser utilizado em um clculo, pois tambm gerar erros de
execuo (nulo no pode ser dividido por 100). A resoluo deste problema efetuada
inicializando-se a varivel atravs de uma das formas:

Local nPercentual, nResultado
nPercentual := 10

ou

Local nPercentual := 10, nResultado


A diferena entre o ltimo exemplo e os dois anteriores que a varivel inicializada
no momento da declarao. Em ambos os exemplos, a varivel primeiro declarada e
ento inicializada em uma outra linha de cdigo.

aconselhvel optar pelo operador de atribuio composto de dois pontos e sinal de
igual, pois o operador de atribuio utilizando somente o sinal de igual pode ser
facilmente confundido com o operador relacional (para comparao) durante a criao
do programa.

6. Regras adicionais da linguagem ADVPL

2.6 Palavras reservadas

AADD DTOS INKEY REPLICATE VAL
ABS ELSE INT RLOCK VALTYPE
ASC ELSEIF LASTREC ROUND WHILE
AT EMPTY LEN ROW WORD
BOF ENDCASE LOCK RTRIM YEAR
BREAK ENDDO LOG SECONDS CDOW
ENDIF LOWER SELECT CHR EOF
LTRIM SETPOS CMONTH EXP MAX
SPACE COL FCOUNT MIN SQRT
CTOD FIELDNAME MONTH STR DATE
FILE PCOL SUBSTR DAY FLOCK
PCOUNT TIME DELETED FOUND PROCEDURE
TRANSFORM DEVPOS FUNCTION PROW TRIM
DOW IF RECCOUNT TYPE DTOC
IIF RECNO UPPER TRY AS
CATCH THROW

E Palavras reservadas no podem ser utilizadas para variveis,
procedimentos ou funes;

E Funes reservadas so pertencentes ao compilador e no
podem ser redefinidas por uma aplicao;

E Todos os identificadores que comearem com dois ou mais
caracteres _ so utilizados como identificadores internos e so
reservados.

E Identificadores de escopo PRIVATE ou PUBLIC utilizados em
aplicaes especficas desenvolvida por clientes ou para
clientes devem ter sua identificao iniciada por um caractere
_.

2.7 Pictures de formatao disponveis

Com base na documentao disponvel no TDN, a linguagem ADVPL e a aplicao ERP
Protheus admitem as seguintes pictures:

Dicionrio de Dados (SX3) e GET

Funes
Contedo Funcionalidade
A Permite apenas caracteres alfabticos.
C Exibe CR depois de nmeros positivos.
E Exibe numrico com o ponto e vrgula invertidos (formato Europeu).
R Insere caracteres diferentes dos caracteres de template na exibio, mas
no os insere na varivel do GET.
S<n> Permite rolamento horizontal do texto dentro do GET, <n> um nmero
inteiro que identifica o tamanho da regio.
X Exibe DB depois de nmeros negativos.
Z Exibe zeros como brancos.
( Exibe nmeros negativos entre parnteses com os espaos em branco
iniciais.
) Exibe nmeros negativos entre parnteses sem os espaos em branco
iniciais.
! Converte caracteres alfabticos para maisculo.

Templates
Contedo Funcionalidade
X Permite qualquer caractere.
9 Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal para
numricos.
# Permite dgitos, sinais e espaos em branco para qualquer tipo de dado.
! Converte caracteres alfabticos para maisculo.
* Exibe um asterisco no lugar dos espaos em branco iniciais em nmeros.
. Exibe o ponto decimal.
, Exibe a posio do milhar.

Exemplo 01 Picture campo numrico

CT2_VALOR Numrico 17,2
Picture: @E 99,999,999,999,999.99

Exemplo 02 Picture campo texto, com digitao apenas em caixa alta

A1_NOME Caracter - 40
Picture: @!

7. Programas de Atualizao

Os programas de atualizao de cadastros e digitao de movimentos seguem um
padro que se apia no Dicionrio de Dados.

Basicamente so trs os modelos mais utilizados:

E Modelo 1 ou AxCadastro: Para cadastramentos em tela
cheia. Exemplo: Cadastro de Cliente.

E Modelo 2: Cadastramentos envolvendo
apenas uma tabela, mas com um
cabealho e, opcionalmente, um
rodap e um corpo com
quantidade ilimitada de linhas.
Ideal para casos em que h
dados que se repetem por vrios
itens e que, por isso, so
colocados no cabealho. Exemplo:
Pedido de Compra.

E Modelo 3: Cadastramentos envolvendo duas
tabelas, um com dados de
cabealho e outro digitado em
linhas com os itens. Exemplo:
Pedido de Vendas, Oramento etc.

Todos os modelos so genricos, ou seja, o programa independe da tabela a ser
tratada, bastando praticamente que se informe apenas o seu Alias. O resto
obtido do Dicionrio de Dados (SX3).


2.8 Modelo1() ou AxCadastro()

O AxCadastro() uma funcionalidade de cadastro simples, com poucas opes de
customizao, a qual composta de:

Browse padro para visualizao das informaes da base de dados, de acordo
com as configuraes do SX3 Dicionrio de Dados (campo browse).
Funes de pesquisa, visualizao, incluso, alterao e excluso padres para
visualizao de registros simples, sem a opo de cabealho e itens.

E Sintaxe: AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt)

E Parmetros:
cAlias
Alias padro do sistema para utilizao, o qual deve estar definido no
dicionrio de dados SX3.
cTitulo Ttulo da Janela
cVldExc Validao para Excluso
cVldAlt Validao para Alterao

Exemplo: Funo AxCadastro()

#include "protheus.ch"

/*/
+-------------------------------------------------------------------
----------
| Funo | XCADSA2 | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
----------
| Descrio | Exemplo de utilizao da funo AXCADASTRO()
|
|+------------------------------------------------------------------
----------
| Uso | Curso ADVPL
|
|+------------------------------------------------------------------
----------
/*/

User Function XCadSA2()

Local cAlias := "SA2"
Local cTitulo := "Cadastro de Fornecedores"
Local cVldExc := ".T."
Local cVldAlt := ".T."

dbSelectArea(cAlias)
dbSetOrder(1)
AxCadastro(cAlias,cTitulo,cVldExc,cVldAlt)

Return Nil

Exerccio 01
Desenvolver um AxCadastro para a tabela padro do ERP SB1: Produtos

Exemplo: Funo de validao da alterao

/*/
+-------------------------------------------------------------------
------
| Funo | VLDALT | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo de validao de alterao para a
AXCADASTRO() |
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function VldAlt(cAlias,nReg,nOpc)

Local lRet := .T.
Local aArea := GetArea()
Local nOpcao := 0

nOpcao := AxAltera(cAlias,nReg,nOpc)

If nOpcao == 1
MsgInfo(Aterao concluda com sucesso!)
Endif

RestArea(aArea)

Return lRet

Exemplo: Funo de validao da excluso

/*/
+-------------------------------------------------------------------
-----------
| Funo | VLDEXC | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
-----------
| Descrio | Funo de validao de excluso para a
AXCADASTRO() |
+-------------------------------------------------------------------
-----------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
-----------
/*/

User Function VldExc(cAlias,nReg,nOpc)

Local lRet := .T.
Local nOpcao := 0

nOpcao := AxExclui(cAlias,nReg,nOpc)

If nOpcao == 1
MsgInfo(Excluso concluda com sucesso!)
Endif

RestArea(aArea)
Return lRet

Exerccio 02
Implementar no AxCadastro as validaes de alterao e excluso.

2.9 Mbrowse()

A Mbrowse() uma funcionalidade de cadastro que permite a utilizao de recursos
mais aprimorados na visualizao e manipulao das informaes do sistema,
possuindo os seguintes componentes:

Browse padro para visualizao das informaes da base de dados, de acordo
com as configuraes do SX3 Dicionrio de Dados (campo browse).

Parametrizao para funes especficas para as aes de visualizao, incluso,
alterao e excluso de informaes, o que viabiliza a manuteno de
informaes com estrutura de cabealhos e itens.

Recursos adicionais como identificadores de status de registros, legendas e
filtros para as informaes.

E Sintaxe: MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias, aFixe, cCpo, nPar08,
cFun, nClickDef, aColors, cTopFun, cBotFun, nPar14, bInitBloc,
lNoMnuFilter, lSeeAll, lChgAll)

E Parmetros:

nLin1 Nmero da Linha Inicial
nCol1 Nmero da Coluna Inicial
nLin2 Nmero da Linha Final
nCol2 Nmero da Coluna Final
cAlias
Alias do arquivo que ser visualizado no browse.
Para utilizar a funo MBrowse com arquivos de trabalho, o alias do
arquivo de trabalho deve ser obrigatoriamente 'TRB' e o parmetro aFixe
torna-se obrigatrio.
aFixe
Array bi-dimensional contendo os nomes dos campos fixos pr-definidos,
obrigando a exibio de uma ou mais colunas ou a definio das colunas
quando a funo utilizada com arquivos de trabalho.
A estrutura do array diferente para arquivos que fazem parte do
dicionrio de dados e para arquivos de trabalho.

Arquivos que fazem parte do dicionrios de dados

[n][1]=>Descrio do campo
[n][2]=>Nome do campo

Arquivos de trabalho

[n][1]=>Descrio do campo
[n][2]=>Nome do campo
[n][3]=>Tipo
[n][4]=>Tamanho
[n][5]=>Decimal
[n][6]=>Picture

E Parmetros:
cCpo
Campo a ser validado se est vazio ou no para exibio do bitmap de
status. Quando esse parmetro utilizado, a primeira coluna do browse
ser um bitmap indicando o status do registro, conforme as condies
configuradas nos parmetros cCpo, cFun e aColors.
nPar08 Parmetro reservado.
cFun
Funo que retornar um valor lgico para exibio do bitmap de status.
Quando esse parmetro utilizado, o parmetro cCpo automaticamente
desconsiderado.
nClickDef
Nmero da opo do aRotina que ser executada quando for efetuado um
duplo clique em um registro do browse. O default executar a rotina de
visualizao.
aColors
Array bi-dimensional para possibilitar o uso de diferentes bitmaps de
status.
[n][1]=>Funo que retornar um valor lgico para a exibio do bitmap
[n][2]=>Nome do bitmap que ser exibido quando a funo retornar .T.
(True). O nome do bitmap deve ser um recurso do repositrio e quando
esse parmetro utilizado os parmetros cCpo e cFun so
automaticamente desconsiderados.
cTopFun
Funo que retorna o limite superior do filtro baseado na chave de ndice
selecionada. Esse parmetro deve ser utilizado em conjunto com o
parmetro cBotFun.
cBotFun
Funo que retorna o limite inferior do filtro baseado na chave de ndice
selecionada.
Esse parmetro deve ser utilizado em conjunto com o parmetro cTopFun.
nPar14 Parmetro reservado.
bInitBloc
Bloco de cdigo que ser executado no ON INIT da janela do browse. O
bloco de cdigo receber como parmetro o objeto da janela do browse.
lNoMnuFilter
Valor lgico que define se a opo de filtro ser exibida no menu da
MBrowse. .T. => No exibe a opo no menu ou .F. => (default) Exibe a
opo no menu. A opo de filtro na MBrowse est disponvel apenas para
TOPConnect.
lSeeAll
Identifica se o Browse dever mostrar todas as filiais.
O valor default .F. ( False ), no mostra todas as filiais. Caso os
parmetros cTopFun ou cBotFun sejam informados esse parmetro ser
configurado automaticamente para .F. ( False ). Parmetro vlido partir
da verso 8.11. A funo SetBrwSeeAll muda o valor default desse
parmetro.
lChgAll
Identifica se o registro de outra filial est autorizado para alteraes.
O valor default .F. ( False ), no permite alterar registros de outras filiais.
Quando esse parmetro est configurado para .T. ( True ), o parmetro
lSeeAll configurado automaticamente para .T. ( True ). Caso os
parmetros cTopFun ou cBotFun sejam informados esse parmetro ser
configurado automaticamente para .F. ( False ).
Parmetro vlido partir da verso 8.11.
A funo SetBrwChgAll muda o valor default desse parmetro.

E Variveis private adicionais

aRotina
Array contendo as funes que sero executadas pela Mbrowse, nele ser
definido o tipo de operao a ser executada (incluso, alterao, excluso,
visualizao, pesquisa, etc. ), e sua estrutura composta de 5 (cinco)
dimenses:

[n][1] - Ttulo;
[n][2] Rotina;
[n][3] Reservado;
[n][4] Operao (1 - pesquisa; 2 - visualizao; 3 - incluso; 4 - alterao;
5 - excluso);

Ele ainda pode ser parametrizado com as funes bsicas da AxCadastro
conforme abaixo:

AADD(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual",0,2})
AADD(aRotina,{"Incluir" ,"AxInclui",0,3})
AADD(aRotina,{"Alterar" ,"AxAltera",0,4})
AADD(aRotina,{"Excluir" ,"AxDeleta",0,5})
cCadastro Ttulo do browse que ser exibido.

E Informaes passadas para funes do aRotina:

Ao definir as funes no array aRotina, se o nome da funo no for especificado com
(), a Mbrowse passar como parmetros as seguintes variveis de controle:

cAlias Nome da rea de trabalho definida para a Mbrowse
nReg Recno do registro posicionado no Browse
nOpc
Posio da opo utilizada na Mbrowse de acordo com a ordem da funo
no array a Rotina.

A posio das funes no array aRotina define o contedo de uma
varivel de controle que ser repassada para as funes chamadas a
partir da Mbrowse, convencionada como nOpc. Desta forma, para
manter o padro da aplicao ERP a ordem a ser seguida na definio
do aRotina :
1. Pesquisar
2. Visualizar
3. Incluir
4. Alterar
5. Excluir
6. Livre

Exemplo: Funo Mbrowse()


/*/
+-------------------------------------------------------------------
------
| Funo | MBRWSA1 | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Exemplo de utilizao da funo MBROWSE()
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function MBrwSA1()

Private cCadastro := "Cadastro de Clientes"
Private aRotina := {}

AADD(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual",0,2})
AADD(aRotina,{"Incluir" ,"AxInclui",0,3})
AADD(aRotina,{"Alterar" ,"AxAltera",0,4})
AADD(aRotina,{"Excluir" ,"AxDeleta",0,5})

dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)

Return Nil

Exemplo: Funo Inclui() substituindo a funo AxInclui() Chamada da
Mbrowse()


/*/
+-------------------------------------------------------------------
------
| Funo | MBRWSA1 | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Exemplo de utilizao da funo MBROWSE()
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/



AADD(aRotina,{"Pesquisar" ,"AxPesqui" ,0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual" ,0,2})
AADD(aRotina,{"Incluir" ,"U_Inclui" ,0,3})

Exemplo (continuao):

AADD(aRotina,{"Alterar" ,"AxAltera" ,0,4})
AADD(aRotina,{"Excluir" ,"AxDeleta" ,0,5})

dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)

Return Nil

Exemplo: Funo Inclui() substituindo a funo AxInclui() Funo Inclui()

/*/
+-------------------------------------------------------------------
-----
| Funo | INCLUI | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
----
| Descrio | Funo de incluso especfica chamando a
AXINCLUI()|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function Inclui(cAlias, nReg, nOpc)

Local cTudoOk := "(Alert('OK'),.T.)"
Local nOpcao := 0

nOpcao := AxInclui(cAlias,nReg,nOpc,,,,cTudoOk)

If nOpcao == 1
MsgInfo(Incluso concluda com sucesso!)
ElseIf == 2
MsgInfo(Incluso cancelada!)
Endif

Return Nil

Exemplo: Determinando a opo do aRotina pela informao recebida em nOpc


/*/
+-------------------------------------------------------------------
------
| Funo | EXCLUI | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo de excluso especifica chamando a AxDeleta
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function Exclui(cAlias, nReg, nOpc)

Local cTudoOk := "(Alert('OK'),.T.)"
Local nOpcao := 0

nOpcao := AxDeleta(cAlias,nReg,aRotina[nOpc,4])
// Identifica corretamente a opo definida para o funo em
aRotinas com mais // do que os 5 elementos padres.

If nOpcao == 1
MsgInfo(Excluso realizada com sucesso!)
ElseIf == 2
MsgInfo(Excluso cancelada!)
Endif

Return Nil

2.9.1 AxFunctions()
Conforme mencionado nos tpicos sobre as interfaces padres AxCadastro() e
Mbrowse(), existem funes padres da aplicao ERP que permitem a
visualizao, incluso, alterao e excluso de dados em formato simples.
Estas funes so padres na definio da interface AxCadastro() e podem ser
utilizadas tambm da construo no array aRotina utilizado pela Mbrowse(), as
quais esto listadas a seguir:
AXPESQUI()
AXVISUAL()
AXINCLUI()
AXALTERA()
AXDELETA()
AXPESQUI()

Sintaxe AXPESQUI()
Descrio
Funo de pesquisa padro em registros exibidos pelos browses do sistema, a
qual posiciona o browse no registro pesquisado. Exibe uma tela que permite a
seleo do ndice a ser utilizado na pesquisa e a digitao das informaes que
compe a chave de busca.

AXVISUAL()

Sintaxe
AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,;
aButtons, lMaximized )
Descrio
Funo de visualizao padro das informaes de um registro, no formato
Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro().

AXINCLUI()

Sintaxe
AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,; cTransact,
aButtons, aParam, aAuto, lVirtual, lMaximized)
Descrio
Funo de incluso padro das informaes de um registro, no formato

AXALTERA()

Sintaxe
AxAltera(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,; cTransact,
aButtons, aParam, aAuto, lVirtual, lMaximized)
Descrio
Funo de alterao padro das informaes de um registro, no formato

AXDELETA()

Sintaxe
AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,; aAuto,
lMaximized)
Descrio
Funo de excluso padro das informaes de um registro, no formato


Exerccio 03
Implementar uma MBrowse com as funes de cadastro padres para a tabela
padro do ERP SB1: Produtos

2.9.2 FilBrowse()

A FilBrowse() uma funcionalidade que permite a utilizao de filtros na MBrowse().

E Sintaxe: FilBrowse(cAlias, aQuery, cFiltro, lShowProc)

E Parmetros:

cAlias Alias ativo definido para a Mbrowse()
aQuery
Este parmetro dever ser inicializado sempre vazio e sua passagem
obrigatoriamente por referncia, pois, seu retorno ser enviado para a
funo EndFilBrw().

[1]=>Nome do Arquivo Fsico
[2]=>Ordem correspondente ao Sindex
cFiltro Condio de filtro para a MBrowse()
lShowProc

Habilita (.T.) ou desabilita (.F.) a apresentao da mensagem
Selecionando registros ..., no processamento.

2.9.3 EndFilBrw()

A EndFilBrw() uma funcionalidade que permite eliminar o filtro e o arquivo
temporrio criados pela FilBrowse().

E Sintaxe: EndFilBrw(cAlias, aQuery)

E Parmetros:

aQuery
Array de retorno passado por referncia para a FilBrowse().
[1]=>Nome do Arquivo Fsico
[2]=>Ordem correspondente ao Sindex
2.9.4 PesqBrw()

A PesqBrw() uma funcionalidade que permite a pesquisa dentro da MBrowse(). Esta
funo dever obrigatoriamente substituir a funo AxPesqui, no array do aRotina,
sempre que for utilizada a funo FilBrowse().

E Sintaxe: PesqBrw(cAlias , nReg, bBrwFilter)

E Parmetros:

nReg Nmero do registro
bBrwFilter
Bloco de Cdigo que contm a FilBrowse()
Ex: bBrwFilter := { || FilBrowse(cAlias, aQuery, cFiltro, lShowProc) }

2.9.5 BrwLegenda ()

A BrwLegenda() uma funcionalidade que permite a incluso de legendas na
MBrowse().

E Sintaxe: BrwLegenda(cCadastro , cTitulo, aLegenda)

E Parmetros:

cCadastro
Mesma varivel utilizada para a MBrowse, que identifica o cadastro que
est em uso no momento
cTitulo Ttulo (identificao) da Legenda
aLegenda
Array contendo de definio da cor e do texto, explicativo sobre o que ela
representa na MBrowse
Ex: {{Cor,Texto}}

Lista de cores disponveis no Protheus

Q BR_AMARELO
Q BR_AZUL
Q BR_BRANCO
Q BR_CINZA
Q BR_LARANJA
Q BR_MARRON
Q BR_VERDE
Q BR_VERMELHO
Q BR_PINK
Q BR_PRETO

Exemplo: Mbrowse() utilizando as funes acessrias

#Include "Protheus.ch"

/*/
+-------------------------------------------------------------------
------
| Programa | MBrwSA2 | Autor | SERGIO FUZINAKA | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Exemplo da MBrowse utilizando a tabela de
Cadastro de |
| | Fornecedores
|
+-------------------------------------------------------------------
------
| Uso | Curso de ADVPL
|
+-------------------------------------------------------------------
------
/*/


Local aCores := {}
Local cFiltra := "A2_FILIAL == '"+xFilial('SA2')+"' .And. A2_EST ==
'SP'"

Private cCadastro := "Cadastro de Fornecedores"
Private aIndexSA2 := {}
Private bFiltraBrw:= { || FilBrowse(cAlias,@aIndexSA2,@cFiltra) }

AADD(aRotina,{"Pesquisar" ,"PesqBrw" ,0,1})
AADD(aRotina,{"Incluir" ,"U_BInclui" ,0,3})
AADD(aRotina,{"Alterar" ,"U_BAltera" ,0,4})
AADD(aRotina,{"Excluir" ,"U_BDeleta" ,0,5})
AADD(aRotina,{"Legenda" ,"U_BLegenda" ,0,3})

/*
-- CORES DISPONIVEIS PARA LEGENDA --
BR_AMARELO
BR_AZUL
BR_BRANCO
BR_CINZA
BR_LARANJA
BR_MARRON
BR_VERDE
BR_VERMELHO
BR_PINK
BR_PRETO
*/
AADD(aCores,{"A2_TIPO == 'F'" ,"BR_VERDE" })
AADD(aCores,{"A2_TIPO == 'J'" ,"BR_AMARELO" })
AADD(aCores,{"A2_TIPO == 'X'" ,"BR_LARANJA" })
AADD(aCores,{"A2_TIPO == 'R'" ,"BR_MARRON" })
AADD(aCores,{"Empty(A2_TIPO)" ,"BR_PRETO" })

dbSetOrder(1)

//+------------------------------------------------------------
//| Cria o filtro na MBrowse utilizando a funo FilBrowse
//+------------------------------------------------------------
Eval(bFiltraBrw)

dbGoTop()
mBrowse(6,1,22,75,cAlias,,,,,,aCores)

//+------------------------------------------------
//| Deleta o filtro utilizado na funo FilBrowse
//+------------------------------------------------
EndFilBrw(cAlias,aIndexSA2)

Return Nil

//+---------------------------------------
//|Funo: BInclui - Rotina de Incluso
//+---------------------------------------
User Function BInclui(cAlias,nReg,nOpc)

Local nOpcao := 0

nOpcao := AxInclui(cAlias,nReg,nOpc)

If nOpcao == 1
MsgInfo("Incluso efetuada com sucesso!")
Else
MsgInfo("Incluso cancelada!")
Endif

Return Nil

//+-----------------------------------------
//|Funo: BAltera - Rotina de Alterao
//+-----------------------------------------
User Function BAltera(cAlias,nReg,nOpc)

Local nOpcao := 0

nOpcao := AxAltera(cAlias,nReg,nOpc)

If nOpcao == 1
MsgInfo("Alterao efetuada com sucesso!")
Else
MsgInfo("Alterao cancelada!")
Endif

Return Nil
//+-----------------------------------------
//|Funo: BDeleta - Rotina de Excluso
//+-----------------------------------------
User Function BDeleta(cAlias,nReg,nOpc)

Local nOpcao := 0

nOpcao := AxDeleta(cAlias,nReg,nOpc)

If nOpcao == 1
MsgInfo("Excluso efetuada com sucesso!")
Else
MsgInfo("Excluso cancelada!")
Endif

Return Nil

//+-------------------------------------------
//|Funo: BLegenda - Rotina de Legenda
//+-------------------------------------------
User Function BLegenda()

Local aLegenda := {}

AADD(aLegenda,{"BR_VERDE" ,"Pessoa Fsica" })
AADD(aLegenda,{"BR_AMARELO" ,"Pessoa Jurdica" })
AADD(aLegenda,{"BR_LARANJA" ,"Exportao" })
AADD(aLegenda,{"BR_MARRON" ,"Fornecedor Rural" })
AADD(aLegenda,{"BR_PRETO" ,"No Classificado" })

BrwLegenda(cCadastro, "Legenda", aLegenda)

Return Nil

Exerccio 04
Implementar a legenda para a MBrowse da tabela padro do ERP SB1: Produtos

2.10 MarkBrowse()

A funo MarkBrow() permite que os elementos de um browse, sejam marcados ou
desmarcados. Para utilizao da MarkBrowse() necessrio declarar as variveis
cCadastro e aRotina como Private, antes da chamada da funo.

E Sintaxe: MarkBrow (cAlias, cCampo, cCpo, aCampos, lInvert, cMarca,
cCtrlM, uPar8, cExpIni, cExpFim, cAval, bParBloco)

E Parmetros:

cCampo Campo do arquivo onde ser feito o controle (gravao) da marca.
cCpo
Campo onde ser feita a validao para marcao e exibio do bitmap de
status.
aCampos
Vetor de colunas a serem exibidas no browse, deve conter as seguintes
dimenses:
[n][1] nome do campo;
[n][2] - Nulo (Nil);
[n][3] - Ttulo do campo;
[n][4] - Mscara (picture).
lInvert Inverte a marcao.
cMarca String a ser gravada no campo especificado para marcao.
cCtrlM Funo a ser executada caso deseje marcar todos elementos.
uPar8 Parmetro reservado.
cExpIni
Funo que retorna o contedo inicial do filtro baseada na chave de ndice
selecionada.
cExpFim
Funo que retorna o contedo final do filtro baseada na chave de ndice
selecionada.
cAval Funo a ser executada no duplo clique em um elemento no browse.
bParBloco Bloco de cdigo a ser executado na inicializao da janela

E Informaes passadas para funes do aRotina:

Ao definir as funes no array aRotina, se o nome da funo no for especificado com
(), a MarkBrowse passar como parmetros as seguintes variveis de controle:

cAlias Nome da rea de trabalho definida para a Mbrowse
nReg Recno do registro posicionado no Browse
nOpc
Posio da opo utilizada na Mbrowse de acordo com a ordem da funo
no array a Rotina.
cMarca Marca em uso pela MarkBrw()
lInverte Indica se foi utilizada a inverso da seleo dos itens no browse.

2.10.1 Funes de Apoio

GetMark: define a marca atual.

IsMark: avalia se um determinado contedo igual a marca atual.

ThisMark: captura a marca em uso.

ThisInv: indica se foi usado o recurso de selecionar todos (inverso).

MarkBRefresh: atualiza exibio na marca do browse. Utilizada quando a marca
colocada ou removida em blocos e no pelo clique.

Exemplo: Funo MarkBrow() e acessrias

/*/
+-------------------------------------------------------------------
------
| Programa | MkBrwSA1 | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
------
| Desc. | MarkBrowse Genrico |
+-------------------------------------------------------------------
------
|
+-------------------------------------------------------------------
------
/*/

USER FUNCTION MkBrwSA1()

Local aCpos := {}
Local aCampos := {}
Local nI := 0

Private aRecSel := {}

AADD(aRotina,{"Incluir" ,"AxInclui" ,0,3})
AADD(aRotina,{"Alterar" ,"AxAltera" ,0,4})
AADD(aRotina,{"Excluir" ,"AxDeleta" ,0,5})
AADD(aRotina,{"Visualizar Lote" ,"U_VisLote" ,0,5})

AADD(aCpos, "A1_OK" )
AADD(aCpos, "A1_FILIAL" )
AADD(aCpos, "A1_COD" )
AADD(aCpos, "A1_LOJA" )
AADD(aCpos, "A1_NOME" )
AADD(aCpos, "A1_TIPO" )

dbSelectArea("SX3")
dbSetOrder(2)
For nI := 1 To Len(aCpos)
IF dbSeek(aCpos[nI])
AADD(aCampos,{X3_CAMPO,"",IIF(nI==1,"",Trim(X3_TITULO)),;
Trim(X3_PICTURE)})
ENDIF
Next

DbSelectArea(cAlias)
DbSetOrder(1)

MarkBrow(cAlias,aCpos[1],"A1_TIPO == '
'",aCampos,.F.,GetMark(,"SA1","A1_OK"))

Return Nil

Exemplo: Funo VisLote() utilizao das funes acessrias da MarkBrow()

/*/
+-------------------------------------------------------------------
------
| Programa | VisLote() | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
------
| Desc. | Funo utilizada para demonstrar o uso do recurso da
MarkBrowse|
+-------------------------------------------------------------------
------
|
+-------------------------------------------------------------------
------
/*/
USER FUNCTION VisLote()
Local cMarca := ThisMark()
Local nX := 0
Local lInvert := ThisInv()
Local cTexto := ""
Local cEOL := CHR(10)+CHR(13)
Local oDlg
Local oMemo

DbSelectArea("SA1")
DbGoTop()
While SA1->(!EOF())

// IsMark("A1_OK", cMarca, lInverte)
IF SA1->A1_OK == cMarca .AND. !lInvert
AADD(aRecSel,{SA1->(Recno()),SA1->A1_COD, SA1->A1_LOJA, SA1-
>A1_NREDUZ})
ELSEIF SA1->A1_OK != cMarca .AND. lInvert
AADD(aRecSel,{SA1->(Recno()),SA1->A1_COD,SA1->A1_LOJA, SA1-
>A1_NREDUZ})
ENDIF

SA1->(dbSkip())
Enddo

IF Len(aRecSel) > 0
cTexto := "Cdigo | Loja | Nome Reduzido "+cEol
// "1234567890123456789012345678901234567890
// "CCCCCC | LL | NNNNNNNNNNNNNNNNNNNN +cEol

For nX := 1 to Len(aRecSel)

cTexto += aRecSel[nX][2]+Space(1)+ "|"+Space(2) +
aRecSel[nX][3]+Space(3)+"|"
cTexto += Space(1)+SUBSTRING(aRecSel[nX][4],1,20)+Space(1)
cTexto += cEOL

Next nX

DEFINE MSDIALOG oDlg TITLE "Clientes Selecionados" From 000,000
TO 350,400 PIXEL
@ 005,005 GET oMemo VAR cTexto MEMO SIZE 150,150 OF oDlg PIXEL
oMemo:bRClicked := {||AllwaysTrue()}
DEFINE SBUTTON FROM 005,165 TYPE 1 ACTION oDlg:End() ENABLE OF
oDlg PIXEL
ACTIVATE MSDIALOG oDlg CENTER
LimpaMarca()
ENDIF

RETURN

Exemplo: Funo LimpaMarca() utilizao das funes acessrias da MarkBrow()

/*/
+-------------------------------------------------------------------
------
| Programa | LimpaMarca | Autor | ARNALDO RAYMUNDO JR. | Data |
|
+-------------------------------------------------------------------
------
| Desc. | Funo utilizada para demonstrar o uso do recurso da
MarkBrowse|
+-------------------------------------------------------------------
------
|
+-------------------------------------------------------------------
------
/*/

STATIC FUNCTION LimpaMarca()

Local nX := 0

For nX := 1 to Len(aRecSel)
SA1->(DbGoto(aRecSel[nX][1]))
RecLock("SA1",.F.)
SA1->A1_OK := SPACE(2)
MsUnLock()
Next nX

RETURN

Exerccio 05
Implementar uma MarkBrowse com as funes de cadastro padres para a tabela
padro do ERP SB1: Produtos

Exerccio 06
Implementar na MarkBrowse da tabela padro SB1, uma funo para excluso de
mltiplos itens selecionados no Browse. ERP SB1: Produtos

Exerccio 07
Implementar uma MarkBrowse para a tabela SA1, para visualizao de dados de
mltiplos clientes selecionados

2.11 Modelo2()

O nome Modelo 2 foi conceituado pela Microsiga por se tratar de um prottipo de tela
para entrada de dados. Inicialmente vamos desmistificar dois pontos:

Q Funo Modelo2() Trata-se de uma funo pronta que contempla o
prottipo Modelo 2, porm, este um assunto que no iremos tratar
aqui, visto que uma funcionalidade simples que quando necessrio
intervir em algo na rotina no h muito recurso para tal.

Q Prottipo Modelo 2 Trata-se de uma tela, como a figura abaixo, onde
seu objetivo efetuar a manuteno em vrios registros de uma s vez.
Por exemplo: efetuar o movimento interno de vrios produtos do
estoque em um nico lote.

2.11.1 Componentes de uma tela no formato Modelo 2

Objeto MsDialog()

Deve ser utilizada como janela padro para entrada de dados, um tipo de objeto
modal, ou seja, no permite que outra janela ativa receba dados enquanto esta estiver
ativa.

Toda vez que utilizar este comando, o ADVPL exige que seja declarada a diretiva
Include no cabealho do programa o arquivo Protheus.ch, isto porque o compilador
precisar porque este comando trata-se de um pseudo cdigo e sua traduo ser feita
na compilao. Vale lembrar, tambm, que este s ser acionado depois que
instanciado e ativado por outro comando.

DEFINE MSDIALOG oDlg TITLE "Prottipo Modelo 2" FROM 0,0 TO 280,552
OF;
oMainWnd PIXEL


Reparem que o comando DEFINE MSDIALOG instanciou e o comando ACTIVATE
MSDIALOG ativa todos os objetos, ou seja, todo ou qualquer outro objeto que precisar
colocar nesta janela ser preciso informar em qual objeto. Para este caso, sempre ser
utilizada a varivel de objeto exportvel oDlg.

Funo EnchoiceBar()

Funo que cria uma barra de botes padro de Ok e Cancelar, permitindo a
implementao de botes adicionais.

E Sintaxe: ENCHOICEBAR( oDlg, bOk, bCancelar, [ lMensApag ] , [ aBotoes ] )

E Parmetros:

oDlg Objeto Janela onde a barra ser criada.
bOk Objeto Bloco de cdigo executado quando clicado boto Ok.
bCancelar Objeto Bloco de cdigo executado quando clicado.
lMensApag Lgico
Indica se ao clicar no boto Ok aparecer uma tela de
confirmao de excluso. Valor padro falso.
aBotes Vetor
Vetor com informaes para criao de botes
adicionais na barra. Seu formato {bitmap, bloco de
cdigo, mensagem}.

Figura: Prottipo Modelo2 Enchoice

Objeto TPanel()

Repare que para facilitar o desenvolvimento foi utilizado o objeto TPanel para ajudar o
alinhamento dos objetos TSay e TGet, ou seja, a utilizao deste recurso permite que o
programador no se preocupe com coordenadas complexas para deixar a unio dos
objetos simtricos.

Utilize o objeto TPanel quando desejar criar um painel esttico, onde podem ser
criados outros controles com o objetivo de organizar ou agrupar componentes visuais.

E Sintaxe: TPanel():New([anRow], [anCol], [acText], [aoWnd], [aoFont],
[alCentered], [lPar6], [anClrText], [anClrBack], [anWidth],
[anHeight], [alLowered], [alRaised])

E Parmetros:

nRow Numrico vertical em pixel.
nCol Numrico horizontal em pixel.
cText Texto a ser exibido ao fundo.
oWnd Objeto da janela ou controle onde ser criado o objeto.
oFont Caractersticas da fonte do texto que aparecer ao fundo.
lCentered Exibe o texto do ttulo centralizado.
lPar6 Reservado.
nClrText Cor do texto de controle.
nClrBack Cor do fundo de controle.
nWidth Largura do controle em pixel.
nHeight Altura do controle em pixel.
lLowered Exibe o painel rebaixado em relao ao controle de fundo.
lRaised
Exibe a borda do controle rebaixado em relao ao controle de
fundo.

Comando SAY - Objeto: TSay()

O comando SAY ou objeto TSay exibe o contedo de texto esttico sobre uma janela.

E Sintaxe SAY:

@ 4,6 SAY "Cdigo:" SIZE 70,7 PIXEL OF oTPanel1

E Sintaxe TSay(): TSay():New([anRow], [anCol], [abText], [aoWnd],
[acPicture], [aoFont], [lPar7], [lPar8], [lPar9], [alPixels],
[anClrText], [anClrBack], [anWidth], [anHeight], [lPar15], [lPar16],
[lPar17], [lPar18], [lPar19])

E Parmetros:

anRow Numrico, opcional. Coordenada vertical em pixels ou caracteres.
anCol
Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
abText
Code-Block, opcional. Quando executado deve retornar uma
cadeia de caracteres a ser exibida.
aoWnd Objeto, opcional. Janela ou dilogo onde o controle ser criado.
acPicture
Caractere, opcional. Picture de formatao do contedo a ser
exibido.
aoFont
Objeto, opcional. Objeto tipo tFont para configurao do tipo de
fonte que ser utilizado para exibir o contedo.
lPar7 Reservado.
lPar8 Reservado.
lPar9 Reservado.
alPixels
Lgico, opcional. Se .T. considera coordenadas passadas em pixels
se .F., padro, considera as coordenadas passadas em caracteres.
anClrText Numrico, opcional. Cor do contedo do controle.
anClrBack Numrico, opcional. Cor do fundo do controle.
anWidth Numrico, opcional. Largura do controle em pixels.
anHeight Numrico, opcional. Altura do controle em pixels.
lPar15 Reservado.
lPar16 Reservado.
lPar17 Reservado.
lPar18 Reservado.
lPar19 Reservado.

Comando MSGET - Objeto: TGet()

O comando MsGet ou o objeto TGet utilizado para criar um controle que armazene
ou altere o contedo de uma varivel atravs de digitao. O contedo da varivel s
modificado quando o controle perde o foco de edio para outro controle.

E Sintaxe MSGET:

@ 3,192 MSGET dData PICTURE "99/99/99" SIZE 40,7 PIXEL OF oTPanel1

E Sintaxe TGet():New([anRow], [anCol], [abSetGet], [aoWnd], [anWidth],
[anHeight], [acPict], [abValid], [anClrFore], [anClrBack], [aoFont],
[lPar12], [oPar13], [alPixel], [cPar15], [lPar16], [abWhen],
[lPar18], [lPar19], [abChange], [alReadOnly], [alPassword],
[cPar23], [acReadVar], [cPar25], [lPar26], [nPar27], [lPar28])

E Parmetros:

anRow Numrico, opcional. Coordenada vertical em pixels ou caracteres.
anCol Numrico, opcional. Coordenada horizontal em pixels ou
caracteres.
abSetGet Bloco de cdigo, opcional. Bloco de cdigo no formato {|u| IF(
Pcount( )>0, <var>:= u, <var> ) } que o controle utiliza para
atualizar a varivel <var>. <var> deve ser tipo caracter, numrico
ou data.
aoWnd Objeto, opcional. Janela ou controle onde o controle ser criado.
anWidth Numrico, opcional. Largura do controle em pixels.
anHeight Numrico, opcional. Altura do controle em pixels.
acPict Caractere, opcional. Mscara de formatao do contedo a ser
exibido.
abValid Bloco de cdigo, opcional. Executado quando o contedo do
controle deve ser validado, deve retornar T se o contedo for
vlido e F quando o contedo for invlido.
anClrFore Numrico, opcional. Cor de fundo do controle.
anClrBack Numrico, opcional. Cor do texto do controle.
aoFont Objeto, opcional. Objeto tipo tFont utilizado para definir as
caractersticas da fonte utilizada, para exibir o contedo do
controle.
lPar12 Reservado.
oPar13 Reservado.
alPixel Lgico, opcional. Se .T. as coordenadas informadas so em pixels,
se .F. so em caracteres.
cPar15 Reservado.
lPar16 Reservado.
abWhen Bloco de cdigo, opcional. Executado quando mudana de foco
de entrada de dados est sendo efetuada na janela onde o
controle foi criado. O bloco deve retornar T se o controle deve
permanecer habilitado ou F, se no.
lPar18 Reservado.
lPar19 Reservado.
abChange Bloco de cdigo, opcional. Executado quando o controle modifica
o valor da varivel associada.
alReadOnly Lgico, opcional. Se .T. o controle no poder ser editado.
alPassword Lgico, opcional. Se .T. o controle exibir asteriscos * no lugar
dos caracteres exibidos pelo controle para simular entrada de
senha.
cPar23 Reservado.
acReadVar Caractere, opcional. Nome da varivel que o controle dever
manipular. Dever ser a mesma varivel informada no parmetro
abSetGet, e ser o retorno da funo ReadVar( ).
cPar25 Reservado.
lPar26 Reservado.
nPar27 Reservado.
lPar18 Reservado.

Objeto MsGetDados()

Objeto tipo lista com uma ou mais colunas para cadastramento de dados baseado em
um vetor. Sua utilizao exige que sejam utilizadas trs variveis com seu escopo
Private, so elas: aRotina, aHeader e aCOLS.

E Observaes importantes:

Q O vetor aHeader deve ser construdo com base no dicionrio de
dados.
Q O vetor aCOLS deve ser construdo com base no vetor aHeader,
porm deve-se criar uma coluna adicional para o controle de
excluso do registro, ou seja, quando o usurio teclar a tecla
<DELETE> a linha ficar na cor cinza e esta coluna estar com o seu
valor igual a verdadeiro (.T.).
Q Quando instanciado este objeto possvel saber em que linha o
usurio est porque o objeto trabalha com uma varivel de escopo
Public denominada n, seu valor numrico e ter sempre no
contedo a linha em que o usurio encontra-se com o cursor.

E Sintaxe: MSGETDADOS():NEW( nSuperior, nEsquerda, nInferior, nDireita,
nOpc, [ cLinhaOk ], [ cTudoOk ], [ cIniCpos ], [ lApagar ], [ aAlter],
, [ uPar1 ], [ lVazio ], [ nMax], [ cCampoOk ], [ cSuperApagar ],
[ uPar2 ], [ cApagaOk ], [ oWnd ] )

E Parmetros:

nSuperior
Distncia entre a MsGetDados e o extremidade superior do
objeto que a contm.
nEsquerda
Distncia entre a MsGetDados e o extremidade esquerda do
objeto que a contm.
nInferior
Distncia entre a MsGetDados e o extremidade inferior do
objeto que a contm.
nDireita
Distncia entre a MsGetDados e o extremidade direita do objeto
que a contm.
nOpc
Posio do elemento do vetor aRotina que a MsGetDados usar
como referencia.
cLinhaOk
Funo executada para validar o contexto da linha atual do
aCols.
cTudoOk
Funo executada para validar o contexto geral da MsGetDados
(todo aCols).
cIniCpos
Nome dos campos do tipo caracter que utilizaro incremento
automtico. Este parmetro deve ser no formato +<nome do
primeiro campo>+<nome do segundo campo>+....
lApagar Habilita deletar linhas do aCols. Valor padro falso.
aAlter Vetor com os campos que podero ser alterados.
lVazio
Habilita validao da primeira coluna do aCols para que esta
no esteja vazia. Valor padro falso.
nMax Nmero mximo de linhas permitidas. Valor padro 99.
cCampoOk Funo executada na validao do campo.
cSuperApagar
Funo executada quando pressionada as teclas
<Ctrl>+<Delete>.
cApagaOk Funo executada para validar a excluso de uma linha do aCols.
oWnd Objeto no qual a MsGetDados ser criada.

Varivel Private aRotina

Array com as rotinas que sero executadas na MBrowse e que definir o tipo de
operao que est sendo executada, por exemplo: Pesquisar, Visualizar, Incluir, Alterar,
Excluir e outros.

Este vetor precisa ser construdo no formato:

Elemento Contedo
1 Ttulo da opo.
2 Nome da rotina (Function).
3 Reservado.
4 Operao (1-Pesquisar;2-Visualizar;3-Incluir;4-Alterar;5-Excluso).
5 Acesso relacionado a rotina. Se esta opo no for informada, nenhum
acesso ser validado.

Varivel Private aHeader

Array com informaes das colunas, ou seja, com as caractersticas dos campos que
esto contidas no dicionrio de dados (SX3), este vetor precisa estar no formato abaixo:

Elemento Contedo
1 Ttulo do campo
2 Nome do campo
3 Mscara do campo
4 Tamanho do campo
5 Decimal do campo
6 Validao de usurio do campo
7 Uso do campo
8 Tipo do campo (caractere, numrico, data e etc.)
9 Prefixo da tabela
10 Contexto do campo (real ou virtual)

Varivel Private aCols

Vetor com as linhas a serem editadas. As colunas devem ser construdas com base no
vetor aHeader e mais uma ltima coluna com o valor lgico que determina se a linha
foi excluda, inicialmente esta dever ter o seu contedo igual a falso (F).

2.11.2 Estrutura de um programa utilizando a Modelo2()

O exemplo abaixo demonstra a montagem de um programa para a utilizao
do prottipo Modelo 2. Antes de iniciarmos o exemplo vamos estruturar o
programa.

Estrutura do programa

Linhas Programa
1 Funo principal;
2 Declarao e atribuio de variveis;
3 Acesso a tabela principal e sua ordem;
4 Chamada da funo MBrowse;
5 Fim da funo principal.
6
7 Funo de visualizao, alterao e excluso;
9
Acesso ao primeiro registro da chave em que est posicionado na
MBrowse;
10 Montagem das variveis estticas em tela;
11 Montagem do vetor aHeader por meio do dicionrio de dados;
12
Montagem do vetor aCOLS de todos os registros referentes chave
principal em que est posicionado na MBrowse;
13 Instncia da MsDialog;
14 Instncia dos objetos TSay e TGet;
15 Instncia do objeto MsGetDados;
16 Ativar o objeto principal que o objeto da janela;
17 Se for operao diferente de visualizao e clicou no boto OK;
18 A operao de Alterao?
19 Chamar a funo para alterar os dados;
20 Caso contrrio:
21 Chamar a funo para excluir os dados;
22 Fim da funo de visualizao, alterao e excluso.
23
24 Funo de incluso;
26 Montagem das variveis estticas em tela;
28
Montagem do vetor aCOLS com o seu contedo conforme o
inicializador padro do campo ou vazio, pois trata-se de uma incluso;
33 Se clicou no boto OK;
34 Chamar a funo para incluir os dados;
35 Fim da funo de incluso.

Rotina principal


//+-----------------------------------------------------------------
---+
//| Rotina | xModelo2 | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Funo exemplo do prottipo Modelo2.
|
//+-----------------------------------------------------------------
---+
//| Uso | Para treinamento e capacitao.
|
//+-----------------------------------------------------------------
---+
User Function xModelo2()
Private cCadastro := "Prottipo Modelo 2"

AADD( aRotina, {"Pesquisar" ,"AxPesqui" ,0,1})
AADD( aRotina, {"Visualizar" ,'U_Mod2Mnt',0,2})
AADD( aRotina, {"Incluir" ,'U_Mod2Inc',0,3})
AADD( aRotina, {"Alterar" ,'U_Mod2Mnt',0,4})
AADD( aRotina, {"Excluir" ,'U_Mod2Mnt',0,5})

dbSelectArea("ZA3")
dbSetOrder(1)
dbGoTop()

MBrowse(,,,,"ZA3")
Return

Rotina de incluso

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2Inc | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para incluir dados.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+

User Function Mod2Inc( cAlias, nReg, nOpc )
Local oDlg
Local oGet
Local oTPanel1
Local oTPAnel2

Local cCodigo := ZA3->ZA3_CODIGO
Local cNome := ZA3->ZA3_NOME
Local dData := dDataBase

Private aHeader := {}
Private aCOLS := {}
Private aREG := {}

dbSelectArea( cAlias )
dbSetOrder(1)

Mod2aHeader( cAlias )
Mod2aCOLS( cAlias, nReg, nOpc )

DEFINE MSDIALOG oDlg TITLE cCadastro From 8,0 To 28,80 OF
oMainWnd

oTPanel1 := TPanel():New(0,0,"",oDlg,NIL,.T.,;
.F.,NIL,NIL,0,16,.T.,.F.)

oTPanel1:Align := CONTROL_ALIGN_TOP

@ 4, 006 SAY "Cdigo:" SIZE 70,7 PIXEL OF oTPanel1
@ 4, 062 SAY "Nome:" SIZE 70,7 PIXEL OF oTPanel1
@ 4, 166 SAY "Emissao:" SIZE 70,7 PIXEL OF oTPanel1

@ 3, 026 MSGET cCodigo F3 "SA3" PICTURE "@!" VALID;
Mod2Vend(cCodigo, @cNome);
SIZE 030,7 PIXEL OF oTPanel1

@ 3, 080 MSGET cNome When .F. SIZE 78,7 PIXEL OF oTPanel1
@ 3, 192 MSGET dData PICTURE "99/99/99" SIZE 40,7 PIXEL
OF
oTPanel1

.F.,NIL,NIL,0,16,.T.,.F.)
oTPanel2:Align := CONTROL_ALIGN_BOTTOM

oGet := MSGetDados():New(0,0,0,0,nOpc,"U_Mod2LOk()",;
".T.","+ZA3_ITEM",.T.)
oGet:oBrowse:Align := CONTROL_ALIGN_ALLCLIENT

ACTIVATE MSDIALOG oDlg CENTER ON INIT ;
EnchoiceBar(oDlg,{|| IIF(U_Mod2TOk(), Mod2GrvI(),;
( oDlg:End(), NIL ) )},{|| oDlg:End() })

Return

Rotina de Visualizao, Alterao e Excluso

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2Mnt | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para Visualizar, Alterar e Excluir dados.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+

User Function Mod2Mnt( cAlias, nReg, nOpc )

Local oDlg
Local oGet
Local oTPanel1
Local oTPAnel2

Local cCodigo := Space(Len(Space(ZA3->ZA3_CODIGO)))
Local cNome := Space(Len(Space(ZA3->ZA3_NOME)))
Local dData := Ctod(Space(8))

Private aCOLS := {}
Private aREG := {}

dbGoTo( nReg )

cCodigo := ZA3->ZA3_CODIGO
cNome := ZA3->ZA3_NOME
cData := ZA3->ZA3_DATA

Mod2aHeader( cAlias )
Mod2aCOLS( cAlias, nReg, nOpc )

DEFINE MSDIALOG oDlg TITLE cCadastro From 8,0 To 28,80 OF
oMainWnd

oTPane1 := TPanel():New(0,0,"",oDlg,NIL,.T.,;
.F.,NIL,NIL,0,16,.T.,.F.)
oTPane1:Align := CONTROL_ALIGN_TOP

@ 4, 006 SAY "Cdigo:" SIZE 70,7 PIXEL OF oTPanel1
@ 4, 062 SAY "Nome:" SIZE 70,7 PIXEL OF oTPanel1
@ 4, 166 SAY "Emissao:" SIZE 70,7 PIXEL OF oTPanel1

@ 3, 026 MSGET cCodigo When .F. SIZE 30,7 PIXEL OF
oTPanel1
@ 3, 080 MSGET cNome When .F. SIZE 78,7 PIXEL OF
oTPanel1
@ 3, 192 MSGET dData When .F. SIZE 40,7 PIXEL OF
oTPanel1

.F.,NIL,NIL,0,16,.T.,.F.)
oTPanel2:Align := CONTROL_ALIGN_BOTTOM

If nOpc == 4
oGet := MSGetDados():New(0,0,0,0,nOpc,"U_Mod2LOk()",;
".T.","+ZA3_ITEM",.T.)
Else
oGet := MSGetDados():New(0,0,0,0,nOpc)
Endif
oGet:oBrowse:Align := CONTROL_ALIGN_ALLCLIENT

ACTIVATE MSDIALOG oDlg CENTER ON INIT ;
EnchoiceBar(oDlg,{|| ( IIF( nOpc==4, Mod2GrvA(), ;
IIF( nOpc==5, Mod2GrvE(), oDlg:End() ) ), oDlg:End() ) },;
{|| oDlg:End() })
Return

Montagem do array aHeader

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2aHeader | Autor | Robson Luiz (rleg)
|Data|01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para montar o vetor aHeader.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+

Static Function Mod2aHeader( cAlias )

dbSelectArea("SX3")
dbSetOrder(1)
dbSeek( cAlias )
While !EOF() .And. X3_ARQUIVO == cAlias
If X3Uso(X3_USADO) .And. cNivel >= X3_NIVEL
AADD( aHeader, { Trim( X3Titulo() ),;
X3_CAMPO,;
X3_PICTURE,;
X3_TAMANHO,;
X3_DECIMAL,;
X3_VALID,;
X3_USADO,;
X3_TIPO,;
X3_ARQUIVO,;
X3_CONTEXT})
Endif
dbSkip()
End
RestArea(aArea)
Return

Montagem do array aCols

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2aCOLS | Autor | Robson Luiz (rleg) |Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para montar o vetor aCOLS.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod2aCOLS( cAlias, nReg, nOpc )
Local cChave := ZA3->ZA3_CODIGO
Local nI := 0

If nOpc <> 3
dbSetOrder(1)
dbSeek( xFilial( cAlias ) + cChave )
While !EOF() .And. ;
ZA3->( ZA3_FILIAL + ZA3_CODIGO ) == xFilial( cAlias ) +
cChave
AADD( aREG, ZA3->( RecNo() ) )
AADD( aCOLS, Array( Len( aHeader ) + 1 ) )
For nI := 1 To Len( aHeader )
If aHeader[nI,10] == "V"
aCOLS[Len(aCOLS),nI] :=
CriaVar(aHeader[nI,2],.T.)
Else
FieldGet(FieldPos(aHeader[nI,2]))
Endif
Next nI
aCOLS[Len(aCOLS),Len(aHeader)+1] := .F.
dbSkip()
End
Else
aCOLS[1, nI] := CriaVar( aHeader[nI, 2], .T. )
Next nI
aCOLS[1, GdFieldPos("ZA3_ITEM")] := "01"
aCOLS[1, Len( aHeader )+1 ] := .F.
Endif
Restarea( aArea )
Return
Efetivao da incluso

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2GrvI | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para gravar os dados na incluso.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod2GrvI()
Local nI := 0
Local nX := 0

dbSelectArea("ZA3")
dbSetOrder(1)
For nI := 1 To Len( aCOLS )
If ! aCOLS[nI,Len(aHeader)+1]
RecLock("ZA3",.T.)
ZA3->ZA3_FILIAL := xFilial("ZA3")
ZA3->ZA3_CODIGO := cCodigo
ZA3->ZA3_DATA := dData
For nX := 1 To Len( aHeader )
FieldPut( FieldPos( aHeader[nX, 2] ),
aCOLS[nI, nX] )
Next nX
MsUnLock()
Endif
Next nI

RestArea(aArea)
Return

Efetivao da alterao

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2GrvA | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para gravar os dados na alterao.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod2GrvA()
Local nI := 0
Local nX := 0

dbSelectArea("ZA3")
For nI := 1 To Len( aREG )
If nI <= Len( aREG )
dbGoTo( aREG[nI] )
RecLock("ZA3",.F.)
If aCOLS[nI, Len(aHeader)+1]
dbDelete()
Endif
Else
RecLock("ZA3",.T.)
Endif

If !aCOLS[nI, Len(aHeader)+1]
ZA3->ZA3_CODIGO := cCodigo
ZA3->ZA3_DATA := dData
For nX := 1 To Len( aHeader )
FieldPut( FieldPos( aHeader[nX, 2] ),
aCOLS[nI, nX] )
Next nX
Endif
MsUnLock()
Next nI
RestArea( aArea )
Return

Efetivao da excluso
//+-----------------------------------------------------------------
---+
//| Rotina | Mod2GrvE | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para excluir os registros.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod2GrvE()
Local nI := 0

dbSelectArea("ZA3")
dbGoTo(aREG[nI])
RecLock("ZA3",.F.)
dbDelete()
MsUnLock()
Next nI
Return

Funo auxiliar: Validao do cdigo do vendedor
//+-----------------------------------------------------------------
---+
//| Rotina | Mod2Vend | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para validar o cdigo do vendedor.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod2Vend( cCodigo, cNome )
If ExistCpo("SA3",cCodigo) .And. ExistChav("ZA3",cCodigo)
cNome :=
Posicione("SA3",1,xFilial("SA3")+cCodigo,"A3_NOME")
Endif
Return(!Empty(cNome))

Funo auxiliar: Validao do cdigo do centro de custo na mudana de linha

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2LOk | Autor | Robson Luiz (rleg) | Data
|01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para validar a linha de dados.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
User Function Mod2LOk()
Local lRet := .T.
Local cMensagem := "No ser permitido linhas sem o centro de
custo."
If !aCOLS[n, Len(aHeader)+1]
If Empty(aCOLS[n,GdFieldPos("ZA3_CCUSTO")])
MsgAlert(cMensagem,cCadastro)
lRet := .F.
Endif
Endif
Return( lRet )

Funo auxiliar: Validao do cdigo do centro de custo para todas as linhas

//+-----------------------------------------------------------------
---+
//| Rotina | Mod2TOk | Autor | Robson Luiz (rleg) | Data
|01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para validar toda as linhas de dados.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+

User Function Mod2TOk()
Local lRet := .T.
Local nI := 0
Local cMensagem := "No ser permitido linhas sem o centro de
custo."

Loop
Endif
If !aCOLS[nI, Len(aHeader)+1]
If Empty(aCOLS[n,GdFieldPos("ZA3_CCUSTO")])
MsgAlert(cMensagem,cCadastro)
lRet := .F.
Exit
Endif
Endif
Next nI
Return( lRet )

2.11.3 Funo Modelo2()

A funo Modelo2() uma interface pr-definida pela Microsiga que
implementa de forma padronizada os compontes necessrios manipulao de
estruturas de dados nas quais o cabealho e os itens da informao
compartilham o mesmo registro fsico.

Seu objetivo atuar como um facilitador de codificao, permitindo a utilizao
dos recursos bsicos dos seguintes componentes visuais:
Q MsDialog()
Q TGet()
Q TSay()
Q MsNewGetDados()
Q EnchoiceBar()

Q A funo Modelo2() no implementa as regras de visualizao,
incluso, alterao e excluso, como uma AxCadastro() ou
AxFunction().

Q A inicializao das variveis Private utilizada nos cabealhos e
rodaps, bem como a inicializao e gravao do aCols devem
ser realizadas pela rotina que suporta a execuo da
Modelo2().

Q Da mesma forma, o Browse deve ser tratado por esta rotina,
sendo comum a funo Modelo2() estar vinculada ao uso de
uma funo MBrowse().

E Sintaxe: Modelo2([cTitulo], [aCab], [aRoda], [aGrid], [nOpc], [cLinhaOk],
[cTudoOk])

E Parmetros:

cTitulo Ttulo da janela
aCab Array contendo as informaes que sero exibidas no cabealho na
forma de Enchoice()
aCab[n][1] (Caractere) := Nome da varivel private que ser vinculada
ao campo da Enchoice().
aCab[n][2] (Array) := Array com as coordenadas do campo na tela
{Linha, Coluna}
aCab[n][3] (Caractere) := Ttulo do campo na tela
aCab[n][4] (Caractere) := Picture de formatao do get() do campo.
aCab[n][5] (Caractere) := Funo de validao do get() do campo.
aCab[n][6] (Caractere) := Nome da consulta padro que ser executada
para o campo via tecla F3
aCab[n][7] (Lgico) := Se o campo estar livre para digitao.

aRoda Array contendo as informaes que sero exibidas no cabealho na
forma de Enchoice(), no mesmo formato que o aCab.
aGrid Array contendo as coordenadas da GetDados() na tela. Padro :=
{44,5,118,315}
nOpc Opo selecionada na fuo MBrowse, ou que deseje ser passada para
controle da Modelo2, aonde:
2 Visualizar
3 - Incluir
4 - Alterar
5 - Excluir
cLinhaOk Funo para validao da linha na GetDados()
cTudoOk Funo para validao na confirmao da tela de interface da funo
Modelo2().

E Retorno:

Lgico Indica se a tela da interface Modelo2() foi confirmada ou cancelada pelo usurio.

Exemplo: Utilizao da Modelo2() para visualizao do Cadastro de Tabelas (SX5)


//+-----------------------------------------------------------------
---+
//| Rotina | MBRW2SX5| Autor | ARNALDO RAYMUNDO JR. | Data
|01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | UTILIZACAO DA MODELO2() PARA VISUALIZAO DO SX5.
|
//+-----------------------------------------------------------------
---+
//| Uso | CURSO DE ADVPL
|
//+-----------------------------------------------------------------
---+

USER FUNCTION MBrw2Sx5()

Local cAlias := "SX5"

Private cCadastro := "Arquivo de Tabelas"
Private cDelFunc := ".T." // Validacao para a exclusao. Pode-
se utilizar ExecBlock

AADD(aRotina,{"Visualizar" ,"U_SX52Vis" ,0,2})
AADD(aRotina,{"Incluir" ,"U_SX52Inc" ,0,3})
AADD(aRotina,{"Alterar" ,"U_SX52Alt" ,0,4})
AADD(aRotina,{"Excluir" ,"U_SX52Exc" ,0,5})

dbSetOrder(1)
mBrowse( 6,1,22,75,cAlias)

Return

USER FUNCTION SX52INC(cAlias,nReg,nOpc)

//Local nUsado := 0
Local cTitulo := "Inclusao de itens - Arquivo de Tabelas"
Local aCab := {} // Array com descricao dos campos do
Cabecalho do Modelo 2
Local aRoda := {} // Array com descricao dos campos do
Rodape do Modelo 2
Local aGrid := {80,005,050,300} //Array com coordenadas
da GetDados no modelo2 - Padrao: {44,5,118,315}
// Linha Inicial - Coluna Inicial - +Qts
Linhas - +Qts Colunas : {080,005,050,300}
Local cLinhaOk := "AllwaysTrue()" // Validacoes na linha da
GetDados da Modelo 2
Local cTudoOk := "AllwaysTrue()" // Validacao geral da GetDados
da Modelo 2
Local lRetMod2 := .F. // Retorno da funo Modelo2 - .T. Confirmou
/ .F. Cancelou
Local nColuna := 0

// Variaveis para GetDados()
Private aCols := {}

// Variaveis para campos da Enchoice()
Private cX5Filial := xFilial("SX5")
Private cX5Tabela := SPACE(5)

// Montagem do array de cabealho
// AADD(aCab,{"Varivel" ,{L,C}
,"Ttulo","Picture","Valid","F3",lEnable})
AADD(aCab,{"cX5Filial" ,{015,010} ,"Filial","@!",,,.F.})
AADD(aCab,{"cX5Tabela" ,{015,080} ,"Tabela","@!",,,.T.})

// Montagem do aHeader
AADD(aHeader,{"Chave" ,"X5_CHAVE","@!",5,0,"AllwaysTrue()",;
"","C","","R"})
AADD(aHeader,{"Descricao"
,"X5_DESCRI","@!",40,0,"AllwaysTrue()",;
"","C","","R"})

// Montagem do aCols
aCols := Array(1,Len(aHeader)+1)

// Inicializao do aCols
For nColuna := 1 to Len(aHeader)

If aHeader[nColuna][8] == "C"
aCols[1][nColuna] := SPACE(aHeader[nColuna][4])
ElseIf aHeader[nColuna][8] == "N"
aCols[1][nColuna] := 0
ElseIf aHeader[nColuna][8] == "D"
aCols[1][nColuna] := CTOD("")
ElseIf aHeader[nColuna][8] == "L"
aCols[1][nColuna] := .F.
ElseIf aHeader[nColuna][8] == "M"
aCols[1][nColuna] := ""
Endif

Next nColuna

aCols[1][Len(aHeader)+1] := .F. // Linha no deletada
lRetMod2 := Modelo2(cTitulo,aCab,aRoda,aGrid,nOpc,cLinhaOk,cTudoOk)

IF lRetMod2
//MsgInfo("Voc confirmou a operao","MBRW2SX5")
For nLinha := 1 to len(aCols)
// Campos de Cabealho
Reclock("SX5",.T.)
SX5->X5_FILIAL := cX5Filial
SX5->X5_TABELA := cX5Tabela
// Campos do aCols
//SX5->X5_CHAVE := aCols[nLinha][1]
//SX5->X5_DESCRI := aCols[nLinha][2]
For nColuna := 1 to Len(aHeader)
SX5->&(aHeader[nColuna][2]) :=
aCols[nLinha][nColuna]
Next nColuna
MsUnLock()
Next nLinha
ELSE
MsgAlert("Voc cancelou a operao","MBRW2SX5")
ENDIF
Return

Exerccio 08
Implementar uma Modelo2() para a tabela padro do ERP SX5: Arquivo de
Tabelas

Exerccio 09
Implementar as funes de Visualizao, Alterao e Excluso para a Modelo2
desenvolvida para o SX5.

Exerccio 10
Implementar uma Modelo2() para a tabela padro do ERP SB1: Tabela de
Produtos

2.12 Modelo3()

O nome Modelo 3, assim como a Modelo 2 foi conceituado pela Microsiga por se tratar
de um prottipo de tela para entrada de dados. Inicialmente, vamos desmistificar dois
pontos:

Q Funo Modelo3() Trata-se de uma funo pronta que contempla o
prottipo Modelo 3, porm, este um assunto que no iremos tratar
aqui, visto que uma funcionalidade simples que quando necessrio
intervir em algo na rotina no h muito recurso para tal.

Q Prottipo Modelo 3 Trata-se de uma tela, como a figura abaixo, onde
seu objetivo efetuar a manuteno em vrios registros de uma s vez
relacionada a outro registro de outra tabela, ou seja, aqui teremos o
relacionamento de registros pai e filho. Ento, preciso se preocupar
com este relacionamento. Por exemplo: efetuar a manuteno em um
pedido de vendas, onde ter um registro em uma tabela referente
cabea do pedido, e, outra tabela, com os registros referentes aos itens
deste pedido de vendas.

Para ganharmos tempo no ser apresentada aqui toda a explicao e as montagens
para a funo EnchoiceBar, comando MsDialog, Say e MsGet e para os vetores
aHeader e aCOLS. Entretanto, todos estes estaro na codificao do cdigo fonte. A
figura abaixo mostra exatamente o que a tela prottipo Modelo 3:


Figura: Prottipo Modelo 3

Este prottipo constitudo de MsDialog, EnchoiceBar, Enchoice, MsGetDados, Say e
Get.

Diante dos expostos at o momento houve um novo nome para ns, ele a funo
Enchoice, o que ?

Funo Enchoice() Objeto MsMGet()

A funo Enchoice ou o objeto MsMGet so recursos baseados no dicionrio de dados
para verificar campos obrigatrios, validaes, gatilhos, consulta padro e etc. Assim
tambm para criar pastas de cadastros. Estes podem ser usados tanto com variveis de
memrias com o escopo Private como diretamente os campos da tabela que se refere.
A diferena entre a funo Enchoice e o objeto MsMGet que a funo no retorna o
nome da varivel de objeto exportvel criado.

A estrutura para montar um programa com o prottipo modelo 3 semelhante ao
prottipo modelo 2, porm a diferena real a utilizao da funo Enchoice ou o
objeto MsMGet, para este documento iremos trabalhar com a funo.

E Sintaxe: Enchoice( cAlias, nReg, nOpc, aAc, cOpc, cTextExclui, aAcho, aPos,
aCpos, nNum, nColMens, cMensagem, cTudOk, oObj, lVirtual)

E Parmetros:

cAlias Alias do dados a serem cadastrados.
nReg Nmero do registro da tabela a ser editado.
aAcho Vetor com os campos que sero apresentados pela MsMGet.
aPos Vetor com as coordenadas onde a MsMGet ser criada no formato
{coord. superior, coord. esquerda, coord. direita, coord. inferior}.
Funo executada para validar o contexto da linha atual do aCols.
aCpos Vetor com os campos que podero ser alterados.
uPar4 Parmetro reservado. Nome dos campos do tipo caracter que
utilizaro incremento automtico. Este parmetro deve ser no
formato +<nome do primeiro campo>+<nome do segundo
campo>+....
oWnd Objeto no qual a MsMGet ser criada.
lMemoria Indica se sero usadas variveis de memria ou os campos da
tabela para cadastramento dos dados. Valor padro falso.
lColuna Indica se a MsMGet ser apresentada com um objeto por linha
(uma coluna). Valor padro falso. Parmetro reservado.
lSemPastas Indica se no sero usadas as Pastas de Cadastro na MsMGet.
Funo executada para validar a excluso de uma linha do aCols.

Vale lembrar que ns programadores reaproveitamos muito o que j existe, isto para
simplesmente ganharmos tempo, e no caso da utilizao da funo Enchoice preciso
criar as variveis de memrias que levam o mesmo nome dos campos da tabela em
questo. Por exemplo, o campo A2_NOME da tabela SA2 (cadastro de fornecedores)
quando queremos referenciar o campo, usa-se o prefixo da tabela e o campo em
questo, desta forma:

SA2->A2_NOME

Agora quando queremos referenciar a uma varivel que est com o contedo do
mesmo campo criamos outro recurso, desta forma:

M->A2_NOME


E para criar variveis com o nome do campo utilizamos um cdigo de bloco (code-
block) e mais um lao de leitura para atribuir valores iniciais a cada uma delas. Ento, o
procedimento o seguinte:

Private bCampo := { |nField| Field(nField) }

E em outro momento, aproveitamos a varivel bCampo para facilitar a atribuio. Veja
o exemplo abaixo :

For nX := 1 To FCount()
M->&( Eval( bCampo, nX ) ) := Atribuio inicial ou atribuio de
valor
Next nX

Ou seja, fazer para todos os campos, e a cada campo criar a varivel com a atribuio
inicial ou atribuio de valor.

2.12.1 Estrutura de um programa utilizando a Modelo3()

O exemplo abaixo demonstra a montagem de um programa para a utilizao do
prottipo Modelo 3. Antes de iniciarmos o exemplo, vamos estruturar o programa.


Linhas Programa
1 Funo principal;
3 Acesso tabela principal e sua ordem;
4 Chamada da funo MBrowse;
6
7 Funo de visualizao, alterao e excluso;
9
Acesso ao primeiro registro da chave em que est posicionado na
MBrowse;
10 Construo das variveis de memria M->???;
11 Montagem do vetor aHeader por meio do Dicionrio de Dados;
12
Montagem do vetor aCOLS de todos os registros referente a chave
principal em que est posicionado na MBrowse;
14 Execuo da funo Enchoice;
17 Se for operao diferente de visualizao e clicou no boto OK;
18 A operao de Alterao?
19 Chamar a funo para alterar os dados;
20 Caso contrrio:
21 Chamar a funo para excluir os dados;
22 Fim da funo de visualizao, alterao e excluso.
23
24 Funo de incluso;
26 Construo das variveis de memria M->???;
28
Montagem do vetor aCOLS com o seu contedo conforme o
inicializador padro do campo ou vazio, pois trata-se de uma incluso;
33 Se clicou no boto OK;
34 Chamar a funo para incluir os dados;
35 Fim da funo de incluso.

Rotina principal

//+-----------------------------------------------------------------
---+
//| Rotina | xModelo3 | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Funo exemplo do prottipo Modelo3.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+

User Function xModelo3()
Private cCadastro := "Prottipo Modelo 3"
Private oCliente
Private oTotal
Private cCliente := ""
Private nTotal := 0

Private bCampo := {|nField| FieldName(nField) }

Private aSize := {}
Private aInfo := {}
Private aObj := {}
Private aPObj := {}
Private aPGet := {}

// Retorna a rea til das janelas Protheus
aSize := MsAdvSize()

// Ser utilizado trs reas na janela
// 1 - Enchoice, sendo 80 pontos pixel
// 2 - MsGetDados, o que sobrar em pontos pixel para este objeto
// 3 - Rodap que a prpria janela, sendo 15 pontos pixel
AADD( aObj, { 100, 080, .T., .F. })
AADD( aObj, { 100, 100, .T., .T. })
AADD( aObj, { 100, 015, .T., .F. })

// Clculo automtico da dimenses dos objetos (altura/largura) em
pixel
aInfo := { aSize[1], aSize[2], aSize[3], aSize[4], 3, 3 }
aPObj := MsObjSize( aInfo, aObj )

// Clculo automtico de dimenses dos objetos MSGET
aPGet := MsObjGetPos( (aSize[3] - aSize[1]), 315, { {004, 024, 240,
270} } )

AADD( aRotina, {"Pesquisar" ,"AxPesqui" ,0,1})
AADD( aRotina, {"Visualizar" ,'U_Mod3Mnt',0,2})
AADD( aRotina, {"Incluir" ,'U_Mod3Inc',0,3})
AADD( aRotina, {"Alterar" ,'U_Mod3Mnt',0,4})
AADD( aRotina, {"Excluir" ,'U_Mod3Mnt',0,5})

dbSelectArea("ZA1")
dbSetOrder(1)
dbGoTop()
MBrowse(,,,,"ZA1")
Return

Funo de Incluso

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3Inc | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para incluir dados.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
User Function Mod3Inc( cAlias, nReg, nOpc )
Local oDlg
Local oGet
Local nX := 0
Local nOpcA := 0

Private aCOLS := {}
Private aGets := {}
Private aTela := {}

dbSetOrder(1)

M->&( Eval( bCampo, nX ) ) := CriaVar( FieldName( nX ), .T. )
Next nX

Mod3aHeader()
Mod3aCOLS( nOpc )

DEFINE MSDIALOG oDlg TITLE cCadastro FROM ;
aSize[7],aSize[1] TO aSize[6],aSize[5] OF oMainWnd PIXEL
EnChoice( cAlias, nReg, nOpc, , , , , aPObj[1])

// Atualizao do nome do cliente
@ aPObj[3,1],aPGet[1,1] SAY "Cliente: " SIZE 70,7 OF oDlg PIXEL
@ aPObj[3,1],aPGet[1,2] SAY oCliente VAR cCliente SIZE 98,7 OF
oDlg PIXEL

// Atualizao do total
@ aPObj[3,1],aPGet[1,3] SAY "Valor Total: " SIZE 70,7 OF oDlg
PIXEL
@ aPObj[3,1],aPGet[1,4] SAY oTotal VAR nTotal ;
PICT "@E 9,999,999,999.99" SIZE 70,7 OF oDlg PIXEL

oGet :=
MSGetDados():New(aPObj[2,1],aPObj[2,2],aPObj[2,3],aPObj[2,4],;
nOpc,"U_Mod3LOk()",".T.","+ZA2_ITEM",.T.)

ACTIVATE MSDIALOG oDlg ON INIT EnchoiceBar(oDlg,;
{|| IIF( Mod3TOk().And.Obrigatorio( aGets, aTela ), ( nOpcA := 1,
oDlg:End() ), NIL) },;
{|| oDlg:End() })

If nOpcA == 1 .And. nOpc == 3
Mod3Grv( nOpc )
ConfirmSXE()
Endif
Return

Funo de Visualizao, Alterao e Excluso

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3Mnt | Autor | Robson Luiz (rleg) | Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para Visualizar, Alterar e Excluir dados.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
User Function Mod3Mnt( cAlias, nReg, nOpc )
Local oDlg
Local oGet
Local nX := 0
Local nOpcA := 0
Private aCOLS := {}
Private aGets := {}
Private aTela := {}
Private aREG := {}

dbSetOrder(1)

M->&( Eval( bCampo, nX ) ) := FieldGet( nX )
Next nX

Mod3aHeader()
Mod3aCOLS( nOpc )
DEFINE MSDIALOG oDlg TITLE cCadastro FROM ;
aSize[7],aSize[1] TO aSize[6],aSize[5] OF oMainWnd PIXEL
EnChoice( cAlias, nReg, nOpc, , , , , aPObj[1])

// Atualizao do nome do cliente
@ aPObj[3,1],aPGet[1,1] SAY "Cliente: " SIZE 70,7 OF oDlg PIXEL
@ aPObj[3,1],aPGet[1,2] SAY oCliente VAR cCliente SIZE 98,7 OF
oDlg PIXEL

// Atualizao do total
@ aPObj[3,1],aPGet[1,3] SAY "Valor Total: " SIZE 70,7 OF oDlg
PIXEL
@ aPObj[3,1],aPGet[1,4] SAY oTotal VAR nTotal PICTURE ;
"@E 9,999,999,999.99" SIZE 70,7 OF oDlg PIXEL

U_Mod3Cli()

oGet :=
MSGetDados():New(aPObj[2,1],aPObj[2,2],aPObj[2,3],aPObj[2,4],;
nOpc,"U_Mod3LOk()",".T.","+ZA2_ITEM",.T.)

ACTIVATE MSDIALOG oDlg ON INIT EnchoiceBar(oDlg,;
{|| IIF( Mod3TOk().And.Obrigatorio( aGets, aTela ), ( nOpcA := 1,
oDlg:End() ), NIL ) },;
{|| oDlg:End() })

If nOpcA == 1 .And. ( nOpc == 4 .Or. nOpc == 5 )
Mod3Grv( nOpc, aREG )
Endif
Return

Funo para montar o vetor aHeader

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3aHeader | Autor | Robson Luiz (rleg)
|Data|01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para montar o vetor aHeader.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod3aHeader()

dbSelectArea("SX3")
dbSetOrder(1)
dbSeek("ZA2")
While !EOF() .And. X3_ARQUIVO == "ZA2"
If X3Uso(X3_USADO) .And. cNivel >= X3_NIVEL
AADD( aHeader, { Trim( X3Titulo() ),;
X3_CAMPO,;
X3_PICTURE,;
X3_TAMANHO,;
X3_DECIMAL,;
X3_VALID,;
X3_USADO,;
X3_TIPO,;
X3_ARQUIVO,;
X3_CONTEXT})
Endif
dbSkip()
End
RestArea(aArea)
Return

Funo para montar o vetor aCols

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3aCOLS | Autor | Robson Luiz (rleg) |Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para montar o vetor aCOLS.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod3aCOLS( nOpc )
Local cChave := ""
Local cAlias := "ZA2"
Local nI := 0

If nOpc <> 3
cChave := ZA1->ZA1_NUM

dbSetOrder(1)
dbSeek( xFilial( cAlias ) + cChave )
While !EOF() .And. ZA2->( ZA2_FILIAL + ZA2_NUM ) == xFilial(
cAlias ) + cChave
AADD( aREG, ZA2->( RecNo() ) )
If aHeader[nI,10] == "V"
CriaVar(aHeader[nI,2],.T.)
Else
FieldGet(FieldPos(aHeader[nI,2]))
Endif
Next nI
aCOLS[Len(aCOLS),Len(aHeader)+1] := .F.
dbSkip()
End
Else
aCOLS[1, nI] := CriaVar( aHeader[nI, 2], .T. )
Next nI
aCOLS[1, GdFieldPos("ZA2_ITEM")] := "01"
aCOLS[1, Len( aHeader )+1 ] := .F.
Endif
Restarea( aArea )
Return

Funo para atribuir o nome do cliente a varivel

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3Cli | Autor | Robson Luiz (rleg) |Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para atualizar a varivel com o nome do cliente.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+

User Function Mod3Cli()
cCliente := Posicione( "SA1", 1, xFilial("SA1") + M->(ZA1_CLIENT +
ZA1_LOJA), "A1_NREDUZ" )
oCliente:Refresh()
Return(.T.)


Funo para validar a mudana de linha na MsGetDados()

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3LOk | Autor | Robson Luiz (rleg) |Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para atualizar a varivel com o total dos itens.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
User Function Mod3LOk()
Local nI := 0
nTotal := 0
If aCOLS[nI,Len(aHeader)+1]
Loop
Endif
nTotal+=Round(aCOLS[nI,GdFieldPos("ZA2_QTDVEN")]*;
aCOLS[nI,GdFieldPos("ZA2_PRCVEN")],2)
Next nI
oTotal:Refresh()
Return(.T.)

Funo para validar se todas as linhas esto preenchidas

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3TOk | Autor | Robson Luiz (rleg) |Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para validar os itens se foram preenchidos.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod3TOk()
Local nI := 0
Local lRet := .T.

For nI := 1 To Len(aCOLS)
Loop
Endif
If Empty(aCOLS[nI,GdFieldPos("ZA2_PRODUT")]) .And. lRet
MsgAlert("Campo PRODUTO preenchimento obrigatorio",cCadastro)
lRet := .F.
Endif
If Empty(aCOLS[nI,GdFieldPos("ZA2_QTDVEN")]) .And. lRet
MsgAlert("Campo QUANTIDADE preenchimento
obrigatorio",cCadastro)
lRet := .F.
Endif
If Empty(aCOLS[nI,GdFieldPos("ZA2_PRCVEN")]) .And. lRet
MsgAlert("Campo PRECO UNITARIO preenchimento
obrigatorio",cCadastro)
lRet := .F.
Endif

If !lRet
Exit
Endif
Next i
Return( lRet )

//+-----------------------------------------------------------------
---+
//| Rotina | Mod3Grv | Autor | Robson Luiz (rleg) |Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | Rotina para efetuar a gravao nas tabelas.
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+
Static Function Mod3Grv( nOpc, aAltera )
Local nX := 0
Local nI := 0

// Se for incluso
If nOpc == 3
// Grava os itens
dbSelectArea("ZA2")
dbSetOrder(1)
For nX := 1 To Len( aCOLS )
If !aCOLS[ nX, Len( aCOLS ) + 1 ]
RecLock( "ZA2", .T. )
FieldPut( FieldPos( Trim( aHeader[nI, 2] ) ),
aCOLS[nX,nI] )
Next nI
ZA2->ZA2_NUM := M->ZA1_NUM
MsUnLock()
Endif
Next nX

// Grava o Cabealho
dbSelectArea( "ZA1" )
If "FILIAL" $ FieldName( nX )
FieldPut( nX, xFilial( "ZA1" ) )
Else
FieldPut( nX, M->&( Eval( bCampo, nX ) ) )
Endif
Next nX
MsUnLock()
Endif

// Se for alterao
If nOpc == 4
// Grava os itens conforme as alteraes
dbSelectArea("ZA2")
dbSetOrder(1)
For nX := 1 To Len( aCOLS )
If nX <= Len( aREG )
dbGoto( aREG[nX] )
RecLock("ZA2",.F.)
If aCOLS[ nX, Len( aHeader ) + 1 ]
dbDelete()
Endif
Else

If !aCOLS[ nX, Len( aHeader ) + 1 ]
Endif
Endif

If !aCOLS[ nX, Len(aHeader)+1 ]
FieldPut( FieldPos( Trim( aHeader[ nI, 2] )
),;
aCOLS[ nX, nI ] )
Next nI
ZA2->ZA2_NUM := M->ZA1_NUM
Endif
MsUnLock()
Next nX

// Grava o Cabealho
dbSelectArea("ZA1")
RecLock( "ZA1", .F. )
If "FILIAL" $ FieldName( nX )
FieldPut( nX, xFilial("ZA1"))
Else
FieldPut( nX, M->&( Eval( bCampo, nX ) ) )
Endif
Next
MsUnLock()
Endif

// Se for excluso
If nOpc == 5
// Deleta os Itens
dbSelectArea("ZA2")
dbSetOrder(1)
dbSeek(xFilial("ZA2") + M->ZA1_NUM)
While !EOF() .And. ZA2->(ZA2_FILIAL + ZA2_NUM) ==
xFilial("ZA2") +;
M->ZA1_NUM
RecLock("ZA2")
dbDelete()
MsUnLock()
dbSkip()
End

// Deleta o Cabealho
dbSelectArea("ZA1")
RecLock("ZA1",.F.)
dbDelete()
MsUnLock()
Endif
Return

2.12.2 Funo Modelo3()

A funo Modelo3) uma interface pr-definida pela Microsiga que implementa de
forma padronizada os compontes necessrios e a manipulao de estruturas de dados
nas quais o cabealho e os itens da informao esto em tabelas separadas.

Seu objetivo atuar como um facilitador de codificao, permitindo a utilizao dos
recursos bsicos dos seguintes componentes visuais:

Q MsDialog()
Q Enchoice()
Q EnchoiceBar()
Q MsNewGetDados()

Q A funo Modelo3() no implementa as regras de visualizao,
incluso, alterao e excluso, como uma AxCadastro() ou
AxFunction().
Q A inicializao dos campos utilizados na Enchoice() deve ser
realizadas pela rotina que suporta a execuo da Modelo3(),
normalmente atravs do uso da funo RegToMemory().
Q Da mesma forma, o Browse deve ser tratado por esta rotina,
sendo comum a Modelo3() estar vinculada ao uso de uma
MBrowse().

E Sintaxe: Modelo3 ([cTitulo], [cAliasE], [cAliasGetD], [aCposE], [cLinOk],
[cTudOk], [nOpcE], [nOpcG], [cFieldOk])

E Parmetros:

cTitulo Ttulo da janela.
cAliasE Alias da tabela que ser utilizada na Enchoice.
cAliasGetD Alias da tabela que ser utilizada na GetDados.
aCposE
Nome dos campos, pertencentes ao Alias especificado o parmetro
cAliasE, que devero ser exibidos na Enchoice:
AADD(aCposE,{nome_campo}).
cLinhaOk Funo para validao da linha na GetDados().
cTudoOk
Funo para validao na confirmao da tela de interface da
Modelo2().
nOpcE
Opo selecionada na funo MBrowse, ou que deseje ser passada
para controle da funo Enchoice da funlo Modelo3, aonde:
2 Visualizar
3 - Incluir
4 - Alterar
5 - Excluir
nOpcG
Opo selecionada na funo MBrowse, ou que deva ser passada para
controle da funo GetDados da funo Modelo3, aonde:
2 Visualizar
3 - Incluir
4 - Alterar
5 - Excluir
cFieldOk Validao dos campos da funo Enchoice()

E Retorno:

Lgico Indica se a tela da interface Modelo2() foi confirmada ou cancelada pelo usurio.

Exemplo: Utilizao da Modelo3() para Pedidos de Vendas (SC5,SC6)

#INCLUDE "protheus.ch"

//+-----------------------------------------------------------------
---+
//| Rotina | MBRWMOD3| Autor | ARNALDO RAYMUNDO JR. |Data |
01.01.2007 |
//+-----------------------------------------------------------------
---+
//| Descr. | EXEMPLO DE UTILIZACAO DA MODELO3().
|
//+-----------------------------------------------------------------
---+
|
//+-----------------------------------------------------------------
---+

User Function MbrwMod3()

Private cCadastro := "Pedidos de Venda"
Private cDelFunc := ".T." // Validacao para a exclusao. Pode-
se utilizar ExecBlock
Private cAlias := "SC5"

AADD(aRotina,{ "Pesquisa","AxPesqui" ,0,1})
AADD(aRotina,{ "Visual" ,"U_Mod3All" ,0,2})
AADD(aRotina,{ "Inclui" ,"U_Mod3All" ,0,3})
AADD(aRotina,{ "Altera" ,"U_Mod3All" ,0,4})
AADD(aRotina,{ "Exclui" ,"U_Mod3All" ,0,5})

dbSetOrder(1)
mBrowse( 6,1,22,75,cAlias)

Return

User Function Mod3All(cAlias,nReg,nOpcx)

Local cTitulo := "Cadastro de Pedidos de Venda"
Local cAliasE := "SC5"
Local cAliasG := "SC6"
Local cLinOk := "AllwaysTrue()"
Local cTudOk := "AllwaysTrue()"
Local cFieldOk:= "AllwaysTrue()"
Local aCposE := {}
Local nUsado, nX := 0

//
// Opcoes de acesso para a Modelo 3
//
Do Case
Case nOpcx==3; nOpcE:=3 ; nOpcG:=3 // 3 - "INCLUIR"
Case nOpcx==4; nOpcE:=3 ; nOpcG:=3 // 4 - "ALTERAR"
Case nOpcx==2; nOpcE:=2 ; nOpcG:=2 // 2 - "VISUALIZAR"
Case nOpcx==5; nOpcE:=2 ; nOpcG:=2 // 5 - "EXCLUIR"
EndCase

//
// Cria variaveis M->????? da Enchoice
//
RegToMemory("SC5",(nOpcx==3 .or. nOpcx==4 )) // Se for inclusao ou
alteracao permite alterar o conteudo das variaveis de memoria

//
// Cria aHeader e aCols da GetDados
//
nUsado:=0
dbSelectArea("SX3")
dbSeek("SC6")
aHeader:={}
While !Eof().And.(x3_arquivo=="SC6")
If Alltrim(x3_campo)=="C6_ITEM"
dbSkip()
Loop
Endif
If X3USO(x3_usado).And.cNivel>=x3_nivel
nUsado:=nUsado+1
Aadd(aHeader,{ TRIM(x3_titulo), x3_campo, x3_picture,;
x3_tamanho, x3_decimal,"AllwaysTrue()",;
x3_usado, x3_tipo, x3_arquivo, x3_context } )
Endif
dbSkip()
End

If nOpcx==3 // Incluir
aCols:={Array(nUsado+1)}
aCols[1,nUsado+1]:=.F.
For nX:=1 to nUsado
aCols[1,nX]:=CriaVar(aHeader[nX,2])
Next
Else
aCols:={}
dbSelectArea("SC6")
dbSetOrder(1)
dbSeek(xFilial()+M->C5_NUM)
While !eof().and.C6_NUM==M->C5_NUM
AADD(aCols,Array(nUsado+1))
For nX:=1 to nUsado

aCols[Len(aCols),nX]:=FieldGet(FieldPos(aHeader[nX,2]))
Next
aCols[Len(aCols),nUsado+1]:=.F.
dbSkip()
End
Endif

If Len(aCols)>0
//
// Executa a Modelo 3

//
aCposE := {"C5_CLIENTE"}

lRetMod3 := Modelo3(cTitulo, cAliasE, cAliasG, aCposE, cLinOk,
cTudOk,;
nOpcE, nOpcG,cFieldOk)
//
// Executar processamento

//
If lRetMod3
Aviso("Modelo3()","Confirmada operacao!",{"Ok"})
Endif
Endif

Return

Exerccio 11
Implementar uma Modelo3() para as tabelas padres do ERP SF1: Cab. NFE e
SD1: Itens NFE

8. Arquivos e ndices Temporrios

2.13 Utilizao de arquivos e ndices temporrios

Os arquivos e ndices temporrios ou de trabalho, so geralmente utilizados em
ambiente CodeBase, pois, neste ambiente no h os recursos de Join e Order By,
como nos bancos de dados relacionais. Por este motivo, quando necessitar gerar uma
informao ordenada e consolidada (ou seja, de vrias tabelas), deveremos recorrer ao
uso dos arquivos e dos ndices temporrios.

2.14 Funes para manipulao de arquivos e ndices temporrios

2.14.1 CriaTrab()

A CriaTrab() uma funcionalidade que permite criar um arquivo fsico ou gerar um
nome aleatrio.

E Sintaxe: CriaTrab(aCampo, lCriar, cExt)

E Parmetros

aCampo
Array com o nome, tipo, tamanho e decimal do campo a ser criado no
arquivo
lCriar
Se verdadeiro (.T.) criar o arquivo, ou falso (.F.) somente retorna um nome
aleatrio
cExt Qual extenso dever ser criado o arquivo de trabalho

Os arquivos criados com a funo CRIATRAB() sero gerados no
diretrio especificado como StartPath, de acordo com o RootPath
configurado no .ini da aplicao.

2.14.2 dbUseArea()

A dbUseArea() uma funcionalidade que permite definir um arquivo de base de dados,
com uma rea de trabalho disponvel na aplicao.

E Sintaxe: dbUseArea(lNewArea, cDriver, cName, cAlias, lShared, lReadOnly)

E Parmetros

lNewArea Indica se e um novo alias no conjunto de alias aberto.
cDriver Drive (RddName()) do arquivo -> DBFCDX / TOPCONN / DBFNTX.
cName Nome fsico da tabela que ser usado.
cAlias Alias que ser usado enquanto estive aberto.
lShared A tabela ter acesso exclusivo ou compartilhado.
lReadOnly Se verdadeiro. a tabela ser somente leitura.

2.14.3 IndRegua()

A IndRegua() uma funcionalidade que permite criar ndices temporrios para o alias
especificado, podendo ou no ter um filtro.

E Sintaxe: IndRegua(cAlias, cNIndex, cExpress, xOrdem, cFor, cMens, lShow)

E Parmetros

cAlias Alias da tabela onde ser efetuada o ndice/filtro temporrio.
cNIndex Nome do arquivo de trabalho retornado pela funo CriaTrab().
cExpress Expresso utilizada na chave do novo ndice.
xOrdem Parmetro nulo.
cFor Expresso utilizada para filtro.
cMens Parmetro nulo.
lShow Apresentar a tela de progresso do ndice/filtro temporrio.

2.15 Funes Auxiliares para Arquivos de Trabalho e Temporrios

DbStruct() - Retorna um array com a estrutura de um Alias aberto no sistema:
Exemplo: {campo,tipo,tamanho,decimal}

RetIndex() - Retorna a quantidade de ndices ativa para um Alias aberto no sistema.

DbSetIndex() - Agrega um arquivo de ndice a um Alias ativo no sistema.
Caso seja um ndice temporrio gerado pela IndRegua, somente deve ser agregado se
Database principal no for Top.

OrdBagExt() - Retorna a extenso dos arquivos de ndices utilizados pelo sistema (.idx
/ .cdx / .ntx)

Exemplo 01: Gerao de arquivo e ndice temporrios


/*/
+-------------------------------------------------------------------
------
| Programa | GeraTrab | Autor | ROBSON LUIZ | Data |
|
+-------------------------------------------------------------------
------
| Desc. | Utilizao de arquivos e ndices temporrios
|
+-------------------------------------------------------------------
------
|
+-------------------------------------------------------------------
------
/*/

User Function GeraTrab()

Local aStru := {}
Local aArqTRB := {}
Local nI := 0
Local cIndTRB := ""
Local cNomArq := ""

AADD( aStru, { "PRODUTO" ,"B1_COD" } )
AADD( aStru, { "DESCRICAO" ,"B1_DESC" } )
AADD( aStru, { "GRUPO" ,"BM_GRUPO" } )
AADD( aStru, { "DESCGRUPO" ,"BM_DESC" } )
AADD( aStru, { "TIPO" ,"B1_TIPO" } )
AADD( aStru, { "DESCTIPO" ,"B1_DESC" } )
AADD( aStru, { "CC" ,"CTT_CC" } )
AADD( aStru, { "DESC_CC" ,"CTT_DESC" } )
AADD( aStru, { "SERIE" ,"D2_SERIE" } )
AADD( aStru, { "DOCTO" ,"D2_COD" } )
AADD( aStru, { "TIPONOTA" ,"D2_TP" } )
AADD( aStru, { "EMISSAO" ,"D2_EMISSAO" } )
AADD( aStru, { "CLIENTE" ,"D2_CLIENTE" } )
AADD( aStru, { "LOJA" ,"D2_LOJA" } )
AADD( aStru, { "NOME" ,"A1_NOME" } )
AADD( aStru, { "QTDE" ,"D2_QUANT" } )
AADD( aStru, { "UNIT" ,"D2_PRCVEN" } )
AADD( aStru, { "TOTAL" ,"D2_TOTAL" } )
AADD( aStru, { "ALIQICMS" ,"D2_PICM" } )
AADD( aStru, { "VALICMS" ,"D2_VALICM" } )
AADD( aStru, { "ALIQIPI" ,"D2_IPI" } )
AADD( aStru, { "VALIPI" ,"D2_VALIPI" } )
AADD( aStru, { "VALMERC" ,"D2_TOTAL" } )
AADD( aStru, { "TOTSEMICMS" ,"D2_TOTAL" } )
AADD( aStru, { "VALPIS" ,"D2_TOTAL" } )
AADD( aStru, { "LIQUIDO" ,"D2_TOTAL" } )
AADD( aStru, { "CUSTO" ,"D2_TOTAL" } )

dbSelectArea("SX3")
dbSetOrder(2)
For nI := 1 To Len( aStru )
dbSeek( aStru[nI,2] )
AADD( aArqTRB, { aStru[nI,1], X3_TIPO, X3_TAMANHO, X3_DECIMAL }
)
Next nI

// ndice que ser criado
cIndTRB := "PRODUTO+DTOS(EMISSAO)"

cNomArq := CriaTrab( aArqTRB, .T. )

dbUseArea( .T., "DBFCDX", cNomArq, "TRB", .T. ,.T. )

IndRegua( "TRB", cNomArq, cIndTRB )
dbSetOrder(1)

// ( ... ) fazer o processamento necessrio

dbSelectArea("TRB")
dbCloseArea()

If MsgYesNo("Apagar o arquivo gerado \system\"+cNomArq+".dbf
?",FunName())
Ferase(cNomArq+".dbf")
Ferase(cNomArq+OrdBagExt())
Endif

Return Nil

Quando criamos um arquivo ou um ndice temporrio
(trabalho), utilizando a funo Indregua, obrigatrio apag-
los no final do rotina.

A utilizao de arquivo ou ndice temporrio, dever ser bem
analisada a fim de evitar lentido nos processamentos da
rotina.

O array aStru foi criado com base nos campos existentes no
sistema, ao invs de criarmos novas estruturas dos campos,
utilizamos as j existentes no Dicionrios de Dados (SX3).

Exemplo 02: Utilizando dois ndices temporrios com RDD DBFCDX

/*/
+-------------------------------------------------------------------
----------
| Programa | IndTwoReg | Autor | MICHEL DANTAS | Data |
|
+-------------------------------------------------------------------
----------
| Desc. | Utilizao de dois ndices temporrios com DBFCDX
|
+-------------------------------------------------------------------
----------
|
+-------------------------------------------------------------------
----------
/*/

User Function IndTwoReg()

LOCAL nOrder := 0
LOCAL cArq1 := CriaTrab(NIL,.F.)
LOCAL cChave1 := "A1_FILIAL+A1_EST"
LOCAL cArq2 := CriaTrab(NIL,.F.)
LOCAL cChave2 := "A1_FILIAL+A1_NOME"

dbSelectArea("SA1")
IndRegua("SA1",cArq1,cChave1,,,"Selecionando Regs...")
IndRegua("SA1",cArq2,cChave2,,,"Selecionando Regs...")

nOrder := RetIndex("SA1")

dbSetIndex(cArq1+OrdBagExt())
dbSetIndex(cArq2+OrdBagExt())

Alert("Agora vai por estado")

dbsetOrder(nOrder+1)
dbGoTop()
While !Eof()
Alert("Estado : " + SA1->A1_EST +" "+" Nome : " + SA1-
>A1_NOME)
dbSkip()
End

Alert("Agora vai por nome")

dbSetOrder(nOrder+2)
dbGoTop()
While !Eof()
Alert("Estado : " + SA1->A1_EST +" "+" Nome : " + SA1-
>A1_NOME)
dbSkip()
End

RetIndex("SA1")
Ferase(cArq1+OrdBagext())
Ferase(cArq2+OrdBagext())

Return

Exerccio 12
Implementar uma rotina que crie um arquivo de trabalho com uma estrutura
similar ao SA1, e que receba as informaes desta tabela.

Exerccio 13
Implementar uma rotina que crie um arquivo de trabalho com uma estrutura
similar ao SB1, e que receba as informaes desta tabela.

9. Relatrios no grficos
Os relatrios desenvolvidos em ADVPL possuem um padro de desenvolvimento que
mais depende de layout e tipos de parmetros do que qualquer outro tipo de
informao, visto que at o momento percebemos que a linguagem padro da
Microsiga muito mais composta de funes genricas do que de comandos.

Este tipo de relatrio caracterizado por um formato de impresso tipo PostScript, e
permite a gerao de um arquivo em formato texto (.txt), com uma extenso prpria da
aplicao ERP (.##R).

A estrutura de um relatrio no grfico baseada no uso da funo SetPrint(),
complementada pelo uso de outras funes acessrias, as quais esto detalhadas no
Guia de Referncia Rpida que acompanha este material.

2.16 Funes Utilizadas para Desenvolvimento de Relatrios

2.16.1 SetPrint()

A funo que cria a interface com as opes de configurao para impresso de um
relatrio no formato texto. Basicamente duas variveis m_pag e aReturn precisam ser
declaradas como privadas (private) antes de executar a SetPrint(). Aps confirmada, os
dados so armazenados no vetor aReturn que ser passado como parmetro para
funo SetDefault().

E Sintaxe: SetPrint ( < cAlias > , < cProgram > , [ cPergunte ] , [ cTitle ] , [
cDesc1 ] , [ cDesc2 ] , [ cDesc3 ] , [ lDic ] , [ aOrd ] , [ lCompres ] ,
[ cSize ] , [ uParm12 ] , [ lFilter ] , [ lCrystal ] , [ cNameDrv ] , [
uParm16 ] , [ lServer ] , [ cPortPrint ] ) --> cReturn

E Parmetros:

cAlias Alias do arquivo a ser impresso.
cProgram Nome do arquivo a ser gerado em disco.
cPergunte Grupo de perguntas cadastrado no dicionrio SX1.
cTitle Ttulo do relatrio.
cDesc1 Descrio do relatrio.
cDesc2 Continuao da descrio do relatrio.
lDic
Utilizado na impresso de cadastro genrico permite a escolha dos campos a
serem impressos. Se o parametro cAlias no for informado o valor padro
assumido ser .F..
aOrd Ordem(s) de impresso.
lCompres Se verdadeiro (.T.) permite escolher o formato da impresso, o valor padro
assumido ser .T.

cSize Tamanho do relatrio "P","M" ou "G".
uParm12 Parmetro reservado.
lFilter
Se verdadeiro (.T.) permite a utilizao do assistente de filtro, o valor padro
assumido ser .T.
lCrystal
Se verdadeiro (.T.) permite integrao com Crystal Report, o valor padro
assumido ser .F.
cNameDrv Nome de um driver de impresso.
lServer Se verdadeiro (.T.) fora impresso no servidor.
cPortPrint Define uma porta de impresso padro.

E Retorno:

Caracter Nome do Relatrio

E Estrutura aReturn:

aReturn[1] Caracter, tipo do formulrio.
aReturn[2] Numrico, opo de margem.
aReturn[3] Caracter, destinatrio.
aReturn[4] Numrico, formato da impresso.
aReturn[5] Numrico, dispositivo de impresso.
aReturn[6] Caracter, driver do dispositivo de impresso.
aReturn[7] Caracter, filtro definido pelo usurio.
aReturn[8] Numrico, ordem.
aReturn[x] A partir a posio [9] devem ser informados os nomes dos campos que devem
ser considerados no processamento, definidos pelo uso da opo Dicionrio da
SetPrint().

2.16.2 SetDefault()

A funo SetDefault() prepara o ambiente de impresso de acordo com as
informaes configuradas no array aReturn, obtidas atravs da funo SetPrint().

E Sintaxe: SetDefault ( < aReturn > , < cAlias > , [ uParm3 ] , [ uParm4 ] ,
[cSize] , [ nFormat ] )

E Parmetros:

aReturn Configuraes de impresso.
cSize Tamanho da pgina "P","M" ou "G"
nFormat Formato da pgina, 1 retrato e 2 paisagem.


SetPrint().

2.16.3 RptStatus()

Rgua de processamento simples, com apenas um indicador de progresso,
utilizada no processamento de relatrios do padro SetPrint().
E Sintaxe: RptStatus(bAcao, cMensagem)

E Parmetros:

bAcao
Bloco de cdigo que especifica a ao que ser
executada com o acompanhamento da rgua de
processamento.
cMensagem
Mensagem que ser exibida na rgua de processamento
durante a execuo.

2.16.3.1 SETREGUA()

A funo SetRegua() utilizada para definir o valor mximo da rgua de progresso
criada atravs da funo RptStatus().

E Sintaxe: SetRegua(nMaxProc)

E Parmetros:

nMaxProc Varivel que indica o valor mximo de processamento (passos) que sero
indicados pela rgua.

2.16.3.2 INCREGUA()

A funo IncRegua() utilizada para incrementar valor na rgua de progresso criada
atravs da funo RptStatus()

E Sintaxe: IncRegua(cMensagem)

E Parmetros:

cMensagem Mensagem que ser exibida e atualizada na rgua de processamento a cada
execuo da funo IncRegua(), sendo que a taxa de atualizao da interface
controlada pelo Binrio.

2.16.4 CABEC()

A funo CABEC() determina as configuraes de impresso do relatrio e imprime o
cabealho do mesmo.

E Sintaxe: Cabec(cTitulo, cCabec1, cCabec2, cNomeProg, nTamanho,
nCompress, aCustomText, lPerg, cLogo)

E Parmetros:

cTitulo Ttulo do relatrio.
cCabec1 String contendo as informaes da primeira linha do cabealho.
cCabec2 String contendo as informaes da segunda linha do cabealho.
cNomeProg Nome do programa de impresso do relatrio.
nTamanho Tamanho do relatrio em colunas (80, 132 ou 220).
nCompress Indica se impresso ser comprimida (15) ou normal (18).
aCustomText
Texto especfico para o cabealho, substituindo a estrutura padro do
sistema.
lPerg
Permite a supresso da impresso das perguntas do relatrio, mesmo que o
parmetro MV_IMPSX1 esteja definido como S.

E Parmetros (continuao):

cLogo
Redefine o bitmap que ser impresso no relatrio, no necessitando que ele
esteja no formato padro da Microsiga:
"LGRL"+SM0->M0_CODIGO+SM0->M0_CODFIL+".BMP"

2.16.5 RODA()

A funo RODA() imprime o rodap da pgina do relatrio, o que pode ser feito a cada
pgina, ou somente ao final da impresso.

E Sintaxe: Roda(uPar01, uPar02, cSize)

E Parmetros:

uPar01
No mais utilizado.
uPar02
No mais utilizado.
cSize
Tamanho do relatrio (P,M,G).

2.16.6 Pergunte()

A funo PERGUNTE() inicializa as variveis de pergunta (mv_par01,...) baseada na
pergunta cadastrado no Dicionrio de Dados (SX1). Se o parmetro lAsk no for
especificado, ou for verdadeiro, ser exibida a tela para edio da pergunta, e, se o
usurio cofirmar, as variveis sero atualizadas e a pergunta no SX1 tambm ser
atualizada.

E Sintaxe: Pergunte( cPergunta , [lAsk] , [cTitle] )

E Parmetros:

cPergunta Pergunta cadastrada no dicionrio de dados ( SX1) a ser utilizada.
|Ask Indica se exibir a tela para edio.
cTitle Ttulo do dilogo.

E Retorno:

Lgico Indica se a tela de visualizao das perguntas foi confirmada (.T.) ou cancelada
(.F.)

2.16.7 AjustaSX1()

A funo AJUSTASX1() permite a incluso simultnea de vrios itens de perguntas para
um grupo de perguntas no SX1 da empresa ativa.


E Sintaxe: AJUSTASX1(cPerg, aPergs)

E Parmetros:

cPerg Grupo de perguntas do SX1 (X1_GRUPO)
aPergs Array contendo a estrutura dos campos que sero gravados no SX1.

E Estrutura Item do array aPerg:

Posio Campo Tipo Descrio
01 X1_PERGUNT Caractere Descrio da pergunta em portugus.
02 X1_PERSPA Caractere Descrio da pergunta em espanhol.
03 X1_PERENG Caractere Descrio da pergunta em ingls.
04 X1_VARIAVL Caractere Nome da varivel de controle auxiliar
(mv_ch).
05 X1_TIPO Caractere Tipo do parmetro.
06 X1_TAMANHO Numrico Tamanho do contedo do parmetro.
07 X1_DECIMAL Numrico Nmero de decimais para contedos
numricos.
08 X1_PRESEL Numrico Define qual opo do combo a padro
para o parmetro.
09 X1_GSC Caractere Define se a pergunta ser do tipo G
Get ou C Choice (combo).
10 X1_VALID Caractere Expresso de validao do parmetro.
11 X1_VAR01 Caractere Nome da varivel MV_PAR+Ordem do
parmetro.
12 X1_DEF01 Caractere Descrio da opo 1 do combo em
portugus.
13 X1_DEFSPA1 Caractere Descrio da opo 1 do combo em
espanhol.
14 X1_DEFENG1 Caractere Descrio da opo 1 do combo em
ingls.
15 X1_CNT01 Caractere Contedo padro ou ultimo contedo
definido como respostas para a
pergunta.
16 X1_VAR02 Caractere No informado.
17 X1_DEF02 Caractere Descrio da opo X do combo em
portugus.
18 X1_DEFSPA2 Caractere Descrio da opo X do combo em
espanhol.
19 X1_DEFENG2 Caractere Descrio da opo X do combo em
ingls.
20 X1_CNT02 Caractere No informado.
portugus.
espanhol.
ingls.
portugus.
espanhol.
ingls.
portugus.
espanhol.
ingls.
36 X1_F3 Caractere Cdigo da consulta F3 vinculada ao
parmetro.
37 X1_GRPSXG Caractere Cdigo do grupo de campos SXG para
atualizao automtica, quando o grupo
for alterado.

38 X1_PYME Caractere Se a pergunta estar disponvel no
ambiente Pyme.
39 X1_HELP Caractere Contedo do campo X1_HELP.
40 X1_PICTURE Caractere Picture de formatao do contedo do
campo.
41 aHelpPor Array Vetor simples contendo as linhas de help
em portugus para o parmetro.
Trabalhar com linhas de at 40
caracteres.
42 aHelpEng Array Vetor simples contendo as linhas de help
em ingls para o parmetro. Trabalhar
com linhas de at 40 caracteres.
43 aHelpSpa Array Vetor simples contendo as linhas de help
em espanhol para o parmetro. Trabalhar
com linhas de at 40 caracteres.

2.16.8 PutSX1()

A funo PUTSX1() permite a incluso de um nico item de pergunta em um grupo
definido no Dicionrio de Dados (SX1). Todos os vetores contendo os textos
explicativos da pergunta devem conter at 40 caracteres por linha.

E Sintaxe: PutSx1(cGrupo, cOrdem, cPergunt, cPerSpa, cPerEng, cVar, cTipo,
nTamanho, nDecimal, nPresel, cGSC, cValid, cF3, cGrpSxg
,cPyme, cVar01, cDef01, cDefSpa1 , cDefEng1, cCnt01, cDef02,
cDefSpa2, cDefEng2, cDef03, cDefSpa3, cDefEng3, cDef04,
cDefSpa4, cDefEng4, cDef05, cDefSpa5, cDefEng5, aHelpPor,
aHelpEng, aHelpSpa, cHelp)

E Parmetros:

cGrupo Grupo de perguntas do SX1 (X1_GRUPO).
cOrdem Ordem do parmetro no grupo (X1_ORDEM).
cPergunt Descrio da pergunta em portugus.
cPerSpa Descrio da pergunta em espanhol.
cPerEng Descrio da pergunta em ingls.
cVar Nome da varivel de controle auxiliar (X1_VARIAVL).
cTipo Tipo do parmetro.
nTamanho Tamanho do contedo do parmetro.
nDecimal Nmero de decimais para contedos numricos.
nPresel Define qual opo do combo a padro para o parmetro.
cGSC Define se a pergunta ser do tipo G Get ou C Choice (combo).
cValid Expresso de validao do parmetro.
cF3 Cdigo da consulta F3 vinculada ao parmetro
cGrpSxg
Cdigo do grupo de campos SXG para atualizao automtica, quando o grupo
for alterado.
cPyme Se a pergunta estar disponvel no ambiente Pyme.
cVar01 Nome da varivel MV_PAR+Ordem do parmetro.
cDef01 Descrio da opo 1 do combo em portugus.
cDefSpa1 Descrio da opo 1 do combo em espanhol.
cDefEng1 Descrio da opo 1 do combo em ingls.
cCnt01 Contedo padro ou ultimo contedo definido como respostas para este item.
cDef0x Descrio da opo X do combo em portugus.
cDefSpax Descrio da opo X do combo em espanhol.
cDefEngx Descrio da opo X do combo em ingls.
aHelpPor Vetor simples contendo as linhas de help em portugus para o parmetro.
aHelpEng Vetor simples contendo as linhas de help em ingls para o parmetro.
aHelpSpa Vetor simples contendo as linhas de help em espanhol para o parmetro.
cHelp Contedo do campo X1_HELP.

2.17 Estrutura de Relatrios Baseados na SetPrint()

Neste tpico ser demonstrada a construo de relatrio no grfico baseado no uso
da funo SetPrint() o qual atende os formatos de base de dados ISAM e Top Connect.
Porm, no contemplando a tecnologia Protheus Embedded SQL.


Linhas Programa
1 Funo principal;
3
Atualizao do arquivo de perguntas atravs da funo especfica
CriaSX1();
4 Definio das perguntas atravs da funo Pergunte();
5 Definio das ordens disponveis para impresso do relatrio;
6 Chamada da funo SetPrint;
7 Atualizao das configuraes de impresso com a funo SetDefault();
8 Execuo da rotina de impresso atravs da funo RptStatus()

10 Funo de processamento e impresso do relatrio
12
Definio dos filtros de impresso, avaliando o banco de dados em uso
pela aplicao;
13
Atualizao da rgua de processamento com a quantidade de registros
que ser processada;
14 Estrutura principal de repetio para impresso dos dados do relatrio;
15
Controle da impresso do cabealho utilizando a funo
Cabec();
16 Impresso dos totais do relatrio;
17
Impresso do rodap da ltima pgina do relatrio utilizando a funo
Roda();
18
Limpeza dos arquivos e ndices temporrios criados para o
processamento();
19
Tratamento da visualizao do relatrio (impresso em disco) atravs
da funo OurSpool()
20
Tratamentos adicionais ao relatrio, de acordo com necessidades
especficas;
21
Liberao do buffer de impresso, seja para impressora, seja para
limpeza do contedo
visualizado em tela, utilizando a funo MS_FLUSH()

22 Fim da funo de processamento e impresso do relatrio

23 Funo de atualizao do arquivo de perguntas
25 Opo 01: Adio individual de cada pergunta no SX1 utilizando a
funo PUTSX1()

Criao de um array individual no formato utilizado pela
PUTSX1() contendo apenas as informaes da pergunta que ser
adicionada no SX1.
25
Opo 02: Adio de um grupo de perguntas no SX1 utilizando a
funo AJUSTASX1()

Criao de um array no formato utilizado pela AJUSTASX1()
contendo todas as perguntas que sero atualizadas.

26 Fim da funo de atualizao do arquivo de perguntas

Funo Principal

//+-----------------------------------------------------------------
+
//| Rotina | Inform | Autor | Robson Luiz (rleg) | Data | 01.01.07 |
//+-----------------------------------------------------------------
+
//| Descr. | Rotina para gerar relatrio utilizando as funes
|
//| | SetPrint() e SetDefault().
|
//+-----------------------------------------------------------------
+
|
//+-----------------------------------------------------------------
+

User Function INFORM()
//+-------------------------
//| Declaraes de variveis
//+-------------------------

Local cDesc1 := "Este relatrio ir imprimir informaes do contas
a pagar conforme"
Local cDesc2 := "parmetros informado. Ser gerado um arquivo no
diretrio "
Local cDesc3 := "Spool - INFORM_????.XLS, onde ???? e o nome do
usurio."

Private cString := "SE2"
Private Tamanho := "M"
Private aReturn := { "Zebrado",2,"Administrao",2,2,1,"",1 }
Private wnrel := "INFORM"
Private NomeProg := "INFORM"
Private nLastKey := 0
Private Limite := 132
Private Titulo := "Ttulo a Pagar - Ordem de "
Private cPerg := "INFORM"
Private nTipo := 0
Private cbCont := 0
Private cbTxt := "registro(s) lido(s)"
Private Li := 80
Private m_pag := 1
Private aOrd := {}
Private Cabec1 := "PREFIXO TITULO PARCELA TIP EMISSAO VENCTO
VENCTO"
Private Cabec1 += "REAL VLR. ORIGINAL PAGO
SALDO "
Private Cabec2 := ""
/*
+----------------------
| Parmetros do aReturn
+----------------------
aReturn - Preenchido pelo SetPrint()
aReturn[1] - Reservado para formulrio
aReturn[2] - Reservado para numero de vias
aReturn[3] - Destinatrio
aReturn[4] - Formato 1=Paisagem 2=Retrato
aReturn[5] - Mdia 1-Disco 2=Impressora
aReturn[6] Porta ou arquivo 1-Lpt1... 4-Com1...
aReturn[7] - Expresso do filtro
aReturn[8] - Ordem a ser selecionada
aReturn[9] [10] [n] - Campos a processar se houver
*/

AADD( aOrd, "Fornecedor" )
AADD( aOrd, "Titulo" )
AADD( aOrd, "Emisso" )
AADD( aOrd, "Vencimento" )
AADD( aOrd, "Vencto. Real" )

//Parmetros de perguntas para o relatrio
//+-------------------------------------------------------------+
//| mv_par01 - Fornecedor de ? 999999 |
//| mv_par02 - Fornecedor ate ? 999999 |
//| mv_par03 - Tipo de ? XXX |
//| mv_par04 - Tipo ate ? XXX |
//| mv_par05 - Vencimento de ? 99/99/99 |
//| mv_par06 - Vencimento ate ? 99/99/99 |
//| mv_par07 - Aglut.Fornecedor ? Sim/No |
//+-------------------------------------------------------------+
CriaSx1()

//+-------------------------------------------------
//| Disponibiliza para usurio digitar os parmetros
//+-------------------------------------------------
Pergunte(cPerg,.F.)
//cPerg -> Nome do grupo de perguntas, .T. mostra a tela,;
// .F. somente carrega as variveis

//+---------------------------------------------------
//| Solicita ao usurio a parametrizao do relatrio.
//+---------------------------------------------------
wnrel :=
SetPrint(cString,wnrel,cPerg,@Titulo,cDesc1,cDesc2,cDesc3,.F.,aOrd,.
F., ;
Tamanho,.F.,.F.)
//SetPrint(cAlias,cNome,cPerg,cDesc,cCnt1,cCnt2,cCnt3,lDic,aOrd,lCom
pres,;
//cSize,aFilter,lFiltro,lCrystal,cNameDrv,lNoAsk,lServer,cPortToPrin
t)

//+--------------------
//| Se teclar ESC, sair
//+--------------------
If nLastKey == 27
Return
Endif

//+-----------------------------------------------------------------
-
//| Estabelece os padres para impresso, conforme escolha do
usurio
//+-----------------------------------------------------------------
-
SetDefault(aReturn,cString)

//+-------------------------------------
//| Verificar se ser reduzido ou normal
//+-------------------------------------
nTipo := IIF(aReturn[4] == 1, 15, 18)

//+--------------------
//| Se teclar ESC, sair
//+--------------------
If nLastKey == 27
Return
Endif

//+-----------------------------------
//| Chama funo que processa os dados
//+-----------------------------------
RptStatus({|lEnd| ImpRel(@lEnd) }, Titulo, "Processando e imprimindo
dados,;
aguarde...", .T. )

Return

Funo de processamento e impresso

//+-----------------------------------------------------------------
+
//| Rotina | ImpRel | Autor | Robson Luiz (rleg) | Data | 01.01.07 |
//+-----------------------------------------------------------------
+
//| Descr. | Rotina de processamento e impresso.
|
//+-----------------------------------------------------------------
+
|
//+-----------------------------------------------------------------
+

Static Function ImpRel(lEnd)

Local nIndice := 0
Local cArq := ""
Local cIndice := ""
Local cFiltro := ""
Local aCol := {}
Local cFornec := ""
Local nValor := 0
Local nPago := 0
Local nSaldo := 0
Local nT_Valor := 0
Local nT_Pago := 0
Local nT_Saldo := 0
Local cArqExcel := ""
Local cAliasImp
Local oExcelApp

Titulo += aOrd[aReturn[8]]

#IFNDEF TOP
cAliasImp := "SE2"

cFiltro := "E2_FILIAL == '"+xFilial("SE2")+"' "
cFiltro += ".And. E2_FORNECE >= '"+mv_par01+"' "
cFiltro += ".And. E2_FORNECE <= '"+mv_par02+"' "
cFiltro += ".And. E2_TIPO >= '"+mv_par03+"' "
cFiltro += ".And. E2_TIPO <= '"+mv_par04+"' "
cFiltro += ".And. Dtos(E2_VENCTO) >= '"+Dtos(mv_par05)+"' "
cFiltro += ".And. Dtos(E2_VENCTO) <= '"+Dtos(mv_par06)+"' "

If aReturn[8] == 1 //Fornecedor
cIndice := "E2_FORNECE+E2_LOJA+E2_NUM"
Elseif aReturn[8] == 2 //Titulo
cIndice := "E2_NUM+E2_FORNECE+E2_LOJA"
Elseif aReturn[8] == 3 //Emissao

cIndice := "Dtos(E2_EMISSAO)+E2_FORNECE+E2_LOJA"
Elseif aReturn[8] == 4 //Vencimento
cIndice := "Dtos(E2_VENCTO)+E2_FORNECE+E2_LOJA"
Elseif aReturn[8] == 5 //Vencimento Real
cIndice := "Dtos(E2_VENCREA)+E2_FORNECE+E2_LOJA"
Endif

cArq := CriaTrab(NIL,.F.)
dbSelectArea(cAliasImp)
IndRegua(cAliasImp,cArq,cIndice,,cFiltro)
nIndice := RetIndex()
nIndice := nIndice + 1
dbSetIndex(cArq+OrdBagExt())
dbSetOrder(nIndice)
#ELSE
cAliasImp := GetNextAlias()

cQuery := "SELECT "
cQuery += "E2_PREFIXO, E2_NUM, E2_PARCELA, E2_TIPO, E2_FORNECE,
E2_LOJA, E2_NOMFOR, "
cQuery += "E2_EMISSAO, E2_VENCTO, E2_VENCREA, E2_VALOR, E2_SALDO "
cQuery += "FROM "+RetSqlName("SE2")+" "
cQuery += "WHERE E2_FILIAL = '"+xFilial("SE2")+"' "
cQuery += "AND E2_FORNECE >= '"+mv_par01+"' "
cQuery += "AND E2_FORNECE <= '"+mv_par02+"' "
cQuery += "AND E2_TIPO >= '"+mv_par03+"' "
cQuery += "AND E2_TIPO <= '"+mv_par04+"' "
cQuery += "AND E2_VENCTO >= '"+Dtos(mv_par05)+"' "
cQuery += "AND E2_VENCTO <= '"+Dtos(mv_par06)+"' "
cQuery += "AND D_E_L_E_T_ <> '*' "
cQuery += "ORDER BY "

cQuery += "E2_FORNECE,E2_LOJA,E2_NUM"
cQuery += "E2_NUM,E2_FORNECE,E2_LOJA"
cQuery += "E2_EMISSAO,E2_FORNECE,E2_LOJA"
cQuery += "E2_VENCTO,E2_FORNECE,E2_LOJA"
cQuery += "E2_VENCREA,E2_FORNECE,E2_LOJA"
Endif

dbUseArea( .T., "TOPCONN", TcGenQry(,,cQuery), cAliasImp, .T., .F. )

/* Instruo SQL Embedded
----------------------
cOrder := "E2_FORNECE,E2_LOJA,E2_NUM"
cOrder := "E2_NUM,E2_FORNECE,E2_LOJA"
cOrder := "E2_EMISSAO,E2_FORNECE,E2_LOJA"
cOrder := "E2_VENCTO,E2_FORNECE,E2_LOJA"

cOrder := "E2_VENCREA,E2_FORNECE,E2_LOJA"
Endif

BeginSQL Alias cAliasImp
Column E2_EMISSAO As Date
Column E2_VENCTO As Date
Column E2_VENCREA As Date
Column E2_VALOR As Numeric(12)
Column E2_SALDO As Numeric(12)
%NoParser%

SELECT E2_PREFIXO, E2_NUM, E2_PARCELA, E2_TIPO,
E2_FORNECE,
E2_LOJA, E2_NOMFOR, E2_EMISSAO, E2_VENCTO, E2_VENCREA,
E2_VALOR,
E2_SALDO
FROM %Table:SE2
WHERE
E2_FILIAL = %xFilial% AND
E2_FORNECE BETWEEN %Exp:mv_par01% AND %Exp:mv_par02% AND
E2_TIPO BETWEEN%Exp:mv_par03% AND %Exp:mv_par04% AND
E2_VENCTO BETWEEN %Exp:mv_par05% AND %Exp:mv_par06% AND
%NotDel%
ORDER BY %Order:cOrder%
EndSQL
*/
#ENDIF

dbGoTop()
SetRegua(0)

//+--------------------
//| Coluna de impresso
//+--------------------
AADD( aCol, 004 ) //Prefixo
AADD( aCol, 012 ) //Titulo
AADD( aCol, 024 ) //Parcela
AADD( aCol, 031 ) //Tipo
AADD( aCol, 036 ) //Emissao
AADD( aCol, 046 ) //Vencimento
AADD( aCol, 058 ) //Vencimento Real
AADD( aCol, 070 ) //Valor Original
AADD( aCol, 090 ) //Pago
AADD( aCol, 110 ) //Saldo

cFornec := (cAliasImp)->E2_FORNECE+(cAliasImp)->E2_LOJA

While !Eof() .And. !lEnd

If Li > 55
Cabec(Titulo,Cabec1,Cabec2,NomeProg,Tamanho,nTipo)
Endif

@ Li, aCol[1] PSay "Cod/Loj/Nome: "+(cAliasImp)->E2_FORNECE+;
"-"+(cAliasImp)->E2_LOJA+" "+(cAliasImp)->E2_NOMFOR
Li ++

While !Eof() .And. !lEnd .And.;
(cAliasImp)->E2_FORNECE+(cAliasImp)->E2_LOJA == cFornec

IncRegua()

If Li > 55
Cabec(Titulo,Cabec1,Cabec2,NomeProg,Tamanho,nTipo)
Endif

If mv_par07 == 2
@ Li, aCol[1] PSay (cAliasImp)->E2_PREFIXO
@ Li, aCol[2] PSay (cAliasImp)->E2_NUM
@ Li, aCol[3] PSay (cAliasImp)->E2_PARCELA
@ Li, aCol[4] PSay (cAliasImp)->E2_TIPO
@ Li, aCol[5] PSay (cAliasImp)->E2_EMISSAO
@ Li, aCol[6] PSay (cAliasImp)->E2_VENCTO
@ Li, aCol[7] PSay (cAliasImp)->E2_VENCREA
@ Li, aCol[8] PSay (cAliasImp)->E2_VALOR ;
PICTURE "@E 99,999,999,999.99"
@ Li, aCol[9] PSay (cAliasImp)->E2_VALOR -;
(cAliasImp)->E2_SALDO ;
PICTURE "@E 99,999,999,999.99"
@ Li, aCol[10] PSay (cAliasImp)->E2_SALDO ;
PICTURE "@E 99,999,999,999.99"
Li ++
Endif

nValor += (cAliasImp)->E2_VALOR
nPago += ((cAliasImp)->E2_VALOR-(cAliasImp)->E2_SALDO)
nSaldo += (cAliasImp)->E2_SALDO

nT_Valor += (cAliasImp)->E2_VALOR
nT_Pago += ((cAliasImp)->E2_VALOR-(cAliasImp)->E2_SALDO)
nT_Saldo += (cAliasImp)->E2_SALDO

dbSkip()
End

@ Li, 000 PSay Replicate("-",Limite)
Li ++
@ Li, aCol[1] PSay "TOTAL....."
@ Li, aCol[8] PSay nValor PICTURE "@E 99,999,999,999.99"
@ Li, aCol[9] PSay nPago PICTURE "@E 99,999,999,999.99"
@ Li, aCol[10] PSay nSaldo PICTURE "@E 99,999,999,999.99"
Li +=2

cFornec := (cAliasImp)->E2_FORNECE+(cAliasImp)->E2_LOJA
nValor := 0
nPago := 0
nSaldo := 0

End

If lEnd
@ Li, aCol[1] PSay cCancel
Return
Endif

@ Li, 000 PSay Replicate("=",Limite)
Li ++
@ Li, aCol[1] PSay "TOTAL GERAL....."
@ Li, aCol[8] PSay nT_Valor PICTURE "@E 99,999,999,999.99"
@ Li, aCol[9] PSay nT_Pago PICTURE "@E 99,999,999,999.99"
@ Li, aCol[10] PSay nT_Saldo PICTURE "@E 99,999,999,999.99"

If Li <> 80
Roda(cbCont,cbTxt,Tamanho)
Endif

//+-----------------------------------------------------------------
-----
//| Gera arquivo do tipo .DBF com extenso .XLS p/ usurio abrir no
Excel
//+-----------------------------------------------------------------
-----
cArqExcel := __RELDIR+NomeProg+"_"+Substr(cUsuario,7,4)+".XLS"
Copy To &cArqExcel

#IFNDEF TOP
RetIndex(cAliasImp)
Set Filter To
#ELSE
dbCloseArea()
#ENDIF
dbSetOrder(1)
dbGoTop()

If aReturn[5] == 1
Set Printer TO
dbCommitAll()
OurSpool(wnrel)
EndIf

//+------------------------
//| Abrir planilha MS-Excel
//+------------------------
If mv_par08 == 1
__CopyFile(cArqExcel,"c:\"+NomeProg+"_"+Substr(cUsuario,7,4)+".XLS")
If ! ApOleClient("MsExcel")
MsgAlert("MsExcel no instalado")
Return
Endif
oExcelApp := MsExcel():New()
oExcelApp:WorkBooks:Open(
"c:\"+NomeProg+"_"+Substr(cUsuario,7,4)+".XLS" )
oExcelApp:SetVisible(.T.)
Endif

Ms_Flush()

Return

Funo para gerar o grupo de parmetros no SX1

//+-----------------------------------------------------------------
+
//| Rotina | CriaSX1 | Autor | Robson Luiz (rleg)| Data | 01.01.07 |
//+-----------------------------------------------------------------
+
//| Descr. | Rotina para criar o grupo de parmetros.
|
//+-----------------------------------------------------------------
+
|
//+-----------------------------------------------------------------
+
Static Function CriaSx1()
Local aP := {}
Local i := 0
Local cSeq
Local cMvCh
Local cMvPar
Local aHelp := {}

/******
Parmetros da funo padro
---------------------------
PutSX1(cGrupo,;cOrdem,;
cPergunt,cPerSpa,cPerEng,;
cVar,;
cTipo,;
nTamanho,;
nDecimal,;
nPresel,;
cGSC,;
cValid,;
cF3,;
cGrpSxg,;
cPyme,;
cVar01,;
cDef01,cDefSpa1,cDefEng1,;
cCnt01,;
aHelpPor,aHelpEng,aHelpSpa,;
cHelp)

Caracterstica do vetor p/ utilizao da funo SX1
---------------------------------------------------
[n,1] --> texto da pergunta
[n,2] --> tipo do dado
[n,3] --> tamanho
[n,4] --> decimal
[n,5] --> objeto G=get ou C=choice
[n,6] --> validao
[n,7] --> F3
[n,8] --> definio 1
[n,9] --> definio 2
[n,10] -> definio 3
[n,11] -> definio 4
[n,12] -> definio 5
***/

AADD(aP,{"Fornecedor de","C",6,0,"G","","SA2","" ,"" ,"","",""})
AADD(aP,{"Fornecedor ate","C",6,0,"G","(mv_par02>=mv_par01)","SA2",;
"" ,"" ,"","",""})
AADD(aP,{"Tipo de","C",3,0,"G","","05" ,"" ,"" ,"","",""})
AADD(aP,{"Tipo ate","C",3,0,"G","(mv_par04>=mv_par03)","05" ,"" ,;
"" ,"","",""})
AADD(aP,{"Vencimento de","D",8,0,"G","","" ,"" ,"" ,"","",""})
AADD(aP,{"Vencimento ate","D",8,0,"G","(mv_par06>=mv_par05)","" ,;
"" ,"" ,"","",""})
AADD(aP,{"Aglutinar pagto.de fornec.","N",1,0,"C","","",;
"Sim","No","","",""})
AADD(aP,{"Abrir planilha MS-Excel" ,"N",1,0,"C","","",;
"Sim","No","","",""})

AADD(aHelp,{"Informe o cdigo do fornecedor.","inicial."})
AADD(aHelp,{"Informe o cdigo do fornecedor.","final."})
AADD(aHelp,{"Tipo de ttulo inicial."})
AADD(aHelp,{"Tipo de ttulo final."})
AADD(aHelp,{"Digite a data do vencimento inicial."})
AADD(aHelp,{"Digite a data do vencimento final."})
AADD(aHelp,{"Aglutinar os ttulos do mesmo forne-",;
"cedor totalizando seus valores."})
AADD(aHelp,{"Ser gerada uma planilha para ",;
"MS-Excel, abrir esta planilha?"})

For i:=1 To Len(aP)
cSeq := StrZero(i,2,0)
cMvPar := "mv_par"+cSeq
cMvCh := "mv_ch"+IIF(i<=9,Chr(i+48),Chr(i+87))

PutSx1(cPerg,;
cSeq,;
aP[i,1],aP[i,1],aP[i,1],;
cMvCh,;
aP[i,2],;
aP[i,3],;
aP[i,4],;
0,;
aP[i,5],;
aP[i,6],;
aP[i,7],;
"",;
"",;
cMvPar,;
aP[i,8],aP[i,8],aP[i,8],;
"",;
aP[i,9],aP[i,9],aP[i,9],;
aP[i,10],aP[i,10],aP[i,10],;
aP[i,11],aP[i,11],aP[i,11],;
aP[i,12],aP[i,12],aP[i,12],;
aHelp[i],;
{},;
{},;
"")
Next i

Return

Exerccio 14
Implementar um relatrio que fornea uma listagem de uma nota fiscal de entrada
e seus itens.
10. Manipulao de arquivos I

2.18 Gerao e leitura de arquivos em formato texto

Arquivos do tipo texto (tambm conhecidos como padro TXT) so arquivos com
registros de tamanho varivel. A indicao do final de cada registro representada por
dois bytes, 0D 0A em hexadecimal ou 13 10 em decimal ou, ainda, CR LF para
padro ASCII.

Apesar do tamanho dos registros ser varivel, a maioria dos sistemas gera este tipo de
arquivo com registros de tamanho fixo, de acordo com um layout especfico que
indica quais so os dados gravados.

Para ilustrar estes procedimentos, sero gerados arquivos textos, com duas famlias de
funes:

1) Famlia: nesta famlia sero utilizadas as funes: FCreate(), FWrite(), FClose(),
FSeek(), FOpen() e FRead().

2) Famlia: nesta famlia sero utilizadas as funes: FT_FUse(), FT_FGoTop(),
FT_FLastRec(), FT_FEof(), FT_FReadLn(), FT_FSkip(), FT_FGoto(), FT_FRecno().

A diferena entre as duas famlias est na leitura do arquivo texto.
Quando se tratar de arquivo texto com tamanho fixo das linhas,
podero ser utilizadas as duas famlias para leitura do arquivo. Porm,
quando se tratar de arquivo texto com tamanho varivel das linhas,
somente poder ser utiliza a segunda famlia, representada pelas
funes: FT_FUse(), FT_FGoTo(), FT_FRecno(), FT_FGoTop(),
FT_FLastRec(), FT_FEof(), FT_FReadLn() e FT_FSkip().

2.18.1 1 Famlia de funes de gravao e leitura de arquivos texto

2.18.1.1 FCREATE()

Funo de baixo-nvel que permite a manipulao direta dos arquivos textos como
binrios. Ao ser executada FCREATE() cria um arquivo ou elimina o seu contedo, e
retorna o handle (manipulador) do arquivo, para ser usado nas demais funes de
manuteno de arquivo. Aps ser utilizado, o Arquivo deve ser fechado atravs da
funo FCLOSE().

Na tabela abaixo, esto descritos os atributos para criao do arquivo , definidos no
arquivo header fileio.ch

E Atributos definidos no include FileIO.ch

Constante Valor Descrio
FC_NORMAL 0 Criao normal do Arquivo (default/padro).
FC_READONLY 1 Cria o arquivo protegido para gravao.
FC_HIDDEN 2 Cria o arquivo como oculto.
FC_SYSTEM 4 Cria o arquivo como sistema.

Caso desejemos especificar mais de um atributo, basta som-los. Por exemplo , para
criar um arquivo protegido contra gravao e escondido , passamos como atributo
FC_READONLY + FC_HIDDEN. .

Nota: Caso o arquivo j exista, o contedo do mesmo ser ELIMINADO, e, seu tamanho
ser truncado para 0 ( ZERO ) bytes.

E Sintaxe: FCREATE ( < cArquivo > , [ nAtributo ] )

E Parmetros:

cArquivo Nome do arquivo a ser criado, podendo ser especificado um pacote (patch)
absoluto ou relativo, para criar arquivos no ambiente local ( Remote ) ou no
Servidor, respectivamente .
nAtributo Atributos do arquivo a ser criado (Vide Tabela de atributos abaixo). Caso no
especificado, o DEFAULT FC_NORMAL.

E Retorno:

Numrico

A funo retornar o Handle do arquivo para ser usado nas demais funes de
manuteno de arquivo. O Handle ser maior ou igual a zero. Caso no seja
possvel criar o arquivo, a funo retornar o handle -1 , e ser possvel obter
maiores detalhes da ocorrncia atravs da funo FERROR() .

2.18.1.2 FWRITE()

Funo que permite a escrita em todo ou em parte do contedo do buffer, limitando a
quantidade de Bytes atravs do parmetro nQtdBytes. A escrita comea a partir da
posio corrente do ponteiro de arquivos, e a funo FWRITE retornar a quantidade
real de bytes escritos. Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(),
podemos abrir ou criar um arquivo ou abrir uma porta de comunicao, para o qual
sero gravados ou enviados os dados do buffer informado. Por tratar-se de uma funo
de manipulao de contedo binrio, so suportados na String cBuffer todos os
caracteres da tabela ASCII, inclusive caracteres de controle (ASC 0 , ASC 12 , ASC 128 ,
etc.).

Caso acontea alguma falha na gravao, a funo retornar um nmero menor que o
nQtdBytes. Neste caso, a funo FERROR() pode ser utilizada para determinar o erro
especfico ocorrido. A gravao no arquivo realizada a partir da posio atual do
ponteiro, que pode ser ajustado atravs das funes FSEEK() , FREAD() ou FREADSTR().

E Sintaxe: FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] )

E Parmetros:

nHandle o manipulador de arquivo ou device retornado pelas funes FOPEN(),
FCREATE(), ou FOPENPORT().
cBuffer <cBuffer> a cadeia de caracteres a ser escrita no arquivo especificado. O
tamanho desta varivel deve ser maior ou igual ao tamanho informado em
nQtdBytes (caso seja informado o tamanho).
nQtdBytes <nQtdBytes> indica a quantidade de bytes a serem escritos a partir da posio
corrente do ponteiro de arquivos. Caso seja omitido, todo o contedo de
<cBuffer> escrito.

E Retorno:

Numrico FWRITE() retorna a quantidade de bytes escritos na forma de um valor numrico
inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a operao foi bem
sucedida. Caso o valor de retorno seja menor que <nBytes> ou zero, ou o disco
est cheio ou ocorreu outro erro. Neste caso, utilize a funo FERROR() para
obter maiores detalhes da ocorrncia.

2.18.1.3 FCLOSE()

Funo de tratamento de arquivos de baixo nvel utilizada para fechar arquivos binrios
e forar que os respectivos buffers do DOS sejam escritos no disco. Caso a operao
falhe, FCLOSE() retorna falso (.F.). FERROR() pode, ento, ser usado para determinar a
razo exata da falha. Por exemplo, ao tentar usar FCLOSE() com um handle (tratamento
dado ao arquivo pelo sistema operacional) invlido retorna falso (.F.) e FERROR()
retorna erro 6 do DOS, invalid handle. Consulte FERROR() para obter uma lista
completa dos cdigos de erro.

Nota: Esta funo permite acesso de baixo nvel aos arquivos e dispositivos do DOS.
Ela deve ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema
operacional utilizado.

E Sintaxe: FCLOSE ( < nHandle > )

E Parmetros:

nHandle Handle do arquivo obtido previamente atravs de FOPEN() ou FCREATE().


E Retorno:

Lgico Retorna falso (.F.) se ocorre um erro enquanto os buffers esto sendo escritos;
do contrrio, retorna verdadeiro (.T.).

2.18.1.4 FSEEK()

Funo que posiciona o ponteiro do arquivo para as prximas operaes de leitura ou
gravao. As movimentaes de ponteiros so relativas nOrigem que pode ter os
seguintes valores, definidos em fileio.ch:

E Tabela A: Origem a ser considerada para a movimentao do ponteiro de
posicionamento do Arquivo.

Origem Constate(fileio.ch) Operao
0 FS_SET Ajusta a partir do inicio do arquivo. (Default).
1 FS_RELATIVE Ajuste relativo a posio atual do arquivo.
2 FS_END Ajuste a partir do final do arquivo.

E Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] )

E Parmetros:

nHandle Manipulador obtido atravs das funes FCREATE, FOPEN.
nOffSet nOffSet corresponde ao nmero de bytes no ponteiro de posicionamento do
arquivo a ser movido. Pode ser um nmero positivo, zero ou negativo, a ser
considerado a partir do parmetro passado em nOrigem.
nOrigem Indica a partir de qual posio do arquivo, o nOffset ser considerado.

E Retorno:

Numrico FSEEK() retorna a nova posio do ponteiro de arquivo com relao ao incio do
arquivo (posio 0) na forma de um valor numrico inteiro. Este valor no leva
em conta a posio original do ponteiro de arquivos antes da execuo da
funo FSEEK().

2.18.1.5 FOPEN()

Funo de tratamento de arquivo de baixo nvel que abre um arquivo binrio existente
para que este possa ser lido e escrito, dependendo do argumento <nModo>. Toda vez
que houver um erro na abertura do arquivo, FERROR() pode ser usado para retornar o
cdigo de erro do Sistema Operacional. Por exemplo, caso o arquivo no exista,
FOPEN() retorna -1 e FERROR() retorna 2 para indicar que o arquivo no foi
encontrado. Veja FERROR() para uma lista completa dos cdigos de erro.
Caso o arquivo especificado seja aberto, o valor retornado o handle (manipulador) do
Sistema Operacional para o arquivo. Este valor semelhante a um alias no sistema de
banco de dados, e ele exigido para identificar o arquivo aberto para as outras funes
de tratamento de arquivo. Portanto, importante sempre atribuir o valor que foi
retornado a uma varivel para uso posterior, como mostra o exemplo desta funo.

E Sintaxe: FOPEN ( < cArq > , [ nModo ] )

E Parmetros:

cArq Nome do arquivo a ser aberto que inclui o pacote, caso haja um.
nModo Modo de acesso DOS solicitado que indica como o arquivo aberto deve ser
acessado. O acesso de uma das categorias relacionadas na tabela A e as
restries de compartilhamento relacionada na Tabela B. O modo padro zero,
somente para leitura, com compartilhamento por Compatibilidade. Ao
definirmos o modo de acesso, devemos somar um elemento da Tabela A com
um elemento da Tabela B.

E Retorno:

Numrico FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535. Caso
ocorra um erro, FOPEN() retorna -1.

2.18.1.6 FREAD()

Funo que realiza a leitura dos dados a partir um arquivo aberto, atravs de FOPEN(),
FCREATE() e/ou FOPENPORT(), e armazena os dados lidos por referncia no buffer
informado.
FREAD() ler at o nmero de bytes informado em nQtdBytes; caso acontea algum
erro ou o arquivo chegue ao final, FREAD() retornar um nmero menor que o
especificado em nQtdBytes. FREAD() l normalmente caracteres de controle (ASC 128,
ASC 0, etc.) e l a partir da posio atual do ponteiro atual do arquivo, que pode ser
ajustado ou modificado pelas funes FSEEK() , FWRITE() ou FREADSTR().

A varivel String a ser utilizada como buffer de leitura deve ser sempre pr-alocada e
passada como referncia. Caso contrrio, os dados no podero ser retornados.

E Sintaxe: FREAD ( < nHandle > , < cBuffer > , < nQtdBytes > )

E Parmetros:

nHandle o manipulador (Handle) retornado pelas funes FOPEN(),
FCREATE(), FOPENPORT(), que faz referncia ao arquivo a ser lido.
cBuffer o nome de uma varivel do tipo String , a ser utilizada como buffer de leitura,
onde os dados lidos devero ser armazenados. O tamanho desta varivel deve
ser maior ou igual ao tamanho informado em nQtdBytes.
Esta varivel deve ser sempre passada como referncia. (@ antes do nome da
varivel), caso contrrio os dados lidos no sero retornados.
nQtdBytes Define a quantidade de bytes que devem ser lidas do arquivo a partir
posicionamento do ponteiro atual.

E Retorno:

Numrico Quantidades de bytes lidos. Caso a quantidade seja menor que a solicitada, isto
indica erro de leitura ou final de arquivo. Verifique a funo FERROR() para mais
detalhes.

Exemplo: Gerao de arquivo TXT, utilizando a primeira famlia de funes


/*/
+-------------------------------------------------------------------
------
| Programa | GeraTXT | Autor | SERGIO FUZINAKA | Data | |
+-------------------------------------------------------------------
------
| Descrio | Gera o arquivo TXT, a partir do Cadastro de
Clientes
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL |
+-------------------------------------------------------------------
------
/*/

User Function GeraTXT()

//+--------------------------------+
//| Declarao de Variveis |
//+--------------------------------+
Local oGeraTxt
Private cPerg := "EXPSA1"
Private cAlias := "SA1"

//CriaSx1(cPerg)
//Pergunte(cPerg,.F.)
dbSetOrder(1)

//+-----------------------------------+
//| Montagem da tela de processamento.|
//+-----------------------------------+

DEFINE MSDIALOG oGeraTxt TITLE OemToAnsi("Gerao de Arquivo Texto")
;
FROM 000,000 TO 200,400 PIXEL

@ 005,005 TO 095,195 OF oGeraTxt PIXEL
@ 010,020 Say " Este programa ira gerar um arquivo texto, conforme
os parame- ";
OF oGeraTxt PIXEL
@ 018,020 Say " tros definidos pelo usurio, com os registros do
arquivo de ";
OF oGeraTxt PIXEL
@ 026,020 Say " SA1 " OF oGeraTxt PIXEL

DEFINE SBUTTON FROM 070, 030 TYPE 1 ;
ACTION (OkGeraTxt(),oGeraTxt:End()) ENABLE OF oGeraTxt

ACTION (oGeraTxt:End()) ENABLE OF oGeraTxt

ACTION (Pergunte(cPerg,.T.)) ENABLE OF oGeraTxt

ACTIVATE DIALOG oGeraTxt CENTERED

Return Nil


/*/
+-------------------------------------------------------------------
------
| Funo | OKGERATXT | Autor | SERGIO FUZINAKA | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo chamada pelo boto OK na tela inicial de
processamento. |
| | Executa a gerao do arquivo texto.
|
+-------------------------------------------------------------------
------
/*/

Static Function OkGeraTxt

//+-----------------------------------------------------------------
------
//| Cria o arquivo texto
//+-----------------------------------------------------------------
------
Private cArqTxt := "\SYSTEM\EXPSA1.TXT"
Private nHdl := fCreate(cArqTxt)

If nHdl == -1
MsgAlert("O arquivo de nome "+cArqTxt+" no pode ser executado!
Verifique os parmetros.","Ateno!")
Return
Endif

// Inicializa a rgua de processamento
Processa({|| RunCont() },"Processando...")

Return Nil

/*/
+-------------------------------------------------------------------
-----
| Funo | RUNCONT | Autor | SERGIO FUZINAKA | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo auxiliar chamada pela PROCESSA. A funo
PROCESSA |
| | monta a janela com a rgua de processamento.
|
+-------------------------------------------------------------------
------
/*/

Static Function RunCont

Local cLin

dbGoTop()
ProcRegua(RecCount()) // Numero de registros a processar

While (cAlias)->(!EOF())
//Incrementa a rgua
IncProc()

cLin := (cAlias)->A1_FILIAL
cLin += (cAlias)->A1_COD
cLin += (cAlias)->A1_LOJA
cLin += (cAlias)->A1_NREDUZ
cLin += STRZERO((cAlias)->A1_MCOMPRA*100,16) // 14,2
cLin += DTOS((cAlias)->A1_ULTCOM)//AAAAMMDD
cLin += CRLF


//+-----------------------------------------------------------------
--+
//| Gravao no arquivo texto. Testa por erros durante a gravao da
|
//| linha montada.
|
//+-----------------------------------------------------------------
--+

If fWrite(nHdl,cLin,Len(cLin)) != Len(cLin)
If !MsgAlert("Ocorreu um erro na gravao do
arquivo."+;
"Continua?","Ateno!")
Exit
Endif
Endif

(cAlias)->(dbSkip())
EndDo

// O arquivo texto deve ser fechado, bem como o dialogo criado na
funo anterior
fClose(nHdl)

Return Nil

Note que para a gerao do arquivo TXT foram utilizadas,
basicamente, as funes FCreate, FWrite e FClose que,
respectivamente, gera o arquivo, adiciona dados e fecha o
arquivo. No exemplo, o formato estabelecido pela
concatenao dos dados na varivel cLin a qual utilizada na
gravao dos dados. Para a leitura de dados TXT sero utilizada as
funes FOpen e FRead.

Exemplo: Leitura de arquivo TXT, utilizando a primeira famlia de
funes

#Include "protheus.ch"

/*/
+-------------------------------------------------------------------
----
| Programa | LeTXT | Autor | SERGIO FUZINAKA | Data |
|
+-------------------------------------------------------------------
----
| Descrio | Leitura de arquivo TXT
|
+-------------------------------------------------------------------
----
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
----
/*/
User Function LeTXT()

//+-----------------------------------------------------------------
--+
//| Declarao de Variveis
|
//+-----------------------------------------------------------------
--+

Local cPerg := "IMPSA1"
Local oLeTxt

Private cAlias := "SA1"

//CriaSx1(cPerg)
//Pergunte(cPerg,.F.)


dbSetOrder(1)

//+-----------------------------------------------------------------
--+
// Montagem da tela de processamento
|
//+-----------------------------------------------------------------
--+

DEFINE MSDIALOG oLeTxt TITLE OemToAnsi("Leitura de Arquivo Texto");
FROM 000,000 TO 200,400 PIXEL
@ 005,005 TO 095,195 OF oLeTxt PIXEL
@ 10,020 Say " Este programa ira ler o contedo de um arquivo texto,
conforme";
OF oLeTxt PIXEL
@ 18,020 Say " os parmetros definidos pelo usurio, com os
registros do arquivo";
OF oLeTxt PIXEL
@ 26,020 Say " SA1" OF oLeTxt PIXEL

ACTION (OkLeTxt(),oLeTxt:End()) ENABLE OF oLeTxt

ACTION (oLeTxt:End()) ENABLE OF oLeTxt

ACTION (Pergunte(cPerg,.T.)) ENABLE OF oLeTxt
ACTIVATE DIALOG oLeTxt CENTERED

Return Nil

/*/
+-------------------------------------------------------------------
------
| Funo | OKLETXT | Autor | SERGIO FUZINAKA | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo chamada pelo boto OK na tela inicial de
processamento |
| | Executa a leitura do arquivo texto
|
+-------------------------------------------------------------------
------
/*/

Static Function OkLeTxt()

//+-----------------------------------------------------------------
--+
//| Abertura do arquivo texto
|
//+-----------------------------------------------------------------
--+

Private cArqTxt := "\SYSTEM\EXPSA1.TXT"
Private nHdl := fOpen(cArqTxt,68)

If nHdl == -1
MsgAlert("O arquivo de nome "+cArqTxt+" no pode ser aberto!
Verifique os parmetros.","Ateno!")
Return
Endif

// Inicializa a rgua de processamento
Processa({|| RunCont() },"Processando...")
Return Nil

/*/
+-------------------------------------------------------------------
-----
| Funo | RUNCONT | Autor | SERGIO FUZINAKA | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo auxiliar chamada pela PROCESSA. A funo
PROCESSA |
| | monta a janela com a rgua de processamento.
|
+-------------------------------------------------------------------
------
/*/

Static Function RunCont

Local nTamFile := 0
Local nTamLin := 56
Local cBuffer := ""
Local nBtLidos := 0
Local cFilSA1 := ""
Local cCodSA1 := ""
Local cLojaSA1 := ""

//123456789012345678901234567890123456789012345678901234567890123456
7890
//000000000100000000020000000003000000000400000000050000000006000000
00070
//FFCCCCCCLLNNNNNNNNNNNNNNNNNNNNVVVVVVVVVVVVVVVVDDDDDDDD
//A1_FILIAL - 01, 02 - TAM: 02
//A1_COD - 03, 08 - TAM: 06
//A1_LOJA - 09, 10 - TAM: 02
//A1_NREDUZ - 11, 30 - TAM: 20
//A1_MCOMPRA - 31, 46 - TAM: 14,2
//A1_ULTCOM - 47, 54 - TAM: 08

nTamFile := fSeek(nHdl,0,2)
fSeek(nHdl,0,0)
cBuffer := Space(nTamLin) // Varivel para criao da linha do
registro para leitura

ProcRegua(nTamFile) // Numero de registros a processar
While nBtLidos < nTamFile

//Incrementa a rgua
IncProc()

// Leitura da primeira linha do arquivo texto
nBtLidos += fRead(nHdl,@cBuffer,nTamLin)

cFilSA1 := Substr(cBuffer,01,02) //- 01, 02 - TAM: 02
cCodSA1 := Substr(cBuffer,03,06) //- 03, 08 - TAM: 06
cLojaSA1 := Substr(cBuffer,09,02) //- 09, 10 - TAM: 02

While .T.
IF dbSeek(cFilSA1+cCodSA1+cLojaSA1)
cCodSA1 := SOMA1(cCodSA1)
Loop
Else
Exit
Endif
Enddo


RecLock(cAlias,.T.)
(cAlias)->A1_FILIAL := cFilSA1 //- 01, 02 - TAM: 02
(cAlias)->A1_COD := cCodSA1 //- 03, 08 - TAM: 06
(cAlias)->A1_LOJA := cLojaSA1 //- 09, 10 - TAM: 02
(cAlias)->A1_NREDUZ := Substr(cBuffer,11,20)
//- 11, 30 - TAM: 20
(cAlias)->A1_MCOMPRA := Val(Substr(cBuffer,31,16))/100
//- 31, 46 - TAM: 14,2
(cAlias)->A1_ULTCOM := STOD(Substr(cBuffer,47,08))
//- 47, 54 - TAM: 08
MSUnLock()

EndDo

// O arquivo texto deve ser fechado, bem como o dialogo criado na
funo anterior.
fClose(nHdl)

Return Nil

2.18.2 2 Famlia de funes de gravao e leitura de arquivos texto

2.18.2.1 FT_FUSE()

Funo que abre ou fecha um arquivo texto para uso das funes FT_F*. As funes
FT_F* so usadas para ler arquivos texto, onde as linhas so delimitadas pela seqncia
de caracteres CRLF ou LF (*) e o tamanho mximo de cada linha 1022 bytes. O
arquivo aberto em uma rea de trabalho, similar usada pelas tabelas de dados.

E Sintaxe: FT_FUSE ( [ cTXTFile ] )
E Parmetros:

cTXTFile Corresponde ao nome do arquivo TXT a ser aberto. Caso o nome no seja
passado, e j exista um arquivo aberto. o mesmo fechado.

E Retorno:

Numrico A funo retorna o Handle de controle do arquivo. Em caso de falha de abertura,
a funo retornar -1

2.18.2.2 FT_FGOTOP()

A funo tem como objetivo mover o ponteiro, que indica a leitura do arquivo texto,
para a posio absoluta especificada pelo argumento <nPos>.

E Sintaxe: FT_FGOTO ( < nPos > )

E Parmetros:

nPos Indica a posio que ser colocado o ponteiro para leitura dos dados no
arquivo.

2.18.2.3 FT_FLASTREC()

Funo que retorna o nmero total de linhas do arquivo texto aberto pela FT_FUse. As
linhas so delimitadas pela seqncia de caracteres CRLF o LF.

E Sintaxe: FT_FLASTREC( )

E Parmetros:

Nenhum ()

E Retorno:

Numrico Retorna a quantidade de linhas existentes no arquivo. Caso o arquivo esteja
vazio, ou no exista arquivo aberto, a funo retornar 0 (zero).

2.18.2.4 FT_FEOF()

Funo que retorna verdadeiro (.t.) se o arquivo texto aberto pela funo FT_FUSE()
estiver posicionado no final do arquivo, similar funo EOF() utilizada para arquivos
de dados.

E Sintaxe: FT_FEOF( )

E Parmetros:

Nenhum ()

E Retorno:

Lgico Retorna true caso o ponteiro do arquivo tenha chegado ao final; false caso
contrrio.

2.18.2.5 FT_FREADLN()

Funo que retorna uma linha de texto do arquivo aberto pela FT_FUse. As linhas so
delimitadas pela seqncia de caracteres CRLF ( chr(13) + chr(10) ), ou apenas LF (
chr(10 ), e o tamanho mximo de cada linha 1022 bytes.

E Sintaxe: FT_FREADLN( )

E Parmetros:

Nenhum ()

E Retorno:

Caracter Retorna a linha inteira na qual est posicionado o ponteiro para leitura de
dados.

2.18.2.6 FT_FSKIP()

Funo que move o ponteiro do arquivo texto aberto pela FT_FUSE() para a prxima
linha, similar ao DBSKIP() usado para arquivos de dados.

E Sintaxe: FT_FSKIP ( [ nLinhas ] )
E Parmetros:

nLinhas nLinhas corresponde ao nmero de linhas do arquivo TXT ref. movimentao do
ponteiro de leitura do arquivo.

E Retorno

Nenhum ()

2.18.2.7 FT_FGOTO()

Funo utilizada para mover o ponteiro, que indica a leitura do arquivo texto, para a
posio absoluta especificada pelo argumento <nPos>.


E Parmetros:

arquivo.

E Retorno:

Nenhum ()

2.18.2.8 FT_FRECNO()

A funo tem o objetivo de retornar a posio do ponteiro do arquivo texto.
A funo FT_FRecno retorna a posio corrente do ponteiro do arquivo texto aberto
pela FT_FUse.

E Sintaxe: FT_FRECNO ( )
E Parmetros:

Nenhum ()

E Retorno:

Caracter Retorna a posio corrente do ponteiro do arquivo texto.

Exemplo: Leitura de arquivo TXT, utilizando a segunda famlia de funes


/*/
+-------------------------------------------------------------------
------
| Programa | LeArqTXT | Autor | Robson Luiz | Data | |
+-------------------------------------------------------------------
------
| Descrio | Leitura de arquivo TXT
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
-----/*/
User Function LeArqTxt()

Private nOpc := 0
Private cCadastro := "Ler arquivo texto"
Private aSay := {}
Private aButton := {}

AADD( aSay, "O objetivo desta rotina e efetuar a leitura em um
arquivo texto" )

AADD( aButton, { 1,.T.,{|| nOpc := 1,FechaBatch()}})
AADD( aButton, { 2,.T.,{|| FechaBatch() }} )

FormBatch( cCadastro, aSay, aButton )

If nOpc == 1
Processa( {|| Import() }, "Processando..." )
Endif
Return Nil

//+-------------------------------------------
//| Funo - Import()
//+-------------------------------------------
Static Function Import()

Local cBuffer := ""
Local cFileOpen := ""
Local cTitulo1 := "Selecione o arquivo"
Local cExtens := "Arquivo TXT | *.txt"

/***
* _________________________________________________________
* cGetFile(<ExpC1>,<ExpC2>,<ExpN1>,<ExpC3>,<ExpL1>,<ExpN2>)
*
* <ExpC1> - Expresso de filtro
* <ExpC2> - Titulo da janela
* <ExpN1> - Numero de mascara default 1 para *.Exe
* <ExpC3> - Diretrio inicial se necessrio
* <ExpL1> - .F. boto salvar - .T. boto abrir
* <ExpN2> - Mascara de bits para escolher as opes de visualizao
do objeto
* (prconst.ch)
*/
cFileOpen := cGetFile(cExtens,cTitulo1,,cMainPath,.T.)

If !File(cFileOpen)
MsgAlert("Arquivo texto: "+cFileOpen+" no localizado",cCadastro)
Return
Endif

FT_FUSE(cFileOpen) //ABRIR
FT_FGOTOP() //PONTO NO TOPO
ProcRegua(FT_FLASTREC()) //QTOS REGISTROS LER

While !FT_FEOF() //FACA ENQUANTO NAO FOR FIM DE ARQUIVO
IncProc()

// Capturar dados
cBuffer := FT_FREADLN() //LENDO LINHA

cMsg := "Filial: " +SubStr(cBuffer,01,02) +
Chr(13)+Chr(10)
cMsg += "Cdigo: " +SubStr(cBuffer,03,06) +
Chr(13)+Chr(10)
cMsg += "Loja: " +SubStr(cBuffer,09,02) +
Chr(13)+Chr(10)
cMsg += "Nome fantasia: " +SubStr(cBuffer,11,15) +
Chr(13)+Chr(10)
cMsg += "Valor: " +SubStr(cBuffer,26,14) +
Chr(13)+Chr(10)
cMsg += "Data: " +SubStr(cBuffer,40,08) +
Chr(13)+Chr(10)

MsgInfo(cMsg)

FT_FSKIP() //prximo registro no arquivo txt
EndDo

FT_FUSE() //fecha o arquivo txt
MsgInfo("Processo finalizada")
Return Nil

Exerccio 15
Desenvolver uma rotina que realize a exportao dos itens marcados no cadastro
de clientes para um arquivo TXT em um diretrio especificado pelo usurio.

Exerccio 16
Desenvolver uma rotina que realize a importao dos dados de clientes contidos
em um arquivo TXT, sendo o mesmo selecionado pelo usurio.

11. Oficina de programao I

2.19 Interfaces com sintaxe clssica

A sintaxe convencional para definio de componentes visuais da linguagem ADVPL
depende diretamente do include especificado no cabealho do fonte. Os dois includes
disponveis para o ambiente ADVPL Protheus so:

E RWMAKE.CH: permite a utilizao da sintaxe CLIPPER na definio dos
componentes visuais.

E PROTHEUS.CH: permite a utilizao da sintaxe ADVPL convencional, a qual um
aprimoramento da sintaxe CLIPPER, com a incluso de novos atributos para os
componentes visuais disponibilizados no ERP Protheus.

Para ilustrar a diferena na utilizao destes dois includes, seguem abaixo as diferentes
definies para o componentes Dialog e MsDialog:

Exemplo 01 Include Rwmake.ch

#include rwmake.ch

@ 0,0 TO 400,600 DIALOG oDlg TITLE "Janela em sintaxe Clipper"
ACTIVATE DIALOG oDlg CENTERED

Exemplo 02 Include Protheus.ch


DEFINE MSDIALOG oDlg TITLE "Janela em sintaxe ADVPL "FROM 000,000 TO
400,600 PIXEL
ACTIVATE MSDIALOG oDlg CENTERED

Ambas as sintaxes produziro o mesmo efeito quando compiladas e
executadas no ambiente Protheus. Mas, deve ser utilizada e a sintaxe
ADVPL atravs do uso do include PROTHEUS.CH

Os componentes da interface visual que sero tratados neste tpico, utilizando a
sintaxe clssica da linguagem ADVPL so:

BUTTON()
CHECKBOX()
COMBOBOX()
FOLDER()
MSDIALOG()
MSGET()
RADIO()
SAY()
SBUTTON()

Executar o fonte DIALOG_OBJETOS.PRW e avaliar a definio dos componentes utilizados utilizando
a sintaxe clssica.

BUTTON()

Sintaxe
@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE OF
oObjetoRef ACTION AO
Descrio
Define o componente visual Button, que permite a incluso de botes de
operao na tela da interface, os quais sero visualizados somente com um
texto simples para sua identificao.

CHECKBOX()

Sintaxe @ nLinha,nColuna CHECKBOX oCheckBox VAR VARIAVEL PROMPT cTexto
WHEN WHEN UNIDADE OF oObjetoRef SIZE nLargura,nAltura MESSAGE
cMensagem
Descrio
Define o componente visual CheckBox, o qual permite a utilizao da uma
marca para habilitar ou no uma opo escolhida, sendo esta marca
acompanhada de um texto explicativo. Difere do RadioMenu pois cada
elemento do check nico, mas o Radio permite a utilizao de uma lista junto
com um controle de seleo.

COMBOBOX()

Sintaxe
@ nLinha,nColuna COMBOBOX VARIAVEL ITEMS AITENS SIZE
nLargura,nAltura UNIDADE OF oObjetoRef
Descrio
Define o componente visual ComboBox, o qual permite seleo de um item
dentro de uma lista de opes de textos simples no formato de um vetor.

FOLDER()

Sintaxe
@ nLinha,nColuna FOLDER oFolder OF oObjetoRef PROMPT
&cTexto1,,&cTextoX PIXEL SIZE nLargura,nAltura
Descrio
Define o componente Visual Folder, o qual permite a incluso de diversos
Dialogs dentro de uma mesma interface visual. Um folder pode ser entendido
como um array de dialogs, aonde cada painel recebe seus componentes e tem
seus atributos definidos independentemente dos demais.

MSDIALOG()

Sintaxe
DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO
nLiFim,nColFim OF oObjetoRef UNIDADE
Descrio
Define o componente MSDIALOG(), o qual utilizado como base para os demais
componentes da interface visual, pois um componente MSDIALOG() uma
janela da aplicao.

MSGET()

Sintaxe
@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF
oObjetoRef F3 cF3 VALID VALID WHEN WHEN PICTURE cPicture
Descrio
Define o componente visual MSGET, o qual utilizado para captura de
informaes digitveis na tela da interface.

RADIO()

Sintaxe
@ nLinha,nColuna RADIO oRadio VAR nRadio 3D SIZE nLargura,nAltura
<ITEMS PROMPT> cItem1,cItem2,...,cItemX OF oObjetoRef UNIDADE ON
CHANGE CHANGE ON CLICK CLICK
Descrio
Define o componente visual Radio, tambm conhecido como RadioMenu, o qual
seleo de uma opo ou de mltiplas opes atravs de uma marca para os
itens exibidos de uma lista. Difere do componente CheckBox, pois cada
elemento de check sempre nico, e o Radio pode conter um ou mais
elementos.

SAY()

Sintaxe
@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF
oObjetoRef
Descrio
Define o componente visual SAY, o qual utilizado para exibio de textos em
uma tela de interface.

SBUTTON()

Sintaxe
DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS
OF oObjetoRef
Descrio
Define o componente visual SButton, que permite a incluso de botes de
operao na tela da interface, os quais sero visualizados, dependendo da
interface do sistema ERP utilizada, somente com um texto simples para sua
identificao, ou com uma imagem (BitMap) pr-definido.

2.20 Rguas de processamento

Os indicadores de progresso ou rguas de processamento disponveis na linguagem
ADVPL que sero abordados neste material so:

RPTSTATUS()
PROCESSA()
MSNEWPROCESS()
MSAGUARDE()
MSGRUN()

2.20.1 RptStatus()

Rgua de processamento simples, com apenas um indicador de progresso, utilizada no
processamento de relatrios do padro SetPrint().

E Sintaxe: RptStatus(bAcao, cMensagem)

E Retorno: Nil


E Parmetros:

bAcao
processamento.
cMensagem
durante a execuo.
Aparncia

Exemplo: Funo RPTStatus() e acessrias

/*/
+-------------------------------------------------------------------
------
| Funo | GRPTSTATUS | Autor | ROBSON LUIZ | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao das funes
RPTSTATUS() |
| | SETREGUA() E INCREGUA()
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function GRptStatus()
Local aSay := {}
Local aButton := {}
Local nOpc := 0
Local cTitulo := "Exemplo de Funes"
Local cDesc1 := "Este programa exemplifica a utilizao da funo
Processa() em conjunto"
Local cDesc2 := "com as funes de incremento ProcRegua() e
IncProc()"

Private cPerg := "RPTSTA"

CriaSX1()
Pergunte(cPerg,.F.)

AADD( aSay, cDesc1 )

AADD( aButton, { 5, .T., {|| Pergunte(cPerg,.T. ) }} )
AADD( aButton, { 1, .T., {|| nOpc := 1, FechaBatch() }} )
AADD( aButton, { 2, .T., {|| FechaBatch() }} )

FormBatch( cTitulo, aSay, aButton )

If nOpc <> 1
Return Nil
Endif

RptStatus( {|lEnd| RunProc(@lEnd)}, "Aguarde...","Executando
rotina.", .T. )

Return Nil

Exemplo: Funes acessrias da RPTStatus()

/*/
+-------------------------------------------------------------------
----------
| Funo | RUNPROC | Autor | ROBSON LUIZ | Data |
|
+-------------------------------------------------------------------
----------
| Descrio | Funo de processamento executada atravs da
RPTSTATUS() |
+-------------------------------------------------------------------
----------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
----------
/*/

Static Function RunProc(lEnd)
Local nCnt := 0

dbSelectArea("SX5")
dbSetOrder(1)
dbSeek(xFilial("SX5")+mv_par01,.T.)

While !Eof() .And. X5_FILIAL == xFilial("SX5") .And. X5_TABELA <=
mv_par02
nCnt++
dbSkip()
End


SetRegua(nCnt)
mv_par02
IncRegua()
If lEnd
MsgInfo(cCancel,"Fim")
Exit
Endif
dbSkip()
End
Return .T.

SETREGUA()

A funo SetRegua() utilizada para definir o valor mximo da rgua de progresso
criada atravs da funo RptStatus().

E Sintaxe: SetRegua(nMaxProc)

E Parmetros:


E Retorno:

Nenhum ()

Exemplo:

...

dbSelectArea("SA1")
dbGoTop()
SetRegua(LastRec())
While !Eof()
IncRegua()
If Li > 60
...

INCREGUA()

A funo IncRegua() utilizada para incrementar valor na rgua de progresso criada
atravs da funo RptStatus()

E Sintaxe: IncRegua(cMensagem)

E Parmetros:

execuo da funo IncRegua(), sendo que a taxa de atualizao da interface

E Retorno:

Nenhum ()

Exemplo:

...

dbSelectArea("SA1")
dbGoTop()
SetRegua(LastRec())
While !Eof()
IncRegua(Avaliando cliente:+SA1->A1_COD)
If Li > 60

2.20.2 Processa()

Rgua de processamento simples, com apenas um indicador de progresso, utilizada no
processamento de rotinas.

E Sintaxe: Processa(bAcao, cMensagem)

E Retorno: Nil


E Parmetros:

bAcao
processamento.
cMensagem
durante a execuo.
Aparncia

Exemplo: Funo PROCESSA() e acessrias

/*/
+-------------------------------------------------------------------
------
| Funo | GPROCES1 | Autor | ROBSON LUIZ | Data |
|
+-------------------------------------------------------------------
------
PROCESSA() |
| | PROCREGUA() E INCPROC()
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function GProces1()
Local aSay := {}
Local aButton := {}
Local nOpc := 0
Local cTitulo := "Exemplo de Funes"
Local cDesc1 := "Este programa exemplifica a utilizao da funo
Processa()"
Local cDesc2 := " em conjunto com as funes de incremento
ProcRegua() e"
Local cDesc3 := " IncProc()"


Private cPerg := "PROCES"

CriaSX1()
Pergunte(cPerg,.F.)


AADD( aButton, { 5, .T., {|| Pergunte(cPerg,.T. ) }} )
AADD( aButton, { 1, .T., {|| nOpc := 1, FechaBatch() }} )
AADD( aButton, { 2, .T., {|| FechaBatch() }} )

FormBatch( cTitulo, aSay, aButton )

If nOpc <> 1
Return Nil
Endif

Processa( {|lEnd| RunProc(@lEnd)}, "Aguarde...","Executando
rotina.", .T. )

Return Nil

/*/
+-------------------------------------------------------------------
------
|
+-------------------------------------------------------------------
------
PROCRSSA() |
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
----
/*/

Static Function RunProc(lEnd)
Local nCnt := 0

dbSelectArea("SX5")
dbSetOrder(1)

dbEval( {|x| nCnt++
},,{||X5_FILIAL==xFilial("SX5").And.X5_TABELA<=mv_par02})


ProcRegua(nCnt)
mv_par02
IncProc("Processando tabela: "+SX5->X5_CHAVE)
If lEnd
MsgInfo(cCancela,"Fim")
Exit
Endif
dbSkip()
End
Return .T.

SETPROC()

A funo SetProc() utilizada para definir o valor mximo da rgua de progresso
criada atravs da funo Processa().

E Sintaxe: Processa(nMaxProc)

E Parmetros:


E Retorno:

Nenhum ()

Exemplo:
...
dbSelectArea("SA1")
dbGoTop()
SetProc(LastRec())
While !Eof()
IncProc()
If Li > 60
...

INCPROC()

A funo IncProc() utilizada para incrementar valor na rgua de progresso criada
atravs da funo Processa()

E Sintaxe: IncProc(cMensagem)

E Parmetros:

execuo da funo IncProc(), sendo que a taxa de atualizao da interface

E Retorno:

Nenhum ()

Exemplo:
...
dbSelectArea("SA1")
dbGoTop()
SetProc(LastRec())
While !Eof()
IncProc(Avaliando cliente:+SA1->A1_COD)
If Li > 60
...

2.20.3 MsNewProcess().

Rgua de processamento dupla, possuindo dois indicadores de progresso
independentes, utilizada no processamento de rotinas.

E Sintaxe: MsNewProcess():New(bAcao, cMensagem)

E Retorno: oProcess objeto do tipo MsNewProcess()

E Parmetros:

bAcao
processamento.
cMensagem
durante a execuo.
Aparncia



E Mtodos:

Activate() Inicia a execuo do objeto MsNewProcess instanciado.
SetRegua1() Define a quantidade de informaes que sero
demonstradas pelo indicador de progresso superior.
Parmetro: nMaxProc
IncRegua1() Incrementa em uma unidade o indicador de progresso
superior, o qual ir demonstrar a evoluo do
processamento de acordo com a quantidade definida
pelo mtodo SetRegua1().
Parmetro: cMensagem
SetRegua2() Define a quantidade de informaes que sero
demonstradas pelo indicador de progresso inferior.
Parmetro: nMaxProc
IncRegua2() Incrementa em uma unidade o indicador de progresso
inferior, o qual ir demonstrar a evoluo do
processamento de acordo com a quantidade definida
pelo mtodo SetRegua2().
Parmetro: cMensagem

Exemplo: Objeto MsNewProcess() e mtodos acessrios

/*/
+-------------------------------------------------------------------
------
| Funo | GPROCES2 | Autor | ROBSON LUIZ | Data |
|
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao do objeto
MsNewProcess() |
| | e seus mtodos IncReguaX() e SetReguaX()
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function GProces2()
Private oProcess := NIL

oProcess := MsNewProcess():New({|lEnd| RunProc(lEnd,oProcess)};
"Processando","Lendo...",.T.)
oProcess:Activate()

Return Nil

/*/
+-------------------------------------------------------------------
------
|
+-------------------------------------------------------------------
-----
MsNewProcess() |
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

Static Function RunProc(lEnd,oObj)
Local i := 0
Local aTabela := {}
Local nCnt := 0

aTabela := {{"00",0},{"13",0},{"35",0},{"T3",0}}

dbSelectArea("SX5")
cFilialSX5 := xFilial("SX5")
dbSetOrder(1)
For i:=1 To Len(aTabela)
dbSeek(cFilialSX5+aTabela[i,1])
While !Eof() .And. X5_FILIAL+X5_TABELA == cFilialSX5+aTabela[i,1]
If lEnd
Exit
Endif
nCnt++
dbSkip()
End
aTabela[i,2] := nCnt
nCnt := 0
Next i
oObj:SetRegua1(Len(aTabela))
For i:=1 To Len(aTabela)
If lEnd
Exit
Endif
oObj:IncRegua1("Lendo Tabela: "+aTabela[i,1])
dbSelectArea("SX5")
dbSeek(cFilialSX5+aTabela[i,1])
oObj:SetRegua2(aTabela[i,2])
While !Eof() .And. X5_FILIAL+X5_TABELA == cFilialSX5+aTabela[i,1]
oObj:IncRegua2("Lendo chave: "+X5_CHAVE)
If lEnd
Exit
Endif
dbSkip()
End
Next i
Return

2.20.4 MsAguarde().

Indicador de processamento sem incremento.

E Sintaxe: Processa(bAcao, cMensagem, cTitulo)

E Retorno: Nil

E Parmetros:

bAcao
processamento.
cMensagem
durante a execuo.
cTitulo Ttulo da janela da rgua de processamento.
Aparncia

Exemplo: MSAguarde()

/*/
+-------------------------------------------------------------------
------
| Funo | GMSAGUARDE | Autor | ROBSON LUIZ | Data |
|
+-------------------------------------------------------------------
------
MSAGUARDE() |
| | e MSPROCTXT()
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

USER FUNCTION GMsAguarde()
PRIVATE lEnd := .F.

MsAguarde({|lEnd| RunProc(@lEnd)},"Aguarde...","Processando
Clientes",.T.)

RETURN

/*/
+-------------------------------------------------------------------
------
|
+-------------------------------------------------------------------
------
| Descrio | Funo de processamento
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

STATIC FUNCTION RunProc(lEnd)

dbSelectArea("SX5")
dbSetOrder(1)
dbGoTop()

While !Eof()
If lEnd
MsgInfo(cCancel,"Fim")
Exit
Endif
MsProcTxt("Tabela: "+SX5->X5_TABELA+" Chave: "+SX5->X5_CHAVE)
dbSkip()
End

RETURN

2.20.5 MsgRun().

Indicador de processamento sem incremento.

E Sintaxe: Processa(cMensagem, cTitulo, bAcao)

E Retorno: Nil

E Parmetros:

cMensagem
durante a execuo.
cTitulo Ttulo da janela da rgua de processamento.
bAcao
Bloco de cdigo que especifica a ao que ser executada
com o acompanhamento da rgua de processamento.
Aparncia

Exemplo: MSGRun()

/*/
+-------------------------------------------------------------------
------
| Funo | GMSGRUN | Autor | ROBSON LUIZ |Data |
|
+-------------------------------------------------------------------
------
MSGRUN()
| | e DBEVAL()
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

USER FUNCTION GMsgRun()
LOCAL nCnt := 0

dbSelectArea("SX1")
dbGoTop()

MsgRun("Lendo arquivo, aguarde...","Ttulo opcional",{|| dbEval({|x|
nCnt++}) })

MsgInfo("Ufa!!!, li "+AllTrim(Str(nCnt))+" registros",FunName())

RETURN


2.21 ListBox()

A sintaxe clssica da linguagem ADVPL permite que o componente visual ListBox
implemente dois tipos distintos de objetos:

E Lista simples: lista de apenas uma coluna no formato de um vetor, a qual no
necessita da especificao de um cabealho.

E Lista com colunas: lista com diversas colunas que necessita de um cabealho
no formato de um aHeader (array de cabealho).

2.21.1 ListBox simples

E Sintaxe:

@ nLinha,nColuna LISTBOX oListbox VAR nLista ITEMS aLista SIZE
nLargura,nAltura OF oObjetoRef UNIDADE ON CHANGE CHANGE

E Parmetros:

nLinha,nColuna Posio do objeto ListBox em funo da janela em que
ele ser definido.
oListBox Objeto ListBox que ser criado.
nLista Varivel numrica que contm o nmero do item
selecionado no ListBox.
aLista Vetor simples contendo as strings que sero exibidas
no ListBox.
nLargura,nAltura Dimenses do objeto ListBox.
oObjetoRef Objeto dialog no qual o componente ser definido.
UNIDADE Unidade de medida das dimenses: PIXEL.
CHANGE Funo ou lista de expresses que ser executada na
seleo de um item do ListBox.


E Aparncia:

Exemplo: LISTBOX como lista simples


/*/
+-------------------------------------------------------------------
------
| Funo | LISTBOXITE | Autor | ROBSON LUIZ |Data |
|
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao do LISTBOX()
como lista |
| | simples.
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/
User Function ListBoxIte()

Local aVetor := {}
Local oDlg := Nil
Local oLbx := Nil
Local cTitulo := "Consulta Tabela"
Local nChave := 0
Local cChave := ""

dbSelectArea("SX5")
dbSetOrder(1)
dbSeek(xFilial("SX5"))

CursorWait()

//+-----------------------------------------+
//| Carrega o vetor conforme a condio |
//+-----------------------------------------+
While !Eof() .And. X5_FILIAL == xFilial("SX5") .And. X5_TABELA=="00"
AADD( aVetor, Trim(X5_CHAVE)+" - "+Capital(Trim(X5_DESCRI)) )
dbSkip()
End

CursorArrow()

If Len( aVetor ) == 0
Aviso( cTitulo, "No existe dados a consultar", {"Ok"} )
Return
Endif

//+-----------------------------------------------+
//| Monta a tela para usurio visualizar consulta |
//+-----------------------------------------------+
DEFINE MSDIALOG oDlg TITLE cTitulo FROM 0,0 TO 240,500 PIXEL
@ 10,10 LISTBOX oLbx VAR nChave ITEMS aVetor SIZE 230,95 OF oDlg
PIXEL
oLbx:bChange := {|| cChave := SubStr(aVetor[nChave],1,2) }
DEFINE SBUTTON FROM 107,183 TYPE 14 ACTION LoadTable(cChave) ENABLE
OF oDlg
DEFINE SBUTTON FROM 107,213 TYPE 1 ACTION oDlg:End() ENABLE OF oDlg


Return

Exemplo: LISTBOX como lista simples funes acessrias

/*/
+-------------------------------------------------------------------
------
| Funo | LISTBOXITE | Autor | ROBSON LUIZ |Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo que carrega os dados da tabela selecionada
em um |
| | listbox.
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

STATIC FUNCTION LoadTable(cTabela)

LOCAL aTabela := {}
LOCAL oDlg := NIL
LOCAL oLbx := NIL

dbSelectArea("SX5")
dbSeek(xFilial("SX5")+cTabela)

//+-------------------------------------------------------------
//| O vetor pode receber carga de duas maneiras, acompanhe... |
//+-------------------------------------------------------------
//| Utilizando While/End |
//+-------------------------------------------------------------

dbEval({|| AADD(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{||
X5_TABELA==cTabela})

If Len(aTabela)==0
Aviso( "FIM", "Necessrio selecionar um item", {"Ok"} )
Return
Endif

DEFINE MSDIALOG oDlg TITLE "Dados da tabela selecionada" FROM
300,400 TO 540,900 PIXEL
@ 10,10 LISTBOX oLbx FIELDS HEADER "Tabela", "Descrio" SIZE
230,095 OF oDlg PIXEL
oLbx:SetArray( aTabela )
oLbx:bLine := {|| {aTabela[oLbx:nAt,1],aTabela[oLbx:nAt,2]} }
ACTIVATE MSDIALOG oDlg

RETURN

2.21.2 ListBox mltiplas colunas

E Sintaxe:

@ nLinha,nColuna LISTBOX oListbox FIELDS HEADER Header1, , HeaderX
SIZE nLargura,nAltura OF oObjetoRef UNIDADE


E Parmetros:

nLinha,nColuna Posio do objeto ListBox em funo da
janela em que ele ser definido.
oListBox Objeto ListBox que ser criado.
nLista Varivel numrica que contm o nmero
do item selecionado no ListBox.
Header1,...,HeaderX Strings identificando os ttulos das
colunas do Grid.
nLargura,nAltura Dimenses do objeto ListBox.
oObjetoRef Objeto dialog no qual o componente
ser definido.
UNIDADE Unidade de medida das dimenses:
PIXEL.
CHANGE Funo ou lista de expresses que ser
executada na seleo de um item do
ListBox.

E Mtodos:

SetArray() Mtodo o objeto ListBox que define qual
array contm os dados que sero
exibidos no grid.

E Atributos:

bLine Atributo do objeto ListBox que vincula
cada linha,coluna do array, com cada
cabealho do grid.

E Aparncia:

Exemplo: LISTBOX com grid


/*/
+-------------------------------------------------------------------
------
| Funo | LIST_BOX | Autor | ROBSON LUIZ |Data |
|
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao de um
LISTBOX() com|
| | grid.
|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function List_Box()

Local aVetor := {}
Local oDlg
Local oLbx
Local cTitulo := "Cadastro de Bancos"
Local cFilSA6

dbSelectArea("SA6")
dbSetOrder(1)
cFilSA6 := xFilial("SA6")
dbSeek(cFilSA6)

// Carrega o vetor conforme a condio.
While !Eof() .And. A6_FILIAL == cFilSA6
AADD( aVetor, { A6_COD, A6_AGENCIA, A6_NUMCON, A6_NOME,
A6_NREDUZ, A6_BAIRRO, A6_MUN } )
dbSkip()
End

// Se no houver dados no vetor, avisar usurio e abandonar rotina.
If Len( aVetor ) == 0
Aviso( cTitulo, "No existe dados a consultar", {"Ok"} )
Return
Endif

// Monta a tela para usurio visualizar consulta.

// Primeira opo para montar o listbox.
@ 10,10 LISTBOX oLbx FIELDS HEADER ;
"Banco", "Agencia", "C/C", "Nome Banco", "Fantasia", "Bairro",
"Municpio" ;
SIZE 230,95 OF oDlg PIXEL

oLbx:SetArray( aVetor )
oLbx:bLine := {|| {aVetor[oLbx:nAt,1],;
aVetor[oLbx:nAt,2],;
aVetor[oLbx:nAt,7]}}


// Segunda opo para monta o listbox
/*
oLbx :=
TWBrowse():New(10,10,230,95,,aCabecalho,,oDlg,,,,,,,,,,,,.F.,,.T.,,.
F.,,,)
oLbx:SetArray( aVetor )
oLbx:bLine := {|| aEval(aVetor[oLbx:nAt],{|z,w|
aVetor[oLbx:nAt,w] } ) }
*/


Return
2.22 ScrollBox()

O ScrollBox o objeto utilizado para permitir que um dialog exiba barras de rolagem
verticais e Horizontais. Algumas aplicaes com objetos definem automaticamente o
ScrollBox, tais como:

E Enchoice() ou MsMGet()
E NewGetDados()
E ListBox()

Quando definido um objeto ScrollBox, os demais componentes da janela devero
referenciar este objeto e no mais o objeto dialog.

Desta forma o ScrollBox atribudo a um objeto dialog, e os componentes ao
ScrollBox.

Q MsDialog() ScrollBox()
Q ScrollBox() Componentes Visuais

E Sintaxe:

@ nLinha,nColuna SCROLLBOX oScrollBox HORIZONTAL VERTICAL SIZE
nLargura,nAltura OF oObjetoRef BORDER

E Parmetros:

nLinha,nColuna Posio do objeto ScrollBox em funo da
janela em que ele ser definido.
oScrollBox Objeto ScrollBox que ser criado.
HORIZONTAL Parmetro que quando definido habilita a
rgua de rolagem horizontal.
VERTICAL Parmetro que quando definido habilita a
rgua de rolagem vertical.
nLargura,nAltura Dimenses do objeto ScrollBox.
oObjetoRef Objeto dialog no qual o componente ser
definido.
BORDER

Parmetro que quando definido habilita a
exibio de uma borda de delimitao do
ScrollBox em relao a outros objetos.

E Aparncia:

Exemplo: Utilizao de mltiplos ScrollBoxes

#INCLUDE "PROTHEUS.CH"

/*/
+-------------------------------------------------------------------
-----
| Funo | SCROLL() | Autor | ROBSON LUIZ |Data |
|
+-------------------------------------------------------------------
-----
| Descrio | Programa que demonstra como montar uma enchoice
apenas |
| | com variveis, incluindo o recurso de rolagem.
|
+-------------------------------------------------------------------
-----
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
-----
/*/

USER FUNCTION Scroll()

LOCAL oDlg := NIL
LOCAL oScroll := NIL
LOCAL oLbx1 := NIL
LOCAL oLbx2 := NIL
LOCAL bGet := NIL
LOCAL oGet := NIL
LOCAL aAIIPM := {}
LOCAL aTitulo := {}
LOCAL nTop := 5
LOCAL nWidth := 0
LOCAL cGet := ""
LOCAL cPict := ""
LOCAL cVar := ""
LOCAL n := 0

PRIVATE cTitulo := "Consulta Parcelamento"
PRIVATE aSay := {}
PRIVATE cProcesso,cPrefixo,cTipo,cCliente,cLoja,cNome,cCGC
PRIVATE dData,nTotal,nUFESP,cStatus,cCond

cProcesso := "P00001"
cPrefixo := "UNI"
cTipo := "MAN"
cCliente := "000001"
cLoja := "01"
cNome := "JOSE DA SILVA SANTOS SOARES"
cCGC := "00.000.000/0001-91"
dData := "26/03/03"
nTotal := 5922.00
nUFESP := 1000.00
cStatus := "Z"
cCond := "001"

// Vetor para os campos no Scrooll Box
//+-------------------------------------+
//| aSay[n][1] - Titulo |
//| aSay[n][2] - Tipo |
//| aSay[n][3] - Tamanho |
//| aSay[n][4] - Decimal |
//| aSay[n][5] - Contedo/Varivel |
//| aSay[n][6] - Formato |
//+-------------------------------------+
AADD(aSay,{"Processo" ,"C",06,0,"cProcesso" ,"@!"})
AADD(aSay,{"Prefixo" ,"C",03,0,"cPrefixo" ,"@!"})
AADD(aSay,{"Tipo" ,"C",03,0,"cTipo" ,"@!"})
AADD(aSay,{"Cliente" ,"C",06,0,"cCliente" ,"@!"})
AADD(aSay,{"Loja" ,"C",02,0,"cLoja" ,"@!"})
AADD(aSay,{"Nome" ,"C",30,0,"cNome" ,"@!"})
AADD(aSay,{"CNPJ/CPF" ,"C",14,0,"cCGC" ,"@!"})
AADD(aSay,{"Dt.Processo" ,"D",08,0,"dData" ,"@!"})
AADD(aSay,{"Total R$" ,"N",17,2,"nTotal" ,"@!"})
AADD(aSay,{"Total UFESP" ,"N",17,2,"nUFESP" ,"@!"})
AADD(aSay,{"Status" ,"C",01,0,"cStatus" ,"@!"})
AADD(aSay,{"Cond.Pagto" ,"C",03,0,"cCond" ,"@!"})

// Vetor para List Box
AADD(aAIIPM,{"1234","DCD9815","26/03/03"})
AADD(aAIIPM,{"1234","DCD9815","26/03/03"})
AADD(aAIIPM,{"1234","DCD9815","26/03/03"})

// Vetor para List Box
AADD(aTitulo,{"A","26/03/03","26/03/03","1.974,00","100,00"})
AADD(aTitulo,{"A","26/03/03","26/03/03","1.974,00","100,00"})
AADD(aTitulo,{"A","26/03/03","26/03/03","1.974,00","100,00"})

DEFINE MSDIALOG oDlg TITLE cTitulo FROM 122,0 TO 432,600 OF oDlg
PIXEL
@ 013,002 TO 154,192 LABEL "Parcelamento" OF oDlg PIXEL
@ 013,195 TO 082,298 LABEL "Ttulos" OF oDlg PIXEL
@ 083,195 TO 154,298 LABEL "AIIPM" OF oDlg PIXEL

//scrollbox
@ 019,006 SCROLLBOX oScroll HORIZONTAL VERTICAL SIZE 131,182 OF
oDlg BORDER
For n:=1 TO Len(aSay)

bGet := &("{|| '"+aSay[n][1]+"'}")
cVar := aSay[n][5]
cGet := "{|u| IIF(PCount()>0,"+cVar+":=u,"+cVar+")}"
cPict := aSay[n][6]

TSay():New(nTop,5,bGet,oScroll,,,.F.,.F.,.F.,.T.,,,;
GetTextWidth(0,Trim(aSay[n][1])),15,;
.F.,.F.,.F.,.F.,.F.)
oGet:=TGet():New(nTop-
2,40,&cGet,oScroll,,7,cPict,,,,,.F.,,.T.,;
,.F.,,.F.,.F.,,.T.,.F.,,(cVar),,,,.T.)
nTop+=11
Next n

//listbox ttulos
@ 019,199 LISTBOX oLbx1 FIELDS HEADER ;
"Parcela","Vencto","Vencto.Real","Valor R$","Qtd.UFESP";
COLSIZES 21,24,33,63,100;
SIZE 095,059 OF oDlg PIXEL
oLbx1:SetArray( aTitulo )
oLbx1:bLine := {||{aTitulo[oLbx1:nAt,1],aTitulo[oLbx1:nAt,2],;
aTitulo[oLbx1:nAt,3],aTitulo[oLbx1:nAt,4],aTitulo[oLbx1:nAt,5]}}

//listbox aiipm
@ 089,199 LISTBOX oLbx2 FIELDS HEADER "AIIPM","Placa","Data
Multa" ;
COLSIZES 24,21,30 SIZE 095,061 OF oDlg PIXEL
oLbx2:SetArray( aAIIPM )
oLbx2:bLine :=
{||{aAIIPM[oLbx2:nAt,1],aAIIPM[oLbx2:nAt,2],aAIIPM[oLbx2:nAt,3]}}

ACTIVATE MSDIALOG oDlg CENTER ON INIT
EnchoiceBar(oDlg,{||oDlg:End()},{||oDlg:End()})

RETURN

2.23 ParamBox()

Implementa uma tela de parmetros, que no necessita da criao de um grupo de
perguntas no SX1, e com funcionalidades que a Pergunte() no disponibiliza, tais como
CheckBox e RadioButtons.

Cada componente da ParamBox ser associado a um parmetro Private denominado
MV_PARxx, de acordo com a ordem do componente na tela. Os parmetros da
ParamBox podem ser utilizados de forma independente em uma rotina especfica, ou
complementando opes de uma rotina padro.

Cuidados

A PARAMBOX define os parmetros seguindo o princpio das variveis
MV_PARxx. Caso ela seja utilizada em uma rotina em conjunto com parmetros
padres (SX1 + Pergunte()) necessrio salvar os parmetros padres, chamar a
Parambox(), salvar o retorno da Parambox() em variveis Private especficas
(MVPARBOXxx) e depois restaurar os parmetros padres, conforme o exemplo
desta documentao.

O objeto COMBO() da PARAMBOX() possui um problema em seu retorno: Caso
o combo no seja selecionado, ele manter seu contedo como numrico, caso
seja, ele receber o texto da opo e no o nmero da opo. O exemplo desta
documentao ilustra o tratamento de cdigo necessrio para proteger a
aplicao.

Ao utilizar a ParamBox em uma funo que tambm utilize parmetros
definidos pela funo Pergunte() deve-se:

E Salvar e restaurar os MV_PARs da Pergunte()
E Definir variveis Private prprias para a ParamBox, as quais iro armazenar o
contedo das MV_PARs que esta retorna.

E Sintaxe: ParamBox (aParamBox, cTitulo, aRet, bOk, aButtons, lCentered,;
nPosx, nPosy, oMainDlg, cLoad, lCanSave, lUserSave)

E Retorno: lOK indica se a tela de parmetros foi cancelada ou confirmada

E Parmetros:

aParamBox
Array de parmetros de acordo com a regra da
ParamBox.
cTitulo Titulo da janela de parmetros.
aRet
Array que ser passado por referncia e retornado com o
contedo de cada parmetro.
bOk
Bloco de cdigo para validao do OK da tela de
parmetros
aButtons
Array contendo a regra para adio de novos botes
(alm do OK e Cancelar) //
AADD(aButtons,{nType,bAction,cTexto})
lCentered
Se a tela ser exibida centralizada, quando a mesma no
estiver vinculada a outra janela.
nPosx Posio inicial -> linha (Linha final: nPosX+274).
nPosy Posio inicial -> coluna (Coluna final: nPosY+445).
oMainDlg Caso o ParamBox deva ser vinculado a uma outra tela.
cLoad
Nome do arquivo aonde as respostas do usurio sero
salvas / lidas.
lCanSave Se as respostas para as perguntas podem ser salvas.
lUserSave Se o usurio pode salvar sua prpria configurao.
E Aparncia:

E Regras do array aParamBox:

[1] Tipo do parmetro: Para cada tipo de parmetro as demais posies do array
variam de contedo conforme abaixo:

1 - MsGet
[2] : Descrio
[3] : String contendo o inicializador do campo
[4] : String contendo a Picture do campo
[5] : String contendo a validao
[6] : Consulta F3
[7] : String contendo a validao When
[8] : Tamanho do MsGet
[9] : Flag .T./.F. Parmetro Obrigatrio?

2 - Combo
[2] : Descrio
[3] : Numrico contendo a opo inicial do combo
[4] : Array contendo as opes do Combo
[5] : Tamanho do Combo
[6] : Validao

3 - Radio
[2] : Descrio
[3] : Numrico contendo a opo inicial do Rdio
[4] : Array contendo as opes do Rdio
[5] : Tamanho do Rdio
[6] : Validao

4 - CheckBox ( Com Say )
[2] : Descrio
[3] : Indicador Lgico contendo o inicial do Check
[4] : Texto do CheckBox
[6] : Validao

5 - CheckBox ( linha inteira )
[2] : Descrio
[3] : Indicador Lgico contendo o inicial do Check
[5] : Validao

6 - File
[2] : Descrio
[8] : Flag .T./.F. Parmetro Obrigatrio ?
[9] : Texto contendo os tipos de arquivo
Ex.: "Arquivos .CSV |*.CSV"
[10]: Diretrio inicial do CGETFILE()
[11]: Parmetros do CGETFILE()

7 - Montagem de expresso de filtro
[2] : Descrio
[3] : Alias da tabela
[4] : Filtro inicial
[5] : Opcional - Clusula When Boto Editar Filtro

8 - MsGet Password
[2] : Descrio
[6] : Consulta F3

9 - MsGet Say
[2] : String Contendo o Texto a ser apresentado
[3] : Tamanho da String
[4] : Altura da String
[5] : Negrito (lgico)

Exemplo: Utilizao da ParamBox()


/*/
+-------------------------------------------------------------------
----
| Funo | xParamBox | Autor | ROBSON LUIZ |Data |
|
+-------------------------------------------------------------------
----
| Descrio | Programa que demonstra a utilizao da PARAMBOX
como |
| | forma alternativa de disponibilizar parmetros em um
|
| | processamento.
|
+-------------------------------------------------------------------
----
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
----
/*/

User Function xParamBox()

Local aRet := {}
Local aParamBox := {}
Local aCombo :=
{"Janeiro","Fevereiro","Maro","Abril","Maio","Junho","Julho","Agost
o","Setembro","Outubro","Novembro","Dezembro"}
Local i := 0
Private cCadastro := "xParambox"

AADD(aParamBox,{1,"Produto",Space(15),"","","SB1","",0,.F.})
AADD(aParamBox,{2,"Tipo de cliente",1,aCombo,50,"",.F.})

AADD(aParamBox,{3,"Mostra
deletados",IIF(Set(_SET_DELETED),1,2),{"Sim","No"},50,"",.F.})

AADD(aParamBox,{4,"Marca todos ?",.F.,"Marque todos se necessrio
for.",50,"",.F.})

AADD(aParamBox,{5,"Marca todos ?",.F.,50,"",.F.})

AADD(aParamBox,{6,"Qual arquivo",Space(50),"","","",50,.F.,;
"Arquivo .DBF |*.DBF"})

AADD(aParamBox,{7,"Monte o
filtro","SX5","X5_FILIAL==xFilial('SX5')"})
AADD(aParamBox,{8,"Digite a senha",Space(15),"","","","",80,.F.})

If ParamBox(aParamBox,"Teste Parmetros...",@aRet)
For i:=1 To Len(aRet)
MsgInfo(aRet[i],"Opo escolhida")
Next
Endif

Return

Exemplo: Protegendo os parmetros MV_PARs da Pergunte() em uso.


/*/
+-------------------------------------------------------------------
------
| Funo | XPARBOX() | Autor | ARNALDO RAYMUNDO JR.|Data |
|
+-------------------------------------------------------------------
------
| Descrio | Funo utilizando a PARAMBOX() e protegendo os
MV_PARs|
| | ativos do programa principal.
|
+-------------------------------------------------------------------
------
+-------------------------------------------------------------------
-----
/*/
Static Function XPARBOX(cPerg)

Local cTitulo := "Transferncia para Operao"
Local bOk := {|| .T.}
Local aButtons := {}; Local aRet := {}
Local nPosx; Local nPosy; Local nX := 0
Local cLoad := ""
Local lCentered := .T.; Local lCanSave := .F.; Local lUserSave :=
.F.
Local aParamAtu := Array(4)

// Salva as perguntas padres antes da chamada da ParamBox
For nX := 1 to Len(aParamAtu)
aParamAtu [nX] := &("Mv_Par"+StrZero(nX,2))
Next nX

AADD(aParamBox,{2,"Atualiza taxa de depreciao?", 2, {"Sim","No"},
100,;
"AllwaysTrue()",.T.})

ParamBox(aParamBox, cTitulo, aRet, bOk, aButtons, lCentered, nPosx,
nPosy, /*oMainDlg*/ ,;
cLoad, lCanSave, lUserSave)

IF ValType(aRet) == "A" .AND. Len(aRet) == Len(aParamBox)
For nX := 1 to Len(aParamBox)
If aParamBox[nX][1] == 1
&("MvParBox"+StrZero(nX,2)) := aRet[nX]
ElseIf aParamBox[nX][1] == 2 .AND. ValType(aRet[nX]) ==
"C"
&("MvParBox"+StrZero(nX,2)) :=
aScan(aParamBox[nX][4],;
{|x| Alltrim(x) == aRet[nX]})
"N"
&("MvParBox"+StrZero(nX,2)) := aRet[nX]
Endif
Next nX
ENDIF

// Restaura as perguntas padres apos a chamada da ParamBox
For nX := 1 to Len(aParamAtu)
&("Mv_Par"+StrZero(nX,2)) := aParamAtu[nX]
Next nX

Return

MDULO 05: INTRODUO A ORIENTAO OBJETOS

12. Concei t os de or i ent ao obj et os
O termo orientao a objetos pressupe uma organizao de software em termos de
coleo de objetos discretos incorporando estrutura e comportamento prprios. Esta
abordagem de organizao essencialmente diferente do desenvolvimento tradicional
de software, onde estruturas de dados e rotinas so desenvolvidas de forma apenas
fracamente acopladas.

Neste tpico sero os conceitos de programao orientada a objetos listados abaixo.
Esta breve viso geral do paradigma permitir entender melhor os conceitos
associados programao orientada a objetos e, em particular, s construes
implementadas atravs da linguagem ADVPL.

E Objetos
E Herana
E Atributos
E Mtodos
E Classes
E Abstrao
E Generalizao
E Encapsulamento
E Polimorfismo

2.24 Definies

Objeto

Um objeto uma entidade do mundo real que tem uma identidade. Objetos podem
representar entidades concretas (um arquivo no meu computador, uma bicicleta) ou
entidades conceituais (uma estratgia de jogo, uma poltica de escalonamento em um
sistema operacional). Cada objeto ter sua identidade significa que dois objetos so
distintos mesmo que eles apresentem exatamente as mesmas caractersticas.

Embora objetos tenham existncia prpria no mundo real, em termos de linguagem de
programao, um objeto necessita um mecanismo de identificao. Esta identificao
de objeto deve ser nica, uniforme e independente do contedo do objeto. Este um
dos mecanismos que permite a criao de colees de objetos, as quais so tambm
objetos em si.

A estrutura de um objeto representada em termos de atributos. O comportamento de
um objeto representado pelo conjunto de operaes que podem ser executadas
sobre o objeto.

Classe

Objetos com a mesma estrutura e o mesmo comportamento so agrupados em
classes. Uma classe uma abstrao que descreve propriedades importantes para uma
aplicao e simplesmente ignora o resto.

Cada classe descreve um conjunto (possivelmente infinito) de objetos individuais. Cada
objeto dito ser uma instncia de uma classe. Assim, cada instncia de uma classe tem
seus prprios valores para cada atributo, mas dividem os nomes dos atributos e
mtodos com as outras instncias da classe. Implicitamente, cada objeto contm uma
referncia para sua prpria classe, em outras palavras: ele sabe o que ele .

Figura: Representao de uma classe de objetos


Figura: Representao de um objeto instanciado de uma classe

Polimorfismo

Polimorfismo significa que a mesma operao pode se comportar de forma diferente
em classes diferentes. Por exemplo, a operao move quando aplicada a uma janela de
um sistema de interfaces tem um comportamento distinto do que quando aplicada a
uma pea de um jogo de xadrez. Um mtodo uma implementao especfica de uma
operao para uma certa classe.

Polimorfismo tambm implica que uma operao de uma mesma classe pode ser
implementada por mais de um mtodo. O usurio no precisa saber quantas
implementaes existem para uma operao, ou explicitar qual mtodo deve ser
utilizado: a linguagem de programao deve ser capaz de selecionar o mtodo correto
a partir do nome da operao, classe do objeto e argumentos para a operao. Desta
forma, novas classes podem ser adicionadas sem necessidade de modificao de
cdigo j existente, pois cada classe apenas define os seus mtodos e atributos.

No mundo real, alguns objetos e classes podem ser descritos como casos especiais, ou
especializaes, de outros objetos e classes. Por exemplo, a classe de computadores
pessoais com processador da linha 80x86 uma especializao de computadores
pessoais, que por sua vez uma especializao de computadores. No desejvel que
tudo que j foi descrito para computadores tenha de ser repetido para computadores
pessoais ou para computadores pessoais com processador da linha 80x86.

Herana

Herana o mecanismo do paradigma de orientao a objetos que permite
compartilhar atributos e operaes entre classes baseada em um relacionamento
hierrquico. Uma classe pode ser definida de forma genrica e depois refinada
sucessivamente em termos de subclasses ou classes derivadas. Cada subclasse
incorpora, or herda, todas as propriedades de sua superclasse (ou classe base) e
adiciona suas propriedades nicas e particulares. As propriedades da classe base no
precisam ser repetidas em cada classe derivada. Esta capacidade de fatorar as
propriedades comuns de diversas classes em uma superclasse pode reduzir
significativamente a repetio de cdigo em um projeto ou programa, sendo uma das
principais vantagens da abordagem de orientao a objetos.

2.25 Conceitos Bsicos

A abordagem de orientao a objetos favorece a aplicao de diversos conceitos
considerados fundamentais para o desenvolvimento de bons programas, tais como
abstrao e encapsulamento.

Tais conceitos no so exclusivos desta abordagem, mas so suportados de forma
melhor no desenvolvimento orientado a objetos do que em outras metodologias.

Abstrao

Abstrao consiste de focalizar nos aspectos essenciais inerentes a uma entidade e
ignorar propriedades acidentais. Em termos de desenvolvimento de sistemas, isto
significa concentrar-se no que um objeto e faz antes de se decidir como ele ser
implementado. O uso de abstrao preserva a liberdade para tomar decises de
desenvolvimento ou de implementao apenas quando h um melhor entendimento
do problema a ser resolvido.

Muitas linguagens de programao modernas suportam o conceito de abstrao de
dados; porm, o uso de abstrao juntamente com polimorfismo e herana, como
suportado em orientao a objetos, um mecanismo muito mais poderoso.

O uso apropriado de abstrao permite que um mesmo modelo conceitual (orientao
a objetos) seja utilizado para todas as fases de desenvolvimento de um sistema, desde
sua anlise at sua documentao.

Encapsulamento

Encapsulamento, tambm referido como esconder informao, consiste em separar os
aspectos externos de um objeto, os quais so acessveis a outros objetos, dos detalhes
internos de implementao do objeto, os quais permanecem escondidos dos outros
objetos. O uso de encapsulamento evita que um programa torne-se to
interdependente que uma pequena mudana tenha grandes efeitos colaterais.

O uso de encapsulamento permite que a implementao de um objeto possa ser
modificada sem afetar as aplicaes que usam este objeto. Motivos para modificar a
implementao de um objeto podem ser, por exemplo, melhoria de desempenho,
correo de erros e mudana de plataforma de execuo.

Assim como abstrao, o conceito de Encapsulamento no exclusivo da abordagem
de orientao a objetos. Entretanto, a habilidade de se combinar estrutura de dados e
comportamento em uma nica entidade torna o Encapsulamento mais elegante e mais
poderoso do que em linguagens convencionais que separam estruturas de dados e
comportamento.

Compartilhamento

Tcnicas de orientao a objetos promovem compartilhamento em diversos nveis
distintos. Herana de estrutura de dados e comportamento permite que estruturas
comuns sejam compartilhadas entre diversas classes derivadas similares sem
redundncia. O compartilhamento de cdigo usando herana uma das grandes
vantagens da orientao a objetos. Ainda mais importante que a economia de cdigo
a clareza conceitual de reconhecer que operaes diferentes so na verdade a mesma
coisa, o que reduz o nmero de casos distintos que devem ser entendidos e analisados.

O desenvolvimento orientado a objetos no apenas permite que a informao dentro
de um projeto seja compartilhada como tambm oferece a possibilidade de
reaproveitar projetos e cdigo em projetos futuros. As ferramentas para alcanar este
compartilhamento, tais como abstrao, Encapsulamento e herana, esto presentes na
metodologia; uma estratgia de reuso entre projetos a definio de bibliotecas de
elementos reusveis. Entretanto, orientao a objetos no uma frmula mgica para
alcanar reusabilidade; para tanto, preciso planejamento e disciplina para pensar em
termos genricos, no voltados simplesmente para a aplicao corrente.

2.26 O Modelo de Objetos (OMT)

Um modelo de objetos busca capturar a estrutura esttica de um sistema mostrando os
objetos existentes, seus relacionamentos, atributos e operaes que caracterizam cada
classe de objetos. atravs do uso deste modelo que se enfatiza o desenvolvimento
em termos de objetos ao invs de mecanismos tradicionais de desenvolvimento
baseado em funcionalidades, permitindo uma representao mais prxima do mundo
real.

Uma vez que as principais definies e conceitos da abordagem de orientao a
objetos esto definidos, possvel introduzir o modelo de objetos que ser adotado ao
longo deste texto. O modelo apresentado um subconjunto do modelo OMT (Object
Modeling Technique), proposto por Rumbaugh entre outros. Este modelo tambm
introduz uma representao diagramtica para este modelo, a qual ser tambm
apresentada aqui.

2.26.1 Objetos e Classes

Objeto definido neste modelo como um conceito, abstrao ou coisa com
limites e significados bem definidos para a aplicao em questo. Objetos tm
dois propsitos: promover o entendimento do mundo real e suportar uma base
prtica para uma implementao computacional. No existe uma maneira
correta de decompor um problema em objetos; esta decomposio depende
do julgamento do projetista e da natureza do problema. Todos os objetos tm
identidade prpria e so distinguveis.

Uma classe de objetos descreve um grupo de objetos com propriedades
(atributos) similares, comportamentos (operaes) similares, relacionamentos
comuns com outros objetos e uma semntica comum. Por exemplo, Pessoa e
Companhia so classes de objetos. Cada pessoa tem um nome e uma idade;
estes seriam os atributos comuns da classe. Companhias tambm podem ter os
mesmos atributos nome e idade definidos. Entretanto, devido distino
semntica, elas provavelmente estariam agrupados em outra classe que no
Pessoa. Como se pode observar, o agrupamento em classes no leva em conta
apenas o compartilhamento de propriedades.

Todo objeto sabe a que classe ele pertence, ou seja, a classe de um objeto um
atributo implcito do objeto. Este conceito suportado na maior parte das
linguagens de programao orientada a objetos, inclusive em ADVPL.

OMT define dois tipos de diagramas de objetos, diagramas de classes e
diagramas de instncias. Um diagrama de classe um esquema, ou seja, um
padro ou gabarito que descreve as muitas possveis instncias de dados. Um
diagrama de instncias descreve como um conjunto particular de objetos est
relacionado. Diagramas de instncias so teis para apresentar exemplos e
documentar casos de testes; diagramas de classes tm uso mais amplos. A
Figura abaixo apresenta a notao adotada para estes diagramas.

Figura: Representao diagramtica de OMT para classes e objetos

O agrupamento de objetos em classes um poderoso mecanismo de abstrao. Desta
forma, possvel generalizar definies comuns para uma classe de objetos, ao invs
de repet-las para cada objeto em particular. Esta uma das formas de reutilizao e
economia que a abordagem de orientao a objetos suporta.

2.26.2 Atributos

Um atributo um valor de dado assumido pelos objetos de uma classe. Nome,
idade e peso so exemplos de atributos de objetos Pessoa. Cor, peso e modelo
so possveis atributos de objetos Carro. Cada atributo tem um valor para cada
instncia de objeto. Por exemplo, o atributo idade tem valor ``29'' no objeto
Pedro Y. Em outras palavras, Pedro Y tem 29 anos de idade. Diferentes
instncias de objetos podem ter o mesmo valor para um dado atributo.
Cada nome de atributo nico para uma dada classe, mas no necessariamente
nico entre todas as classes. Por exemplo, ambos Pessoa e Companhia podem
ter um atributo chamado endereo.

No diagrama de classes, atributos so listados no segundo segmento da caixa
que representa a classe. O nome do atributo pode ser seguido por detalhes
opcionais, tais como o tipo de dado assumido e valor default. A Figura abaixo
mostra esta representao.


Figura: Representao diagramtica de OMT para classes e objetos com atributos

No se deve confundir identificadores internos de objetos com atributos do mundo
real. Identificadores de objetos so uma convenincia de implementao, e no tm
nenhum significado para o domnio da aplicao. Por exemplo, CIC e RG no so
identificadores de objetos, mas sim verdadeiros atributos do mundo real.

2.26.3 Operaes e Mtodos

Uma operao uma funo ou transformao que pode ser aplicada a ou por
objetos em uma classe. Por exemplo, abrir, salvar e imprimir so operaes que
podem ser aplicadas a objetos da classe Arquivo. Todos os objetos em uma
classe compartilham as mesmas operaes.
Toda operao tem um objeto-alvo como um argumento implcito. O
comportamento de uma operao depende da classe de seu alvo. Como um
objeto sabe qual sua classe, possvel escolher a implementao correta da
operao. Alm disto, outros argumentos (parmetros) podem ser necessrios
para uma operao.

Uma mesma operao pode se aplicar a diversas classes diferentes. Uma
operao como esta dita ser polimrfica, ou seja, ela pode assumir distintas
formas em classes diferentes.
Um mtodo a implementao de uma operao para uma classe. Por
exemplo, a operao imprimir pode ser implementada de forma distinta,
dependendo se o arquivo a ser impresso contm apenas texto ASCII, um
arquivo de um processador de texto ou binrio. Todos estes mtodos executam
a mesma operao: imprimir o arquivo; porm, cada mtodo ser
implementado por um diferente cdigo.
A assinatura de um mtodo dada pelo nmero e tipos de argumentos do
mtodo, assim como por seu valor de retorno. Uma estratgia de
desenvolvimento recomendvel manter assinaturas coerentes para mtodos
implementando uma dada operao, assim como um comportamento
consistente entre as implementaes.
Em termos de diagramas OMT, operaes so listadas na terceira parte da caixa
de uma classe. Cada nome de operao pode ser seguida por detalhes
opcionais, tais como lista de argumentos e tipo de retorno. A lista de
argumentos apresentada entre parnteses aps o nome da operao. Uma
lista de argumentos vazia indica que a operao no tem argumentos; da
ausncia da lista de argumentos no se pode concluir nada. O tipo de resultado
vem aps a lista de argumentos, sendo precedido por dois pontos (:). Caso a
operao retorne resultado, este no deve ser omitido, pois esta a forma de
distingui-la de operaes que no retornam resultado. Exemplos de
representao de operaes em OMT so apresentados na Figura abaixo:

Figura: Representao diagramtica de OMT para classes com atributos e operaes

2.26.4 Sugestes de desenvolvimento

Na construo de um modelo para uma aplicao, as seguintes sugestes
devem ser observadas a fim de se obter resultados claros e consistentes:
E No comece a construir um modelo de objetos simplesmente definindo classes,
associaes e heranas. A primeira coisa a se fazer entender o problema a ser
resolvido.
E Tente manter seu modelo simples. Evite complicaes desnecessrias.
E Escolha nomes cuidadosamente. Nomes so importantes e carregam
conotaes poderosas. Nomes devem ser descritivos, claros e no deixar
ambigidades. A escolha de bons nomes um dos aspectos mais difceis da
modelagem.
E No enterre apontadores ou outras referncias a objetos dentro de objetos
como atributos. Ao invs disto, modele estas referncias como associaes. Isto
torna o modelo mais claro e independente da implementao.
E Tente evitar associaes que envolvam trs ou mais classes de objetos. Muitas
vezes, estes tipos de associaes podem ser decompostos em termos de
associaes binrias, tornando o modelo mais claro.
E No transfira os atributos de ligao para dentro de uma das classes.
E Tente evitar hierarquias de generalizao muito profundas.
E No se surpreenda se o seu modelo necessitar vrias revises; isto o normal.
E Sempre documente seus modelos de objetos. O diagrama pode especificar a
estrutura do modelo, mas nem sempre suficiente para descrever as razes por
trs da definio do modelo. Uma explicao escrita pode clarificar pontos tais
como significado de nomes e explicar a razo para cada classe e
relacionamento.
E Nem sempre todas as construes OMT so necessrias para descrever uma
aplicao. Use apenas aquelas que forem adequadas para o problema
analisado.
13. Orientao a objetos em ADVPL
Neste tpico ser detalhada a forma com a qual a linguagem ADVPL implementa os
conceitos de orientao a objetos e a sintaxe utilizada no desenvolvimento de
aplicaes.

2.27 Sintaxe e operadores para orientao a objetos

Palavras reservadas

CLASS
CONSTRUCTOR
DATA
ENDCLASS
FROM
METHOD
SELF

CLASS

Descrio
Utilizada na declarao de uma classe de objetos, e para identificar a qual classe
um determinado mtodo est relacionado.
Sintaxe 1 CLASS <nome_da_classe>
Sintaxe 2 METHOD <nome_do_mtodo> CLASS <nome_da_classe>

CONSTRUCTOR

Descrio
Utilizada na especificao de um mtodo especial, definido como construtor, o
qual tem a funo de retornar um novo objeto com os atributos e mtodos
definidos na classe.
Sintaxe METHOD <nome_do_mtodo()> CONSTRUCTOR

DATA

Descrio Utilizada na declarao de um atributo da classe de objetos.
Sintaxe DATA <nome_do_atributo>

ENDCLASS

Descrio Utilizada na finalizao da declarao da classe.
Sintaxe ENDCLASS

FROM

Descrio
Utilizada na declarao de uma classe, a qual ser uma instncia de uma
superclasse, recebendo os atributos e mtodos nela definidos, implementando a
herana entre classes.
Sintaxe CLASS <nome_da_classe> FROM <nome_da_superclasse>

METHOD

Descrio
Utilizada na declarao do prottipo do mtodo de uma classe de objetos, e na
declarao do mtodo efetivamente desenvolvido.
Sintaxe 1 METHOD <nome_do_mtodo()>
Sintaxe 2 METHOD <nome_do_mtodo(<parmetros>)> CLASS <nome_da_classe>

SELF

Descrio
Utilizada principalmente pelo mtodo construtor para retornar o objeto criado
para a aplicao.
Sintaxe Return SELF

Operadores especficos

:
Utilizado para referenciar um mtodo ou um atributo de um objeto j
instanciado.
Exemplo 1 cNome := oAluno:sNome
Exemplo 2 cNota := oAluno:GetNota(cCurso)

::
Utilizado pelos mtodos de uma classe para referenciar os atributos disponveis
para o objeto.
Exemplo
METHOD GetNota(cCurso) CLASS ALUNO

Local nPosCurso := 0
Local nNota := 0

nPosCurso := aScan(::aCursos,{|aCurso| aCurso[1] == cCurso})

IF nPosCurso > 0

nNota := ::aCursos[nPosCurso][2]

ENDIF

Return nNota

2.28 Estrutura de uma classe de objetos em ADVPL

Declarao da classe

A declarao de uma classe da linguagem ADVPL realizada de forma similar a
declarao de uma funo, com a diferena de que uma classe no possui
diferenciao quanto a sua procedncia, como uma Function() e uma User Function(), e
no possui visibilidade limitada como uma Static Function().

Exemplo:

CLASS Pessoa()

Definio dos atributos

Seguindo o mesmo princpio de variveis no tipadas, os atributos das classes em
ADVPL no precisam ter seu tipo especificado, sendo necessrio apenas determinar
seus nomes.

Desta forma recomendado o uso da notao Hngara tambm para a definio dos
atributos de forma a facilitar a anlise, interpretao e utilizao da classe e seus
objetos instanciados.

Exemplo:

CLASS Pessoa()

DATA cNome
DATA nIdade

Prototipao dos mtodos

A prototipao dos mtodos uma regra utilizada pelas linguagens orientadas a
objetos, atravs da qual so especificadas as operaes que podem ser realizadas pelo
objeto, diferenciando os mtodos de outras funes internas de uso da classe, e para
especificar quais so os mtodos construtores.

Em linguagens tipadas, na prototipao dos mtodos necessrio definir quais so os
parmetros recebidos e seus respectivos tipos, alm de definir o tipo do retorno que
ser fornecido. Em ADVPL necessrio apenas descrever a chamada do mtodo e caso
necessrio se o mesmo um construtor.

Exemplo:

CLASS Pessoa()

DATA cNome
DATA nIdade

METHOD Create() CONSTRUCTOR
METHOD SetNome()
METHOD SetIdade()

ENDCLASS

2.29 Implementao dos mtodos de uma classe em ADVPL

Mtodo Construtor

O mtodo construtor possui a caracterstica de retornar um objeto com o tipo da classe
da qual o mesmo foi instanciado. Por esta razo diz-se que o tipo do objeto
instanciado a classe daquele objeto.

Para produzir este efeito, o mtodo construtor utiliza a palavra reservada SELF, a qual
utilizada pela linguagem ADVPL para referncia a prpria classe daquele objeto.

Exemplo:

CLASS Pessoa()

DATA cNome
DATA nIdade

METHOD SetNome()
METHOD SetIdade()

ENDCLASS

METHOD Create(cNome, nIdade) CLASS Pessoa

::cNome := cNome
::nIdade := nIdade

Return SELF

Manipulao de atributos

Os atributos definidos para uma classe com a utilizao da palavra reservada DATA
em sua declarao podem ser manipulados por seus mtodos utilizando o operador
::.

A utilizao deste operador permite ao interpretador ADVPL diferenciar variveis
comuns criadas pelas funes e mtodos que utilizam este objeto dos atributos
propriamente ditos.

Exemplo:

CLASS Pessoa()

DATA cNome
DATA nIdade

METHOD SetNome()
METHOD SetIdade()
ENDCLASS

METHOD Create(cNome, nIdade) CLASS Pessoa

::cNome := cNome
::nIdade := nIdade

Return SELF

Utilizao de funes em uma classe de objetos

Conforme mencionado anteriormente, a utilizao da palavra reservada METHOD
permite ao interpretador ADVPL diferenciar os mtodos que podem ser utilizados
atravs da referncia do objeto de funes internas descritas internamente na classe.

Isto permite a utilizao de funes tradicionais da linguagem ADVPL, como as Static
Functions() as quais sero visveis apenas a classe, e no podero ser referenciadas
diretamente pelo objeto.

Exemplo parte 01: Funo CadPessoa (usuria da classe Pessoa)


USER FUNCTION CadPessoa()

Local oPessoa
Local cNome :=
Local dNascimento:= CTOD()
Local aDados := {}

aDados := GetDados()
oPessoa := Pessoa():Create(cNome,dNascimento)

Return

Exemplo parte 02: Classe Pessoa

CLASS Pessoa()

DATA cNome
DATA nIdade
DATA dNascimento

METHOD SetNome()
METHOD SetIdade()

ENDCLASS

METHOD Create(cNome, dNascimento) CLASS Pessoa
::cNome := cNome
::dNascimento := dNascimento
::nIdade := CalcIdade(dNascimento)
Return SELF

STATIC FUNCTION CalcIdade(dNascimento)
Local nIdade
nIdade := dDataBase - dNascimento
RETURN nIdade

Herana entre classes

Seguindo o principio da orientao a objetos, a linguagem ADVPL permite que uma
classe receba por herana os mtodos e atributos definidos em uma outra classe, a
qual tornasse a superclasse desta instncia.

Para utilizar este recurso deve ser utilizada a palavra reservada FROM na declarao
da classe, especificando a superclasse que ser referenciada.

Em ADVPL o exemplo prtico desta situao a superclasse TSrvObject, a qual
utilizada pela maioria das classes e componentes da interface visual, como
demonstrado no mdulo 06.

Exemplo parte 01: Declarao da classe Pessoa

CLASS Pessoa()

DATA cNome
DATA nIdade
DATA dNascimento

METHOD SetNome()
METHOD SetIdade()

ENDCLASS

Exemplo parte 02: Declarao da classe Aluno

CLASS Aluno() FROM Pessoa

DATA nID
DATA aCursos

METHOD Inscrever()
METHOD Avaliar()
METHOD GetNota()
METHOD GetStatus()

ENDCLASS

// Os objetos da classe Aluno, possuem todos os mtodos e atributos
da classe Pessoa, alm
// dos mtodos e atributos declarados na prpria classe.


Construtor para classes com herana

Quanto utilizado o recurso de herana entre classes, o construtor da classe
instanciada deve receber um tratamento adicional, para que o objeto instanciado seja
criado com os atributos e mtodos definidos na superclasse.

Nestes casos, logo aps a definio do mtodo construtor da classe, dever ser
executado o mtodo construtor da superclasse.

Exemplo parte 03: Mtodo Construtor da classe Aluno

METHOD Create(cNome,dNascimento,nID)
:Create(cNome,dNascimento) // Chamada do mtodo construtor da classe
Pessoa.

::nID := ID

Return SELF


MDULO 06: ADVPL ORIENTADO OBJETOS I
Neste mdulo sero tratados os componentes e objetos da interface visual da
linguagem ADVPL, permitindo o desenvolvimento de aplicaes com interfaces grficas
com sintaxe orientada a objetos.

14. Componentes da interface visual do ADVPL
A linguagem ADVPL possui diversos componentes visuais e auxiliares, os quais podem
ser representados utilizando a estrutura abaixo:

.
Classes da Interface
Visual

Tsrvobject
. Classes Auxiliares
Tfont

. Classes de Janelas
Msdialog
Tdialog
Twindow

.
Classes de
Componentes

Tcontrol

.
Classes de
Componentes
Visuais
Brgetddb
Mscalend
Mscalendgrid
Msselbr
Msworktime
Sbutton
Tbar
Tbitmap
Tbrowsebutton
Tbtnbmp
Tbtnbmp2
Tbutton
Tcbrowse
Tcheckbox
Tcolortriangle
Tcombobox
Tfolder
Tfont
Tget
Tgroup
Thbutton
Tibrowser
Tlistbox
Tmenu
Tmenubar
Tmeter
Tmsgraphic
Tmsgbar
Tmultibtn
Tmultiget
Tolecontainer
Tpageview
Tpanel
Tradmenu
Tsbrowse
Tsay
Tscrollbox
Tsimpleeditor
Tslider

.
Classes de
Componentes
Visuais
Tsplitter
Ttabs
Ttoolbox
Twbrowse
Vcbrowse

Classes da interface visual

TSRVOBJECT()

Descrio
Classe abstrata inicial de todas as classes de interface do ADVPL. No deve ser
instanciada diretamente.

Classes auxiliares

TFONT()

Descrio Classe de objetos que define a fonte do texto utilizado nos controles visuais.

Classes de janelas

MSDIALOG()

Descrio
Classe de objetos que deve ser utilizada como padro de janela para entrada
de dados. MSDialog um tipo de janela dilogo modal, isto , no permite
que outra janela ativa receba dados enquanto esta estiver ativa.

TDIALOG()

Descrio
Classe de objetos do tipo dilogo de entrada de dados, sendo seu uso
reservado. Recomenda-se utilizar a classe MSDialog que herdada desta
classe.

TWINDOW()

Descrio
Classe de objetos do tipo dilogo principal de programa. Dever existir
apenas uma instncia deste objeto na execuo do programa.

Classes de componentes

TCONTROL()

Descrio
Classe abstrata comum entre todos os componentes visuais editveis. No
deve ser instanciada diretamente.

Classes de componentes visuais

BRGETDDB()

Descrio Classe de objetos visuais do tipo Grid.
MSCALEND()

Descrio Classe de objetos visuais do tipo Calendrio.

MSCALENDGRID()

Descrio Classe de objetos visuais do tipo Grade de Perodos.

MSSELBR()

Descrio Classe de objetos visuais do tipo controle - Grid

MSWORKTIME()

Descrio Classe de objetos visuais do tipo controle - Barra de Perodo.

SBUTTON()

Descrio
Classe de objetos visuais do tipo boto, o qual pode possuir imagens
padres associadas ao seu tipo.

TBAR()

Descrio Classe de objetos visuais do tipo Barra Superior.

TBITMAP()

Descrio Classe de objetos visuais que permite a exibio de uma imagem.

TBROWSEBUTTON()

Descrio
Classe de objetos visuais do tipo boto no formato padro utilizado em
browses da aplicao.

TBTNBMP()

Descrio
Classe de objetos visuais do tipo boto, o qual permite que seja
vinculada uma imagem ao controle.

TBTNBMP2()

Descrio
Classe de objetos visuais do tipo boto, o qual permite a exibio de
uma imagem ou de um popup.

TBUTTON()

Descrio
Classe de objetos visuais do tipo boto, o qual permite a utilizao de
texto para sua identificao.

TCBROWSE()

Descrio Classe de objetos visuais do tipo Grid.

TCHECKBOX()

Descrio Classe de objetos visuais do tipo controle - CheckBox.

TCOLORTRIANGLE()

Descrio Classe de objetos visuais do tipo Paleta de Cores.

TCOMBOBOX()

Descrio
Classe de objetos visuais do tipo tComboBox, a qual cria uma entrada de
dados com mltipla escolha com item definido em uma lista vertical,
acionada por F4 ou pelo boto esquerdo localizado na parte direita do
controle. A varivel associada ao controle ter o valor de um dos itens
selecionados ou no caso de uma lista indexada, o valor de seu ndice.

TFOLDER()

Descrio Classe de objetos visuais do tipo controle - Folder.

TGET()

Descrio
Classe de objetos visuais do tipo controle tGet, a qual cria um controle
que armazena ou altera o contedo de uma varivel atravs de digitao.
O contedo da varivel s modificado quando o controle perde o foco
de edio para outro controle.

TGROUP()

Descrio
Classe de objetos visuais do tipo painel tGroup, a qual cria um painel
onde controles visuais podem ser agrupados ou classificados. Neste
painel criada uma borda com ttulo em volta dos controles agrupados.

THBUTTON()

Descrio Classe de objetos visuais do tipo boto com hiperlink.

TIBROWSER()

Descrio
Classe de objetos visuais do tipo Pgina de Internet, sendo necessrio
incluir a clausula BrowserEnabled=1 no Config do Remote.INI

TLISTBOX()

Descrio
Classe de objetos visuais do tipo controle tListbox, a qual cria uma
janela com itens selecionveis e barra de rolagem. Ao selecionar um
item, uma varivel atualizada com o contedo do item selecionado.

TMENU()

Descrio Classe de objetos visuais do tipo controle - Menu.

TMENUBAR()

Descrio Classe de objetos visuais do tipo controle - Barra de Menu.

TMETER()

Descrio
Classe de objetos visuais do tipo controle tMeter, a qual exibe uma
rgua (gauge) de processamento, descrevendo o andamento de um
processo atravs da exibio de uma barra horizontal.

TMSGRAPHIC()

Descrio Classe de objetos visuais do tipo controle - Grfico.

TMSGBAR()

Descrio Classe de objetos visuais do tipo controle - Rodap.

TMULTIBTN()

Descrio Classe de objetos visuais do tipo controle - Mltiplos botes.

TMULTIGET()

Descrio
Classe de objetos visuais do tipo controle - edio de texto de mltiplas
linhas.

TOLECONTAINER()

Descrio
Classe de objetos visuais do tipo controle, a qual permite a criao de
um boto vinculado a um objeto OLE.

TPAGEVIEW()

Descrio
Classe de objetos visuais do tipo controle, que permite a visualizao de
arquivos no formato gerado pelo spool de impresso do Protheus.

TPANEL()

Descrio
Classe de objetos visuais do tipo controle tPanel, a qual permite criar
um painel esttico, onde podem ser criados outros controles com o
objetivo de organizar ou agrupar componentes visuais.

TRADMENU()

Descrio
Classe de objetos visuais do tipo controle TRadMenu, a qual permite
criar um controle visual no formato Radio Button.

TSBROWSE()

Descrio
Classe de objetos visuais do tipo controle TSBrowse, a qual permite
criar um controle visual do tipo Grid.

TSAY()

Descrio
Classe de objetos visuais do tipo controle tSay, a qual exibe o contedo
de texto esttico sobre uma janela ou controle previamente definidos.

TSCROLLBOX()

Descrio
Classe de objetos visuais do tipo controle tScrollbox, a qual permite
criar um painel com scroll deslizantes nas laterais (horizontais e verticais)
do controle.

TSIMPLEEDITOR()

Descrio
Classe de objetos visuais do tipo controle tSimpleEditor, a qual permite
criar um controle visual para edio de textos com recursos simples,
como o NotePad

TSLIDER()

Descrio
Classe de objetos visuais do tipo controle tSlider, a qual permite criar
um controle visual do tipo boto deslizante.

TSPLITTER()

Descrio
Classe de objetos visuais do tipo controle tSplitter, a qual permite criar
um controle visual do tipo divisor.

TTABS()

Descrio
Classe de objetos visuais do tipo controle TTabs, a qual permite criar
um controle visual do tipo pasta.

TTOOLBOX()

Descrio
Classe de objetos visuais do tipo controle tToolbox, a qual permite criar
um controle visual para agrupar diferentes objetos.

TWBROWSE()

Descrio
Classe de objetos visuais do tipo controle TWBrowse, a qual permite

VCBROWSE()
Descrio
Classe de objetos visuais do tipo controle VCBrowse, a qual permite

Documentao dos componentes da interface visual

Os componentes da interface visual da linguagem ADVPL utilizados neste treinamento
esto documentados na seo Guia de Referncia, ao final deste material.

2.30 Particularidades dos componentes visuais

2.30.1 Configurando as cores para os componentes

Os componentes visuais da linguagem ADVPL utilizam o padro de cores RGB.

As cores deste padro so definidas pela seguinte frmula, a qual deve ser avaliada
tendo como base a paleta de cores no formato RGB:

nCor := nVermelho + (nVerde * 256) + (nAzul * 65536)

Figura: Paleta de cores no formato RGB

Com base nesta paleta, podemos definir os valores das seguintes cores bsicas:

Cor R G B Valor
Preto 0 0 0 0
Azul 0 0 255 16711680
Verde 0 255 0 65280
Ciano 0 255 255 16776960
Vermelho 255 0 0 255
Rosa 255 0 255 16711935
Amarelo 255 255 0 65535
Branco 255 255 255 16777215

Para atribuir as cores aos objetos visuais devem ser observados os atributos utilizados
para estes fins em cada objeto, como por exemplo:

MSDIALOG()

nClrPane Cor de fundo do painel
nClrText Cor da fonte das letras do painel

TSAY()

nClrPane Cor de fundo do painel
nClrText Cor da fonte das letras do painel

Funo RGB()

A linguagem ADVPL possui a funo RGB() a qual retorna o valor da cor a ser definido,
de acordo com a parametrizao de cada um dos elementos da paleta RGB.

RGB(nRed, nGreen, nBlue)

nRed Valor de 0-255 para o elemento vermelho da paleta RGB
nGreen Valor de 0-255 para o elemento verde da paleta RGB
nBlue Valor de 0-255 para o elemento azul da paleta RGB
Retorno Valor a ser definido para o atributo cor do componente

15. Aplicaes com a interface visual do ADVPL

A linguagem ADVPL possui interfaces visuais pr-definidas que auxiliam no
desenvolvimento de aplicaes mais completas, combinando estas interfaces com os
componentes visuais demonstrados anteriormente.

Didaticamente as interfaces visuais pr-definidas da linguagem ADVPL podem ser
divididas em trs grupos:

E Captura de informaes simples ou Multi-Gets;
E Captura de mltiplas informaes ou Multi-Lines;
E Barras de botes

2.31 Captura de informaes simples (Multi-Gets)

Em ADVPL, as telas de captura de informaes compostas por mltiplos campos
digitveis acompanhados de seus respectivos textos explicativos so comumente
chamados de Enchoices.

Um Enchoice pode ser facilmente entendida como diversos conjuntos de objetos TSay
e TGet alinhados de forma a visualizar ou capturar informaes, normalmente
vinculadas a arquivos de cadastros ou movimentaes simples.

Abaixo temos a visualizao de uma Enchoice para o arquivo padro do ERP Protheus
de Cadastro de Clientes (SA1):

Figura: Enchoice do Cadastro de Clientes do ERP Protheus

A linguagem ADVPL permite a implementao da Enchoice de duas formas similares:

E Funo Enchoice: Sintaxe tradicionalmente utilizada em ADVPL, a qual no
retorna um objeto para a aplicao chamadora;

E Classe MsMGet: Classe do objeto Enchoice, a qual permite a instanciao direta
de um objeto, tornando-o disponvel na aplicao chamadora.

A utilizao de um ou outro objeto depende unicamente da escolha do desenvolvedor
j que os parmetros para a funo Enchoice e para o mtodo New() da classe MsMGet
so os mesmos, lembrando que para manter a coerncia com uma aplicao escrita em
orientao a objetos dever ser utilizada a classe MsMGet().

2.31.1 Enchoice()

E Sintaxe: Enchoice( cAlias, nReg, nOpc, aCRA, cLetra, cTexto, aAcho, aPos,
aCpos, nModelo, nColMens, cMensagem, cTudoOk, oWnd, lF3,
lMemoria, lColumn, caTela, lNoFolder, lProperty)

E Retorno: Nil
E Parmetros:

cAlias Tabela cadastrada no Dicionrio de Tabelas (SX2) que
ser editada
nReg Parmetro no utilizado
nOpc Nmero da linha do aRotina que definir o tipo de
edio (Incluso, Alterao, Excluso, Visualizao)
aCRA Parmetro no utilizado
cLetra Parmetro no utilizado
cTexto Parmetro no utilizado
aAcho Vetor com nome dos campos que sero exibidos. Os
campos de usurio sempre sero exibidos se no existir
no parmetro um elemento com a expresso "NOUSER"
aPos Vetor com coordenadas para criao da enchoice no
formato {<top>, <left>, <bottom>, <right>}
aCpos Vetor com nome dos campos que podero ser editados
nModelo Se for diferente de 1 desabilita execuo de gatilhos
estrangeiros
nColMens Parmetro no utilizado
cMensagem Parmetro no utilizado
cTudoOk Expresso para validao da Enchoice
oWnd Objeto (janela, painel, etc.) onde a enchoice ser criada.
lF3 Indica se a enchoice esta sendo criada em uma consulta
F3 para utilizar variveis de memria
lMemoria Indica se a enchoice utilizar variveis de memria ou os
campos da tabela na edio
lColumn Indica se a apresentao dos campos ser em forma de
coluna
caTela Nome da varivel tipo "private" que a enchoice utilizar
no lugar da propriedade aTela
lNoFolder Indica se a enchoice no ir utilizar as Pastas de
Cadastro (SXA)
lProperty Indica se a enchoice no utilizar as variveis aTela e
aGets, somente suas propriedades com os mesmos
nomes

Exemplo: Utilizao da funo Enchoice()


/*/
+-------------------------------------------------------------------
------
| Funo | MBRWENCH | Autor | ARNALDO RAYMUNDO JR.|Data |
|
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao da funo
Enchoice()|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function MrbwEnch()

Private cCadastro := " Cadastro de Clientes"
Private aRotina := {{"Pesquisar" , "axPesqui" , 0, 1},;
{"Visualizar" , "U_ModEnc" , 0, 2}}

DbSelectArea("SA1")
DbSetOrder(1)

MBrowse(6,1,22,75,"SA1")

Return

User Function ModEnc(cAlias,nReg,nOpc)

Local aCpoEnch := {}
Local aAlter := {}

Local cAliasE := cAlias
Local aAlterEnch := {}
Local aPos := {000,000,400,600}
Local nModelo := 3
Local lF3 := .F.
Local lMemoria := .T.
Local lColumn := .F.
Local caTela := ""
Local lNoFolder := .F.
Local lProperty := .F.
Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0]
Private aGETS[0]

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)

While !Eof() .And. SX3->X3_ARQUIVO == cAliasE
If !(SX3->X3_CAMPO $ "A1_FILIAL") .And. cNivel >= SX3->X3_NIVEL
.And.;
X3Uso(SX3->X3_USADO)
AADD(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End

aAlterEnch := aClone(aCpoEnch)

DEFINE MSDIALOG oDlg TITLE cCadastro FROM 000,000 TO 400,600 PIXEL
RegToMemory("SA1", If(nOpc==3,.T.,.F.))

Enchoice(cAliasE, nReg, nOpc, /*aCRA*/, /*cLetra*/, /*cTexto*/,
;
aCpoEnch, aPos, aAlterEnch, nModelo, /*nColMens*/,;
/*cMensagem*/,/*cTudoOk*/, oDlg, lF3, lMemoria,
lColumn,;
caTela, lNoFolder, lProperty)


Return

2.31.2 MsMGet()

E Sintaxe: MsMGet():New( cAlias, nReg, nOpc, aCRA, cLetra, cTexto, aAcho,
aPos, aCpos, nModelo, nColMens, cMensagem, cTudoOk, oWnd,
lF3, lMemoria, lColumn, caTela, lNoFolder, lProperty)

E Retorno: oMsMGet objeto do tipo MsMGet()

E Parmetros:

cAlias Tabela cadastrada no Dicionrio de Tabelas (SX2) que
ser editada
nReg Parmetro no utilizado
nOpc Nmero da linha do aRotina que definir o tipo de
edio (Incluso, Alterao, Excluso, Visualizao)
aCRA Parmetro no utilizado
cLetra Parmetro no utilizado
cTexto Parmetro no utilizado
aAcho Vetor com nome dos campos que sero exibidos. Os
campos de usurio sempre sero exibidos se no existir
no parmetro um elemento com a expresso "NOUSER"
aPos Vetor com coordenadas para criao da enchoice no
formato {<top>, <left>, <bottom>, <right>}
aCpos Vetor com nome dos campos que podero ser editados
nModelo Se for diferente de 1 desabilita execuo de gatilhos
estrangeiros
nColMens Parmetro no utilizado
cMensagem Parmetro no utilizado
cTudoOk Expresso para validao da Enchoice
oWnd Objeto (janela, painel, etc.) onde a enchoice ser criada.
lF3 Indica se a enchoice esta sendo criada em uma consulta
F3 para utilizar variveis de memria
lMemoria Indica se a enchoice utilizar variveis de memria ou os
campos da tabela na edio
lColumn Indica se a apresentao dos campos ser em forma de
coluna
caTela Nome da varivel tipo "private" que a enchoice utilizar
no lugar da propriedade aTela
lNoFolder Indica se a enchoice no ir utilizar as Pastas de
Cadastro (SXA)
lProperty Indica se a enchoice no utilizar as variveis aTela e
aGets, somente suas propriedades com os mesmos
nomes

Exemplo: Utilizao do objeto MsMGet()


/*/
+-------------------------------------------------------------------
------
| Funo | MBRWMSGET | Autor | ARNALDO RAYMUNDO JR. |Data |
|
+-------------------------------------------------------------------
------
MsMget()|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function MrbwMsGet()

Private cCadastro := " Cadastro de Clientes"
{"Visualizar" , "U_ModEnc" , 0, 2}}

DbSelectArea("SA1")
DbSetOrder(1)

MBrowse(6,1,22,75,"SA1")

Return

User Function ModEnc(cAlias,nReg,nOpc)
Local aAlter := {}

Local aPos := {000,000,400,600}
Local nModelo := 3
Local lF3 := .F.
Local caTela := ""
Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0]
Private aGETS[0]

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)

.And. X3Uso(SX3->X3_USADO)
EndIf
DbSkip()
End


oDlg := MSDIALOG():New(000,000,400,600,cCadastro,,,,,,,,,.T.)

RegToMemory(cAliasE, If(nOpc==3,.T.,.F.))

oEnch := MsMGet():New(cAliasE, nReg, nOpc, /*aCRA*/,
/*cLetra*/,;
/*cTexto*/, aCpoEnch, aPos, aAlterEnch, nModelo,
/*nColMens*/,;
/*cMensagem*/, /*cTudoOk*/,oDlg,lF3,lMemoria,lColumn,
caTela,;
lNoFolder, lProperty)

oDlg:lCentered := .T.
oDlg:Activate()

Return

2.32 Captura de mltiplas informaes (Multi-Lines)

A linguagem ADVPL permite a utilizao de basicamente dois tipos de objetos do tipo
grid, ou como tambm so conhecidos: multi-line:

E Grids digitveis: permitem a visualizao e captura de informaes,
comumente utilizados em interfaces de cadastro e manuteno, tais como:

MSGETDB()
MSGETDADOS()
MSNEWGETDADOS()

E Grids no digitveis: permitem somente a visualizao de informaes,
comumente utilizados como browses do ERP Protheus, tais como:

TWBROWSE()
MAWNDBROWSE()
MBROWSE()

Neste tpico sero tratadas as grids digitveis disponveis na linguagem ADVPL para o
desenvolvimento de interfaces de cadastros e manuteno de informaes.

2.32.1 MsGetDB()

A classe de objetos visuais MsGetDB() permite a criao de um grid digitvel
com uma ou mais colunas, baseado em uma tabela temporria.

E Sintaxe: MsGetDB():New(nTop, nLeft, nBottom, nRight, nOpc, cLinhaOk,
cTudoOk, cIniCpos, lDelete, aAlter, nFreeze, lEmpty, uPar1, cTRB,
cFieldOk, lCondicional, lAppend, oWnd, lDisparos, uPar2,
cDelOk, cSuperDel)

E Retorno: oMsGetDB objeto do tipo MsGetDB()

E Parmetros:

nTop Distancia entre a MsGetDB e o extremidade superior do
objeto que a contm.
nLeft Distancia entre a MsGetDB e o extremidade esquerda do
objeto que a contm.
nBottom Distancia entre a MsGetDB e o extremidade inferior do
objeto que a contm.
nRight

Distancia entre a MsGetDB e o extremidade direita do
objeto que a contm.
nOpc Posio do elemento do vetor aRotina que a MsGetDB
usar como referncia.
cLinhaOk Funo executada para validar o contexto da linha atual
do aCols.
cTudoOk Funo executada para validar o contexto geral da
MsGetDB (todo aCols).
cIniCpos Nome dos campos do tipo caracter que utilizaro
incremento automtico. Este parmetro deve ser no
formato +<nome do primeiro campo>+<nome do
segundo campo>+....
lDelete Habilita a opo de excluir linhas do aCols. Valor padro
falso.
nFreeze Indica qual coluna no ficara congelada na exibio.
lEmpty Habilita validao da primeira coluna do aCols para esta
no poder estar vazia. Valor padro falso.
cFieldOk Funo executada na validao do campo.
cTRB Alias da tabela temporria.
lCondicional Reservado
lAppend Indica se a MsGetDB ira criar uma linha em branco
automaticamente quando for incluso.
cDelOk Funo executada para validar a excluso de uma linha
do aCols.
lDisparos Indica se ser utilizado o Dicionrio de Dados para
consulta padro, inicializao padro e gatilhos.
cSuperDel -Funo executada quando pressionada as teclas
<Ctrl>+<Delete>.
oWnd Objeto no qual a MsGetDB ser criada.
E
E Aparncia:

E Variveis private:

aRotina Vetor com as rotinas que sero executadas na MBrowse
e que definira o tipo de operao que esta sendo
executada (incluso, alterao, excluso, visualizao,
pesquisa, ...) no formato:
{cTitulo, cRotina, nOpo, nAcesso}, aonde:
nOpo segue o padro do ERP Protheus para:
1- Pesquisar
2- Visualizar
3- Incluir
4- Alterar
5- Excluir
aHeader Vetor com informaes das colunas no formato:

{cTitulo, cCampo, cPicture, nTamanho, nDecimais,;
cValidao, cReservado, cTipo, xReservado1,
xReservado2}

A tabela temporria utilizada pela MsGetDB dever ser
criada com base no aHeader mais um ltimo campo tipo
lgico que determina se a linha foi excluda.

lRefresh Varivel tipo lgica para uso reservado.


E Variveis pblicas:

nBrLin Indica qual a linha posicionada do aCols.

E Funes de validao:

cLinhaOk Funo de validao na mudana das linhas da grid. No
pode ser definida como Static Function.
cTudoOk Funo de validao da confirmao da operao com o
grid. No pode ser definida como Static Function.

E Mtodos adicionais:

ForceRefresh() Atualiza a MsGetDB com a tabela e posiciona na
primeira linha.

Exemplo: Utilizao do objeto MsGetDB()


/*/
+-------------------------------------------------------------------
------
| Funo | GETDBSA1 | Autor | MICROSIGA |Data |
|
+-------------------------------------------------------------------
------
MsGetDB()|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function GetDbSA1()

Local nI
Local oDlg
Local oGetDB
Local nUsado := 0
Local aStruct := {}

Private lRefresh := .T.
Private aCols := {}
Private aRotina := {{"Pesquisar", "AxPesqui", 0, 1},;
{"Visualizar", "AxVisual", 0, 2},;
{"Incluir", "AxInclui", 0, 3},;
{"Alterar", "AxAltera", 0, 4},;
{"Excluir", "AxDeleta", 0, 5}}

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek("SA1")


While !Eof() .and. SX3->X3_ARQUIVO == "SA1"
If X3Uso(SX3->X3_USADO) .and. cNivel >= SX3->X3_NIVEL
nUsado++
AADD(aHeader,{Trim(X3Titulo()),;
SX3->X3_CAMPO,;
SX3->X3_PICTURE,;
SX3->X3_TAMANHO,;
SX3->X3_DECIMAL,;
SX3->X3_VALID,;
"",;
SX3->X3_TIPO,;
"",;
"" })
AADD(aStruct,{SX3->X3_CAMPO,SX3->X3_TIPO,SX3->X3_TAMANHO,;
SX3->X3_DECIMAL})
EndIf
DbSkip()
End

AADD(aStruct,{"FLAG","L",1,0})

cCriaTrab := CriaTrab(aStruct,.T.)
DbUseArea(.T.,__LocalDriver,cCriaTrab,,.T.,.F.)

oDlg := MSDIALOG():New(000,000,300,400, MsGetDB
SA1,,,,,,,,,.T.)
oGetDB := MsGetDB():New(05,05,145,195,3,"U_LINHAOK", "U_TUDOOK",
"+A1_COD", ;
.T.,{"A1_NOME"},1,.F.,,cCriaTrab,"U_FIELDOK",,.T.,oDlg, .T.,
,"U_DELOK",;
"U_SUPERDEL")

oDlg:Activate()
DbSelectArea(cCriaTrab)
DbCloseArea()

Return

User Function LINHAOK()
ApMsgStop("LINHAOK")
Return .T.

User Function TUDOOK()
Return .T.

User Function DELOK()
ApMsgStop("DELOK")
Return .T.

User Function SUPERDEL()
ApMsgStop("SUPERDEL")
Return .T.

User Function FIELDOK()
ApMsgStop("FIELDOK")
Return .T.

2.32.2 MsGetDados()

A classe de objetos visuais MsGetDados() permite a criao de um grid digitvel com
uma ou mais colunas, baseado em um array.

E Sintaxe: MsGetDados():New( nTop, nLeft, nBottom, nRight, nOpc,
cLinhaOk, cTudoOk, cIniCpos, lDelete, aAlter, uPar1, lEmpty,
nMax, cFieldOk, cSuperDel, uPar2, cDelOk, oWnd)

E Retorno: oMsGetDados objeto do tipo MsGetDados()

E Parmetros:

nTop Distncia entre a MsGetDados e o extremidade superior
do objeto que a contm.
nLeft Distncia entre a MsGetDados e o extremidade esquerda
nBottom Distncia entre a MsGetDados e o extremidade inferior
nRight

Distncia entre a MsGetDados e o extremidade direita
nOpc Posio do elemento do vetor aRotina que a
MsGetDados usar como referencia.
cLinhaOk Funo executada para validar o contexto da linha atual
do aCols.
MsGetDados (todo aCols).
incremento automtico. Este parmetro deve ser no
formato +<nome do primeiro campo>+<nome do
segundo campo>+....
lDelete Habilita excluir linhas do aCols. Valor padro falso.
lEmpty Habilita validao da primeira coluna do aCols para esta
no poder estar vazia. Valor padro falso.
nMax Nmero mximo de linhas permitidas. Valor padro 99.
cFieldOk Funo executada na validao do campo.
cSuperDel Funo executada quando pressionada as teclas
<Ctrl>+<Delete>.
do aCols.
oWnd Objeto no qual a MsGetDados ser criada.


E Aparncia:

E Variveis private:

aRotina
Vetor com as rotinas que sero executadas na MBrowse
6- Pesquisar
7- Visualizar
8- Incluir
9- Alterar
10- Excluir

xReservado2}



E Variveis pblicas:

N Indica qual a linha posicionada do aCols.

E Funes de validao:



ForceRefresh() Atualiza a MsGetDados com a tabela e posiciona na
primeira linha.
Hide() Oculta a MsGetDados.
Show() Mostra a MsGetDados.

Exemplo: Utilizao do objeto MsGetDados()


/*/
+-------------------------------------------------------------------
------
| Funo | GETDADOSA1 | Autor | MICROSIGA |Data |
|
+-------------------------------------------------------------------
------
MSGETADOS()|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function GetDadoSA1()

Local nI
Local oDlg
Local oGetDados
Local nUsado := 0
Private lRefresh := .T.
Private aCols := {}

Private aRotina := {{"Pesquisar", "AxPesqui", 0, 1},;
{"Visualizar", "AxVisual", 0, 2},;
{"Incluir", "AxInclui", 0, 3},;
{"Alterar", "AxAltera", 0, 4},;
{"Excluir", "AxDeleta", 0, 5}}

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek("SA1")

While !Eof() .and. SX3->X3_ARQUIVO == "SA1"
If X3Uso(SX3->X3_USADO) .and. cNivel >= SX3->X3_NIVEL
nUsado++
AADD(aHeader,{Trim(X3Titulo()),;
SX3->X3_CAMPO,;
SX3->X3_PICTURE,;
SX3->X3_TAMANHO,;
SX3->X3_DECIMAL,;
SX3->X3_VALID,;
"",;
SX3->X3_TIPO,;
"",;
"" })
EndIf
DbSkip()
End


For nI := 1 To nUsado
aCols[1][nI] := CriaVar(aHeader[nI][2])
Next

aCols[1][nUsado+1] := .F.

oDlg := MSDIALOG():New(000,000,300,400, MsGetDados
SA1,,,,,,,,,.T.)

oGetDados := MsGetDados():New(05, 05, 145, 195, 4, "U_LINHAOK",
"U_TUDOOK",;
"+A1_COD", .T., {"A1_NOME"}, , .F., 200, "U_FIELDOK",
"U_SUPERDEL",,;
"U_DELOK", oDlg)

oDlg:Activate()

Return

User Function LINHAOK()
Return .T.

User Function TUDOOK()
Return .T.

User Function DELOK()
ApMsgStop("DELOK")
Return .T.

User Function SUPERDEL()
ApMsgStop("SUPERDEL")
Return .T.

User Function FIELDOK()
ApMsgStop("FIELDOK")
Return .T.

2.32.3 MsNewGetDados()

A classe de objetos visuais MsNewGetDados() permite a criao de um grid digitvel
com uma ou mais colunas, baseado em um array.

E Sintaxe: MsNewGetDados():New(nSuperior, nEsquerda ,nInferior, nDireita,
nOpc, cLinOk, cTudoOk, cIniCpos, aAlterGDa, nFreeze, nMax,
cFieldOk, cSuperDel, cDelOk, oDLG, aHeader, aCols)

E Retorno: oMsGetDados objeto do tipo MsNewGetDados()

E Parmetros:

nSuperior Distancia entre a MsNewGetDados e o extremidade
superior do objeto que a contem
nEsquerda Distancia entre a MsNewGetDados e o extremidade
esquerda do objeto que a contem
nInferior Distancia entre a MsNewGetDados e o extremidade
inferior do objeto que a contem
nDireita Distancia entre a MsNewGetDados e o extremidade
direita do objeto que a contem
nOpc Operao em execuo: 2- Visualizar, 3- Incluir, 4- Alterar,
5- Excluir
cLinOk Funo executada para validar o contexto da linha atual
do aCols
MsNewGetDados (todo aCols)
incremento automtico.
aAlterGDa Campos alterveis da GetDados
nFreeze Campos estticos na GetDados, partindo sempre da
posio inicial da getdados aonde:
1- Primeiro campo congelado
2- Primeiro e segundo campos congelados...
nMax Nmero mximo de linhas permitidas. Valor padro 99
cFieldOk Funo executada na validao do campo
cSuperDel Funo executada quando pressionada as teclas
<Ctrl>+<Delete>
do aCols
oDLG Objeto no qual a MsNewGetDados ser criada
aHeader Array a ser tratado internamente na MsNewGetDados
como aHeader
aCols Array a ser tratado internamente na MsNewGetDados
como aCols

E Aparncia:



E Variveis private:

aRotina Vetor com as rotinas que sero executadas na MBrowse

1- Pesquisar
2- Visualizar
3- Incluir
4- Alterar
5- Excluir

xReservado2}



E Variveis pblicas:

N Indica qual a linha posicionada do aCols.

E Funes de validao:



ForceRefresh() Atualiza a MsNewGetDados com a tabela e posiciona na
primeira linha.
Hide() Oculta a MsNewGetDados.
Show() Mostra a MsNewGetDados.

Exemplo: Utilizao dos objetos MsNewGetDados() e MsMGet()


/*/
+-------------------------------------------------------------------
------
| Funo | MBRWGETD | Autor | ARNALDO RAYMUNDO JR. |Data |
|
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao dos objetos|
| | MsNewGetDados() e MsMGet() combinados
|
+-------------------------------------------------------------------
------
+-------------------------------------------------------------------
------
/*/

User Function MrbwGetD()

{"Visualizar" , "U_ModGtd" , 0, 2},;
{"Incluir" , "U_ModGtd" , 0, 3}}

DbSelectArea("SC5")
DbSetOrder(1)

MBrowse(6,1,22,75,"SC5")

Return

User Function ModGtd(cAlias,nReg,nOpc)

Local nX := 0
Local nUsado := 0
Local aButtons := {}
Local aPos := {000,000,080,400}
Local nModelo := 3
Local lF3 := .F.
Local caTela := ""
Local aCpoGDa := {}
Local cAliasGD := "SC6"
Local nSuperior := 081
Local nEsquerda := 000
Local nInferior := 250
Local nDireita := 400
Local cLinOk := "AllwaysTrue"
Local cTudoOk := "AllwaysTrue"
Local cIniCpos := "C6_ITEM"
Local nFreeze := 000
Local nMax := 999
Local cFieldOk := "AllwaysTrue"
Local cSuperDel := ""
Local cDelOk := "AllwaysFalse"
Local aHeader := {}
Local aCols := {}
Local aAlterGDa := {}

Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0]
Private aGETS[0]

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)

If !(SX3->X3_CAMPO $ "C5_FILIAL") .And. cNivel >= SX3->X3_NIVEL
.And.;
EndIf
DbSkip()
End


DbSelectArea("SX3")
DbSetOrder(1)
MsSeek(cAliasGD)

While !Eof() .And. SX3->X3_ARQUIVO == cAliasGD
If !(AllTrim(SX3->X3_CAMPO) $ "C6_FILIAL") .And.;
cNivel >= SX3->X3_NIVEL .And. X3Uso(SX3->X3_USADO)
AADD(aCpoGDa,SX3->X3_CAMPO)
EndIf
DbSkip()
End

aAlterGDa := aClone(aCpoGDa)

nUsado:=0
dbSelectArea("SX3")
dbSeek("SC6")
aHeader:={}
nUsado:=nUsado+1
AADD(aHeader,{ TRIM(x3_titulo), x3_campo, x3_picture,x3_tamanho,;
x3_decimal,"AllwaysTrue()",x3_usado, x3_tipo, x3_arquivo, x3_context
} )
Endif
dbSkip()
End

If nOpc==3 // Incluir
For nX:=1 to nUsado
IF aHeader[nX,2] == "C6_ITEM"
aCols[1,nX]:= "0001"
ELSE
ENDIF
Next
Else
aCols:={}
dbSelectArea("SC6")
dbSetOrder(1)
For nX:=1 to nUsado

Next
dbSkip()
End
Endif

oDlg := MSDIALOG():New(000,000,400,600, cCadastro,,,,,,,,,.T.)
RegToMemory("SC5", If(nOpc==3,.T.,.F.))

oEnch :=
MsMGet():New(cAliasE,nReg,nOpc,/*aCRA*/,/*cLetra*/,/*cTexto*/,;
aCpoEnch,aPos,aAlterEnch, nModelo, /*nColMens*/,
/*cMensagem*/,;
/*cTudoOk*/, oDlg,lF3, lMemoria,lColumn,caTela,lNoFolder,;
lProperty)

oGetD:= MsNewGetDados():New(nSuperior, nEsquerda, nInferior,
nDireita,;
nOpc,cLinOk,cTudoOk, cIniCpos, aAlterGDa, nFreeze,
nMax,cFieldOk,;
cSuperDel,cDelOk, oDLG, aHeader, aCols)

oDlg:bInit := {|| EnchoiceBar(oDlg,
{||oDlg:End()},{||oDlg:End()},,aButtons)}
oDlg:Activate()
Return

2.32.3.1 Definindo cores personalizadas para o objeto MsNewGetDados()

Conforme visto no tpico sobre definio das propriedades de cores para os
componentes visuais, cada objeto possui caractersticas que devem ser respeitadas
para correta utilizao deste recurso.

E Atributos adicionais:

lUseDefaultColors Atributo que dever ser definido como .F. para que as
alteraes nas cores sejam permitidas.


SetBlkBackColor Mtodo que define a cor que ser utilizada para cada
linha do grid. No necessrio utilizar o mtodo
Refresh() aps a definio da cor por este mtodo.


E Aparncia:

Exemplo: Definindo cores personalizadas para o objeto MsNewGetDados()


/*/
+-------------------------------------------------------------------
------
| Funo | MRBWGTCL | Autor | ARNALDO RAYMUNDO JR. |Data | |
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao dos objetos
|
| | MsNewGetDados() e MsMGet() combinados e tratamento de
cores|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function MrbwGtCl()

{"Visualizar" , "U_ModGtd" , 0, 2},;
{"Incluir" , "U_ModGtd" , 0, 3}}

DbSelectArea("SC5")
DbSetOrder(1)

MBrowse(6,1,22,75,"SC5")

Return

User Function ModGtd(cAlias,nReg,nOpc)

Local nX := 0
Local nUsado := 0

Local aPos := {000,000,080,400}
Local nModelo := 3
Local lF3 := .F.
Local caTela := ""
Local aCpoGDa := {}
Local cAliasGD := "SC6"
Local nSuperior := 081
Local nEsquerda := 000
Local nInferior := 250
Local nDireita := 400
Local cLinOk := "AllwaysTrue"
Local cTudoOk := "AllwaysTrue"
Local cIniCpos := "C6_ITEM"
Local nFreeze := 000
Local nMax := 999
Local cFieldOk := "AllwaysTrue"
Local cSuperDel := ""
Local cDelOk := "AllwaysFalse"
Local aHeader := {}
Local aCols := {}
Local aAlterGDa := {}

Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0]
Private aGETS[0]

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)

If !(SX3->X3_CAMPO $ "C5_FILIAL") .And. cNivel >= SX3->X3_NIVEL
.And.;
EndIf
DbSkip()
End


DbSelectArea("SX3")
DbSetOrder(1)
MsSeek(cAliasGD)

While !Eof() .And. SX3->X3_ARQUIVO == cAliasGD
If !(AllTrim(SX3->X3_CAMPO) $ "C6_FILIAL") .And. cNivel >=
SX3->X3_NIVEL .And. X3Uso(SX3->X3_USADO)
AADD(aCpoGDa,SX3->X3_CAMPO)
EndIf
DbSkip()
End

aAlterGDa := aClone(aCpoGDa)

nUsado:=0
dbSelectArea("SX3")
dbSeek("SC6")
aHeader:={}
nUsado:=nUsado+1
AADD(aHeader,{ TRIM(x3_titulo), x3_campo, x3_picture,;
x3_tamanho, x3_decimal,"AllwaysTrue()",;
x3_usado, x3_tipo, x3_arquivo, x3_context } )
Endif
dbSkip()
End

If nOpc==3 // Incluir
For nX:=1 to nUsado

IF aHeader[nX,2] == "C6_ITEM"
aCols[1,nX]:= "0001"
ELSE
ENDIF

Next
Else
aCols:={}
dbSelectArea("SC6")
dbSetOrder(1)
For nX:=1 to nUsado

Next
dbSkip()
End
Endif

oDlg := MSDIALOG():New(000,000,400,600, cCadastro,,,,,,,,,.T.)

RegToMemory("SC5", If(nOpc==3,.T.,.F.))

oEnch := MsMGet():New(cAliasE,nReg,nOpc,/*aCRA*/,/*cLetra*/,
/*cTexto*/,;
aCpoEnch,aPos, aAlterEnch, nModelo, /*nColMens*/,
/*cMensagem*/,;
cTudoOk,oDlg,lF3,
lMemoria,lColumn,caTela,lNoFolder,lProperty)

oGetD:=
MsNewGetDados():New(nSuperior,nEsquerda,nInferior,nDireita, nOpc,;
cLinOk,cTudoOk,cIniCpos,aAlterGDa,nFreeze,nMax,cFieldOk,
cSuperDel,;
cDelOk, oDLG, aHeader, aCols)

// Tratamento para definio de cores especficas,
// logo aps a declarao da MsNewGetDados

oGetD:oBrowse:lUseDefaultColors := .F.
oGetD:oBrowse:SetBlkBackColor({||
GETDCLR(oGetD:aCols,oGetD:nAt,aHeader)})

oDlg:bInit := {|| EnchoiceBar(oDlg, {||oDlg:End()},
{||oDlg:End()},,aButtons)}
oDlg:Activate()

Return

// Funo para tratamento das regras de cores para a grid da
MsNewGetDados

Static Function GETDCLR(aLinha,nLinha,aHeader)

Local nCor2 := 16776960 // Ciano - RGB(0,255,255)
Local nCor3 := 16777215 // Branco - RGB(255,255,255)
Local nPosProd := aScan(aHeader,{|x| Alltrim(x[2]) ==
"C6_PRODUTO"})
Local nUsado := Len(aHeader)+1
Local nRet := nCor3

If !Empty(aLinha[nLinha][nPosProd]) .AND. aLinha[nLinha][nUsado]
nRet := nCor2
ElseIf !Empty(aLinha[nLinha][nPosProd]) .AND.
!aLinha[nLinha][nUsado]
nRet := nCor3
Endif

Return nRet

2.33 Barras de botes

A linguagem ADVPL permite a implementao de barras de botes utilizando funes
pr-definidas desenvolvidas com o objetivo de facilitar sua utilizao, ou atravs da
utilizao direta dos componentes visuais disponveis. Dentre os recursos da linguagem
que podem ser utilizados com esta finalidade sero abordados:

E Funo EnchoiceBar: Sintaxe tradicionalmente utilizada em ADVPL, a qual no
retorna um objeto para a aplicao chamadora;

E Classe TBar: Classe do objeto TBar(), a qual permite a instanciao direta de um
objeto do tipo barra de botes superior, tornando-o disponvel na aplicao
chamadora.

E Classe ButtonBar: Classe do objeto ButtonBar(), a qual permite a instanciao
direta de um objeto barra de botes genrico, o qual pode ser utilizado em
qualquer posio da tela, tornando-o disponvel na aplicao chamadora.

2.33.1 EnchoiceBar()

Funo que cria uma barra de botes no formato padro utilizado pelas interfaces de
cadastro da aplicao Protheus.

Esta barra possui os botes padres para confirmar ou cancelar a interface e ainda
permite a adio de botes adicionais com a utilizao do parmetro aButtons.
E Sintaxe:

EnchoiceBar( oDlg, bOk, bCancel, lMsgDel, aButtons, nRecno, cAlias)

E Parmetros:

oDlg Dialog onde ir criar a barra de botes
bOk Bloco de cdigo a ser executado no boto Ok
bCancel Bloco de cdigo a ser executado no boto Cancelar
lMsgDel Exibe dialog para confirmar a excluso
aButtons
Array contendo botes adicionais.
aArray[n][1] -> Imagem do boto
aArray[n][2] -> bloco de cdigo contendo a ao do
boto
aArray[n][3] -> ttulo do boto
nRecno Registro a ser posicionado aps a execuo do boto Ok.
cAlias
Alias do registro a ser posicionado aps a execuo do
boto Ok. Se o parmetro nRecno for informado, o cAlias
passa ser obrigatrio.

E Aparncia:

Exemplo: Utilizao da funo EnchoiceBar()


/*/
+-------------------------------------------------------------------
------
| Funo | DENCHBAR | Autor | ARNALDO RAYMUNDO JR. |Data |
|
+-------------------------------------------------------------------
------
| Descrio | Programa que demonstra a utilizao da funo
|
| | EnchoiceBar()
|
+-------------------------------------------------------------------
------
+-------------------------------------------------------------------
------
/*/

User Function DEnchBar()
Local oDlg, oBtn

DEFINE MSDIALOG oDlg TITLE "Teste EnchoiceBar" FROM 000,000 TO
400,600 PIXEL OF;
oMainWnd

AADD( aButtons, {"HISTORIC", {|| TestHist()}, "Histrico...",;
"Histrico",{|| .T.}} )

@ -15,-15 BUTTON oBtn PROMPT "..." SIZE 1,1 PIXEL OF oDlg

ACTIVATE MSDIALOG oDlg ;
ON INIT
(EnchoiceBar(oDlg,{||lOk:=.T.,oDlg:End()},{||oDlg:End()},,@aButtons)
)

Return

2.33.2 TBar()

Classe de objetos visuais que permite a implementao de um componente do tipo
barra de botes para a parte superior de uma janela previamente definida.

E Sintaxe: New(oWnd, nBtnWidth, nBtnHeight, l3D, cMode, oCursor,
cResource, lNoAutoAdjust)

E Retorno: oTBar objeto do tipo TBar()

E Parmetros:

oWnd
Objeto, opcional. Janela ou controle onde o boto
dever ser criado.
nBtnWidth Numrico, opcional. Largura do boto contido na barra
nBtnHeight Numrico, opcional. Altura do boto contido na barra
l3D Lgico, opcional. Define tipo da barra
cMode No utilizado.
oCursor
Objeto, opcional. Define Cursor ao posicionar o mouse
sobre a barra.
cResource
Caracter, opcional. Imagem do recurso a ser inserido
como fundo da barra.
lNoAutoAdjust Lgico.

E Aparncia:

Exemplo: Utilizao da funo EnchoiceBar()

#include 'protheus.ch'

/*/
+-------------------------------------------------------------------
------
| Funo | TSTBAR | Autor | MICROSIGA |Data |
|
+-------------------------------------------------------------------
------
TBar()|
+-------------------------------------------------------------------
------
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
------
/*/

User Function TstTBar()
Local oDlg

oDlg := MSDIALOG():New(000,000,305,505, 'Exemplo -
TBAR',,,,,,,,,.T.)


oTBar := TBar():New( oDlg,25,32,.T.,,,,.F. )

oTBtnBmp2_1 := TBtnBmp2():New( 00, 00, 35, 25, 'copyuser' ,,,,;
{||Alert('TBtnBmp2_1')}, oTBar,'msGetEx',,.F.,.F. )

oTBtnBmp2_2 := TBtnBmp2():New( 00, 00, 35, 25, 'critica' ,,,,;
{||},oTBar,'Critica',,.F.,.F. )

oTBtnBmp2_3 := TBtnBmp2():New( 00, 00, 35, 25, 'bmpcpo' ,,,,;
{||},oTBar,'PCO',,.F.,.F. )

oTBtnBmp2_4 := TBtnBmp2():New( 00, 00, 35, 25, 'preco' ,,,,;
{||},oTBar,'Preo' ,,.F.,.F. )

oDlg:Activate()

Return

2.33.3 ButtonBar

A sintaxe ButtonBar a forma clssica utilizada na linguagem ADVPL para
implementar um objeto da classe TBar(), o qual possui as caractersticas mencionadas
no tpico anterior.

E Sintaxe:

DEFINE BUTTONBAR oBar SIZE nWidth, nHeight 3D MODE OF oDlg
CURSOR

E Retorno: ().

E Parmetros:

oBar Objeto do tipo TBar() que ser criado com a utilizao
da sintaxe ButtonBar().
nWidth Numrico, opcional. Largura do boto contido na barra.
nHeight Numrico, opcional. Altura do boto contido na barra.
3D Se definido habilita a visualizao em 3D da barra de
botes.
oDlg Objeto, opcional. Janela ou controle onde o boto
dever ser criado.
MODE Define a forma de orientao do objeto ButtonBar
utilizando os seguintes termos pr-definidos:
TOP, BOTTOM, FLOAT

CURSOR Objeto, opcional. Define Cursor ao posicionar o mouse
sobre a barra.

A sintaxe ButtonBar requer a adio dos botes como recursos adicionais da barra
previamente definida utilizando a sintaxe abaixo:

E Botes: BUTTON RESOURCE

E Sintaxe adicional:

DEFINE BUTTON RESOURCE cBitMap OF oBar ACTION cAcao
TOOLTIP cTexto

E Parmetros:

cBitMap Nome da imagem disponvel na aplicao.
oBar Objeto do tipo TBar() no qual o boto ser adicionado.
cAcao Funo ou lista de expresses que determina a ao que
ser realizada pelo boto.
cTexto Texto no estilo tooltip text que ser exibido quando o
cursor do mouse for posicionado sobre o boto na barra
de ferramentas.

E Aparncia:


Exemplo: Utilizao da sintaxe ButtonBar

#include 'protheus.ch'

/*/
+-------------------------------------------------------------------
----
| Funo | TstBBar | Autor | MICROSIGA |Data |
|
+-------------------------------------------------------------------
----
TBar()|
+-------------------------------------------------------------------
----
| Uso | Curso ADVPL
|
+-------------------------------------------------------------------
----
/*/

User Function TstBBar()

Local oDlg
Local oBtn1
Local oBtn2

oDlg := MSDIALOG():New(000,000,305,505, 'Exemplo -
BUTTONBAR',,,,,,,,,.T.)

DEFINE BUTTONBAR oBar SIZE 25,25 3D TOP OF oDlg

DEFINE BUTTON RESOURCE "S4WB005N" OF oBar ACTION NaoDisp() TOOLTIP
"Recortar"
"Copiar"
"Colar"
DEFINE BUTTON oBtn1 RESOURCE "S4WB008N" OF oBar GROUP;
ACTION Calculadora() TOOLTIP "Calculadora"

oBtn1:cTitle:="Calc"
DEFINE BUTTON RESOURCE "S4WB009N" OF oBar ACTION Agenda() TOOLTIP
"Agenda"
DEFINE BUTTON RESOURCE "S4WB010N" OF oBar ACTION OurSpool() TOOLTIP
"Spool"
DEFINE BUTTON RESOURCE "S4WB016N" OF oBar GROUP;
ACTION HelProg() TOOLTIP "Ajuda"

DEFINE BUTTON oBtn2 RESOURCE "PARAMETROS" OF oBar GROUP;
ACTION Sx1C020() TOOLTIP "Parmetros"

oBtn2:cTitle:="Param."

DEFINE BUTTON oBtOk RESOURCE "FINAL" OF oBar GROUP;
ACTION oDlg:End()TOOLTIP "Sair"

oBar:bRClicked := {|| AllwaysTrue()}
oDlg:Activate()

Return

2.33.4 Imagens pr-definidas para as barras de botes

Conforme mencionado nos tpicos anteriores, os botes visuais do tipo barra de
botes permitem a definio de itens com aes e imagens vinculadas.

Dentre os objetos e funes mencionados, foi citada a EnchoiceBar(), a qual permite a
adio de botes adicionais atravs do parmetro aButton, sendo que os itens deste
array devem possuir o seguinte formato:

E Sintaxe: AADD(aButtons,{cBitMap, bAcao, cTexto})

E Estrutura:

cBitMap
Nome da imagem pr-definida existente na aplicao
ERP que ser vinculada ao boto.
bAcao
Bloco de cdigo que define a ao que ser executada
com a utilizao do boto.
cTexto
Texto no estilo tooltip text que ser exibido quando o
cursor do mouse for posicionado sobre o boto na barra
de ferramentas.

E Alguns BitMaps disponveis:

DESTINOS

DISCAGEM

EDIT

EDITABLE

EXCLUIR

FORM

GRAF2D

GRAF3D

LINE

NOTE

OBJETIVO

OK

PENDENTE

PRECO

PRODUTO

S4SB014N

S4WB001N

S4WB005N

S4WB006N

S4WB007N

S4WB008N

S4WB009N

S4WB010N

S4WB011N

S4WB013N

S4WB014A

S4WB016N

SIMULACA

VENDEDOR

USER

E Exemplo:

AADD(aButtons,{"USER",{||AllwaysTrue()},"Usurio"})

APNDICE

BOAS PRTICAS DE PROGRAMAO

16. Arredondamento
Algumas operaes numricas podem causar diferenas de arredondamento. Isso
ocorre devido a diferenas no armazenamento de variveis numricas nos diversos
processadores, diferena esta, inclusive, presente no ADVPL, mesmo antes do
surgimento do Protheus.

Para evitar esses problemas de arredondamento, deve ser utilizada a funo Round(),
principalmente antes de realizar uma comparao e antes de se utilizar a funo Int().

Desse modo, assegura-se que o resultado ser correto independentemente do
processador ou plataforma.

Exemplo 01:

If (Valor/30) == 50 // pode ser falso ou invlido
If Round(Valor/30, 0) == 50 // correto

Exemplo 02:

M->EE8_QTDEM1 := Int(M->EE8_SLDINI/M->EE8_QE) // pode ser falso ou
invlido
M->EE8_QTDEM1 := Int(Round(M->EE8_SLDINI/M->EE8_QE,10)) // correto

17. Utilizao de Identao
obrigatria a utilizao da identao, pois torna o cdigo muito mais legvel. Veja os
exemplos abaixo:

While !SB1->(Eof())
If mv_par01 == SB1->B1_COD
dbSkip()
Loop
Endif
Do Case
Case SB1->B1_LOCAL == 01 .OR. SB1->B1_LOCAL == 02
TrataLocal(SB1->B1_COD, SB1->B1_LOCAL)
Case SB1->B1_LOCAL == 03
TrataDefeito(SB1->B1_COD)
OtherWise
TrataCompra(SB1->B1_COD, SB1->B1_LOCAL)
EndCase
dbSkip()
EndDo

A utilizao da identao seguindo as estruturas de controle de fluxo (while, IF, caso
etc.) torna a compreenso do cdigo muito mais fcil:

While !SB1->(Eof())

If mv_par01 == SB1->B1_COD
dbSkip()
Loop
Endif

Do Case
Case SB1->B1_LOCAL == 01 .OR. SB1->B1_LOCAL == 02
TrataLocal(SB1->B1_COD, SB1->B1_LOCAL)

Case SB1->B1_LOCAL == 03
TrataDefeito(SB1->B1_COD)

OtherWise
TrataCompra(SB1->B1_COD, SB1->B1_LOCAL)
EndCase
dbSkip()

EndDo


Para identar o cdigo utilize a tecla <TAB> e na ferramenta DEV-Studio, a qual pode
ser configurada atravs da opo Preferncias:

18. Capitulao de Palavras-Chave

Uma conveno amplamente utilizada a de capitular as palavras chaves, funes,
variveis e campos utilizando uma combinao de caracteres em maisculo e
minsculo, visando facilitar a leitura do cdigo fonte. O cdigo a seguir:

Local ncnt while ( ncnt++ < 10 ) ntotal += ncnt * 2 enddo

Ficaria melhor com as palavras chaves e variveis capituladas:

Local nCnt While ( nCnt++ < 10 ) nTotal += nCnt * 2 EndDo

Para funes de manipulao de dados que comecem por db, a
capitulao s ser efetuada aps o db:

E dbSeek()
E dbSelectArea()

2.34 Palavras em maisculo

A regra utilizar caracteres em maisculo para:

E Constantes:

#define NUMLINES 60 #define NUMPAGES 1000

E Variveis de memria:

M-> CT2_CRCONV M->CT2_MCONVER := CriaVar("CT2_CONVER")

E Campos:

SC6->C6_NUMPED

E Querys:

SELECT * FROM...

19. Utilizao da Notao Hngara
A notao hngara consiste em adicionar os prefixos aos nomes de variveis, de modo
a facilmente se identificar seu tipo. Isto facilita na criao de cdigos-fonte extensos,
pois usando a Notao Hngara, voc no precisa ficar o tempo todo voltando
definio de uma varivel para se lembrar qual o tipo de dados que deve ser
colocado nela. Variveis devem ter um prefixo de Notao Hngara em minsculas,
seguido de um nome que identifique a funo da varivel, sendo que a inicial de cada
palavra deve ser maiscula.
obrigatria a utilizao desta notao para nomear variveis.
Notao Tipo de dado Exemplo
a Array aValores
b Bloco de cdigo bSeek
c Caracter cNome
d Data dDataBase
l Lgico lContinua
n Numrico nValor
o Objeto oMainWindow
x Indefinido xConteudo

20. Tcnicas de programao eficiente
Para o desenvolvimento de sistemas e a programao de rotinas, sempre esperado
que qualquer cdigo escrito seja:

Q Funcionalmente correto
Q Eficiente
Q Legvel
Q Reutilizvel
Q Extensvel
Q Portvel

Aps anos de experincia na utilizao de linguagens padro xBase e do
desenvolvimento da linguagem ADVPL, algumas tcnicas para uma programao
otimizada e eficiente foram reconhecidas. A utilizao das tcnicas a seguir, visa buscar
o mximo aproveitamento dos recursos da linguagem com o objetivo de criar
programas com estas caractersticas.

Criao de funes segundo a necessidade

Observe o cdigo de exemplo:

User Function GetAnswer(lDefault)
Local lOk
lOk := GetOk(lDefault)
If lOk
Return .T.
Else
Return .F.
Endif
Return nil

Utilizando-se apenas o critrio "a funo funciona corretamente?", a funo GetAnswer
perfeita. Recebe um parmetro lgico com a resposta padro e retorna um valor
lgico dependente da opo escolhida pelo usurio em uma funo de dilogo
"sim/no" designada para isso. Pode entretanto ser melhorada, particularmente se
eficincia for considerada como um critrio para um cdigo melhor. Eficincia
tipicamente envolve a utilizao de poucos recursos de mquina, poucos chamadas de
funes ou tornar mais rpido um processo.

Segundo esse raciocnio, poderia se produzir o seguinte cdigo:

Return If( GetOk(lDefault), .T., .F.)

O cdigo acima ainda pode ser aprimorado conforme abaixo:

Return GetOk(lDefault)

Com a otimizao do cdigo da funo GetAnswer(), pode facilmente verificar que a
mesma no realiza nada adicional chamada de GetOk(), podendo ser substituda por
uma chamada direta desta, continuando a funcionar corretamente.

Codificao auto-documentvel

Nenhum comentrio substitui um cdigo claramente escrito, e este no um acidente.
Considere o exemplo:

cVar := " " // 11 espaos

O tamanho da varivel cVar no evidente por si s e no facilmente verificado. Estes
mesmos 10 espaos estariam mais bvios e ainda assim garantidos se a instruo fosse
escrita como:

cVar := Space(11)

O mesmo princpio pode ser aplicado para qualquer string longa de caracteres
repetidos. A funo Replicate pode ser utilizada como a seguir:

cVar := Replicate( "*", 80 )

Este tipo de programao deixa o cdigo fcil de digitar, fcil de ler e mais flexvel.

Utilizao de solues simples

Simplicidade na criao de instrues torna a programao e at mesmo a execuo
mais rpida. Considere a linha de cdigo:

If nVar > 0 .Or. nVar < 0

Se o valor da varivel nVar for igual a zero (0) no momento da execuo desta linha de
cdigo, ambas as comparaes separadas pelo operador lgico .Or. sero efetuadas:
Aps ser avaliada, a primeira comparao ir falhar. A segunda comparao ser ento
avaliada e falhar tambm. Como resultado, o cdigo existente dentro da estrutura de
fluxo If no ser executado. Tal cdigo somente ser executado quando o valor desta
varivel for maior OU menor do que zero. Ou seja, sempre que for DIFERENTE de zero,
o que torna a linha a seguir mais eficiente:

If nVar != 0


Este tipo de alterao torna o cdigo mais legvel e o processamento mais rpido,
evitando a avaliao de instrues desnecessariamente.

Existem outras situaes onde a simplificao pode ser utilizada. A expresso de
avaliao a seguir:

If cVar == "A" .Or. cVar == "B" .Or cVar == "C" .Or. cVar == "D"

Pode ser substitudo pelo operador de conteno:

If cVar $ "ABCD"

Opo por flexibilidade

A melhor soluo aquela que envolve o problema imediato e previne problemas no
futuro. Considere o exemplo:

@nRow,nCol PSAY cVar Picture "!!!!!!!!!!!!!!!!!!!!"

Exceto contando-se os caracteres, no existe maneira de saber se o nmero de
caracteres de exclamao o esperado. Enquanto isto um problema, existem algo
mais grave. A expresso de picture esttica. Se no futuro for necessrio ajustar o
tamanho da varivel cVar, ser necessrio localizar todos os lugares no cdigo onde
esta mscara de picture est sendo utilizada para ajuste manual.

Existe uma opo de soluo de auto-ajuste disponvel que fcil de digitar e tem a
garantia de executar a tarefa igualmente (tornar todos os caracteres maisculos):

@nRow,nCol PSAY cVar Picture "@!"

Opo da praticidade ao drama

Se a soluo parece complexa, provavelmente porque o caminho escolhido est
levando a isso. Deve-se sempre se perguntar porque algum desenvolveria uma
linguagem que requisite tantos comandos complicados para fazer algo simples. Na
grande maioria dos casos, existe uma soluo mais simples. O exemplo abaixo deixa
isso bem claro:

@ 10,25 Say Substr(cCep,1,5) + "-" + Substr(cCep,6,3) Picture
"!!!!!!!!!"

Este cdigo pode ser escrito de uma forma muito mais simples, conforme demonstrado
abaixo:

@ 10,25 Say cCep Picture "@R 99999-999"

Utilizao de operadores de incremento/decremento

Utilizados devidamente, os operadores de incremento e decremento tornam o cdigo
mais fcil de ler e possivelmente um pouco mais rpidos. Ao contrrio de escrever
adies simples como:

nVar := nVar + 1
nVar := nVar -1

Pode-se escrev-las assim:

++nVar
--nVar

Deve-se apenas tomar cuidado com a precedncia destes operadores, pois o "++" ou o
"--" podem aparecer antes ou depois de uma varivel, e em alguns casos quando a
varivel for utilizada dentro de uma expresso, a prefixao ou sufixao destes
operadores afetar o resultado. Para maiores detalhes, consulte a documentao de
operadores da linguagem ADVPL.

Evitar passos desnecessrios

Existe uma diferena entre um bom hbito e perda de tempo. Algumas vezes estes
conceitos podem estar muito prximos, mas um modo de diferenci-los balancear os
benefcios de realizar alguma ao contra o problema que resultaria se no fosse
executada. Observe o exemplo:

Local nCnt := 0
For nCnt := 1 To 1
<cdigo>
Next nCnt

Inicializar a varivel no momento da declarao no um problema. Se o 0 fosse
necessrio no exemplo, teria sido til a inicializao na declarao. Mas neste caso a
estrutura de repetio For...Next atribui o seu valor imediatamente com 1, portanto
no houve ganho em atribuir a varivel com 0 no comeo.

Neste exemplo no h nenhum ponto negativo e nada errado ocorrer se a varivel
no for inicializada, portanto aconselhvel evitar este tipo de inicializao, pois no
torna o cdigo mais seguro e tambm no expressa a inteno do cdigo mais
claramente.

Porm, note este exemplo, onde a varivel no inicializada:

Local nCnt
While ( nCnt++ < 10 )
<cdigo>
EndDo

Em ADVPL, variveis no inicializadas sempre tem seu valor contendo nulo (nil) a
princpio, o que far com que uma exceo em tempo de execuo acontea quando a
instruo de repetio while for executada.

Diferentemente do primeiro exemplo, onde a inicializao da varivel no fazia
diferena alguma, neste segundo exemplo a inicializao absolutamente necessria.
Deve-se procurar inicializar variveis numricas com zero (0) e variveis caracter com
string nula ("") apenas quando realmente necessrio.

Utilizao de alternativas

Quando se est trabalhando em uma simples rotina, deve-se tomar algum tempo para
explorar duas ou trs diferentes abordagens. Quando se est trabalhando em algo mais
complexo, deve-se planejar prototipar algumas a mais. Considere o seguinte cdigo:

If cHair = "A"
Replace hair With "Loira"
Else
If cHair = "B"
Replace hair With "Morena"
Else
If cHair = "C"
Replace hair With "Ruiva"
Else
If cHair = "D"
Replace hair With "Grisalho"
Else
Replace hair With "Preto"
Endif
Endif
Endif
Endif

Um cdigo de uma nica letra, (A at E), foi informado para indicar a cor de cabelo.
Este cdigo foi ento convertido e armazenado como uma string. Pode-se notar que a
cor "Preto" ser atribuda se nenhuma outra opo for verdadeira.

Uma alternativa que reduz o nvel de identao torna o cdigo mais fcil de ler
enquanto reduz o nmero de comandos replace:

Do Case
Case cHair == "A"
cColor := "Loira"
Case cHair == "B"
cColor := "Morena"
Case cHair == "C"
cColor := "Ruiva"
Case cHair == "D"
cColor := "Grisalho"
OtherWise
cColor := "Preto"
EndCase

Replace hair With cColor

Utilizao de arquivos de cabealho quando necessrio

Se um arquivo de cdigo criado se referencia a comandos para interpretao e
tratamento de arquivos XML, este deve se incluir o arquivo de cabealho prprio para
tais comandos (XMLXFUN.CH no exemplo). Porm no deve-se incluir arquivos de
cabealho apenas por segurana. Se no se est referenciando nenhuma das
constantes ou utilizando nenhum dos comandos contidos em um destes arquivos, a
incluso apenas tornar a compilao mais demorada.

Constantes em maisculo

Isto uma conveno que faz sentido. Em ADVPL, como em C por exemplo, a regra
utilizar todos os caracteres de uma constante em maisculo, a fim de que possam ser
claramente reconhecidos como constantes no cdigo, e que no seja necessrios
lembrar onde foram declarados.

Utilizao de identao

Este um hbito que todo programador deve desenvolver. No consome muito
esforo para manter o cdigo alinhado durante o trabalho, porm quando necessrio
pode-se utilizar a ferramenta TOTVS DevStudio para a re-identao de cdigo. Para
maiores detalhes, consulte a documentao sobre a identao de cdigos fontes
disponvel nos demais tpicos deste material.

Utilizao de espaos em branco

Espaos em branco extras tornam o cdigo mais fcil para a leitura. No necessrio
imensas reas em branco, mas agrupar pedaos de cdigo atravs da utilizao de
espaos em branco funciona muito bem. Costuma-se separar parmetros com espaos
em branco.

Quebra de linhas muito longas

Com o objetivo de tornar o cdigo mais fcil de ler e imprimir, as linhas do cdigo no
devem estender o limite da tela ou do papel. Podem ser "quebradas" em mais de uma
linha de texto utilizando o ponto-e-vrgula (;).

Capitulao de palavras-chave

Uma conveno amplamente utilizada a de capitular as palavras chaves, funes,
variveis e campos utilizando uma combinao de caracteres em maisculo e
minsculo, visando facilitar a leitura do cdigo fonte.

Avaliando o cdigo a seguir:

local ncnt
while ( ncnt++ < 10 )
ntotal += ncnt * 2
enddo

O mesmo ficaria muito mais claro se re-escrito conforme abaixo:

Local nCnt

While ( nCnt++ < 10 )
nTotal += nCnt * 2
EndDo

Utilizao da Notao Hngara

A Notao Hngara muito comum entre programadores xBase e de outras
linguagens. A documentao do ADVPL utiliza esta notao para a descrio das
funes e comandos e aconselhvel sua utilizao na criao de rotinas, pois ajuda a
evitar pequenos erros e facilita a leitura do cdigo. Para maiores detalhes, consulte a
documentao sobre a utilizao da Notao Hngara de cdigos fontes disponvel
nos demais tpicos deste material.

Utilizao de nomes significantes para variveis

A principal vantagem da liberdade na criao dos nomes de variveis a facilidade de
identificao da sua utilidade. Portanto deve-se utilizar essa facilidade o mximo
possvel. Nomes sem sentido apenas tornaro difcil a identificao da utilidade de uma
determinada varivel, assim como nomes extremamente curtos. Nem sempre a
utilizao de uma varivel chamada i a melhor sada. Claro, no convm criar uma
varivel com um nome muito longo que ser utilizada como um contador, e
referenciada muitas vezes no cdigo. O bom senso deve ser utilizado.

Criar variveis como nNumero ou dData tambm no ajudam na identificao. A
Notao Hngara j est sendo utilizada para isso e o objetivo do nome da varivel
deveria ser identificar sua utilizao, no o tipo de dado utilizado. Deve-se procurar
substituir tais variveis por algo como nTotal ou dCompra.

O mesmo vlido para nomes de funes, que devem descrever um pouco sobre o
que a funo faz. Novamente nomes extremamente curtos no so aconselhveis.

Utilizao de comentrios

Comentrios so muito teis na documentao de programas criados e para facilitar a
identificao de processos importantes no futuro e devem sempre ser utilizados.

Sempre que possvel, funes criadas devem ter uma breve descrio do seu objetivo,
parmetros e retorno. Alm de servir como documentao, os comentrios embelezam
o cdigo ao separar as funes umas das outras. Os comentrios devem ser utilizados
com bom senso, pois reescrever a sintaxe ADVPL em portugus torna-se apenas perda
de tempo:

If nLastKey == 27 // Se o nLastKey for igual a 27

Criao de mensagens sistmicas significantes e consistentes

Seja oferecendo assistncia, exibindo mensagens de aviso ou mantendo o usurio
informado do estado de algum processo, as mensagens devem refletir o tom geral e a
importncia da aplicao. Em termos gerais, deve-se evitar ser muito informal e ao
mesmo tempo muito tcnico.

"Aguarde. Reindexando (FILIAL+COD+ LOCAL) do arquivo:
\DADOSADV\SB1990.DBF"

Esse tipo de mensagem pode dar informaes demais para o usurio e deix-lo
sentindo-se desconfortvel se no souber o que significa "reindexando", etc. E de fato,
o usurio no devia ser incomodado com tais detalhes. Apenas a frase "Aguarde,
indexando." funcionaria corretamente, assim como palavras "processando" ou
"reorganizando".

Outra boa idia evitar a referencia a um item corrente de uma tabela como um
"registro":

"Deletar este registro?"

Se a operao estiver sendo efetuada em um arquivo de clientes, o usurio deve ser
questionado sobre a remoo do cliente corrente, se possvel informando valores de
identificao como o cdigo ou o nome.

Evitar abreviao de comandos em 4 letras

Apesar do ADVPL suportar a abreviao de comandos em quatro letras (por exemplo,
repl no lugar de replace) no h necessidade de utilizar tal funcionalidade. Isto apenas
torna o cdigo mais difcil de ler e no torna a compilao mais rpida ou simples.

Evitar "disfarces" no cdigo

No deve-se criar constantes para expresses complexas. Isto tornar o cdigo muito
difcil de compreender e poder causar erros primrios, pois pode-se imaginar que
uma atribuio efetuada a uma varivel quando na verdade h toda uma expresso
disfarada:

#define NUMLINES aPrintDefs[1]
#define NUMPAGES aPrintDefs[2]
#define ISDISK aReturn[5]

If ISDISK == 1
NUMLINES := 55
Endif

NUMPAGES += 1

A impresso que se tem aps uma leitura deste cdigo de que valores esto sendo
atribudos s variveis ou que constantes esto sendo utilizadas. Se o objetivo
flexibilidade, o cdigo anterior deve ser substitudo por:

#define NUMLINES 1
#define NUMPAGES 2
#define ISDISK 5

If aReturn[ISDISK] == 1
aPrintDefs[ NUMLINES ] := 55
Endif

aPrintDefs[ NUMPAGES ] += 1

Evitar cdigo de segurana desnecessrio

Dada sua natureza binria, tudo pode ou no acontecer dentro de um computador.
Adicionar pedaos de cdigo apenas para "garantir a segurana" freqentemente
utilizado como uma desculpa para evitar corrigir o problema real. Isto pode incluir a
checagem para validar intervalos de datas ou para tipos de dados corretos, o que
comumente utilizando em funes:

Static Function MultMalor( nVal )
If ValType( nVal ) != "N"
nVal := 0
Endif
Return ( nVal * nVal )

O ganho irrisrio na checagem do tipo de dado do parmetro j que nenhum
programa corretamente escrito em execuo poderia enviar uma string ou uma data
para a funo. De fato, este tipo de "captura" o que torna a depurao difcil, j que o
retorno ser sempre um valor vlido (mesmo que o parmetro recebido seja de tipo de
dado incorreto). Se esta captura no tiver sido efetuada quando um possvel erro de
tipo de dado invlido ocorrer, o cdigo pode ser corrigido para que este erro no mais
acontea.

Isolamento de strings de texto

No caso de mensagens e strings de texto, a centralizao um bom negcio. Pode-se
colocar mensagens, caminhos para arquivos, e mesmo outros valores em um local
especfico. Isto os torna acessveis de qualquer lugar no programa e fceis de gerenciar.

Por exemplo, se existe uma mensagem comum como "Imprimindo, por favor
aguarde..." em muitas partes do cdigo, corre-se o risco de no seguir um padro
para uma das mensagens em algum lugar do cdigo. E mant-las em um nico lugar,
como um arquivo de cabealho, torna fcil a produo de documentao e a
internacionalizao em outros idiomas.
GUIA DE REFERNCIA RPIDA: FUNES E COMANDOS ADVPL
Neste guia de referncia rpida sero descritas as funes bsicas da linguagem
ADVPL, incluindo as funes herdadas da linguagem Clipper, necessrias ao
desenvolvimento no ambiente ERP.

Converso entre tipos de dados

CTOD()

Realiza a converso de uma informao do tipo caracter no formato DD/MM/AAAA
para uma varivel do tipo data.

E Sintaxe: CTOD(cData)
E Parmetros

cData Caracter no formato DD/MM/AAAA

Exemplo:

cData := 31/12/2006
dData := CTOD(cData)

IF dDataBase >= dData
MSGALERT(Data do sistema fora da competncia)
ELSE
MSGINFO(Data do sistema dentro da competncia)
ENDIF

CVALTOCHAR()

Realiza a converso de uma informao do tipo numrico em uma string, sem a adio
de espaos a informao.

E Sintaxe: CVALTOCHAR(nValor)
E Parmetros

nValor Valor numrico que ser convertido para caractere.

Exemplo:

FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos

DTOC()

Realiza a converso de uma informao do tipo data para caracter, sendo o resultado
no formato DD/MM/AAAA.

E Sintaxe: DTOC(dData)
E Parmetros

dData Varivel com contedo data

Exemplo:

MSGINFO(Database do sistema: +DTOC(dData)

DTOS()

Realiza a converso de uma informao do tipo data em um caracter, sendo o
resultado no formato AAAAMMDD.

E Sintaxe: DTOS(dData)
E Parmetros

dData Varivel com contedo data

Exemplo:

cQuery := SELECT A1_COD, A1_LOJA, A1_NREDUZ FROM SA1010 WHERE
cQuery += A1_DULTCOM >=+DTOS(dDataIni)+

STOD()

Realiza a converso de uma informao do tipo caracter com contedo no formato
AAAAMMDD em data.

E Sintaxe: STOD(sData)
E Parmetros

sData String no formato AAAAMMDD

Exemplo:

sData := LERSTR(01,08) // Funo que realiza a leitura de uma string
de um txt previamente
// aberto
dData := STOD(sData)

STR()

Realiza a converso de uma informao do tipo numrico em uma string, adicionando
espaos direita.

E Sintaxe: STR(nValor)
E Parmetros


Exemplo:

NEXT nPercorridos

STRZERO()

Realiza a converso de uma informao do tipo numrico em uma string, adicionando
zeros esquerda do nmero convertido, de forma que a string gerada tenha o
tamanho especificado no parmetro.

E Sintaxe: STRZERO(nValor, nTamanho)
E Parmetros

nTamanho Tamanho total desejado para a string retornada.

Exemplo:

NEXT nPercorridos


VAL()

Realiza a converso de uma informao do tipo caracter em numrica.

E Sintaxe: VAL(cValor)
E Parmetros

cValor String que ser convertida para numrico.

Exemplo:

Static Function Modulo11(cData)
LOCAL L, D, P := 0
L := Len(cdata)
D := 0
P := 1
While L > 0
P := P + 1
D := D + (Val(SubStr(cData, L, 1)) * P)
If P = 9
P := 1
End
L := L - 1
End
D := 11 - (mod(D,11))
If (D == 0 .Or. D == 1 .Or. D == 10 .Or. D == 11)
D := 1
End
Return(D)

Matemticas

ACOS()

Funo utilizada para calcular o valor do arco co-seno.

E Sintaxe: ACOS(nValor)

E Parmetros:

nValor Valor entre -1 e 1 de quem ser calculado o Arco Co-Seno.


E Retorno:

Numrico Range de 0 a radianos.

Se o valor informado no parmetro for menor que 1 ou maior que 1, acos
retorna um valor indefinido por default [+ , -]

CEILING()

Funo utilizada para calcular o valor mais prximo possvel de um valor nMax
informado como parmetro para a funo.

E Sintaxe: CELLING(nMax)

E Parmetros

nMax Valor limite para anlise da funo, no formato floating-point.

E Retorno:

Numrico
Valor do tipo double, representando o menor inteiro que maior ou igual ao
valor de nX. No h retorno de erro na funo.

COS()

Funo utilizada para calcular o valor do co-seno ou co-seno hiperblico.

Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da
funo COS().

E Sintaxe: COS(nAngulo)

E Parmetros:

nAngulo Valor que representa o ngulo em radianos.

E Retorno:

Numrico Valor que representa o co-seno ou co-seno hiperblico do ngulo informado.


E Situaes invlidas:

Entrada Exceo apresentada Significado da Exceo
QNAN,IND None Sem Domnio
(cosf, cos) INVALID Sem Domnio
x 7.104760e+002 (cosh, coshf) INEXACT+OVERFLOW OVERFLOW

LOG10()

Funo utilizada para calcular o logartmo natural de um valor numrico, em base 10.

LOG10() uma funo numrica que calcula o logaritmo natural de um nmero. O
logaritmo natural tem como base o valor 10. Devido ao arredondamento matemtico,
os valores retornados por LOG() podem no coincidir exatamente.

E Sintaxe: LOG10(nNatural)

E Parmetros:

nNatural Valor cujo o logaritmo deve ser encontrado.

E Retorno:

Numrico A funo retorna o logartmo de nNatural se bem sucedidas. Se nNatural for
negativo, estas funes retornam um indefinido, pelo defeito. Se nNatural for 0,
retornam INF(infinito).

SIN()

Funo utilizada para calcular o valor do seno ou seno hiperblico. Devemos informar
como parmetro para a funo um valor que representa o ngulo em radianos.

funo SIN().

E Sintaxe: SIN(nAngulo)

E Parmetros:

nAngulo Valor do ngulo em radianos.

E Retorno:

Numrico Retorna o valor do seno do ngulo especificado.

E Situaes invlidas:

(senf, sen) INVALID Sem Domnio
x 7.104760e+002 (senh, senhf) INEXACT+OVERFLOW OVERFLOW

SQRT()

Funo utilizada para calcular a raiz quadrada de um nmero positivo.

E Sintaxe: SQRT(nValor)
E Parmetros:

nValor Um nmero positivo do qual ser calculada a raiz quadrada.

E Retorno:

Numrico Retorna um valor numrico calculado com preciso dupla. A quantidade de
casas decimais exibidas determinada apenas por SET DECIMALS, sem importar
a configurao de SET FIXED. Um nmero negativo <nValor> retorna zero.

TAN()

Funo utilizada para calcular o valor da tangente ou tangente hiperblica.

funo cos.

E Sintaxe: TAN(nAngulo)

E Parmetros:

nAngulo Valor do ngulo em radianos.

E Retorno:

Numrico Retorna o valor da tangente do ngulo especificado.

E Situaes invlidas:

INVALID Sem Domnio


Anlise de variveis

TYPE()

Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em
execuo.

E Sintaxe: TYPE(cVariavel)

E Parmetros

cVariavel Nome da varivel que se deseja avaliar, entre aspas ().

Exemplo:
IF TYPE(dDataBase) == D
MSGINFO(Database do sistema: +DTOC(dDataBase))
ELSE
MSGINFO(Varivel indefinida no momento)
ENDIF

VALTYPE()

Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em
execuo.

E Sintaxe: VALTYPE(cVariavel)

E Parmetros

cVariavel Nome da varivel que se deseja avaliar.

Exemplo:
STATIC FUNCTION GETTEXTO(nTamanho, cTitulo, cSay)
LOCAL cTexto :=
LOCAL nColF, nLargGet := 0
PRIVATE oDlg
Default cTitulo := "Tela para informar texto"
Default cSay := "Informe o texto:"
Default nTamanho := 1

nTamanho := IIF(ValType(nTamanho) != N,1,nTamanho) // Se o
parmetro foi passado
cTexto := Space(nTamanho);nLargGet := Round(nTamanho * 2.5,0);
nColf := Round(195 + (nLargGet * 1.75) ,0)

DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 120,nColF PIXEL
@ 005,005 TO 060, Round(nColF/2,0) OF oDlg PIXEL
@ 010,010 SAY cSay SIZE 55, 7 OF oDlg PIXEL
@ 010,065 MSGET cTexto SIZE nLargGet, 11 OF oDlg PIXEL ;
Picture "@!" VALID !Empty(cTexto)
ACTION (nOpca := 1,oDlg:End()) ENABLE OF oDlg
ACTION (nOpca := 0,oDlg:End()) ENABLE OF oDlg
cTexto := IIF(nOpca==1,cTexto,"")
RETURN cTexto

Manipulao de arrays

AADD()

A funo AADD() permite a insero de um item em um array j existente, sendo que
este item podem ser um elemento simples, um objeto ou outro array.

E Sintaxe: AADD(aArray, xItem)

E Parmetros

aArray Array pr-existente no qual ser adicionado o item definido em xItem
xItem Item que ser adicionado ao array.

Exemplo:

aDados := {} // Define que a varivel aDados um array, sem
especificar suas dimenses.
aItem := {} // Define que a varivel aItem um array, sem
especificar suas dimenses.

AADD(aItem, cVariavel1) // Adiciona um elemento no array aItem de
acordo com o cVariavel1

// Neste ponto o array a Item possui 03 elementos os quais podem ser
acessados com:
// aItem[1] -> corresponde ao contedo de cVariavel1

AADD(aDados,aItem) // Adiciona no array aDados o contedo do array
aItem

// Neste ponto, o array a aDados possui apenas um elemento, que
tambm um array
// contendo 03 elementos:
// aDados [1][1] -> corresponde ao contedo de cVariavel1

AADD(aDados, aItem)
AADD(aDados, aItem)

// Neste ponto, o array aDados possui 03 elementos, aonde cada qual
um array com outros
// 03 elementos, sendo:




// Desta forma, o array aDados montando com uma estrutura de 03
linhas e 03 colunas, com
// o contedo definido por variveis externas, mas com a mesma forma
obtida com o uso do
// comando: aDados := ARRAY(3,3).

ACLONE()

A funo ACLONE() realiza a cpia dos elementos de um array para outro array
integralmente.

E Sintaxe: AADD(aArray)

E Parmetros

aArray Array pr-existente que ter seu contedo copiado para o array especificado.

Exemplo:

// Utilizando o array aDados utilizado no exemplo da funo AADD()
aItens := ACLONE(aDados)

// Neste ponto, o array aItens possui exatamente a mesma estrutura e
informaes do array
// aDados.

Por ser uma estrutura de memria, um array no pode ser
simplesmente copiado para outro array atravs de uma atribuio
simples (:=).

Para mais informaes sobre a necessidade de utilizar o comando
ACLONE() verifique o tpico 6.1.3 Cpia de Arrays.

ACOPY()

Funo de array que copia elementos do array aOrigem para array aDestino. O array
destino aDestino j deve ter sido declarado e grande o bastante para conter os
elementos que sero copiados. Se o array aOrigem contiver mais elementos, alguns
dos elementos no sero copiados. ACOPY() copia os valores de todos os dados,
incluindo valores nulos (NIL) e cdigos de bloco.

Se um elemento for um subarray, o elemento correspondente no array aDestino,
conter o mesmo subarray. Portanto, ACOPY() no produzir uma cpia completa de
array multidimensionais.

E Sintaxe: ACOPY( aOrigem, aDestino , [ nInicio ], [ nQtde ], [ nPosDestino ])

E Parmetros:

aOrigem o array que contm os elementos a serem copiados.
aDestino o array que receber a cpia dos elementos.
nInicio indica qual o ndice do primeiro elemento de aOrigem que ser copiado. Se
no for especificado, o valor assumido ser 01.
nQtde indica a quantidade de elementos a serem copiados a partir do array aOrigem.
iniciando-se a contagem a partir da posio nInicio. Se nQtde no for
especificado, todos os elementos do array aOrigem sero copiados, iniciando-
se a partir da posio nInicio.
nPosDestino a posio do elemento inicial no array aDestino que receber os elementos
de aOrigem. Se no especificado, ser assumido 01.

E Retorno:

aDestino referncia ao array aDestino.

Exemplo:

LOCAL nCount := 2, nStart := 1, aOne, aTwo
aOne := { 1, 1, 1 }
aTwo := { 2, 2, 2 }
ACOPY(aOne, aTwo, nStart, nCount)
// Result: aTwo is now { 1, 1, 2 }

ADEL()

A funo ADEL() permite a excluso de um elemento do array. Ao efetuar a excluso de
um elemento, todos os demais so reorganizados de forma que a ultima posio do
array passar a ser nula.

E Sintaxe: ADEL(aArray, nPosio)

E Parmetros

aArray Array do qual deseja-se remover uma determinada posio.
nPosio Posio do array que ser removida.

Exemplo:

// Utilizando o array aItens do exemplo da funo ACLONE() temos:

ADEL(aItens,1) // Ser removido o primeiro elemento do array aItens.

// Neste ponto, o array aItens continua com 03 elementos, aonde:
// aItens[1] -> antigo aItens[2], o qual foi reordenado como efeito
da excluso do item 1.
// aItens[2] -> antigo aItens[3], o qual foi reordenado como efeito
da excluso do item 1.
// aItens[3] -> contedo nulo, por se tratar do item excludo.

ADIR()

Funo que preenche os arrays passados com os dados dos arquivos encontrados,
atravs da mscara informada. Tanto arquivos locais (Remote) como do servidor
podem ser informados.

Importante: ADir uma funo obsoleta, utilize sempre Directory().

E Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ],
[aHora], [ aAtributo ])

E Parmetros:

cArqEspec Caminho dos arquivos a serem includos na busca de informaes. Segue o
padro para especificao de arquivos, aceitando arquivos no servidor Protheus
e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso seja omitido,
sero aceitos todos os arquivos do diretrio default ( *.* ).
aNomeArq Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
aTamanho Array Numrico. So os tamanhos dos arquivos encontrados na busca.
aData Array de Datas. So as datas de modificao dos arquivos encontrados na busca.
aHora Array de Caracteres. So os horrios de modificao dos arquivos encontrados.
Cada elemento contm horrio no formato: hh:mm:ss.
aAtributos Array de Caracteres. So os atributos dos arquivos, caso esse array seja passado
como parmetros, sero includos os arquivos com atributos de sistema e
ocultos.

E Retorno:

nArquivos Quantidade de arquivos encontrados.

Exemplo:

LOCAL aFiles[ADIR("*.TXT")]
ADIR("*.TXT", aFiles)
AEVAL(aFiles, { |element| QOUT(element) })

AFILL()

Funo de manipulao de arrays, que preenche os elementos do array com qualquer
tipo de dado. Incluindo code-block. Esta funo no deve ser usada para preencher um
array com outro array.

E Sintaxe: AFILL( aDestino , xExpValor, [ nInicio ], [ nQuantidade ])

E Parmetros

aDestino o onde os dados sero preenchidos.
xExpValor o dado que ser preenchido em todas as posies informadas, no
permitida a utilizao de arrays.
nInicio a posio inicial de onde os dados sero preenchidos, o valor padro 1.
nCount Quantidade de elementos a partir de [nInicio] que sero preenchidos com
<expValor>, caso no seja informado o valor ser a quantidade de elementos
at o final do array.

E Retorno:

aDestino Retorna uma referncia para aDestino.

Exemplo:

LOCAL aLogic[3]
// Resultado: aLogic { NIL, NIL, NIL }
AFILL(aLogic, .F.)
// Resultado: aLogic { .F., .F., .F. }
AFILL(aLogic, .T., 2, 2)
// Resultado: aLogic { .F., .T., .T. }

AINS()

A funo AINS() permite a insero de um elemento no array especificado em qualquer
ponto da estrutura do mesmo, diferindo desta forma da funo AADD() a qual sempre
insere um novo elemento ao final da estrutura j existente.

E Sintaxe: AINS(aArray, nPosicao)

E Parmetros

aArray Array pr-existente no qual desejasse inserir um novo elemento.
nPosicao Posio na qual o novo elemento ser inserido.

Exemplo:

aAlunos := {Edson, Robson, Renato, Tatiana}

AINS(aAlunos,3)
// Neste ponto o array aAlunos ter o seguinte contedo:
// {Edson, Robson, nulo, Renato, Tatiana}

Similar ao efeito da funo ADEL(), o elemento inserido no array pela
funo AINS() ter um contedo nulo, sendo necessrio trata-lo aps a
realizao deste comando.

ARRAY()

A funo Array() utilizada na definio de variveis de tipo array, como uma opo a
sintaxe utilizando chaves ({}).

E Sintaxe: Array(nLinhas, nColunas)

E Parmetros

nLinhas Determina o nmero de linhas com as quais o array ser criado.
nColunas Determina o nmero de colunas com as quais o array ser criado.

Exemplo:

aDados := Array(3,3) // Cria um array de trs linhas, cada qual com
3 colunas.


O array definido pelo comando Array() apesar de j possuir a estrutura
solicitada, no possui contedo em nenhum de seus elementos, ou
seja:

aDados[1] -> array de trs posies
aDados[1][1] -> posio vlida, mas de contedo nulo.

ASCAN()

A funo ASCAN() permite que seja identificada a posio do array que contm uma
determinada informao, atravs da anlise de uma expresso descrita em um bloco de
cdigo.

E Sintaxe: ASCAN(aArray, bSeek)

E Parmetros

aArray Array pr-existente no qual desejasse identificar a posio que contm a
informao pesquisada.
bSeek Bloco de cdigo que configura os parmetros da busca a ser realizada.

Exemplo:

aAlunos := {Mrcio, Denis, Arnaldo, Patrcia}

bSeek := {|x| x == Denis}

nPosAluno := aScan(aAlunos,bSeek) // retorno esperado 2

Durante a execuo da funo aScan, a varivel x receber o contedo o item
que est posicionado no momento, no caso aAlunos[x]. Como aAlunos[x] uma
posio do array que contm o nome do aluno, x poderia ser renomeada para
cNome, e a definio do bloco bSeek poderia ser escrita como:

bSeek := {|cNome| cNome == Denis}

Na definio dos programas sempre recomendvel utilizar variveis com nomes
significativos, desta forma os blocos de cdigo no so exceo.

Sempre opte por analisar como o bloco de cdigo ser utilizado e ao invs de x,
y e similares, defina os parmetros com nomes que representem seu contedo.
Ser mais simples o seu entendimento e o entendimento de outros que forem
analisar o cdigo escrito.

ASCANX()
Funo utilizada para varrer um vetor procurando um valor especificado, operando de
forma similar a funo ASCAN.
A diferena fundamental da funo ASCANX que esta funo recebe um segundo
parmetro em seu code-block representando o ndice do array.
E Sintaxe: ASCANX ( < xDestino > , < bSeek > , [ nInicio ] , [ nCont ] )

E Parmetros:

xDestino Representa o objeto a ser varrido pela funo, pode ser atribudo ao parmetro
um array um Objeto.
bSeek Representa o valor que ser pesquisado, podendo ser um bloco de cdigo.
nInicio Representa o elemento a partir do qual ter inicio a pesquisa, quando este
argumento no for informado o valor default ser 1.
nCont Representa a quantidade de elementos que sero pesquisados a partir da
posio inicial, quando este argumento no for informado todos elementos do
array sero pesquisados.

Exemplo.:

nPos := aScanX( ARRAY, { |X,Y| X[1] == cNome .OR. y<=100})

No cdigo demonstrado acima, note a incluso no code-block do Y,
onde a funo ir terminar sua execuo em 3 condies:

1) At encontrar o elemento no ARRAY com a ocorrncia cNome,
retornando a posio desse elemento.

2) Essa novidade, ASCANX ir verificar o Array at a posio 100.

3) O elemento cNome no foi encontrado no ARRAY e a condio de Y
at 100 no satisfaz, pois o array menor do que 100 posies!

Como ASCAN() que utiliza o operador (=) para comparaes, a funo
ASCANX() tambm case sensitive, no caso os elementos procurados
devem ser exatamente igual.

ASIZE()

A funo ASIZE permite a redefinio da estrutura de um array pr-existente,
adicionando ou removendo itens do mesmo.

E Sintaxe: ASIZE(aArray, nTamanho)

E Parmetros

aArray Array pr-existente que ter sua estrutura redimensionada.
nTamanho Tamanho com o qual deseja-se redefinir o array. Se o tamanho for menor do
que o atual, sero removidos os elementos do final do array, j se o tamanho for
maior do que o atual sero inseridos itens nulos ao final do array.

Exemplo:

// Utilizando o array aItens, o qual teve um elemento excludo pelo
uso da funo ADEL()

ASIZE(aItens,Len(aItens-1))

// Neste ponto o array aItens possui 02 elementos, ambos com
contedos vlidos.

Utilizar a funo ASIZE() aps o uso da funo ADEL() uma prtica
recomendada e evita que seja acessada uma posio do array com um
contedo invlido para a aplicao em uso.

ASORT()

A funo ASORT() permite que os itens de um array sejam ordenados a partir de um
critrio pr-estabelecido.

E Sintaxe: ASORT(aArray, nInicio, nItens, bOrdem)

E Parmetros

aArray Array pr-existente que ter seu contedo ordenado atravs de um critrio
estabelecido.
nInicio Posio inicial do array para incio da ordenao. Caso no seja informado, o
array ser ordenado a partir de seu primeiro elemento.
nItens Quantos itens, a partir da posio inicial devero ser ordenados. Caso no seja
informado, sero ordenados todos os elementos do array.
bOrdem Bloco de cdigo que permite a definio do critrio de ordenao do array.
Caso bOrdem no seja informado, ser utilizado o critrio ascendente.

Um bloco de cdigo basicamente uma funo escrita em linha. Desta forma sua
estrutura deve suportar todos os requisitos de uma funo, os quais so atravs
da anlise e interpretao de parmetros recebidos, executar um processamento
e fornecer um retorno.

Com base nesse requisito, pode-se definir um bloco de cdigo com a estrutura
abaixo:

bBloco := { |xPar1, xPar2, ... xParZ| Ao1, Ao2, AoZ } , aonde:

|| -> define o intervalo onde esto compreendidos os parmetros
Ao Z-> expresso que ser executadas pelo bloco de cdigo
Ao1... AoZ -> intervalo de expresses que sero executadas pelo bloco de
cdigo, no formato de lista de expresses.

Retorno -> resultado da ultima ao executada pelo bloco de cdigo, no caso
AoZ.

Para maiores detalhes sobre a estrutura e utilizao de blocos de cdigo consulte
o tpico 6.2 Listas de Expresses e Blocos de cdigo.

Exemplo 01 Ordenao ascendente

aAlunos := { Mauren, Soraia, Andria}

aSort(aAlunos)

// Neste ponto, os elementos do array aAlunos sero {Andria,
Mauren, Soraia}

Exemplo 02 Ordenao descendente

aAlunos := { Mauren, Soraia, Andria}
bOrdem := {|x,y| x > y }

// Durante a execuo da funo aSort(), a varivel x receber o
contedo do item que est
// posicionado. Como o item que est posicionado a posio
aAlunos[x] e aAlunos[x] ->
// string contendo o nome de um aluno, pode-se substituir x por
cNomeAtu.
// A varivel y receber o contedo do prximo item a ser
avaliado, e usando a mesma
// analogia de x, pode-se substituir y por cNomeProx. Desta
forma o bloco de cdigo
// bOrdem pode ser re-escrito como:

bOrdem := {|cNomeAtu, cNomeProx| cNomeAtu > cNomeProx}

aSort(aAlunos,,bOrdem)

// Neste ponto, os elementos do array aAlunos sero {Soraia ,
Mauren, Andria}

ATAIL()

ATAIL() uma funo de manipulao de array que retorna o ltimo elemento de um
array. Ela deve ser usada em substituio da seguinte construo: aArray [LEN( aArray )]

E Sintaxe: ATAIL( aArray )

E Parmetros:

aArray o array de onde ser retornado o ltimo elemento.

E Retorno:

nUltimo Nmero do ltimo elemento do array.

Exemplo:

aArray := {"a", "b", "c", "d"}
ATAIL(aArray) // Resultado: d

Manipulao de blocos de cdigo

EVAL()

A funo EVAL() utilizada para avaliao direta de um bloco de cdigo, utilizando as
informaes disponveis no mesmo de sua execuo. Esta funo permite a definio e
passagem de diversos parmetros que sero considerados na interpretao do bloco
de cdigo.

E Sintaxe: EVAL(bBloco, xParam1, xParam2, xParamZ)

E Parmetros

bBloco Bloco de cdigo que ser interpretado.
xParamZ Parmetros que sero passados ao bloco de cdigo. A partir da passagem do
bloco, todos os demais parmetros da funo sero convertidos em parmetros
para a interpretao do cdigo.

Exemplo:

nInt := 10
bBloco := {|N| x:= 10, y:= x*N, z:= y/(x*N)}
nValor := EVAL(bBloco, nInt)
// O retorno ser dado pela avaliao da ultima ao da lista de
expresses, no caso z.
// Cada uma das variveis definidas em uma das aes da lista de
expresses fica disponvel
// para a prxima ao.
// Desta forma temos:
// N recebe nInt como parmetro (10)
// X tem atribudo o valor 10 (10)
// Y resultado da multiplicao de X por N (100)
// Z resultado a diviso de Y pela multiplicao de X por N ( 100
/ 100) 1

DBEVAL()

A funo DBEval() permite que todos os registro de uma determinada tabela sejam
analisados e para cada registro ser executado o bloco de cdigo definido.

E Sintaxe: Array(bBloco, bFor, bWhile)

E Parmetros

bBloco Bloco de cdigo principal, contendo as expresses que sero avaliadas para
cada registro do alias ativo.

bFor Condio para continuao da anlise dos registros, com o efeito de uma
estrutura For ... Next.

bWhile Condio para continuao da anlise dos registros, com o efeito de uma
estrutura While ... End.

Exemplo 01:
// Considerando o trecho de cdigo abaixo:
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()

While !Eof() .And. X5_FILIAL == xFilial("SX5") .And.; X5_TABELA <=
mv_par02
nCnt++
dbSkip()
End

// O mesmo pode ser re-escrito com o uso da funo DBEVAL():
dbEval( {|x| nCnt++ },,{||X5_FILIAL==xFilial("SX5") .And.
X5_TABELA<=mv_par02})

Exemplo 02:
// Considerando o trecho de cdigo abaixo:
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()

While !Eof() .And. X5_TABELA == cTabela
AADD(aTabela,{X5_CHAVE, Capital(X5_DESCRI)})
dbSkip()
End

// O mesmo pode ser re-escrito com o uso da funo DBEVAL():

dbEval({|| AADD(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{||
X5_TABELA==cTabela})

Na utilizao da funo DBEVAL() deve ser informado apenas um dos
dois parmetros: bFor ou bWhile.

AEVAL()

A funo AEVAL() permite que todos os elementos de um determinada array sejam
analisados e para cada elemento ser executado o bloco de cdigo definido.

E Sintaxe: AEVAL(aArray, bBloco, nInicio, nFim)

E Parmetros

aArray Array que ser avaliado na execuo da funo.
bBloco Bloco de cdigo principal, contendo as expresses que sero avaliadas para
cada elemento do array informado.

nInicio Elemento inicial do array, a partir do qual sero avaliados os blocos de cdigo.
nFim Elemento final do array, at o qual sero avaliados os blocos de cdigo.

Exemplo 01:

Considerando o trecho de cdigo abaixo:

AADD(aCampos,A1_FILIAL)
AADD(aCampos,A1_COD)
SX3->(dbSetOrder(2))
For nX:=1 To Len(aCampos)
SX3->(dbSeek(aCampos[nX]))
AADD(aTitulos,AllTrim(SX3->X3_TITULO))
Next nX

O mesmo pode ser re-escrito com o uso da funo AEVAL():

aEval(aCampos,{|x| SX3->(dbSeek(x)),IIF(Found(), AADD(aTitulos,;
AllTrim(SX3->X3_TITULO)))})

Manipulao de strings

ALLTRIM()

Retorna uma string sem os espaos direita e esquerda, referente ao contedo
informado como parmetro.

A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e LTRIM
(left trim).

E Sintaxe: ALLTRIM(cString)

E Parmetros

cString String que ser avaliada para remoo dos espaos a direita e a esquerda.

Exemplo:

cNome := ALLTRIM(SA1->A1_NOME)

MSGINFO(Dados do campo A1_NOME:+CRLF
Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))

ASC()

Converte uma informao caractere em seu valor de acordo com a tabela ASCII.

E Sintaxe: ASC(cCaractere)

E Parmetros

cCaractere Caracter que ser consultado na tabela ASCII.

Exemplo:

USER FUNCTION NoAcento(Arg1)
Local nConta := 0
Local cLetra := ""
Local cRet := ""
Arg1 := Upper(Arg1)
For nConta:= 1 To Len(Arg1)
cLetra := SubStr(Arg1, nConta, 1)
Do Case
Case (Asc(cLetra) > 191 .and. Asc(cLetra) < 198) .or.;
(Asc(cLetra) > 223 .and. Asc(cLetra) < 230)
cLetra := "A"
cLetra := "E"

cLetra := "I"

(Asc(cLetra) == 240) .or. (Asc(cLetra) > 241 .and. Asc(cLetra) <
247)
cLetra := "O"

cLetra := "U"

Case Asc(cLetra) == 199 .or. Asc(cLetra) == 231
cLetra := "C"

EndCase

cRet := cRet+cLetra

Next

Return UPPER(cRet)

AT()

Retorna a primeira posio de um caracter ou string dentro de outra string
especificada.

E Sintaxe: AT(cCaractere, cString )

E Parmetros

cCaractere Caractere ou string que se deseja verificar.
cString String na qual ser verificada a existncia do contedo de cCaractere.

Exemplo:
STATIC FUNCTION NOMASCARA(cString,cMascara,nTamanho)

LOCAL cNoMascara := ""
LOCAL nX := 0

IF !Empty(cMascara) .AND. AT(cMascara,cString) > 0
FOR nX := 1 TO Len(cString)
IF !(SUBSTR(cString,nX,1) $ cMascara)
cNoMascara += SUBSTR(cString,nX,1)
ENDIF
NEXT nX
cNoMascara := PADR(ALLTRIM(cNoMascara),nTamanho)
ELSE
cNoMascara := PADR(ALLTRIM(cString),nTamanho)
ENDIF

RETURN cNoMascara
BITON()

Funo utilizada para ligar determinados bits de uma String passada por parmetro
para a funo. Alm da string a ser alterada, a funo tambm recebe como parmetro
um numrico que indica o bit de incio a ser alterado, um numrico que indica a
quantidade de bits a serem alterados(ligados) e o tamanho da string passada.

E Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > )

E Parmetros

cValue String no qual desejamos ligar os bits.
nBitIni Indica a partir de qual bit, comear a ser ligados os bits na String.
nBitEnd Indica a quantidade de bits que sero ligados a partir do incio.
nStrLen Representa o tamanho da String passada para a funo.

CAPITAL()

Funo que avalia a string passada como parmetro alterando a primeira letra de cada
palavra para maiscula e as demais letras como minsculas.

E Sintaxe: CAPITAL(cFrase)

E Parmetros:

cFrase String a ser avaliada.

E Retorno:

String Contedo da string original com as modificaes necessrias para atender a
condio da funo.

CHR()

Converte um valor nmero referente a uma informao da tabela ASCII no caractere
que esta informao representa.

E Sintaxe: CHR(nASCII)

E Parmetros

nASCII Cdigo ASCII do caractere

Exemplo:

#DEFINE CRLF CHR(13)+CHR(10) // FINAL DE LINHA

DESCEND()

Funo de converso que retorna a forma complementada da expresso string
especificada. Esta funo normalmente utilizada para a criao de indexadores em
ordem decrescente

E Sintaxe: DESCEND ( < cString > )

E Parmetros:

cString Corresponde seqncia de caracteres a ser analisada.

E Retorno:

Caracter

String complementada da string analisada.

Exemplo:

// Este exemplo utiliza DESCEND() em uma expresso INDEX para criar
um ndice de datas de
// ordem descendente:

USE Sales NEW
INDEX ON DESCEND(DTOS(OrdDate)) TO SalesDate

// Depois, DESCEND() pode ser utilizado para fazer uma pesquisa
(SEEK) no ndice
// descendente:

DbSEEK(DESCEND(DTOS(dFindDate)))

GETDTOVAL()

Funo utilizada para retornar um numero formatado, de acordo com o valor passado
por parmetro, sendo que ir apenas manter os valores numricos contidos na string
passada por parmetro, verificando se existe algum caractere '.' retornando um nmero
fracionrio, na ordem dos nmeros contidos na string.

A funo muito til quando desejamos utilizar o valor numrico de uma data que
est contida em uma string.

E Sintaxe: GETDTOVAL ( < cDtoVal > )

E Parmetros:

cDtoVal Representa uma string contendo um valor numrico no qual ser convertido.

E Retorno:

Numrico Retorna um dado numrico de acordo com o valor informado em <cDtoVal>.

Exemplo:

GetDtoVal('123456') //retorno 123456.0000
GetDtoVal('1/2/3/4/5/6') //retorno 123456.0000
GetDtoVal('fim.123456') //retorno 0.123456
GetDtoVal('teste') //retorno 0.0

ISALPHA()

Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de
caracteres alfabtico, permitindo avaliar se o string especificado comea com um
caractere alfabtico. Um caractere alfabtico consiste em qualquer letra maiscula ou
minscula de A a Z.

E Sintaxe: ISALPHA ( < cString > )

E Parmetros:

cString Cadeia de caracteres a ser examinada.

E Retorno:

Lgico Retorna verdadeiro (.T.) se o primeiro caractere em <cString> for alfabtico,
caso contrrio, retorna falso (.F.).

ISDIGIT()

Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de
caracteres um dgito, permitindo avaliar se o primeiro caractere em um string um
dgito numrico entre zero e nove.

E Sintaxe: ISDIGIT ( < cString > )

E Parmetros:


E Retorno:

Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um dgito entre
zero e nove; caso contrrio, retorna falso (.F.).

ISLOWER()

Funo utilizada para determinar se o caractere mais esquerda uma letra minscula,
permitindo avaliar se o primeiro caractere de um string uma letra minscula. o
contrrio de ISUPPER(), a qual determina se a cadeia de caracteres comea com uma
letra maiscula. ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e
UPPER(), que convertem caracteres minsculos para maisculos, e vice-versa.

E Sintaxe: ISLOWER( < cString > )

E Parmetros:


E Retorno:

Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja minsculo, caso
contrrio, retorna falso (.F.).

ISUPPER()

Funo utilizada para determinar se o caractere mais esquerda uma letra maiscula,
permitindo avaliar se o primeiro caractere de um string uma letra maiscula. o
contrrio de ISLOWER (), a qual determina se a cadeia de caracteres comea com uma
letra minscula. ISLOWER() e ISUPPER() ambas so relacionadas s funes LOWER() e
UPPER(), que convertem caracteres minsculos para maisculos, e vice-versa.

E Sintaxe: ISUPPER( < cString > )

E Parmetros:


E Retorno:

Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja maisculo, caso
contrrio, retorna falso (.F.).

LEN()

Retorna o tamanho da string especificada no parmetro.

E Sintaxe: LEN(cString)

E Parmetros

cString String que ser avaliada.

Exemplo:

cNome := ALLTRIM(SA1->A1_NOME)
MSGINFO(Dados do campo A1_NOME:+CRLF
Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))

LOWER()

Retorna uma string com todos os caracteres minsculos, tendo como base a string
passada como parmetro.

E Sintaxe: LOWER(cString)

E Parmetros

cString String que ser convertida para caracteres minsculos.

Exemplo:

cTexto := ADVPL

MSGINFO(Texto:+LOWER(cTexto))

LTRIM()

Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que
possuam espaos em branco esquerda. Pode ser o caso de, por exemplo, nmeros
convertidos para cadeias de caracteres atravs da funo STR().

LTRIM() relacionada a RTRIM(), a qual remove espaos em branco direita, e a
ALLTRIM(), que remove espaos tanto esquerda quanto direita.

O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(),
as quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres,
atravs da insero de caracteres de preenchimento.

E Sintaxe: LTRIM ( < cString > )

E Parmetros:

cString <cString> a cadeia de caracteres a ser copiada sem os espaos em branco
esquerda.

E Retorno:

Caracter LTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco
esquerda foram removidos. Caso <cString> seja uma cadeia de caracteres nula
("") ou toda composta de espaos em branco, LTRIM() retorna uma cadeia de
caracteres nula ("").

MATHC()

Funo utilizada para realizar operaes matemticas com strings que contm um valor
numrico. MATHC() realiza algumas operaes matemticas como: Soma, Subtrao,
Diviso, Multiplicao e Exponenciao.

A funo ir retornar uma string contendo o resultado da operao matemtica, com
uma especificao de at 18 casas de preciso no nmero.

E Sintaxe: MATHC ( < cNum1 > , < cOperacao > , < cNum2 > )

E Parmetros:

cNum1 String contendo um valor numrico, representando o numero no qual
desejamos realizar uma operao.
cOperacao Representa a string que indica a operao que desejamos realizar. Olhar na
tabela para verificar quais valores devem ser informados aqui.
cNum2 String contendo um valor numrico, representando o numero no qual
desejamos realizar uma operao.

E Retorno:

Caracter Retorna uma nova string contendo o resultado matemtico da operao.

OEMTOANSI()

Funo que transforma uma string no Formato OEM / MS-DOS Text para uma
string ANSI Text ( formato do Windows ).

Quando utilizamos um programa baseado no MS-DOS para alimentar uma base de
dados, os acentos e caracteres especiais so gravados como texto OEM. Para tornar
possvel a correta visualizao destes dados em uma interface Windows, utilizamos a
funo OemToAnsi() para realizar a converso.

Ao utilizarmos um programa baseado no Windows para alimentar uma base de dados,
o texto capturado no formato ANSI Text. Caso este texto seja utilizado para alimentar
uma base de dados a ser acessada atravs de um programa MS-DOS, devemos
converter o dado para OEM antes de grav-lo, atravs da funo AnsiToOem().

E Sintaxe: OemToAnsi ( < cStringOEM > )

E Parmetros:

cStringOEM String em formato OEM - MsDos a ser convertida.

E Retorno:

Caracter String convertida para ser exibida no Windows ( Formato ANSI ).

PADL() / PADR() / PADC()

Funes de tratamento de strings que inserem caracteres de preenchimento para
completar um tamanho previamente especificado em vrios formatos como data ou
numricos.

Q PADC() centraliza <cExp>, adicionando caracteres de preenchimento direita e
esquerda.
Q PADL() adiciona caracteres de preenchimento esquerda.
Q PADR() adiciona caracteres de preenchimento direita.

Caso o tamanho de <cExp> exceda o argumento <nTamanho>, todas as funes PAD()
truncam string preenchida ao <nTamanho> especificado.

PADC(), PADL(), e PADR() so utilizadas para exibir cadeias de caracteres de tamanho
varivel em uma rea de tamanho fixo. Elas podem ser usadas, por exemplo, para
assegurar o alinhamento com comandos consecutivos. Outra utilizao exibir textos
em uma tela de tamanho fixo, para certificar-se de que o texto anterior foi
completamente sobrescrito.

PADC(), PADL(), e PADR() so o contrrio das funes ALLTRIM(), LTRIM(), e LTRIM(), as
quais eliminam espaos em branco esquerda e direita de cadeias de caracteres.

E Sintaxe: PADL / PADR / PADC ( < cExp > , < nTamanho > , [ cCaracPreench
] )

E Parmetros

cExp Caractere, data, ou numrico no qual sero inseridos caracteres de
preenchimento.
nTamanho Tamanho da cadeia de caracteres a ser retornada.
cCaracPreench Caractere a ser inserido em cExp. Caso no seja especificado, o padro o
espao em branco.

E Retorno:

Caracter Retornam o resultado de <cExp> na forma de uma cadeia de caracteres
preenchida com <cCaracPreench>, para totalizar o tamanho especificado
por <nTamanho>.

RAT()

Retorna a ltima posio de um caracter ou string dentro de outra string especificada.

E Sintaxe: RAT(cCaractere, cString)

E Parmetros

cCaractere Caractere ou string que se deseja verificar
cString String na qual ser verificada a existncia do contedo de cCaractere.

REPLICATE()

A funo Replicate() utilizada para gerar uma cadeira de caracteres repetidos a partir
de um caracter base informado, podendo a string gerada conter at 64KB. Caso seja
especificado no parmetro de itens a repetir o nmero zero, ser retornada uma string
vazia.

E Sintaxe: REPLICATE(cString, nCount)

E Parmetros:

cString Caracter que ser repetido.
nCount Quantidade de ocorrncias do caracter base que sero geradas na string de
destino.

E Retorno:

cReplicated String contendo as ocorrncias de repeticao geradas para o caracter
informado.

RTRIM()

Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que
contenham espaos em branco direita. Ela til quando voc deseja eliminar espaos
em branco direita ao se concatenar cadeias de caracteres. o caso tpico de campos
de banco de dados que so armazenados em formato de tamanho fixo. Por exemplo,
voc pode usar RTRIM() para concatenar o primeiro e o ltimo campos de nome para
formar uma cadeia de caracteres de nome.

LTRIM() relacionada a RTRIM(), que remove espaos em branco direita, e a
ALLTRIM(), que remove espaos em branco direita e esquerda.

O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(),
as quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres,
inserindo caracteres de preenchimento.

E Sintaxe: RTRIM ( < cString > ) --> cTrimString

E Parmetros:

cString <cString> a cadeia de caracteres a ser copiada sem os espaos em branco
direita.

E Retorno:

Caracter

RTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco
direita foram removidos. Caso <cString> seja uma cadeia de caracteres nula ("")
ou totalmente composta por espaos, RTRIM() retorna uma cadeia de caracteres
nula ("").

SPACE()

Funo de tratamento de caracteres utilizada para retornar uma quantidade
especificada de espaos. A utilizao desta funo tem o mesmo efeito que
REPLICATE(' ', <nCont>), e normalmente utilizada para inicializar uma varivel do
tipo caractere, antes que a mesma seja associada a um GET.

Sintaxe: SPACE ( < nCont > )

E Parmetros:

nCont A quantidade de espaos a serem retornados, sendo que o nmero mximo
65.535 (64K).

E Retorno:

Caracter Retorna uma cadeia de caracteres. Se <nCont> for zero, SPACE()retorna uma
cadeia de caracteres nula ("").

STRTOKARR()

Funo utilizada para retornar um array, de acordo com os dados passados como
parmetro para a funo. Esta funo recebe uma string <cValue> e um caracter
<cToken> que representa um separador, e para toda ocorrncia deste separador em
<cValue> adicionado um item no array.

E Sintaxe: STRTOKARR ( < cValue > , < cToken > )

E Parmetros:

cValue Representa a cadeia de caracteres no qual desejamos separar de acordo com
<cToken>.
cToken Representa o caracter que indica o separador em <cValue>.

E Retorno:

Array Array de caracteres que representa a string passada como parmetro.

Exemplo:

STRTOKARR('1;2;3;4;5', ';') //retorna {'1','2','3','4','5'}

STRTRAN()

Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive.

E Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [
nCount ] )

E Parmetros:

cString Seqncia de caracteres ou campo memo a ser pesquisado.
cSearch Seqncia de caracteres a ser procurada em cString.
cReplace Seqncia de caracteres que deve substituir a string cSearch. Caso no seja
especificado, as ocorrncias de cSearch em cString sero substitudas por uma
string nula ("").
nStart nStart corresponde ao nmero seqencial da primeira ocorrncia de cSEarch
em cString a ser substituda por cReplace. Se este argumento for omitido , o
default 1 ( um ). Caso seja passado um nmero menor que 1, a funo
retornar uma string em branco ("").
nCount nCount corresponde ao nmero mximo de trocas que dever ser realizada
pela funo. Caso este argumento no seja especificado, o default substituir
todas as ocorrncias encontradas.

E Retorno:

Code-Block

A funo STRTRAN retorna uma nova string, com as ocorrncias especificadas
de cSearch trocadas para cReplace, conforme parametrizao.

STUFF()

Funo que permite substituir um contedo caractere em uma string j existente,
especificando a posio inicial para esta adio e o nmero de caracteres que sero
substitudos.

E Sintaxe: STUFF(cString, nPosInicial, nExcluir, cAdicao)

E Parmetros:

cString A cadeia de caracteres destino na qual sero eliminados e inseridos caracteres.
nPosInicial A posio inicial na cadeia de caracteres destino onde ocorre a
insero/eliminao.
nExcluir A quantidade de caracteres a serem eliminados.
cAdicao A cadeia de caracteres a ser inserida.

E Retorno:

Caracter Retorna a nova string gerada pela funo com as modificaes.

Exemplo:

cLin := Space(100)+cEOL // Cria a string base
cCpo := PADR(SA1->A1_FILIAL,02) // Informao que ser armazenada na
string
cLin := Stuff(cLin,01,02,cCpo) // Substitui o contedo de cCpo na
string base

SUBSTR()

Retorna parte do contedo de uma string especificada, de acordo com a posio inicial
deste contedo na string e a quantidade de caracteres que dever ser retornada a
partir daquele ponto (inclusive).

E Sintaxe: SUBSTR(cString, nPosInicial, nCaracteres)

E Parmetros

cString String que se deseja verificar
nPosInicial Posio inicial da informao que ser extrada da string
nCaracteres Quantidade de caracteres que dever ser retornada a partir daquele ponto
(inclusive).

Exemplo:

cCampo := A1_NOME
nPosUnder := AT(cCampo)
cPrefixo := SUBSTR(cCampo,1, nPosUnder) // A1_

TRANSFORM()

Funo de converso que formata valores caractere, data, lgicos e numricos
conforme um string de mscara especificado, a qual inclui uma combinao de strings
de template e funes de picture. Ela faz o mesmo que a clusula PICTURE do comando
@...SAY, sendo normalmente utilizada para formatar dados a serem enviados tela ou
impressora.

E Sintaxe: TRANSFORM ( < cExp > , < cSayPicture > )

E Parmetros:

cExp O valor a ser formatado. Esta expresso pode ser qualquer tipo de dados
vlidos, exceto vetor, bloco de cdigo, e NIL.
cSayPicture Uma string de caracteres de mscara e template usado para descrever o formato
da cadeia de caracteres a ser retornada.

E Retorno:

- Retorna a converso de <cExp> para uma cadeia de caracteres formatada
conforme a definio em <cSayPicture>.

UPPER()

Retorna uma string com todos os caracteres maisculos, tendo como base a string
passada como parmetro.

E Sintaxe: UPPER(cString)

E Parmetros

cString String que ser convertida para caracteres maisculos.

Exemplo:

cTexto := ADVPL

MSGINFO(Texto:+LOWER(cTexto))

Manipulao de data / hora

CDOW()

Funo que converte uma data para uma cadeia de caracteres.

E Sintaxe: CDOW( dExp )

E Parmetros:

dExp Data que ser convertida.

E Retorno:

cDayWeek Nome do dia da semana como uma cadeia de caracteres. A primeira letra
maiscula e as demais minsculas.

Exemplo:

dData := DATE() // Resultado: 09/01/90
cDiaDaSemana := CDOW(DATE()) // Resultado: Friday
cDiaDaSemana := CDOW(DATE() + 7) // Resultado: Friday
cDiaDaSemana := CDOW(CTOD("06/12/90")) // Resultado: Tuesday

CMONTH()

Funo de converso de datas que retorna uma cadeia de caracteres com o nome do
ms em ingls.

E Sintaxe: CMONTH( dData )

E Parmetros:

dData Data que ser convertida.

E Retorno:

cMonth Retorna o nome do ms em uma cadeia de caracteres. A primeira letra do
retorno em maiscula e o restante do nome, em minsculas.

Exemplo:

cMes := CMONTH(DATE()) // Resultado: September
cMes := CMONTH(DATE() + 45) // Resultado: October
cMes := CMONTH(CTOD("12/01/94")) // Resultado: December
cMes := SUBSTR(CMONTH(DATE()), 1, 3) + STR(DAY(DATE())) //
Resultado: Sep 1

DATE()

Funo que retorna a data do atual sistema. O formato de sada controlado pelo
comando SET DATE, sendo que o formato padro mm/dd/yy.

E Sintaxe: DATE()

E Parmetros:

Nenhum ()


E Retorno:

dData Data do sistema.

Exemplo:

dData := DATE() + 30 // Resultado: 10/01/01
dData := DATE() - 30 // Resultado: 08/02/90
dData := DATE()
cMes := CMONTH(dData) // Resultado: September

DAY()

Funo de converso de datas usada para converter o valor data em um nmero inteiro
que representa o dia do ms. Esta funo pode ser usada em conjunto com CMONTH()
e YEAR() para formatar datas. Pode ser usada tambm em diversos clculos envolvendo
datas.

E Sintaxe: DAY( dData )

E Parmetros:


E Retorno:

nDias Se o ms do argumento dData for fevereiro, anos bissextos so considerados. Se
a data do argumento dData for 29 de fevereiro e o ano no for bissexto, ou se o
argumento dData for vazio.

Exemplo:
// Estes exemplos mostram a funo DAY() de diversas maneiras:
nDia := DAY(DATE()) // Resultado: 1
nDia := DAY(DATE()) + 1 // Resultado: 2
nDia := DAY(CTOD("12/01/94")) // Resultado: 1
// Este exemplo mostra a funo DAY() usada em conjunto com CMONTH()
e
YEAR() para formatar o valor da data:
dData := Date()
cData := CMONTH(dData) + STR(DAY(dData)) + "," + STR(YEAR(dData)) //
Resultado: June 15, 2001

DOW()

Funo que converte uma data para o valor numrico que representa o dia da semana.
til quando se deseja fazer clculos semanais. DOW() similar a CDOW(), que retorna o
dia da semana como uma cadeia de caracteres.

E Sintaxe: DOW( dData )

E Parmetros:


E Retorno:

nDia Retorna um nmero entre zero e sete, representando o dia da semana. O
primeiro dia da semana 1 (Domingo) e o ltimo 7 (Sbado). Se a data for
vazia ou invlida, DOW() retorna zero.

Exemplo:

nDiaDaSemana := DOW(DATE()) // Resultado: 3
cDiaDaSemana := CDOW(DATE()) // Resultado: Tuesday
nDiaDaSemana := DOW(DATE() - 2) // Resultado: 1
cDiaDaSemana := CDOW(DATE() - 2) // Resultado: Sunday

DTOC()

Funo para converso de uma data para uma cadeia de caracteres formatada segundo
o padro corrente, definido pelo comando SET DATE. Se for necessria a utilizao de
formatao especial, use a funo TRANSFORM().

Em expresses de ndices de arquivo, use DTOS() no lugar de DTOC() para converter
datas para cadeia de caracteres.

E Sintaxe: DTOC( dData )

E Parmetros:



E Retorno:

cData uma cadeia de caracteres representando o valor da data. O retorno
formatado utilizando-se o formato corrente definido pelo comando SET DATE
FORMAT. O formato padro mm/dd/yy. Para uma data nula ou invlida, o
retorno ser uma cadeia de caracteres com espaos e tamanho igual ao formato
atual.

Exemplo:

cData := DATE() // Resultado: 09/01/90
cData := DTOC(DATE()) // Resultado: 09/01/90
cData := "Today is " + DTOC(DATE()) // Resultado: Today is 09/01/90

DTOS()

Funo para converso de uma data que pode ser usada para criar expresses de
ndice. O resultado estruturado visando manter a ordem correta do ndice (ano, ms,
dia).

E Sintaxe: DTOS( dData )

E Parmetros:


E Retorno:

sData Retorna uma cadeia de caracteres com oito bytes de tamanho no formato
yyyymmdd. Quando dData nulo ou invalido, DTOS() retorna uma cadeia de
caracteres com oito espaos. O valor retornado no afetado pela formato da
data corrente.

Exemplo:

cData := DATE() // Resultado: 09/01/90
cData := DTOS(DATE()) // Resultado: 19900901
nLen := LEN(DTOS(CTOD(""))) // Resultado: 8

ELAPTIME()

Funo que retorna uma cadeia de caracteres contendo a diferena de tempo no
formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.

E Sintaxe: ElapTime( cHoraInicial , cHoraFinal )

E Parmetros:

cHoraInicial Informe a hora inicial no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os
minutos e ss os segundos.
CHoraFinal Informe a hora final no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os

E Retorno:

Caracter A diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os

Exemplo:

cHoraInicio := TIME() // Resultado: 10:00:00
...
<instrues>
...
cElapsed := ELAPTIME(TIME(), cHoraInicio)

MONTH()

Funo de converso que extrai da data o valor numrico do ms, semelhante a funo
que retorna o nome do ms a partir do valor de dData.

E Sintaxe: MONTH( dData )

E Parmetros:


E Retorno:

Numrico >=0 e <=12 Para uma data vlida.
0 Se a data for nula ou invlida.


Exemplo:

nMes := MONTH(DATE()) // Resultado: 9
nMes := MONTH(DATE()) + 1 // Resultado: 10

SECONDS()

Esta funo retorna o nmero de segundos decorridos desde a meia-noite, segundo a
hora do sistema. Est relacionada funo TIME() que retorna a hora do sistema como
uma cadeia de caracteres no formato hh:mm:ss.

E Sintaxe: SECONDS()

E Parmetros:

Nenhum ()

E Retorno:

Numrico >=0 e <=86399 Retorna a hora do sistema em segundos. O valor numrico
representa o nmero de segundos decorridos desde a meia-noite, baseado no
relgio de 24 horas e varia de 0 a 86399.

Exemplo:

cHora := TIME() // Resultado: 10:00:00
cSegundos := SECONDS() // Resultado: 36000.00

//Este exemplo usa a funo SECONDS() para cronometrar o tempo
decorrido:

LOCAL nStart, nElapsed
nStart:= SECONDS()

TIME()

Funo que retorna a hora do sistema como uma cadeia de caracteres, e que est
relacionada com SECONDS(), que retorna o valor inteiro representando o nmero de
segundos desde a meia-noite. SECONDS() geralmente usada no lugar de TIME() para
clculos.

E Sintaxe: TIME()

E Parmetros:

Nenhum .

E Retorno:

Caracter A hora do sistema como uma cadeia de caracteres no formato hh:mm:ss onde
hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.

Exemplo:

cTime := TIME() // Resultado: 10:37:17
cHora := SUBSTR(cTime, 1, 2) // Resultado: 10
cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37
cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17

YEAR()

YEAR() uma funo de converso de data que extrai o valor numrico do ano. YEAR()
membro de um grupo de funes que retornam valores numricos de uma data. O
grupo inclui DAY() e MONTH() que retornam o dia e o ms como valores numricos.

E Sintaxe: YEAR( dData )

E Parmetros:


E Retorno:

Numrico Valor numrico do ano da data especificada em dData incluindo os dgitos do
sculo. O valor retornado no afetado pelos valores especificados pelos
comandos SET DATE ou SET CENTURY.

Para uma data invlida ou nula ser retornado o valor 0.


Exemplo 01:

dAno := YEAR(dData) // Resultado: 2001
dAno := YEAR(dData) + 11 // Resultado: 2012

Exemplo 02:

// Este exemplo cria uma funo de usurio que usa a funo YEAR()
para formatar o valor da
// data:

cData := Mdy(DATE()) // Result: September 20, 1990
FUNCTION Mdy( dDate )
RETURN CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate))) + "," +
STR(YEAR(dDate))

Manipulao de variveis numricas

ABS()

Retorna um valor absoluto (independente do sinal) com base no valor especificado no
parmetro.

E Sintaxe: ABS(nValor)

E Parmetros

nValor Valor que ser avaliado

Exemplo:

nPessoas := 20
nLugares := 18

IF nPessoas < nLugares
MSGINFO(Existem +CVALTOCHAR(nLugares-
nPessoas)+disponveis)
ELSE
MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares-
nPessoas))+faltando)
ENDIF

ALEATORIO()

Gera um nmero aleatrio de acordo com a semente passada. Esta funo retorna um
nmero aleatrio menor ou igual ao primeiro parmetro informado, usando como
semente o segundo parmetro. recomendado que esta semente seja sempre o ltimo
nmero aleatrio gerado por esta funo.

E Sintaxe: Aleatorio(nMax,nSeed)

E Parmetros

nMax Nmero mximo para a gerao do nmero aleatrio.
nSeed Semente para a gerao do nmero aleatrio.

Exemplo Funo ALEATORIO()

nSeed := 0
For i := 1 to 100
nSeed := Aleatorio(100,nSeed)
? Str(i,3)+ numero aleatorio gerado: +Str(nSeed,3)
Next i
inkey(0)
Return

INT()

Retorna a parte inteira de um valor especificado no parmetro.

E Sintaxe: INT(nValor)

E Parmetros

nValor Valor que ser avaliado.

Exemplo:

STATIC FUNCTION COMPRAR(nQuantidade)

LOCAL nDinheiro := 0.30
LOCAL nPrcUnit := 0.25

IF nDinheiro >= (nQuantidade*nPrcUnit)
RETURN nQuantidade
ELSEIF nDinheiro > nPrcUnit
nQuantidade := INT(nDinheiro / nPrcUnit)
ELSE
nQuantidade := 0
ENDIF

RETURN nQuantidade

NOROUND()

Retorna um valor, truncando a parte decimal do valor especificado no parmetro de
acordo com a quantidade de casas decimais solicitadas.

E Sintaxe: NOROUND(nValor, nCasas)

E Parmetros

nCasas Nmero de casas decimais vlidas. A partir da casa decimal especificada os
valores sero desconsiderados.

Exemplo Funo NOROUND()

nBase := 2.985
nValor := NOROUND(nBase,2) 2.98

RANDOMIZE()

Atravs da funo RANDOMIZE() , geramos um numero inteiro aleatrio,
compreendido entre a faixa inferior e superior recebida atravs dos parmetros
nMinimo e nMaximo, respectivamente.

Observao :

Q O limite inferior recebido atravs do parmetro nMinimo "maior ou igual a ",
podendo ser sorteado e fazer parte do retorno; porm o limite superior
"menor que", de modo a nunca ser atingido ou devolvido no resultado. Por
exemplo , a chamada da funo RANDOMIZE(1,2) sempre retornar 1 .

E Sintaxe: RANDOMIZE ( < nMinimo > , < nMaximo > )

E Parmetros

nMinimo Corresponde ao menor numero a ser gerado pela funo.
nMaximo Corresponde ao maior nmero ( menos um ) a ser gerado pela funo.

E Retorno:

Numrico Nmero randmico , compreendido no intervalo entre (nMinimo) e (nMaximo-1)
: O nmero gerado pode ser maior ou igual nMinimo e menor ou igual a
nMaximo-1 .

ROUND()

Retorna um valor, arredondando a parte decimal do valor especificado no parmetro
de acordo com a quantidades de casas decimais solicitadas, utilizando o critrio
matemtico.

E Sintaxe: ROUND(nValor, nCasas)

E Parmetros

nCasas Nmero de casas decimais vlidas. As demais casas decimais sofrero o
arredondamento matemtico, aonde:

Se nX <= 4 0, seno +1 para a casa decimal superior.

Exemplo:

nBase := 2.985
nValor := ROUND(nBase,2) 2.99

Manipulao de arquivos

ADIR()

Funo que preenche os arrays passados com os dados dos arquivos encontrados,
atravs da mscara informada. Tanto arquivos locais (Remote) como do servidor
podem ser informados.

Importante: ADir uma funo obsoleta, utilize sempre Directory().

E Sintaxe: ADIR([ cArqEspec ], [ aNomeArq ], [ aTamanho ], [ aData ],
[aHora], [ aAtributo ])

E Parmetros:

cArqEspec Caminho dos arquivos a serem includos na busca de informaes. Segue o
padro para especificao de arquivos, aceitando arquivos no servidor Protheus
e no Cliente. Caracteres como * e ? so aceitos normalmente. Caso seja omitido,
sero aceitos todos os arquivos do diretrio default ( *.* ).
aNomeArq Array de Caracteres. o array com os nomes dos arquivos encontrados na
busca.O contedo anterior do array apagado.
aTamanho Array Numrico. So os tamanhos dos arquivos encontrados na busca.
aData Array de Datas. So as datas de modificao dos arquivos encontrados na busca.
aHora Array de Caracteres. So os horrios de modificao dos arquivos encontrados.
Cada elemento contm horrio no formato: hh:mm:ss.
aAtributos Array de Caracteres. So os atributos dos arquivos, caso esse array seja passado
como parmetros, sero includos os arquivos com atributos de sistema e
ocultos.

E Retorno:

nArquivos Quantidade de arquivos encontrados.

Exemplo:

LOCAL aFiles[ADIR("*.TXT")]
ADIR("*.TXT", aFiles)
AEVAL(aFiles, { |element| QOUT(element) })

CGETFILE()

Funo utilizada para seleo de um arquivo ou diretrio, disponibilizando uma
interface grfica e amigvel para o usurio. Esta funo est normalmente associada ao
recurso de abrir ou salvar arquivos, permitindo a digitao opcional do nome do
arquivo que ser gravado.

E Sintaxe: cGetFile ( ExpC1, ExpC2, ExpN1, ExpC3, ExpL1, ExpN2,ExpL2 )

E Parmetros:

ExpC1 Mscara para filtro (Ex: 'Informes Protheus (*.##R) | *.##R').
ExpC2 Titulo da Janela.
ExpN1 Nmero da mascara default ( Ex: 1 p/ *.exe ).
ExpC3 Diretrio inicial se necessrio.
Expl1 .T. para mostrar boto como 'Salvar' e .F. para boto 'Abrir'.
ExpN2 Mscara de bits para escolher as opes de visualizao do Objeto.
ExpL2 .T. para exibir diretrio [Servidor] e .F. para no exibir.

E Mscaras de bits para opes:

GETF_OVERWRITEPROMPT Solicita confirmao para sobrescrever.
GETF_MULTISELECT Permite selecionar mltiplos arquivos.
GETF_NOCHANGEDIR No permite mudar o diretrio inicial.
GETF_LOCALFLOPPY Exibe o(s) Drive(s) de disquete da maquina local.
GETF_LOCALHARD Exibe o(s) HardDisk(s) Local(is).
GETF_NETWORKDRIVE Exibe os drives da rede ( Mapeamentos ).
GETF_SHAREWARE No implementado.
GETF_RETDIRECTORY Retorna um diretrio.

Exemplo:

cGetFile ( '*.PRW|*.CH' , 'Fontes', 1, 'C:\VER507', .F.,
GETF_LOCALHARD + GETF_LOCALFLOPPY)


E Aparncia:

Para permitir a seleo de diversos arquivos contidos em um diretrio
necessrio combinar as funes CGETFILE(), DIRECTORY() e o objeto
LISTBOX() conforme abaixo:

CGETFILE: exibe os diretrios disponveis e retorna o nome do
item selecionado.
DIRECTORY: efetua a leitura dos arquivos contidos no diretrio
retornado pela CGETFILE.
LISTBOX: Exibe uma tela de seleo de com a opo de
marcao, para que sejam selecionados os arquivos que sero
processados.

Exemplo: Seleo de mltiplos arquivos com CGETFILE, DIRECTORY() e LISTBOX()

Funo Principal: SELFILE()


//+----------------------------------------------------------------+
//| Rotina | SELFILE | Autor | ARNALDO R. JUNIOR | Data |
01.01.2007 |
//+----------------------------------------------------------------+
//| Descr. | Funo exemplo para seleo de mltiplos arquivos. |
//+----------------------------------------------------------------+
//| Uso | CURSO DE ADVPL |
//+----------------------------------------------------------------+

USER FUNCTION SELFILE()

LOCAL cDirectory := ""
LOCAL aArquivos := {}
LOCAL nArq := 0

PRIVATE aParamFile:= ARRAY(1)

IF !PARBOXFILE()
RETURN
ENDIF

// Exibe a estrutura de diretrio e permite a seleo dos arquivos
que sero processados
cDirectory := ALLTRIM(cGetFile("Arquivos de
Dados|'"+aParamFile[1]+"'|", 'Importao de lanamentos', 0,'', .T.,
GETF_OVERWRITEPROMPT + GETF_NETWORKDRIVE + GETF_RETDIRECTORY,.T.))
aArquivos := Directory(cDirectory+"*.*")
aArquivos := MARKFILE(aArquivos,cDirectory,aParamFile[1],@lSelecao)

FOR nArq TO Len(aArquivos)

IF !aArquivos[nArq][1]
LOOP
ENDIF

<...processamento...>

NEXT nArq

RETURN
Funo auxiliar: PARBOXFILE()

//+----------------------------------------------------------------+
//| Rotina | PARBOXFILE | Autor | ARNALDO R. JUNIOR Data |
01.01.2007 |
//+----------------------------------------------------------------+
//| Descr. | Funo exemplo de uso da PARAMBOX em conjunto com
CGETFILE|
//+----------------------------------------------------------------+
//+---------------------------------------------------------------+

STATIC FUNCTION PARBOXFILE()

Local cTitulo := "Filtros Adicionais"
Local aRet := {}
Local bOk := {|| .T.}
Local lCentered := .T.
Local nPosx
Local nPosy
Local cLoad := ""
Local lCanSave := .F.
Local lUserSave := .F.
Local nX := 0
Local lRet := .T.

AADD(aParamBox,{2,"Tipo de arquivo"
,2,{"*.dbf","*.dtc"},100,"AllwaysTrue()",.T.})
lRet := ParamBox(aParamBox, cTitulo, aRet, bOk, aButtons, lCentered,
nPosx, nPosy,, cLoad, lCanSave, lUserSave)
IF ValType(aRet) == "A" .AND. Len(aRet) == Len(aParamBox)
For nX := 1 to Len(aParamBox)
If aParamBox[nX][1] == 1
aParam102[nX] := aRet[nX]
"C"
aParam102[nX] := aRet[nX] // Tipo do arquivo
"N"
aParam102[nX] := aParamBox[nX][4][aRet[nX]] // Tipo do
arquivo
Endif
Next nX
ENDIF
RETURN lRet
Funo auxiliar: MARKFILE()

//+----------------------------------------------------------------+
//| Rotina | MARKFILE | Autor | ARNALDO R. JUNIOR | Data |
01.01.2007 |
//+----------------------------------------------------------------+
//| Descr. | Funo exemplo para marcao de mltiplos arquivos. |
//+----------------------------------------------------------------+
//+----------------------------------------------------------------+

STATIC FUNCTION MARKFILE(aArquivos,cDiretorio,cDriver,lSelecao)

Local aChaveArq := {}
Local cTitulo := "Arquivos para importao: "
Local bCondicao := {|| .T.}
// Variveis utilizadas na seleo de categorias
Local oChkQual,lQual,oQual,cVarQ
// Carrega bitmaps
Local oOk := LoadBitmap( GetResources(), "LBOK")
Local oNo := LoadBitmap( GetResources(), "LBNO")
// Variveis utilizadas para lista de filiais
Local nx := 0
Local nAchou := 0

//+----------------------------------------------------------------+
//| Carrega os arquivos do diretrio no array da ListBox |
//+----------------------------------------------------------------+
For nX := 1 to Len(aArquivos)
//+-----------------------------------------------------------+
//| aChaveArq - Contem os arquivos que sero exibidos para
seleo |
//+-----------------------------------------------------------+
AADD(aChaveArq,{.F.,aArquivos[nX][1],cDiretorio})
Next nX

//+---------------------------------------------------------------+
//| Monta tela para seleo dos arquivos contidos no diretrio
|
//+----------------------------------------------------------------+
DEFINE MSDIALOG oDlg TITLE cTitulo STYLE DS_MODALFRAME From 145,0 To
445,628;
OF oMainWnd PIXEL
oDlg:lEscClose := .F.
@ 05,15 TO 125,300 LABEL UPPER(cDriver) OF oDlg PIXEL
@ 15,20 CHECKBOX oChkQual VAR lQual PROMPT "Inverte Seleo" SIZE
50, 10;
OF oDlg PIXEL;
ON CLICK (AEval(aChaveArq, {|z| z[1] := If(z[1]==.T.,.F.,.T.)}),;
oQual:Refresh(.F.))
@ 30,20 LISTBOX oQual VAR cVarQ Fields HEADER
"","Cdigo","Descrio" SIZE;
273,090 ON DBLCLICK
(aChaveArq:=Troca(oQual:nAt,aChaveArq),oQual:Refresh());
NoScroll OF oDlg PIXEL
oQual:SetArray(aChaveArq)
oQual:bLine := { || {If(aChaveArq[oQual:nAt,1],oOk,oNo),;
aChaveArq[oQual:nAt,2],aChaveArq[oQual:nAt,3]}}
DEFINE SBUTTON FROM 134,240 TYPE 1 ACTION IIF(MarcaOk(aChaveArq),;
(lSelecao := .T., oDlg:End(),.T.),.F.) ENABLE OF oDlg
DEFINE SBUTTON FROM 134,270 TYPE 2 ACTION (lSelecao := .F.,
oDlg:End());
ENABLE OF oDlg

RETURN aChaveArq

Funo auxiliar: TROCA()

//+----------------------------------------------------------------+
//| Rotina | TROCA | Autor | ARNALDO R. JUNIOR | Data |
01.01.2007 |
//+----------------------------------------------------------------+
|
//+----------------------------------------------------------------+

STATIC FUNCTION Troca(nIt,aArray)
aArray[nIt,1] := !aArray[nIt,1]
Return aArray

Funo auxiliar: MARCAOK()

//+----------------------------------------------------------------+
//| Rotina | MARCAOK | Autor | ARNALDO R. JUNIOR | Data |
01.01.2007 |
//+----------------------------------------------------------------+
//+----------------------------------------------------------------+

STATIC FUNCTION MarcaOk(aArray)
Local lRet:=.F.
Local nx:=0

// Checa marcaes efetuadas
For nx:=1 To Len(aArray)
If aArray[nx,1]
lRet:=.T.
EndIf
Next nx
// Checa se existe algum item marcado na confirmao
If !lRet
HELP("SELFILE",1,"HELP","SEL. FILE","No existem itens marcados",1,0)
EndIf

Return lRet

CPYS2T()

Funo utilizada para copiar um arquivo do servidor para o cliente (Remote), sendo
que os caracteres * e ? so aceitos normalmente. Caso a compactao seja
habilitada (lCompacta), os dados sero transmitidos de maneira compacta e
descompactados antes do uso.
E Sintaxe: CPYS2T ( < cOrigem > , < cDestino > , [ lCompacta ] )

E Parmetros:

cOrigem Nome(s) dos arquivos a serem copiados, aceita apenas arquivos no servidor,
WildCards ( * e ? ) so aceitos normalmente.
cDestino Diretrio com o destino dos arquivos no Client ( Remote ).
lCompacta Indica se a cpia deve ser feita compactando o arquivo antes do envio.


E Retorno:

Lgico

lSucess retorna .T. caso o arquivo seja copiado com sucesso, ou .F. em caso de
falha na cpia.

Exemplo:
// Copia arquivos do servidor para o remote local, compactando antes
de transmitir
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .T. )
// Copia arquivos do servidor para o remote local, sem compactar
antes de transmitir
CpyS2T( "\BKP\MANUAL.DOC", "C:\TEMP", .F. )

CPYT2S()

Funo utilizada para copiar um arquivo do cliente (Remote) para o servidor, sendo que
os caracteres * e ? so aceitos normalmente. Caso a compactao seja habilitada
(lCompacta), os dados sero transmitidos de maneira compacta e descompactados
antes do uso.
E Sintaxe: CpyT2S( cOrigem, cDestino, [ lCompacta ])

E Parmetros:

cOrigem Nomes dos arquivos a serem copiados, aceita apenas arquivos locais (Cliente),
WildCards so aceitos normalmente.
cDestino Diretrio com o destino dos arquivos no remote ( Cliente ).
lCompacta Indica se a cpia deve ser feita compactando o arquivo antes.

E Retorno:

Lgico Indica se o arquivo foi copiado para o cliente com sucesso.

Exemplo:
// Copia arquivos do cliente( remote ) para o Servidor compactando
antes de transmitir
CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP", .T. )
// Copia arquivos do cliente( remote ) para o Servidor sem
compactar.
CpyT2S( "C:\TEMP\MANUAL.DOC", "\BKP" )

CURDIR()

Funo que retorna o diretrio corrente do servidor. O caminho retornado sempre
relativo ao RootPath definido na configurao do Environment no .INI do Protheus
Server. Inicialmente, o diretrio atual da aplicao o constante na chave StartPath,
tambm definido na configurao do Environment no .INI do Protheus Server.

Caso seja passado o parmetro cNovoPath, este path assumido como sendo o pacote
atual. Caso o path recebido como parmetro no exista, seja invlido, ou seja um
pacote absoluto (iniciado com uma letra de drive ou caminho de rede), a funo no ir
setar o novo pacote, mantendo o atual.

E Sintaxe: CURDIR ( [ cNovoPath ] )

E Parmetros:

cNovoPath Caminho relativo, com o novo diretrio que ser ajustado como corrente.

E Retorno:

Caracter Diretrio corrente, sem a primeira barra.

Exemplo:

cOldDir := curdir()
cNewDir := '\webadv\xis'
curdir(cNewDir) // Troca o path
If cNewDir <> '\'+curdir() // E verifica se trocou mesmo
conout('Falha ao Trocar de Path de '+cOldDir + ' para '+cNewDir)
Else
conout('Path de '+cOldDir + ' trocado para '+cNewDir+' com
sucesso.')
Endif

DIRECTORY()

Funo de tratamento de ambiente que retorna informaes a respeito dos arquivos no
diretrio corrente ou especificado. semelhante a ADIR(), porm retorna um nico
vetor ao invs de adicionar valores a uma srie de vetores existentes passados por
referncia.

DIRECTORY() pode ser utilizada para realizar operaes em conjuntos de arquivos. Em
combinao com AEVAL(), voc pode definir um bloco que pode ser aplicado a todos
os arquivos que atendam a <cDirSpec> especificada.

Para tornar as referncias aos vrios elementos de cada sub-vetor de arquivo mais
legveis, fornecido o arquivo header Directry.ch, que contm os #defines para os
subarray subscripts.

E TABELA A: Atributos de DIRECTORY()

Atributo Significado
H Incluir arquivos ocultos
S Incluir arquivos de sistema
D Incluir diretrios
V Procura pelo volume DOS e exclui outros arquivos

Nota: Arquivos normais so sempre includos na pesquisa, a no ser que V seja
especificado.
E TABELA B: Estrutura dos Subvetores de DIRECTORY()

Posio Metasmbolo Directry.ch
1 cNome F_NAME
2 cTamanho F_SIZE
3 dData F_DATE
4 cHora F_TIME
5 cAtributos F_ATT

E Sintaxe: DIRECTORY ( < cDirSpec > , [ ] )

E Parmetros:

cDirSpec

<cDirSpec> especifica o driver, diretrio e arquivo para a pesquisa no diretrio.
Caracteres do tipo coringa so permitidos na especificao de arquivos. Caso
<cDirSpec> seja omitido, o valor padro *.*.
O caminho especificado pode estar na estao (remote), ou no servidor,
obedecendo s definies de Path Absoluto/Relativo de acesso.
cAtributos> <cAtributos> especifica que arquivos com atributos especiais devem ser
includos na informao retornada. <cAtributos> consiste em uma cadeia de
caracteres que contm um ou mais dos seguintes caracteres, contidos na tabela
adicional A , especificada anteriormente.

E Retorno:

Array

DIRECTORY() retorna um vetor de sub-vetores, sendo que cada sub-vetor
contm informaes sobre cada arquivo que atenda a <cDirSpec>.Veja maiores
detalhes na Tabela B, discriminada anteriormente.

Exemplo:
#INCLUDE "Directry.ch"

aDirectory := DIRECTORY("*.*","D")
AEVAL( aDirectory, {|aFile| CONOUT(aFile[F_NAME])} )

DIRREMOVE()

Funo que elimina um diretrio especifico. Caso especifiquemos um pacote sem a
unidade de disco , ele ser considerado no ambiente do Servidor , a partir do RootPath
do ambiente ( caso o path comece com \ ), ou a partir do diretrio corrente (caso o
path no seja iniciado com \ ).

Quando especificado um pacote(path) absoluto ( com unidade de disco preenchida ), a
funo ser executada na estao onde est sendo executado o Protheus Remote.
Quando executamos a funo DirRemove() em JOB ( processo isolado no Server, sem
interface ), no possvel especificar um Path absoluto de disco. Caso isto seja
realizado, a funo retornar .F. e FError() retornar -1 ( Syntax Error ).

Note que necessrio ter direitos suficientes para remover um diretrio, e o diretrio a
ser eliminado precisa estar vazio, sem subdiretrios ou arquivos dentro do mesmo.

E Sintaxe: DIRREMOVE ( < cDiretorio > )

E Parmetros:

cDiretorio Nome do diretrio a ser removido.

E Retorno:

Lgico lSucesso ser .T. caso o diretrio tenha sido eliminado, ou .F. caso no seja
possvel excluir o diretrio. Quando a funo DirRemove retornar .F., possvel
obter mais detalhes da ocorrncia recuperando o cdigo do Erro atravs da
funo FError().

Exemplo:
cDelPath := 'c:\TmpFiles'
lRemoveOk := DIRREMOVE(cDelPath)

IF !lRemoveOk
MsgStop('Falha ao remover a pasta '+cDelPath+' ( File Error
'+str(Fewrror(),4)+' ) ')
Else
MsgStop('Pasta '+cDelPath+' removida com sucesso.')
Endif


DISKSPACE()

Funo de ambiente que determina quantos bytes esto disponveis em uma
determinada unidade de disco. Esta funo obtm a informao sempre relativa
estao onde est sendo executado o Protheus Remote. Atravs do parmetro nDrive ,
selecionamos qual a unidade de disco que desejamos obter a informao do espao
livre, onde:

0 : Unidade de disco atual da estao (DEFAULT).
1 : Drive A: da estao remota.
2 : Drive B: da estao remota.
3 : Drive C: da estao remota.
4 : Drive D: da estao remota ... e assim por diante.

Caso a funo DiskSpace seja executada atravs de um Job (processo isolado no
Servidor, sem interface Remota) , ou seja passado um argumento de unidade de disco
inexistente ou indisponvel, a funo DISKSPACE() retornar -1

E Sintaxe: DISKSPACE ( [ nDrive ] )

E Parmetros:

nDrive Nmero do driver, onde 0 o espao na unidade de disco corrente, e 1 o drive
A: do cliente, 2 o drive B: do cliente, etc..

E Retorno:

Numrico Nmero de bytes disponveis no disco informado como parmetro.

Exemplo:

nBytesLocal := DISKSPACE( ) // Retorna o espao disponvel na
unidade de disco local

IF nBytesLocal < 1048576
MsgStop('Unidade de Disco local possui menos de 1 MB livre.')
Else
MsgStop('Unidade de disco local possui '+str(nBytes_A,12)+' bytes
livres.')
Endif
nBytes_A := DISKSPACE( 1 ) // Retorna o espao disponvel no drive
A: local ( remote ).

If nBytes_A == -1
MsgStop('Unidade A: no est disponvel ou no h disco no
Drive')
ElseIf nBytes_A < 8192
MsgStop('No h espao disponvel no disco. Substitua o disco na
Unidade A:')
Else
MsgStop('Unidade A: Verificada . '+str(nBytes_A,12)+' bytes
livres.')
Endif

EXISTDIR()

Funo utilizada para determinar se um pacote de diretrio existe e valido.

E Sintaxe: EXISTDIR (< cPath >)

E Parmetros:

cPath String contendo o diretrio que ser verificado, caso seja feita uma verificao a
partir do server, devemos informar a partir do rootPath do Protheus, caso
contrrio devemos passar o pacote completo do diretrio.

E Retorno:

Lgico Retorna se verdadeiro(.T.) caso o diretrio solicitado exista, falso(.F.) caso
contrrio.

Exemplo 01: No server a partir do rootPath

lRet := ExistDir('\teste')

Exemplo 02: No client, passando o FullPath

lRet := ExistDir('c:\APO')

FCLOSE()

Funo de tratamento de arquivos de baixo nvel utilizada para fechar arquivos binrios
e forar que os respectivos buffers do DOS sejam escritos no disco. Caso a operao
falhe, FCLOSE() retorna falso (.F.). FERROR() pode ento ser usado para determinar a
razo exata da falha. Por exemplo, ao tentar-se usar FCLOSE() com um handle
(tratamento dado ao arquivo pelo sistema operacional) invlido retorna falso (.F.) e
FERROR() retorna erro 6 do DOS, invalid handle. Consulte FERROR() para obter uma
lista completa dos cdigos de erro.

Nota: Esta funo permite acesso de baixo nvel aos arquivos e dispositivos do DOS.
Ela deve ser utilizada com extremo cuidado e exige que se conhea a fundo o sistema
operacional utilizado.

E Sintaxe: FCLOSE ( < nHandle > )

E Parmetros:

nHandle Handle do arquivo obtido previamente atravs de FOPEN() ou FCREATE().

E Retorno:

Lgico Retorna falso (.F.) se ocorre um erro enquanto os buffers esto sendo escritos;
do contrrio, retorna verdadeiro (.T.).

Exemplo:

#include "Fileio.ch"

nHandle := FCREATE("Testfile", FC_NORMAL)

If !FCLOSE(nHandle)
conout( "Erro ao fechar arquivo, erro numero: ", FERROR() )
EndIf

FCREATE()

Funo de baixo-nvel que permite a manipulao direta dos arquivos textos como
binrios. Ao ser executada FCREATE() cria um arquivo ou elimina o seu contedo, e
retorna o handle (manipulador) do arquivo, para ser usado nas demais funes de
manuteno de arquivo. Aps ser utilizado , o Arquivo deve ser fechado atravs da
funo FCLOSE().

Na tabela abaixo , esto descritos os atributos para criao do arquivo, definidos no
arquivo header fileio.ch.

E Atributos definidos no include FileIO.ch

Constante Valor Descrio
FC_NORMAL 0 Criao normal do Arquivo (default/padro).
FC_READONLY 1 Cria o arquivo protegido para gravao.
FC_HIDDEN 2 Cria o arquivo como oculto.
FC_SYSTEM 4 Cria o arquivo como sistema.

Caso desejemos especificar mais de um atributo, basta som-los. Por exemplo , para
criar um arquivo protegido contra gravao e escondido, passamos como atributo
FC_READONLY + FC_HIDDEN. .

Nota: Caso o arquivo j exista, o contedo do mesmo ser ELIMINADO, e seu tamanho
ser truncado para 0 ( ZERO ) bytes.

E Sintaxe: FCREATE ( < cArquivo > , [ nAtributo ] )

E Parmetros:

cArquivo Nome do arquivo a ser criado, podendo ser especificado um pacote absoluto ou
relativo, para criar arquivos no ambiente local (Remote) ou no Servidor,
respectivamente.
nAtributo Atributos do arquivo a ser criado (Vide Tabela de atributos abaixo). Caso no
especificado, o DEFAULT FC_NORMAL.

E Retorno:

Numrico

A funo retornar o Handle do arquivo para ser usado nas demais funes de
manuteno de arquivo. O Handle ser maior ou igual a zero. Caso no seja
possvel criar o arquivo, a funo retornar o handle -1, e ser possvel obter
maiores detalhes da ocorrncia atravs da funo FERROR().

FERASE()

Funo utilizada para apagar um arquivo no disco. O Arquivo pode estar no Servidor
ou na estao local (Remote). O arquivo para ser apagado deve estar fechado, no
sendo permitido a utilizao de caracteres coringa (wildcards).

E Sintaxe: FERASE ( < cArquivo > )

E Parmetros:

cArquivo Nome do arquivo a ser apagado . Pode ser especificado um path absoluto ou
relativo , para apagar arquivos na estao local (Remote) ou no Servidor,
respectivamente.

E Retorno:

Numrico A funo retornar 0 caso o arquivo seja apagado com sucesso, e -1 caso no
seja possvel apagar o arquivo. Caso a funo retorne -1, possvel obter
maiores detalhes da ocorrncia atravs da funo FERROR().

E
xemplo:

#include 'DIRECTRY.CH'

aEval(Directory("*.BAK"), { |aFile| FERASE(aFile[F_NAME]) })

// Este exemplo apaga um arquivo no cliente ( Remote ) , informando
o status da operao
IF FERASE("C:\ListaTXT.tmp") == -1
MsgStop('Falha na deleo do Arquivo ( FError'+str(ferror(),4)+
')')
Else
MsgStop('Arquivo deletado com sucesso.')
ENDIF

FILE()

Funo que verifica se existe um arquivo ou um padro de arquivos, no diretrio.
Podem ser especificados caminhos absolutos (arquivos na estao - Remote) ou
relativos (a partir do RootPath do Protheus Server), sendo os caracteres * e ?
(wildcards) aceitos.

E Sintaxe: FILE ( < cArquivo > )

E Parmetros:

cArquivo Nome do arquivo, podendo ser especificado um pacote (caminho) . Caminhos
locais (Remote) ou caminhos de servidor so aceitos, bem como wildcards
(Caracteres * e ? ).

E Retorno:

Lgico O retorno ser .T. caso o arquivo especificado exista. Caso o mesmo no exista
no path especificado, a funo retorna .F.

Exemplo:

//Verifica no diretrio corrente do servidor se existe o arquivo
teste.dbf
FILE("teste.dbf")

// Verifica no diretrio Sigaadv do servidor se existe o arquivo
teste.dbf
FILE("\SIGAADV\TESTE.dbf")

// Verifica no diretrio Temp do cliente (Remote) se existe o
arquivo teste.dbf
FILE("C:\TEMP\TESTE.dbf")

Caso a funo FILE() seja executada em Job ( programa sem interface
remota ), sendo passado um caminho absoluto de arquivo (exemplo
c:\teste.txt) , a funo retornar .F. e FERROR() retornar -1 ).

FILENOEXT()

Funo que retorna o nome de um arquivo contido em uma string, ignorando a
extenso.

E Sintaxe: FileNoExt( cString )

E Parmetros

cString String contendo o nome do arquivo.

Exemplo:

Local cString := '\SIGAADV\ARQZZZ.DBF'
cString := FileNoExt( cString )
// Retorno \SIGAADV\ARQZZZ

FOPEN()

Funo de tratamento de arquivo de baixo nvel que abre um arquivo binrio existente
para que este possa ser lido e escrito, dependendo do argumento <nModo>. Toda vez
que houver um erro na abertura do arquivo, FERROR() pode ser usado para retornar o
cdigo de erro do Sistema Operacional. Por exemplo, caso o arquivo no exista,
FOPEN() retorna -1 e FERROR() retorna 2 para indicar que o arquivo no foi
encontrado. Veja FERROR() para uma lista completa dos cdigos de erro.

Caso o arquivo especificado seja aberto, o valor retornado o handle (manipulador) do
Sistema Operacional para o arquivo. Este valor semelhante a um alias no sistema de
banco de dados, e ele exigido para identificar o arquivo aberto para as outras funes
de tratamento de arquivo. Portanto, importante sempre atribuir o valor que foi
retornado a uma varivel para uso posterior, como mostra o exemplo desta funo.

Nota: Esta funo permite acesso de baixo nvel a arquivos e dispositivos. Ela deve ser
utilizada com extremo cuidado e exige que se conhea a fundo o sistema operacional
utilizado.

FOPEN procura o arquivo no diretrio corrente e nos diretrios
configurados na varivel de pesquisa do Sistema Operacional,
a no ser que um path seja declarado explicitamente como
parte do argumento <cArq>.
Por serem executadas em um ambiente cliente-servidor, as
funes de tratamento de arquivos podem trabalhar em
arquivos localizados no cliente (estao) ou no servidor. O
ADVPL identifica o local onde o arquivo ser manipulado
atravs da existncia ou no da letra do drive no nome do
arquivo passado em <cArq>. Ou seja, se o arquivo for
especificado com a letra do driver, ser aberto na estao. Caso
contrrio, ser aberto no servidor com o diretrio configurado
como rootpath sendo o diretrio raiz para localizao do
arquivo.

E Sintaxe: FOPEN ( < cArq > , [ nModo ] )

E Parmetros:

cArq Nome do arquivo a ser aberto que inclui o pacote, caso haja um.
nModo Modo de acesso DOS solicitado que indica como o arquivo aberto deve ser
acessado. O acesso de uma das categorias relacionadas na tabela A e as
restries de compartilhamento relacionada na Tabela B. O modo padro zero,
somente para leitura, com compartilhamento por Compatibilidade. Ao
definirmos o modo de acesso, devemos somar um elemento da Tabela A com
um elemento da Tabela B.

E Retorno:

Numrico FOPEN() retorna o handle de arquivo aberto na faixa de zero a 65.535. Caso
ocorra um erro, FOPEN() retorna -1.

Exemplo:

#include 'fileio.ch'
...
nH := fopen('\sigaadv\error.log' , FO_READWRITE + FO_SHARED )
If nH == -1
MsgStop('Erro de abertura : FERROR '+str(ferror(),4))
Else
MsgStop('Arquivo aberto com sucesso.')
...
fclose(nH)
Endif
...

E Tabela A: Modos de acesso a arquivos binrios

Modo Constate(fileio.ch) Operao
0 FO_READ Aberto para leitura (padro assumido)
1 FO_WRITE Aberto para gravao
2 FO_READWRITE Aberto para leitura e gravao

E Tabela B: Modos de acesso de compartilhamento a arquivos binrios

Modo Constate(fileio.ch) Operao
0 FO_COMPAT Modo de Compatibilidade (Default).
16 FO_EXCLUSIVE Acesso total exclusivo.
32 FO_DENYWRITE Acesso bloqueando a gravao de outros
processos ao arquivo.
48 FO_DENYREAD Acesso bloqueando a leitura de outros
processos ao arquivo.
64 FO_DENYNONE Acesso compartilhado. Permite a leitura e
gravao por outros.

FREAD()

Funo que realiza a leitura dos dados a partir um arquivo aberto, atravs de FOPEN(),
FCREATE() e/ou FOPENPORT(), e armazena os dados lidos por referncia no buffer
informado.
FREAD() ler at o nmero de bytes informado em nQtdBytes; caso acontea algum
erro ou o arquivo chegue ao final, FREAD() retornar um nmero menor que o
especificado em nQtdBytes. FREAD() l normalmente caracteres de controle (ASC 128,
ASC 0, etc.) e l a partir da posio atual do ponteiro atual do arquivo, que pode ser
ajustado ou modificado pelas funes FSEEK() , FWRITE() ou FREADSTR().

A varivel String a ser utilizada como buffer de leitura deve ser sempre pr-alocado e
passado como referncia. Caso contrrio, os dados no podero ser retornados.

E Sintaxe: FREAD ( < nHandle > , < cBuffer > , < nQtdBytes > )

E Parmetros:

nHandle o manipulador (Handle) retornado pelas funes FOPEN(),
FCREATE(), FOPENPORT(), que faz referncia ao arquivo a ser lido.
cBuffer o nome de uma varivel do tipo String, a ser utilizada como buffer de leitura,
onde os dados lidos devero ser armazenados. O tamanho desta varivel deve
ser maior ou igual ao tamanho informado em nQtdBytes.
Esta varivel deve ser sempre passada por referncia. (@ antes do nome da
varivel), caso contrrio os dados lidos no sero retornados.
nQtdBytes Define a quantidade de Bytes que devem ser lidas do arquivo a partir
posicionamento do ponteiro atual.

E Retorno:

Numrico Quantidades de bytes lidos. Caso a quantidade seja menor que a solicitada, isto
indica erro de leitura ou final de arquivo, Verifique a funo FERROR() para
maiores detalhes.

FREADSTR ()

Funo que realiza a leitura de caracteres de um arquivo binrio. FREADSTR() l de um
arquivo aberto, atravs de FOPEN(), FCREATE(), FOPENPORT(). FREADSTR() ler at o
nmero de bytes informado em nQtdBytes ou at encontrar um CHR(0). Caso acontea
algum erro ou o arquivo chegue ao final, FREADSTR() retornar uma string menor do
que nQdBytes e colocar o erro em FERROR(). FREADSTR() l a partir da posio atual
do ponteiro, que pode ser ajustado pelo FSEEK(), FWRITE( ) ou FREAD().

E Sintaxe: FREADSTR ( < nHandle > , < nQtdBytes > )

E Parmetros:

nHandle o manipulador retornado pelas funes FOPEN(),
FCREATE(), FOPENPORT().
nQtdBytes Nmero mximo de bytes que devem ser lidos.

E Retorno:

Caracter Retorna uma string contendo os caracteres
lidos.

FRENAME()

Atravs da funo FRENAME() possvel renomear um arquivo para outro nome, tanto
no servidor como na estao. Ao renomear um arquivo no esquea que esta arquivo
dever
estar fechado (isto , no pode estar em uso por nenhum outro processo ou estao).
Caso o arquivo esteja aberto por outro processo, a operao de renomear o arquivo
no possvel. A funo fRename() no aceita wildcards ( * e/ou ? ).

Vale lembrar que no possvel renomear um arquivo especificando nos parmetros
simultaneamente um caminho de servidor e um de estao remota, bem como
especificar dois arquivos remotos e executar a funo fRename() atravs de um JOB.
Caso isto ocorra, a funo retornar -1 , e fError() retornar tambm -1.


Quando especificamos um path diferente nos arquivos de origem e
destino , a funo fRename() realiza a funcionalidade de MOVER o
arquivo para o Path especificado.

E Sintaxe: FRENAME ( < cOldFile > , < cNewFile > )

E Parmetros:

cOldFile Nome do arquivo ser renomeado, aceita caminhos do servidor e caminhos do
cliente. Caso no seja especificado nenhuma unidade de disco e pacote,
considerado o pacote atual no servidor.
cNewFile Novo nome do arquivo, aceita tambm caminho do servidor, e caminho do
cliente.

E Retorno:

Numrico Se o status retornado for -1 , ocorreu algum erro na mudana de nome:
Verifique se os dois caminhos esto no mesmo ambiente, verifique a existncia
do arquivo de origem, se ele no est em uso no momento por outro processo,
e verifique se o nome do arquivo de destino j no existe no pacote de destino
especificado.

FSEEK()

Funo que posiciona o ponteiro do arquivo para as prximas operaes de leitura ou
gravao. As movimentaes de ponteiros so relativas nOrigem que pode ter os
seguintes valores, definidos em fileio.ch:

E Tabela A: Origem a ser considerada para a movimentao do ponteiro de
posicionamento do Arquivo.

Origem Constate(fileio.ch) Operao
0 FS_SET Ajusta a partir do inicio do arquivo. (Default)
1 FS_RELATIVE Ajuste relativo a posio atual do arquivo.
2 FS_END Ajuste a partir do final do arquivo.

E Sintaxe: FSEEK ( < nHandle > , [ nOffSet ] , [ nOrigem ] )

E Parmetros:

nHandle Manipulador obtido atravs das funes FCREATE,FOPEN.
nOffSet nOffSet corresponde ao nmero de bytes no ponteiro de posicionamento do
arquivo a ser movido. Pode ser um nmero positivo, zero ou negativo, a ser
considerado a partir do parmetro passado em nOrigem.
nOrigem Indica a partir de qual posio do arquivo, o nOffset ser considerado.

E Retorno:

Numrico FSEEK() retorna a nova posio do ponteiro de arquivo com relao ao incio do
arquivo (posio 0) na forma de um valor numrico inteiro. Este valor no leva
em conta a posio original do ponteiro de arquivos antes da execuo da
funo FSEEK().

FT_FEOF()

Funo que retorna verdadeiro (.t.) se o arquivo texto aberto pela funo FT_FUSE()
estiver posicionado no final do arquivo, similar funo EOF() utilizada para arquivos
de dados.

E Sintaxe: FT_FEOF( )

E Parmetros:

Nenhum ()

E Retorno:

Lgico Retorna true caso o ponteiro do arquivo tenha chegado ao final, false caso
contrrio.

FT_FGOTO()

Funo utilizada para mover o ponteiro, que indica a leitura do arquivo texto, para a
posio absoluta especificada pelo argumento <nPos>.


E Parmetros:

nPos Indica a posio em que ser colocado o ponteiro para leitura dos dados no
arquivo.

E Retorno:

Nenhum ()

FT_FGOTOP()

A funo tem como objetivo mover o ponteiro, que indica a leitura do arquivo texto,
para a posio absoluta especificada pelo argumento <nPos>.


E Parmetros:

arquivo.

E Retorno:

Nenhum ()

FT_FLASTREC()

Funo que retorna o nmero total de linhas do arquivo texto aberto pela FT_FUse. As
linhas so delimitadas pela seqncia de caracteres CRLF o LF.

Verifique maiores informaes sobre formato do arquivo e
tamanho mximo da linha de texto na funo FT_FREADLN().

E Sintaxe: FT_FLASTREC( )

E Parmetros:

Nenhum ()

E Retorno:

Numrico Retorna a quantidade de linhas existentes no arquivo. Caso o arquivo esteja
vazio, ou no exista arquivo aberto, a funo retornar 0 (zero).

Exemplo:

FT_FUse('teste.txt') // Abre o arquivo
CONOUT("Linhas no arquivo ["+str(ft_flastrec(),6)+"]")
FT_FGOTOP()
While !FT_FEof()
conout("Ponteiro ["+str(FT_FRECNO(),6)+"] Linha
["+FT_FReadln()+"]")
FT_FSkip()
Enddo
FT_FUse() // Fecha o arquivo

FT_FREADLN()

Funo que retorna uma linha de texto do arquivo aberto pela FT_FUse. As linhas so
delimitadas pela seqncia de caracteres CRLF ( chr(13) + chr(10) ) , ou apenas LF (
chr(10 ), e o tamanho mximo de cada linha 1022 bytes.

A utilizao desta funo no altera a posio do ponteiro para
leitura dos dados, o ponteiro do arquivo no movido. A
movimentao do ponteiro realizada atravs da funo
FT_FSKIP().
O limite de 1022 bytes por linha inclui os caracteres
delimitadores de final de linha. Deste modo, quando utilizados
os separadores CRLF, isto nos deixa 1020 bytes de texto, e
utilizando LF, 1021 bytes. A tentativa de leitura de arquivos com
linhas de texto maiores do que os valores especificados acima
resultar na leitura dos 1023 primeiros bytes da linha, e
incorreta identificao das quebras de linha posteriores.
As funes FT_F* foram projetadas para ler arquivos com
contedo texto apenas. A utilizao das mesmas em arquivos
binrios pode gerar comportamentos inesperados na
movimentao do ponteiro de leitura do arquivo, e incorretas
identificaes nos separadores de final de linha.

Release: Quando utilizado um Protheus Server, com build
superior a 7.00.050713P, a funo FT_FREADLN() tambm
capaz de ler arquivos texto / ASCII, que utilizam tambm o
caractere LF ( chr(10) ) como separador de linha.

E Sintaxe: FT_FREADLN( )

E Parmetros:

Nenhum ()

E Retorno:

Caracter Retorna a linha inteira na qual est posicionado o ponteiro para leitura de
dados.

FT_FRECNO()

A funo tem o objetivo de retornar a posio do ponteiro do arquivo texto.
A funo FT_FRecno retorna a posio corrente do ponteiro do arquivo texto aberto
pela FT_FUse.

E Sintaxe: FT_FRECNO ( )

E Parmetros:

Nenhum ()

E Retorno:

Caracter Retorna a posio corrente do ponteiro do arquivo texto.

FT_FSKIP()

Funo que move o ponteiro do arquivo texto aberto pela FT_FUSE() para a prxima
linha, similar ao DBSKIP() usado para arquivos de dados.

E Sintaxe: FT_FSKIP ( [ nLinhas ] )

E Parmetros:

nLinhas nLinhas corresponde ao nmero de linhas do arquivo TXT ref. movimentao do
ponteiro de leitura do arquivo.

E Retorno

Nenhum ()

FT_FUSE()

Funo que abre ou fecha um arquivo texto para uso das funes FT_F*. As funes
FT_F* so usadas para ler arquivos texto, onde as linhas so delimitadas pela seqncia
de caracteres CRLF ou LF (*) e o tamanho mximo de cada linha 1022 bytes. O arquivo
aberto em uma rea de trabalho, similar usada pelas tabelas de dados.

Verifique maiores informaes sobre formato do arquivo e
tamanho mximo da linha de texto na funo FT_FREADLN().

E Sintaxe: FT_FUSE ( [ cTXTFile ] )

E Parmetros:

cTXTFile Corresponde ao nome do arquivo TXT a ser aberto. Caso o nome no seja
passado, e j exista um arquivo aberto. o mesmo fechado.

E Retorno:

Numrico A funo retorna o Handle de controle do arquivo. Em caso de falha de abertura,
a funo retornar -1

FWRITE()

Funo que permite a escrita em todo ou em parte do contedo do buffer, limitando a
quantidade de Bytes atravs do parmetro nQtdBytes. A escrita comea a partir da
posio corrente do ponteiro de arquivos, e a funo FWRITE retornar a quantidade
real de bytes escritos. Atravs das funes FOPEN(), FCREATE(), ou FOPENPORT(),
podemos abrir ou criar um arquivo ou abrir uma porta de comunicao, para o qual
sero gravados ou enviados os dados do buffer informado. Por tratar-se de uma
funo de manipulao de contedo binrio , so suportados na String cBuffer todos
os caracteres da tabela ASCII , inclusive caracteres de controle ( ASC 0 , ASC 12 , ASC
128 , etc.).

Caso acontea alguma falha na gravao, a funo retornar um nmero menor que o
nQtdBytes. Neste caso , a funo FERROR() pode ser utilizada para determinar o erro
especfico ocorrido. A gravao no arquivo realizada a partir da posio atual do
ponteiro, que pode ser ajustado atravs das funes FSEEK(), FREAD() ou FREADSTR().

E Sintaxe: FWRITE ( < nHandle > , < cBuffer > , [ nQtdBytes ] )

E Parmetros:
nHandle o manipulador de arquivo ou device retornado pelas funes FOPEN(),
FCREATE(), ou FOPENPORT().
cBuffer <cBuffer> a cadeia de caracteres a ser escrita no arquivo especificado. O
tamanho desta varivel deve ser maior ou igual ao tamanho informado em
nQtdBytes (caso seja informado o tamanho).
nQtdBytes <nQtdBytes> indica a quantidade de bytes a serem escritos a partir da posio
corrente do ponteiro de arquivos. Caso seja omitido, todo o contedo de
<cBuffer> escrito.

E Retorno:
Numrico FWRITE() retorna a quantidade de bytes escritos na forma de um valor numrico
inteiro. Caso o valor retornado seja igual a <nQtdBytes>, a operao foi bem
sucedida. Caso o valor de retorno seja menor que <nBytes> ou zero, ou o disco
est cheio ou ocorreu outro erro. Neste caso, utilize a funo FERROR() para
obter maiores detalhes da ocorrncia.

Exemplo:

#INCLUDE "FILEIO.CH"
#DEFINE F_BLOCK 1024 // Define o bloco de Bytes a serem lidos /
gravados por vez

User Function TestCopy()
Local cBuffer := SPACE(F_BLOCK)
Local nHOrigem , nHDestino
Local nBytesLidos , nBytesFalta , nTamArquivo
Local nBytesLer , nBytesSalvo
Local lCopiaOk := .T.

// Abre o arquivo de Origem
nHOrigem := FOPEN("ORIGEM.TXT", FO_READ)

// Testa a abertura do Arquivo
If nHOrigem == -1
MsgStop('Erro ao abrir origem. Ferror =
'+str(ferror(),4),'Erro')
Return .F.
Endif

// Determina o tamanho do arquivo de origem
nTamArquivo := Fseek(nHOrigem,0,2)

// Move o ponteiro do arquivo de origem para o inicio do arquivo
Fseek(nHOrigem,0)

// Cria o arquivo de destino
nHDestino := FCREATE("DESTINO.TXT", FC_NORMAL)

// Testa a criao do arquivo de destino
If nHDestino == -1
MsgStop('Erro ao criar destino. Ferror =
'+str(ferror(),4),'Erro')
FCLOSE(nHOrigem) // Fecha o arquivo de Origem
Return .F.
Endif

// Define que a quantidade que falta copiar o prprio tamanho do
Arquivo
nBytesFalta := nTamArquivo

// Enquanto houver dados a serem copiados
While nBytesFalta > 0

// Determina quantidade de dados a serem lidos
nBytesLer := Min(nBytesFalta , F_BLOCK )

// l os dados do Arquivo
nBytesLidos := FREAD(nHOrigem, @cBuffer, nBytesLer )

// Determina se no houve falha na leitura
If nBytesLidos < nBytesLer
MsgStop( "Erro de Leitura da Origem. "+;
Str(nBytesLer,8,2)+" bytes a LER."+;
Str(nBytesLidos,8,2)+" bytes Lidos."+;
"Ferror = "+str(ferror(),4),'Erro')
lCopiaOk := .F.
Exit
Endif

// Salva os dados lidos no arquivo de destino
nBytesSalvo := FWRITE(nHDestino, cBuffer,nBytesLer)

// Determina se no houve falha na gravao
If nBytesSalvo < nBytesLer
MsgStop("Erro de gravao do Destino. "+;
Str(nBytesLer,8,2)+" bytes a SALVAR."+;
Str(nBytesSalvo,8,2)+" bytes
gravados."+;
"Ferror = "+str(ferror(),4),'Erro')
lCopiaOk := .F.
EXIT
Endif

// Elimina do Total do Arquivo a quantidade de bytes copiados
nBytesFalta -= nBytesLer

Enddo

// Fecha os arquivos de origem e destino
FCLOSE(nHOrigem)
FCLOSE(nHDestino)

If lCopiaOk
MsgStop('Cpia de Arquivos finalizada com sucesso. '+;
str(nTamArquivo,12,0)+' bytes
copiados.','Final')
Else
MsgStop( 'Falha na Cpia. Arquivo de Destino incompleto. '+;
'Do total de '+str(nTamArquivo,12,0)+' bytes,
faltaram '+str(nBytesFalta,12,0)+' bytes.','Final')
Endif

Return


MSCOPYFILE()

Funo que executa a cpia binria de um arquivo para o destino especificado.

E Sintaxe: MSCOPYFILE( cArqOrig, cArqDest )

E Parmetros:

cArqOrig Nome do arquivo origem e a extenso.
cArqDest Nome do arquivo destino e a extenso.

E Retorno:

Lgico Se a copia for realizada com sucesso a funo retornar verdadeiro (.T.).

Exemplo:

Local cArqOrig := 'ARQ00001.DBF'
Local cArqDest := 'ARQ00002.XXX'

If MsCopyFile( cArqOrig, cArqDest )
APMsgInfo('Copia realizada com sucesso!')
EndIf

MSCOPYTO()

Funo que realiza a cpia dos registros de uma base de dados para outra, criando o
arquivo destino de acordo com a estrutura da base de dados origem.

E Sintaxe: MSCOPYTO( [cArqOrig], cArqDest )

E Parmetros:

cArqOrig
Nome do arquivo origem e a extenso se o ambiente for Top o parmetro
passar a ser obrigatrio.
cArqDest Nome do arquivo destino e a extenso.

E Retorno:

Lgico Se a cpia for realizada com sucesso a funo retornar verdadeiro (.T.).

Exemplo:

Local cArqDest := 'SX2ZZZ.DBF'
DbSelectArea('SX2')
If MsCopyTo( , cArqDest )
APMsgInfo('Copia realizada com sucesso!')
Else
APMsgInfo('Problemas ao copiar o arquivo SX2!')
EndIf

MSCREATE()

Funo que cria um arquivo (tabela) de acordo com a estrutura informada no
parmetro aStruct. Se o parmetro cDriver no for informado o RDD corrente ser
assumido como padro. Para criao de tabelas no Top Connect necessrio estar
conectado ao banco e o environment do protheus ser TOP.

aStruct: array contendo a estrutura da tabela aonde:
1 - caracter, nome do campo;
2 - caracter, tipo do campo;
3 - numrico, tamanho do campo;
4 - numrico, decimais.

E Sintaxe: MsCreate( cArquivo, aStru ,[cDriver] )

E Parmetros:

cArquivo Nome do arquivo.
aStruct Estrutura do arquivo.
cDriver RDD do arquivo.

E Retorno:

Lgico Indica se a operao foi executada com sucesso.

Exemplo:

Local cTarget := '\sigaadv\'
Local aStrut
aStrut := { { 'Campo', 'C', 40, 0 } }
If MsCreate( cTarget+'ARQ1001', aStrut )
APMsgInfo('Criado com sucesso!')
Else
APMsgInfo('Problemas ao criar o arquivo!')
EndIf


MSERASE()

Funo utilizada para deletar fisicamente o arquivo especificado.

E Sintaxe: MsErase( cArquivo, [cIndice], [cDriver] )

E Parmetros:

cArquivo Nome do arquivo e a extenso.
cIndice Nome do arquivo de ndice e a extenso.
cDriver RDD do arquivo, se no for informado assumir o RDD corrente.

E Retorno:

Lgico Indica se a operao foi executada com sucesso.

Exemplo:

Local cArquivo := 'SX2ZZZ.DBF'
Local cIndice := 'SX2ZZZ'+ OrdBagExt()
If MsErase( cArquivo, cIndice )
APMsgInfo( 'Arquivo deletado com sucesso!' )
Else
APMsgInfo( 'Problemas ao deletar arquivo!' )
EndIf

MSRENAME()

Funo que verifica a existncia do arquivo especificado.

E Sintaxe: MsFile( cArquivo, [cIndice], [cDriver] )

E Parmetros:

cArquivo Nome do arquivo e a extenso.
cIndice Nome do arquivo de ndice e a extenso.
cDriver RDD do arquivo, se no for informado assumir o RDD corrente.

E Retorno:

Lgico Indica se o arquivo especificado existe.

Exemplo:

Local cArquivo := 'SX2ZZZ.DBF'
Local cIndice := 'SX2ZZZ'+ OrdBagExt()
If !MsFile ( cArquivo, cIndice )
APMsgInfo( 'Arquivo no encontrado!' )
EndIf

RETFILENAME()

Funo que retorna o nome de um arquivo contido em uma string, ignorando o
caminho e a extenso.

E Sintaxe: RetFileName( cArquivo )

E Parmetros:

cArquivo String contendo o nome do arquivo

E Retorno:

Caracter Nome do arquivo contido na string cArquivo sem o caminho e a extenso.

Exemplo:

Local cArquivo := '\SIGAADV\ARQZZZ.DBF'
cArquivo := RetFileName( cArquivo )
// retorno ARQZZZ

Manipulao de arquivos e ndices temporrios

CRIATRAB()

Funo que cria um arquivo de trabalho com uma estrutura especificada, sendo que:

Q Caso o parmetro lDbf seja definido como .T., a funo criar um arquivo DBF
com este nome e a estrutura definida em aArray.
Q Caso o parmetro lDbf seja definido como .F., a funo no criar arquivo de
nenhum tipo, apenas fornecer um nome vlido.

E Sintaxe: CriaTrab(aArray,lDbf)

E Parmetros:

aArray Array multidimensional contendo a estrutura de campos da tabela que ser
criada no formato: {Nome, Tipo, Tamanho, Decimal}
lDbf Determina se o arquivo de trabalho deve ser criado ( .T.) ou no (.F. )

E Retorno:

Caracter Nome do Arquivo gerado pela funo.

Exemplo:

// Com lDbf = .F.
cArq := CriaTrab(NIL, .F.)
cIndice := C9_AGREG++IndexKey()
Index on &cIndice To &cArq

// Com lDbf = .T.
aStru := {}
AADD(aStru,{ MARK , C, 1, 0})
AADD(aStru,{ AGLUT , C, 10, 0})
AADD(aStru,{ NUMOP , C, 10, 0})
AADD(aStru,{ PRODUTO, C, 15, 0})
AADD(aStru,{ QUANT , N, 16, 4})
AADD(aStru,{ ENTREGA, D, 8, 0})
AADD(aStru,{ ENTRAJU, D, 8, 0})
AADD(aStru,{ ORDEM , N, 4, 0})
AADD(aStru,{ GERADO , C, 1, 0})
cArqTrab := CriaTrab(aStru, .T.)
USE &cArqTrab ALIAS TRB NEW

Na criao de ndices de trabalho temporrios utilizada a sintaxe:

Q CriaTrab(Nil, .F.)

Manipulao de bases de dados

ALIAS()

Funo de banco de dados utilizada para determinar o alias da rea de trabalho
especificada. Alias o nome atribudo a uma rea de trabalho quando um arquivo de
banco de dados est em uso. O nome real atribuido o nome do arquivo de banco de
dados, ou um nome que foi explicitamente atribudo atravs da clusula ALIAS do
comando USE.

A funo ALIAS() o inverso da funao SELECT() pois retorna o alias atravs do nmero
da rea de trabalho, enquanto SELECT() retorna o nmero da rea de trabalho atravs
do alias.

E Sintaxe: ALIAS ( [ nAreaTrabalho ] )

E Parmetros:

nAreaTrabalho <nAreaTrabalho> o nmero da rea de trabalho a ser verificada.

E Retorno:

Caracter Retorna o alias da rea de trabalho especificada na forma de uma cadeia de
caracteres, em letra maiscula. Caso a <nAreaTrabalho> no seja
especificada, retornado o alias da rea de trabalho corrente. Se no houver
nenhum arquivo de banco de dados em uso na rea de Trabalho
especificada, ALIAS() retorna uma cadeia de caracteres nula ("").

Exemplo:

cAlias := alias()
IF empty(cAlias)
alert('No h Area em uso')
Else
alert(Area em uso atual : '+cAlias)
Endif

BOF() / EOF()

As funes BOF() e EOF() so utilizadas para determinar se o ponteiro de leitura do
arquivo encontra-se no comeo ou no final do mesmo conforme abaixo:

Q BOF() uma funo de tratamento de banco de dados utilizada para testar
uma condio de limite de inicial do arquivo quando o ponteiro de registros
est se movendo para trs em um arquivo de banco de dados.
Q EOF() uma funo de tratamento de banco de dados utilizada para testar
uma condio de limite de final de arquivo quando o ponteiro de registros
est se movendo para frente em um arquivo de banco de dados.

Normalmente utilizada a condio EOF() como parte do argumento <lCondicao> de
uma construao DO WHILE que processa registros sequencialmente em um arquivo de
banco de dados. Neste caso <lCondicao> incluiria um teste para .NOT. EOF(), forando
o lao DO WHILE a terminar quando EOF() retornar verdadeiro (.T.)

E Sintaxe: BOF() / EOF()

E Parmetros:

Nenhum ()

E Retorno:

Lgico Retorna verdadeiro (.T.) quando feita uma tentativa de mover o ponteiro de
registros para alm do primeiro registro lgico em um arquivo de banco de
dados. Do contrrio, ela retorna falso (.F.).
Lgico Retorna verdadeiro (.T.) quando feita uma tentativa de mover o ponteiro de
registros para alm do ltimo registro lgico em um arquivo de banco de dados.
Do contrrio, ela retorna falso (.F.). Caso no haja nenhum arquivo de banco de
dados aberto na rea de trabalho corrente, EOF() retorna falso (.F.). Se o arquivo
de banco de dados corrente no possui registros, EOF() retorna verdadeiro (.T.).

COPY()

O comando COPY TO permite a cpia de todos ou parte dos registros da tabela
atualmente selecionada como rea de trabalho atual, para um novo arquivo. Os
registros considerados para a cpia podem ser limitados pela clusula <escopo>,
atravs de expresses FOR/WHILE, e/ou atravs de um filtro.

Se o filtro para registros deletados ( SET DELETED ) estiver desligado (OFF), registros
deletados ( marcados para deleo ) so copiados para o arquivo de destino,
mantendo este status. Caso contrrio, nenhum registro deletado copiado. Da mesma
maneira, caso exista uma condio de filtro na tabela atual ( SET FILTER ), apenas os
registros que satisfaam a condio de filtro sero copiados.

Os registros so lidos na tabela atual, respeitando a ordem de ndice setada. Caso no
hajam ndices abertos, ou a ordem de navegao nos ndices (SET ORDER ) seja 0
(zero), os registros so lidos em ordem natural ( ordem de RECNO ) .

A tabela de destino dos dados copiados criada, e aberta em modo exclusivo, antes da
operao de cpia efetiva ser iniciada.

E Tabela A : Especificao do formato SDF ( System Data Format )

Elemento do Arquivo Formato
Campos 'C' Caractere
Tamanho fixo, ajustado com espaos em
branco.
Campos 'D' Data Formato aaaammdd ( ano, ms, dia ).
Campos 'L' lgicos T ou F.
Campos 'M' Memo (campo ignorado).
Campos 'N' Numricos Ajustados direita, com espaos em branco.
Delimitador de Campos Nenhum.
Separador de Registros CRLF ( ASCII 13 + ASCII 10 ).
Marca de final de arquivo
(EOF)
Nenhum.


E Tabela B : Especificao do formato delimitado ( DELIMITED / DELIMITED
WITH <cDelimiter> )

Elemento do Arquivo Formato
Campos 'C' Caractere Delimitados, ignorando espaos direita.
Campos 'D' Data Formato aaaammdd ( ano, ms, dia ).
Campos 'L' lgicos T ou F.
Campos 'M' Memo (campo ignorado).
Campos 'N' Numricos sem espaos em branco.
Delimitador de Campos Vrgula.
Separador de Registros CRLF ( ASCII 13 + ASCII 10 ).
Marca de final de arquivo
(EOF)
Nenhum.

A Linguagem Advpl, antes do Protheus, suportava a gerao de uma
tabela delimitada diferenciada, obtida atravs do comando COPY TO
(...) DELIMITED WITH BLANK . No Protheus este formato no
suportado. Caso utilize-se deste comando com a sintaxe acima, o
arquivo ASCII gerado ser delimitado, utilizando-se a sequncia de
caracteres 'BLANK' como delimitadora de campos Caractere.

E Sintaxe:

COPY [ FIELDS <campo,...> ] TO cFile [cEscopo] [ WHILE <lCondicao> ]
[ FOR <lCondicao> ] [ SDF | DELIMITED [WITH <cDelimiter>] ]
[ VIA <cDriver> ]

E Parmetros:

FIELDS <campo,...> FIELDS <campo,...> especifica um ou mais campos, separados por
vrgula, a serem copiados para a tabela de destino. Caso no
especificado este parmetro, sero copiados todos os campos da
tabela de origem.
TO cFile TO <cFile> especifica o nome do arquivo de destino. O nome do
arquivo de destino pode ser especificado de forma literal direta, ou
como uma expresso Advpl, entre parnteses.

Caso sejam especificadas as clusulas SDF ou DELIMITED, gerado
um arquivo ASCII, com extenso .txt por default.
cEscopo <cEscopo> define a poro de dados da tabela atual a ser coipiada.
Por default, so copiados todos os registros (ALL). Os escopos
possveis de uso so:

ALL - Copia todos os registros.
REST - Copia, a partir do registro atualmente posicionado, at o final
da tabela.
NEXT <n> - Copia apenas <n> registros, iniciando a partir do
registro atualmente posicionado.

OBSERVAO : Vale a pena lembrar que o escopo sensvel tambm
s demais condies de filtro ( WHILE / FOR ).
WHILE <lCondicao> WHILE <lCondicao> permite especificar uma condio para
realizao da cpia, a partir do registro atual, executada antes de
inserir cada registro na tabela de destino, sendo realizada a operao
de cpia enquanto esta condio for verdadeira.
FOR <lCondicao> FOR <lCondicao> especifica uma condio para cpia de registros,
executada antes de inserir um registro na tabela de destino, sendo a
operao realizada apenas se lCondicao for verdadeira ( .T. )
[SDF|DELIMITED] [ SDF | DELIMITED [WITH <xcDelimiter>] ]

SDF especifica que o tipo de arquivo de destino gerado um arquivo
no formato "System Data Format" ASCII, onde registros e campos
possuirem tamanho fixo no arquivo de destino.

DELIMITED especifica que o arquivo ASCII de destino ser no formato
delimitado, onde os campos do tipo Caractere so delimitados entre
aspas duplas ( delimitador Default ). Registros e campos tm
tamanho varivel no arquivo ASCII.

DELIMITED WITH <xcDelimiter> permite especificar um novo
caractere, ou sequncia de caracteres, a ser utilizada como
delimitador, ao invs do default ( aspas duplas ). O caractere
delimitador pode ser escrito de forma literal, ou como uma
expresso entre parnteses.

Nas Tabelas complementares A e B, na documentao do comando,
so detalhadas as especificaes dos formatos SDF e DELIMITED.
VIA <cDriver> VIA <xcDriver> permite especificar o driver utilizado para criar a
tabela de destino dos dados a serem copiados.

O Driver deve ser especificado como uma expresso caractere. Caso
especificado como um valor literal direto, o mesmo deve estar entre
aspas.


E Retorno:

Nenhum ()

COPY STRUCTURE()

O comando COPY STRUCTURE cria uma nova tabela vazia, com a estrutura da tabela
ativa na rea de trabalho atual. Caso a tabela a ser criada j exista, a mesma
sobrescrita. A tabela de destino criada utiliza o mesmo RDD da tabela de origem (
tabela ativa na rea de trabalho atual ).

A Linguagem Advpl, antes do Protheus, suportava a parametrizao de
uma lista de campos da tabela atual, para compor a estrutura da tabela
de destino, atravs da clusula FIELDS <campo,...>. Esta opo no
suportada no Protheus. Caso seja utilizada, o programa ser abortado
com a ocorrncia de erro fatal : 'DBCopyStruct - Parameter <Fields>
not supported in Protheus'

E Sintaxe:

COPY STRUCTURE TO <xcDataBase>

E Parmetros:

TO <xcDataBase> Deve ser especificado em xcDatabase o nome da tabela a ser criada.

E Retorno:

Nenhum ()

DBAPPEND()

A funo DBAPPEND() acrescenta mais um registro em branco no final da tabela
corrente. Se no houver erro da RDD, o registro acrescentado e bloqueado.

E Sintaxe: DBAPPEND ( [ lLiberaBloqueios ] )

E Parmetros:

lLiberaBloqueios Se o valor for .T., libera todos os registros bloqueados anteriormente (locks).
Se for .F., todos os bloqueios anteriores so mantidos. Valor default: .T.

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
FOR i:=1 to 5
DBAPPEND(.F.)
NOME := "XXX"
END : ="YYY"
NEXT
// Os 5 registros includos permanecem bloqueados
DBAPPEND()
// Todos os bloqueios anteriores so liberados

DBCLEARALLFILTER()

A funo DBCLEARALLFILTER() salva as atualizaes realizadas e pendentes de todas as
tabelas e depois limpa as condies de filtro de todas as tabelas.

E Sintaxe: DBCLEARALLFILTER()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
DBSETFILTER( {|| Idade < 40}, 'Idade < 40') // Seta a expresso de
filtro
...
DBCLEARALLFILTER()
// Limpa a expresso de filtro de todas as ordens

DBCLEARFILTER()

A funo DBCLEARFILTER() salva as atualizaes realizadas e pendentes na tabela
corrente e depois limpa todas as condies de filtro da ordem ativa no momento. Seu
funcionamento oposto ao comando SET FILTER.

E Sintaxe: DBCLEARFILTER()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
DBSETFILTER( {|| Idade < 40}, "Idade < 40" ) // Seta a expresso de
filtro
...
DBCLEARFILTER()
// Limpa a expresso de filtro

DBCLEARINDEX()

A funo DBCLEARINDEX() salva as atualizaes pendentes na tabela corrente e fecha
todos os arquivos de ndice da rea de trabalho. Por conseqncia, limpa todas as
ordens da lista. Seu funcionamento oposto ao comando SET INDEX.

E Sintaxe: DBCLEARINDEX()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome"
...
DBCLEARINDEX()
// Fecha todos os arquivos de ndices

DBCLOSEALL()

A funo DBCLOSEALL() salva as atualizaes pendentes, libera todos os registros
bloqueados e fecha todas as tabelas abertas (reas de trabalho) como se
chamasse DBCLOSEAREA para cada rea de trabalho.

E Sintaxe: DBCLOSEALL()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

// Este exemplo demonstra como se pode utilizar o DBCLOSEALL para
fechar a rea de trabalho atual.
USE Clientes NEW
DBSETINDEX("Nome") // Abre o arquivo de ndice "Nome"
USE Fornecedores NEW
DBSETINDEX("Idade") // Abre o arquivo de ndice "Idade"
...
DBCLOSEALL() //Fecha todas as reas de trabalho, todos os ndices e
ordens

DBCLOSEAREA()

A funo DBCLOSEAREA() permite que um alias presente na conexo seja fechado, o
que viabiliza seu reuso em outra operao. Este comando tem efeito apenas no alias
ativo na conexo, sendo necessria sua utilizao em conjunto com o comando
DbSelectArea().

E Sintaxe: DBCLOSEAREA()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) +
registros.)
DbCloseArea()

DBCOMMIT()

A funo DBCOMMIT() salva em disco todas as atualizaes pendentes na rea de
trabalho corrente.

E Sintaxe: DBCOMMIT()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
DBGOTO(100)
Nome := "Jose"
DBGOTO(168)
Nome := "Joao"
DBCOMMIT() // Salva em disco apenas as alteraes realizadas na
tabela Fornecedores

DBCOMMITALL()

A funo DBCOMMITALL() salva em disco todas as atualizaes pendentes em todas
as reas de trabalho.

E Sintaxe: DBCOMMITALL()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
DBGOTO(100)
Nome := "Jose"
DBGOTO(168)
Nome := "Joao"
DBCOMMITALL()
// Salva em disco as alteraes realizadas nas tabelas Clientes e
Fornecedores

DBCREATE()

A funo DBCREATE() utilizada para criar um novo arquivo de tabela cujo nome
est especificado atravs do primeiro parmetro (cNome) e estrutura atravs do
segundo (aEstrutura). A estrutura especificada atravs de um array com todos os
campos,
onde cada campo expresso atravs de um array contendo {Nome, Tipo, Tamanho,
Decimais}.

E Sintaxe: DBCREATE ( < cNOME > , < aESTRUTURA > , [ cDRIVER ] )

E Parmetros:

cNOME Nome do arquivo a ser criado. Se contm pasta, ela se localiza abaixo do
"RootPath". Se no, criado por padro no caminho formado por
"RootPath"+"StartPath"
aESTRUTURA Lista com as informaes dos campos para ser criada a tabela.
cDRIVER Nome da RDD a ser utilizado para a criao da tabela. Se for omitido ser
criada com a corrente.

E Retorno:

Nenhum ()

Exemplo:

// Este exemplo mostra como se pode criar novo arquivo atravs da
funo DBCREATE:
LOCAL aEstrutura :={{Cod,N,3,0},
{Nome,C,10,0},
{Idade,N,3,0},
{Nasc,D,8,0},
{Pagto,N,7,2}}
// Cria a tabela com o RDD corrente
DBCREATE('\teste\cliente.dbf', aEstrutura)
USE '\teste\cliente.dbf' VIA 'DBFCDX' NEW

Erros mais comuns:

1. DBCreate - Data base files can only be created on the server: O
nome do arquivo a ser criado no pode conter 'driver', pois, por
conveno, ele seria criado na mquina onde o Remote est
rodando.
2. DBCreate - Invalid empty filename: Nome do arquivo no foi
especificado.
3. DBCreate - Field's name cannot be 'DATA': Algumas RDD's no
suportam este nome de campo. uma palavra reservada.
4. DBCreate - The length of Field's name must be at most 10: Nome
do campo no pode ter mais que 10 caracteres.
5. DBCreate - Field's name must be defined: Nome do campo no
foi definido.
6. DBCreate - Field's type is not defined: Tipo do campo no foi
definido.
7. DBCreate - invalid Field's type: Tipo do campo diferente de 'C',
'N', 'D', 'M' ou 'L'.

8. DBCreate - Invalid numeric field format: Considerando 'len' o
tamanho total do campo numrico e 'dec' o nmero de decimais,
ocorre este erro se:

(len = 1) .and. (dec <> 0): Se o tamanho total 1, o campo no
pode ter decimais.

(len>1) .and. (len< dec + 2): Se o tamanho total maior que 1,
ele deve ser maior que o nmero de decimais mais 2, para
comportar o separador de decimais e ter pelo menos um
algarismo na parte inteira.

Exemplo: O nmero 12.45 poderia ser o valor de um campo
com len=5 e dec=2 (no mnimo).


Erros mais comuns:

Podem ocorrer tambm erros decorrentes de permisso e direitos na
pasta onde se est tentando criar o arquivo ou por algum problema
no banco de dados. Verifique as mensagens do servidor Protheus e
do banco de dados.

DBCREATEINDEX()

A funo DBCREATEINDEX() utilizada para criar um novo arquivo de ndice com o
nome
especificado atravs do primeiro parmetro, sendo que, se o mesmo existir, deletado
e criado o novo. Para tanto so executados os passos a seguir:

Q Salva fisicamente as alteraes ocorridas na tabela corrente;
Q Fecha todos os arquivos de ndice abertos;
Q Cria o novo ndice;
Q Seta o novo ndice como a ordem corrente;
Q Posiciona a tabela corrente no primeiro registro do ndice.

Com exceo do RDD CTREE, a tabela corrente no precisa estar aberta em modo
exclusivo para a criao de ndice, pois na criao de ndices no Ctree alterada a
estrutura da tabela, precisando para isto a tabela estar aberta em modo exclusivo.

E Sintaxe: DBCREATEINDEX(<cNOME>, <cEXPCHAVE>, [bEXPCHAVE],
[lUNICO])

E Parmetros:

cNOME Nome do arquivo de ndice a ser criado.
cEXPCHAVE Expresso das chaves do ndice a ser criado na forma de string.
bEXPCHAVE Expresso das chaves do ndice a ser criado na forma executvel.
lUNICO Cria ndice como nico (o padro .F.).

E Retorno:

Nenhum ()

Exemplo:

// Este exemplo mostra como se pode criar novo arquivo de ndice
criando a ordem sobre os
// campos Nome e End e no aceitar duplicao:

USE Cliente VIA "DBFCDX" NEW
DBCREATEINDEX("\teste\ind2.cdx","Nome+End",{ || Nome+End },.T.)

DBDELETE()

A funo DBDELETE() marca o registro corrente como apagado logicamente(), sendo
necessria sua utilizao em conjunto com as funes RecLock() e MsUnLock().

Para filtrar os registro marcados do alias corrente pode-se utilizar o comando SET
DELETED e para apag-los fisicamente pode-se utilizar a funo __DBPACK().

E Sintaxe: DBDELETE ( )

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata

IF Found()
RecLock(SA1,.F.) // Define que ser realizada uma alterao no
registro posicionado
DbDelete() // Efetua a excluso lgica do registro posicionado.
MsUnLock() // Confirma e finaliza a operao
ENDIF

DBF()

A funo DBF() verifica qual o Alias da rea de trabalho corrente. O Alias definido
quando a tabela aberta atravs do parmetro correspondente (DBUSEAREA()). Esta
funo o inverso da funo SELECT(), pois nesta retornado o nmero da rea de
trabalho do Alias correspondente.

E Sintaxe: DBF()

E Parmetros:

Nenhum ()

E Retorno:

Caracter Retorna o Alias corrente. Caso no exista Alias corrente retorna "" (String vazia).

Exemplo:

dbUseArea( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F.
)
MessageBox("O Alias corrente : "+DBF(),"Alias", 0) //Resultado: "O
Alias corrente : SSS"

DBFIELDINFO()

A funo DBFIELDINFO() utilizada para obter informaes sobre determinado campo
da tabela corrente. O tipo de informao (primeiro argumento) escolhido de acordo
com as constantes abaixo:

E Tabela A : Constantes utilizadas na parametrizao da funo

Constante Descrio Retorno
DBS_NAME Nome do campo. Caracter
DBS_DEC Nmero de casas decimais. Numrico
DBS_LEN Tamanho. Numrico
DBS_TYPE Tipo. Caracter

A posio do campo no leva em considerao os campos internos do Protheus (Recno
e Deleted).

E Sintaxe: DBFIELDINFO ( < nINFOTIPO > , < nCAMPO > )

E Parmetros:

nINFOTIPO Tipo de informao a ser verificada (DBS_NAME, DBS_DEC, DBS_LEN e
DBS_TYPE).
nCAMPO Posio do campo a ser verificado.

E Retorno:

Indefinido Retorna NIL se no h tabela corrente ou a posio do campo
especificado est invlida.
Informao do campo Informao requisitada pelo usurio (pode ser de tipo
numrico se for tamanho ou casas decimais, tipo caracter se for nome ou tipo).

Exemplo:

USE Clientes NEW

DBFIELDINFO(DBS_NAME,1) // Retorno: Nome
DBFIELDINFO(DBS_TYPE,1) // Retorno: C
DBFIELDINFO(DBS_LEN,1) // Retorno: 10
DBFIELDINFO(DBS_DEC,1) // Retorno: 0

DBFILTER()

A funo DBFILTER() utilizada para verificar a expresso de filtro ativo na rea de
trabalho corrente.

E Sintaxe: DBFILTER()

E Parmetros:

Nenhum ()

E Retorno:

Caracter Retorna a expresso do filtro ativo na rea de trabalho atual. Caso no exista
filtro ativo retorna "" (String vazia).

Exemplo:

USE Cliente INDEX Ind1 NEW
SET FILTER TO Nome > "Jose"
DBFILTER() // retorna: Nome > "Jose"
SET FILTER TO Num < 1000
DBFILTER() // retorna: Num < 1000

DBGOTO()

Move o cursor da rea de trabalho ativa para o record number (recno) especificado,
realizando um posicionamento direto, sem a necessidade uma busca (seek) prvio.

E Sintaxe: DbGoto(nRecno)

E Parmetros

nRecno Record number do registro a ser posicionado.

Exemplo:

DbSelectArea(SA1)
DbGoto(100) // Posiciona no registro 100

IF !EOF() // Se a rea de trabalho no estiver em final de arquivo
MsgInfo(Voc est no cliente:+A1_NOME)
ENDIF

DBGOTOP()

Move o cursor da rea de trabalho ativa para o primeiro registro lgico.

E Sintaxe: DbGoTop()

E Parmetros

Nenhum ()

Exemplo:

nCount := 0 // Varivel para verificar quantos registros h no
intervalo
DbSelectArea(SA1)
DbGoTop()

While !BOF() // Enquanto no for o incio do arquivo
nCount++ // Incrementa a varivel de controle de registros no
intervalo
DbSkip(-1)
End


MsgInfo(Existem :+STRZERO(nCount,6)+ registros no intervalo).

// Retorno esperado :000001, pois o DbGoTop posiciona no primeiro
registro.

DBGOBOTTON()

Move o cursor da rea de trabalho ativa para o ltimo registro lgico.

E Sintaxe: DbGoBotton()

E Parmetros

Nenhum ()

Exemplo:

nCount := 0 // Varivel para verificar quantos registros h no
intervalo
DbSelectArea(SA1)
DbGoBotton()

While !EOF() // Enquanto no for o incio do arquivo
nCount++ // Incrementa a varivel de controle de registros no
intervalo
DbSkip(1)
End

MsgInfo(Existem :+STRZERO(nCount,6)+ registros no intervalo).

// Retorno esperado :000001, pois o DbGoBotton posiciona no ltimo
registro.

DBINFO()

DBINFO() utilizada para obter informaes sobre a tabela corrente. O tipo de
informao (primeiro argumento) escolhido de acordo com as constantes abaixo:


DBI_GETRECSIZE
Tamanho do registro em nmero de
bytes similar a RECSIZE.
Numrico
DBI_TABLEEXT
Extenso do arquivo da tabela
corrente.
Caracter
DBI_FULLPATH
Nome da tabela corrente com
caminho completo.
Caracter
DBI_BOF
Se est posicionada no incio da
tabela similar a BOF
Lgico
DBI_EOF
Se est posicionada no final da tabela
similar a EOF
Lgico
DBI_FOUND
Se a tabela est posicionada aps
uma pesquisa similar a FOUND
Lgico
DBI_FCOUNT
Nmero de campos na estrutura da
tabela corrente similar a FCOUNT
Numrico
DBI_ALIAS
Nome do Alias da rea de trabalho
corrente similar a ALIAS
Caracter
DBI_LASTUPDATE
Data da ltima modificao similar a
LUPDATE
Data

E Sintaxe: DBINFO(<nINFOTIPO>)

E Parmetros:

nINFOTIPO Tipo de informao a ser verificada.

E Retorno:

Indefinido Informao da Tabela Informao requisitada pelo usurio (o tipo depende da
informao requisitada). Se no houver tabela corrente retorna NIL.

Exemplo:

USE Clientes NEW
DBINFO(DBI_FULLPATH) // Retorno: C:\Teste\Clientes.dbf
DBINFO(DBI_FCOUNT) // Retorno: 12
DBGOTOP()
DBINFO(DBI_BOF) // Retorno: .F.
DBSKIP(-1)
DBINFO(DBI_BOF) // Retorno: .T.

DBNICKINDEXKEY()

Funo que retorna o IndexKey,ou seja, a expresso de ndice da ordem especificada
pelo NickName. Se no existe ndice com o nickname, retorna uma string vazia.

E Sintaxe: DBNICKINDEXKEY(<cNick>)

E Parmetros:

cNick Indica o "NickName" da ordem de ndice.

E Retorno:

Caracter Expresso do ndice identificado pelo "NickName".

DBORDERINFO()

A funo DBORDERINFO() utilizada para obter informaes sobre determinada
ordem. A especificao da ordem pode ser realizada atravs de seu nome ou sua
posio dentro da lista de ordens, mas se ela no for especificada sero
obtidas informaes da ordem corrente. O tipo de informao (primeiro argumento)
escolhido de acordo com as constantes abaixo:


DBOI_BAGNAME
Nome do arquivo de ndice ao qual
a ordem pertence.
Caracter
DBOI_FULLPATH
do arquivo de ndice (com seu
diretrio) ao qual a ordem pertence.
Caracter
DBOI_ORDERCOUNT
Nmero de ordens existentes no
arquivo de ndice especificado.
Caracter

E Sintaxe: DBORDERINFO(<nINFOTIPO>)

E Parmetros:

nINFOTIPO Nome do arquivo de ndice.

E Retorno:

Caracter Retorna a informao da Ordem requisitada pelo usurio (pode ser de tipo
numrico se for nmero de ordens no ndice, tipo caracter se for nome do
arquivo de ndice). Caso no exista ordem corrente ou a posio da ordem
especificada est invlida retorna NIL.

Exemplo:

DBORDERINFO(DBOI_BAGNAME) // retorna: Ind
DBORDERINFO(DBOI_FULLPATH) // retorna: C:\AP6\Teste\Ind.cdx

DBORDERNICKNAME()

A funo DBORDERNICKNAME() utilizada para selecionar a ordem ativa atravs de
seu
apelido. Esta ordem a responsvel pela seqncia lgica dos registros da tabela
corrente.

E Sintaxe: DBORDERNICKNAME(<cAPELIDO>)

E Parmetros:

cAPELIDO Nome do apelido da ordem a ser setada.

E Retorno:

Lgico Retorna Falso se no conseguiu tornar a ordem ativa. Principais erros: No existe
tabela ativa ou no foi encontrada a ordem com o apelido.
Retorna Verdadeiro se a ordem foi setada com sucesso.

Exemplo:

USE Cliente NEW
SET INDEX TO Nome, Idade

IF !DBORDERNICKNAME("IndNome")
Messagebox("Registro no encontrado","Erro", 0)
ENDIF

DBPACK()

A funo DBPACK() remove fisicamente todos os registros com marca de excludo da
tabela.

E Sintaxe: __DBPACK()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
DBGOTO(100)
DBDELETE()
DBGOTO(105)
DBDELETE()
DBGOTO(110)
DBDELETE()

// Se a excluso for confirmada:
__DBPACK()

DBRECALL()

A funo DBRECALL() utilizada para retirar a marca de registro deletado do registro
atual. Para ser executada o registro atual deve estar bloqueado ou a tabela deve estar
aberta em modo exclusivo. Se o registro atual no estiver deletado, esta funo no faz
nada. Ela o oposto da funo DBDELETE() que marca o registro atual como deletado.

E Sintaxe: DBRECALL()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo 01: Desfazendo a deleo do registro posicionado do alias corrente

USE Cliente
DBGOTO(100)
DBDELETE()
DELETED() // Retorna: .T.
DBRECALL()
DELETED() // Retorna: .F.

Exemplo 02: Desfazendo as delees do alias corrente

USE Cliente
DBGOTOP()
WHILE !EOF()
DBRECALL()
DBSKIP()
ENDDO

DBRECORDINFO()

A funo DBRECORDINFO() utilizada para obter informaes sobre o registro
especificado pelo segundo argumento (recno) da tabela corrente, se esta informao
for omitida ser verificado o registro corrente. O tipo de informao (primeiro
argumento) escolhido de acordo com as constantes abaixo:


DBRI_DELETED Estado de deletado similar a DELETED Lgico
DBRI_RECSIZE
Tamanho do registro similar a
RECSIZE
Numrico
DBRI_UPDATED
Verifica se o registro foi alterado e
ainda no foi atualizado fisicamente
similar a UPDATED
Lgico

E Sintaxe: DBRECORDINFO ( < nINFOTIPO > , [ nREGISTRO ] ) --> xINFO

E Parmetros:

nINFOTIPO Tipo de informao a ser verificada.
nREGISTRO Nmero do registro a ser verificado.

E Retorno:

Indefinido No h tabela corrente ou registro invlido. Informao do Registro. Informao
requisitada pelo usurio (o tipo depende da informao requisitada).

Exemplo:

USE Clientes NEW
DBGOTO(100)
DBRECORDINFO(DBRI_DELETED) // Retorno: .F.
DBDELETE()
DBRECORDINFO(DBRI_DELETED) // Retorno: .F.
DBRECALL()
DBRECORDINFO(DBRI_RECSIZE) // Retorno: 230
NOME := "JOAO"
DBGOTO(200)
DBRECORDINFO(DBRI_UPDATED) // Retorno: .F.
DBRECORDINFO(DBRI_UPDATED,100) // Retorno: .T.

DBREINDEX()

A funo DBREINDEX() reconstri todos os ndices da rea de trabalho corrente e
posiciona as tabelas no primeiro registro lgico.

E Sintaxe: DBREINDEX()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE Clientes NEW
DBSETINDEX("IndNome")
DBREINDEX()

DBRLOCK()

A funo DBRLOCK() utilizada quando se tem uma tabela aberta e compartilhada e se
deseja bloquear um registro para que outros usurios no possam alter-lo.
Se a tabela j est aberta em modo exclusivo, a funo no altera seu estado.
O usurio pode escolher o registro a ser bloqueado atravs do parmetro
(recno), mas se este for omitido ser bloqueado o registro corrente como na funo
RLOCK().
Esta funo o oposto DBRUNLOCK, que libera registros bloqueados.

E Sintaxe: DBRLOCK([nREGISTRO])

E Parmetros:

nREGISTRO Nmero do registro a ser bloqueado.

E Retorno:

Lgico Retorna Falso se no conseguiu bloquear o registro. Principal motivo: o registro
j foi bloqueado por outro usurio.

Retorna Verdadeiro se o registro foi bloqueado com sucesso.

Exemplo:

DBUSEAREA( .T.,"dbfcdxads", "\dadosadv609\sa1990.dbf","SSS",.T., .F.
)
DBGOTO(100)
DBRLOCK() // Bloqueia o registro atual (100)
DBRLOCK(110) // Bloqueia o registro de nmero 110

DBRLOCKLIST()

A funo DBRLOCKLIST() utilizada para verificar quais registros esto locados na
tabela corrente. Para tanto, retornada uma tabela unidimensional com os nmeros
dos registros.

E Sintaxe: DBRLOCKLIST()

E Parmetros:

Nenhum ()

E Retorno:

Array Retorna NIL se no existe tabela corrente ou no existe nenhum
registro locado. Retorna a lista com os recnos dos registros locados na tabela
corrente.

Exemplo:

)
DBGOTOP()
DBRLOCK() // Bloqueia o primeiro registro
DBRLOCKLIST() // Retorna: {1,100,110}

DBRUNLOCK()

A funo DBRUNLOCK() utilizada para liberar determinado registro bloqueado. O
usurio pode escolher o registro a ser desbloqueado atravs do parmetro (Recno),
mas se este for omitido ser desbloqueado o registro corrente como na funo
DBUNLOCK(). Esta funo o oposto DBRLOCK, que bloquea os registros.

E Sintaxe: DBRUNLOCK([nREGISTRO])

E Parmetros:

nREGISTRO Nmero do registro a ser desbloqueado.

E Retorno:

Nenhum ()

Exemplo:

)
DBGOTO(100)
DBRUNLOCK() //Desbloqueia o registro atual (100)
DBRUNLOCK(110) // Desbloqueia o registro de nmero 110

DBSETDRIVER()

A funo DBSETDRIVER() pode ser utilizada apenas para verificar qual o RDD que est
definido como padro quando for omitido seu parmetro. Ela tambm pode ser
utilizada para especificar outro RDD como padro, especificando-o atravs do
parmetro.

E Sintaxe: DBSETDRIVER([cNOVORDD])

E Parmetros:

cNOVORDD Novo nome do RDD a ser definido como padro.

E Retorno:

Caracter Nome do RDD padro corrente.

Exemplo:

DBSETDRIVER("CTREECDX") // Retorna: DBFCDX
DBSETDRIVER() // Retorna: CTREECDX

Note que ao utilizar a funo DBSETDRIVER para redefinir o driver
corrente, o retorno da funo no ser o driver definido nos
parmetros, mas o driver que estava em uso antes da atualizao.

DBSETINDEX()

A funo DBSETINDEX() utilizada para acrescentar uma ou mais ordens de
determinado ndice na lista de ordens ativas da rea de trabalho. Quando o arquivo de
ndice possui apenas uma ordem, a mesma acrescentada lista e torna-se ativa.
Quando o ndice possui mais de uma ordem, todas so acrescentadas lista e a
primeira torna-se ativa.

Para utilizar os arquivos de extenso padro do RDD este dado deve
ser especificado.

E Sintaxe: DBSETINDEX(<@cARQINDICE>)

E Parmetros:

cARQINDICE Nome do arquivo de ndice, com ou sem diretrio.

E Retorno:

Nenhum ()

Exemplo:

USE Cliente NEW
DBSETINDEX("Ind1")
DBSETINDEX("\teste\Ind2.cdx")

DBSETNICKNAME()

A funo DBSETNICKNAME() utilizada para colocar um apelido em determinada
ordem
especificada pelo primeiro parmetro. Caso seja omitido o nome do apelido a ser dado,
a funo apenas verifica o apelido corrente.

E Sintaxe: DBSETNICKNAME(<cINDICE>, [cAPELIDO])

E Parmetros:

cINDICE Nome da ordem que deve receber o apelido.
cAPELIDO Nome do apelido da ordem a ser setada.

E Retorno:

Caracter Retorna "" (String vazia) se no conseguiu encontrar a ordem especificada, no
conseguiu setar o apelido ou no havia apelido. Retorna o apelido corrente.

Exemplo:

USE Cliente NEW
DBSETNICKNAME("IndNome") // retorna: ""
DBSETNICKNAME("IndNome","NOME") // retorna: ""
DBSETNICKNAME("IndNome") // retorna: "NOME"

DBSELECTAREA()

Define a rea de trabalho especificada com sendo a rea ativa. Todas as operaes
subseqentes que fizerem referncia a uma rea de trabalho a utilizao, a menos que
a rea desejada seja informada explicitamente.

E Sintaxe: DbSelectArea(nArea | cArea)

E Parmetros

nArea
Valor numrico que representa a rea desejada, em funo de todas as reas j
abertas pela aplicao, que pode ser utilizado ao invs do nome da rea.
cArea Nome de referncia da rea de trabalho a ser selecionada.

Exemplo 01: DbselectArea(nArea)

nArea := Select(SA1) // 10 (proposto)

DbSelectArea(nArea) // De acordo com o retorno do comando Select()

ALERT(Nome do cliente: +A1_NOME) // Como o SA1 o alias
selecionado, os comandos
// a partir da seleo do alias compreendem que ele
// est implcito na expresso, o que causa o mesmo
// efeito de SA1->A1_NOME

Exemplo 02: DbselectArea(cArea)

DbSelectArea(SA1) // Especificao direta do alias que deseja-se
selecionar

ALERT(Nome do cliente: +A1_NOME) // Como o SA1 o alias
selecionado, os comandos
// a partir da seleo do alias compreendem que ele
// est implcito na expresso, o que causa o mesmo
// efeito de SA1->A1_NOME

DBSETORDER()

Define qual ndice ser utilizado pela rea de trabalho ativa, ou seja, pela rea
previamente selecionada atravs do comando DbSelectArea(). As ordens disponveis no
ambiente Protheus so aquelas definidas no SINDEX /SIX, ou as ordens disponibilizadas
por meio de ndices temporrios.

E Sintaxe: DbSetOrder(nOrdem)

E Parmetros

nOrdem
Nmero de referncia da ordem que deseja ser definida como ordem ativa para
a rea de trabalho.

Exemplo:

DbSelectArea(SA1)
DbSetOrder(1) // De acordo com o arquivo SIX ->
A1_FILIAL+A1_COD+A1_LOJA

DBORDERNICKNAME()

Define qual ndice criado pelo usurio seja utilizado. O usurio pode incluir os seus
prprios ndices e no momento da incluso deve criar o NICKNAME para o mesmo.

E Sintaxe: DbOrderNickName(NickName)
E Parmetros

NickName NickName atribudo ao ndice criado pelo usurio.

Exemplo:

DbSelectArea(SA1)
DbOrderNickName(Tipo) // De acordo com o arquivo SIX -> A1_FILIAL+A1_TIPO
NickName: Tipo


DBSEEK() E MSSEEK()

DbSeek(): Permite posicionar o cursor da rea de trabalho ativo no registro com as
informaes especificadas na chave de busca, fornecendo um retorno lgico indicando
se o posicionamento foi efetuado com sucesso, ou seja, se a informao especificada
na chave de busca foi localizada na rea de trabalho.

E Sintaxe: DbSeek(cChave, lSoftSeek, lLast)

E Parmetros

cChave
Dados do registro que deseja-se localizar, de acordo com a ordem de busca
previamente especificada pelo comando DbSetOrder(), ou seja, de acordo com o
ndice ativo no momento para a rea de trabalho.
lSoftSeek
Define se o cursor ficar posicionado no prximo registro vlido, em relao a
chave de busca especificada, ou em final de arquivo, caso no seja encontrada
exatamente a informao da chave. Padro .F.
lLast
Define se o cursor ser posicionado no primeiro ou no ltimo registro de um
intervalo com as mesmas informaes especificadas na chave. Padro .F.

Exemplo 01 Busca exata

DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX ->

IF DbSeek(01 + 000001 + 02 ) // Filial: 01, Cdigo: 000001,
Loja: 02

MsgInfo(Cliente localizado, Consulta por cliente)

Else
MsgAlert(Cliente no encontrado, Consulta por cliente)

Endif

Exemplo 02 Busca aproximada

DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX ->

DbSeek(01 + 000001 + 02, .T. ) // Filial: 01, Cdigo: 000001,
Loja: 02

// Exibe os dados do cliente localizado, o qual pode no ser o
especificado na chave:

MsgInfo(Dados do cliente localizado: +CRLF +;
Filial: + A1_FILIAL + CRLF +;
Cdigo: + A1_COD + CRLF +;
Loja: + A1_LOJA + CRLF +;
Nome: + A1_NOME + CRLF, Consulta por cliente)

MsSeek(): Funo desenvolvida pela rea de Tecnologia da Microsiga, a qual possui as
mesmas funcionalidades bsicas da funo DbSeek(), com a vantagem de no
necessitar acessar novamente a base de dados para localizar uma informao j
utilizada pela thread (conexo) ativa.

Desta forma, a thread mantm em memria os dados necessrios para reposicionar os
registros j localizados atravs do comando DbSeek (no caso o Recno()) de forma que
a aplicao pode simplesmente efetuar o posicionamento sem executar novamente a
busca.

A diferena entre o DbSeek() e o MsSeek() notada em aplicaes com grande volume
de posicionamentos, como relatrios, que necessitam referenciar diversas vezes o
mesmo registro durante uma execuo.

DBSKIP()

Move o cursor do registro posicionado para o prximo (ou anterior dependendo do
parmetro), em funo da ordem ativa para a rea de trabalho.

E Sintaxe: DbSkip(nRegistros)

E Parmetros

nRegistros Define em quantos registros o cursor ser deslocado. Padro 1

Exemplo 01 Avanando registros

DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGotop() // Posiciona o cursor no incio da rea de trabalho ativa

While !EOF() // Enquanto o cursor da rea de trabalho ativa no
indicar fim de arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip()
End

Exemplo 02 Retrocedendo registros

DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGoBotton() // Posiciona o cursor no final da rea de trabalho
ativa

While !BOF() // Enquanto o cursor da rea de trabalho ativa no
indicar incio de arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip(-1)
End

DBSETFILTER()

Define um filtro para a rea de trabalho ativa, o qual pode ser descrito na forma de um
bloco de cdigo ou atravs de uma expresso simples.

E Sintaxe: DbSetFilter(bCondicao, cCondicao)

E Parmetros

bCondicao Bloco de expressa a condio de filtro em forma executvel.
cCondicao Expresso de filtro simples na forma de string.

Exemplo 01 Filtro com bloco de cdigo

bCondicao := {|| A1_COD >= 000001 .AND. A1_COD <= 001000}
DbSelectArea(SA1)
DbSetOrder(1)
DbSetFilter(bCondicao)
DbGoBotton()

While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End

// O ltimo cliente visualizado deve ter o cdigo menor do que
001000.

Exemplo 02 Filtro com expresso simples

cCondicao := A1_COD >= 000001 .AND. A1_COD <= 001000
DbSelectArea(SA1)
DbSetOrder(1)
DbSetFilter(,cCondicao)
DbGoBotton()

While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End

// O ltimo cliente visualizado deve ter o cdigo menor do que
001000.

DBSTRUCT()

Retorna um array contendo a estrutura da rea de trabalho (alias) ativo. A estrutura
ser um array bidimensional conforme abaixo:

ID* Nome campo Tipo campo Tamanho Decimais

*ndice do array

E Sintaxe: DbStruct()

E Parmetros

Nenhum ()

Exemplo:

cCampos :=
DbSelectArea(SA1)
aStructSA1 := DbStruct()

FOR nX := 1 to Len(aStructSA1)

cCampos += aStructSA1[nX][1] + /

NEXT nX

ALERT(cCampos)

DBUNLOCK()

A funo DBUNCLOK() retira os bloqueios dos registros e do arquivo da tabela
corrente.

E Sintaxe: DBUNLOCK()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

DBUNLOCKALL()

A funo DBUNLOCKALL() Retira os bloqueios de todos os registros e dos arquivos de
todas as tabelas abertas. Esta funo utilizada para liberar todos os registros
bloqueados e equivalente a executar DBUNLOCK para todas as tabelas da rea de
trabalho.

E Sintaxe: DBUNLOCKALL()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

DBUSEAREA()

Define um arquivo de base de dados como uma rea de trabalho disponvel na
aplicao.

E Sintaxe: DbUseArea(lNovo, cDriver, cArquivo, cAlias, lComparilhado,;
lSoLeitura)

E Parmetros

lNovo
Parmetro opcional que permite que se caso o cAlias especificado j esteja
em uso, ele seja fechado antes da abertura do arquivo da base de dados.
cDriver
Driver que permita a aplicao manipular o arquivo de base de dados
especificado. A aplicao ERP possui a varivel __LOCALDRIVER definida a
partir das configuraes do .ini do server da aplicao.
Algumas chaves vlidas: DBFCDX, CTREECDX, DBFCDXAX, TOPCONN.
cArquivo
Nome do arquivo de base de dados que ser aberto com o alias
especificado.
cAlias Alias para referncia do arquivos de base de dados pela aplicao.
lComparilhado Se o arquivo poder ser utilizado por outras conexes.
lSoLeitura Se o arquivo poder ser alterado pela conexo ativa.

Exemplo:

DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) +
registros.)
DbCloseArea()

DELETED()

A funo DELETED() Verifica se o registro est com marca de excludo. Quando o
registro excludo, permanece fisicamente na tabela, mas fica marcado como excludo.
Esta funo verifica este estado. Se nenhuma rea est selecionada, retorna .F.. Quando
executada a funo DBPACK() todos os registros marcados como deletados so
apagados fisicamente. A funo DBRECALL() retira todas as marcas.

E Sintaxe: DELETED()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

USE "\DADOSADV\AA1990.DBF" SHARED NEW
DBGOTO(100)
IF DELETED()
Messagebox("O registro atual foi deletado","Erro", 0)
ENDIF

FCOUNT()

A funo FCOUNT() avalia a quantidade de campos existentes na estrutura do arquivo
ativo como rea de trabalho.

E Sintaxe: FCOUNT()

E Parmetros:

Nenhum ()

E Retorno:

Numrico Quantidade de campos existentes na estrutura da rea de trabalho ativa.

Exemplo:

DbSelectArea(SA1)
nFields := FCOUNT()

IF nFields > 0
MSGINFO(A estrutura da tabela contm
:+CvalToChar(nFields)+campos.)
ENDIF

FOUND()

A funo FOUND() recupera o resultado de sucesso referente a ltima operao de
busca efetuada pelo processamento corrente.

E Sintaxe: FOUND()

E Parmetros:

Nenhum ()

E Retorno:

Lgico Indica se a ltima operao de busca realizada pelo processamento corrente
obteve sucesso (.T.) ou no (.F.).

Exemplo:
Pergunte(cPerg,.T.)
DbSelectArea(SA1)
DbSetOrder(1)
DbSeek(xFilial(SA1)+MVPAR01)

IF Found()
MSGINFO(Cliente encontrado)
ELSE
MSGALERT(Dados no encontrados)
ENDIF

INDEXKEY()

A funo INDEXKEY() determina a expresso da chave de um ndice especificado na
rea de trabalho corrente, e o retorna na forma de uma cadeia de caracteres, sendo
normalmente utilizada na rea de trabalho correntemente selecionada.

E Sintaxe: INDEXKEY()

E Parmetros:

nOrdem Ordem do ndice na lista de ndices abertos pelo comando USE...INDEX ou SET
INDEX TO na rea de trabalho corrente. O valor default zero especifica o ndice
corrente, independentemente de sua posio real na lista.


E Retorno:

Caracter Expresso da chave do ndice especificado na forma de uma cadeia de
caracteres. Caso no haja um ndice correspondente, INDEXKEY() retorna uma
cadeia de caracteres vazia ("").

Exemplo:

cExpressao := SA1->(IndexKey())

INDEXORD()

A funo INDEXORD() verifica a posio do ndice corrente na lista de ndices do
respectivo alias.

E Sintaxe: INDEXORD()

E Parmetros:

Nenhum ()

E Retorno:

Numrico Posio do ndice corrente na lista de ndices da tabela. Retorna 0 se no existe
ndice aberto na tabela corrente.

Exemplo:

USE Cliente NEW
SET INDEX TO Nome, End, Cep
nOrd:=INDEXORD() // Return: 1 - o primeiro ndice da lista

LUPDATE()

A funo LUPDATE() verifica qual a data da ltima modificao e fechamento da tabela
corrente, sendo que caso no exista tabela corrente retornada uma data em branco.

E Sintaxe: LUPDATE()

E Parmetros:

Nenhum ()

E Retorno:

Data Retorna um valor do tipo Data , indicando a data da ultima modificao e
fechamento da Tabela. Caso no haja tabela selecionada na rea de trabalho
atual , a funo retornar uma data vazia (ctod("")) .

Exemplo:

// Mostra a data da ltima modificao da tabela corrente,
dModificacao := LUpdate()
IF (EMPTY(dModificacao))
CONOUT("No h tabela corrente")
ELSE
CONOUT(("Data da ultima modificacao : " + DTOS(dModificacao)))
ENDIF

MSAPPEND()

A funo MsAppend() adiciona registros de um arquivo para outro, respeitando a
estrutura das tabelas.

E Sintaxe: MSAPPEND( [cArqDest], cArqOrig )

E Parmetros:

cArqDest Se o RDD corrente for DBFCDX os registros sero adicionados na rea
selecionada, caso contrrio o arquivo destino ter que ser informado.
cArqOrig Nome do arquivo origem contendo os registros a serem adicionados.


E Retorno:

Lgico Se a operao for realizada com sucesso o funo retornar verdadeiro (.T.).

Exemplo:

dbSelectArea(XXX)
MsAppend(,ARQ00001)

MSUNLOCK()

Libera o travamento (lock) do registro posicionado confirmando as atualizaes
efetuadas neste registro.

E Sintaxe: MsUnLock()

E Parmetros

Nenhum ()

Exemplo:

DbSelectArea(SA1)

IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
ENDIF

ORDBAGEXT()

A funo ORDBAGEXT utilizada no gerenciamento de indices para os arquivos de
dados do sistema, permitindo avaliar qual a extenso deste ndices atualmente em uso,
de acordo com a RDD ativa.

E Sintaxe: ORDBAGEXT()

E Parmetros:

Nenhum ()

E Retorno:

cBagExt Extenso do arquivo dos arquivos de ndices em uso pelo sistema, determinado
pela RDD ativa.

Exemplo:

cArqTRB := CriaTrab(aStruTRB,.T.)
// RDD UTILIZADA: DBFCDXADS
DbUseArea(.T., DBFCDXADS, cArqTRB, "TRBSA1", .F., .F.)

DbSelectArea("TRBSA1")
cArqInd := CriaTrab(Nil,.F.)
IndRegua("TRBSA1",cArqInd,cChaveInd,,"","Selecionando registros
...")
#IFNDEF TOP
DbSetIndex(cArqInd+OrdBagExt())
// RETORNO: .CDX
#ENDIF
DbSetOrder(1)

ORDKEY()

A funo ORDKEY() verifica qual a expresso de chave de determinada ordem. Caso
no sejam especificados os parmetros de identificao da ordem, verificada a ordem
corrente. Para evitar conflito, no caso de haver mais de uma ordem com o mesmo
nome, pode-se passar o parmetro com o nome do ndice ao qual a ordem pertence.

A ordem passada no primeiro parmetro pode ser especificada atravs da sua posio
na lista de ordens ativas (atravs do ORDLISTADD) ou atravs do nome dado ordem.
A funo verifica automaticamente se o parmetro numrico ou caracter.

E Sintaxe: ORDKEY([cOrdem | nPosicao] , [cArqIndice])

E Parmetros:

cOrdem
nPosicao
H duas opes para o primeiro parmetro:
cNome: tipo caracter, contm nome do ndice.
nPosicao: tipo numrico, indica ordem do ndice.
cArqIndice Nome do arquivo de ndice.

E Retorno:

Caracter Expresso de chave da ordem ativa ou especificada pelos parmetros.
Cadeia vazia indica que no existe ordem corrente.

Exemplo:

USE Cliente NEW
INDEX ON Nome+Cod TO Ind1 FOR Nome+Cod > 'AZZZZZZZ'
ORDKEY('Ind1')
// Retorna: Nome+Cod

RECLOCK()

Efetua o travamento do registro posicionado na rea de trabalho ativa, permitindo a
incluso ou alterao das informaes do mesmo.

E Sintaxe: RecLock(cAlias,lInclui)

E Parmetros

cAlias Alias que identifica a rea de trabalho que ser manipulada.
lInclui Define se a operao ser uma incluso (.T.) ou uma alterao (.F.)

Exemplo 01 - Incluso

DbSelectArea(SA1)
RecLock(SA1,.T.)
SA1->A1_FILIAL := xFilial(SA1) // Retorna a filial de acordo com
as configuraes do ERP
SA1->A1_COD := 900001
SA1->A1_LOJA := 01

Exemplo 02 - Alterao

DbSelectArea(SA1)

IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
ENDIF

A linguagem ADVPL possui variaes da funo RecLock(), as quais so:

E RLOCK()
E DBRLOCK()

A sintaxe e a descrio destas funes esto disponveis no Guia de
Referncia Rpido ao final deste material.

A linguagem ADVPL possui variaes da funo MsUnlock(), as quais
so:

E UNLOCK()
E DBUNLOCK()
E DBUNLOCKALL()

A sintaxe e a descrio destas funes esto disponveis no Guia de
Referncia Rpido ao final deste material.

RECNO()

A funo RECNO() retorna o nmero do registro atualmente posiconado na rea de
trabalho ativa.

E Sintaxe: RECNO()

E Parmetros:

Nenhum ()

E Retorno:
nRecno Identificador numrico do registro atualmente posicionando na rea de trabalho
ativa.

Exemplo:

DbSelectArea(SA1)
DbGoto(100) // Posiciona no registro de recno 100.
MSGINFO(Registro posicionado:+cValToChar(RECNO()))

SELECT()

A funo SELECT() determina o nmero da rea de trabalho de um alias. O nmero
retornado pode variar de zero a 250. Se <cAlias> no for especificado, retornado o
nmero da rea de trabalho corrente. Caso <cAlias> seja especificado e o alias nao
existir, SELECT() retorna zero.

E Sintaxe: SELECT([cAlias])

E Parmetros:

cAlias Nome da rea de trabalho a ser verificada.

E Retorno:

Numrico rea de trabalho do alias especificado na forma de um valor numrico inteiro.

Exemplo:

nArea := Select(SA1)

ALERT(Referncia do alias SA1: +STRZERO(nArea,3)) // 10
(proposto)

SET FILTER TO

O comando SET FILTER TO define uma condio de filtro que ser aplicada a rea de
trabalho ativa.

Recomenda-se o uso da funo DbSetFilter() em substituio ao
comando SET FILTER TO

E Sintaxe: SET FILTER TO cCondicao

E Parmetros:

cCondicao Expresso que ser avaliada pela SET FILTER, definindo os registros que ficaro
disponveis na rea de trabalho ativa.
Esta expresso obrigatoriamente deve ter um retorno lgico.

E Retorno:

Nenhum ()

O uso da sintaxe SET FILTER TO desativa o filtro na rea de trabalho
corrente.

Exemplo:

USE Employee INDEX Name NEW

SET FILTER TO Age > 50

LIST LastName, FirstName, Age, Phone

SET FILTER TO

SOFTLOCK()

Permite a reserva do registro posicionado na rea de trabalho ativa de forma que
outras operaes, com exceo da atual, no possam atualizar este registro. Difere da
funo RecLock() pois no gera uma obrigao de atualizao, e pode ser sucedido por
ele.

Na aplicao ERP Protheus, o SoftLock() utilizado nos browses, antes da confirmao
da operao de alterao e excluso, pois neste momento a mesma ainda no foi
efetivada, mas outras conexes no podem acessar aquele registro pois o mesmo est
em manuteno, o que implementa da integridade da informao.

E Sintaxe: SoftLock(cAlias)

E Parmetros

cAlias
Alias de referncia da rea de trabalho ativa, para o qual o registro posicionado
ser travado.

Exemplo:

cChave := GetCliente() // Funo ilustrativa que retorna os dados de
busca de um cliente

DbSelectArea(SA1)
DbSetOrder(1)
DbSeek(cChave)

IF Found()
SoftLock() // Reserva o registro localizado
lConfirma := AlteraSA1() // Funo ilustrativa que exibe os dados do
registro
// posicionado e
pemite a alterao dos mesmos.

IF lConfirma
RecLock(SA1,.F.)
GravaSA1() // Funo ilustrativa que altera os dados conforme a
AlertaSA1()
MsUnLock() // Liberado o RecLock() e o SoftLock() do registro.
Endif
Endif

USED()

A funo USED() utilizada para determinar se h um arquivo de banco de dados em
uso em uma rea de trabalho especfica. O padro que USED() opere na rea de
trabalho correntemente selecionada.

E Sintaxe: USED()

E Parmetros:

Nenhum ()

E Retorno:

Lgico Verdadeiro (.T.) caso haja um arquivo de banco de dados em uso; caso contrrio,
retorna falso (.F.).

Exemplo:

USE Customer NEW
CONOUT(USED()) // Resulta: .T.
CLOSE
CONOUT (USED()) // Resulta: .F.

ZAP

O comando ZAP remove fisicamente todos os registro da tabela corrente. necessrio
que o alias em questo seja aberto em modo exclusivo para esta operao ser
realizada.

E Sintaxe: ZAP

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:
cTabela := RetSqlName("SA4")
cAlias := "TMP"
USE (cTabela) ALIAS (cAlias) EXCLUSIVE NEW VIA "TOPCONN"
IfNetErr()
MsgStop("Nao foi possivel abrir "+cTabela+" em modo
EXCLUSIVO.")
Else
ZAP
USE
MsgStop("Registros da tabela "+cTabela+" eliminados com sucesso.")
Endif

Controle de numerao seqencial

GETSXENUM()

Obtm o nmero seqncia do alias especificado no parmetro, atravs da referncia
aos arquivos de sistema SXE/SXF ou ao servidor de numerao, quando esta
configurao est habilitada no ambiente Protheus.

E Sintaxe: GETSXENUM(cAlias, cCampo, cAliasSXE, nOrdem)

E Parmetros

cAlias
Alias de referncia da tabela para a qual ser efetuado o controle da numerao
seqencial.
cCampo Nome do campo no qual est implementado o controle da numerao.
cAliasSXE
Parmetro opcional, quando o nome do alias nos arquivos de controle de
numerao no o nome convencional do alias para o sistema ERP.
nOrdem Nmero do ndice para verificar qual a prxima ocorrncia do nmero.

CONFIRMSXE()

Confirma o nmero alocado atravs do ltimo comando GETSXENUM().

E Sintaxe: CONFIRMSXE(lVerifica)

E Parmetros

lVerifica

Verifica se o nmero confirmado no foi alterado, e por conseqncia j
existe na base de dados.

ROLLBACKSXE()

Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a
numerao disponvel para outras conexes.

E Sintaxe: ROLLBACKSXE()

E Parmetros

Nenhum ()

Validao

ALLWAYSFALSE()

A funo AllwaysFalse() foi criada com o objetivo de compatibilidade, sendo que
sempre ir retornar um valor lgico falso, facilitando a especificao desta situao nas
parametrizaes de validaes de modelos de interface pr-definidos no sistema.

E Sintaxe: ALLWAYSFALSE()

E Parmetros:

Nenhum ()

E Retorno:

Lgico Retorna um valor lgico sempre falso.

ALLWAYSTRUE()

A funo AllwaysTrue() foi criada com o objetivo de compatibilidade, sendo que
sempre ir retornar um valor lgico verdadeiro, facilitando a especificao desta
situao nas parametrizaes de validaes de modelos de interface pr-definidos no
sistema.

E Sintaxe: ALLWAYSTRUE()

E Parmetros:

Nenhum ()

E Retorno:

Lgico Retorna um valor lgico sempre verdadeiro.


EXISTCHAV()

Retorna .T. ou .F. se o contedo especificado existe no alias especificado. Caso exista
ser exibido um help de sistema com um aviso informando da ocorrncia.

Funo utilizada normalmente para verificar se um determinado cdigo de cadastro j
existe na tabela na qual a informao ser inserida, como por exemplo o CNPJ no
cadastro de clientes ou fornecedores.

E Sintaxe: ExistChav(cAlias, cConteudo, nIndice)

E Parmetros

cAlias Alias de referncia para a validao da informao.
cConteudo Chave a ser pesquisada, sem a filial.
nIndice ndice de busca para consulta da chave.

EXISTCPO()

Retorna .T. ou .F. se o contedo especificado no existe no alias especificado. Caso no
exista ser exibido um help de sistema com um aviso informando da ocorrncia.

Funo utilizada normalmente para verificar se a informao digitada em um campo, a
qual depende de outra tabela, realmente existe nesta outra tabela. Como, por exemplo,
o cdigo de um cliente em um pedido de venda.

E Sintaxe: ExistCpo(cAlias, cConteudo, nIndice)

E Parmetros

cAlias Alias de referncia para a validao da informao.
cConteudo Chave a ser pesquisada, sem a filial.
nIndice ndice de busca para consulta da chave.

LETTERORNUM()

A funo LETTERORNUM() avalia se um determinado contedo composto apenas de
letras e nmeros (alfanumrico).

E Sintaxe: LETTERORNUM(cString)

E Parmetros:

cString String que ter seu contedo avaliado.

E Retorno:

Lgico Indica que se a string avaliada contm apenas letras e nmero, ou seja,
alfanumrico.

NAOVAZIO()

Retorna .T. ou .F. se o contedo do campo posicionado no momento no est vazio.

E Sintaxe: NaoVazio()

E Parmetros

Nenhum ()

NEGATIVO()

Retorna .T. ou .F. se o contedo digitado para o campo negativo.

E Sintaxe: Negativo()

E Parmetros

Nenhum ()

PERTENCE()

Retorna .T. ou .F. se o contedo digitado para o campo est contido na string definida
como parmetro da funo. Normalmente utilizada em campos com a opo de
combo. Caso contrrio, seria utilizada a funo ExistCpo().

E Sintaxe: Pertence(cString)

E Parmetros

cString

String contendo as informaes vlidas que podem ser digitadas para um
campo.

POSITIVO()

Retorna .T. ou .F. se o contedo digitado para o campo positivo.

E Sintaxe: Positivo()

E Parmetros

Nenhum ()

TEXTO()

Retorna .T. ou .F. se o contedo digitado para o campo contm apenas nmeros ou
alfanumricos.

E Sintaxe: Texto()

E Parmetros

Nenhum ()

VAZIO()

Retorna .T. ou .F. se o contedo do campo posicionado no momento est vazio.

E Sintaxe: Vazio()

E Parmetros

Nenhum ()

Manipulao de parmetros do sistema

GETMV()

Retorna o contedo do parmetro especificado no arquivo SX6, considerando a filial
parametrizada na conexo. Caso o parmetro no exista, ser exibido um help do
sistema informando a ocorrncia.

E Sintaxe: GETMV(cParametro)

E Parmetros

cParametro

Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema.

GETNEWPAR()

parametrizada na conexo. Caso o parmetro no exista ser exibido um help do

Difere do SuperGetMV() pois considera que o parmetro pode no existir na verso
atual do sistema, e por conseqncia no ser exibida a mensagem de help.

E Sintaxe: GETNEWPAR(cParametro, cPadrao, cFilial)

E Parmetros

cParametro

Nome do parmetro do sistema no SX6, sem a especificao da filial de
sistema.

cPadrao Contedo padro que ser utilizado caso o parmetro no exista no SX6.
cFilial

Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.

PUTMV()

Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as
parametrizaes informadas.

E Sintaxe: PUTMV(cParametro, cConteudo)

E Parmetros

cParametro Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema.
cConteudo Contedo que ser atribudo ao parmetro no SX6.

SUPERGETMV()

parametrizada na conexo. Caso o parmetro no exista, ser exibido um help do

Difere do GetMv() pois os parmetros consultados so adicionados em uma rea de
memria, para que em uma nova consulta no seja necessrio acessar e pesquisar o
parmetro na base de dados.

E Sintaxe: SUPERGETMV(cParametro , lHelp , cPadrao , cFilial)

E Parmetros

cParametro

Nome do parmetro do sistema no SX6, sem a especificao da filial de
sistema.

lHelp

Se ser exibida a mensagem de Help caso o parmetro no seja encontrado no
SX6.

cPadrao Contedo padro que ser utilizado caso o parmetro no exista no SX6.
cFilial

Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.

Controle de impresso

AVALIMP()

A funo AVALIMP() utilzada em relatrios especficos em substituio da funo
CABEC(), configurando a impressora de acordo com o driver escolhido e os parmetros
de impresso disponveis no array aReturn, respeitando o formato utilizado pela funo
SETPRINT().

E Sintaxe: AVALIMP(nLimite)

E Parmetros:

nLimite Tamanho do relatrio em colunas, podendo assumir os valores 80,132 ou 220
colunas, respectivamente para os formatos P, M ou G de impresso.

E Retorno:

Caracter String com caracteres de controle, dependente das configuraes escolhidas
pelo usurio e do arquivo de driver especificado.

Exemplo:

/*/
+-------------------------------------------------------------------
| Funo | XAVALIMP | Autor | ARNALDO RAYMUNDO JR. | Data |
01.01.2007 |
+-------------------------------------------------------------------
| Descrio | Exemplo de utilizao da funo AXCADASTRO() |
|+------------------------------------------------------------------
|+------------------------------------------------------------------
/*/

USER FUNCTION XAVALIMP()

LOCAL cTitulo := PADC(AVALIMP,74)
LOCAL cDesc1 := PADC(Demonstrao do uso da funo
AVALIMP(),74)
LOCAL cDesc2 :=
LOCAL cDesc3 := PADC(CURSO DE ADVPL,74)
LOCAL cTamanho := G
LOCAL cLimite := 220
LOCAL cNatureza :=
LOCAL aReturn := {Especial, 1,Administrao, 1, 2, 2,,1}
LOCAL cNomeProg := RAVALIMP
LOCAL cPerg := PADR(RAVALIMP,10) // Compatibilizao
com MP10
LOCAL nLastKey := 0
LOCAL cString :=SF2"

Pergunte(cPerg,.F.) // Pergunta no SX1

wnrel:=
SetPrint(cString,wnrel,cPerg,cTitulo,cDesc1,cDesc2,cDesc3,.T.)


If nLastKey == 27
Return
Endif

RptStatus({|| RunReport(cString)},cTitulo)
Return

/*/
+------------------------------------------------------------------
| Funo | RUNREPORT | Autor | -------------------- | Data |
01.01.2007 |
+------------------------------------------------------------------
| Descrio | Funo interna de processamento utilizada pela
XAVALIMP() |
|+------------------------------------------------------------------
|+------------------------------------------------------------------
/*/

Static Function RunReport(cString)
SetPrc(0,0)

//+----------------------------------------------------------------+
//| Chamada da funo AVALIMP() |
//+----------------------------------------------------------------+
@ 00,00 PSAY AvalImp(220)
dbSelectArea(cString)
dbSeek(xFilial()+mv_par01+mv_par03,.T.)
...

Return

CABEC()

A funo CABEC() determina as configuraes de impresso do relatrio e imprime o
cabealho do mesmo.

E Sintaxe: Cabec(cTitulo, cCabec1, cCabec2, cNomeProg, nTamanho,
nCompress, aCustomText, lPerg, cLogo)

E Parmetros:

cTitulo Ttulo do relatrio.
cCabec1 String contendo as informaes da primeira linha do cabealho.
cCabec2 String contendo as informaes da segunda linha do cabealho.
cNomeProg Nome do programa de impresso do relatrio.
nTamanho Tamanho do relatrio em colunas (80, 132 ou 220).
nCompress Indica se impresso ser comprimida (15) ou normal (18).
aCustomText
Texto especfico para o cabealho, substituindo a estrutura padro do
sistema.
lPerg
Permite a supresso da impresso das perguntas do relatrio, mesmo que o
parmetro MV_IMPSX1 esteja definido como S.


cLogo
Redefine o bitmap que ser impresso no relatrio, no necessitando que ele
esteja no formato padro da Microsiga:
"LGRL"+SM0->M0_CODIGO+SM0->M0_CODFIL+".BMP"

E Retorno:

Nenhum ()

Exemplo:


/*/
+-------------------------------------------------------------------
| Funo | MPTR001 | Autor | ARNALDO RAYMUNDO JR. | Data |
01.01.2007 |
+-------------------------------------------------------------------
| Descrio | Exemplo de utilizao das funes de impresso
CABEC() |
|+-----------------------------------------------------------------
|+-----------------------------------------------------------------
/*/

User Function MPTR001()

Local cDesc1 := "Este programa tem como objetivo imprimir relatorio "
Local cDesc2 := "de acordo com os parametros informados pelo usuario."
Local cDesc3 := "Listagem de clientes"
Local cTitulo := "Listagem de clientes"
Local lImprime := .T.

// Parametros da SetPrint()
Local cString := "SA1"
Local cPerg := ""
Local lDic := .T. // Habilita a visalizacao do dicionario
Local aOrd := RetSixOrd(cString)
Local lCompres := .T. // .F. - Normal / .T. - Comprimido
Local lFilter := .T. // Habilita o filtro para o usuario
Local cNomeProg := "MPTR002"
Local cTamanho := "M"
Local nTipo := 18
Local nLimite := 132

Default lCriaTrab := .T.

Private lEnd := .F.
Private lAbortPrint := .F.
Private aReturn := { "Zebrado", 1, "Administracao", 2, 2, 1, "", 1}
//aReturn[4] 1- Retrato, 2- Paisagem
//aReturn[5] 1- Em Disco, 2- Via Spool, 3- Direto na Porta, 4- Email

Private nLastKey := 0
Private m_pag := 01
Private wnrel := "MPTR002"

dbSelectArea("SA1")
dbSetOrder(1)

//
// Monta a interface padrao com o usuario...
//
wnrel :=
SetPrint(cString,cNomeProg,cPerg,@cTitulo,cDesc1,cDesc2,cDesc3,lDic,
aOrd,lCompres,cTamanho,,lFilter)

If nLastKey == 27
Return
Endif

SetDefault(aReturn,cString,,,cTamanho,aReturn[4]) // nFormato: 1-
Retrato, 2-Paisagem

If nLastKey == 27
Return
Endif

nTipo := IIF(aReturn[4]==1,15,18)

//
// Processamento. RPTSTATUS monta janela com a regua de
processamento.
//
RptStatus({||
RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)},cTitulo
)
Return

/*/
+---------------------------------------------------------------
01.01.2007 |
+-------------------------------------------------------------------
MPTR001() |
|+------------------------------------------------------------------
|+-----------------------------------------------------------------
/*/

Static Function
RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)

Local nLin := 80
Local cCabec1 := ""
Local cCabec2 := ""
Local cArqInd

cCabec1 := "CODIGO"+Space(2)+"LOJA"+Space(2)+"NOME
REDUZIDO"+Space(9)
cCabec1 += "RAZAO
SOCIAL"+Space(30)+"CNPJ"+Space(18)+"INSCR.ESTADUAL"+Space(8)
cCabec1 += "CEP"
cCabec2 := "ESTADO"+Space(2)+"MUNICIPIO"+Space(8)+"ENDERECO"

dbSelectArea("TRBSA1")
dbGoTop()

SetRegua(RecCount())

While !EOF()

If lAbortPrint .OR. nLastKey == 27
@nLin,00 PSAY "*** CANCELADO PELO OPERADOR ***"
Exit
Endif

If nLin > 55 // Salto de Pgina. Neste caso o formulario tem 55
linhas...
Cabec(cTitulo,cCabec1,cCabec2,cNomeProg,cTamanho,nTipo)
nLin := 9
Endif
...

IMPCADAST()

A funo IMPCADAST() cria uma interface simples que permite a impresso dos
cadastros do sistema com parametrizao DE/ATE.

E Sintaxe: IMPCADAST(cCab1, cCab2, cCab3, cNomeProg, cTam, nLimite,
cAlias)

E Parmetros:

cCab1 Primeira linha do cabealho.
cCab2 Segunda linha do cabealho.
cCab3 Terceira linha do cabealho.
cNomeProg Nome do programa.
cTam Tamanho do relatrio nos formatos P, M e G.
nLimite Nmero de colunas do relatrio, seguindo o formato especificado no tamanho,
aonde:
P- 80 colunas
M- 132 colunas
G- 220 colunas
cAlias Alias do arquivo de cadastro que ser impresso.


E Retorno:

Nenhum ()

MS_FLUSH()

A funo MS_FLUSH() envia o spool de impresso para o dispositivo previamente
especificado com a utilizao das funes AVALIMP() ou SETPRINT().

E Sintaxe: MS_FLUSH()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

/*/--------------------------------------------------------
01.01.2007 |
+-------------------------------------------------------------------
MPTR001() |
|+------------------------------------------------------------------
|+------------------------------------------------------------------
| Observao| Continuao do exemplo da funo CABEC() |
|+------------------------------------------------------------------
/*/

Static Function
RunReport(cTitulo,cString,cNomeProg,cTamanho,nTipo,nLimite)

Local nLin := 80
Local cCabec1 := ""
Local cCabec2 := ""
Local cArqInd

cCabec1 := "CODIGO"+Space(2)+"LOJA"+Space(2)+"NOME
REDUZIDO"+Space(9)
cCabec1 += "RAZAO
SOCIAL"+Space(30)+"CNPJ"+Space(18)+"INSCR.ESTADUAL"+Space(8)
cCabec1 += "CEP"
cCabec2 := "ESTADO"+Space(2)+"MUNICIPIO"+Space(8)+"ENDERECO"

dbSelectArea("TRBSA1")
dbGoTop()

SetRegua(RecCount())

While !EOF()

If lAbortPrint .OR. nLastKey == 27
@nLin,00 PSAY "*** CANCELADO PELO OPERADOR ***"
Exit
Endif

If nLin > 55 // Salto de Pgina. Neste caso o formulario tem 55
linhas...
Cabec(cTitulo,cCabec1,cCabec2,cNomeProg,cTamanho,nTipo)
nLin := 9
Endif

// Primeira linha de detalhe:
@nLin,000 PSAY TRBSA1->A1_COD
@nLin,008 PSAY TRBSA1->A1_LOJA
@nLin,014 PSAY TRBSA1->A1_NREDUZ
@nLin,036 PSAY TRBSA1->A1_NOME
@nLin,078 PSAY TRBSA1->A1_CGC
@nLin,100 PSAY TRBSA1->A1_INSCR
@nLin,122 PSAY TRBSA1->A1_CEP
nLin++

// Segunda linha de detalhe
@nLin,000 PSAY TRBSA1->A1_EST
@nLin,008 PSAY TRBSA1->A1_MUN
@nLin,025 PSAY TRBSA1->A1_END
nLin++

//Linha separadora de detalhes
@nLin,000 PSAY Replicate("-",nLimite)
nLin++

dbSkip() // Avanca o ponteiro do registro no arquivo
EndDo

SET DEVICE TO SCREEN

If aReturn[5]==1
dbCommitAll()
SET PRINTER TO
OurSpool(wnrel)
Endif

MS_FLUSH()
RETURN

OURSPOOL()

A funo OURSPOOL() executa o gerenciador de impresso da aplicao Protheus,
permitindo a visualizao do arquivo de impresso gerado pelo relatrio no formato
PostScrip com extenso ##R.

E Sintaxe: OURSPOOL(cArquivo)

E Parmetros:

cArquivo Nome do relatrio a ser visualizado.

E Retorno:

Nenhum ()

Exemplo:

If aReturn[5]==1 // Indica impresso em disco.
dbCommitAll()
SET PRINTER TO
OurSpool(wnrel)
Endif

RODA()

A funo RODA() imprime o rodap da pgina do relatrio, o que pode ser feito a cada
pgina, ou somente ao final da impresso.

Pode ser utilizado o ponto de entrada "RodaEsp" para tratamento de
uma impresso especfica.

E Sintaxe: Roda(uPar01, uPar02, cSize)

E Parmetros:

uPar01
No mais utilizado.
uPar02
No mais utilizado.
cSize
Tamanho do relatrio (P,M,G).

E Retorno:

Nenhum ()

Exemplo:

/*/
+------------------------------------------------------------------
| Funo | TESTIMPR | Autor | MICROSIGA | Data |
01.01.2007 |
+-------------------------------------------------------------------
| Descrio | Exemplo de utilizao da funo RODA() em
conjunto com a CABEC.|
|+------------------------------------------------------------------
|+-----------------------------------------------------------------
/*/


User Function TestImpr()
Local wnrel
Local cString := "SA1"
Local titulo := "Teste Impresso de Relatorios"
Local NomeProg := "XXX"
Local Tamanho := "M"

PRIVATE aReturn := { "Zebrado", 1,"Administracao", 1, 2, 1, "",1 }

wnrel:=SetPrint(cString,NomeProg,"",@titulo,"", "",
"",.F.,.F.,.F.,Tamanho,,.F.)


RptStatus({|lEnd|
TestRel(@lEnd,wnRel,cString,Tamanho,NomeProg)},titulo)

Return


/*/
+------------------------------------------------------------------
| Funo | TESTREL | Autor | MICROSIGA | Data |
01.01.2007 |
+------------------------------------------------------------------
| Descrio | Funo interna de impresso da TestImpr(). |
|+------------------------------------------------------------------
|+--------------------------------------------------------------/*/
User Function TestRel(lEnd,WnRel,cString,Tamanho,NomeProg)

LOCAL cabec1,cabec2
LOCAL cRodaTxt := oemtoansi("Rodap")
Local nCntImpr
Local nTipo

nCntImpr := 0
li := 80
m_pag := 1
nTipo := 15
titulo:= oemtoansi("Lista de Clientes")
cabec1:= oemtoansi("COD LOJA NOME"+Space(27)+ "NOME FANTASIA")
cabec2:=""

dbSelectArea("SA1")
dbGoTop()
SetRegua(LastRec())
While !Eof()
IncRegua()
If Li > 60
cabec(titulo,cabec1,cabec2,nomeprog,tamanho,15)
@ Li,0 PSAY __PrtThinLine()
Endif
nCntImpr++
Li++
@ Li,01 PSAY A1_COD
@ Li,05 PSAY A1_LOJA
@ Li,10 PSAY A1_NOME
@ Li,51 PSAY A1_NREDUZ
If Li > 60
Li:=66
Endif
dbSkip()
EndDO

If li != 80
Roda(nCntImpr,cRodaTxt,Tamanho)
EndIf

Set Device to Screen
If aReturn[5] = 1
Set Printer To
dbCommitAll()
OurSpool(wnrel)
Endif
MS_FLUSH()
Return

SETDEFAULT()

A funo SetDefault() prepara o ambiente de impresso de acordo com as informaes
configuradas no array aReturn, obtidas atravs da funo SetPrint().

E Sintaxe: SetDefault ( < aReturn > , < cAlias > , [ uParm3 ] , [ uParm4 ] ,
[cSize] , [ nFormat ] )

E Parmetros:

aReturn Configuraes de impresso.
cSize Tamanho da pgina "P","M" ou "G"
nFormat Formato da pgina, 1 retrato e 2 paisagem.

E Retorno:

Nenhum ()



SetPrint().

SETPRC()

A funo SETPRC() utilizada para posicionar o dispositivo de impresso ativo,
previamente definido pelo uso das funes AVALIMP() ou SETPRINT(), em uma
linha/coluna especificada.

E Sintaxe: SETPRC(nLinha, nColuna)

E Parmetros:

nLinha Linha na qual dever ser posicionado o dispositivo de impresso.
nColuna Coluna na qual dever ser posicionado o dispositivo de impresso.

E Retorno:

Nenhum ()

Exemplo:

aReturn := { "", 1, "" , 2, 3, cPorta , "",IndexOrd() }
SetPrint(Alias(),"","","",,,,.F.,,,,,,,'EPSON.DRV',.T.,,cPorta)
if nLastKey == 27
Return (.F.)
Endif
SetDefault(aReturn,Alias())
SetPrc(0,0)

SETPRINT()

A funo SetPrint() cria uma interface padro onde as opes de impresso de um
relatrio podem ser configuradas. Basicamente duas variveis m_pag e aReturn
precisam ser declaradas como privadas (private) antes de executar a SetPrint(), sendo
que:

Q m_pag: controla o nmero de pginas.
Q aReturn: vetor contendo as opes de impresso, sendo sua estrutura
bsica composta de 8 (oito) elementos.

Aps confirmada, os dados so armazenados no vetor aReturn que ser passado como
parmetro para funo SetDefault().

E Sintaxe: SetPrint ( < cAlias > , < cProgram > , [ cPergunte ] , [ cTitle ] , [
cDesc1 ] , [ cDesc2 ] , [ cDesc3 ] , [ lDic ] , [ aOrd ] , [ lCompres ] ,
[ cSize ] , [ uParm12 ] , [ lFilter ] , [ lCrystal ] , [ cNameDrv ] , [
uParm16 ] , [ lServer ] , [ cPortPrint ] ) --> cReturn

E Parmetros:

cProgram Nome do arquivo a ser gerado em disco.
cPergunte Grupo de perguntas cadastrado no dicionrio SX1.
cTitle Ttulo do relatrio.


cDesc1 Descrio do relatrio.
lDic
Utilizado na impresso de cadastro genrico permite a escolha dos campos a
serem impressos. Se o parmetro cAlias no for informado o valor padro
assumido ser .F.
aOrd Ordem(s) de impresso.
lCompres
Se verdadeiro (.T.) permite escolher o formato da impresso, o valor padro
assumido ser .T.
cSize Tamanho do relatrio "P","M" ou "G".
lFilter
Se verdadeiro (.T.) permite a utilizao do assistente de filtro, o valor padro
assumido ser .T.
lCrystal
Se verdadeiro (.T.) permite integrao com Crystal Reports, o valor padro
assumido ser .F.
cNameDrv Nome de um driver de impresso.
lServer Se verdadeiro (.T.) fora impresso no servidor.
cPortPrint Define uma porta de impresso padro.

E Retorno:

Caracter Nome do Relatrio


SetPrint().

Controle de processamentos

ABREEXCL()

A funo ABREEXCL() fecha o arquivo cujo alias est expresso em <cAlias> e o reabre
em modo exclusivo para proceder operaes em que isto necessrio, como por
exemplo, PACK. Se outra estao estiver usando o arquivo, o retorno ser .F..

E Sintaxe: ABREEXCL(cAlias)

E Parmetros:

cAlias Alias do arquivo que ser reaberto em modo exclusivo.

E Retorno:

Lgico Indica se foi possvel abrir o arquivo em modo exclusivo.

CLOSEOPEN()

A funo CLOSEOPEN() utilizada para fechar e reabrir uma lista de arquivos
especificada.

E Sintaxe: CLOSEOPEN(aClose, aOpen)

E Parmetros:

aClose Array contendo os Aliases dos arquivos que devero ser fechados.
aOpen Array contendo os Aliases dos arquivos que devero ser abertos.

E Retorno:

Lgico Indica se todos os arquivos especificados em aOpen foram abertos com sucesso.

CLOSESFILE()

A funo CLOSESFILE() fecha todos os arquivos em uso pela conexo, com exceo dos
SXs (inclusive SIX), SM2 e SM4.

E Sintaxe: CLOSESFILE(cAlias)

E Parmetros:

cAlias String contendo os nomes dos demais Aliases que no devero ser fechados,
separando os itens com /.

E Retorno:

Lgico Indica se todos os arquivos foram fechados com sucesso.

CHKFILE()

A funo CHKFILE() retorna verdadeiro (.T.) se o arquivo j estiver aberto ou se o Alias
no for informado. Sempre que desejar mudar o modo de acesso do arquivo (de
compartilhado para exclusivo ou vice-versa), feche-o antes de cham-la.

E Sintaxe: ChkFile(cAlias,lExcl,cNewAlias)

E Parmetros:

cAlias Alias do arquivo a ser reaberto.
lExcl Se for informado verdadeiro (.T.), o arquivo ser aberto em modo
Exclusivo. Caso contrrio, o arquivo ser aberto em modo compartilhado.
Se este parmetro no for informado, ser assumido falso (.F.).
cNewAlias Novo Alias para reabertura do arquivo.

E Retorno:

Lgico Indica se o arquivo foi re-aberto com sucesso.

Exemplo:

dbSelectArea(SA1)
dbCloseArea()
lOk := .T.
While .T.
IF !ChkFile(SA1,.T.)
nResp := Alert(Outro usurio usando! Tenta de
novo?,{Sim,Nao})
If nResp == 2
lOk := .F.
Exit
Endif
Endif
EndDo
If lOk
// Faz o processamento com o arquivo...
Endif
// Finaliza
If Select(SA1)
dbCloseArea()
Endif
ChkFile(SA1,.F.)
Return

CONOUT()

A funo CONOUT() permite a exibio de uma mensagem de texto no console do
Server do Protheus. Caso o Protheus esteja configurado como servio a mensagem ser
gravada no arquivo de log.

E Sintaxe: CONOUT(cMensagem)

E Parmetros:

cMensagem String contendo a mensagem que dever ser exibida no console do Protheus.

E Retorno:

Nenhum ()

CRIAVAR()

A funo CRIAVAR() cria uma varivel, retornando o valor do campo, de acordo com o
dicionrio de dados, inclusive avaliando o inicializador padro, permitindo um retorno
de acordo com o tipo de dado definido no dicionrio.

E Sintaxe: CriaVar(cCampo,lIniPad,cLado)

E Parmetros:

cCampo Nome do campo.
lIniPad Indica se considera (.T.) ou no (.F.) o inicializador.
cLado Se a varivel for caracter, cLado pode ser: C - centralizado, L
- esquerdo ou R direito.

E Retorno:

Indefinido Tipo de dado de acordo com o dicionrio de dados, considerando inicializador
padro

Exemplo:

// Exemplo do uso da funo CriaVar:
cNumNota := CriaVar(F2_DOC) // Retorna o contedo do
// inicializador padro,
// se existir, ou espaos em branco
Alert(cNumNota)
Return

DISARMTRANSACTION()

A funo DISARMTRANSATCION() utilizada para realizar um RollBack de uma
transao aberta com o comando BEGIN TRANSACTION e delimitada com o comando
END TRANSACTION.

Ao utilizar esta funo, todas as alteraes realizadas no intervalo delimitado pela
transao so desfeitas, restaurando a situao da base de dados ao ponto
imediatamente anterior ao incio do processamento.

O uso da funo DISARMTRANSACTION() no finaliza a conexo ou o
processamento corrente.

Caso seja necessrio alm de desfazer as alteraes, finalizar o
processamento, dever ser utilizada a funo USEREXCEPTION().

E Sintaxe: DISARMTRANSACTION()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

Exemplo:

lMsErroAuto := .F.
MSExecAuto({|x,y| MATA240(x,y)}, aCampos, 3)

If lMsErroAuto

aAutoErro := GETAUTOGRLOG()
DisarmTransaction()
MostraErro()

EndIf

EXECBLOCK()

A funo EXECBLOCK() executa uma funo de usurio que esteja compilada no
repositrio. Esta funo normalmente utilizada pelas rotinas padres da aplicao
Protheus para executar pontos de entrada durante seu processamento.

A funo de usurio executada atravs da EXECBLOCK() no recebe
parmetros diretamente, sendo que estes estaro disponveis em uma
varivel private denominada PARAMIXB.

A varivel PARAMIXB o reflexo do parmetro xParam, definido na
execuo da funo EXECBLOCK(). Caso seja necessria a passagem de
vrias informaes, as mesmas devero ser definidas na forma de um
array, tornando PARAMIXB um array tambm, a ser tratado na funo
de usurio que ser executada.

EXISTBLOCK()

A funo EXISTBLOCK() verifica a existncia de uma funo de usurio compilada no
repositrio de objetos da aplicao Protheus. Esta funo normalmente utilizada nas
rotinas padres da apliao Protheus para determinar a existncia de um ponto de
entrada e permitir sua posterior execuo.

E Sintaxe: EXISTBLOCK(cFuno)

E Parmetros:

cFuno Nome da funo que ser avaliada.

E Retorno:

Lgico Indica se a funo de usurio existe compilada no repositrio de objetos
corrente.

Exemplo:

IF EXISTBLOCK(MT100GRV)
EXECBLOCK(MT100GRV,.F.,.F.,aParam)
ENDIF


E Sintaxe: EXECBLOCK(cFuno, lReserv1, lReserv2, xParam)

E Parmetros:

cFuno Nome da funo de usurio que ser executada.
lReserv1 Parmetro de uso reservado da aplicao. Definir como .F.
lReserv2 Parmetro de uso reservado da aplicao. Definir como .F.
xParam Contedo que ficar disponvel na funo de usurio executada, na forma da
varivel private PARAMIXB.

E Retorno:

Indefinido O retorno da EXECBLOCK() definido pela funo que ser executada.

Exemplo:

aParam := {cNota, cSerie, cFornece, cLoja)

IF EXISTBLOCK(MT100GRV)
lGravou := EXECBLOCK(MT100GRV,.F.,.F.,aParam)
ENDIF

USER FUNCTION MT100GRV()

LOCAL cNota := PARAMIXB[1]
LOCAL cSerie:= PARAMIXB[1]
LOCAL cFornece:= PARAMIXB[1]
LOCAL cLoja:= PARAMIXB[1]

RETURN .T.

ERRORBLOCK()

A funo ERRORBLOCK() efetua o tratamento de erros e define a atuao de um
handler de erros sempre que ocorrer um erro em tempo de execuao. O manipulador
de erros especificado como um bloco de cdigo da seguinte forma:

Q { |<objError>| <lista de expressoes>, ... }, onde:

<objError> um error object que contm informaoes sobre o erro. Dentro do bloco
de cdigo, podem ser enviadas mensagens ao error object para obter informaoes
sobre o erro. Se o bloco de tratamento de erros retornar verdadeiro (.T.), a operaao
que falhou repetida, e se retornar falso (.F.), o processamento recomea.

Se no foi especificado nenhum <bErrorHandler> utilizando ERRORBLOCK() e ocorrer
um erro em tempo de execuao, o bloco de tratamento ao de erros padrao avaliado.
Este manipulador de erros exibe uma mensagem descritiva na tela, ajusta a funao
ERRORLEVEL() para 1, e depois sai do programa (QUIT).

Como ERRORBLOCK() retorna o bloco de tratamento ao de erros correntes, possvel
especificar um bloco de tratamento de erros para uma operaao gravando-se o bloco
de manipulaao de erros correntes e depois recuperando-o aps o final da operaao.
Alm disso, uma importante consequncia do fato de os blocos de tratamento de erros
serem especificados como blocos de cdigo, que eles podem ser passados para
rotinas e funoes definidas por usurio e depois retornadas como valores.

E Sintaxe: ERRORBLOCK ( < bErrorHandler > )

E Parmetros:

bErrorHandler

O bloco de cdigo a ser executado toda vez que
ocorrer um erro em tempo de execuao.
Quando avaliado, o <bErrorHandler> passado na forma de um objeto erro
como um argumento pelo sistema.

E Retorno:

Code-block Retorna o bloco de cdigo corrente que deve tratar o erro. Caso no tenha sido
enviado nenhum bloco de tratamento de erro desde que o programa foi
invocado, ERRORBLOCK() retorna o bloco de tratamento de erro padro.

Exemplo:

Function CA010Form()
LOCAL xResult
LOCAL cForm:= Upper(&(ReadVar()))
LOCAL bBlock:= ErrorBlock( { |e| ChecErro(e) } )
LOCAL cOutMod
Local lOptimize := GetNewPar("MV_OPTNFE",.F.) .Or.
GetNewPar("MV_OPTNFS",.F.)

PRIVATE lRet:=.T.

cVarOutMod := If(Type("cVarOutMod") = "U", "", cVarOutMod)
cOutMod := cVarOutMod + If(Right(cVarOutMod, 1) = ",", "", ",")

While ! Empty(cOutMod)
If Left(cOutMod, At(",", cOutMod) - 1) $ Upper(cForm) //
no modulo
Help( " ",1,"ERR_FORM,,"Variavel nao disponivel para este
modulo"
Return .F.
Endif
cOutMod := Subs(cOutMod, At(",", cOutMod) + 1)
EndDo
If ("LERSTR"$cForm .or. "LERVAL"$cForm .or. "LERDATA"$cForm) .And.
M->I5_CODIGO > "499"
Help( " ",1,"CA010TXT")
ErrorBlock(bBlock)
Return .F.
Endif
BEGIN SEQUENCE
If !"EXECBLOCK"$cForm .and. !"LERSTR"$cForm .And.; // nao
executa execblock
!"LERVAL"$cForm .And.; // nem funcao de leitura
!"LERDATA"$cForm .And.; // de texto no
cadastramento
IIf(!lOptimize,.T.,!"CTBANFS"$cForm .And.
!"CTBANFE"$cForm)
xResult := &cForm
Endif
END SEQUENCE
ErrorBlock(bBlock)
Return lRet

FINAL()

A funo FINAL() executa as operaes bsicas que garantem a integridade dos dados
ao finalizar o sistema desmontando as transaes (se houver), desbloqueando os
semforos e fechando as tabelas abertas, finalizando-o em seguinda.

E Sintaxe: Final( [cMensagem1], [cMensagem2] )

E Parmetros:

cMensagem1 Primeira mensagem
cMensagem2 Segunda mensagem

E Retorno:

Nenhum ()

Exemplo:

User Function ValidUser( cUsuario, cSenha )

Local cMensag1 := Usurio invalido!
Local cMensag2 := Opo disponvel para usurios Adminstradores!

If !PswAdmin( cUsuario, cSenha )
Final( cMensag1, cMensag2 )
EndIf

Return

FINDFUNCTION()

A funo FINDFUNCTION() tem como objetivo verificar se uma determinada funo se
encontra no repositrio de objetos e at mesmo do binrio do Protheus, sendo uma
funo bsica da linguagem.

E Sintaxe: FINDFUNCTION(cFuno)

E Parmetros:

cFuno Nome da funo que ser avaliada no repositrio de objetos corrente.

E Retorno:

Lgico Indica se a funo existe compilada no repositrio de objetos corrente.

FUNDESC()

A funo FunDesc() retornar a descrio de uma opo selecionada no menu da
aplicao.

E Sintaxe: FUNDESC()

E Parmetros:

Nenhum ()

E Retorno:

Caracter Descrio da opo selecionada no menu da aplicao.

FUNNAME()

A funo FunName() retornar o nome de uma funo executada a partir de um menu
da aplicao.

E Sintaxe: FUNNAME()

E Parmetros:

Nenhum ()

E Retorno:

Caracter Nome da funo executada a partir do menu da aplicao.

GETAREA()

Funo utilizada para proteger o ambiente ativo no momento de algum
processamento especfico. Para salvar uma outra rea de trabalho (alias) que no o
ativo, a funo GetArea() deve ser executada dentro do alias: ALIAS->(GetArea()).

E Sintaxe: GETAREA()

E Retorno: Array contendo {Alias(),IndexOrd(),Recno()}

E Parmetros

Nenhum ()

GETCOUNTRYLIST()

A funo GETCOUNTRYLIST() retorna um array de duas dimenses contendo
informaes dos pases localizados.

E Sintaxe: GetCountryList()

E Parmetros:

Nenhum ()

E Retorno:

Array Array de duas dimenses, sendo uma linha para cada pas localizado, contendo
em cada posio a sigla dos pases, o nome do pas e a identificao do pas
com dois dgitos.

Exemplo:

Local aArray := GetCountryList()
Local cSigla := GetMv( MV_PAISLOC )
Local nPos

nPos := Ascan( aArray, {|d| d[1] == Upper(cSigla) } )
If nPos > 0
APMsgInfo( Pas de localizao + aArray[nPos,2] )
EndIf

ISINCALLSTACK()

A funo ISINCALLSTACK() verifica se uma determinada funo est existe dentro da
pilha de chamadas do processamento corrente.

E Sintaxe: IsInCallStack( cIsInCallStack , cStackExit )

E Parmetros:

cIsInCallStack Nome da funo que desejasse pesquisar na pilha.
cStackExit String que identifica o ponto em que desejasse finalizar a busca. Caso no seja
informada, ser utilizada como padro a expresso "STACK_EXIT".

E Retorno:
Lgico Indica se a funo especificada encontrasse na pilha de chamadas do
processsamento corrente, at o ponto de sada especificado.

REGTOMEMORY()

Inicializa as variveis de memria identificadas pelo uso do alias M-> de acordo com
a estrutura e/ou informaes contidas no arquivo definido como referncia.

E Sintaxe: REGTOMEMORY(cAlias, lInclui)

E Parmetros:

cAlias Alias do arquivo que ser utilizado como referncia para inicializao das
variveis de memria.
lInclui Identifica se as variveis devero ser inicializadas com contedos padres, ou
contendo as informaes do registro posicionado do alias especificado.


E Retorno:

Nenhum ()

RESTAREA()

Funo utilizada para devolver a situao do ambiente salva atravs do comando
GETAREA(). Deve-se observar que a ltima rea restaurada a rea que ficar ativa para
a aplicao.

E Sintaxe: RESTAREA(aArea)

E Parmetros

aArea
Array contendo: {cAlias, nOrdem, nRecno}, normalmente gerado pelo uso
da funo GetArea().

Exemplo:

// ALIAS ATIVO ANTES DA EXECUO DA ROTINA SN3
User Function XATF001()

LOCAL cVar
LOCAL aArea := GetArea()
LOCAL lRet := .T.

cVar := &(ReadVar())

dbSelectArea("SX5")
IF !dbSeek(xFilial()+"Z1"+cVar)

cSTR0001 := "REAV - Tipo de Reavaliacao"
cSTR0002 := "Informe um tipo de reavalicao valido"
cSTR0003 := "Continuar"
Aviso(cSTR0001,cSTR0002,{cSTR0003},2)
lRet := .F.

ENDIF

RestArea(aArea)
Return( lRet )

USEREXCEPTION()

A funo USEREXCEPTION() tem o objetivo de forar um erro em ADVPL de forma que
possamos tratar de alguma forma. USEREXCEPTION() recebe uma string contendo uma
descrio do erro, essa descrio ser exibida de acordo com o ambiente que se est
executando (no caso, um ambiente ERP). Ser exibida uma tela de erro.

E Sintaxe: USEREXCEPTION(cMensagem)

E Parmetros:

cMensagem Mensagem que ser exibida no cabealho do erro, contendo a explicao da
exceo.

E Retorno:

Nenhum ()

Utilizao de recursos do ambiente ERP

AJUSTASX1()

A funo AJUSTASX1() permite a incluso simultnea de vrios itens de perguntas para
um grupo de perguntas no SX1 da empresa ativa.

E Sintaxe: AJUSTASX1(cPerg, aPergs)

E Parmetros:

cPerg Grupo de perguntas do SX1 (X1_GRUPO)
aPergs Array contendo a estrutura dos campos que sero gravados no SX1.

E Retorno:

Nenhum ()


E Estrutura Item do array aPerg:

Posio Campo Tipo Descrio
01 X1_PERGUNT Caractere Descrio da pergunta em portugus.
02 X1_PERSPA Caractere Descrio da pergunta em espanhol.
03 X1_PERENG Caractere Descrio da pergunta em ingls.
04 X1_VARIAVL Caractere Nome da varivel de controle auxiliar
(mv_ch).
05 X1_TIPO Caractere Tipo do parmetro.
06 X1_TAMANHO Numrico Tamanho do contedo do parmetro.
07 X1_DECIMAL Numrico Nmero de decimais para contedos
numricos.
08 X1_PRESEL Numrico Define qual opo do combo a
padro para o parmetro.
09 X1_GSC Caractere Define se a pergunta ser do tipo G
Get ou C Choice (combo).
10 X1_VALID Caractere Expresso de validao do parmetro.
11 X1_VAR01 Caractere Nome da varivel MV_PAR+Ordem
do parmetro.
12 X1_DEF01 Caractere Descrio da opo 1 do combo em
portugus.
13 X1_DEFSPA1 Caractere Descrio da opo 1 do combo em
espanhol.
14 X1_DEFENG1 Caractere Descrio da opo 1 do combo em
ingls.
15 X1_CNT01 Caractere Contedo padro ou ltimo contedo
definido como respostas para a
pergunta.
portugus.
espanhol.
ingls.
portugus.


E Estrutura Item do array aPerg (continuao):

espanhol.
ingls.
portugus.
espanhol.
ingls.
portugus.
espanhol.
ingls.
36 X1_F3 Caractere Cdigo da consulta F3 vinculada ao
parmetro.
37 X1_GRPSXG Caractere Cdigo do grupo de campos SXG para
atualizao automtica, quando o
grupo for alterado.
38 X1_PYME Caractere Se a pergunta estar disponvel no
ambiente Pyme.
39 X1_HELP Caractere Contedo do campo X1_HELP
40 X1_PICTURE Caractere Picture de formatao do contedo do
campo.
41 aHelpPor Array Vetor simples contendo as linhas de
help em portugus para o parmetro.
caracteres.
42 aHelpEng Array Vetor simples contendo as linhas de
help em ingls para o parmetro.
caracteres.
43 aHelpSpa Array Vetor simples contendo as linhas de
help em espanhol para o parmetro.
caracteres.

ALLUSERS()

A funo ALLUSERS() retorna um array multidimensional contendo as informaes dos
usurios do sistema.

E Sintaxe: ALLUSERS()

E Parmetros:

Nenhum ()

E Retorno:

Array Array multidimensional contendo as informaes dos usurios do sistema,
aonde para cada usurio sero demonstradas as seguintes informaes:

aArray[x][1] Configuraes gerais de acesso
aArray[x][2] Configuraes de impresso
aArray[x][3] Condiguraes de acesso aos mdulos

E Array de informaes dos usurios: Configuraes gerais de acesso

Elemento Descrio Tipo Qtd.
1
1 ID C 6
2 Nome C 15
3 Senha C 6
4 Nome Completo C 30
5 Vetor com n ltimas senhas A --
6 Data de validade D 8
7 Quantas vezes para expirar N 4
8 Autorizado a alterar a senha L 1
9 Alterar a senha no prximo logon L 1
10 Vetor com os grupos A --
11 ID do superior C 6
12 Departamento C 30
13 Cargo C 30
14 E-Mail C 130
15 Nmero de acessos simultneos N 4
16 Data da ltima alterao D 8
17 Usurio bloqueado L 1
18 Nmero de dgitos para o ano N 1
19 Listner de ligaes L 1
20 Ramal C 4
E Array de informaes dos usurios: Configuraes de impresso

2
1 Vetor com horrios de acesso A --
2 Idioma N 1
3 Diretrio C 100
4 Impressora C --
5 Acessos C 512
6 Vetor com empresas A --
7 Ponto de entrada C 10
8 Tipo de impresso N 1
9 Formato N 1
10 Ambiente N 1
11 Prioridade p/ config. do grupo L 1
12 Opo de impresso C 50
13 Acesso a outros dir de impresso L 1

E Array de informaes dos usurios: Configuraes de acesso aos mdulos

3
1 Mdulo+nvel+menu C

ALLGROUPS()

A funo ALLGROUPS() retorna um array multidimensional contendo as informaes
dos grupos de usurios do sistema.

E Sintaxe: ALLGROUPS()

E Parmetros:

Nenhum ()

E Retorno:

Array Array multidimensional contendo as informaes dos grupos de usurios do
sistema, aonde para cada grupo sero demonstradas as seguintes informaes:

aArray[x][1] Configuraes gerais de acesso
aArray[x][2] Configuraes de acesso aos mdulos


E Array de informaes dos grupos: Configuraes gerais de acesso

1
1 ID C 6
2 Nome C 20
3 Vetor com horrios de acesso A
4 Data de validade D 8
5 Quantas vezes para expirar N 4
6 Autorizado a alterar a senha L 1
7 Idioma N 1
8 Diretrio C 100
9 Impressora C
10 Acessos C 512
11 Vetor com empresas A
12 Data da ltima alterao D 8
13 Tipo de impresso N 1
14 Formato N 1
15 Ambiente N 1
16 Opo de impresso L 1
17 Acesso a outros Dir de impresso L 1

E Array de informaes dos grupos: Configuraes de acesso aos mdulos

2
1 Modulo+nvel+menu C

CGC()

A funo CGC() valida o CGC digitado, utilizando o algoritmo nacional para verificao
do dgito de controle.

E Sintaxe: CGC(cCGC)

E Parmetros:

cCGC String contendo o CGC a ser validado.

E Retorno:

Lgico Indica se o CGC informado vlido.

CONPAD1()

A funo CONPAD1() exibe uma tela de consulta padro baseada no Dicionrio de
Dados (SXB).

E Sintaxe: ConPad1 ( [uPar1], [uPar2], [uPar3], cAlias, [cCampoRet] , [uPar4],
[lOnlyView] )

E Parmetros:

uPar Parmetro reservado.
cAlias Consulta padro cadastrada no Dicionrio de Dados (SXB) a ser utilizada.
cCampoRet Nome da varivel ou campo que receber o retorno da consulta padro.
uPar4
Parmetro Reservado.

lOnlyView Indica se ser somente para visualizao.

E Retorno:

Nenhum ()

DATAVALIDA()

A funo DATAVALIDA() retorna a primeira data vlida a partir de uma data
especificada como referncia, considerando inclusive a data informada para anlise.

E Sintaxe: DATAVALIDA(dData)

E Parmetros:

dData Data a partir da qual ser avaliada a prxima data vlida, considerando-a
inclusive como uma possibilidade.

E Retorno:

Data Prxima data vlida, desconsiderando sbados, domingos e os feriados
cadastrados no sistema.

EXISTINI()

A funo EXISTINI() verifica se o campo possui inicializador padro.

E Sintaxe: EXISTINI(cCampo)

E Parmetros:

cCampo Nome do campo para verificao.

E Retorno:

Lgico Indica se o campo possui um inicializador padro.

Exemplo:

// Exemplo de uso da funcao ExistIni:
// Se existir inicializador no campo B1_COD:
If ExistIni(B1_COD)
// Executa o inicializador:
cCod := CriaVar(B1_COD)
Endif

Return

EXTENSO()

A funo EXTENSO() retorna uma string referente descrio por extenso de um valor
numrico, sendo comumente utilizada para impresso de cheques, valor de duplicatas,
etc.

E Sintaxe: Extenso(nValor, lQtd, nMoeda)

E Parmetros:

nValor Valor para gerao do extenso.
lQtd Indica se o valor representa uma quantidade (.T.) ou dinheiro (.F.).
nMoeda Para qual moeda do sistema deve ser o extenso.

E Retorno:

String Descrio do valor por extenso.

FORMULA()

Interpreta uma frmula cadastrada. Esta funo interpreta uma frmula, previamente
cadastrada no Arquivo SM4 atravs do Mdulo Configurador, e retorna o resultado
com tipo de dado de acordo com a prpria frmula.

E Sintaxe: Formula(cFormula)

E Parmetros:

cFormula Cdigo da frmula a ser avaliada e cadastrada no SM4 Cadastro de Frmulas.

E Retorno:

Indefinido Resultado da interpretao da frmula cadastrada no SM4.

GETADVFVAL()

A funo GETADVFVAL() executa uma pesquisa em um arquivo pela chave de busca e
na ordem especificada, possibilitando o retorno de um ou mais campos.

E Sintaxe: GetAdvFVal(cAlias,uCpo,uChave,nOrder,uDef)

E Parmetros:

cAlias Alias do arquivo.
uCpo Nome de um campo ou array contendo os nomes dos campos
Desejados.
uChave Chave para a pesquisa.
nOrder Ordem do ndice para a pesquisa.
uDef Valor ou array default para ser retornado caso a chave no seja encontrada

E Retorno:

Indefinido Retorna o contedo de um campo ou array com o contedo de vrios campos.

A funo GETADVFVAL() difere da funo POSICIONE() apenas por
permitir o retorno de vrios campos em uma nica consulta.

As duas funes devem ser protegidas por GETAREA() / RESTAREA()
dependendo da aplicao.

HELP()

Esta funo exibe a ajuda especificada para o campo e permite sua edio. Se for
um help novo, escreve-se o texto em tempo de execuo.

E Sintaxe: Help(cHelp,nLinha, cTitulo, uPar4,cMensagem,nLinMen,nColMen)

E Parmetros:

cHelp Nome da Rotina chamadora do help. (sempre branco)
nLinha Nmero da linha da rotina chamadora. (sempre 1)
cTitulo Ttulo do help
uPar4 Sempre NIL
cMensagem Mensagem a ser exibida para o Help.
nLinMen Nmero de linhas da Mensagem. (relativa janela)
nColMen Nmero de colunas da Mensagem. (relativa janela)

E Retorno:

Nenhum ()

A funo HELP() tratada na execuo das rotinas com o recurso de
MSEXECAUTO(), permitindo a captura e exibio da mensagem no log
de processamento.

Por esta razo, em rotinas que podem ser chamadas atravs da funo
MSEXECAUTO() deve-se sempre utilizar avisos utilizando esta funo,
para que este tipo de processamento no seja travado indevidamente.

Exemplo:

IF lAuto // Se for rotina automtica
Help("ESPECIFICO",1,"HELP","PROCESSAMENTO","Parmetros do JOB
Invlidos",1,0)
ELSE
MsgAlert(Parmetros do JOB Invlidos, PROCESSAMENTO)
ENDIF

MESEXTENSO()

A funo MESEXTENSO() retorna o nome de um ms por extenso.

E Sintaxe: MESEXTENSO(nMes)

E Parmetros:

nMes Indica o nmero do ms a ter seu nome escrito por extenso.

Este parmetro pode ser definido tambm como caracter ou como
data.

E Retorno:

String Nome do ms indicado por extenso.

OBRIGATORIO()

A funo OBRIGATORIO() avalia se todos os campos obrigatrios de uma Enchoice()
foram digitados.

E Sintaxe: OBRIGATORIO(aGets, aTela, aTitulos)

E Parmetros:

aGets Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no fonte.
aTela Varivel PRIVATE tratada pelo objeto Enchoice(), previamente definida no fonte.
aTitulos Array contendo os ttulos dos campos exibidos na Enchoice().

E Retorno:

Lgico Indica se todos os campos obrigatrios foram preenchidos.

Exemplo:
/*/
+------------------------------------------------------------------
| Programa | ATFA010A | Autor | ARNALDO R. JUNIOR | Data | |
+------------------------------------------------------------------
| Desc. | Cadastro de dados complementares do bem Ativo Fixo |
+------------------------------------------------------------------
| Uso | Curso de ADVPL |
+-------------------------------------------------------------------
/*/

User Function ATFA010A()

Private cCadastro := "Atualizacao de dados do bem"
Private aRotina := { {"Pesquisar" ,"AxPesqui" ,0,1} ,;
{"Visualizar" ,"AxVisual" ,0,2} ,;
{"Atualizar" ,"U_A010AATU" ,0,4}}

Private cDelFunc := ".T."
Private cString := "SN1"

dbSelectArea("SN1")
dbSetOrder(1)
dbSelectArea(cString)
mBrowse( 6,1,22,75,cString)

Return

/*/
+-------------------------------------------------------------------
| Programa | A010AATU | Autor | ARNALDO R. JUNIOR | Data | |
+------------------------------------------------------------------
| Desc. | Atualizao de dados do bem Ativo Fixo |
+-------------------------------------------------------------------
+------------------------------------------------------------------
/*/

User Function A010AATU(cAlias,nReg,nOpc)

Local aAlter := {}

Local aPos := {015,000,400,600
Local nModelo :=
Local lF3 := .F.
Local caTela := ""

Private oDlg
Private oGetD
Private oEnch
Private aTELA[0][0] // Variveis que sero atualizadas pela
Enchoice()
Private aGETS[0] // e utilizadas pela funo OBRIGATORIO()

DbSelectArea("SX3")
DbSetOrder(1)
DbSeek(cAliasE)
//+----------------------------------------------------------------+
//|Campos da enchoice |
//+----------------------------------------------------------------+
.And. X3Uso(SX3->X3_USADO)
AAdd(aCpoEnch,SX3->X3_CAMPO)
EndIf
DbSkip()
End
//+----------------------------------------------------------------+
//|Campos alterveis da enchoice |
//+---------------------------------------------------------------+
AADD(aAlterEnch,"N1_TIPOADT") // Controle de Adiantamentos
AADD(aAlterEnch,"N1_DESCRIC") // Descrio
AADD(aAlterEnch,"N1_CHAPA") // Numero da plaqueta
AADD(aAlterEnch,"N1_FORNEC") // Fornecedor
AADD(aAlterEnch,"N1_LOJA") // Loja do Fornecedor
AADD(aAlterEnch,"N1_NSERIE") // Serie da Nota
AADD(aAlterEnch,"N1_NFISCAL") // Numero da Nota
AADD(aAlterEnch,"N1_NFITEM") // Item da Nota
AADD(aAlterEnch,"N1_UM") // Unidade de Medida
AADD(aAlterEnch,"N1_PRODUTO") // Cdigo do Produto
AADD(aAlterEnch,"N1_PEDIDO") // Codigo do Pedido de Compras
AADD(aAlterEnch,"N1_ITEMPED") // Item do Pedido de Compras
AADD(aAlterEnch,"N1_PRCIMP") // Codigo do Processo de Importacao
AADD(aAlterEnch,"N1_CODPAIS") // Codigo do Pais
AADD(aAlterEnch,"N1_ORIGCPR") // Origem de Compras
AADD(aAlterEnch,"N1_CODSP") // Codigo da SP Interna
AADD(aAlterEnch,"N1_CHASSIS") // Numero de serie

//+----------------------------------------------------------------+
//|Montagem do DIALOG |
//+----------------------------------------------------------------+
DEFINE MSDIALOG oDlg TITLE cCadastro FROM 000,000 TO 400,600 PIXEL
RegToMemory("SN1", .F.)

oEnch := MsMGet():New(cAliasE, nReg, nOpc, /*aCRA*/,
/*cLetra*/,;
/*cTexto*/, aCpoEnch,aPos,aAlterEnch, nModelo,
/*nColMens*/,;
/*cMensagem*/, /*cTudoOk*/, oDlg, lF3, lMemoria,
lColumn,;
caTela, lNoFolder, lProperty)

ACTIVATE MSDIALOG oDlg CENTERED;
ON INIT EnchoiceBar(oDlg,
{||IIF(A010AGRV(aCpoEnch,aAlterEnch,nOpc),;
oDlg:End(),.F.)},; // Boto OK
{||oDlg:End()},,aButtons) // Boto Cancelar

RETURN

/*/
+-------------------------------------------------------------------
| Programa | A010AGRV | Autor | ARNALDO R. JUNIOR | Data | |
+-------------------------------------------------------------------
| Desc. | Validao da enchoice e gravao dos dados do bem |
+------------------------------------------------------------------
+-------------------------------------------------------------------
/*/
Static Function A010AGRV(aCpos,aAlter,nOpc)

Local nX := 0

IF !Obrigatorio(aGets,aTela) /*Valida o cabecalho*/
Return .F.
ENDIF

// Atualizacao dos campos passiveis de alteracao no SN1
RecLock("SN1",.F.)
For nX := 1 to Len(aAlter)
SN1->&(aAlter[nX]) := M->&(aAlter[nX])
Next nX
MsUnLock()

Return .T.
OPENFILE()

A funo OPENFILE() exibe o diagnstico de arquivos, verificando a existncia dos
arquivos de dados e os ndices do sistema, criando-os, caso no existam. Alm de abrir
os arquivos de acordo com o mdulo onde executada ou de acordo com a
parametrizao.

E Sintaxe: OPENFILE(cEmp)

E Parmetros:

cEmp Empresa cujo os arquivos sero re-abertos.

E Retorno:

Nenhum ()

PERGUNTE()

A funo PERGUNTE() inicializa as variveis de pergunta (mv_par01,...) baseada na
pergunta cadastrado no Dicionrio de Dados (SX1). Se o parmetro lAsk no for
especificado ou for verdadeiro ser exibida a tela para edio da pergunta e se o
usurio cofirmar as variveis sero atualizadas e a pergunta no SX1 tambm ser
atualizada.

E Sintaxe: Pergunte( cPergunta , [lAsk] , [cTitle] )

E Parmetros:

cPergunta Pergunta cadastrada no Dicionrio de Dados ( SX1) a ser utilizada.
|Ask Indica se exibir a tela para edio.
cTitle Ttulo do dilogo.

E Retorno:

Lgico Indica se a tela de visualizao das perguntas foi confirmada (.T.) ou cancelada
(.F.)

PESQPICT()

A funo PESQPICT() retorna a picture definida para um campo especificado no
Dicionrio de Dados (SX3).

E Sintaxe: PesqPict(cAlias,cCampo,nTam)

E Parmetros:

cCampo Nome do campo.
nTam Opcional, para campos numricos, ser usado como o tamanho do campo para
definio da picture. Se no informado, e usado o tamanho padro no
Dicionrio de Dados.

E Retorno:

String Picture do campo especificado.

PESQPICTQT()

A funo PESQPICTQT() retorna a picture de um campo numrico referente a uma
quantidade, de acordo com o Dicionrio de Dados (SX3). Esta funo geralmente
utilizada quando h pouco espao disponvel para impresso de valores em relatrios,
quando o valor nEdio no informado, ela tem o comportamento semelhante ao da
funo X3Picture, pois busca o tamanho do campo no dicionrio de dados.

E Sintaxe: PesqPictQt(cCampo,nEdio)

E Parmetros:

cCampo Nome do campo a verificar a picture.
nEdio Espao disponvel para edio.

E Retorno:

String Picture ideal para o espao definido por nEdio, sem a separao dos milhares
por vrgula.

POSICIONE()

A funo POSICIONE() permite o retorno do contedo de um campo de um registro de
uma tabela especificado atravs de uma chave de busca.

E Sintaxe: Posicione(cAlias, nOrdem, cChave, cCampo)

E Parmetros:

nOrdem Ordem utilizada.
cChave Chave pesquisa.
cCampo Campo a ser retornado.

E Retorno:

Indefinido Contedo do campo solicitado.

A utilizao da funo POSICIONE() deve ser protegida com GETAREA()
/ RESTAREA() dependendo da aplicao.

PUTSX1()

A funo PUTSX1() permite a incluso de um nico item de pergunta em um grupo de
definido no Dicionrio de Dados (SX1). Todos os vetores contendo os textos
explicativos da pergunta devem conter at 40 caracteres por linha.

E Sintaxe: PutSx1(cGrupo, cOrdem, cPergunt, cPerSpa, cPerEng, cVar, cTipo,
nTamanho, nDecimal, nPresel, cGSC, cValid, cF3, cGrpSxg
,cPyme, cVar01, cDef01, cDefSpa1 , cDefEng1, cCnt01, cDef02,
cDefSpa2, cDefEng2, cDef03, cDefSpa3, cDefEng3, cDef04,
cDefSpa4, cDefEng4, cDef05, cDefSpa5, cDefEng5, aHelpPor,
aHelpEng, aHelpSpa, cHelp)

E Parmetros:

cGrupo Grupo de perguntas do SX1 (X1_GRUPO).
cOrdem Ordem do parmetro no grupo (X1_ORDEM).
cPergunt Descrio da pergunta em portugus.
cPerSpa Descrio da pergunta em espanhol.
cPerEng Descrio da pergunta em ingls.
cVar Nome da varivel de controle auxiliar (X1_VARIAVL).
cTipo Tipo do parmetro.
nTamanho Tamanho do contedo do parmetro.
nDecimal Nmero de decimais para contedos numricos.
nPresel Define qual opo do combo a padro para o parmetro.
cGSC Define se a pergunta ser do tipo G Get ou C Choice (combo).
cValid Expresso de validao do parmetro.
cF3 Cdigo da consulta F3 vinculada ao parmetro.
cGrpSxg
Cdigo do grupo de campos SXG para atualizao automtica, quando o grupo
for alterado.
cPyme Se a pergunta estar disponvel no ambiente Pyme.
cVar01 Nome da varivel MV_PAR+Ordem do parmetro.
cDef01 Descrio da opo 1 do combo em portugus.
cDefSpa1 Descrio da opo 1 do combo em espanhol.
cDefEng1 Descrio da opo 1 do combo em ingls.
cCnt01 Contedo padro ou ultimo contedo definido como respostas para este item.
cDef0x Descrio da opo X do combo em portugus.
cDefSpax Descrio da opo X do combo em espanhol.
cDefEngx Descrio da opo X do combo em ingls.
aHelpPor Vetor simples contendo as linhas de help em portugus para o parmetro.
aHelpEng Vetor simples contendo as linhas de help em ingls para o parmetro.
aHelpSpa Vetor simples contendo as linhas de help em espanhol para o parmetro.
cHelp Contedo do campo X1_HELP.

RETINDEX()

A funo RETINDEX() restaura os ndices padres de um alias definidos no Dicionrio
de Dados (SIX).

E Sintaxe: RETINDEX(cAlias)

E Parmetros:
cAlias Alias de um arquivo do sistema existente no Dicionrio de Dados.

E Retorno:

Numrico Indica quantos ndices padres o alias especificado possui no Dicionrio de
Dados.

A funo RETINDEX() quando utilizada em ambientes TOP CONNECT retorna -1

SIXDESCRICAO()

A funo SIXDESCRICAO() retorna a descrio da chave de ndice, de acordo com o
registro posicionado no SIX e idioma corrente.

E Sintaxe: SIXDESCRICAO()

E Parmetros:

Nenhum ()

E Retorno:
String Descrio do indice posicionado no SIX de acordo com o idioma corrente.

Exemplo:

User Function <nome-da-funo>( cChave, cOrdem )
Local cSixDesc :=

dbSelectArea(SIX)
dbSetOrder(1)

If dbSeek(cChave+cOrdem)
cSixDescr := SixDescricao()
EndIf
Return
TABELA()

A funo TABELA() retorna o contedo de uma tabela cadastrada no Arquivo de
Tabelas (SX5) de acordo com a chave especificada. Caso a tabela, ou a chave
especificada, no exista ser exibido um HELP() padro do sistema.

E Sintaxe: Tabela(cTab,cChav,lPrint)

E Parmetros:

cTab Idenficao da tabela a pesquisar (deve ser informado como caracter).
cChav Chave a pesquisar na tabela informada.
lPrint Indica se deve (.T.) ou no (.F.) exibir o help ou a chave NOTAB se a tabela no
existir.

E Retorno:

String Contedo da tabela na chave especificada. Retorna nulo caso a tabela no exista
ou a chave no seja encontrada.

TAMSX3()

A funo TAMSX3() retorna o tamanho (total e parte decimal) de um campo
especificado no Dicionrio de Dados (SX3).

E Sintaxe: TAMSX3(cCampo)

E Parmetros:

cCampo Nome do campo a ser consultado no Dicionrio de Dados (SX3).

E Retorno:

Array Array de duas posies contendo o tamanho total e o nmero de decimais do
campo especificado respectivamente.

TM()

A funo TM() retorna a picture de impresso para valores numricos dependendo do
espao disponvel.

E Sintaxe: TM(nValor, nEdio, nDec)

E Parmetros:

nValor Valor a ser avaliado.
nEdio Espao disponvel para edio.
nDec Nmero de casas decimais.

E Retorno:

String Picture ideal para edio do valor nValor.

Esta rotina leva em considerao duas variveis:

MV_MILHAR Determina se deve haver separao de milhar;
MV_CENT Nmero de casas decimais padro da moeda corrente.

Para ajustar o valor passado (nValor) ao espao disponvel (nEdio) a
funo verifica se pode haver separao de milhar, neste caso, a rotina
eliminar tantos pontos decimais quantos sejam necessrios ao ajuste do
tamanho. Caso no seja possvel ajustar o valor ao espao dado, ser
colocado na picture o caracter de estouro de campo *.A funo tambm
ajusta um valor ao nmero de decimais (nDec), sempre imprimindo a
quantidade de decimais passados no parmetro.

X1DEF01()

A funo X1DEF01() retorna o contedo da primeira definio da pergunta posicionada
no SX1 (caso seja combo) no idioma corrente.

E Sintaxe: X1DEF01()

E Parmetros:

Nenhum ()

E Retorno:

String Contedo da primeira definio da pergunta no idioma corrente.

Exemplo:

User Function <nome-da-funo>( cGrupo, cPerg )
Local cDef01
Local cDef02
Local cDef03
Local cDef04
Local cDef05

dbSelectArea(SX1)
dbSetOrder(1)

If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg.
cDef01 := X1Def01()
cDef02 := X1Def02()
cDef03 := X1Def03()
cDef04 := X1Def04()
cDef05 := X1Def05()
EndIf

Return

X1PERGUNT()

A funo X1PERGUNT() retorna a descrio da pergunta posicionada no Dicionrio de
Dados (SX1) para o idioma corrente.

E Sintaxe: X1PERGUNT()

E Parmetros:
Nenhum ()

E Retorno:
String Descrio da pergunta do Dicionrio de Dados (SX1) no idioma corrente.

Exemplo:

User Function <nome-da-funo>( cGrupo, cPerg )
Local cDescr
dbSelectArea(SX1)
dbSetOrder(1)
If dbSeek( cGrupo + cPerg ) // grupo da pergunta + o numero da perg.
cDescr := X1Pergunt()
EndIf
Return


X2NOME()

A funo X2NOME() retorna a descrio de uma tabela posicionada no Dicionrio de
Dados (SX2) no idioma corrente.

E Sintaxe: X2NOME()

E Parmetros:

Nenhum ()

E Retorno:

String Descrio da tabela posicionada no Dicionrio de Dados (SX2) no idioma
corrente.

Exemplo:

User Function <nome-da-funo>( )
Local cTabela
dbSelectArea(SX2)
dbSetOrder(1)
If dbSeek( SA1 )
cTabela := X2Nome()
EndIf
Return

X3CBOX()

A funo X3CBOX() retorna o contedo de um campo tipo combo posicionado no
Dicionrio de Dados (SX3) no idioma corrente.

E Sintaxe: X3CBOX()

E Parmetros:

Nenhum ()

E Retorno:

String Contedo do campo do tipo combo posicionado no Dicionrio de Dados (SX3)
no idioma corrente.

Exemplo:


Local cTitulo
Local cDescri
Local cCombo

dbSelectArea(SX3)
dbSetOrder(2)

If dbSeek( cCampo )
cTitulo := X3Titulo()
cDescri := X3Descri()
cCombo := X3Cbox()
EndIf

Return

X3DESCRIC()

A funo X3DESCRIC() retorna a descrio de um campo posicionado no Dicionrio de

E Sintaxe: X3DESCRIC()

E Parmetros:

Nenhum ()

E Retorno:

String Descrio do campo posicionado no Dicionrio de Dados (SX3) no idioma
corrente.

Exemplo:


Local cTitulo
Local cDescri
Local cCombo

dbSelectArea(SX3)
dbSetOrder(2)

If dbSeek( cCampo )
cDescri := X3Descri()
cCombo := X3Cbox()
EndIf

Return

X3PICTURE()

A funo X3PICTURE() retorna a mscara de um campo contido no Dicionrio de Dados
(SX3).

E Sintaxe: X3PICTURE(cCampo)

E Parmetros:

cCampo Nome do campo contido no Dicionrio de Dados (SX3).

E Retorno:

String Picture do campo informado.

Exemplo:

User Function <nome-da-funo>( cCampo )

Local cPicture

cPicture := X3Picture( cCampo )
Return cPicture

X3TITULO()

A funo X3TITULO() retorna o ttulo de um campo posicionado no Dicionrio de

E Sintaxe: X3TITULO()

E Parmetros:

Nenhum ()

E Retorno:

String Ttulo do campo posicionado no dicionrio de dados (SX3) no idioma corrente.

Exemplo:


Local cTitulo

dbSelectArea(SX3)
dbSetOrder(2)

If dbSeek( A1_COD )
EndIf

Return

X3USO()
A funo X3USO() verifica se o campo atualmente posicionado no Dicionrio de Dados
(SX3) est disponvel para uso.

E Sintaxe: X3USO( cUsado, [Modulo])

E Parmetros:
cUsado Contedo do campo X3_USADO a ser avaliado.
Modulo Nmero do mdulo. Caso no seja informado ser assumido como padro o
nmero do mdulo corrente.

E Retorno:

Lgico Indica se o campo est configurado como usado no Dicionrio de Dados (SX3).

Exemplo:

User Function <nome-da-funo>()

Local lUsado := .F.

DbSelectArea(SX3)
DbSetOrder(2)
DbSeek(A1_COD)

If X3Uso( SX3->X3_USADO )
lUsado := .T.
EndIf

Return lUsado

X5DESCRI()

A funo X5DESCRI() retorna a descrio de um item de uma tabela posicionado no
Arquivo de Tabelas (SX5) no idioma corrente.

E Sintaxe: X5DESCRI()

E Parmetros:

Nenhum ()

E Retorno:

String Decrio do item do Arquivo de Tabelas (SX5) no idioma corrente.

Exemplo:

User Function <nome-da-funo>( cFilial, cTabela, cChave )
Local cDescr

dbSelectArea(SX5)
dbSetOrder(1)

If dbSeek( cFilial+cTabela+cChave )
cDescr := X5Descri()
EndIf

Return

X6CONTEUD()

A funo X6CONTEUD() retorna o contedo de um parmetro posicionado no
Dicionrio de Dados (SX6) para o idioma corrente.

E Sintaxe: X6CONTEUD()

E Parmetros:

Nenhum ()

E Retorno:

Indefinido Contedo do parmetro posicionado no Dicionrio de Dados (SX6) para o
idioma corrente.

Utilizar preferncialmente as funes de manipulao de parmetros
GETMV() e suas variantes.

Exemplo:

User Function <nome-da-funo>( cFilial, cParam )
Local cDescr
Local cConteud

dbSelectArea(SX6)
dbSetOrder(1)

If dbSeek( cFilial+cParm )
cDescr := X6Descric()
cDescr += X6Desc1()
cDescr += X6Desc2()
cConteud := X6Conteud()
EndIf

Return

X6DESCRIC()

A funo X6DESCRI() retorna o contedo da descrio de um parmetro de acordo
com o registro posicionado no Dicionrio de Dados (SX6) no idioma corrente.

E Sintaxe: X6DESCRIC()

E Parmetros:

Nenhum ()

E Retorno:

String Descrio do parmetro posicionado no Dicionrio de Dados (SX6) no idioma
corrente.

Para avaliar os contedos dos primeiro e segundo complementos da
descrio do parmetro utilize as funes:

X6DESC01() retorna o primeiro complemento da descrio.
X6DESC02() retorna o segundo complemento da descrio.

As trs funes possuem a mesma sintaxe e forma de utilizao.

Exemplo:

User Function <nome-da-funo>( cFilial, cParam )

Local cDescr
Local cConteud

dbSelectArea(SX6)
dbSetOrder(1)

If dbSeek( cFilial+cParm )
cDescr := X6Descric()
cDescr += X6Desc1()
cDescr += X6Desc2()
cConteud := X6Conteud()
EndIf
Return

XADESCRIC()

A funo XADESCRI() retorna o contedo da descrio das pastas de acordo com o
registro posicionado no Dicionrio de Dados (SXA) no idioma corrente.

E Sintaxe: XADESCRIC()

E Parmetros:

Nenhum ()

E Retorno:

String Descrio do folder posicionado no Dicionrio de Dados (SXA) no idioma
corrente.

Exemplo:

User Function <nome-da-funo>( cFolder, cNumero )
Local cDescr
dbSelectArea(SXA)
dbSetOrder(1)
If dbSeek( cFolder+cNumero ) // alias do folder + numero do folder
cDescr := XADescric()
EndIf
Return

XBDESCRI()

A funo XBDESCRI() retorna o contedo da descrio de uma consulta de acordo com
o registro posicionado no Dicionrio de Dados (SXB) no idioma corrente.

E Sintaxe: XBDESCRI()

E Parmetros:

Nenhum ()

E Retorno:

String Descrio da consulta posicionada no Dicionrio de Dados (SXB) no idioma
corrente.

Exemplo:

User Function <nome-da-funo>( cAlias )
Local cDescr
dbSelectArea(SXB)
dbSetOrder(1)
If dbSeek( cAlias + 1 )
cDescr := XBDescri()
EndIf
Return

XFILIAL()

A funo XFILIAL() retorna a filial utilizada por determinado arquivo.

Esta funo utilizada para permitir que pesquisas e consultas em arquivos trabalhem
somente com os dados da filial corrente, dependendo, neste caso do
compartilhamento do arquivo (definio que feita atravs do mdulo Configurador
Dicionrio de Dados (SX2)).

importante verificar que esta funo no tem por objetivo retornar apenas a filial
corrente, mas retorn-la caso o arquivo seja exclusivo. Se o arquivo estiver
compartilhado, a funo xFilial retornar dois espaos em branco.

E Sintaxe: XFILIAL(cAlias)

E Parmetros:

cAlias Alias do arquivo desejado. Se no for especificado, o arquivo tratado ser o da
rea corrente.

E Retorno:

Caracter String contendo a filial do arquivo corrente.

Componentes da interface visual

MSDIALOG()

Define o componente MSDIALOG(), o qual utilizado como base para os demais
componentes da interface visual, pois um componente MSDIALOG() uma janela da
aplicao.

E Sintaxe:

DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO
nLiFim,nColFim OF oObjetoRef UNIDADE

E Parmetros

oObjetoDLG Posio do objeto Say em funo da janela em que ele ser definido.
cTitulo Ttulo da janela de dilogo.
nLinIni, nColIni Posio inicial em linha / coluna da janela.
nLiFim, nColFim Posio final em linha / coluna da janela.
oObjetoRef Objeto dialog no qual a janela ser definida.
UNIDADE Unidade de medida das dimenses: PIXEL

Exemplo:


MSGET()

Define o componente visual MSGET, o qual utilizado para captura de informaes
digitveis na tela da interface.

E Sintaxe:

@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF
oObjetoRef F3 cF3 VALID VALID WHEN WHEN PICTURE cPicture


E Parmetros

nLinha, nColuna Posio do objeto MsGet em funo da janela em que ele ser definido.
VARIAVEL
Varivel da aplicao que ser vinculada ao objeto MsGet, que definir
suas caractersticas e na qual ser armezanado o que for informado no
campo.
nLargura,nAltura Dimenses do objeto MsGet para exibio do texto.
cF3 String que define a consulta padro que ser vinculada ao campo.
VALID Funo de validao para o campo.
WHEN
Condio para manipulao do campo, a qual pode ser diretamente .T. ou
.F., ou uma varivel ou uma chamada de funo.
cPicture String contendo a definio da Picture de digitao do campo.

Exemplo:

@ 010,050 MSGET cCGC SIZE 55, 11 OF oDlg PIXEL PICTURE "@R
99.999.999/9999-99";
VALID !Vazio()

SAY()

Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela
de interface.

E Sintaxe:

@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF
oObjetoRef

E Parmetros

nLinha, nColuna Posio do objeto Say em funo da janela em que ele ser definido.
cTexto Texto que ser exibido pelo objeto Say.
nLargura,nAltura Dimenses do objeto Say para exibio do texto.

Exemplo:

@ 010,010 SAY cTexto SIZE 55, 07 OF oDlg PIXEL

BUTTON()

Define o componente visual Button, o qual permite a incluso de botes de operao
na tela da interface, os quais sero visualizados somente com um texto simples para
sua identificao.

E Sintaxe: BUTTON()

@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE OF
oObjetoRef
ACTION AO

E Parmetros

nLinha,nColuna Posio do objeto Button em funo da janela em que ele ser definido.
cTexto String contendo o texto que ser exibido no boto.
nLargura,nAltura Dimenses do objeto Button para exibio do texto.
AO
Funo ou lista de expresses que define o comportamento do boto
quando ele for utilizado.

Exemplo:

010, 120 BUTTON Confirmar SIZE 080, 047 PIXEL OF oDlg;
ACTION (nOpca := 1,oDlg:End())

SBUTTON()

Define o componente visual SButton, o qual permite a incluso de botes de operao
na tela da interface, os quais sero visualizados dependendo da interface do sistema
ERP utilizada somente com um texto simples para sua identificao, ou com uma
imagem (BitMap) pr-definido.

E Sintaxe: SBUTTON()

DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS OF
oObjetoRet

E Parmetros

nLinha, nColuna Posio do objeto sButton em funo da janela em que ele ser definido.
TYPE N
Nmero que indica o tipo do boto (imagem) pr-definida que ser
utilizada.
AO
Funo ou lista de expresses que define o comportamento do boto
quando ele for utilizado.
STATUS Propriedade de uso do boto: ENABLE ou DISABLE
oObjetoRet Objeto dialog no qual o componente ser definido.

Exemplo:

DEFINE SBUTTON FROM 020, 120 TYPE 2 ACTION (nOpca := 2,oDlg:End());
ENABLE OF oDlg

E Visual dos diferentes tipos de botes disponveis

CHECKBOX()

Define o componente visual CheckBox, o qual permite a utilizao da uma marca para
habilitar ou no uma opo escolhida, sendo esta marca acompanhada de um texto
explicativo. Difere do RadioMenu pois cada elemento do check nico, mas o Radio
permite a utilizao de uma lista junto com um controle de seleo.

E Sintaxe:

@ nLinha,nColuna CHECKBOX oCheckBox VAR VARIAVEL PROMPT cTexto WHEN
WHEN UNIDADE OF oObjetoRef SIZE nLargura,nAltura MESSAGE cMensagem

E Parmetros:

nLinha,nColuna
Posio do objeto ComboBox em funo da janela em que ele ser
definido.
oCheckBox Objeto do tipo CheckBox que ser criado.
VARIAVEL
Varivel do tipo lgico com o status do objeto (.T. marcado, .F.
desmarcado).
cTexto Texto que ser exibido ao lado do get de marcao.
WHEN
Condio para manipulao do objeto, a qual pode ser diretamente .T. ou
.F., ou uma varivel ou uma chamada de funo.
nLargura,nAltura Dimenses do objeto CheckBox.
cMensagem Texto que ser exibido ao clicar no componente.

Exemplo:

@ 110,10 CHECKBOX oChk VAR lChk PROMPT "Marca/Desmarca" SIZE 60,007
PIXEL OF oDlg ;
ON CLICK(aEval(aVetor,{|x| x[1]:=lChk}),oLbx:Refresh())

COMBOBOX()

Define o componente visual ComboBox, o qual permite seleo de um item dentro de
uma lista de opes de textos simples no formato de um vetor.

E Sintaxe:

@ nLinha,nColuna COMBOBOX VARIAVEL ITEMS AITENS SIZE
nLargura,nAltura UNIDADE OF oObjetoRef

E Parmetros:

nLinha,nColuna
Posio do objeto ComboBox em funo da janela em que ele ser
definido.
VARIAVEL
Varivel do tipo caracter que ir receber a descrio do item selecionado
no ComboBox.
AITENS
Vetor simples contendo as strings que sero exibidas como opes do
ComboBox.
nLargura,nAltura Dimenses do objeto ComboBox.

Exemplo:

@ 40, 10 COMBOBOX oCombo VAR cCombo ITEMS aCombo SIZE 180,10 PIXEL
OF oFld:aDialogs[2]

FOLDER()

Define o componente visual Folder, o qual permite a incluso de diversos Dialogs
dentro de uma mesma interface visual. Um Folder pode ser entendido como um array
de Dialogs, aonde cada painel recebe seus componentes e tem seus atributos definidos
independentemente dos demais.

E Sintaxe:

@ nLinha,nColuna FOLDER oFolder OF oObjetoRef PROMPT
&cTexto1,,&cTextoX UNIDADE SIZE nLargura,nAltura


E Parmetros

nLinha,nColuna
Posio do objeto Folder em funo da janela em que ele ser
definido.
oFolder Objeto Folder que ser criado.
&cTexto1,,&cTextoX
Strings de ttulos de cada uma das abas do Folder, sempre
precedidas por &. Exemplo: &Pasta1,&PastaX.
nLargura,nAltura Dimenses do objeto Folder.

Exemplo:

@ 50,06 FOLDER oFld OF oDlg PROMPT "&Buscas", "&Consultas", "Check-
&Up / Botes" PIXEL SIZE 222,078

RADIO()

Define o componente visual Radio, tambm conhecido como RadioMenu, o qual
seleo de uma opo ou de mltiplas opes atravs de uma marca para os itens
exibidos de uma lista. Difere do componente CheckBox, pois cada elemento de check
sempre nico, e o Rdio pode conter um ou mais elementos.

E Sintaxe:

@ nLinha,nColuna RADIO oRadio VAR nRadio 3D SIZE nLargura,nAltura
<ITEMS PROMPT> cItem1,cItem2,...,cItemX OF oObjetoRef UNIDADE ON
CHANGE CHANGE ON CLICK CLICK


E Parmetros

nLinha,nColuna
Posio do objeto Rdio em funo da janela em que ele ser
definido.
oRadio Objeto do tipo Rdio que ser criado.
nRadio Item do objeto Rdio que est selecionado.
3D
Item opcional que define se o RadioButton ter aspecto simples ou
3D.
nLargura,nAltura Dimenses do objeto Rdio.
<ITEMS PROMPT>
Utilizar um dos dois identificadores para definir quais os textos que
sero vinculados a cada RadioButton.
cItem1,cItem2,...,cItemX Texto que ser vinculado a cada RadioButton.
CHANGE
Funo ou lista de expresses que ser executada na mudana de
um item de um RadioButton para outro.
CLICK
Funo ou lista de expresses que ser executada na seleo de
um item RadioButton.

Exemplo:

aAdd( aRadio, "Disco" )
aAdd( aRadio, "Impressora" )
aAdd( aRadio, "Scanner" )

@ 30, 10 RADIO oRadio VAR nRadio ITEMS aRadio[1],aRadio[2],aRadio[3]
SIZE 65,8 ;
PIXEL OF ;
oFld:aDialogs[3] ;
ON CHANGE ;
(Iif(nRadio==1,MsgInfo("Opco 1",cAtencao),;
Iif(nRadio==2,MsgInfo("Opo 2",cAtencao),MsgInfo("Opo
3",cAtencao))))

Interfaces de cadastro

AXCADASTRO()

Sintaxe AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt)
Descrio
O AxCadastro() uma funcionalidade de cadastro simples, com poucas opes
de customizao.

MBROWSE()

Sintaxe MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias)
Descrio
A Mbrowse() uma funcionalidade de cadastro que permite a utilizao de
recursos mais aprimorados na visualizao e manipulao das informaes do
sistema.

AXPESQUI()

Funo de pesquisa padro em registros exibidos pelos browses do sistema, a qual
posiciona o browse no registro pesquisado. Exibe uma tela que permite a seleo do
ndice a ser utilizado na pesquisa e a digitao das informaes que compe a chave
de busca.

E Sintaxe: AXPESQUI()

E Parmetros

Nenhum ()

AXVISUAL()

Funo de visualizao padro das informaes de um registro, no formato Enchoice,
conforme demonstrado no tpico sobre a interface AxCadastro().

E Sintaxe: AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem,
cFunc,; aButtons, lMaximized )

E Parmetros

cAlias Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada
nReg Record number (recno) do registro posicionado no alias ativo.
nOpc
Nmero da linha do aRotina que definir o tipo de edio (Incluso,
Alterao, Excluso, Visualizao).
aAcho
Vetor com nome dos campos que sero exibidos. Os campos de usurio
sempre sero exibidos se no existir no parmetro um elemento com a
expresso "NOUSER".
nColMens Parmetro no utilizado.
cMensagem Parmetro no utilizado.
cFunc
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido
internamente pela AxFunction() executada como .T.
aButtons
Botes adicionais para a EnchoiceBar, no formato:
aArray[n][2] -> bloco de cdigo contendo a ao do boto
lMaximized Indica se a janela dever ser ou no maximizada

AXINCLUI()

Funo de incluso padro das informaes de um registro, no formato Enchoice,

E Sintaxe: AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,;
cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized)

E Parmetros

cAlias Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada.
nOpc
aAcho
Vetor com nome dos campos que sero exibidos. Os campos de usurio
sempre sero exibidos se no existir no parmetro um elemento com a
expresso "NOUSER".
cFunc
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso, o parmetro lVirtual definido
internamente pela AxFunction() executada como .T.
aCpos Vetor com nome dos campos que podero ser editados.
cTudoOk
Funo de validao de confirmao da tela. No deve ser passada como
Bloco de Cdigo, mas pode ser passada como uma lista de expresses,
desde que a ltima ao efetue um retorno lgico:

(Func1(), Func2(), ...,FuncX(), .T. )

lF3
Indica se a enchoice est sendo criada em uma consulta F3 para utilizar
variveis de memria.
cTransact Funo que ser executada dentro da transao da AxFunction().
aButtons
aParam
Funes para execuo em pontos pr-definidos da AxFunction(),
conforme abaixo:
aParam[1] := Bloco de cdigo que ser processado antes da exibio da
interface.
aParam[2] := Bloco de cdigo para processamento na validao da
confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da transao da
AxFunction().
aParam[4] := Bloco de cdigo que ser executado fora da transao da
AxFunction().
aAuto
Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja
informado este array, no ser exibida a tela de interface, e ser executada
a funo EnchAuto().
aAuto[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
aAuto[n][3] := Validao que ser utilizada em substituio as validaes
do SX3
lVirtual
Indica se a Enchoice() chamada pela AxFunction() utilizar variveis de
memria ou os campos da tabela na edio.
lMaximized Indica se a janela dever ser ou no maximizada.

AXALTERA()

Funo de alterao padro das informaes de um registro, no formato Enchoice,

E Sintaxe: AXALTERA(cAlias, nReg, nOpc, aAcho, aCpos, nColMens,
cMensagem,; cTudoOk, cTransact, cFunc, aButtons, aParam, aAuto, lVirtual,
lMaximized)

E Parmetros

Vide documentao de parmetros da funo AxInclui().

AXDELETA()

Funo de excluso padro das informaes de um registro, no formato Enchoice,

E Sintaxe: AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons,
aParam,; aAuto, lMaximized)

E Parmetros
cAlias Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada.
nOpc
cTransact Funo que ser executada dentro da transao da AxFunction().
aCpos Vetor com nome dos campos que podero ser editados.
aButtons
aParam
Funes para execuo em pontos pr-definidos da AxFunction(),
conforme abaixo:
aParam[1] := Bloco de cdigo que ser processado antes da exibio da
interface.
aParam[2] := Bloco de cdigo para processamento na validao da
confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da transao da
AxFunction().
aParam[4] := Bloco de cdigo que ser executado fora da transao da
AxFunction().
aAuto
Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja
informado este array, no ser exibida a tela de interface, e ser executada
a funo EnchAuto().
aAuto[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
aAuto[n][3] := Validao que ser utilizada em substituio as validaes
do SX3
lMaximized Indica se a janela dever ser ou no maximizada.

Interfaces visuais para aplicaes

ALERT()

E Sintaxe: AVISO(cTexto)

E Parmetros

cTexto Texto a ser exibido

AVISO()

E Sintaxe: AVISO(cTitulo, cTexto, aBotoes, nTamanho)

E Retorno: numrico indicando o boto selecionado.

E Parmetros

cTexto Texto do aviso.
aBotoes Array simples (vetor) com os botes de opo.
nTamanho Tamanho (1,2 ou 3).

FORMBACTH()

E Sintaxe: FORMBATCH(cTitulo, aTexto, aBotoes, bValid, nAltura, nLargura )

E Parmetros

aTexto
Array simples (vetor) contendo cada uma das linhas de texto que sero exibidas
no corpo da tela.
aBotoes
Array com os botes do tipo SBUTTON(), com a seguinte estrutura:

{nTipo,lEnable,{|| Ao() }}

bValid (opcional) Bloco de validao do janela.
nAltura (opcional) Altura em pixels da janela.
nLargura (opcional) Largura em pixels da janela.


MSGFUNCTIONS()

E Sintaxe: MSGALERT(cTexto, cTitulo)
E Sintaxe: MSGINFO(cTexto, cTitulo)
E Sintaxe: MSGSTOP(cTexto, cTitulo)
E Sintaxe: MSGYESNO(cTexto, cTitulo)
E Parmetros

cTexto Texto a ser exibido como mensagem.
cTitulo Ttulo da janela de mensagem.
MSGALERT

MSGINFO

MSGSTOP

MSGYESNO

Recursos das interfaces visuais

GDFIELDGET()

A funo GDFIELDGET() retorna o contedo de um campo especificado em uma grid
formada por um objeto do tipo MsNewGetDados() de acordo com a linha da grid
desejada.

E Sintaxe: GDFIELDGET(cCampo, nLinha)

E Parmetros:

cCampo Nome do campo para retorno do contedo.
nLinha Linha da grid que dever ser avaliada.

E Retorno:

Indefinido Contedo do campo especificado de acordo com a linha da grid informada.

GDFIELDPOS()

A funo GDFIELDPOS() retorna a posio de um campo especificado em uma gria
formada por um objeto do tipo MsNewGetDados().

E Sintaxe: GDFIELDPOS(cCampo)

E Parmetros:

cCampo Nome do campo a ser avaliado na grid.

E Retorno:

Numrico Posio que o campo ocupada na grid. Caso o mesmo no exista ser retornado
0.

GDFIELDPUT()

A funo GDFIELDPUT() atualiza o contedo de uma grid formada por um objeto do
tipo MsNewGetDados() de acordo com o campo e linha da grid especificados.

E Sintaxe: GDFIELDPUT(cCampo, xConteudo, nLinha)

E Parmetros:

cCampo Nome do campo a ser atualizado.
xConteudo Contedo que ser atribudo a clula da grid.
nLinha Linha da grid que ser atualizada.

E Retorno:

Nenhum ()

GETMARK()

A funo GETMARK() utilizada em conjunto com a funo MarkBrow(), para retornar o
conjunto de caracteres que sero utilizados para identificar os registros marcados pelo
browse.

E Sintaxe: GETMARK( [lUpper] )

E Parmetros:

lUpper Se verdadeiro (.T.) retorna somente caracteres em maisculos.

E Retorno:

String
Conjunto de caracteres que definem a marca que dever ser utilizada pela
MarkBrowse durante o processamento corrente.

O retorno da funo GETMARK() depende do contedo atual do
parmetro MV_MARCA.

altamente recomendvel limpar o contedo do campo marcado
pela MarkBrowse() ao trmino do processamento, para se evitar
problemas com a reutilizao da marca aps a exausto das
possibilidades de combinao de dois caracteres, o qual o tamanho
padro do campos utilizados para marcao de registros pela
MarkBrowse(), que neste caso somam 1891 possibilidades de 00 a
zz.

Exemplo:

Function <nome-da-funo>( )

Local aCampos := {{'CB_OK' ,,''},;
{'CB_USERLIB' ,,'Usurio'},;
{'CB_TABHORA' ,,'Hora'},;
{'CB_DTTAB' ,,'Data'}}

Private cMarca := GetMark()
Private cCadastro := 'Cadastro de Contrato'
Private aRotina := { { 'Pesquisar' , 'AxPesqui' , 0, 1 }}

MarkBrow( 'SCB', 'CB_OK','!CB_USERLIB',aCampos,,
cMarca,'MarkAll()',,,,'Mark()' )

Return

MARKBREFRESH()

A funo MARKBREFRESH() atualiza a exibio da marca no MarkBrowse(), sendo
utilizada quando algum processamento paralelo atualiza o contedo do campo
definido como controle de marca para os registros em exibio pelo browse.

Este tipo de processamento comum, e normalmente est associonada a clique de
inverter seleo, ou a opes de marcar e desmarcar todas.

A MarkBrowse() atualiza automaticamente a exibio da marca de
registros quando utilizado o browse.

E Sintaxe: MARKBREFRESH()

E Parmetros:

Nenhum ()

E Retorno:

Nenhum ()

READVAR()

A funo READVAR() retorna o nome da varivel ou campo associoado ao objeto do
tipo GET() atualmente selecionado ou em edio.

E Sintaxe: READVAR()

E Parmetros:

Nenhum ()

E Retorno:

String Nome da varivel ou campo associado ao objeto do tipo GET.

Todos os direitos reservados. 0800 709 8100
totvs.com

Programação Advpl2 p10 2009

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Programação Advpl2 p10 2009

Enviado por

Direitos autorais:

Formatos disponíveis

Todos os direitos reservados.

0800 709 8100

Você também pode gostar