Apostila ADVPL Avancado

Programação em ADVPL / SQL / ASP com AP5
Programação ADVPL /SQL / ASP
Com Protheus 5.08
Windows NT Server , Windows Workstation, Windows 95/98 e SQL Server são 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 didático/suporte e não pode ser reproduzido sem autorização da MicroSiga.
CopyRight © 2001 Microsiga Software S.A.
Índice
1. Introdução ao ambiente Relacional
1.1. Objetivos
1.2. Conceitos Básicos 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
1.3.1.2. Segurança e Backup
1.3.1.3. Construindo Query’s evitando problemas com estouro da Área de LOG
1.3.2. Área temporária do Banco de Dados
1.4. Normalização de Base de Dados
1.5. MER (Modelo Entidade Relacionamento)
1.6. Diferenças 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. Informações gerais
2.2. Controle de tipo de dados ( Tabela TOP_FIELD )
2.3. Opções de Visualizar os Eventos (Mensagens de Erros)
2.4. Sistema de controle de Registros
2.4.1. Portabilidade
2.4.2. Função da coluna R_E_C_N_O_
2.4.2.1. Limite de registros
2.4.2.2. Renumeração da coluna RECNO
2.4.3. Controle dos registros deletados (Coluna D_E_L_E_T_)
2.5. Constraints do Banco de dados que são criados automaticamente
2.5.1. Criação da Estrutura de tabelas
2.5.2. Índices
2.5.3. Defaults
2.5.4. Problemas com conteúdo Nulo
2.6. Manutenção do Banco de dados
2.6.1. Aumentando a performance executando a operação de PACK
2.7. DBFNTX x TopConnect
2.7.1. Índices de produção
2.7.2. Funções em chaves de índices
2.7.3. Índices condicionais
2.7.4. Chaves numéricas compostas
2.7.5. Expressões de filtro com funções e variáveis
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. Funções
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*
( * )Funções apenas para o TOPConnect rodando em servidores AS/400.
2.10. Performance
2.10.1. Otimizando seu código
2.10.2. Leitura Seqüencial
2.10.3. O uso de filtros
2.10.4. Stored Procedures
2.11. Integração 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. Utilitário importante
3.1. INSTALADOR DE STORED PROCEDURES NO BANCO DE DADOS
4. AP5 WEB - CONECTIVIDADE

5. RPC ENTRE O AP5 E OUTRAS APLICAÇÕES
5.1 A API de comunicação com o AP5

5.2 O Controle ActiveX
6. RPC ATRAVÉS DA INTERNET
6.1 O AP5 Server como um servidor Web
6.1.1 Serviços de FTP

6.1.1 Serviços de HTTP
6.2 Criando funções APL
6.2.1 Exemplo de função APL
6.3 O ADVPL ASP
6.3.1 Características do ADVPL ASP
7. Introdução
8. Funções 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. Introdução ao ambiente Relacional

1.1. Objetivos
Este curso tem como objetivo treinar e aperfeiçoar nossos analistas e parceiros quanto à confecção de
programas específicos, em ambiente de trabalho com Base de Dados SQL desta forma pretendemos
aumentar a facilidade de manuseio dos componentes envolvidos tanto na análise e detecção de erros, e
quais possíveis ações para saná-los, antes de recorrer ao suporte interno. Demonstraremos também
como otimizar programas através da linguagem SQL em seus RDMAKES e futuras implementações para
as próximas versões.
Todos os tópicos mencionados poderão servir como base de consulta, para escrita de programas e
resolução de problemas.
1.2. Conceitos Básicos de Banco de Dados
Os conceitos básicos dos Bancos de Dados relacionais são bem diferenciados dos conhecidos DBF
´s. Estes conceitos básicos são úteis principalmente para saber responder eventuais perguntas que
nossos clientes poderão efetuar sobre nosso sistema.
SQL quer dizer : Structured Query Language , que foi desenvolvido inicialmente pela IBM
Corporation.
Um banco de dados não trabalha em função de registros, ou Arquivos como nós estamos
acostumados a ver e fazer em linguagem de programação Clipper. o SQL utiliza a teoria de
conjuntos conhecida pôr todos, que tem o objetivo de resolver os problemas dos usuários com
comandos simples, chamados de query´s ( Requisição e Alteração de dados ), que utilizam
basicamente 4 comandos : SELECT, INSERT, UPDATE, DELETE.
A primeira diferença entre o ambiente SQL e o DBF é o fato de criarmos uma área no disco
(DATABASE) que o próprio banco se encarregara de administrar, no sentido de criar tabelas, índices,
e todos os objetos envolvidos no sistema. A nomenclatura muda um pouco: ao invés de CAMPOS
temos COLUNAS e ao invés de REGISTROS temos LINHAS.
Os índices trabalham de forma semelhante ao DBF, e são utilizados com duas finalidades : a de
termos uma chave de acesso extremamente rápida, e de garantirmos uma chave única em uma
tabela. A partir do momento que indicamos uma chave única em uma tabela, o próprio banco de
dados passa a garantir que não existirá dados duplicados, sem a necessidade de programação para
tal.
Também estarão ligados à uma tabela específica os Triggers, e as Foreign Keys ( Chaves
Estrangeiras ). Em cada DataBase também estarão armazenadas as Stored Procedures, que são
programas ou funções escritas como qualquer linguagem conhecida ( Clipper, Pascal etc.), só que no
padrão ANSI / SQL.
Uma Trigger funciona como um gatilho, só que este é disparado não a cada campo alterado, e sim a
cada Inclusão, Alteração ou Exclusão de uma linha da tabela. Os Triggers também são escritos como
as Stored Procedures, ou seja, como um programa qualquer, que pode efetuar qualquer tipo de
validação, atualização em outras tabelas, etc...
Hoje não utilizamos no Siga PROTHEUS nenhuma Trigger. Em alguns casos específicos em
clientes, as mesmas poderão ser utilizadas.
Uma Foreign Key ( Chave Estrangeira ) é uma ligação entre tabelas que são criadas nas mesmas.
São estas que garantem que nunca o Cliente “X” será excluído se o mesmo tiver movimentos
( Pedidos, Notas , Duplicatas Etc. ), também será garantido que nunca será incluído um Pedido de
Vendas do Cliente “Y”, se o mesmo não existir.
Este tratamento é feito diretamente pelo Banco de Dados, não necessitando qualquer codificação
para isto.
O Siga PROTHEUS/AP5 não trabalha hoje com o conceito de chaves estrangeiras no banco de
dados.
O uso de um Banco de Dados SQL se faz necessário pela segurança dos dados e pela fácil
recuperação dos mesmos por vários aplicativos como Siga PROTHEUS / AP5 (TopConnect), Crystal
Reports (ODBC), SigaEIS (BDE), Excel, etc.
Devido ao controle exercido sobre os dados a performance do banco acaba sendo prejudicada. Nos
próximos tópicos 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 utilização de banco de dados normalmente encontramos um
profissional chamado DBA (Data Base Administrator), que tem a função de administrar o banco de
dados, quanto a otimização, configuração, backups e segurança. Sabemos que na prática isto só
funciona para empresas grandes, portanto temos que saber o mínimo possível de cada banco de
dados para podermos identificar problemas e soluções que se adequam melhor à instalação 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 operação de inclusão, alteração ou exclusão de registro é armazenada

primeiramente na área de LOG. Se você faz uma inclusão no banco de dados de uma
simples linha o mesmo garante a inclusão completa da linha (inserção de todas as colunas).
Este fato é garantido pela definição no seu banco de dados de uma transação implícita.
Agora vamos supor que você tenha uma operação que necessite que várias inclusões,
alterações e exclusões realizadas só sejam efetuadas quando todas as operações tenham
sido efetuadas com sucesso, caso contrário todas as operações devem ser canceladas.
Para definição de transação pelo usuário, normalmente se utilizam os comandos BEGIN e
COMMIT , para definir início e fim de uma transação respectivamente. Para o cancelamento
de um transação 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 número de usuários e a quantidade de transações
realizadas em um determinado intervalo de tempo.
1.3.1.2. Segurança e Backup
Depois que uma transação é concluída com sucesso, não indica que a mesma estará sendo
transferida para a área real dos dados. Este tramite de transferência é chamado de
CheckPoint , este ponto é configurável de acordo o SGDB utilizado. Para bancos de dados de
maior escala, o processo de check point só é realizado após o Backup da área de LOG.
O LOG também é utilizado para fazer o backup de grande bancos de dados, guardando
somente as alterações efetuados em um determinado intervalo de tempo. Em clientes com
base de dados pequenas, não utilizamos este tipo de recurso.
1.3.1.3. Construindo Query’s evitando problemas com estouro da Área de LOG
Conhecendo melhor o processo de gravação do banco de dados, percebemos que quanto

menor for o número de operações de inserção, alteração e exclusão realizados dentro de
uma transação melhor será a performance. Banco de dados que possuem grandes
transações ocasionam problemas de deadlock. Realização de grandes updates na base de
dados sem informar a clausula Where delimitando um intervalo de linhas a serem
modificados. Na alteração e exclusão de linhas, precisamos tomar cuidado sempre com o
intervalo de registros, se for o caso devemos executar várias 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 temporária do Banco de Dados
Esta área é de utilidade exclusiva do Banco de Dados, a mesma é utilizada em situações que o
SGDB precisa gerar arquivo temporários para resolver as query’s que estamos solicitando,
normalmente operações que exigem um determinada ordenação no resultado e não existe
nenhum índice correspondente. Devemos tomar cuidado com query’s que necessitem área de
trabalho, por que elas estarão perdendo mais tempo com i/o de disco.
1.4. Normalização de Base de Dados
A normalização de Base de dados tem como objetivo, definir a estrutura de entidades e seus atributos
eliminando vários problemas de definição de armazenamento dos dados, que no momento da
implementação serão percebidos. Existe até cinco níveis de normalização , mas somente utilizamos
até o terceiro nível, atualmente não existe equipamento capaz de administrar um Banco de dados
normalizado totalmente.
Com a pratica vamos perceber que a normalização é muito boa, mas o seu excesso gera problemas na
programação, portanto temos sempre que fazer o máximo de normalização mas devemos estar
consciente de quanto conseguiremos de vantagem com isto.
Existe casos que a desnormalização é uma das melhores soluções, para facilitar o desenvolvimento da
aplicação 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 relação.
Ex.: Entidade = Pedido

Atributos = Data Emissão, Produto , Quantidade ,etc.
Neste caso criaremos um campo código que define a sua chave principal de
relacionamento, criaremos o Código. Nunca utilize mais de um coluna agregada com campo chave.(Este
tipo de campo gera vários problemas na programação 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).

Atributos = Número do Pedido (Chave), Data de Emissão, etc.
Entidade = Itens do Pedido

Atributos = Número, item (Número+item = chave), Quantidade, etc..
A terceira forma normal diz que devemos eliminar colunas que são concebidas por calculo de outras
colunas de mesma entidade.

Atributos = Total do Pedido, Quantidade Total, etc.
1.5. MER (Modelo Entidade Relacionamento)
A partir da normalização podemos definir as relações estrangeiras de cada tabela, o MER é uma
modelo gráfico que facilita a visualização do desenvolvimento de aplicativo. Além de apresentar todo o
fluxo do dado dentro de um Banco de Dados. No caso do SigaPROTHEUS / AP5 você ter em mãos
toda a estrutura do sistema é quase impossível, nestes casos o modelo é feito por módulo, e os pontos
de integração são replicados em cada MER do correspondente módulo.
Sempre que possível ao desenvolver processos específicos no sistema procure desenhar o MER para
detectar os problemas antes de sair desenvolvendo o produto.
1.6. Diferenças cruciais entre ambientes DBF e SQL

1.6.1. DBF – Trabalha de forma posicional com acesso compartilhado
Quando trabalhamos em um ambiente posicional, vários regras de programação e definição como

apresentamos acima, não precisam ser cumpridas. E mesmo assim os processos são rápidos e
de fácil manuseio. Este ambiente utiliza o modo Shared de controle de arquivos do sistema
operacional, ou seja, o servidor destes arquivos é apenas um mero repositório 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 nível de segurança 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 várias exigências como controle de acesso ao dado que é muito mais restrito, a
programação feita na aplicação deve ser bem otimizada para evitar requisições desnecessárias, o
SGDB precisa utilizar processamento do Servidor para recuperar um dado solicitado pela
aplicação. 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. Informações gerais
O TOPConnect foi desenvolvido em linguagem ‘C’ pela Microsiga e é utilizado hoje pelo
SigaPROTHEUS / AP5 através da linguagem ADVPL (PROTHEUS Protheus Language). Ele
também pode ser utilizado por aplicações XBASE que queiram trocar a base de dados de DBF para
SQL.
Os gerenciadores de banco de dados hoje suportados são:
 MS-SQL Server 6.5 e 7.0 ( MSSQL / MSSQL7 )

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

comunicação, sendo estes bibliotecas para aplicativos DOS e DLL's para aplicativos Windows. Estas
bibliotecas devem ser linkeditadas com sua aplicação ADVPL para acessar o TOPConnect Server.
Alguns comandos e funções avançadas são disponibilizadas para que seu aplicativo possa usufruir
de todos os benefícios da plataforma cliente servidor, que são apresentados logo em seguida.
2.2. Controle de tipo de dados ( Tabela TOP_FIELD )
Em um banco existem vários tipos de dados (CHAR, VARCHAR, FLOAT, NUMBER, etc.) porem para
existir uma unicidade no código do Topconnect alguns dados são armazenados de forma diferente da
definida na tabela SX3, porem a aplicação recebe o dado da forma como definido.
Os tipos de dados que são tratados atualmente são o seguintes:
 Campos numéricos - são armazenados em variáveis do tipo FLOAT

 Campos Lógicos - são armazenados em variáveis do tipo CHAR (0 ou 1)
 Campos Data - são armazenados em variáveis do tipo CHAR com 8 bytes, no formato
YYYYMMDD.
Os campo caracter não recebem nenhum tratamento.
A tabela TOP_FIELD contem a descrição de todos os campos NAO-CARACTER, para que o

TopConnect faca a conversão dos dados quando da leitura dos mesmos.
Ela é “alimentada” na criação de uma tabela.
Ex.: Tabela SA1010
A1_FILIAL C 2
A1_COD C 6
A1_LOJA C 2
A1_DESC C 1
A1_EMISSAO C 8
A1_VEND1 C 6
...
Ex.: Tabela TOP_FIELD
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 vocês perceberão que na tabela TOP_FIELD só existe os campo numéricos, data e
Lógico (no caso não existe nenhum usado pelo arquivo).
Alerta! : Se você for utilizar diretamente o Banco de dados você precisa estar ciente que
um campo numérico é 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 query’s você deve utilizar a função TCSETFIELD para resolver esta situação.
(Veja função TCSETFIELD).
Importante também salientar que qualquer modificação efetuada em arquivo SX3 diretamente,
ou seja, sem utilizar o configurador, você pode Ter problemas com inconsistência de estrutura
da tabela do Banco de Dados e TOP_FIELD contra o dicionário 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 dicionário de dados manualmente conforme estrutura no Banco de Dados.
2.3. Opções de Visualizar os Eventos (Mensagens de Erros)
A parte mais importante do Topconnect Manager é o gerenciamento das mensagens de erros, estas
mensagens não são 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 utilitário do próprio 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. Sistema de controle de Registros

2.4.1. Portabilidade
Acreditamos que muitos já perguntarão por que da existência da coluna R_E_C_N_O_ no Banco
de dados, mesmo os que não conhecem esta coluna tem como objetivo manter a portabilidade de
uma Base DBF e Banco ADS para um Banco de Dados qualquer e também entre Banco de dados.
Se você possui sua aplicação trabalhando em DBF , você pode porta-la independente de
modificações 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 específicos desenvolvidos (RDMAKES), você precisa que os
mesmos estejam desenvolvidos nos padrões de compatibilidade exigidos pela Microsiga. Você
verá mais adiante exemplos de programas e uma apresentação mais completa deste assunto.
2.4.2. Função da coluna R_E_C_N_O_
A Coluna R_E_C_N_O_, tem por objetivo principal guardar um número seqüencial de controle de
registro, mais conhecido como ID (identificador). Este identificador é utilizado pela aplicação na
pesquisa e posicionamento de registro.
Esta coluna não possui repetição, ela é sempre preenchida com o valor máximo da coluna
R_E_C_N_O_ + 1 nas próximas inserções. Esta operação é feita pelo TopConnect , se você utiliza
outros produtos que fazem inserção na Base de Dados do SigaPROTHEUS / AP5 você deve seguir
as orientações do Capítulo Integrações com outros aplicativos.
2.4.2.1. Limite de registros
O limite de registros em uma tabela é de 2,147,483,648 , este número normalmente deve

ser levado em consideração para as tabelas que recebem muita inserção de registro
seguidas de muitas exclusões física do registro.
2.4.2.2. Renumeração da coluna RECNO
Quando os registros são deletados pelo sistema, os mesmos são apenas marcados,
para exclusão física acontece em quando executamos a operação que conhecemos com
Pack de registros. Após esta operação a coluna R_E_C_N_O_ não é renumerada. Não
existe a necessidade de fazer a renumeração desta coluna, a não ser que você esteja
perto de estourar o maior número possível 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 exclusão de registro feita no Banco de Dados ou em qualquer plataforma do SigaPROTHEUS

/ AP5, só é feita logicamente, ou seja, o registro é marcado como excluído (delete), e esta marca é
feita utilizando o campo chamado D_E_L_E_T_ , a mesma é preenchida com (*) Asterisco, caso
contrário a coluna permanece com o conteúdo em branco.
Alerta! : Quando você utiliza o comando Set Delet on/off, o TopConnect estará tratando o dado
para você, mas se você utiliza query’s para recuperação de dados você deverá tratar este coluna
(Mais informações sobre o tratamento da coluna D_E_L_E_T_ será apresentado em exemplos de
query’s em RDMAKES.
2.5. Constraints do Banco de dados que são criados automaticamente
2.5.1. Criação da Estrutura de tabelas
A estrutura de cada tabela do SigaAdvacend é criada automaticamente, tendo em vista a não

existência da mesma no Banco de Dados. Para isto o usuário criado para o TopConnect acessar
o banco de dados precisa Ter permissão de criação de tabelas, de preferência a permissão de
DBA.
Neste momento a tabela TOP_FIELD estará sendo alimentada com todos os campos numéricos,
datas e Lógicos.
Alerta! : Após o primeiro usuário fazer a conexão com o TopConnect e a parte de verificação de
tabelas já foi executada, as referências de cada tabela selecionado no .mnu para abertura
estarão em memória no TopConnect, portanto se por acaso alguma tabela for removida
diretamente por um utilitário do Banco de Dados o TopConnect terá uma informação não
coerente, você deve reiniciar o serviço do Topconnect (Parando / iniciando o Serviço).
2.5.2. Índices
Os índices são criados imediatamente após a criação 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 formação do nome = <nome da tabela> + _RECNO , este índice e sempre composto
da coluna R_E_C_N_O_ e não permite duplicidade.
Alerta!: Nunca remova os índices das tabelas, principalmente o índice RECNO que não 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
também do Banco de Dados.
2.5.3. Defaults
São constraints de validação de campos que não são informados, nos comandos de inserção e
alteração, ou seja, se você não possui os defaults criados o Banco de Dados estará deixando
estes campos com valor nulo. Os defaults são criados no momento da criação das tabelas.
Alerta!: Se você fizer qualquer operação de transferência via Banco de Dados que não 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 conexões com dados indevidos. A solução neste caso é utilizar o
utilitário DEFAULT que esta disponível 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 não 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 conteúdo Nulo
Os Bancos de dados possuem o conteúdo nulo para todos os tipo de campos, mas o nosso
sistema não 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
não tem os contraints de defaults na coluna filial, agora você faz a inserção 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
espaço em branco.
Este problema muitas vezes causa a impressão que o índice esta com problemas, por que a
tela de Browse do SigaPROTHEUS / AP5 não apresenta a coluna filial.
Alerta!: Tabelas com conteúdo nulo, geram vários problemas no sistema, provavelmente deve
gerar erros no TopConnect que o mesmo estará derrubando as conexões quando elas fizerem
acesso a este tipo de conteúdo (nulo). Existe um utilitário que ajusta este problema se você o
tiver, o mesmo esta disponível no site da Microsiga, com o nome de DEFAULT.exe
2.6. Manutenção do Banco de dados

2.6.1. Aumentando a performance executando a operação de PACK
Esporadicamente você deve fazer uma manutenção no Banco de dados, quanto as registros
excluídos logicamente, os mesmo devem ser excluídos fisicamente, por que a sua existência em
grande quantidade e de forma seqüencial gera um grave problema de performance no acesso aos
dados.
Alerta!: Se você tiver este problema, utilize a operação de Pack do utilitário SDU na tabela que
possui registros excluídos , ou utilize o programa fonte PACK para fazer esta operação 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
/*
Função ³PACK ³ Autor ³ Emerson/Vicente ³ Data ³ 16.12.99
Descrição ³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
Descrição ³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
return
2.7. DBFNTX x TopConnect

2.7.1. Índices de produção
Todos os SGDB's utilizam o conceito de índices de produção portando uma aplicação que utilize o
TOPConnect não necessita ter todos os índices abertos para que os mesmos sejam atualizados.
2.7.2. Funções em chaves de índices
Devido ao fato de os SGDB's não suportarem o uso de funções nos índices o TOPConnect não tem
como suportar este tipo de implementação.
As únicas funções suportadas são STR e DTOS.
Para a criação de índices que contenham campos caracter e numéricos na chave apenas uma
regra deve ser obedecida. A função STR deve obrigatoriamente receber como parâmetros valores
idênticos a definição da tabela.
Exemplo:
Em um arquivo com a seguinte estrutura:
CAMPO1 – Caracter de 10 posições.

CAMPO2 – Numérico de 14 Posições 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 não 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 aplicação 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 função OrderBy nos filtros o que reproduz o mesmo efeito de um
índice filtrado.
O TOPConnect disponibiliza os dados na ordem solicitada pela cláusula OrderBy na Ordem 0 do

arquivo, não interferindo assim com os índices do arquivo.
2.7.4. Chaves numéricas compostas
Os SGDB's não suportam índices que contenham expressões ADVPL onde dois campos numéricos
são somados na chave.
Exemplo:
INDEX ON CPOVAL1 + CPOVAL2 TO ARQIND
2.7.5. Expressões de filtro com funções e variáveis
Uma vez que o TOPConnect utiliza a arquitetura Cliente/Servidor o servidor não tem como avaliar o
conteúdo de uma variável de memória ou o retorno de uma função do cliente.
O TOPConnect permite a utilização de variáveis e funções nos filtros porém é necessário ter em
mente que a avaliação deste filtro ocorrerá no cliente e não 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 avaliação seja feita no
servidor e que apenas os registros que obedeçam ao filtro venha para o cliente.
Agora este:
SET FILTER TO CODIGO > RetornaCodigo()
Considerando que RetornaCodigo é uma função ADVPL da aplicação todas as linhas deste arquivo
serão 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 máximo possível de uma expressão seja avaliada
no servidor.
Pôr exemplo:
SET FILTER TO ESTADO = 'SP' .AND. SALDO > 10000 .AND. CODIGO > RetornaCodigo()
Nesta expressão somente virão para o cliente os registros onde os campos ESTADO e SALDO
obedeçam ao filtro e então o campo CODIGO será avaliado no cliente.
2.8. Comandos
Neste capítulo 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 utilização destes comandos o programa deverá conter a seguinte instrução:
#INCLUDE "TOPCONN.CH"
2.8.1. APPEND FROM
Em uma aplicação 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 parâmetro 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 aplicação 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 parâmetro opcional VIA também 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 usuário terá acesso a esta tabela. Todas as outras
tentativas de colocar esta mesma tabela em uso falharão.
SHARED Especifica que a tabela será aberta em modo compartilhado.
NEW Abre a tabela <cTable> na próxima Work Area disponível. Se esta clausula não for
especificada, <xcTable> será na Work Area corrente.
READONLY Abre <cTable> apenas para leitura.
VIA "TOPCONN" Este parâmetro indica ao ADVPL que esta Work Area será gerenciada
pelo TOPconnect.
Se nenhum parâmetro 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 início de uma transação no banco de dados.

Desde o ponto em que uma aplicação executa um BEGIN TRANSACTION cada APPEND ou
REPLACE encontrado até um COMMIT TRANSACTION ou ROLLBACK TRANSACTION serão
considerados uma única transação.
Os demais usuários somente terão acesso aos novos registros ou às modificações após 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

//Adiciona um pedido
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. Funções
2.9.1. TCCANOPEN
Verifica a existência de tabelas e índices no servidor.

Sintaxe
TCCanOpen(cTable [, cIndice]) =>lógico
Exemplo
//Testa a existência da tabela customer
IF !TCCanOpen("CUSTOMER")
dbCreate("CUSTOMER", aStru, "TOPCONN")
ENDIF
USE CUSTOMER SHARED NEW VIA "TOPCONN"
//Testa a existência 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 comunicação 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 utilitário TOPBrigde para comunicação de estações DOS NPIPE com
servidor AS/400 utilizando TCP/IP.
Exemplo
//Especifica conexão 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 excluída.

Exemplo
TCDelFile("CUSTOMER")
2.9.4. TCGETDB
Retorna o Tipo de Banco de Dados corrente
cDataBase := TCGETDB()
Onde os valores de retorno são :
MSSQL Microsoft SQL-Server 6.5

MSSQL7 Microsoft SQL-Server 7.0
ORACLE Oracle
DB2 IBM Universal Database
SYBASE Sybase SQL-Server
ANYWHERE Sybase SQL Anywhere
ANYSYBASE Sybase SQL Anywhere
(Emulando Sybase SQL-Server)
INFORMIX Informix
2.9.5. TCLINK
Abre uma conexão com o Servidor TOPConnect.

Sintaxe
nCon := TCLink(<cConectString>,<cServer>)
Onde o parâmetro <cConnectString> é composto por:
Para TOPConnect NT : Nome do Banco de Dados / Nome do Ambiente

Para TOPConnect/400: Nome do Ambiente
O parâmetro <cServer> contém:

Para conexões NamedPipe, APPC e Brigde : O nome do servidor TOPConnect
Para conexões TCP/IP : O endereço IP do servidor TOPConnect
Para o TOPConnect NT acessando Oracle, um ambiente é o nome do Alias criado com o utilitário
SQL-Net.
Para o TOPConnect NT acessando os demais SGDB's um ambiente é um System DSN criado

através do ODBC Data Source Administrator.
Para o TOPConnect AS/400 um ambiente é uma Library criada através do comando
CRTTOPENV do TOPConnect.
Para informações sobre a criação de ambientes consulte o manual de instalação do

TOPConnect.
Esta é a lista de Bancos de Dados hoje suportados e seus respectivos nomes compor a string de
conexão com o TOPConnect NT:
Microsoft SQL-Server 6.5 MSSQL

Microsoft SQL-Server 7.0 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 função TCLink retorna ou o número da conexão ou um valor negativo contendo o código 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 //Conexões com retorno < 0 significam erro
Alert("Falha de conexão 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. TCQUERY
Executa uma Query no servidor e coloca seu retorno em uma WorkArea.

Sintaxe:
TCQUERY [<cSQLExpr>
[ALIAS <xcAlias>]
[NEW]
VIA "TOPCONN"
<cSQLExpr> Expressão SQL a ser enviada ao servidor.

ALIAS < cAlias> Especifica um nome para a Work Area a ser aberta
NEW Abre a tabela <cTable> na próxima Work Area disponível. Se esta clausula não for
especificada, <xcTable> será na Work Area corrente.
VIA "TOPCONN" Este parâmetro indica ao ADVPL que esta Work Area será gerenciada
pelo TOPconnect.
A Work Area criada com o comando TCQUERY é READ-ONLY, portanto não é permitido o uso
de APPEND's ou REPLACE's.
O TOPConnect tem apenas um cursor para a Query executada portando apenas os seguintes
comandos são 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 serão 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 conexões com o TOPConnect

Sintaxe
TCQuit()
2.9.8. TCSETCONN
Seleciona conexão ativa.
Sintaxe
TCSETCONN(<nConn>)
Onde <nConn> é o número da conexão.
Exemplo
// Abre conexão com o ambiente de Produção
nCon1 := TCLink("MSSQL/PRODUCAO")
if nCon1 < 0
Alert("Falha conectando ambiente de Produção")
QUIT
endif
// Abre conexão 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 produção

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 função serve como apoio ao comando TCQUERY, na recuperação de campos tipo
NUMERIC, DATE e LOGICAL, pois os mesmos são gravados fisicamente no Banco de Dados
como caracteres, e no caso dos numéricos 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 não mais um
campo caracter como é o seu armazenamento.
O campo Data só é retornado como um campo caracter por que estamos utilizando a função
TCQUERY, se não o tratamento é automático.
2.9.10. TCSPEXEC
Executa uma Stored Procedure no Banco de Dados.
Devido a uma limitação em alguns dos Bancos de Dados suportados na obtenção dos tipos de
parâmetros (se são de INPUT e/ou OUTPUT) todos as Stored Procedures a serem executadas
através do TOPConnect deverão obedecer o seguinte padrão de nomenclatura de seus
parâmetros :
Parâmetros de INPUT devem começar com IN_... Ex. IN_VALOR.

Parâmetros de OUTPUT devem começar com OUT_... Ex. OUT_CODIGO
Após a execução de uma Stored Procedure o TOPConnect retornará ao ADVPL um array com 'n'
elementos, onde n é o número de parâmetros de OUTPUT da Stored Procedure.
Sintaxe
<aRet> := TCSPExec(<cSPName>,[<xParam1>,<xParam2>...<xParamN>])
Onde <aRet> é um array com os parâmetros de retorno da Stored Procedure e <cSPName> é o

nome da Stored Procedure a ser executada e os demais parâmetros variam conforme a definição
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 existência de uma determinada Stored Procedure no servidor.

Sintaxe
<lExist> := TCSPExist(<cSPName>)
Onde <lExist> indica se a Stored Procedure existe ou não 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 execução 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 conteúdo igual a "WinNT" ou "AS/400".
Exemplo
TCLink("MSSQL/TESTE","TOPSRV")
?TCSrvtype()
2.9.15. TCUNLINK
Encerra uma conexão com o TOPConnect.

Sintaxe
TCUnlink(<nConn>)
Onde <nConn> é o número da conexão retornado pela função TCLink()

Exemplo
TCConType("NPIPE")
nConn := TCLink("MSSQL/TOPCONN","TOPSRV")
TCUnLink(nConn)
2.9.16. TCCHKOBJ*
Verifica a existência de um objeto no servidor AS/400

Sintaxe
<nError> := TCChkObj(<cObj>,<cLibrary>,<cType>)
Onde:
<nError> é 0 quando o objeto existe ou o número 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 FUNÇÃO SE APLICA APENAS PARA O TOPCONNECT AS/400
2.9.17. TCEXEERROR*
Retorna uma string com a mensagem de erro retornada pela execução das funções
TCPGMEXE() e TCSYSEXE().
Sintaxe
<cError> := TCExeError()
Onde <cError> é a string com a mensagem de erro.

Exemplo
?TCExeError()
2.9.18. TCPGMEXE*
Executa um programa no servidor AS/400
TCPGMEXE( program name )
2.9.19. TCSYSEXE*
cCommand := "CRTCBLMOD MODULE("+cTDataBase+"/"+ cName+"F"+cCrrEmp+") "

cCommand += "SRCFILE("+cTDataBase+"/QSPSRC) "
cCommand += "SRCMBR("+cName+"F"+cCrrEmp+") "
cCommand += "REPLACE(*YES)"
TCSysExe( cCommand )
2.10. Performance
2.10.1. Otimizando seu código
A linguagem ADVPL tem um enfoque posicional, recuperando os dados utilizando orientação a

registros, enquanto aos Bancos de Dados SQL recuperam os dados por blocos de dados.
Devido a esta diferença conceitual, vários pontos devem ser levados em consideração para que
se possa obter uma boa performance e utilizar os recursos de uma aplicação Client/Server.
2.10.2. Leitura Sequencial
Operações de leitura seqüencial de uma tabela podem levar a problemas de performance.

Vamos analisar o seguinte código:
dbSelectArea("CLIENTES")
nValor := 0
Do While !Eof()
If ESTADO = "SP"
nValor += SALDO
Endif
DbSkip()
End
O código acima fará com que todas as linhas(registros) da tabela venham para o Client, o que irá
gerar um número de Queries no servidor igual ao número de linhas da tabela e cada uma delas
irá recuperar apenas uma linha, subtilizando a capacidade de processamento do servidor.
O código acima poderia ser substituído por:

TCQUERY "SELECT SUM(SALDO) ;
FROM CLIENTES ;
WHERE ESTADO = 'SP'" NEW
nValor := COLUMN1
Com a utilização do comando TCQUERY todo a somatória é feita no servidor retornando assim
para a aplicação apenas uma linha com o resultado desejado.
2.10.3. O uso de filtros

O uso de filtros em aplicações ADVPL são conhecidos como fonte de problemas de performance.
Isto se deve ao fato de que todos os registros são avaliados pela estação.
O mesmo não ocorre utilizando o TOPConnect, pois o filtro é avaliado pelo próprio servidor vindo
para a estação apenas os registros que respeitem a condição do filtro.
Para que um filtro tenha uma boa performance é necessário que a expressão do filtro
corresponda a um índice no servidor, caso contrário, 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 aplicação se utilizar dos
benefícios da arquitetura Cliente/Servidor.
O TOPConnect suporta o uso de Stored Procedures conforme documentado na função

TCSPExec()
2.11. Integração com outros aplicativos

2.11.1. Incluindo registros nas tabelas do SigaPROTHEUS / AP5
As tabelas criadas no Banco de dados pode receber inserções de outros aplicativos, esta
inserção deve ser feita contemplando as seguintes operações :
 Antes de inserir o registro você deve obter o número máximo da coluna R_E_C_N_O_
existente na tabela
 Deste número você deve somar 1
 Logo em seguida fazer a inserção propriamente dita do registro
 Se o registro não 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 exclusão de registro por outros aplicativos você deve apenas
fazer uma operação de alteração do registro, colocando o símbolo de ‘*’ na coluna D_E_L_E_T_,
principalmente se esta operação for concorrente com o SigaPROTHEUS / AP5.
2.11.3. Vantagens e Desvantagens
As vantagens deste processo é a agilidade na integração entre os sistemas, não existe a

necessidade de gerar arquivos textos, para depois fazermos a integração. Principalmente em
situações on-line , utilizar o recurso do Banco é uma das melhores saídas.
As desvantagens deste processo, são que você deve estar ciente de todas atualizações que são
feitas na base de dados no sistema, já que o sistema esta desta forma vulnerável a problemas
inesperados.
Normalmente aconselhamos a sempre fazer a atualização em tabelas específicas e depois criar

rotinas pelo sistema o qual repassarão os dados destas tabelas para as tabelas definitivas, desta
forma vamos evitar problemas na atualização de versão, ou até em alguma mudança de estrutura
que o configurador faça.(Você estará perdendo os triggers desta tabela).
3. Ferramenta importante
3.1. Instalador de Stored Procedures no Banco de Dados
Alguns clientes utilizam rotinas como Stored Procedures para agilizar alguns processos críticos do
sistema, para instalação 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)
Após a confirmação desta operação todas as Procedures que estiverem disponíveis neste arquivo serão
compiladas para a empresa em questão, 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 instalação das Stores Procedures será gerado

um arquivo de log chamado SPBuild.LOG no diretório \SIGAADV\. E também 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 aplicações,
gerenciamento das conexões e compilação de programas. E uma de suas principais características é a alta conectividade. Ou
seja, o AP5 pode ser integrado a diferentes soluções ou sistemas, através da utilização de uma API de acesso (contida em uma
DLL) ou um controle ActiveX, ou mesmo diretamente através da Web (via protocolo HTTP ou FTP). Isso permite outras
aplicações a terem acesso a execução de funções (jobs) no AP5, utilizando o conceito de RPC.
RPC (Remote Procedure Call) significa Chamada Remota de Procedimentos, ou seja, através de uma aplicação externa (ou
através da Internet) é possível executar no AP5 rotinas criadas em ADVPL. Tais rotinas poderão realizar todo o tipo de tarefa
desejada, como por exemplo cadastrar um pedido, um cliente, ou emitir um relatório em formato HTML, retornando
informações à aplicação externa.
A utilização da API de acesso e do controle ActiveX é mais indicada para aplicações desenvolvidas em outras linguagens e
que necessitem interagir com o AP5. Já com o acesso via Internet, é possível criar toda uma aplicação Web que alie o poder
de processamento do AP5 com a facilidade de formatação de interface do HTML.
RPC Entre o AP5 e Outras Aplicações
São duas as opções para realizar RPC entre uma aplicação externa e o AP5:
 Uma API de acesso, utilizando a DLL (Dinamic Link Library) chamada AP5DCONN.DLL;
 Um controle ActiveX , utilizado através do arquivo AP5CONNXCONTROL.OCX.
Ambas opções têm as mesmas funcionalidades:

 Conexão a um ou mais servidores AP5;
 Acesso a algumas funções gerenciais, como obtenção de lista de usuários conectados, envio de mensagens, e
gerenciamento das conexões;
 Execução de jobs e procs. Os jobs podem ser executados no AP5 sem que necessariamente a aplicação externa
aguarde pelo retorno. Podem assim permanecer executando no AP5 Server enquanto a aplicação externa realiza
outras tarefas, ou mesmo executa outros jobs. Os procs entretanto, sempre farão com que a aplicação externa
aguarde o retorno do AP5;
 Os jobs ou procs são funções contidas no repositório do AP5 (incluindo as funções criadas por usuários – User
Function). A aplicação externa pode, sempre através da DLL ou da OCX, enviar parâmetros e receber o retorno
destas funções, segundo os tipos de dados válidos: Caracter, numérico, lógico, data e array;
 A conexão ao AP5 é sempre efetuada através do protocolo TCP/IP. O acesso ao AP5 Server somente será efetuado
se a correta senha e usuário forem informados. A checagem dessa senha é efetuada pelo Advanced, e deve ser
mantida através do SIGACFG. O usuário informado deve ser o Administrador do sistema ou pertencer ao grupo
Administradores;
Geralmente a utilização de uma dessas opções será indicada para aplicações 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, é necessário a DLL de comunicação do AP5 chamada
AP5CONN.DLL. Por isso, sempre que for necessário utilizar uma dessas opções, a DLL de comunicação deve
estar em um path localizável pelo Windows e deve estar atualizada em relação ao AP5 Server em que a aplicação
externa tentará se conectar.
A API de comunicação com o AP5
Para utilizar a API de comunicação do AP5, é necessário conhecer a linguagem em que a aplicação externa está escrita, a
ponto de poder utilizar o conceito de DLL´s do Windows. Qualquer linguagem de programação que suportar a utilização de
DLL´s poderá utilizar a API de comunicação.
Diferentemente do controle ActiveX, a DLL de comunicação não pode ser tratada como um objeto, porém podem existir
várias instâncias de comunicação, o que permite a comunicação com diferentes servidores do AP5 simultâneamente. O
processo de utilização resume-se em:
1. Criação de uma instância de comunicação;

2. Conexão ao AP5 Server;
3. Utilização efetiva: Execução de rotinas, obtenção do retorno, etc;
4. Desconexão;
5. Destruição da instância de comunicação.
Para tal, existem as seguintes funções disponibilizadas na DLL de comunicação:
AP5CreateConnControl
Descrição: Criação de uma instância de comunicação com o AP5 Server. Pode-se criar diferentes
instâncias de comunicação, acessando um ou mais servidores do AP5.
Parâmetro cServer: char * - Nome ou endereço IP do servidor para a conexão;

s: nPort: int - Porta do socket TCP/IP utilizada para a conexão;
cEnvironment: char * - Ambiente utilizado para a execução de processos;
cUser: char * - Usuário do sistema para validação da conexão. O usuário informado deve
pertencer ao grupo Administradores do sistema;
cPassWord: char * - Senha do usuário informado, para validação da conexão.
Retorno: int - Retorna o Handle da instância criada. Este Handle retornado deverá ser informado em
todas as demais funções de comunicação, para identificação da instância que será utilizada.
Sintaxe: nAP5 = AP5CreateConnControl(“APSERVER”, 1024, “ENVIRONMENT”, “Administrador”,

“”)
AP5DestroyConnControl
Descrição: Destruição de uma instância de comunicação com o AP5 Server. Após a utilização da API, e
antes de encerrar a execução da aplicação externa, é necessário destruir o Handle criado com a
função anterior para a liberação de memória.
Parâmetro nObjectID: int - Handle da instância criada com a função anterior.

s:
Retorno: bool - Retorna verdadeiro ou falso, indicando a execução com sucesso da função.
Sintaxe: lOk = AP5DestroyConnControl(nAP5)
AP5Connect
Descrição: Conexão a um AP5 Server. Esta função não deve ser confundida com a função
AP5CreateConnControl. Esta função irá realizar a conexão com o AP5 Server indicado durante
a criação da instância informada como parâmetro.
Parâmetro nObjectID: int - Handle da instância que será utilizada para a execução desta função. É através
s: do Handle que é definido em qual servidor, porta e ambiente os processos serão executados.
Retorno: bool - Retorna verdadeiro ou falso, indicando se a conexão foi efetuada com sucesso.
Sintaxe: lOk = AP5Connect(nAP5)
AP5Disconnect
Descrição: Desconexão de um AP5 Server. Esta função não deve ser confundida com a função
AP5DestroyConnControl. Esta função irá encerrar a conexão ativa com um AP5 Server, da
instância informada como parâmetro.
Parâmetro nObjectID: int - Handle da instância que será utilizada para a execução desta função.
s:
Retorno: Sem retorno.
Sintaxe: AP5Disconnect(nAP5)
AddNullParam,
AddNumericParam,
AddStringParam,
AddLogicalParam,
AddDateParamAsDouble,
AddDateParamAsString,
AddArrayParam
Descrição: Estas funções são utilizadas para a execução de processos em um servidor AP5. Podem ser
utilizadas somente após uma conexão ser ativada. Um processo executado em um servidor AP5
pode necessitar de parâmetros, que deverão ser enviados ao servidor antes da execução do
processo através da utilização destas funções. Os tipos de dados que podem ser enviados são:
Numérico (int), Caracter (char *), Lógico (bool), Data (enviado como caracter – char * - ou
como numérico - int) e Array (variant).
Parâmetro nObjectID: int - Handle da instância que será utilizada para a execução desta função. É através
s: do Handle que é definido para qual servidor o parâmetro será enviado;
xParametro: indefinido - O tipo de dado do parâmetro dependerá da função utilizada, segundo
os tipos de dados permitidos explicados acima.
Retorno: bool - Retorna verdadeiro ou falso, indicando se o parâmetro pôde ser enviado ao AP5 Server
com sucesso.
Sintaxe: lOk = AddNumericParam(nAP5,5)
ou
lOk = AddStringParam(nAP5,“TEXTO”)
ou
lOk = AddLogicalParam(nAP5,true)
ResultAsNumeric,
ResultAsString,
ResultAsLogical,
ResultAsDate,
ResultAsDateString,
ResultAsArray
Descrição: Estas funções são utilizadas para obter o retorno do AP5 Server após a execução de um
processo.
Parâmetro nObjectID: int - Handle da instância que será utilizada para a execução desta função.
s: Apenas para as funções ResultAsString e ResultAsDateString:
cBuffer: char * - Buffer de caracteres alocado para receber o retorno em formato caracter;
nSize: int - Tamanho do buffer passado no parâmetro anterior.
Retorno: O tipo de dado do retorno dependerá da função utilizada, segundo os tipos de dados definidos
anteriormente. Para as funções 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
Descrição: Função utilizada para obter o número do build de compilação da API de conexão ao AP5.
Parâmetro nObjectID: int - Handle da instância que será utilizada para a execução desta função;
s: cBuild: char * - Buffer de caracteres para receber o número do build;
nSize: int - Tamanho do buffer passado no segundo parâmetro.
Retorno: int - Retorna o tamanho do buffer contendo o número do build.

Sintaxe: AP5BuildNumber(nAP5,cBuffer,nSize)
PrepareEnv
Descrição: Função utilizada para preparar o ambiente do sistema, ou seja, abrir arquivos, criar variáveis, e
tornar o ambiente de execução da aplicação externa em relação ao AP5 Server, o mais parecido
possível com o que é realizado pelos módulos do sistema.
s: cEnv: char * - Ambiente que será utilizado para a abertura dos arquivos;
cEmp: char * - Código da empresa do sistema (dois dígitos) que deverá ser aberta;
cFil: char * - Código da filial que será utilizada (dois dígitos);
aTables: variant – Este parâmetro deve ser um array variant (para detalhes, consulte a
documentação da linguagem utilizada) contendo as siglas das tables que deverão ser abertas
(por exemplo “SB1”).
Retorno: bool - Retorna verdadeiro ou falso, indicando o sucesso da execução da função.

Sintaxe: PrepareEnv(nAP5,“ENVIRONMENMT”,“99”,“01”,aTables)
StartJob
Descrição: Esta função permite a execução de um processo (job) em um AP5 Server. O processo executado
pode ser qualquer um dos existentes no repositório definido pelo ambiente informado, incluindo
as funções criadas pelo usuário (User Function). Pode também receber parâmetros, bem como
retornar um valor para a aplicação externa, sempre utilizando-se das funções descritas
anteriormente. A execução de um processo resume-se em:
A)
1. Enviar os parâmetros (se existirem);
2. Executar o processo e aguardar sua finalização;
3. Obter o resultado (se existir).
B)
1. Enviar os parâmetros (se existirem);
2. Executar o processo sem aguardar sua finalização;
Os processos são executados em threads de execução separadas. Isso permite à aplicação

externa que esteja utilizando a API, optar por executar o processo e continuar trabalhando
enquanto o mesmo está em execução. Porém, somente poderá obter um retorno quando esperar
até que o processo termine de ser executado.
Obs.: Como estes processos são executados sem que uma instância do AP5 Remote esteja ativa,
devem ser criados sem nenhum comando de interface (criação de janelas, comandos de alerta,
help, etc). Se um comando de interface for utilizado no código ADVPL de um processo, a
execução deste através da API gerará um erro de execução.
s: cEnv: char * - Ambiente que será utilizado para a execução do processo;
cFunc: char * - Nome do processo ou função que será executado no AP5 Server;
lWait: bool - Verdadeiro ou Falso indicando se a aplicação externa deverá ou não aguardar pelo
término da execução do processo.
Retorno: bool - Retorna verdadeiro ou falso, indicando se o processo foi iniciado com sucesso.
Sintaxe: StartJob(nAP5,“ENVIRONMENMT”,“MESEXTENSO”,true)
CallProc
Descrição: Esta função tem o mesmo objetivo que a anterior, porém sempre aguardará o término do
processo para que o controle volte à aplicação externa, e tem algumas diferenças conceituais:
A) Não se pode escolher o ambiente no qual o processo será executado. Os
processos executados pela CallProc serão sempre executados no ambiente indicado na
criação da instância com a função AP5CreateConnControl;
B) Um processo executado através da função StartJob, começará de um
ambiente totalmente novo. Porém, os processos executados pela função CallProc
mantêm o ambiente da última execução. Assim, o valor de variáveis criadas, os arquivos
abertos, etc, são mantidos na próxima execução.
s: cFunc: char * - Nome do processo ou função 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 utilização da API, pode-se criar toda uma aplicação, em Visual Basic por exemplo, que executará funções do sistema
Advanced como o usuário faria através 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”)
If lOk Then
ResultAsString(nAP5,cRes)
Else
CRes = “Não foi possível obter o mês por extenso”
End if
AP5Disconnect(nAP5)
End if
AP5DestroyConnControl(nAP5)
Importante: A notação dos tipos de dados e da sintaxe mencionados na descrição das funções segue o
padrão de linguagens como a linguagem C. Deve-se considerar os exemplos de sintaxe conforme a
linguagem utilizada.
Todas as funções 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 parâmetro para a função chamada. A aplicação externa
também será responsável por liberar a memória do buffer alocado.
O Controle ActiveX
O controle ActiveX tem as mesmas funcionalidades da API. Porém o formato de utilização é diferenciado. O controle
ActiveX é um objeto que deve ser registrado no computador onde será utilizado e durante a execução da aplicação externa,
deverá ser criado, utilizado e destruido ao final. Para maiores detalhes, consulte a documentação da linguagem utilizada ou a
documentação do conceito ActiveX na página da Microsoft (http://www.microsoft.com).
RPC através da Internet
O RPC através da Internet é realizado diretamente com o AP5 Server utilizando o protocolo HTTP. Isto significa que é
possível criar páginas 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 através do protocolo HTTP. Neste
último caso é possível também utilizar uma conexão direta TCP/IP (via socket).
Para realizar o RPC utilizando o protocolo HTTP diretamente com o AP5 Server, não é necessário a utilização de um servidor
Web de terceiros, pois o AP5 Server também é 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
requisições 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 própria
Intranet num ambiente de rede local, ou publicar o endereço IP da máquina com o AP5 Server na Internet e executar funções
através de RPC ou simplesmente criar o seu próprio Web Site com páginas HTML estáticas e/ou dinâmicas.
Serviços de FTP
O protocolo FTP (File Transfer Protocol) permite a transferência de arquivos entre um servidor e uma aplicação
client de FTP (com um Web Browser como o Internet Explorer, por exemplo). Utilizando o AP5 Server como um servidor
FTP, os usuários poderão remotamente baixar arquivos disponibilizados em um diretório configurável no servidor. Pode-se
também habilitar um recurso de auto-atualização para o AP5 Remote, que irá automaticamente baixar arquivos compactados
para se auto atualizar quando necessário.
Para habilitar o serviço de FTP no AP5 Server, o seguinte

grupo deve ser criado no arquivo de configurações
(AP5SRV.INI):
[FTP]
Enable=1
Path=C:\AP5\FTP
Port=21
Onde as chaves são:

- Enable indica se habilita ou desabilita este serviço;
- Path indica o diretório onde o AP5 Server localizará os arquivos para disponibilizar no FTP;
- Port é a porta usada para conexão das aplicação client.
Figura 1 - Internet Explorer 5 acessando a área de
FTP do AP5 Server
O recurso de auto-atualização encontrado no AP5 Remote funciona através da detecção de diferenças na versão das DLL´s
locais (ou seja, que se encontram juntamente com o executável do AP5 Remote). Quando isto ocorre, o usuário é questionado
sobre a execução da auto-atualização. Se tudo estiver corretamente configurado no arquivo de configuração do AP5 Remote
(AP5RMT.INI – para maiores detalhes, consulte a documentação do AP5 Remote), ao escolher que deseja tentar uma auto-
atualização, o AP5 Remote irá abrir uma conexão FTP com o Server configurado e baixar os arquivos compactados (com a
extensão .CAB) contendo as DLL´s e executáveis mais atualizados. Os arquivos serão então descompactados localmente para
a atualização.
Serviços de HTTP
O protocolo HTTP (HyperText Transmission Protocol) é o protocolo utilizado na comunicação entre um servidor e
um Web Browser. É o protocolo utilizado para o envio e recebimento de páginas formatadas em padrões SGML
(HTML,XML, etc). Este protocolo se baseia principalmente em dois comandos: GET e POST. O comando GET é utilizado
para obter alguma informação do servidor HTTP e o POST para “postar” informações para o servidor. Mais adiante, será
mais fácil compreender onde tais comandos são utilizados no AP5 Server.
Utilizando o AP5 Server como um servidor HTTP, o

mesmo poderá ser acessado através de um Web
Browser como o Internet Explorer por exemplo, que
receberá as páginas HTML enviadas de um diretório
configurado no servidor. Adicionalmente ao envio e
recebimento de páginas estáticas formatadas, pode-
se utilizar a linguagem Advpl do AP5 para processar
páginas mistas, que contém código Advpl e
comandos HTML de formatação. Tais páginas serão
processadas no AP5 Server, e então enviadar para o
Web Browser, que irá formatá-las de acordo com os
comandos HTML contidos. Também é possível
executar diretamente funções compiladas no
repositório do AP5, através de um request HTTP
(por exemplo, através de um POST em um
formulário em HTML, ou de um link, ou mesmo
Figura 2 - Internet Explorer 5 acessando o AP5 Server como diretamente na linha de URL do Web Browser. O
um servidor HTTP mesmo vale para qualquer outra aplicação que seja
capaz de efetuar comandos GET ou POST utilizando o protocolo HTTP).
Para habilitar o serviço de HTTP no AP5 Server, os seguintes grupos devem ser criados no arquivo de configurações
(AP5SRV.INI):
HTTP]
Enable=1
Path=C:\AP5\HTTP
RPCServer=SERVERKEY
RPCEnv=ENVIRONMENT
RpcTimeOut=40
Port=1234
GetProc=<função>
PostProc=<função>
[SERVERKEY]
TYPE=TCPIP
Server=172.16.1.1
Port=5024
Onde as chaves são:

 Grupo HTTP
- Enable indica se habilita/desabilita o serviço;
- Path indica o diretório 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 configurações do AP5 Server onde serão executadas as chamadas
de funções Advpl através de RPC (por requests HTTP);
- RPCEnv indica o nome do grupo que contém as configurações de ambiente para a execução das funções requisitadas
em RPC;
- RPCTimeOut indica o tempo em segundos que a thread de execução RPC permanecerá no ar (e conseqüentemente
com todo o ambiente preparado para ser utilizado em uma próxima execução de RPC via HTTP);
Port é a porta utilizada para a conexão dos Web Browsers;
- GetProc e PostProc são parâmetros 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
função informada é executada e receberá um parâmetro com o nome da página, arquivo ou função, originalmente
requisitado.
 Grupo <SERVIDOR> (no exemplo, SERVERKEY)
- TYPE indica o tipo de conexão 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 endereço IP do servidor encarregado da execução das rotinas em Advpl (RPC). Note que
estes servidor não precisa necessariamente ser um servidor diferente do utilizado para responder aos requests HTTP
(aquele que trabalha como Web Server);
- Port é a porta utilizada para conexão ao Servidor RPC.
Quando uma URL é requisitada através de um Web Browser (seja através de um comando POST, um link ou diretamente
através do campo de URL do Browser), essa requisição é recebida pelo AP5 Server que a tratará do seguinte modo:
Extensão Descrição O que acontece Exemplo

do arquivo
Nenhuma Um endereço http Ao chamar um endereço URL sem http://servidor/
único, sem um nome informar um nome de arquivo, o AP5
de arquivo definido. Server irá procurar o arquivo chamado
DEFAULT.HTM para enviar ao Web
Browser que efetuou o request.
.HTM;.HTM Páginas HTML, A página HTML, ou qualquer que seja o http://servidor/
L ou outra arquivos texto, arquivo, será simplesmente enviado ao cadastro.htm
extensão arquivos de imagem, Web Browser, sendo que este é o ou
qualquer. som, vídeo, etc. responsável pela sua http://servidor/
tradução/interpretação. imagem.gif
.APL É uma chamada Quando o AP5 Server receber um request http://servidor/
direta a uma função deste tipo, a função chamada (no exemplo acerto.apl
do repositório do func.apl, a função chamada é func, sem a ou
AP5. extensão) será executada no AP5 Server http://servidor/
configurado na chave RPCSERVER no runprog.apl
ambiente definido pela chave RPCENV.
O que deverá ser retornado pela função é
uma string, que será enviada para o Web
Browser.
.APH É uma chamada para Uma página Advpl ASP é uma página http://servidor/
uma página ativa HTML contendo código interpretável no activepage.apl
(uma página em servidor. Tais páginas são criadas ou
ADVPL ASP). utilizando qualquer editor de texto ou http://servidor/
editor HTML, e devem ter SEMPRE a cadastro.apl
extensão .APH. Devem ser compiladas
através do AP5 IDE. Durante a
compilação, o AP5 Server transforma
essa página em uma função interna que
será executada da mesma maneira que
aquelas chamadas .APL explicadas
anteriormente.
Como também são funções, as páginas
em Advpl ASP devem ser chamadas do
Web Browser com a extensão .APL
exatamente como explicado
anteriormente.
Criando funções APL

A princípio, todas as funções contidas no repositório podem ser executadas diretamente através de uma requisição HTTP ao
AP5 Server. Porém, alguns detalhes devem ser considerados:
 Uma função executada no momento do recebimento de uma requisição HTTP é executada como um JOB, ou seja,
não contem interface. Por isso, tais funções não podem conter comandos de interface, como criação de janelas ou
exibição de helps e mensagens de alerta;
 A única interface possível é a utilizada no client HTTP. Por isso, tais funções devem SEMPRE retornar uma string
de caracteres. Após o processamento da função, essa string de retorno será enviada diretamente ao client HTTP e
este será o responsável por sua interpretação. Por exemplo, utilizando um Web Browser como client pode-se
retornar a string de comandos HTML diretamente. O HTML então será propriamente exibido no Web Browser;
 Qualquer retorno diferente de uma string de caracteres gerará um erro que será enviado à aplicação client HTTP (o
erro gerado é “Invalid Proc Return”);
 O AP5 Server passa alguns parâmetros para as funções chamadas. Isso significa que ao criar funções para serem
utilizadas em resposta às requisições HTTP, deve-se criar o cabeçalho da função com estes parâmetros. Não é
obrigatório utilizar os mesmos nomes de parâmetros sugeridos abaixo quando criar diretamente estas funções.
Porém, como são esses os nomes utilizados no ADVPL ASP explicado mas a frente, é aconselhável utilizá-los por
motivo de padronização:
- __aCookies: Este parâmetro recebe um array bidimensional com os Cookies criados na aplicação client HTTP
(por exemplo, no Internet Explorer 5). Pode-se utilizá-lo para checar validações mantidas nas máquinas client
por exemplo. Para maiores detalhes, consulte a documentação do HTML ou do Web Browser utilizado.
- __aPostParms: Este parâmetro recebe um array bidimensional com os campos contidos em um formulário
HTML recebido através de um comando POST. Cada item deste array contém um array com o nome do campo
e o valor informado. Por exemplo, para um formulário com dois campos para digitação (um chamado nome e o
outro chamado endereco), que enviam os dados para a função cadastro.apl através de um POST, a função
receberá o array __aPostParms da seguinte forma:
{
{“nome”, “NOME DIGITADO NA PAGINA HTML”},
{“endereco”, “ENDERECO DIGITADO NA PAGINA HTML”}
}
A função pode tratar os dados recebidos neste array para realizar um processamento específico com tais
informações. Para campos onde não é possível a entrada de dados e sim a escolha de uma informação pré-
definida (como por exemplo um checkbox), o item somente existirá no array caso o campo tenha sido
selecionado no formulário HTML (por exemplo, se o checkbox for marcado).
- __nProcID: Contém o Handle da Thread de execução daquela função. A utilização deste parâmetro será
explicada juntamente com o tópico ADVPL ASP posteriormente;
- __aProcParms: Este parâmetro recebe um array bidimensional com os parâmetros enviados na linha de URL
do Web Browser. Por exemplo, na execução de uma função via linha de URL do Web Browser como:
http://servidor/vende.apl?cod=000001&nome=PRODUTO DE TESTE&quant=20
a função chamada vende receberá o array __aProcParms da seguinte forma:
{
{“cod”, “000001”},
{“nome”, “PRODUTO DE TESTE”},
{“quant”, “20”}
}
A função pode tratar estes dados recebidos para realizar processamentos específicos. É muito útil também para
criar links de execução diretamente através de um Web Browser.
- __cHTTPPage: Esse parâmetro recebe o nome da página, arquivo ou função originalmente requisitada para o
AP5 Server. É utilizado quando as chaves GETPROC e POSTPROC (explicadas anteriormente) são habilitadas
no arquivo de configurações do AP5 Server. A função configurada irá receber nesse parâmetro o nome original
requisitado e poderá executar algum processamento específico para continuar o processo (retornando a própria
função original) ou desviar para outra página, por exemplo.
Exemplo de função APL
A função a seguir é um bom exemplo para ser executado através de um Web Browser como o Internet Explorer ou o
Netscape Navigator. Ela retorna uma string contendo a página HTML onde está escrita a mensagem “Hello World” e a lista
de parâmetros passados na linha de URL. Para testá-la, crie um arquivo novo no AP5 IDE, cole o código abaixo e salve o
arquivo como WEBDEMO.PRW. Após 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
Código da função:
#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 parâmetro informado na linha de URL.'
Else
For i := 1 To Len(__aProcParms)
cHTML += '<p>Parâmetro: ' + __aProcParms[i,1] + ' - Valor: ' +

__aProcParms[i,2] + '</p>'
Next i
Endif
Return(cHTML)
Para crias as funções que serão utilizadas em chamadas via um Web Browser, ou seja, em qualquer
request HTTP, deve-se seguir o procedimento normal de criação de funções no AP5: utilizando o
AP5 IDE para a edição e para a compilação.
Note que no caso de funções do usuário (User Function) o nome chamado na URL do Browser
também deverá conter o U_ no começo da função, por exemplo:
http://servidor/u_webrelato.apl
E deve-se sempre indicar a extensão .APL para que o AP5 Server identifique que é uma função a ser executada.
O ADVPL ASP
Uma página ASP (Active Server Pages) é uma página HTML contendo código interpretável em uma linguagem
compreensível ao servidor HTTP em uso. Por exemplo, o IIS da Microsoft utiliza o VBScript para criar suas páginas ASP,
do mesmo modo que o AP5 utiliza o ADVPL. Uma página ASP é uma combinação de script HTML e código interpretável.
No ADVPL ASP esse código é padrão xBase, portanto a preocupação maior daqueles que já conhecem e trabalham com o
AP5 e desejam desenvolver páginas ativas para aplicações Web utilizando essa facilidade é conhecer HTML.
Características do ADVPL ASP
Os arquivos ADVPL ASP têm a extensão padrão .APH. São arquivos texto e devem ser adicionados a um projeto no AP5
IDE e compilados da mesma maneira que os programas tradicionais. A diferença é que o AP5 Server identificará que se
trata de um ADVPL ASP e executará uma espécie de tradutor (parser) antes que a compilação seja executada. Este parser irá
transformar todo o arquivo em uma função única, que receberá os mesmos parâmetros das funções APL simples, como
explicado anteriormente, e retornará uma string. O desenvolvedor não precisa se preocupar em retornar HTML algum, pois
o APH também é um arquivo HTML. A função que foi gerada na compilação irá se encarregar de retornar o HTML contido
no arquivo, depois que o código foi processado.
Por se tornar uma função no momento da compilação, não é possível utilizar a cláusula FUNCTION para criar
outras funções dentro de um arquivo APH. Caso exista essa necessidade, tais funções devem ser criadas em um
arquivo PRW tradicional e chamadas de dentro do APH.
Do mesmo modo que as demais funções, o arquivo APH também deve ser executado (através da
URL do Browser, por exemplo) com a extensão .APL.
A extensão APH para o nome dos arquivos é obrigatória. Qualquer outra extensão usada no nome
do arquivo não será reconhecida e o parser não será executado antes da compilação.
Assim como outros ASP´s, a diferenciação entre script HTML e código é efetuada através dos caracteres <% para indicação
de abertura de código e %> para indicação do encerramento de código.
Por exemplo, o HTML abaixo contém um pedaço de código 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 números
Local i, nSoma := 0
For i := 1 To 100
NSoma += i
Next i
%>
</body>
</html>
Quando este arquivo for requisitado ao AP5 Server (através de uma chamada em URL por exemplo) o código entre os
delimitadores será executado, porém o script colocado ao redor do código será mantido exatamente como se encontra.
A grande vantagem de se criar arquivos ADVPL ASP em relação a criar funções APL simples, decorre do fato de que não é
necessário conhecer tão profundamente HTML e que nas funções APL simples o desenvolvedor deve se preocupar em
retornar todo o HTML necessário para a correta exibição no Web Browser. E também, como o ADVPL ASP mistura o script
HTML com o código interpretável, pode-se criar um arquivo APH utilizando o editor desejado (como o Microsoft
FrontPage por exemplo) e inserir o código necessário entre o script. Outro detalhe importante é que pode-se utilizar as
estruturas de fluxo da linguagem ADVPL para repetir comandos do próprio 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 também pode existir diferentes blocos de código interpretável separados pelos delimitadores, dentro de um mesmo
arquivo.
Tão importante quanto mesclar código interpretável com script de formatação HTML, é utilizar os comandos ADVPL para
alterar o script de formatação. Ou seja, colocar o conteúdo de variáveis, campos, etc, diretamente no HTML que será
enviado à aplicação client (ao Browser por exemplo). Isso pode ser realizado através dos delimitadores de avaliação. Os
delimitadores de avaliação são <%= para abertura e %> para encerramento. Diferentemente dos delimitadores de código
interpretável, estes devem sempre estar na mesma linha. Com eles pode-se criar uma linha de script HTML, cujo conteúdo
contém uma expressão que será avaliada em tempo de execução:
<b>Esta linha é HTML, mas a data exibida aqui: <%= Time() %> foi obtida em tempo de
execução.</b>
No exemplo acima, a linha HTML será retornada para o Browser com o resultado da função time (ou seja, a hora atual no
servidor) inserido no texto.
Utilizando todos esses conceitos, pode-se criar toda uma apliação 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 relatório de clientes criado utilizando o ADVPL ASP. Para testá-lo basta copiar o código, salvá-lo como
WEBREL.APH e compilar o arquivo através do AP5 IDE:
<html>
<head>
<% //Função para manutenção do ambiente %>

<%= HTMLProcID(__nProcID) %>
<title>ADVPL ASP DEMO</title>

</head>
<%
#define FIELD_CODDE "FROM_CODE"
#define FIELD_CODATE "TO_CODE"
#define FIELD_LOCDE "FROM_LOCAL"
#define FIELD_LOCATE "TO_LOCAL"
// Criação das variáveis com os parâmetros recebidos através 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>Relatório de Produtos</u></h3>
</td>
</tr>
<tr>
<td>
<p align="left"><b>Data de geração</b>: <%=Day(Date())%> de <%=MesExtenso(Date())%> de <
%=Year(Date())%></td>
</tr>
<tr>
<td>
<hr>
</td>
</tr>
</table>
<div align="center">
<center>
<% If Len(__aProcParms) > 0 %>

<table border="1" cellpadding="0" cellspacing="0" width="508" height="24">
<tr>
<th width="181" height="24" bgcolor="#008080" align="left"><font
color="#FFFFFF"><b>Parâmetro</b></font></th>
<th width="327" height="24" bgcolor="#008080" align="left"><font
color="#FFFFFF"><b>Valor</b></font></th>
</tr>
<%
// "Impressão" dos parâmetros
Local i
For i := 1 To Len(__aProcParms)
%>
<tr>
<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 parâmetro 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>Código</b></font></th>
<th width="50%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Descrição</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
Médio</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 width="12%" bgcolor="#FFFFCC"><%= HTMLAllTrim(SB1->B1_COD) %></td>
<td width="50%" bgcolor="#FFFFCC"><%= HTMLAllTrim(SB1->B1_DESC) %></td>
<td width="7%" bgcolor="#FFFFCC"><%= HTMLAllTrim(SB2->B2_LOCAL) %></td>
<td width="17%" bgcolor="#FFFFCC"><%= SB2->B2_QATU %></td>
<td width="14%" bgcolor="#FFFFCC"><%= "R$" + Str(SB2->B2_CM1,8,2) %></td>
</tr>
<%
dbSkip()
EndDo
%>
</table>
</body>
</html>
Após ter o código compilado, pode-se visualizar o resultado acessando através 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 aperfeiçoar nossos clientes com algumas funções que a
microsiga desenvolveu no Siga PROTHEUS.
Todos os tópicos mencionados poderão servir como base consulta, considerando-se como “ideal” o
ambiente apresentado nas versões, pacths, e build´s .
8. Função
8.1. Função FIELDGET()
Esta função 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 função tem a finalidade de incluir ou seja pegar o conteudo do resultado da função 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 opção
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 funções não checam as ordens do Dicionario da dados da Siga SX3010.DBF.
8.3. GETADVFVAL
Tipo: Processamento
Esta função permite executar uma pesquisa em um arquivo, pela chave especificada
e na ordem especificada, retornando o conteúdo de um ou mais campos.
Sintaxe
GetAdvFVal(cAlias,uCpo,uChave,nOrder,uDef)
Parâmetros
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 não seja encontrada.
Retorna
uRet – Retorna o conteúdo de um campo ou array com o conteúdo de vários 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, após pesquisar no SB1 (Cadastro de Produtos), sugerir a
quantidade vendida a partir de um campo específico:
// Colunas...
nPosCod := aScan(aHeader,{ |x| Upper(AllTrim(x[2])) == C6_PRODUTO })

nPosQtd := aScan(aHeader,{ |x| Upper(AllTrim(x[2])) == C6_QTDVENlm })
// Obtém o código 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 específico com a quantidade padrão

__Return(SB1->B1_QTSUGER)
Para uma melhor compreensão, você pode analisar os programas RDMOD2.PRX e/ou RDMOD3.PRX que
acompanham o SIGA PROTHEUS. Eles estão no diretório 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 padrões definidos pela função SetPrint.
Sintaxe
SetDefault (aArray, cAlias)
Parâmetros
aArray – Array aReturn, preenchido pelo SetPrint
[1] Reservado para Formulário
[2] Reservado para Nº de Vias
[3] Destinatário
[4] Formato => 1-Comprimido 2-Normal
[5] Mídia => 1-Disco 2-Impressora
[6] Porta ou Arquivo 1-LPT1... 4-COM1...
[7] Expressão do Filtro
[8] Ordem a ser selecionada
[9]..[10]..[n] Campos a Processar (se houver)
cAlias – Alias do arquivo a ser impresso.
Retorna
Nil
Comentários
Esta função habilita os padrões de relatório alterados pela função SetPrint.
Exemplo
// Define Variáveis
cString:= “SB1”
NomeRel:= MATR290lR
cPerg := MTR290lr
titulo := RELAÇÃO PARA ANÁLISE DOS ESTOQUESlL
cDesc1 := “Este relatório demonstra a situação de cada item em “
cDesc2 := “relação 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 função 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)
Parâmetros
aArray – Array multidimensional contendo os campos a criar {Nome, Tipo,Tamanho, Decimal}

lDbf – Determina se o arquivo de trabalho deve ser criado ( .T.) ou não (.F. )
Retorna
ExpC1 – Nome do Arquivo gerado pela função.
Comentários
Esta função retorna o nome de um arquivo de trabalho que ainda não exista.
Caso lDbf = .T., a função criará um arquivo DBF com este nome e a estrutura definida em aArray.
Caso lDbf = .F., a função não criará arquivo de nenhum tipo, apenas fornecerá um nome válido.
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 régua padrão de processamento.
Sintaxe
ProcRegua(nRegs,nLinha,nColuna)
Parâmetros
nRegs – Número de registros que serão processados.
nLinha – Número da Linha da régua
nColuna – Número da Coluna da régua
Retorna
Nil
Exemplo
ProcRegua(1000)
For i:= 1 to 1000
IncProc()
Next
Return
No RdMake Windows a ProcRegua só utiliza o primeiro parâmetro. No RdMake
DOS são utilizados os três parâmetros.
= Ver também IncProc()

8.7 - INCPROC
Tipo: Tela DOS/Windows

Incrementa régua padrão de processamento.
Sintaxe
IncProc()
Parâmetros
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> cTítulo
Parâmetros
nLinha1 – Número da linha superior
nColuna1 – Número da coluna superior
nLinha2 – Número da linha inferior
nColuna2 – Número da coluna inferior
cTítulo – Titulo apresentado na linha superior (opcional)
Comentários
A cláusula TITLE é opcional. Se for omitida, o box não terá título.
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 padrão do sistema, conforme os parâmetros.
Sintaxe
mBrowse(nLinha1, nColuna1, nLinha2, nColuna2, cAlias, aFixe, cCpo, nPar, cCor, n Opc)
Parâmetros
nLinha1 – Número da linha inicial
nColuna1 – Número da coluna inicial
nLinha2 – Número da linha final
nColuna2 – Número 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 – Parâmetro obsoleto
cCor – Função que retorna um valor lógico, muda a cor da linha
nOpc – Define qual opção 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 padrão do sistema, permitindo marcar e desmacar linhas.
Sintaxe
MarkBrowse(cAlias,cCampo,cCpo,aCampos,lMarc,cMarca,cCtrlM,lBotoes,cTopFun,cBotFun,aCoord)
Parâmetros
cAlias – Álias do arquivo
cCampo – Campo que estabelece relação 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 não
cMarca – Marca obtida com a função Getmark
cCtrlM – Função para ser executada no Alt_M
lBotoes – Parâmetro obsoleto
cTopFun – Função filtro para estabelecer o primeiro registro
cTopFun – Função 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 Avancado

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Apostila ADVPL Avancado

Enviado por

Direitos autorais:

Formatos disponíveis

Programação em ADVPL / SQL / ASP com AP5

Programação ADVPL /SQL / ASP

Com Protheus 5.08

4. AP5 WEB - CONECTIVIDADE

5.1 A API de comunicação com o AP5

6. RPC ATRAVÉS DA INTERNET

6.1 O AP5 Server como um servidor Web

6.1.1 Serviços de FTP

6.2 Criando funções APL

6.2.1 Exemplo de função APL

6.3 O ADVPL ASP

6.3.1 Características do ADVPL ASP

1. Introdução ao ambiente Relacional

1.2. Conceitos Básicos 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

Toda e qualquer operação de inclusão, alteração ou exclusão de registro é armazenada

1.3.1.2. Segurança e Backup

1.3.1.3. Construindo Query’s evitando problemas com estouro da Área de LOG

Conhecendo melhor o processo de gravação do banco de dados, percebemos que quanto

1.3.2. Área temporária do Banco de Dados

1.4. Normalização de Base de Dados

Ex.: Entidade = Pedido

Ex.: Entidade = Pedido

Entidade = Itens do Pedido

Ex.: Entidade = Pedido

1.5. MER (Modelo Entidade Relacionamento)

1.6. Diferenças cruciais entre ambientes DBF e SQL

Quando trabalhamos em um ambiente posicional, vários regras de programação e definição como

2.1. Informações gerais

 MS-SQL Server 6.5 e 7.0 ( MSSQL / MSSQL7 )

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

2.2. Controle de tipo de dados ( Tabela TOP_FIELD )

Os tipos de dados que são tratados atualmente são o seguintes:

 Campos numéricos - são armazenados em variáveis do tipo FLOAT

Os campo caracter não recebem nenhum tratamento.

A tabela TOP_FIELD contem a descrição de todos os campos NAO-CARACTER, para que o

Ex.: Tabela SA1010

FIELD_TABLE FIELD_NAME FIELD_TYPE FIELD_PREC FIELD_DEC

2.4. Sistema de controle de Registros

2.4.2. Função da coluna R_E_C_N_O_

2.4.2.1. Limite de registros

O limite de registros em uma tabela é de 2,147,483,648 , este número normalmente deve

2.4.2.2. Renumeração da coluna RECNO

2.4.3. Controle dos registros deletados (Coluna D_E_L_E_T_)

Toda exclusão de registro feita no Banco de Dados ou em qualquer plataforma do SigaPROTHEUS

2.5. Constraints do Banco de dados que são criados automaticamente

2.5.1. Criação da Estrutura de tabelas

A estrutura de cada tabela do SigaAdvacend é criada automaticamente, tendo em vista a não

CREATE TABLE [dbo].[SA1990] (

CREATE UNIQUE CLUSTERED INDEX [SA1990_RECNO] ON [dbo].[SA1990]([R_E_C_N_O_]) ON

ALTER TABLE [dbo].[SA1990] WITH NOCHECK ADD

CREATE INDEX [SA19901] ON [dbo].[SA1990]([A1_FILIAL], [A1_COD], [A1_LOJA], [R_E_C_N_O_]) ON

CREATE INDEX [SA19902] ON [dbo].[SA1990]([A1_FILIAL], [A1_NOME], [A1_LOJA], [R_E_C_N_O_]) ON

CREATE INDEX [SA19903] ON [dbo].[SA1990]([A1_FILIAL], [A1_CGC], [R_E_C_N_O_]) ON [PRIMARY]

CREATE INDEX [SA19904] ON [dbo].[SA1990]([A1_FILIAL], [A1_TEL], [R_E_C_N_O_]) ON [PRIMARY]

2.5.4. Problemas com conteúdo Nulo

Considere a filial do arquivo de pedido de forma compartilhada.(Filiial=Branco)

2.6. Manutenção do Banco de dados

2.7. DBFNTX x TopConnect

2.7.2. Funções em chaves de índices

As únicas funções suportadas são STR e DTOS.