Apostila ADVPL Avançado

Programao em ADVPL /
SQL / ASP com
AP5
Programao ADVPL /SQL / ASP
Com Protheus 5.08
Windows NT Server , Windows Workstation, Windows 95/98 e SQL Server so marcas registradas da Microsoft
Corporation.
Banco de Dados Oracle a marca registrada da Oracle Corporation.
Banco de Dados Informix a marca registrada da Informix Corporation.
Banco de Dados Sybase a marca registrada da Sybase Corporation.
Banco de Dados UDB a marca registrada da IBM.
Este material de efeito didtico/suporte e no pode ser reproduzido sem autorizao da MicroSiga.
CopyRight 2001 Microsiga Software S.A.
ndice
1. Introduo ao ambiente Relacional
1.1.
Objetivos
1.2.
Conceitos Bsicos de Banco de Dados
1.3.
Conhecendo a estrutura de Armazenamento dos dados
1.3.1. LOG do Banco de dados
1.3.1.1.
Controle Transacional
Programao em ADVPL / SQL / ASP com AP5

1.3.1.2.
Segurana e Backup
1.3.1.3.
Construindo Querys evitando problemas com estouro da rea de LOG
1.3.2. rea temporria do Banco de Dados
1.4.
Normalizao de Base de Dados
1.5.
MER (Modelo Entidade Relacionamento)
1.6.
Diferenas cruciais entre ambientes DBF e SQL
1.6.1. DBF Trabalha de forma posicional com acesso compartilhado
1.6.2. SQL Trabalha de forma relacional (Teoria dos conjuntos) e o acesso de forma
centralizada
2. TopConnect
2.1.
Informaes gerais
2.2.
Controle de tipo de dados ( Tabela TOP_FIELD )
2.3.
Opes de Visualizar os Eventos (Mensagens de Erros)
2.4.
Sistema de controle de Registros
2.4.1. Portabilidade
2.4.2. Funo da coluna R_E_C_N_O_
2.4.2.1.
Limite de registros
2.4.2.2.
Renumerao da coluna RECNO
2.4.3. Controle dos registros deletados (Coluna D_E_L_E_T_)
2.5.
Constraints do Banco de dados que so criados automaticamente
2.5.1. Criao da Estrutura de tabelas
2.5.2. ndices
2.5.3. Defaults
2.5.4. Problemas com contedo Nulo
2.6.
Manuteno do Banco de dados
2.6.1. Aumentando a performance executando a operao de PACK
2.7.
DBFNTX x TopConnect
2.7.1. ndices de produo
2.7.2. Funes em chaves de ndices
2.7.3. ndices condicionais
2.7.4. Chaves numricas compostas
2.7.5. Expresses de filtro com funes e variveis
2.8.
Comandos
2.8.1. APPEND FROM
2.8.2. COPY TO
2.8.3. USE
2.8.4. BEGIN, COMMIT, ROLLBACK TRANSACTION
2.9.
Funes
2.9.1. TCCANOPEN
2.9.2. TCCONTYPE
2.9.3. TCDELFILE
2.9.4. TCGETDB
2.9.5. TCLINK
2.9.6. TCQUERY
2.9.7. TCQUIT
2.9.8. TCSETCONN
2.9.9. TCSETFIELD
2.9.10. TCSPEXEC
2.9.11. TCSPEXIST
2.9.12. TCSQLERROR
2.9.13. TCSQLEXEC
2.9.14. TCSRVTYPE
2.9.15. TCUNLINK
2.9.16. TCCHKOBJ*
2.9.17. TCEXEERROR*
2.9.18. TCPGMEXE*
2.9.19. TCSYSEXE*
( * )Funes apenas para o TOPConnect rodando em servidores AS/400.
2.10. Performance
2.10.1. Otimizando seu cdigo

2.10.2. Leitura Seqencial
2.10.3. O uso de filtros
2.10.4. Stored Procedures
2.11. Integrao com outros aplicativos
2.11.1. Incluindo registros nas tabelas do SigaProtheus / AP5
2.11.2. Excluindo registros (Sempre Marcar )
2.11.3. Vantagens e Desvantagens
3. Utilitrio importante
3.1.
Instalador de Stored Procedures no Banco de Dados
4. AP5 WEB - CONECTIVIDADE
5. RPC ENTRE O AP5
OUTRAS APLICAES
5.1 A API de comunicao com o AP5

5.2 O Controle ActiveX
6. RPC ATRAVS
DA INTERNET
6.1 O AP5 Server como um servidor Web

6.1.1 Servios de FTP
6.1.1 Servios de HTTP
6.2 Criando funes APL
6.2.1 Exemplo de funo APL
6.3 O ADVPL ASP
6.3.1 Caractersticas do ADVPL ASP
7.
8.
Introduo
Funes em ADVPL para o Protheus 5.07 / 5.08
8.1. FIELDGET()
8.2. FILEDPUT()
8.3. ALIQICMS()
8.4. ASCAN()
8.5. SALVAMENTO DE AREAS
8.6. SETPRINT()
8.7. CRIATRAB()
8.8. GETADVFAL()
8.9. PROCREGUA()
8.10. ACTIVATE DIALOG()
8.11. MBROWSE()
8.12. NCPROC()
1. Introduo ao ambiente Relacional

1.1.
Objetivos
Este curso tem como objetivo treinar e aperfeioar nossos analistas e parceiros quanto confeco de
programas especficos, em ambiente de trabalho com Base de Dados SQL desta forma pretendemos
aumentar a facilidade de manuseio dos componentes envolvidos tanto na anlise e deteco de erros, e
quais possveis aes para san-los, antes de recorrer ao suporte interno. Demonstraremos tambm
como otimizar programas atravs da linguagem SQL em seus RDMAKES e futuras implementaes para
as prximas verses.
Todos os tpicos mencionados podero servir como base de consulta, para escrita de programas e
resoluo de problemas.
1.2.
SQL / ASP com
AP5
Conceitos Bsicos de Banco de Dados

Os conceitos bsicos dos Bancos de Dados relacionais so bem diferenciados dos conhecidos DBF
s. Estes conceitos bsicos so teis principalmente para saber responder eventuais perguntas que
nossos clientes podero efetuar sobre nosso sistema.
SQL quer dizer : Structured Query Language , que foi desenvolvido inicialmente pela IBM
Corporation.
Um banco de dados no trabalha em funo de registros, ou Arquivos como ns estamos
acostumados a ver e fazer em linguagem de programao Clipper. o SQL utiliza a teoria de conjuntos
conhecida pr todos, que tem o objetivo de resolver os problemas dos usurios com comandos
simples, chamados de querys ( Requisio e Alterao de dados ), que utilizam basicamente 4
comandos : SELECT, INSERT, UPDATE, DELETE.
A primeira diferena entre o ambiente SQL e o DBF o fato de criarmos uma rea no disco
(DATABASE) que o prprio banco se encarregara de administrar, no sentido de criar tabelas, ndices,
e todos os objetos envolvidos no sistema. A nomenclatura muda um pouco: ao invs de CAMPOS
temos COLUNAS e ao invs de REGISTROS temos LINHAS.
Os ndices trabalham de forma semelhante ao DBF, e so utilizados com duas finalidades : a de
termos uma chave de acesso extremamente rpida, e de garantirmos uma chave nica em uma
tabela. A partir do momento que indicamos uma chave nica em uma tabela, o prprio banco de
dados passa a garantir que no existir dados duplicados, sem a necessidade de programao para
tal.
Tambm estaro ligados uma tabela especfica os Triggers, e as Foreign Keys ( Chaves
Estrangeiras ). Em cada DataBase tambm estaro armazenadas as Stored Procedures, que so
programas ou funes escritas como qualquer linguagem conhecida ( Clipper, Pascal etc.), s que no
padro ANSI / SQL.
Uma Trigger funciona como um gatilho, s que este disparado no a cada campo alterado, e sim a
cada Incluso, Alterao ou Excluso de uma linha da tabela. Os Triggers tambm so escritos como
as Stored Procedures, ou seja, como um programa qualquer, que pode efetuar qualquer tipo de
validao, atualizao em outras tabelas, etc...
Hoje no utilizamos no Siga PROTHEUS nenhuma Trigger. Em alguns casos especficos em clientes,
as mesmas podero ser utilizadas.
Uma Foreign Key ( Chave Estrangeira ) uma ligao entre tabelas que so criadas nas mesmas.
So estas que garantem que nunca o Cliente X ser excludo se o mesmo tiver movimentos
( Pedidos, Notas , Duplicatas Etc. ), tambm ser garantido que nunca ser includo um Pedido de
Vendas do Cliente Y, se o mesmo no existir.
Este tratamento feito diretamente pelo Banco de Dados, no necessitando qualquer codificao
para isto.
O Siga PROTHEUS/AP5 no trabalha hoje com o conceito de chaves estrangeiras no banco de
dados.
O uso de um Banco de Dados SQL se faz necessrio pela segurana dos dados e pela fcil
recuperao dos mesmos por vrios aplicativos como Siga PROTHEUS / AP5 (TopConnect), Crystal
Reports (ODBC), SigaEIS (BDE), Excel, etc.
SQL / ASP com
AP5
Devido ao controle exercido sobre os dados a performance do banco acaba sendo prejudicada. Nos
prximos tpicos estaremos demonstrando como melhorar e otimizar o SGDB (Sistema Gerenciador
de Banco de Dados) para o melhor aproveitamento do sistema.
Para empresas que fazem uma grande utilizao de banco de dados normalmente encontramos um
profissional chamado DBA (Data Base Administrator), que tem a funo de administrar o banco de
dados, quanto a otimizao, configurao, backups e segurana. Sabemos que na prtica isto s
funciona para empresas grandes, portanto temos que saber o mnimo possvel de cada banco de
dados para podermos identificar problemas e solues que se adequam melhor instalao do
cliente.
1.3.
Conhecendo a estrutura de Armazenamento dos dados
1.3.1.
LOG do Banco de dados
1.3.1.1.
Controle Transacional
Toda e qualquer operao de incluso, alterao ou excluso de registro armazenada

primeiramente na rea de LOG. Se voc faz uma incluso no banco de dados de uma
simples linha o mesmo garante a incluso completa da linha (insero de todas as colunas).
Este fato garantido pela definio no seu banco de dados de uma transao implcita.
Agora vamos supor que voc tenha uma operao que necessite que vrias incluses,
alteraes e excluses realizadas s sejam efetuadas quando todas as operaes tenham
sido efetuadas com sucesso, caso contrrio todas as operaes devem ser canceladas.

Para definio de transao pelo usurio, normalmente se utilizam os comandos BEGIN e
COMMIT , para definir incio e fim de uma transao respectivamente. Para o cancelamento
de um transao sem sucesso normalmente chamamos de ROLLBACK.
A rea de LOG do Banco de dados normalmente definida com 25% do tamanho da rea de
dados, mas este fator depende muito do nmero de usurios e a quantidade de transaes
realizadas em um determinado intervalo de tempo.
1.3.1.2.
Segurana e Backup
Depois que uma transao concluda com sucesso, no indica que a mesma estar sendo
transferida para a rea real dos dados. Este tramite de transferncia chamado de
CheckPoint , este ponto configurvel de acordo o SGDB utilizado. Para bancos de dados de
maior escala, o processo de check point s realizado aps o Backup da rea de LOG.
O LOG tambm utilizado para fazer o backup de grande bancos de dados, guardando
somente as alteraes efetuados em um determinado intervalo de tempo. Em clientes com
base de dados pequenas, no utilizamos este tipo de recurso.
1.3.1.3.
Construindo Querys evitando problemas com estouro da rea de LOG

Conhecendo melhor o processo de gravao do banco de dados, percebemos que quanto
menor for o nmero de operaes de insero, alterao e excluso realizados dentro de
uma transao melhor ser a performance. Banco de dados que possuem grandes
transaes ocasionam problemas de deadlock. Realizao de grandes updates na base de
dados sem informar a clausula Where delimitando um intervalo de linhas a serem
modificados. Na alterao e excluso de linhas, precisamos tomar cuidado sempre com o
intervalo de registros, se for o caso devemos executar vrias vezes o mesmo blocos de
comandos, mudando o intervalo de linhas, deste forma nunca teremos problemas com a
rea de LOG.
1.3.2.
rea temporria do Banco de Dados

Esta rea de utilidade exclusiva do Banco de Dados, a mesma utilizada em situaes que o
SGDB precisa gerar arquivo temporrios para resolver as querys que estamos solicitando,
normalmente operaes que exigem um determinada ordenao no resultado e no existe
nenhum ndice correspondente. Devemos tomar cuidado com querys que necessitem rea de
trabalho, por que elas estaro perdendo mais tempo com i/o de disco.
1.4.
Normalizao de Base de Dados

A normalizao de Base de dados tem como objetivo, definir a estrutura de entidades e seus atributos
eliminando vrios problemas de definio de armazenamento dos dados, que no momento da
implementao sero percebidos. Existe at cinco nveis de normalizao , mas somente utilizamos
at o terceiro nvel, atualmente no existe equipamento capaz de administrar um Banco de dados
normalizado totalmente.
Com a pratica vamos perceber que a normalizao muito boa, mas o seu excesso gera problemas na
programao, portanto temos sempre que fazer o mximo de normalizao mas devemos estar
consciente de quanto conseguiremos de vantagem com isto.
Existe casos que a desnormalizao uma das melhores solues, para facilitar o desenvolvimento da
aplicao ou para ganharmos performance.
A primeira forma normal diz que devemos definir a entidade e seus atributos, e destes atributos
devemos definir um atributo chave de relao.
Ex.: Entidade = Pedido
Atributos = Data Emisso, Produto , Quantidade ,etc.

Neste caso criaremos um campo cdigo que define a sua chave principal de
relacionamento, criaremos o Cdigo. Nunca utilize mais de um coluna agregada com campo chave.(Este
tipo de campo gera vrios problemas na programao SQL)
A segunda forma normal diz que devemos subdividir os atributos que ocorrem mais de que uma vez,
em uma outra entidade.(Esta entidade deve ter um campo chave, atendendo a primeira forma normal).
Ex.: Entidade = Pedido
Atributos = Nmero do Pedido (Chave), Data de Emisso, etc.
Entidade = Itens do Pedido
Atributos = Nmero, item (Nmero+item = chave), Quantidade, etc..
A terceira forma normal diz que devemos eliminar colunas que so concebidas por calculo de outras
colunas de mesma entidade.
Ex.:
1.5.
Entidade =
Atributos =
Pedido
Total do Pedido, Quantidade Total, etc.
MER (Modelo Entidade Relacionamento)

A partir da normalizao podemos definir as relaes estrangeiras de cada tabela, o MER uma
modelo grfico que facilita a visualizao do desenvolvimento de aplicativo. Alm de apresentar todo o
fluxo do dado dentro de um Banco de Dados. No caso do SigaPROTHEUS / AP5 voc ter em mos
toda a estrutura do sistema quase impossvel, nestes casos o modelo feito por mdulo, e os pontos
de integrao so replicados em cada MER do correspondente mdulo.
Sempre que possvel ao desenvolver processos especficos no sistema procure desenhar o MER para
detectar os problemas antes de sair desenvolvendo o produto.
1.6.
Diferenas cruciais entre ambientes DBF e SQL

1.6.1. DBF Trabalha de forma posicional com acesso compartilhado
Quando trabalhamos em um ambiente posicional, vrios regras de programao e definio como
apresentamos acima, no precisam ser cumpridas. E mesmo assim os processos so rpidos e
de fcil manuseio. Este ambiente utiliza o modo Shared de controle de arquivos do sistema
operacional, ou seja, o servidor destes arquivos apenas um mero repositrio de dados, nada
processado no Server. A desvantagem de utilizar estes arquivos normalmente taxada pelo
problemas gerados com erro em arquivos de ndices e o nvel de segurana muito baixo.
1.6.2.
SQL Trabalha de forma relacional (Teoria dos conjuntos) e o acesso de forma

centralizada
Agora quando trabalhamos com Base de Dados Relacional, a estrutura totalmente diferente.
Devemos atender vrias exigncias como controle de acesso ao dado que muito mais restrito, a
programao feita na aplicao deve ser bem otimizada para evitar requisies desnecessrias, o
SGDB precisa utilizar processamento do Servidor para recuperar um dado solicitado pela
aplicao. O Banco de Dados suporta grande capacidade de armazenamento de dados, garantindo
sua integridade como um todo. A desvantagem do Banco de Dados a necessidade de
equipamentos potentes para atender a demanda.
2. TopConnect
2.1.
SQL / ASP com
AP5
Informaes gerais
O TOPConnect foi desenvolvido em linguagem C pela Microsiga e utilizado hoje pelo
SigaPROTHEUS / AP5 atravs da linguagem ADVPL (PROTHEUS Protheus Language). Ele tambm
pode ser utilizado por aplicaes XBASE que queiram trocar a base de dados de DBF para SQL.
Os gerenciadores de banco de dados hoje suportados so:
MS-SQL Server 6.5 e 7.0

Oracle 7.3.4, 8.0.5 e 8i
IBM Universal Database 5.0
DB2/400
Sybase Anywhere
Sybase SQL-Server
Informix
( MSSQL / MSSQL7 )
( ORACLE )
( DB2 )
( AS/400 )
( ANYWHERE / ANYSYB )
( SYBASE )
( INFORMIX )
O TOPConnect composto por um biblioteca replaceble database driver(RDD) e componentes de

comunicao, sendo estes bibliotecas para aplicativos DOS e DLL's para aplicativos Windows. Estas
bibliotecas devem ser linkeditadas com sua aplicao ADVPL para acessar o TOPConnect Server.
Alguns comandos e funes avanadas so disponibilizadas para que seu aplicativo possa usufruir
de todos os benefcios da plataforma cliente servidor, que so apresentados logo em seguida.
2.2.
Controle de tipo de dados ( Tabela TOP_FIELD )

Em um banco existem vrios tipos de dados (CHAR, VARCHAR, FLOAT, NUMBER, etc.) porem para
existir uma unicidade no cdigo do Topconnect alguns dados so armazenados de forma diferente da
definida na tabela SX3, porem a aplicao recebe o dado da forma como definido.
Os tipos de dados que so tratados atualmente so o seguintes:
Campos numricos
Campos Lgicos
- so armazenados em variveis do tipo FLOAT

- so armazenados em variveis do tipo CHAR (0 ou 1)
Campos Data
YYYYMMDD.
SQL / ASP com AP5

- so armazenados em variveis do tipo CHAR com 8 bytes, no formato
Os campo caracter no recebem nenhum tratamento.

A tabela TOP_FIELD contem a descrio de todos os campos NAO-CARACTER, para que o
TopConnect faca a converso dos dados quando da leitura dos mesmos.
Ela alimentada na criao de uma tabela.
Ex.: Tabela SA1010
A1_FILIAL
C
A1_COD
C
A1_LOJA
C
A1_DESC
C
A1_EMISSAO
C
A1_VEND1
C
...
Ex.: Tabela TOP_FIELD
2
6
2
1
8
6
FIELD_TABLE
FIELD_NAME
FIELD_TYPE FIELD_PREC FIELD_DEC
------------------------------------------------------ -------------------------------- ------------------ ------------------ ---------------dbo.SA1010
A1_COMIS
P
5
2
dbo.SA1010
A1_DESC
P
2
0
dbo.SA1010
A1_LC
P
14
2
dbo.SA1010
A1_EMISSAO
D
8
0
dbo.SA1010
A1_MCOMPRA
P
17
2
dbo.SA1010
A1_METR
P
7
2
dbo.SA1010
@@HAS_DFT_VAL@@ X
0
0
...
Neste exemplo vocs percebero que na tabela TOP_FIELD s existe os campo numricos, data e
Lgico (no caso no existe nenhum usado pelo arquivo).
Alerta! : Se voc for utilizar diretamente o Banco de dados voc precisa estar ciente que
um campo numrico armazenado como um tipo float(MSSQL Server), Number(Oracle), etc.
Por exemplo o valor 40,40 no banco pode estar armazenado como 40,39999999. Quando
formos utilizar querys voc deve utilizar a funo TCSETFIELD para resolver esta situao.
(Veja funo TCSETFIELD).
Importante tambm salientar que qualquer modificao efetuada em arquivo SX3 diretamente,
ou seja, sem utilizar o configurador, voc pode Ter problemas com inconsistncia de estrutura
da tabela do Banco de Dados e TOP_FIELD contra o dicionrio de dados. Para resolver este
problema voc dever remover os dados da Tabela do Banco de dados, eliminar a tabela e
deixa-la criar novamente e depois importar os dados via APPEND(Utilize SDU/CFG-AP5), ou
voc pode ajustar o dicionrio de dados manualmente conforme estrutura no Banco de Dados.
2.3.
Opes de Visualizar os Eventos (Mensagens de Erros)
A parte mais importante do Topconnect Manager o gerenciamento das mensagens de erros, estas
mensagens no so do TopConnect mas sim, de cada Banco de Dados, ou seja, se voc obtiver um
erro de Logon o erro que voc receber neste reporte, exatamente a mesma mensagem que o Banco
de Dados estaria informando se voc utilizar um utilitrio do prprio Banco para fazer o Acesso.
Na maioria dos problemas este logo de erros o ponto principal para descobrir o que esta
acontecendo, entre o Topconnect e o Banco de dados. Voc s estar recebendo mensagens se o link
entre o Banco de dados e o Topconnect estiver funcionando.
2.4.
SQL / ASP com
AP5
Sistema de controle de Registros

2.4.1. Portabilidade
Acreditamos que muitos j perguntaro por que da existncia da coluna R_E_C_N_O_ no Banco
de dados, mesmo os que no conhecem esta coluna tem como objetivo manter a portabilidade de
uma Base DBF e Banco ADS para um Banco de Dados qualquer e tambm entre Banco de dados.
Se voc possui sua aplicao trabalhando em DBF , voc pode porta-la independente de
modificaes para uma Base SQL, e se voc j esta em uma base SQL do tipo MSSQL SQL Server
e gostaria de porta-la para ORACLE, voc pode fazer isto sem nenhum problema.
Alerta! : Se voc possui programas especficos desenvolvidos (RDMAKES), voc precisa que os
mesmos estejam desenvolvidos nos padres de compatibilidade exigidos pela Microsiga. Voc
ver mais adiante exemplos de programas e uma apresentao mais completa deste assunto.
2.4.2.
Funo da coluna R_E_C_N_O_

A Coluna R_E_C_N_O_, tem por objetivo principal guardar um nmero seqencial de controle de
registro, mais conhecido como ID (identificador). Este identificador utilizado pela aplicao na
pesquisa e posicionamento de registro.
Esta coluna no possui repetio, ela sempre preenchida com o valor mximo da coluna
R_E_C_N_O_ + 1 nas prximas inseres. Esta operao feita pelo TopConnect , se voc utiliza
outros produtos que fazem insero na Base de Dados do SigaPROTHEUS / AP5 voc deve seguir
as orientaes do Captulo Integraes com outros aplicativos.
2.4.2.1.
Limite de registros
O limite de registros em uma tabela de 2,147,483,648 , este nmero normalmente deve
ser levado em considerao para as tabelas que recebem muita insero de registro
seguidas de muitas excluses fsica do registro.
2.4.2.2.
Renumerao da coluna RECNO

Quando os registros so deletados pelo sistema, os mesmos so apenas marcados,
para excluso fsica acontece em quando executamos a operao que conhecemos com
Pack de registros. Aps esta operao a coluna R_E_C_N_O_ no renumerada. No
existe a necessidade de fazer a renumerao desta coluna, a no ser que voc esteja
perto de estourar o maior nmero possvel nesta coluna. Neste caso voc precisar
extrair os dados do Banco de Dados para uma Base DBF e logo em seguida subir a

Base novamente para o Banco de Dados, automaticamente a coluna R_E_C_N_O_ ser
ajustada.
2.4.3.
Controle dos registros deletados (Coluna D_E_L_E_T_)

Toda excluso de registro feita no Banco de Dados ou em qualquer plataforma do
SigaPROTHEUS / AP5, s feita logicamente, ou seja, o registro marcado como excludo
(delete), e esta marca feita utilizando o campo chamado D_E_L_E_T_ , a mesma preenchida
com (*) Asterisco, caso contrrio a coluna permanece com o contedo em branco.
Alerta! : Quando voc utiliza o comando Set Delet on/off, o TopConnect estar tratando o dado
para voc, mas se voc utiliza querys para recuperao de dados voc dever tratar este coluna
(Mais informaes sobre o tratamento da coluna D_E_L_E_T_ ser apresentado em exemplos de
querys em RDMAKES.
2.5.
Constraints do Banco de dados que so criados automaticamente

2.5.1.
Criao da Estrutura de tabelas

A estrutura de cada tabela do SigaAdvacend criada automaticamente, tendo em vista a no
existncia da mesma no Banco de Dados. Para isto o usurio criado para o TopConnect acessar
o banco de dados precisa Ter permisso de criao de tabelas, de preferncia a permisso de
DBA.
Neste momento a tabela TOP_FIELD estar sendo alimentada com todos os campos numricos,
datas e Lgicos.
Alerta! : Aps o primeiro usurio fazer a conexo com o TopConnect e a parte de verificao de
tabelas j foi executada, as referncias de cada tabela selecionado no .mnu para abertura
estaro em memria no TopConnect, portanto se por acaso alguma tabela for removida
diretamente por um utilitrio do Banco de Dados o TopConnect ter uma informao no
coerente, voc deve reiniciar o servio do Topconnect (Parando / iniciando o Servio).
2.5.2.
ndices
Os ndices so criados imediatamente aps a criao da estrutura das tabelas. Os ndices
criados partem do arquivo de ndices do SigaPROTHEUS / AP5, que o arquivo SINDEX.
Existe um ndice que criado apenas uma vez no momento em que a tabela criada, este ndice
tem como formao do nome = <nome da tabela> + _RECNO , este ndice e sempre composto
da coluna R_E_C_N_O_ e no permite duplicidade.
Alerta!: Nunca remova os ndices das tabelas, principalmente o ndice RECNO que no ser
criado pelo TopConnect quando a tabela j existe. Se voc criou um ndice pelo SINDEX e
depois percebeu que montou errado ou precisa elimina-lo, voc precisa elimin-lo do SINDEX e
tambm do Banco de Dados.
2.5.3.
Defaults
So constraints de validao de campos que no so informados, nos comandos de insero e
alterao, ou seja, se voc no possui os defaults criados o Banco de Dados estar deixando
estes campos com valor nulo. Os defaults so criados no momento da criao das tabelas.
Alerta!: Se voc fizer qualquer operao de transferncia via Banco de Dados que no transfira
os Defaults, e logo em seguida voc utilizar o sistema , estar correndo risco de inserir nulos na
Base de Dados. Se isto acontecer voc poder Ter problemas com o TopConnect Server, ele
poder travar ou derrubar conexes com dados indevidos. A soluo neste caso utilizar o
utilitrio DEFAULT que esta disponvel no site da Microsiga.

Este um exemplo de script para MSSQL Server que o TopConnect estar
disparando para o Banco de Dados quando a tabela SA1990 no existir no Banco.
CREATE TABLE [dbo].[SA1990] (
[A1_FILIAL] [varchar] (2) NULL ,
[A1_COD] [varchar] (6) NULL ,
[A1_LOJA] [varchar] (2) NULL ,
[A1_NOME] [varchar] (40) NULL ,
[A1_NREDUZ] [varchar] (20) NULL ,
[A1_TIPO] [varchar] (1) NULL ,
...
[D_E_L_E_T_] [varchar] (1) NULL ,
[R_E_C_N_O_] [int] NULL
)
GO
CREATE UNIQUE CLUSTERED INDEX [SA1990_RECNO] ON [dbo].[SA1990]([R_E_C_N_O_]) ON
[PRIMARY]
GO
ALTER TABLE [dbo].[SA1990] WITH NOCHECK ADD
CONSTRAINT [DF__SA1990__A1_FILIA__06648751] DEFAULT (' ') FOR [A1_FILIAL],
CONSTRAINT [DF__SA1990__A1_COD__0758AB8A] DEFAULT ('
') FOR [A1_COD],
CONSTRAINT [DF__SA1990__A1_LOJA__084CCFC3] DEFAULT (' ') FOR [A1_LOJA],
CONSTRAINT [DF__SA1990__A1_NOME__0940F3FC] DEFAULT ('
') FOR [A1_NOME],
CONSTRAINT [DF__SA1990__A1_NREDU__0A351835] DEFAULT ('
') FOR [A1_NREDUZ],
CONSTRAINT [DF__SA1990__A1_TIPO__0B293C6E] DEFAULT (' ') FOR [A1_TIPO],
...
CONSTRAINT [DF__SA1990__D_E_L_E___6E57F396] DEFAULT (' ') FOR [D_E_L_E_T_],
CONSTRAINT [DF__SA1990__R_E_C_N___6F4C17CF] DEFAULT (0) FOR [R_E_C_N_O_]
GO
CREATE INDEX [SA19901] ON [dbo].[SA1990]([A1_FILIAL], [A1_COD], [A1_LOJA], [R_E_C_N_O_]) ON
[PRIMARY]
GO
CREATE INDEX [SA19902] ON [dbo].[SA1990]([A1_FILIAL], [A1_NOME], [A1_LOJA], [R_E_C_N_O_]) ON
[PRIMARY]
GO
CREATE INDEX [SA19903] ON [dbo].[SA1990]([A1_FILIAL], [A1_CGC], [R_E_C_N_O_]) ON [PRIMARY]
GO
CREATE INDEX [SA19904] ON [dbo].[SA1990]([A1_FILIAL], [A1_TEL], [R_E_C_N_O_]) ON [PRIMARY]
GO
2.5.4.
Problemas com contedo Nulo

Os Bancos de dados possuem o contedo nulo para todos os tipo de campos, mas o nosso
sistema no os utiliza, se por ventura qualquer tabela tenha algumas linhas com alguma coluna
com o valor nulo, isto pode provocar problemas que aparentam ser erro de ndice, como ex. Voc
tem a tabela de pedidos que com os pedidos 000001,000002 e sua tabela por qualquer motivo
no tem os contraints de defaults na coluna filial, agora voc faz a insero do pedido 0000003 o
sistema ir apresentar um Browse ordenado por pedido da seguinte forma:
Considere a filial do arquivo de pedido de forma compartilhada.(Filiial=Branco)
Filial Pedido
--------- -----------Null
000003
000001
000002
Neste exemplo voc percebe que o pedido 000003 aparece em primeira ordem, sendo o ndice
filial+pedido, ou seja, o valor nulo na tabela ASCII(Binary Order) aparece antes do caracter
espao em branco.

Este problema muitas vezes causa a impresso que o ndice esta com problemas, por que a
tela de Browse do SigaPROTHEUS / AP5 no apresenta a coluna filial.
Alerta!: Tabelas com contedo nulo, geram vrios problemas no sistema, provavelmente deve
gerar erros no TopConnect que o mesmo estar derrubando as conexes quando elas fizerem
acesso a este tipo de contedo (nulo). Existe um utilitrio que ajusta este problema se voc o
tiver, o mesmo esta disponvel no site da Microsiga, com o nome de DEFAULT.exe
2.6.
Manuteno do Banco de dados

2.6.1. Aumentando a performance executando a operao de PACK
Esporadicamente voc deve fazer uma manuteno no Banco de dados, quanto as registros
excludos logicamente, os mesmo devem ser excludos fisicamente, por que a sua existncia em
grande quantidade e de forma seqencial gera um grave problema de performance no acesso aos
dados.
Alerta!: Se voc tiver este problema, utilize a operao de Pack do utilitrio SDU na tabela que
possui registros excludos , ou utilize o programa fonte PACK para fazer esta operao em todas as
tabelas.
Segue abaixo exemplo de fonte em RDMAKE, para fazer um pack em qualquer Banco de dados.
Exemplo de fonte em ADVPL para executar um Pack no Banco de Dados , esta rotina j prev
problema de estouro da rea de LOG/RollBack de um Back de Dados
/*
Funo PACK
Autor Emerson/Vicente
Data 16.12.99
Descrio Rotina RDMAKE para eliminar os registros deletados do banco
Uso
RDMake <Programa.Ext> -w
Exemplo RDMake Pack.prw
*/
@ 96,42 TO 323,505 DIALOG oDlg5 TITLE "Rotina de Pack"
@ 8,10 TO 84,222
@ 91,168 BMPBUTTON TYPE 1 ACTION Execute(OkProc)
@ 91,196 BMPBUTTON TYPE 2 ACTION Close(oDlg5)
@ 23,14 SAY "Este programa ira fazer um pack em todos arquivos abertos pelo PROTHEUS."
ACTIVATE DIALOG oDlg5
Return nil
Function OkProc
Close(oDlg5)
Processa( {|| Execute(RunProc) } )
Return
/*
Funcao RunProc
Descrio Executa o Processamento
*/
Function RunProc
DbSelectArea("SX2")
NrecnoSX2 := SX2->(Recno())
DbGoTop()
ProcRegua(reccount())
While !Eof()
If Select(SX2->X2_CHAVE) > 0
cQuery := 'SELECT MAX(R_E_C_N_O_) RECNO FROM ' + SX2->X2_ARQUIVO
dbUseArea(.T., "TOPCONN", TCGenQry(,,cQuery), 'CONT', .F., .T.)
nCont := 1
While nCont <= CONT->RECNO
cQuery := "DELETE FROM "+SX2->X2_ARQUIVO
cQuery := cQuery + " WHERE D_E_L_E_T_ = '*'"
cQuery := cQuery + " AND R_E_C_N_O_ between "+Str(nCont)+" AND +Str(nCont+1024)
nCont := nCont + 1024
TCSQLEXEC(cQuery)
Enddo
DbSelectArea("CONT")
DbCloseArea()
Endif
DbSelectArea("SX2")
dbSkip()
incproc()
Enddo
SQL / ASP com
AP5
return
2.7.
DBFNTX x TopConnect
2.7.1. ndices de produo
Todos os SGDB's utilizam o conceito de ndices de produo portando uma aplicao que utilize o
TOPConnect no necessita ter todos os ndices abertos para que os mesmos sejam atualizados.
2.7.2.
Funes em chaves de ndices

Devido ao fato de os SGDB's no suportarem o uso de funes nos ndices o TOPConnect no tem
como suportar este tipo de implementao.
As nicas funes suportadas so STR e DTOS.
Para a criao de ndices que contenham campos caracter e numricos na chave apenas uma
regra deve ser obedecida. A funo STR deve obrigatoriamente receber como parmetros valores
idnticos a definio da tabela.
Exemplo:
Em um arquivo com a seguinte estrutura:
CAMPO1 Caracter de 10 posies.
CAMPO2 Numrico de 14 Posies com 2 decimais.
Para se criar um ndice que ordene o arquivo por CAMPO1 + CAMPO2 dever o seguinte comando
ser utilizado:
INDEX ON CAMPO1+STR(CAMPO2,14,2) TO ARQIND
No caso do SigaPROTHEUS voc deve colocar o ndice na tabela SINDEX.
2.7.3.
ndices condicionais
Nos gerenciadores de banco de dados no existe a figura dos ndices condicionais.
Para se obter resultados semelhantes aos ndices condicionais o TOPConnect agregou nova
funcionalidade ao filtro do SigaPROTHEUS / AP5.
Considere uma aplicao que crie o seguinte ndice:
INDEX ON CODIGO,NOME FOR ESTADO = "SP" AND SALDO > 10000
Com o TOPConnect este ndice seria o mesmo que:
SET FILTER TO ESTADO = "SP" .AND. SALDO > 10000 .AND. ORDERBY(CODIGO,NOME)
dbSetOrder(0)
O TOPConnect permite o uso da funo OrderBy nos filtros o que reproduz o mesmo efeito de um
ndice filtrado.
O TOPConnect disponibiliza os dados na ordem solicitada pela clusula OrderBy na Ordem 0 do
arquivo, no interferindo assim com os ndices do arquivo.
2.7.4.
Chaves numricas compostas

Os SGDB's no suportam ndices que contenham expresses ADVPL onde dois campos numricos
so somados na chave.
Exemplo:
INDEX ON CPOVAL1 + CPOVAL2 TO ARQIND
2.7.5.
SQL / ASP com
AP5
Expresses de filtro com funes e variveis

Uma vez que o TOPConnect utiliza a arquitetura Cliente/Servidor o servidor no tem como avaliar o
contedo de uma varivel de memria ou o retorno de uma funo do cliente.
O TOPConnect permite a utilizao de variveis e funes nos filtros porm necessrio ter em
mente que a avaliao deste filtro ocorrer no cliente e no no servidor o que poder resultar em
problemas de performance.
Analisando o seguinte filtro :
SET FILTER TO CODIGO > "01000" .AND. CODIGO < "02000"
Este filtro contem apenas campos e constantes o que permite que sua avaliao seja feita no
servidor e que apenas os registros que obedeam ao filtro venha para o cliente.
Agora este:
SET FILTER TO CODIGO > RetornaCodigo()
Considerando que RetornaCodigo uma funo ADVPL da aplicao todas as linhas deste arquivo
sero avaliadas no cliente.
Visando minimizar os problemas de performance o TOPConnect conta com um sistema chamado
SFE (Smart Filter Engine) o que faz com que o mximo possvel de uma expresso seja avaliada
no servidor.
Pr exemplo:
SET FILTER TO ESTADO = 'SP' .AND. SALDO > 10000 .AND. CODIGO > RetornaCodigo()
Nesta expresso somente viro para o cliente os registros onde os campos ESTADO e SALDO
obedeam ao filtro e ento o campo CODIGO ser avaliado no cliente.
2.8.
Comandos
Neste captulo mencionaremos apenas os comandos da linguagem ADVPL que tem a sua funcionalidade
alterada ou complementada e os novos comandos implementados pelo TOPConnect via RDD.
Para a utilizao destes comandos o programa dever conter a seguinte instruo:
#INCLUDE "TOPCONN.CH"
2.8.1.
APPEND FROM
Em uma aplicao ADVPL o comando APPEND FROM utilizado para se inserir registros na
Work Area corrente com registros vindos de outro arquivo DBF.
No TOPConnect o comando APPEND FROM importara registros de um arquivo DBF para uma
tabela do banco de dados.
No ADVPL opcionalmente poder ser especificado o parmetro VIA "TOPCONN" o que far com
que registros de uma tabela sejam inseridos na Work Area corrente.
Exemplo
SELECT CLIENTES
//Importa registros de um DBF
APPEND FROM c:\temp\newcli.dbf
Ou
SELECT CLIENTES
//Importa registros da tabela NEWCLI
APPEND FROM NEWCLI VIA "TOPCONN"
2.8.2.
COPY TO

Em uma aplicao ADVPL o comando COPY TO utilizado para se copiar a estrutura e os
registros da Work Area corrente para um arquivo DBF.
No TOPConnect o comando COPY TO utilizado para exportar a estrutura e os registros de uma
tabela do banco de dados para um arquivo DBF.
Assim como no comando APPEND FROM no ADVPL o parmetro opcional VIA tambm pode ser
especificado.
2.8.3.
USE
Abre uma tabela no banco de dados.
Sintaxe:
USE [<xcTable>
[INDEX <xcIndex list>]
[ALIAS <xcAlias>] [EXCLUSIVE | SHARED]
[NEW] [READONLY]
VIA "TOPCONN"
<cTable>
O nome da tabela a ser aberta.
INDEX <cIndex List> Especifica o nome de 1 a 15 ndices a serem abertos na Work Area
corrente.
ALIAS < cAlias>
Especifica um nome para a Work Area onde a tabela ser aberta
EXCLUSIVE Especifica que apenas este usurio ter acesso a esta tabela. Todas as outras
tentativas de colocar esta mesma tabela em uso falharo.
SHARED
Especifica que a tabela ser aberta em modo compartilhado.
NEW Abre a tabela <cTable> na prxima Work Area disponvel. Se esta clausula no for
especificada, <xcTable> ser na Work Area corrente.
READONLY
Abre <cTable> apenas para leitura.
VIA "TOPCONN"
Este parmetro indica ao ADVPL que esta Work Area ser gerenciada
pelo TOPconnect.
Se nenhum parmetro for especificado a tabela aberta na Work Area corrente ser fechada.
Exemplo
//Abre a tabela de Clientes em uma nova Work Area
USE clientes SHARED NEW VIA "TOPCONN"
2.8.4.
BEGIN, COMMIT, ROLLBACK TRANSACTION

Marca o incio de uma transao no banco de dados.
Desde o ponto em que uma aplicao executa um BEGIN TRANSACTION cada APPEND ou
REPLACE encontrado at um COMMIT TRANSACTION ou ROLLBACK TRANSACTION sero
considerados uma nica transao.
Os demais usurios somente tero acesso aos novos registros ou s modificaes aps um
COMMIT TRANSACTION
Exemplo
SELECT CLIENTES
if !Rlock()
Alert("Registro em uso!")
Return .f.
Endif
BEGIN TRANSACTION
//Atualiza saldo no cadastro de clientes
REPLACE SALDO WITH SALDO nValor
Programao em ADVPL / SQL / ASP com

//Adiciona um pedido
AP5
SELECT PEDIDOS
APPEND BLANK
REPLACE NUM WITH cNumero
REPLACE VALOR WITH nValor
SELECT ITEMS
APPEND BLANK
REPLACE QUANT WITH nQuant
.....
APPEND BLANK
REPLACE QUANT WITH nQuant
.....
COMMIT TRANSACTION
2.9.
Funes
2.9.1. TCCANOPEN
Verifica a existncia de tabelas e ndices no servidor.
Sintaxe
TCCanOpen(cTable [, cIndice]) =>lgico
Exemplo
//Testa a existncia da tabela customer
IF !TCCanOpen("CUSTOMER")
dbCreate("CUSTOMER", aStru, "TOPCONN")
ENDIF
USE CUSTOMER SHARED NEW VIA "TOPCONN"
//Testa a existncia do ndice
IF !TCCanOpen("CUSTOMER","CUSTCOD")
INDEX ON CODIGO TO CUSTCOD
ELSE
SET INDEX TO CUSTCOD
ENDIF
...
2.9.2.
TCCONTYPE
Especifica o protocolo de comunicao a ser utilizado pelo TOPConnect.
Sintaxe
TCConType(<cType>)
Onde <cType> pode ser:
TCPIP Utiliza o protocolo TCP/IP.
NPIPE Utiliza o protocolo Named Pipes.
APPC Utiliza o protocolo APPC.

BRIDGE
Utiliza o utilitrio TOPBrigde para comunicao de estaes DOS NPIPE com
servidor AS/400 utilizando TCP/IP.
Exemplo
//Especifica conexo TCP/IP
TCConType("TCPIP")
//Conecta-se ao ambiente SIGAADV no Microsoft SQL-Server
TCLink("MSSQL/SIGAADV")
2.9.3.
TCDELFILE
Exclui uma tabela no servidor.
Sintaxe
TCDelFile(<cTable>)
Onde <cTable> o nome da tabela a ser excluda.
Exemplo
TCDelFile("CUSTOMER")
2.9.4.
TCGETDB
Retorna o Tipo de Banco de Dados corrente
cDataBase := TCGETDB()
Onde os valores de retorno so :
MSSQL
MSSQL7
ORACLE
DB2
SYBASE
ANYWHERE
ANYSYBASE
INFORMIX
2.9.5.
Microsoft SQL-Server 6.5

Oracle
IBM Universal Database
Sybase SQL-Server
Sybase SQL Anywhere
Sybase SQL Anywhere
(Emulando Sybase SQL-Server)
Informix
TCLINK
Abre uma conexo com o Servidor TOPConnect.
Sintaxe
nCon := TCLink(<cConectString>,<cServer>)
Onde o parmetro <cConnectString> composto por:
Para TOPConnect NT : Nome do Banco de Dados / Nome do Ambiente
Para TOPConnect/400: Nome do Ambiente
O parmetro <cServer> contm:
Para conexes NamedPipe, APPC e Brigde : O nome do servidor TOPConnect
Para conexes TCP/IP : O endereo IP do servidor TOPConnect
Para o TOPConnect NT acessando Oracle, um ambiente o nome do Alias criado com o utilitrio
SQL-Net.
Para o TOPConnect NT acessando os demais SGDB's um ambiente um System DSN criado
atravs do ODBC Data Source Administrator.

Para o TOPConnect AS/400 um ambiente uma Library criada atravs do comando
CRTTOPENV do TOPConnect.
Para informaes sobre a criao de ambientes consulte o manual de instalao do
TOPConnect.
Esta a lista de Bancos de Dados hoje suportados e seus respectivos nomes compor a string de
conexo com o TOPConnect NT:
MSSQL
MSSQL7
Oracle
ORACLE
IBM Universal Database
DB2
Sybase SQL-Server
SYBASE
Sybase SQL Anywhere
ANYWHERE
Sybase SQL Anywhere
(Emulando Sybase SQL-Server) ANYSYBASE
Informix
INFORMIX
A funo TCLink retorna ou o nmero da conexo ou um valor negativo contendo o cdigo do
erro.
Exemplo
//Conecta-se ao Microsoft SQL-Server no ambiente SIGAADV
//Protocolo Named Pipes
TCConType("NPIPE")
nCon := TCLink("MSSQL/SIGAADV","TOPSRV")
if nCon < 0 //Conexes com retorno < 0 significam erro
Alert("Falha de conexo com o TOPConnect")
endif
//Protocolo TCP/IP
TCConType("TCPIP")
//Conecta-se ao Oracle no ambiente TESTES
nCon := TCLink("ORACLE/TESTES",172.16.1.2)
//Protocolo APPC
//Conecta-se ao AS/400 no ambiente PRODUCAO
nCon := TCLink("PRODUCAO","TOP400")
2.9.6.
SQL / ASP com
AP5
TCQUERY
Executa uma Query no servidor e coloca seu retorno em uma WorkArea.
Sintaxe:
TCQUERY [<cSQLExpr>
[ALIAS <xcAlias>]
[NEW]
VIA "TOPCONN"
<cSQLExpr> Expresso SQL a ser enviada ao servidor.
ALIAS < cAlias>
Especifica um nome para a Work Area a ser aberta
NEW Abre a tabela <cTable> na prxima Work Area disponvel. Se esta clausula no for
especificada, <xcTable> ser na Work Area corrente.
VIA "TOPCONN"
Este parmetro indica ao ADVPL que esta Work Area ser gerenciada
pelo TOPconnect.
A Work Area criada com o comando TCQUERY READ-ONLY, portanto no permitido o uso de
APPEND's ou REPLACE's.
O TOPConnect tem apenas um cursor para a Query executada portando apenas os seguintes
comandos so suportados em uma Work Area criada com TCQUERY:
GO TOP - DbGoTop()
GO BOTTOM - DbGoBottom()
SKIP - DbSkip()
Eof()
Bof()
Obs: Ao executar uma Query que retorne um ou mais valores calculados, o nome dos campos da
WorkArea sero COLUMN1, COLUMN2... COLUMNn.
Exemplo
//Abre a tabela de Clientes em uma nova Work Area
cQuery := "SELECT a.codigo, b.nome FROM CLIENTES a, CLIDATA b ; WHERE a.CODIGO =
b.CODIGO ORDER BY CODIGO,NOME"
TCQUERY cQuery ALIAS CLIENTES NEW VIA "TOPCONN"
dbGoTop()
While !Eof()
? CODIGO,NOME
dbSkip()
end
USE
cQuery := 'SELECT SUM(VALOR),SUM(SALDO) FROM CUSTOMER'
TCQUERY cQuery NEW VIA "TOPCONN"
?COLUMN1 //Somatoria dos valores
?COLUMN2 //Somatoria dos saldos
2.9.7.
TCQUIT
Encerra todas as conexes com o TOPConnect
Sintaxe
TCQuit()
2.9.8.
TCSETCONN
Seleciona conexo ativa.
Sintaxe
TCSETCONN(<nConn>)
Onde <nConn> o nmero da conexo.
Exemplo

// Abre conexo com o ambiente de Produo
nCon1 := TCLink("MSSQL/PRODUCAO")
if nCon1 < 0
Alert("Falha conectando ambiente de Produo")
QUIT
endif
// Abre conexo com o ambiente de Testes
nCon2 := TCLink("MSSQL/TESTES")
if nCon2 < 0 then
Alert("falha conectando ambiente de Testes")
QUIT
endif
TCSetConn(nCon1)
//Abre tabela de Clientes no ambiente de produo
USE CUSTOMER ALIAS PROD SHARED NEW VIA "TOPCONN"
TCSetConn(nCon2)
//Abre tabela de Clientes no ambiente de testes
USE CUSTOMER ALIAS TEST SHARED NEW VIA "TOPCONN"
...
2.9.9.
TCSETFIELD
Esta funo serve como apoio ao comando TCQUERY, na recuperao de campos tipo
NUMERIC, DATE e LOGICAL, pois os mesmos so gravados fisicamente no Banco de Dados
como caracteres, e no caso dos numricos como float.
Sintaxe
TCSetField(<cAlias>, <cField> ,<cType>, [<Prec.Inteira>,<Prec.Decimal>] )
Onde <cAlias> o alias da WorkArea, <cField> o nome do campo e <cType> o
tipo desejado para o campo.
Exemplo
TCQUERY "SELECT NOME, DATA, MARRIED, VALOR FROM CUSTOMER" ALIAS QUERY VIA
"TOPCONN"
TCSetField("QUERY","DATA","D")
TCSetField("QUERY","VALOR","N",12,2)
Dentro de um programa ADVPL j podemos considerar como um campo data no mais um
campo caracter como o seu armazenamento.
O campo Data s retornado como um campo caracter por que estamos utilizando a funo
TCQUERY, se no o tratamento automtico.
2.9.10. TCSPEXEC
Executa uma Stored Procedure no Banco de Dados.
Devido a uma limitao em alguns dos Bancos de Dados suportados na obteno dos tipos de
parmetros (se so de INPUT e/ou OUTPUT) todos as Stored Procedures a serem executadas
atravs do TOPConnect devero obedecer o seguinte padro de nomenclatura de seus
parmetros :
Parmetros de INPUT devem comear com IN_... Ex. IN_VALOR.
Parmetros de OUTPUT devem comear com OUT_... Ex. OUT_CODIGO
SQL / ASP com
AP5
Aps a execuo de uma Stored Procedure o TOPConnect retornar ao ADVPL um array com 'n'
elementos, onde n o nmero de parmetros de OUTPUT da Stored Procedure.
Sintaxe
<aRet> := TCSPExec(<cSPName>,[<xParam1>,<xParam2>...<xParamN>])
Onde <aRet> um array com os parmetros de retorno da Stored Procedure e <cSPName> o
nome da Stored Procedure a ser executada e os demais parmetros variam conforme a definio
da Stored Procedure.
Exemplo
//Verifica se a Stored Procedure Teste existe no Servidor
If TCSPExist("TESTE")
//Executa a Stored Procedure Teste
aRet := TCSPExec("TESTE","JOSE",1000)
if aRet <> nil
For i:= 1 to Len(aRet)
//Mostra os valores de retorno
?aRet[i]
Next
Else
?"Erro executando Stored Procedure"
?"Mensagem: "+TCSQLError()
Endif
EndIf
2.9.11. TCSPEXIST
Verifica a existncia de uma determinada Stored Procedure no servidor.
Sintaxe
<lExist> := TCSPExist(<cSPName>)
Onde <lExist> indica se a Stored Procedure existe ou no e <cSPName> o nome da Stored
Procedure procurada.
Exemplo
If SPExist("CALCCUSTO")
TCSPExec("CALCCUSTO")
Endif
2.9.12. TCSQLERROR
Retorna o ltimo erro registrado pelo TOPConnect durante a execuo de uma Query.
Sintaxe
<cError> := TCSQLError()
Onde <cError> a mensagem de erro.
Exemplo
If TCSQLExec("UPDATE CUSTOMER SET VALUE=0") < 0 then
?TCSQLError()
Endif
OBS: Esta a mesma mensagem que esta registrada no log de eventos do TopConnect
Manager.
2.9.13. TCSQLEXEC

Executa comandos SQL no servidor.
Sintaxe
<nRet> := TCSQLExec(<cCommand>)
Onde <nRet> retorna um valor negativo em caso de erros e <cCommand> e o comando SQL a
ser executado.
Exemplo
TCSQLExec("UPDATE CUSTOMER SET VALUE=0)
2.9.14. TCSRVTYPE
Retorna o Tipo do Servidor onde esta sendo executado o TOPConnect.
Sintaxe
<cType> := TCSrvType()
Onde <cType> o tipo do servidor podendo Ter seu contedo igual a "WinNT" ou "AS/400".
Exemplo
TCLink("MSSQL/TESTE","TOPSRV")
?TCSrvtype()
2.9.15. TCUNLINK
Encerra uma conexo com o TOPConnect.
Sintaxe
TCUnlink(<nConn>)
Onde <nConn> o nmero da conexo retornado pela funo TCLink()
Exemplo
TCConType("NPIPE")
nConn := TCLink("MSSQL/TOPCONN","TOPSRV")
TCUnLink(nConn)
2.9.16. TCCHKOBJ*
Verifica a existncia de um objeto no servidor AS/400
Sintaxe
<nError> := TCChkObj(<cObj>,<cLibrary>,<cType>)
Onde:
<nError> 0 quando o objeto existe ou o nmero do erro no AS/400.
<cLibrary> o nome da biblioteca que deve conter o objeto.
<cType> o tipo de objeto AS/400. Ex: *FILE, *PGM, etc.
Exemplo
nError := TCChkObj("CALCCUST","PRODUCAO","*PGM")
ESTA FUNO SE APLICA APENAS PARA O TOPCONNECT AS/400
2.9.17. TCEXEERROR*
Retorna uma string com a mensagem de erro retornada pela execuo das funes
TCPGMEXE() e TCSYSEXE().
Sintaxe
<cError> := TCExeError()
Onde <cError> a string com a mensagem de erro.
Exemplo

?TCExeError()
AP5

2.9.18. TCPGMEXE*
Executa um programa no servidor AS/400
TCPGMEXE( program name )
2.9.19. TCSYSEXE*
cCommand := "CRTCBLMOD MODULE("+cTDataBase+"/"+
cCommand += "SRCFILE("+cTDataBase+"/QSPSRC) "
cCommand += "SRCMBR("+cName+"F"+cCrrEmp+") "
cCommand += "REPLACE(*YES)"
cName+"F"+cCrrEmp+") "
TCSysExe( cCommand )
2.10. Performance
2.10.1. Otimizando seu cdigo
A linguagem ADVPL tem um enfoque posicional, recuperando os dados utilizando orientao a
registros, enquanto aos Bancos de Dados SQL recuperam os dados por blocos de dados.
Devido a esta diferena conceitual, vrios pontos devem ser levados em considerao para que
se possa obter uma boa performance e utilizar os recursos de uma aplicao Client/Server.
2.10.2. Leitura Sequencial
Operaes de leitura seqencial de uma tabela podem levar a problemas de performance.
Vamos analisar o seguinte cdigo:
dbSelectArea("CLIENTES")
nValor := 0
Do While !Eof()
If ESTADO = "SP"
nValor += SALDO
Endif
DbSkip()
End
O cdigo acima far com que todas as linhas(registros) da tabela venham para o Client, o que ir
gerar um nmero de Queries no servidor igual ao nmero de linhas da tabela e cada uma delas
ir recuperar apenas uma linha, subtilizando a capacidade de processamento do servidor.
O cdigo acima poderia ser substitudo por:
TCQUERY "SELECT SUM(SALDO) ;
FROM CLIENTES ;
WHERE ESTADO = 'SP'" NEW
nValor := COLUMN1
Com a utilizao do comando TCQUERY todo a somatria feita no servidor retornando assim
para a aplicao apenas uma linha com o resultado desejado.
2.10.3. O uso de filtros

O uso de filtros em aplicaes ADVPL so conhecidos como fonte de problemas de performance.
Isto se deve ao fato de que todos os registros so avaliados pela estao.
O mesmo no ocorre utilizando o TOPConnect, pois o filtro avaliado pelo prprio servidor vindo
para a estao apenas os registros que respeitem a condio do filtro.
Para que um filtro tenha uma boa performance necessrio que a expresso do filtro
corresponda a um ndice no servidor, caso contrrio, para poder avaliar o filtro o servidor SQL
ter que ler linha a linha da tabela.
2.10.4. Stored Procedures
O uso de Stored Procedures a maneira mais eficiente de uma aplicao se utilizar dos
benefcios da arquitetura Cliente/Servidor.
O TOPConnect suporta o uso de Stored Procedures conforme documentado na funo
TCSPExec()
2.11. Integrao com outros aplicativos
2.11.1. Incluindo registros nas tabelas do SigaPROTHEUS / AP5
As tabelas criadas no Banco de dados pode receber inseres de outros aplicativos, esta
insero deve ser feita contemplando as seguintes operaes :
Antes de inserir o registro voc deve obter o nmero mximo da coluna R_E_C_N_O_
existente na tabela
Deste nmero voc deve somar 1
Logo em seguida fazer a insero propriamente dita do registro
Se o registro no for inserido com sucesso voc deve voltar ao primeiro passo.
Alerta!: Em alguns Bancos de Dados o Topconnect estar registrando no log de eventos do

Topconnect Manager, um mensagem de alerta dizendo que existe duplicidade de registro.
(Desconsiderar esta mensagem, de tempos em tempos voc deve limpar o Log do TopConnect.
2.11.2. Excluindo registros ( Sempre Marcar )
Quando houver necessidade de excluso de registro por outros aplicativos voc deve apenas
fazer uma operao de alterao do registro, colocando o smbolo de * na coluna D_E_L_E_T_,
principalmente se esta operao for concorrente com o SigaPROTHEUS / AP5.
2.11.3. Vantagens e Desvantagens
As vantagens deste processo a agilidade na integrao entre os sistemas, no existe a
necessidade de gerar arquivos textos, para depois fazermos a integrao. Principalmente em
situaes on-line , utilizar o recurso do Banco uma das melhores sadas.
As desvantagens deste processo, so que voc deve estar ciente de todas atualizaes que so
feitas na base de dados no sistema, j que o sistema esta desta forma vulnervel a problemas
inesperados.
Normalmente aconselhamos a sempre fazer a atualizao em tabelas especficas e depois criar
rotinas pelo sistema o qual repassaro os dados destas tabelas para as tabelas definitivas, desta
forma vamos evitar problemas na atualizao de verso, ou at em alguma mudana de estrutura
que o configurador faa.(Voc estar perdendo os triggers desta tabela).
3. Ferramenta importante
3.1.
Instalador de Stored Procedures no Banco de Dados
SQL / ASP com
AP5
Alguns clientes utilizam rotinas como Stored Procedures para agilizar alguns processos crticos do
sistema, para instalao destas Storeds Procedures voc devem possuir o arquivo com o nome de
SIGAXXX.SPS, onde o XXX o tipo de Banco de Dados que o Cliente estar utilizando ex: SIGASQ7
(MSSQL 7.0), SIGAIFX (INFORMIX), SIGAORA (ORACLE)
Aps a confirmao desta operao todas as Procedures que estiverem disponveis neste arquivo sero
compiladas para a empresa em questo, se o cliente tiver mais do que uma empresa e ele deseja
instalar as procedures em todas as empresas ele precisa entrar em cada empresa.
Se houver qualquer problema na instalao das Stores Procedures ser gerado
um arquivo de log chamado SPBuild.LOG no diretrio \SIGAADV\. E tambm ser
apresentado o erro no Log do TopConnect.
AP5 Web - Conectividade

O AP5 Server o centro de funcionamento do Advanced Protheus. o encarregado pelo processamento das aplicaes,
gerenciamento das conexes e compilao de programas. E uma de suas principais caractersticas a alta conectividade. Ou
seja, o AP5 pode ser integrado a diferentes solues ou sistemas, atravs da utilizao de uma API de acesso (contida em uma
DLL) ou um controle ActiveX, ou mesmo diretamente atravs da Web (via protocolo HTTP ou FTP). Isso permite outras
aplicaes a terem acesso a execuo de funes (jobs) no AP5, utilizando o conceito de RPC.
RPC (Remote Procedure Call) significa Chamada Remota de Procedimentos, ou seja, atravs de uma aplicao externa (ou
atravs da Internet) possvel executar no AP5 rotinas criadas em ADVPL. Tais rotinas podero realizar todo o tipo de tarefa
desejada, como por exemplo cadastrar um pedido, um cliente, ou emitir um relatrio em formato HTML, retornando
informaes aplicao externa.
A utilizao da API de acesso e do controle ActiveX mais indicada para aplicaes desenvolvidas em outras linguagens e
que necessitem interagir com o AP5. J com o acesso via Internet, possvel criar toda uma aplicao Web que alie o poder
de processamento do AP5 com a facilidade de formatao de interface do HTML.
RPC Entre o AP5 e Outras Aplicaes

So duas as opes para realizar RPC entre uma aplicao externa e o AP5:
Uma API de acesso, utilizando a DLL (Dinamic Link Library) chamada AP5DCONN.DLL;
Um controle ActiveX , utilizado atravs do arquivo AP5CONNXCONTROL.OCX.
Ambas opes tm as mesmas funcionalidades:
Conexo a um ou mais servidores AP5;
Acesso a algumas funes gerenciais, como obteno de lista de usurios conectados, envio de mensagens, e
gerenciamento das conexes;
Execuo de jobs e procs. Os jobs podem ser executados no AP5 sem que necessariamente a aplicao externa
aguarde pelo retorno. Podem assim permanecer executando no AP5 Server enquanto a aplicao externa realiza
outras tarefas, ou mesmo executa outros jobs. Os procs entretanto, sempre faro com que a aplicao externa
aguarde o retorno do AP5;

Os jobs ou procs so funes contidas no repositrio do AP5 (incluindo as funes criadas por usurios User
Function). A aplicao externa pode, sempre atravs da DLL ou da OCX, enviar parmetros e receber o retorno
destas funes, segundo os tipos de dados vlidos: Caracter, numrico, lgico, data e array;
A conexo ao AP5 sempre efetuada atravs do protocolo TCP/IP. O acesso ao AP5 Server somente ser efetuado se
a correta senha e usurio forem informados. A checagem dessa senha efetuada pelo Advanced, e deve ser mantida
atravs do SIGACFG. O usurio informado deve ser o Administrador do sistema ou pertencer ao grupo
Administradores;
Geralmente a utilizao de uma dessas opes ser indicada para aplicaes que necessitem executar processos dentro do
AP5, como por exemplo, colocar um pedido de venda diretamente na base de dados do sistema,
Importante: Para utilizar a API ou o controle ActiveX, necessrio a DLL de comunicao do AP5 chamada
AP5CONN.DLL. Por isso, sempre que for necessrio utilizar uma dessas opes, a DLL de comunicao deve
estar em um path localizvel pelo Windows e deve estar atualizada em relao ao AP5 Server em que a aplicao
externa tentar se conectar.
A API de comunicao com o AP5

Para utilizar a API de comunicao do AP5, necessrio conhecer a linguagem em que a aplicao externa est escrita, a
ponto de poder utilizar o conceito de DLLs do Windows. Qualquer linguagem de programao que suportar a utilizao de
DLLs poder utilizar a API de comunicao.
Diferentemente do controle ActiveX, a DLL de comunicao no pode ser tratada como um objeto, porm podem existir
vrias instncias de comunicao, o que permite a comunicao com diferentes servidores do AP5 simultneamente. O
processo de utilizao resume-se em:
1.
2.
3.
4.
5.
Criao de uma instncia de comunicao;

Conexo ao AP5 Server;
Utilizao efetiva: Execuo de rotinas, obteno do retorno, etc;
Desconexo;
Destruio da instncia de comunicao.
Para tal, existem as seguintes funes disponibilizadas na DLL de comunicao:
AP5CreateConnControl
Descrio:
Criao de uma instncia de comunicao com o AP5 Server. Pode-se criar diferentes instncias
de comunicao, acessando um ou mais servidores do AP5.
Parmetro
s:
cServer: char * - Nome ou endereo IP do servidor para a conexo;

nPort: int - Porta do socket TCP/IP utilizada para a conexo;
cEnvironment: char * - Ambiente utilizado para a execuo de processos;
cUser: char * - Usurio do sistema para validao da conexo. O usurio informado deve
pertencer ao grupo Administradores do sistema;
cPassWord: char * - Senha do usurio informado, para validao da conexo.
Retorno:
int - Retorna o Handle da instncia criada. Este Handle retornado dever ser informado em
todas as demais funes de comunicao, para identificao da instncia que ser utilizada.
Sintaxe:
nAP5 = AP5CreateConnControl(APSERVER, 1024, ENVIRONMENT, Administrador,

)
SQL / ASP com
AP5
AP5DestroyConnControl
Descrio:
Destruio de uma instncia de comunicao com o AP5 Server. Aps a utilizao da API, e
antes de encerrar a execuo da aplicao externa, necessrio destruir o Handle criado com a
funo anterior para a liberao de memria.
Parmetro
s:
Retorno:
nObjectID: int - Handle da instncia criada com a funo anterior.
Sintaxe:
lOk = AP5DestroyConnControl(nAP5)
bool - Retorna verdadeiro ou falso, indicando a execuo com sucesso da funo.
AP5Connect
Descrio:
Conexo a um AP5 Server. Esta funo no deve ser confundida com a funo
AP5CreateConnControl. Esta funo ir realizar a conexo com o AP5 Server indicado durante
a criao da instncia informada como parmetro.
Parmetro
s:
nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. atravs
do Handle que definido em qual servidor, porta e ambiente os processos sero executados.
Retorno:
bool - Retorna verdadeiro ou falso, indicando se a conexo foi efetuada com sucesso.
Sintaxe:
lOk = AP5Connect(nAP5)
AP5Disconnect
Descrio:
Desconexo de um AP5 Server. Esta funo no deve ser confundida com a funo
AP5DestroyConnControl. Esta funo ir encerrar a conexo ativa com um AP5 Server, da
instncia informada como parmetro.
Parmetro
s:
Retorno:
nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo.
Sintaxe:
AP5Disconnect(nAP5)
Sem retorno.
AddNullParam,
AddNumericParam,
AddStringParam,
AddLogicalParam,
AddDateParamAsDouble,
AddDateParamAsString,
AddArrayParam
Descrio:
Estas funes so utilizadas para a execuo de processos em um servidor AP5. Podem ser
utilizadas somente aps uma conexo ser ativada. Um processo executado em um servidor AP5
pode necessitar de parmetros, que devero ser enviados ao servidor antes da execuo do
processo atravs da utilizao destas funes. Os tipos de dados que podem ser enviados so:
Numrico (int), Caracter (char *), Lgico (bool), Data (enviado como caracter char * - ou
como numrico - int) e Array (variant).
Parmetro
s:
nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. atravs
do Handle que definido para qual servidor o parmetro ser enviado;
xParametro: indefinido - O tipo de dado do parmetro depender da funo utilizada, segundo
os tipos de dados permitidos explicados acima.
Retorno:
bool - Retorna verdadeiro ou falso, indicando se o parmetro pde ser enviado ao AP5 Server
com sucesso.

lOk = AddNumericParam(nAP5,5)
Sintaxe:
AP5
ou
lOk = AddStringParam(nAP5,TEXTO)
ou
lOk = AddLogicalParam(nAP5,true)
ResultAsNumeric,
ResultAsString,
ResultAsLogical,
ResultAsDate,
ResultAsDateString,
ResultAsArray
Descrio:
Parmetro
s:
Estas funes so utilizadas para obter o retorno do AP5 Server aps a execuo de um
processo.
nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo.
Apenas para as funes ResultAsString e ResultAsDateString:
cBuffer: char * - Buffer de caracteres alocado para receber o retorno em formato caracter;
nSize: int - Tamanho do buffer passado no parmetro anterior.
Retorno:
O tipo de dado do retorno depender da funo utilizada, segundo os tipos de dados definidos
anteriormente. Para as funes ResultAsString e ResultAsDateString o retorno ser o tamanho
do buffer preenchido.
Sintaxe:
nRet = ResultAsNumeric(nAP5)
ou
lRet = ResultAsLogical(nAP5)
ou
ResultAsString(nAP5,cBuffer,nSize)
AP5BuildNumber
Descrio:
Funo utilizada para obter o nmero do build de compilao da API de conexo ao AP5.
Parmetro
s:
nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo;
cBuild: char * - Buffer de caracteres para receber o nmero do build;
nSize: int - Tamanho do buffer passado no segundo parmetro.
Retorno:
int - Retorna o tamanho do buffer contendo o nmero do build.
Sintaxe:
AP5BuildNumber(nAP5,cBuffer,nSize)
PrepareEnv
Descrio:
Funo utilizada para preparar o ambiente do sistema, ou seja, abrir arquivos, criar variveis, e
tornar o ambiente de execuo da aplicao externa em relao ao AP5 Server, o mais parecido
possvel com o que realizado pelos mdulos do sistema.
Parmetro
s:
cEnv: char * - Ambiente que ser utilizado para a abertura dos arquivos;
cEmp: char * - Cdigo da empresa do sistema (dois dgitos) que dever ser aberta;
cFil: char * - Cdigo da filial que ser utilizada (dois dgitos);
aTables: variant Este parmetro deve ser um array variant (para detalhes, consulte a
documentao da linguagem utilizada) contendo as siglas das tables que devero ser abertas
(por exemplo SB1).
Retorno:
bool - Retorna verdadeiro ou falso, indicando o sucesso da execuo da funo.
Sintaxe:
PrepareEnv(nAP5,ENVIRONMENMT,99,01,aTables)
SQL / ASP com
AP5
StartJob
Descrio:
Esta funo permite a execuo de um processo (job) em um AP5 Server. O processo executado
pode ser qualquer um dos existentes no repositrio definido pelo ambiente informado, incluindo
as funes criadas pelo usurio (User Function). Pode tambm receber parmetros, bem como
retornar um valor para a aplicao externa, sempre utilizando-se das funes descritas
anteriormente. A execuo de um processo resume-se em:
A)
1. Enviar os parmetros (se existirem);
2. Executar o processo e aguardar sua finalizao;
3. Obter o resultado (se existir).
B)
1. Enviar os parmetros (se existirem);
2. Executar o processo sem aguardar sua finalizao;
Os processos so executados em threads de execuo separadas. Isso permite aplicao
externa que esteja utilizando a API, optar por executar o processo e continuar trabalhando
enquanto o mesmo est em execuo. Porm, somente poder obter um retorno quando esperar
at que o processo termine de ser executado.
Parmetro
s:
Obs.: Como estes processos so executados sem que uma instncia do AP5 Remote esteja ativa,
devem ser criados sem nenhum comando de interface (criao de janelas, comandos de alerta,
help, etc). Se um comando de interface for utilizado no cdigo ADVPL de um processo, a
execuo deste atravs da API gerar um erro de execuo.
cEnv: char * - Ambiente que ser utilizado para a execuo do processo;
cFunc: char * - Nome do processo ou funo que ser executado no AP5 Server;
lWait: bool - Verdadeiro ou Falso indicando se a aplicao externa dever ou no aguardar pelo
trmino da execuo do processo.
Retorno:
bool - Retorna verdadeiro ou falso, indicando se o processo foi iniciado com sucesso.
Sintaxe:
StartJob(nAP5,ENVIRONMENMT,MESEXTENSO,true)
CallProc
Descrio:
Esta funo tem o mesmo objetivo que a anterior, porm sempre aguardar o trmino do
processo para que o controle volte aplicao externa, e tem algumas diferenas conceituais:
A)
No se pode escolher o ambiente no qual o processo ser executado. Os
processos executados pela CallProc sero sempre executados no ambiente indicado na
criao da instncia com a funo AP5CreateConnControl;
B)
Um processo executado atravs da funo StartJob, comear de um
ambiente totalmente novo. Porm, os processos executados pela funo CallProc
mantm o ambiente da ltima execuo. Assim, o valor de variveis criadas, os arquivos
abertos, etc, so mantidos na prxima execuo.
Parmetro
s:
cFunc: char * - Nome do processo ou funo que ser executado no AP5 Server.
Retorno:
Bool - Retorna verdadeiro ou falso, indicando se o processo foi finalizado com sucesso.
Sintaxe:
CallProc(nAP5,CALCEST)
Com a utilizao da API, pode-se criar toda uma aplicao, em Visual Basic por exemplo, que executar funes do sistema
Advanced como o usurio faria atravs do AP5 Remote:
Dim nAP5 As Integer
Dim cRes As String
nAP5 = AP5CreateConnControl(APSERVER, 1024, ENVIRONMENT, Administrador, )
If AP5Connect(nAP5) Then
AddNumericParam(nAP5,5)
lOk = CallProc(nAP5,MESEXTENSO)
SQL / ASP com
AP5
If lOk Then
ResultAsString(nAP5,cRes)
Else
CRes = No foi possvel obter o ms por extenso
End if
AP5Disconnect(nAP5)
End if
AP5DestroyConnControl(nAP5)
Importante: A notao dos tipos de dados e da sintaxe mencionados na descrio das funes segue o
padro de linguagens como a linguagem C. Deve-se considerar os exemplos de sintaxe conforme a
linguagem utilizada.
Todas as funes de caracter como ResultAsString ou AP5BuildNumber, trabalham com buffer de
caracteres. Isto significa que o buffer que receber o retorno deve ser alocado na linguagem utilizada e
que o tamanho alocado dever ser passado como parmetro para a funo chamada. A aplicao externa
tambm ser responsvel por liberar a memria do buffer alocado.
O Controle ActiveX
O controle ActiveX tem as mesmas funcionalidades da API. Porm o formato de utilizao diferenciado. O controle
ActiveX um objeto que deve ser registrado no computador onde ser utilizado e durante a execuo da aplicao externa,
dever ser criado, utilizado e destruido ao final. Para maiores detalhes, consulte a documentao da linguagem utilizada ou a
documentao do conceito ActiveX na pgina da Microsoft (http://www.microsoft.com).
RPC atravs da Internet

O RPC atravs da Internet realizado diretamente com o AP5 Server utilizando o protocolo HTTP. Isto significa que
possvel criar pginas HTML que executem processos no AP5 Server, ou mesmo utilizar recursos de conectividade Wireless,
como por exemplo um Palm, para acessar e executar processos diretamente no AP5 Server atravs do protocolo HTTP. Neste
ltimo caso possvel tambm utilizar uma conexo direta TCP/IP (via socket).
Para realizar o RPC utilizando o protocolo HTTP diretamente com o AP5 Server, no necessrio a utilizao de um servidor
Web de terceiros, pois o AP5 Server tambm um servidor Web.
O AP5 Server como um servidor Web

O AP5 Server pode ser configurado para trabalhar como um servidor Web. Isso significa trabalhar como um servidor de
requisies dos protocolos HTTP e/ou FTP, do mesmo modo que outros servidores conhecidos no mercado (por exemplo, o
IIS Internet Information Server, da Microsoft ou o Apache para Linux). Assim, basta ter o AP5 para poder criar sua prpria
Intranet num ambiente de rede local, ou publicar o endereo IP da mquina com o AP5 Server na Internet e executar funes
atravs de RPC ou simplesmente criar o seu prprio Web Site com pginas HTML estticas e/ou dinmicas.
Servios de FTP
O protocolo FTP (File Transfer Protocol) permite a transferncia de arquivos entre um servidor e uma aplicao
client de FTP (com um Web Browser como o Internet Explorer, por exemplo). Utilizando o AP5 Server como um servidor
FTP, os usurios podero remotamente baixar arquivos disponibilizados em um diretrio configurvel no servidor. Pode-se
tambm habilitar um recurso de auto-atualizao para o AP5 Remote, que ir automaticamente baixar arquivos compactados
para se auto atualizar quando necessrio.
Para habilitar o servio de FTP no AP5 Server, o seguinte
grupo deve ser criado no arquivo de configuraes
(AP5SRV.INI):
[FTP]
Enable=1
Path=C:\AP5\FTP
Port=21
Onde as chaves so:

Enable indica se habilita ou desabilita este servio;
Path indica o diretrio onde o AP5 Server localizar os arquivos para disponibilizar no FTP;
- Port a porta usada para conexo das aplicao client.
Figura 1 - Internet Explorer 5 acessando a rea de
FTP do AP5 Server
-
O recurso de auto-atualizao encontrado no AP5 Remote funciona atravs da deteco de diferenas na verso das DLLs
locais (ou seja, que se encontram juntamente com o executvel do AP5 Remote). Quando isto ocorre, o usurio questionado
sobre a execuo da auto-atualizao. Se tudo estiver corretamente configurado no arquivo de configurao do AP5 Remote
(AP5RMT.INI para maiores detalhes, consulte a documentao do AP5 Remote), ao escolher que deseja tentar uma autoatualizao, o AP5 Remote ir abrir uma conexo FTP com o Server configurado e baixar os arquivos compactados (com a
extenso .CAB) contendo as DLLs e executveis mais atualizados. Os arquivos sero ento descompactados localmente para
a atualizao.
Servios de HTTP
O protocolo HTTP (HyperText Transmission Protocol) o protocolo utilizado na comunicao entre um servidor e
um Web Browser. o protocolo utilizado para o envio e recebimento de pginas formatadas em padres SGML
(HTML,XML, etc). Este protocolo se baseia principalmente em dois comandos: GET e POST. O comando GET utilizado
para obter alguma informao do servidor HTTP e o POST para postar informaes para o servidor. Mais adiante, ser mais
fcil compreender onde tais comandos so utilizados no AP5 Server.
Figura 2 - Internet Explorer 5 acessando o AP5 Server como um

servidor HTTP
Utilizando o AP5 Server como um servidor HTTP, o

mesmo poder ser acessado atravs de um Web
Browser como o Internet Explorer por exemplo, que
receber as pginas HTML enviadas de um diretrio
configurado no servidor. Adicionalmente ao envio e
recebimento de pginas estticas formatadas, podese utilizar a linguagem Advpl do AP5 para processar
pginas mistas, que contm cdigo Advpl e
comandos HTML de formatao. Tais pginas sero
processadas no AP5 Server, e ento enviadar para o
Web Browser, que ir format-las de acordo com os
comandos HTML contidos. Tambm possvel
executar diretamente funes compiladas no
repositrio do AP5, atravs de um request HTTP
(por exemplo, atravs de um POST em um
formulrio em HTML, ou de um link, ou mesmo
diretamente na linha de URL do Web Browser. O
mesmo vale para qualquer outra aplicao que seja
capaz de efetuar comandos GET ou POST utilizando
o protocolo HTTP).
Para habilitar o servio de HTTP no AP5 Server, os seguintes grupos devem ser criados no arquivo de configuraes
(AP5SRV.INI):
HTTP]
Enable=1
Path=C:\AP5\HTTP
RPCServer=SERVERKEY
RPCEnv=ENVIRONMENT
RpcTimeOut=40
Port=1234
GetProc=<funo>
PostProc=<funo>
[SERVERKEY]
TYPE=TCPIP
Server=172.16.1.1
Port=5024

Onde as chaves so:
Grupo HTTP
- Enable indica se habilita/desabilita o servio;
- Path indica o diretrio onde o AP5 Server localizar os arquivos HTML e demais arquivos que forem requeridos por
um Web Browser;
- RPCServer indica o nome do grupo que contem as configuraes do AP5 Server onde sero executadas as chamadas
de funes Advpl atravs de RPC (por requests HTTP);
- RPCEnv indica o nome do grupo que contm as configuraes de ambiente para a execuo das funes requisitadas
em RPC;
- RPCTimeOut indica o tempo em segundos que a thread de execuo RPC permanecer no ar (e conseqentemente
com todo o ambiente preparado para ser utilizado em uma prxima execuo de RPC via HTTP);
Port a porta utilizada para a conexo dos Web Browsers;
- GetProc e PostProc so parmetros opcionais que podem ser utilizados para interceptar os comandos GET e POST
que caem no AP5 Server. Quando um comando desses requisitado ao servidor e uma destas chaves est em uso, a
funo informada executada e receber um parmetro com o nome da pgina, arquivo ou funo, originalmente
requisitado.
Grupo <SERVIDOR> (no exemplo, SERVERKEY)
- TYPE indica o tipo de conexo que ser efetuada entre o servidor atual (que o AP5 Server encarregado de
responder os requests HTTP) e o servidor de RPC (que o encarregado de executar as rotinas em Advpl);
- Server indica o nome ou endereo IP do servidor encarregado da execuo das rotinas em Advpl (RPC). Note que
estes servidor no precisa necessariamente ser um servidor diferente do utilizado para responder aos requests HTTP
(aquele que trabalha como Web Server);
- Port a porta utilizada para conexo ao Servidor RPC.

Quando uma URL requisitada atravs de um Web Browser (seja atravs de um comando POST, um link ou diretamente
atravs do campo de URL do Browser), essa requisio recebida pelo AP5 Server que a tratar do seguinte modo:
Extenso
do arquivo
Descrio
O que acontece
Exemplo
Nenhuma
Um endereo http
nico, sem um nome
de arquivo definido.
http://servidor/
.
HTM;.HTML
ou
outra
extenso
qualquer.
.APL
Pginas
HTML,
arquivos
texto,
arquivos de imagem,
som, vdeo, etc.
.APH
uma chamada para

uma pgina ativa
(uma pgina em
ADVPL ASP).
Ao chamar um endereo URL sem

informar um nome de arquivo, o AP5
Server ir procurar o arquivo chamado
DEFAULT.HTM para enviar ao Web
Browser que efetuou o request.
A pgina HTML, ou qualquer que seja o
arquivo, ser simplesmente enviado ao
Web Browser, sendo que este o
responsvel
pela
sua
traduo/interpretao.
Quando o AP5 Server receber um request
deste tipo, a funo chamada (no exemplo
func.apl, a funo chamada func, sem a
extenso) ser executada no AP5 Server
configurado na chave RPCSERVER no
ambiente definido pela chave RPCENV.
O que dever ser retornado pela funo
uma string, que ser enviada para o Web
Browser.
Uma pgina Advpl ASP uma pgina
HTML contendo cdigo interpretvel no
servidor. Tais pginas so criadas
utilizando qualquer editor de texto ou
editor HTML, e devem ter SEMPRE a
extenso .APH. Devem ser compiladas
atravs do AP5 IDE. Durante a
compilao, o AP5 Server transforma essa
pgina em uma funo interna que ser
executada da mesma maneira que aquelas
chamadas .APL explicadas anteriormente.
Como tambm so funes, as pginas
em Advpl ASP devem ser chamadas do
Web Browser com a extenso .APL
exatamente
como
explicado
anteriormente.
uma chamada
direta a uma funo
do repositrio do
AP5.
http://servidor/cadastro
.htm
ou
http://servidor/imagem.
gif
http://servidor/acerto.a
pl
ou
http://servidor/runprog.
apl
http://servidor/activepa
ge.apl
ou
http://servidor/cadastro
.apl
Criando funes APL

A princpio, todas as funes contidas no repositrio podem ser executadas diretamente atravs de uma requisio HTTP ao
AP5 Server. Porm, alguns detalhes devem ser considerados:
Uma funo executada no momento do recebimento de uma requisio HTTP executada como um JOB, ou seja,
no contem interface. Por isso, tais funes no podem conter comandos de interface, como criao de janelas ou
exibio de helps e mensagens de alerta;
A nica interface possvel a utilizada no client HTTP. Por isso, tais funes devem SEMPRE retornar uma string
de caracteres. Aps o processamento da funo, essa string de retorno ser enviada diretamente ao client HTTP e
este ser o responsvel por sua interpretao. Por exemplo, utilizando um Web Browser como client pode-se
retornar a string de comandos HTML diretamente. O HTML ento ser propriamente exibido no Web Browser;
Qualquer retorno diferente de uma string de caracteres gerar um erro que ser enviado aplicao client HTTP (o
erro gerado Invalid Proc Return);
O AP5 Server passa alguns parmetros para as funes chamadas. Isso significa que ao criar funes para serem
utilizadas em resposta s requisies HTTP, deve-se criar o cabealho da funo com estes parmetros. No
obrigatrio utilizar os mesmos nomes de parmetros sugeridos abaixo quando criar diretamente estas funes.
Porm, como so esses os nomes utilizados no ADVPL ASP explicado mas a frente, aconselhvel utiliz-los por
motivo de padronizao:
- __aCookies: Este parmetro recebe um array bidimensional com os Cookies criados na aplicao client HTTP
(por exemplo, no Internet Explorer 5). Pode-se utiliz-lo para checar validaes mantidas nas mquinas client
por exemplo. Para maiores detalhes, consulte a documentao do HTML ou do Web Browser utilizado.
-
__aPostParms: Este parmetro recebe um array bidimensional com os campos contidos em um formulrio
HTML recebido atravs de um comando POST. Cada item deste array contm um array com o nome do campo
e o valor informado. Por exemplo, para um formulrio com dois campos para digitao (um chamado nome e o
outro chamado endereco), que enviam os dados para a funo cadastro.apl atravs de um POST, a funo
receber o array __aPostParms da seguinte forma:
{
{nome, NOME DIGITADO NA PAGINA HTML},
{endereco, ENDERECO DIGITADO NA PAGINA HTML}
}
A funo pode tratar os dados recebidos neste array para realizar um processamento especfico com tais
informaes. Para campos onde no possvel a entrada de dados e sim a escolha de uma informao prdefinida (como por exemplo um checkbox), o item somente existir no array caso o campo tenha sido
selecionado no formulrio HTML (por exemplo, se o checkbox for marcado).
__nProcID: Contm o Handle da Thread de execuo daquela funo. A utilizao deste parmetro ser
explicada juntamente com o tpico ADVPL ASP posteriormente;
__aProcParms: Este parmetro recebe um array bidimensional com os parmetros enviados na linha de URL
do Web Browser. Por exemplo, na execuo de uma funo via linha de URL do Web Browser como:
http://servidor/vende.apl?cod=000001&nome=PRODUTO DE TESTE&quant=20
a funo chamada vende receber o array __aProcParms da seguinte forma:
{
{cod, 000001},
{nome, PRODUTO DE TESTE},
{quant, 20}
}
A funo pode tratar estes dados recebidos para realizar processamentos especficos. muito til tambm para
criar links de execuo diretamente atravs de um Web Browser.
__cHTTPPage: Esse parmetro recebe o nome da pgina, arquivo ou funo originalmente requisitada para o
AP5 Server. utilizado quando as chaves GETPROC e POSTPROC (explicadas anteriormente) so habilitadas
no arquivo de configuraes do AP5 Server. A funo configurada ir receber nesse parmetro o nome original
requisitado e poder executar algum processamento especfico para continuar o processo (retornando a prpria
funo original) ou desviar para outra pgina, por exemplo.
Exemplo de funo APL

A funo a seguir um bom exemplo para ser executado atravs de um Web Browser como o Internet Explorer ou o
Netscape Navigator. Ela retorna uma string contendo a pgina HTML onde est escrita a mensagem Hello World e a lista
de parmetros passados na linha de URL. Para test-la, crie um arquivo novo no AP5 IDE, cole o cdigo abaixo e salve o
arquivo como WEBDEMO.PRW. Aps compilar o programa, basta chamar em um Web Browser uma URL como:
http://localhost/u_webdemo.apl?cod=000001&desc=DESCRICAO DO PRODUTO&qtd=2
Cdigo da funo:
#include "rwmake.ch"
User Function WebDemo(__aCookies,__aPostParms,__nProcID,__aProcParms,__cHTTPPage)
Local cHTML := ""
Local i

// Coloca uma mensagem em HTML
cHTML += '<p><h1 align="center">Hello World!!!</h1></p>'
// Coloca um separador de linha em HTML
cHTML += '<hr>'
If Len(__aProcParms) = 0
cHTML += '<p>Nenhum parmetro informado na linha de URL.'
Else
For i := 1 To Len(__aProcParms)
cHTML += '<p>Parmetro: ' + __aProcParms[i,1] + '
__aProcParms[i,2] + '</p>'
Valor: ' +
Next i
Endif
Return(cHTML)
Para crias as funes que sero utilizadas em chamadas via um Web Browser, ou seja, em qualquer
request HTTP, deve-se seguir o procedimento normal de criao de funes no AP5: utilizando o
AP5 IDE para a edio e para a compilao.
Note que no caso de funes do usurio (User Function) o nome chamado na URL do Browser
tambm dever conter o U_ no comeo da funo, por exemplo:
http://servidor/u_webrelato.apl
E deve-se sempre indicar a extenso .APL para que o AP5 Server identifique que uma funo a ser executada.
O ADVPL ASP
Uma pgina ASP (Active Server Pages) uma pgina HTML contendo cdigo interpretvel em uma linguagem
compreensvel ao servidor HTTP em uso. Por exemplo, o IIS da Microsoft utiliza o VBScript para criar suas pginas ASP,
do mesmo modo que o AP5 utiliza o ADVPL. Uma pgina ASP uma combinao de script HTML e cdigo interpretvel.
No ADVPL ASP esse cdigo padro xBase, portanto a preocupao maior daqueles que j conhecem e trabalham com o
AP5 e desejam desenvolver pginas ativas para aplicaes Web utilizando essa facilidade conhecer HTML.
Caractersticas do ADVPL ASP

Os arquivos ADVPL ASP tm a extenso padro .APH. So arquivos texto e devem ser adicionados a um projeto no AP5
IDE e compilados da mesma maneira que os programas tradicionais. A diferena que o AP5 Server identificar que se trata
de um ADVPL ASP e executar uma espcie de tradutor (parser) antes que a compilao seja executada. Este parser ir
transformar todo o arquivo em uma funo nica, que receber os mesmos parmetros das funes APL simples, como
explicado anteriormente, e retornar uma string. O desenvolvedor no precisa se preocupar em retornar HTML algum, pois
o APH tambm um arquivo HTML. A funo que foi gerada na compilao ir se encarregar de retornar o HTML contido
no arquivo, depois que o cdigo foi processado.
Por se tornar uma funo no momento da compilao, no possvel utilizar a clusula FUNCTION para criar
outras funes dentro de um arquivo APH. Caso exista essa necessidade, tais funes devem ser criadas em um
arquivo PRW tradicional e chamadas de dentro do APH.
Do mesmo modo que as demais funes, o arquivo APH tambm deve ser executado (atravs da
URL do Browser, por exemplo) com a extenso .APL.
A extenso APH para o nome dos arquivos obrigatria. Qualquer outra extenso usada no nome
do arquivo no ser reconhecida e o parser no ser executado antes da compilao.
Assim como outros ASPs, a diferenciao entre script HTML e cdigo efetuada atravs dos caracteres <% para indicao
de abertura de cdigo e %> para indicao do encerramento de cdigo.
Por exemplo, o HTML abaixo contm um pedao de cdigo ADVPL separado pelos delimitadores:
<html>
<head>
<title>ADVPL ASP Demo</title>
</head>
<body>
<p>Bem vindo ao mundo do ADVPL ASP!</p>

<%
// Soma os 100 primeiros nmeros
Local i, nSoma := 0
For i := 1 To 100
NSoma += i
Next i
%>
</body>
</html>
Quando este arquivo for requisitado ao AP5 Server (atravs de uma chamada em URL por exemplo) o cdigo entre os
delimitadores ser executado, porm o script colocado ao redor do cdigo ser mantido exatamente como se encontra.
A grande vantagem de se criar arquivos ADVPL ASP em relao a criar funes APL simples, decorre do fato de que no
necessrio conhecer to profundamente HTML e que nas funes APL simples o desenvolvedor deve se preocupar em
retornar todo o HTML necessrio para a correta exibio no Web Browser. E tambm, como o ADVPL ASP mistura o script
HTML com o cdigo interpretvel, pode-se criar um arquivo APH utilizando o editor desejado (como o Microsoft FrontPage
por exemplo) e inserir o cdigo necessrio entre o script. Outro detalhe importante que pode-se utilizar as estruturas de
fluxo da linguagem ADVPL para repetir comandos do prprio script HTML (por exemplo, colocar um comando de script
HTML dentro de um comando While em ADVPL):
<% While !EOF() %>
<B> Esta linha ser repetida no HTML at ocorrer o fim de arquivo </B>
<%
dbSkip()
EndDo
%>
Note que tambm pode existir diferentes blocos de cdigo interpretvel separados pelos delimitadores, dentro de um mesmo
arquivo.
To importante quanto mesclar cdigo interpretvel com script de formatao HTML, utilizar os comandos ADVPL para
alterar o script de formatao. Ou seja, colocar o contedo de variveis, campos, etc, diretamente no HTML que ser
enviado aplicao client (ao Browser por exemplo). Isso pode ser realizado atravs dos delimitadores de avaliao. Os
delimitadores de avaliao so <%= para abertura e %> para encerramento. Diferentemente dos delimitadores de cdigo
interpretvel, estes devem sempre estar na mesma linha. Com eles pode-se criar uma linha de script HTML, cujo contedo
contm uma expresso que ser avaliada em tempo de execuo:
<b>Esta linha HTML, mas a data exibida aqui: <%= Time() %> foi obtida em tempo de
execuo.</b>
No exemplo acima, a linha HTML ser retornada para o Browser com o resultado da funo time (ou seja, a hora atual no
servidor) inserido no texto.
Utilizando todos esses conceitos, pode-se criar toda uma apliao Web baseada no AP5. Ou seja, o processamento e acesso
aos dados fica por conta do AP5 Server, e a interface fica por conta do Browser (utilizando o HTML). Abaixo um exemplo
de um relatrio de clientes criado utilizando o ADVPL ASP. Para test-lo basta copiar o cdigo, salv-lo como
WEBREL.APH e compilar o arquivo atravs do AP5 IDE:
<html>
<head>
<% //Funo para manuteno do ambiente %>
<%= HTMLProcID(__nProcID) %>
<title>ADVPL ASP DEMO</title>
</head>
<%
#define
#define
#define
#define
FIELD_CODDE
FIELD_CODATE
FIELD_LOCDE
FIELD_LOCATE
"FROM_CODE"
"TO_CODE"
"FROM_LOCAL"
"TO_LOCAL"
// Criao das variveis com os parmetros recebidos atravs do array __aProcParms

Local cCodDe,cCodAte,cLocDe,cLocAte
Local nPos
nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_CODDE })
If nPos != 0
cCodDe := __aProcParms[nPos,2]
Else
cCodDe := ""
Endif
nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_CODATE })
If nPos != 0
cCodAte := __aProcParms[nPos,2]
Else
cCodAte := "ZZZZZZ"
Endif
nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_LOCDE })
If nPos != 0
cLocDe := __aProcParms[nPos,2]
Else
cLocDe := ""
Endif
nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_LOCATE })
If nPos != 0
cLocAte := __aProcParms[nPos,2]
Else
cLocAte := "ZZ"
Endif
%>
<body topmargin="0" leftmargin="0">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td>
<h1 align="left">ADVPL ASP - Demo</h1>
</td>
</tr>
<tr>
<td>
<hr size="5">
</td>
</tr>
<tr>
<td>
<h3 align="left"><u>Relatrio de Produtos</u></h3>
</td>
</tr>
<tr>
<td>
<p align="left"><b>Data de gerao</b>: <%=Day(Date())%>
%=Year(Date())%></td>
</tr>
<tr>
<td>
<hr>
</td>
</tr>
</table>
<div align="center">
<center>
de
<%=MesExtenso(Date())%>
<% If Len(__aProcParms) > 0 %>

<table border="1" cellpadding="0" cellspacing="0" width="508" height="24">
<tr>
<th
width="181"
height="24"
bgcolor="#008080"
color="#FFFFFF"><b>Parmetro</b></font></th>
<th
width="327"
height="24"
bgcolor="#008080"
color="#FFFFFF"><b>Valor</b></font></th>
</tr>
<%
// "Impresso" dos parmetros
Local i
For i := 1 To Len(__aProcParms)
%>
<tr>
de
<
align="left"><font
align="left"><font

<td width="181" height="24" bgcolor="#FFFFCC"><%= __aProcParms[i,1] %></td>
<td width="327" height="24" bgcolor="#FFFFCC"><%= __aProcParms[i,2] %></td>
</tr>
<% Next i %>
</table>
<% Else %>
<b>Nenhum parmetro informado.</b>
<% Endif %>
</center>
</div>
<p align="left"> </p>
<%
// Abertura dos arquivos e posicionamento do ponteiro
If Select("SB2") == 0 .Or. Select("SB1") == 0
RpcSetEnv ( "99", "01", "", "","","", {"SB1","SB2"} )
Endif
dbSelectArea("SB1")
dbSetOrder(1)
dbSeek(xFilial("SB1")+cCodDe+cLocDe,.T.)
%>
<table border="1" cellpadding="0" width="100%" cellspacing="0">
<tr>
<th width="12%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Cdigo</b></font></th>
<th width="50%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Descrio</b></font></th>
<th width="7%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Local</b></font></th>
<th
width="17%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Quantidade em
Estoque</b></font></th>
<th
width="14%"
align="left"
bgcolor="#336699"><font
color="#FFFFFF"><b>Custo
Mdio</b></font></th>
</tr>
<%
While !EOF() .And. xFilial("SB1") == SB1->B1_FILIAL .And. SB1->B1_COD <= cCodAte;
.And. SB1->B1_LOCPAD <= cLocAte
SB2->(dbSetOrder(1))
SB2->(dbSeek(xFilial("SB2")+SB1->B1_COD+SB1->B1_LOCPAD,.F.))
%>
<tr>
<td
<td
<td
<td
<td
width="12%"
width="50%"
width="7%"
width="17%"
width="14%"
bgcolor="#FFFFCC"><%=
HTMLAllTrim(SB1->B1_COD)
HTMLAllTrim(SB1->B1_DESC)
HTMLAllTrim(SB2->B2_LOCAL)
SB2->B2_QATU
"R$" + Str(SB2->B2_CM1,8,2)
%></td>
%></td>
%></td>
%></td>
%></td>
</tr>
<%
dbSkip()
EndDo
%>
</table>
</body>
</html>
Aps ter o cdigo compilado, pode-se visualizar o resultado acessando atravs de um Web Browser como o Internet
Explorer a seguinte URL:
http://servidor/h_webrel.apl
7. Conceito do ADVPL
Objetivo : Este curso tem como objetivo treinar e aperfeioar nossos clientes com algumas funes que a
microsiga desenvolveu no Siga PROTHEUS.

Todos os tpicos mencionados podero servir como base consulta, considerando-se como
ambiente apresentado nas verses, pacths, e builds .
ideal
8. Funo
8.1.
Funo FIELDGET()
Esta funo tem a finalidade de criar / duplicar o registro dentro do arquivo corrente oude um outro arquivo ,
entretanto este comando necessita ser utilizado com um outro comando primo .
Alem de que os arquivos tanto de origem como o de destino devem Ter sua estrutura identica, mesmos
campos / tamanhos / tipos.
Primicia basica voce necessita estar posicionado na arquivo e registro que voce deseja ser duplicado ou
copiado.
Sintaxe :
AADD( Array , FIELDGET(_NCONTADOR)
Exemplo :
DbSelectArea("SC7")
_aCamposSC7 := {}
For _nI := to Fcount()
AADD ( aCamposSC7,FieldGet(_nI))
Next
8.2.
FIELDPUT()
Esta funo tem a finalidade de incluir ou seja pegar o conteudo do resultado da funo acima e duplica o
registro dentro do arquivo corrente ou de um outro arquivo, entretanto este comando necessita ser utilizado
por um comando primo .
Alem de que os arquivos tanto de origem como o de destino devem Ter sua estrutura identica, mesmos
campos / tamanhos / tipos.
Primicia basica voce devera travar o registro no arquivo sempre com o comando RECLOCK() com a opo
de verdade .
Sintaxe :
FIELDPUT(_NCONTADOR,ARRAY[_Contador])
Exemplo :
DbSelectArea("SC7")
RecLock("SC7",.T.)
For _nI := to Len( aCamposSC7)
FIELDPUT(_Ni,_aCamposSC7[_nI])
Next
Ambas as funes no checam as ordens do Dicionario da dados da Siga SX3010.DBF.

8.3. GETADVFVAL
Tipo: Processamento
Esta funo permite executar uma pesquisa em um arquivo, pela chave especificada
e na ordem especificada, retornando o contedo de um ou mais campos.
Sintaxe
GetAdvFVal(cAlias,uCpo,uChave,nOrder,uDef)
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 indice para a pesquisa.
uDef Valor ou array default para ser retornado caso a chave no seja encontrada.
Retorna
uRet Retorna o contedo de um campo ou array com o contedo de vrios campos.
Exemplo
// Exemplo de uso da funcao GetAdvFVal:
// Obtendo apenas de um campo:
cChave := SD2->D2_COD+SD2->D2_LOCAL
cDesc := GetAdvFVal(SB1,B1_DESC,cChave,1,SC6->C6_DESCRI)
// Obtendo o conteudo de mais de um campo:
cChave := SD2->D2_COD+SD2->D2_LOCAL
aCpos := {B1_DESC+2B1_PRV1,B1_UM}
aDados := GetAdvFVal(SB1,aCpos,cChave,1,{SC6->C6_DESCRI,SC6->C6_PRCVEN,SC6->C6_UM})
refere-se aos Itens do Pedido de Venda) e, aps pesquisar no SB1 (Cadastro de Produtos), sugerir a
quantidade vendida a partir de um campo especfico:
// Colunas...
nPosCod := aScan(aHeader,{ |x| Upper(AllTrim(x[2])) == C6_PRODUTO })
nPosQtd := aScan(aHeader,{ |x| Upper(AllTrim(x[2])) == C6_QTDVENlm })
// Obtm o cdigo do produto
cCodigo := aCols[n,nPosCod]
// Pesquisa
dbSelectArea(SB1)
dbSetOrder(1)
dbSeek(xFilial(SB1)+cCod)
// Altera a quantidade no grid
aCols[n,nPosQtd] := SB1->B1_QTSUGER // Campo especfico com a quantidade padro
__Return(SB1->B1_QTSUGER)
Para uma melhor compreenso, voc pode analisar os programas RDMOD2.PRX e/ou RDMOD3.PRX que
acompanham o SIGA PROTHEUS. Eles esto no diretrio principal do sistema (geralmente \SIGAADV\) e demonstram
rotinas usadas para cadastros semelhantes ao Pedido de Vendas e que trabalham com os arrays mencionados.
8.4 - SETDEFAULT
Tipo: Processamento
Habilita os padres definidos pela funo SetPrint.
Sintaxe
SetDefault (aArray, cAlias)
Parmetros
aArray Array aReturn, preenchido pelo SetPrint
[1] Reservado para Formulrio
[2] Reservado para N de Vias
[3] Destinatrio
[4] Formato => 1-Comprimido 2-Normal
[5] Mdia => 1-Disco 2-Impressora
[6] Porta ou Arquivo 1-LPT1... 4-COM1...
[7] Expresso do Filtro
[8] Ordem a ser selecionada
[9]..[10]..[n] Campos a Processar (se houver)
cAlias Alias do arquivo a ser impresso.
Retorna
Nil
Comentrios
Esta funo habilita os padres de relatrio alterados pela funo SetPrint.
Exemplo
// Define Variveis
cString:= SB1
NomeRel:= MATR290lR
cPerg := MTR290lr
titulo := RELAO PARA ANLISE DOS ESTOQUESlL
cDesc1 := Este relatrio demonstra a situao de cada item em
cDesc2 := relao ao seu saldo , seu empenho , suas entradas previstas
cDesc3 := e sua classe ABC
aOrd := { Por Codigo io,lg Por Tipo }
Tamanho := G
// Envia controle para a funo SETPRINT
NomeRel:= SetPrint( cString, NomeRel, cPerg, @titulo, cDesc1, ;
cDesc2, cDesc3, .F., aOrd, .F., Tamanho)
If LastKey() = 27 .or. nLastKey = 27
Return
Endif
SetDefault(aReturn,cAlias)
If LastKey() = 27 .OR. nLastKey = 27
Return
Endif
8.5 - CRIATRAB
Tipo: Processamento
Cria arquivo de trabalho.
Sintaxe
CriaTrab(aArray,lDbf)
Parmetros
aArray Array multidimensional contendo os campos a criar {Nome, Tipo,Tamanho, Decimal}

lDbf Determina se o arquivo de trabalho deve ser criado ( .T.) ou no (.F. )
Retorna
ExpC1 Nome do Arquivo gerado pela funo.
Comentrios
Esta funo retorna o nome de um arquivo de trabalho que ainda no exista.
Caso lDbf = .T., a funo criar um arquivo DBF com este nome e a estrutura definida em aArray.
Caso lDbf = .F., a funo no criar arquivo de nenhum tipo, apenas fornecer um nome vlido.
Exemplos
// 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,{ NUMOPl, C, 10, 0})
AADD(aStru,{ PRODUTO, C, 15, 0})
AADD(aStru,{ QUANT , N, 16, 4})
AADD(aStru,{ ENTREGA, D, 8, 0})
AADD(aStru,{ ENTRAJ, D, 8, 0})
AADD(aStru,{ ORDEM , D, 4, 0})
AADD(aStru,{ GERADO , C, 1, 0})
cArqTrab := CriaTrab(aStru, .T.)
USE &cArqTrab ALIAS TRB NEW
8.6 - PROCREGUA
Tipo: Tela DOS/Windows
Inicializa rgua padro de processamento.
Sintaxe
ProcRegua(nRegs,nLinha,nColuna)
Parmetros
nRegs Nmero de registros que sero processados.
nLinha Nmero da Linha da rgua
nColuna Nmero da Coluna da rgua
Retorna
Nil
Exemplo
ProcRegua(1000)
For i:= 1 to 1000
IncProc()
Next
Return
No RdMake Windows a ProcRegua s utiliza o primeiro parmetro. No RdMake

DOS so utilizados os trs parmetros.
= Ver tambm IncProc()
8.7 - INCPROC
Tipo: Tela DOS/Windows
Incrementa rgua padro de processamento.
Sintaxe
IncProc()
Parmetros
Nil
Retorno
Nil
Exemplo
ProcRegua(1000)
For i:= 1 to 1000
IncProc()
Next
Return
2.8 - ACTIVATE DIALOG

Tipo: Tela
Desenha um box 3d.
Sintaxe
@ nLInha1,nColuna1 TO nLinha2,nColuna2 <TITLE> cTtulo
Parmetros
nLinha1 Nmero da linha superior
nColuna1 Nmero da coluna superior
nLinha2 Nmero da linha inferior
nColuna2 Nmero da coluna inferior
cTtulo Titulo apresentado na linha superior (opcional)
Comentrios
A clusula TITLE opcional. Se for omitida, o box no ter ttulo.
Exemplo
@ 000, 000 TO 430, 500 DIALOG oDlg TITLE (Tela de browse)
@ 060, 005 TO 185, 245 TITLE Exemplos
@ 070, 010 BUTTON U_Objetos SIZE 70,20 ACTION Execute(BasicObj)
@ 070, 090 BUTTON U_Browses SIZE 70,20 ACTION Execute(Browse)
@ 130, 170 BUTTON U_Dlg c/Refresh SIZE 70,20 ACTION Execute(DlgDinam)
@ 160, 090 BUTTON U_SQL SIZE 70,20 ACTION Execute(SqlDemo)
@ 192,218 BMPBUTTON TYPE 1 ACTION Close(oDlg)
ACTIVATE DIALOG oDlg CENTERED
8.9 - MBROWSE
Tipo: Processamento
Monta um browse padro do sistema, conforme os parmetros.
Sintaxe
mBrowse(nLinha1, nColuna1, nLinha2, nColuna2, cAlias, aFixe, cCpo, nPar, cCor, n Opc)
Parmetros
nLinha1 Nmero da linha inicial
nColuna1 Nmero da coluna inicial
nLinha2 Nmero da linha final
nColuna2 Nmero da coluna final
cAlias Alias do arquivo
aFixe Array contendo os campos fixos (a serem mostrados em primeiro
lugar no browse)
cCpo Campo a ser tratado. Quando vazio, muda a cor da linha
nPar Parmetro obsoleto
cCor Funo que retorna um valor lgico, muda a cor da linha
nOpc Define qual opo do aRotina que ser utilizada no double click
Exemplo
cCadastro := Cadastro de Orcamentos
aRotina := {{Pesquisar ,AxPesquil ,0,1};
{Incluir
,ExecBlock(DEMOA,.F.),0,3};
{Altera
,ExecBlock(DEMOB)l.,0,4};
{Exclui
,ExecBlock(DEMOC,.F.),0,5}}
MBrowse(6, 1, 22, 75, SA1)
8.10 - MARKBROWSE
Tipo: Processamento
Monta um browse padro do sistema, permitindo marcar e desmacar linhas.
Sintaxe
MarkBrowse(cAlias,cCampo,cCpo,aCampos,lMarc,cMarca,cCtrlM,lBotoes,cTopFun,cBotFun,aCoord)
Parmetros
cAlias lias do arquivo
cCampo Campo que estabelece relao com a culuna de marca
cCpo Campo que se estiver vazio muda a cor da linha
aCampos Array com os campos para montar o browse
lMarc Flag para inicializar marcado ou no
cMarca Marca obtida com a funo Getmark
cCtrlM Funo para ser executada no Alt_M
lBotoes Parmetro obsoleto
cTopFun Funo filtro para estabelecer o primeiro registro
cTopFun Funo filtro para estabelecer o ltimo registro
aCoord Array com as coordenadas da MarkBrowse.
Exemplo
cMarca := GetMark()
cCadastro := Escolher Clientes
aRotina := { { Pesquisa,.AxPesqui,0,1}, ;
{Visualizar,.AxVisual,0,2}}
MarkBrowse(SA1 , A1_OK , SA1->A1_OK , , , cMarca)

Apostila ADVPL Avançado

Enviado por

Dados do documento

Descrição:

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?

Descrição:

Direitos autorais:

Formatos disponíveis

Apostila ADVPL Avançado

Título original:

Enviado por

Descrição:

Direitos autorais:

Formatos disponíveis

Programao em ADVPL /

SQL / ASP com

Programao ADVPL /SQL / ASP

Com Protheus 5.08

Programao em ADVPL / SQL / ASP com AP5

Programao em ADVPL / SQL / ASP com AP5

5.1 A API de comunicao com o AP5

6.1 O AP5 Server como um servidor Web

1. Introduo ao ambiente Relacional

SQL / ASP com

Conceitos Bsicos de Banco de Dados

SQL / ASP com

Conhecendo a estrutura de Armazenamento dos dados

LOG do Banco de dados

Toda e qualquer operao de incluso, alterao ou excluso de registro armazenada

Programao em ADVPL / SQL / ASP com AP5

Construindo Querys evitando problemas com estouro da rea de LOG

rea temporria do Banco de Dados

Normalizao de Base de Dados

Programao em ADVPL / SQL / ASP com AP5

MER (Modelo Entidade Relacionamento)

Diferenas cruciais entre ambientes DBF e SQL

SQL Trabalha de forma relacional (Teoria dos conjuntos) e o acesso de forma

SQL / ASP com

MS-SQL Server 6.5 e 7.0

O TOPConnect composto por um biblioteca replaceble database driver(RDD) e componentes de

Controle de tipo de dados ( Tabela TOP_FIELD )

- so armazenados em variveis do tipo FLOAT

SQL / ASP com AP5

Os campo caracter no recebem nenhum tratamento.

SQL / ASP com

Sistema de controle de Registros

Funo da coluna R_E_C_N_O_

Renumerao da coluna RECNO

Programao em ADVPL / SQL / ASP com AP5

Controle dos registros deletados (Coluna D_E_L_E_T_)

Constraints do Banco de dados que so criados automaticamente

Criao da Estrutura de tabelas

Programao em ADVPL / SQL / ASP com AP5

Problemas com contedo Nulo

Programao em ADVPL / SQL / ASP com AP5

Manuteno do Banco de dados

SQL / ASP com

Funes em chaves de ndices

Chaves numricas compostas

SQL / ASP com

Expresses de filtro com funes e variveis

Programao em ADVPL / SQL / ASP com AP5

BEGIN, COMMIT, ROLLBACK TRANSACTION

Programao em ADVPL / SQL / ASP com

Programao em ADVPL / SQL / ASP com AP5

Microsoft SQL-Server 6.5

Programao em ADVPL / SQL / ASP com AP5

SQL / ASP com

Programao em ADVPL / SQL / ASP com AP5

SQL / ASP com

Programao em ADVPL / SQL / ASP com AP5

Programao em ADVPL / SQL / ASP com

( * )Funes apenas para o TOPConnect rodando em servidores AS/400.