Advanced Protheus - AP5

AP5 Web – Conectividade e AdvPL ASP

CopyRight © 2000 Microsiga Software S.A.

Advanced Protheus - AP5 Web – Conectividade e Advpl ASP CopyRight © 2000

Microsiga Software S.A.
Sumário
Advanced Protheus - AP5...............................................................................................................................................1
AP5 WEB – CONECTIVIDADE E ADVPL ASP......................................................................................................1

COPYRIGHT © 2000 MICROSIGA SOFTWARE S.A...........................................................................................1

SUMÁRIO.....................................................................................................................................................................2

AP5 WEB - CONECTIVIDADE.................................................................................................................................3

RPC ENTRE O AP5 E OUTRAS APLICAÇÕES..........................................................................................................................4
A API de comunicação com o AP5......................................................................................................................................4
O Controle ActiveX.............................................................................................................................................................9
RPC ATRAVÉS DA INTERNET...............................................................................................................................................10
O AP5 Server como um servidor Web.....................................................................................................................................10
Serviços de FTP.................................................................................................................................................................10
Serviços de HTTP..............................................................................................................................................................11
Criando funções APL...............................................................................................................................................................13
Exemplo de função APL....................................................................................................................................................14
O ADVPL ASP........................................................................................................................................................................16
Características do ADVPL ASP.........................................................................................................................................16

Advanced Protheus - AP5 Web – Conectividade e Advpl ASP CopyRight © 2000

Microsiga Software S.A.
 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.

Advanced Protheus - AP5 – Conectividade e Advpl ASP 3

CopyRight © 2000 Release A – Microsiga Software S.A.
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.

Advanced Protheus - AP5 – Conectividade e Advpl ASP 4

CopyRight © 2000 Release A – Microsiga Software S.A.
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âmetros: cServer: char * - Nome ou endereço IP do servidor para a conexão;

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âmetros: nObjectID: int - Handle da instância criada com a função anterior.

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âmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função. É atravé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âmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função.
Retorno: Sem retorno.
Sintaxe: AP5Disconnect(nAP5)

Advanced Protheus - AP5 – Conectividade e Advpl ASP 5

CopyRight © 2000 Release A – Microsiga Software S.A.
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âmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função. É atravé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âmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função.
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)

Advanced Protheus - AP5 – Conectividade e Advpl ASP 6

CopyRight © 2000 Release A – Microsiga Software S.A.
AP5BuildNumber
Descrição: Função utilizada para obter o número do build de compilação da API de conexão ao AP5.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;
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.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;
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.

Advanced Protheus - AP5 – Conectividade e Advpl ASP 7

CopyRight © 2000 Release A – Microsiga Software S.A.
Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;
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.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;
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.

Advanced Protheus - AP5 – Conectividade e Advpl ASP 8

CopyRight © 2000 Release A – Microsiga Software S.A.
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).

Advanced Protheus - AP5 – Conectividade e Advpl ASP 9

CopyRight © 2000 Release A – Microsiga Software S.A.
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.

Advanced Protheus - AP5 – Conectividade e Advpl ASP

10 CopyRight © 2000 Release A – Microsiga Software S.A.
 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
Figura 2 - Internet Explorer 5 acessando o AP5 Server como um HTML, ou de um link, ou mesmo
servidor HTTP diretamente na linha de URL do Web
Browser. O 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] Onde as chaves são:

Enable=1 • Grupo HTTP
Path=C:\AP5\HTTP - Enable indica se habilita/desabilita o serviço;
RPCServer=SERVERKEY - Path indica o diretório onde o AP5 Server localizará os arquivos
RPCEnv=ENVIRONMENT HTML e demais arquivos que forem requeridos por um Web Browser;
RpcTimeOut=40 - RPCServer indica o nome do grupo que contem as configurações do
Port=1234 AP5 Server onde serão executadas as chamadas de funções Advpl
GetProc=<função> através de RPC (por requests HTTP);
PostProc=<função> - RPCEnv indica o nome do grupo que contém as configurações de
ambiente para a execução das funções requisitadas em RPC;
[SERVERKEY] - RPCTimeOut indica o tempo em segundos que a thread de execução
TYPE=TCPIP RPC permanecerá no ar (e conseqüentemente com todo o ambiente
Server=172.16.1.1 preparado para ser utilizado em uma próxima execução de RPC via
Port=5024 HTTP);
- Port é a porta utilizada para a conexão dos Web Browsers;

Advanced Protheus - AP5 – Conectividade e Advpl ASP

11 CopyRight © 2000 Release A – Microsiga Software S.A.
 - 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 do Descrição O que acontece Exemplo

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;.HTML Páginas HTML, A página HTML, ou qualquer que seja o http://servidor/cadastro.htm
ou outra arquivos texto, arquivo, será simplesmente enviado ao ou
extensão arquivos de imagem, Web Browser, sendo que este é o http://servidor/imagem.gif
qualquer. som, vídeo, etc. responsável pela sua
tradução/interpretação.
.APL É uma chamada Quando o AP5 Server receber um request http://servidor/acerto.apl
direta a uma função deste tipo, a função chamada (no exemplo ou
do repositório do func.apl, a função chamada é func, sem a http://servidor/runprog.apl
AP5. extensão) será executada no AP5 Server
configurado na chave RPCSERVER no
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/activepage.apl
uma página ativa HTML contendo código interpretável no ou
(uma página em servidor. Tais páginas são criadas http://servidor/cadastro.apl
ADVPL ASP). utilizando qualquer editor de texto ou
editor HTML, e devem ter SEMPRE a
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.

Advanced Protheus - AP5 – Conectividade e Advpl ASP

12 CopyRight © 2000 Release A – Microsiga Software S.A.
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”}

Advanced Protheus - AP5 – Conectividade e Advpl ASP

13 CopyRight © 2000 Release A – Microsiga Software S.A.
 }
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.
Advanced Protheus - AP5 – Conectividade e Advpl ASP
14 CopyRight © 2000 Release A – Microsiga Software S.A.
Advanced Protheus - AP5 – Conectividade e Advpl ASP
15 CopyRight © 2000 Release A – Microsiga Software S.A.
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.

Advanced Protheus - AP5 – Conectividade e Advpl ASP

16 CopyRight © 2000 Release A – Microsiga Software S.A.
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]
Advanced Protheus - AP5 – Conectividade e Advpl ASP
17 CopyRight © 2000 Release A – Microsiga Software S.A.
 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

Advanced Protheus - AP5 – Conectividade e Advpl ASP

18 CopyRight © 2000 Release A – Microsiga Software S.A.
 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">&nbsp;</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>

Advanced Protheus - AP5 – Conectividade e Advpl ASP

19 CopyRight © 2000 Release A – Microsiga Software S.A.
</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

Advanced Protheus - AP5 – Conectividade e Advpl ASP

20 CopyRight © 2000 Release A – Microsiga Software S.A.