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.
Sumrio

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

RPC ENTRE O AP5 E OUTRAS APLICAES....................................................................................................................4

A API de comunicao com o AP5.......................................................................................................................................4

O Controle ActiveX.............................................................................................................................................................. 9

RPC ATRAVS DA INTERNET.........................................................................................................................................10

O AP5 Server como um servidor Web......................................................................................................................................10

Servios de FTP................................................................................................................................................................. 10
Servios de HTTP.............................................................................................................................................................. 11

Criando funes APL............................................................................................................................................................... 13

Exemplo de funo APL.....................................................................................................................................................14

O ADVPL ASP......................................................................................................................................................................... 15

Caractersticas do ADVPL ASP..........................................................................................................................................15

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
aplicaes, gerenciamento das conexes e compilao de programas. E uma de suas principais caractersticas a alta
conectividade. Ou seja, o AP5 pode ser integrado a diferentes solues ou sistemas, atravs da utilizao de uma API
de acesso (contida em uma DLL) ou um controle ActiveX, ou mesmo diretamente atravs da Web (via protocolo
HTTP ou FTP). Isso permite outras aplicaes a terem acesso a execuo de funes (jobs) no AP5, utilizando o
conceito de RPC.
RPC (Remote Procedure Call) significa Chamada Remota de Procedimentos, ou seja, atravs de uma aplicao
externa (ou atravs da Internet) possvel executar no AP5 rotinas criadas em ADVPL. Tais rotinas podero realizar
todo o tipo de tarefa desejada, como por exemplo cadastrar um pedido, um cliente, ou emitir um relatrio em
formato HTML, retornando informaes aplicao externa.

A utilizao da API de acesso e do controle ActiveX mais indicada para aplicaes desenvolvidas em outras
linguagens e que necessitem interagir com o AP5. J com o acesso via Internet, possvel criar toda uma aplicao
Web que alie o poder de processamento do AP5 com a facilidade de formatao de interface do HTML.

Advanced Protheus - AP5 Conectividade e Advpl ASP 3

CopyRight 2000 Release A Microsiga Software S.A.
RPC Entre o AP5 e Outras Aplicaes
So duas as opes para realizar RPC entre uma aplicao externa e o AP5:
Uma API de acesso, utilizando a DLL (Dinamic Link Library) chamada AP5DCONN.DLL;
Um controle ActiveX , utilizado atravs do arquivo AP5CONNXCONTROL.OCX.

Ambas opes tm as mesmas funcionalidades:

Conexo a um ou mais servidores AP5;
Acesso a algumas funes gerenciais, como obteno de lista de usurios conectados, envio de mensagens,
e gerenciamento das conexes;
Execuo de jobs e procs. Os jobs podem ser executados no AP5 sem que necessariamente a aplicao
externa aguarde pelo retorno. Podem assim permanecer executando no AP5 Server enquanto a aplicao
externa realiza outras tarefas, ou mesmo executa outros jobs. Os procs entretanto, sempre faro com que a
aplicao externa aguarde o retorno do AP5;
Os jobs ou procs so funes contidas no repositrio do AP5 (incluindo as funes criadas por usurios
User Function). A aplicao externa pode, sempre atravs da DLL ou da OCX, enviar parmetros e receber
o retorno destas funes, segundo os tipos de dados vlidos: Caracter, numrico, lgico, data e array;
A conexo ao AP5 sempre efetuada atravs do protocolo TCP/IP. O acesso ao AP5 Server somente ser
efetuado se a correta senha e usurio forem informados. A checagem dessa senha efetuada pelo
Advanced, e deve ser mantida atravs do SIGACFG. O usurio informado deve ser o Administrador do
sistema ou pertencer ao grupo Administradores;

Geralmente a utilizao de uma dessas opes ser indicada para aplicaes que necessitem executar processos
dentro do AP5, como por exemplo, colocar um pedido de venda diretamente na base de dados do sistema,

Importante: Para utilizar a API ou o controle ActiveX, necessrio a DLL de comunicao do AP5
chamada AP5CONN.DLL. Por isso, sempre que for necessrio utilizar uma dessas opes, a DLL de
comunicao deve estar em um path localizvel pelo Windows e deve estar atualizada em relao ao
AP5 Server em que a aplicao externa tentar se conectar.

A API de comunicao com o AP5

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

1. Criao de uma instncia de comunicao;

2. Conexo ao AP5 Server;
3. Utilizao efetiva: Execuo de rotinas, obteno do retorno, etc;
4. Desconexo;
5. Destruio da instncia de comunicao.

Advanced Protheus - AP5 Conectividade e Advpl ASP 4

CopyRight 2000 Release A Microsiga Software S.A.
Para tal, existem as seguintes funes disponibilizadas na DLL de comunicao:

AP5CreateConnControl
Descrio: Criao de uma instncia de comunicao com o AP5 Server. Pode-se criar diferentes instncias de
comunicao, acessando um ou mais servidores do AP5.

Parmetros: cServer: char * - Nome ou endereo IP do servidor para a conexo;

nPort: int - Porta do socket TCP/IP utilizada para a conexo;
cEnvironment: char * - Ambiente utilizado para a execuo de processos;
cUser: char * - Usurio do sistema para validao da conexo. O usurio informado deve pertencer ao
grupo Administradores do sistema;
cPassWord: char * - Senha do usurio informado, para validao da conexo.

Retorno: int - Retorna o Handle da instncia criada. Este Handle retornado dever ser informado em todas as
demais funes de comunicao, para identificao da instncia que ser utilizada.

Sintaxe: nAP5 = AP5CreateConnControl(APSERVER, 1024, ENVIRONMENT, Administrador, )

AP5DestroyConnControl
Descrio: Destruio de uma instncia de comunicao com o AP5 Server. Aps a utilizao da API, e antes de
encerrar a execuo da aplicao externa, necessrio destruir o Handle criado com a funo anterior
para a liberao de memria.

Parmetros: nObjectID: int - Handle da instncia criada com a funo anterior.

Retorno: bool - Retorna verdadeiro ou falso, indicando a execuo com sucesso da funo.
Sintaxe: lOk = AP5DestroyConnControl(nAP5)

AP5Connect
Descrio: Conexo a um AP5 Server. Esta funo no deve ser confundida com a funo
AP5CreateConnControl. Esta funo ir realizar a conexo com o AP5 Server indicado durante a
criao da instncia informada como parmetro.

Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. atravs do
Handle que definido em qual servidor, porta e ambiente os processos sero executados.

Retorno: bool - Retorna verdadeiro ou falso, indicando se a conexo foi efetuada com sucesso.
Sintaxe: lOk = AP5Connect(nAP5)

AP5Disconnect
Descrio: Desconexo de um AP5 Server. Esta funo no deve ser confundida com a funo
AP5DestroyConnControl. Esta funo ir encerrar a conexo ativa com um AP5 Server, da instncia
informada como parmetro.

Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo.
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
Descrio: Estas funes so utilizadas para a execuo de processos em um servidor AP5. Podem ser utilizadas
somente aps uma conexo ser ativada. Um processo executado em um servidor AP5 pode necessitar
de parmetros, que devero ser enviados ao servidor antes da execuo do processo atravs da
utilizao destas funes. Os tipos de dados que podem ser enviados so: Numrico (int), Caracter
(char *), Lgico (bool), Data (enviado como caracter char * - ou como numrico - int) e Array
(variant).

Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. atravs do
Handle que definido para qual servidor o parmetro ser enviado;
xParametro: indefinido - O tipo de dado do parmetro depender da funo utilizada, segundo os
tipos de dados permitidos explicados acima.

Retorno: bool - Retorna verdadeiro ou falso, indicando se o parmetro pde ser enviado ao AP5 Server com
sucesso.

Sintaxe: lOk = AddNumericParam(nAP5,5)

ou
lOk = AddStringParam(nAP5,TEXTO)
ou
lOk = AddLogicalParam(nAP5,true)

ResultAsNumeric,
ResultAsString,
ResultAsLogical,
ResultAsDate,
ResultAsDateString,
ResultAsArray
Descrio: Estas funes so utilizadas para obter o retorno do AP5 Server aps a execuo de um processo.
Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo.
Apenas para as funes ResultAsString e ResultAsDateString:
cBuffer: char * - Buffer de caracteres alocado para receber o retorno em formato caracter;
nSize: int - Tamanho do buffer passado no parmetro anterior.

Retorno: O tipo de dado do retorno depender da funo utilizada, segundo os tipos de dados definidos
anteriormente. Para as funes ResultAsString e ResultAsDateString o retorno ser o tamanho do
buffer preenchido.

Sintaxe: nRet = ResultAsNumeric(nAP5)

ou
lRet = ResultAsLogical(nAP5)
ou
ResultAsString(nAP5,cBuffer,nSize)

Advanced Protheus - AP5 Conectividade e Advpl ASP 6

CopyRight 2000 Release A Microsiga Software S.A.
AP5BuildNumber
Descrio: Funo utilizada para obter o nmero do build de compilao da API de conexo ao AP5.

Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo;
cBuild: char * - Buffer de caracteres para receber o nmero do build;
nSize: int - Tamanho do buffer passado no segundo parmetro.

Retorno: int - Retorna o tamanho do buffer contendo o nmero do build.

Sintaxe: AP5BuildNumber(nAP5,cBuffer,nSize)

PrepareEnv
Descrio: Funo utilizada para preparar o ambiente do sistema, ou seja, abrir arquivos, criar variveis, e tornar
o ambiente de execuo da aplicao externa em relao ao AP5 Server, o mais parecido possvel
com o que realizado pelos mdulos do sistema.

Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo;
cEnv: char * - Ambiente que ser utilizado para a abertura dos arquivos;
cEmp: char * - Cdigo da empresa do sistema (dois dgitos) que dever ser aberta;
cFil: char * - Cdigo da filial que ser utilizada (dois dgitos);
aTables: variant Este parmetro deve ser um array variant (para detalhes, consulte a documentao
da linguagem utilizada) contendo as siglas das tables que devero ser abertas (por exemplo SB1).

Retorno: bool - Retorna verdadeiro ou falso, indicando o sucesso da execuo da funo.

Sintaxe: PrepareEnv(nAP5,ENVIRONMENMT,99,01,aTables)

StartJob
Descrio: Esta funo permite a execuo de um processo (job) em um AP5 Server. O processo executado pode
ser qualquer um dos existentes no repositrio definido pelo ambiente informado, incluindo as funes
criadas pelo usurio (User Function). Pode tambm receber parmetros, bem como retornar um valor
para a aplicao externa, sempre utilizando-se das funes descritas anteriormente. A execuo de um
processo resume-se em:
A)
1. Enviar os parmetros (se existirem);
2. Executar o processo e aguardar sua finalizao;
3. Obter o resultado (se existir).
B)
1. Enviar os parmetros (se existirem);
2. Executar o processo sem aguardar sua finalizao;

Os processos so executados em threads de execuo separadas. Isso permite aplicao externa que
esteja utilizando a API, optar por executar o processo e continuar trabalhando enquanto o mesmo est
em execuo. Porm, somente poder obter um retorno quando esperar at que o processo termine de
ser executado.

Obs.: Como estes processos so executados sem que uma instncia do AP5 Remote esteja ativa,
devem ser criados sem nenhum comando de interface (criao de janelas, comandos de alerta, help,
etc). Se um comando de interface for utilizado no cdigo ADVPL de um processo, a execuo deste
atravs da API gerar um erro de execuo.

Advanced Protheus - AP5 Conectividade e Advpl ASP 7

CopyRight 2000 Release A Microsiga Software S.A.
Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo;
cEnv: char * - Ambiente que ser utilizado para a execuo do processo;
cFunc: char * - Nome do processo ou funo que ser executado no AP5 Server;
lWait: bool - Verdadeiro ou Falso indicando se a aplicao externa dever ou no aguardar pelo
trmino da execuo do processo.

Retorno: bool - Retorna verdadeiro ou falso, indicando se o processo foi iniciado com sucesso.
Sintaxe: StartJob(nAP5,ENVIRONMENMT,MESEXTENSO,true)

CallProc
Descrio: Esta funo tem o mesmo objetivo que a anterior, porm sempre aguardar o trmino do processo
para que o controle volte aplicao externa, e tem algumas diferenas conceituais:
A) No se pode escolher o ambiente no qual o processo ser executado. Os processos
executados pela CallProc sero sempre executados no ambiente indicado na criao da
instncia com a funo AP5CreateConnControl;
B) Um processo executado atravs da funo StartJob, comear de um ambiente
totalmente novo. Porm, os processos executados pela funo CallProc mantm o ambiente
da ltima execuo. Assim, o valor de variveis criadas, os arquivos abertos, etc, so mantidos
na prxima execuo.

Parmetros: nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo;
cFunc: char * - Nome do processo ou funo que ser executado no AP5 Server.

Retorno: Bool - Retorna verdadeiro ou falso, indicando se o processo foi finalizado com sucesso.
Sintaxe: CallProc(nAP5,CALCEST)

Com a utilizao da API, pode-se criar toda uma aplicao, em Visual Basic por exemplo, que executar funes do
sistema Advanced como o usurio faria atravs do AP5 Remote:

Dim nAP5 As Integer

Dim cRes As String

nAP5 = AP5CreateConnControl(APSERVER, 1024, ENVIRONMENT, Administrador, )

If AP5Connect(nAP5) Then
AddNumericParam(nAP5,5)
lOk = CallProc(nAP5,MESEXTENSO)
If lOk Then
ResultAsString(nAP5,cRes)
Else
CRes = No foi possvel obter o ms por extenso
End if
AP5Disconnect(nAP5)
End if

AP5DestroyConnControl(nAP5)

Importante: A notao dos tipos de dados e da sintaxe mencionados na descrio das funes
segue o padro de linguagens como a linguagem C. Deve-se considerar os exemplos de sintaxe
conforme a linguagem utilizada.
Todas as funes de caracter como ResultAsString ou AP5BuildNumber, trabalham com buffer
de caracteres. Isto significa que o buffer que receber o retorno deve ser alocado na linguagem
utilizada e que o tamanho alocado dever ser passado como parmetro para a funo chamada.
A aplicao externa tambm ser responsvel por liberar a memria do buffer alocado.

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. Porm o formato de utilizao diferenciado. O
controle ActiveX um objeto que deve ser registrado no computador onde ser utilizado e durante a execuo da
aplicao externa, dever ser criado, utilizado e destruido ao final. Para maiores detalhes, consulte a documentao
da linguagem utilizada ou a documentao do conceito ActiveX na pgina da Microsoft (http://www.microsoft.com).

Advanced Protheus - AP5 Conectividade e Advpl ASP 9

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

O AP5 Server como um servidor Web

O AP5 Server pode ser configurado para trabalhar como um servidor Web. Isso significa trabalhar como um servidor
de requisies dos protocolos HTTP e/ou FTP, do mesmo modo que outros servidores conhecidos no mercado (por
exemplo, o IIS Internet Information Server, da Microsoft ou o Apache para Linux). Assim, basta ter o AP5 para
poder criar sua prpria Intranet num ambiente de rede local, ou publicar o endereo IP da mquina com o AP5
Server na Internet e executar funes atravs de RPC ou simplesmente criar o seu prprio Web Site com pginas
HTML estticas e/ou dinmicas.

Servios de FTP

O protocolo FTP (File Transfer Protocol) permite a transferncia de arquivos entre um servidor e uma
aplicao client de FTP (com um Web Browser como o Internet Explorer, por exemplo). Utilizando o AP5 Server
como um servidor FTP, os usurios podero remotamente baixar arquivos disponibilizados em um diretrio
configurvel no servidor. Pode-se tambm habilitar um recurso de auto-atualizao para o AP5 Remote, que ir
automaticamente baixar arquivos compactados para se auto atualizar quando necessrio.

Para habilitar o servio de FTP no AP5 Server, o

seguinte grupo deve ser criado no arquivo de
configuraes (AP5SRV.INI):

[FTP]
Enable=1
Path=C:\AP5\FTP
Port=21

Onde as chaves so:

- Enable indica se habilita ou desabilita este servio;
- Path indica o diretrio onde o AP5 Server localizar
os arquivos para disponibilizar no FTP;
- Port a porta usada para conexo das aplicao
client.

Figura 1 - Internet Explorer 5 acessando a rea de

FTP do AP5 Server

O recurso de auto-atualizao encontrado no AP5 Remote funciona atravs da deteco de diferenas na verso das
DLLs locais (ou seja, que se encontram juntamente com o executvel do AP5 Remote). Quando isto ocorre, o
usurio questionado sobre a execuo da auto-atualizao. Se tudo estiver corretamente configurado no arquivo de
configurao do AP5 Remote (AP5RMT.INI para maiores detalhes, consulte a documentao do AP5 Remote), ao
escolher que deseja tentar uma auto-atualizao, o AP5 Remote ir abrir uma conexo FTP com o Server
configurado e baixar os arquivos compactados (com a extenso .CAB) contendo as DLLs e executveis mais
atualizados. Os arquivos sero ento descompactados localmente para a atualizao.

Advanced Protheus - AP5 Conectividade e Advpl ASP 10

CopyRight 2000 Release A Microsiga Software S.A.
 Servios de HTTP

O protocolo HTTP (HyperText Transmission Protocol) o protocolo utilizado na comunicao entre um

servidor e um Web Browser. o protocolo utilizado para o envio e recebimento de pginas formatadas em padres
SGML (HTML,XML, etc). Este protocolo se baseia principalmente em dois comandos: GET e POST. O comando
GET utilizado para obter alguma informao do servidor HTTP e o POST para postar informaes para o
servidor. Mais adiante, ser mais fcil compreender onde tais comandos so utilizados no AP5 Server.

Utilizando o AP5 Server como um servidor

HTTP, o mesmo poder ser acessado
atravs de um Web Browser como o
Internet Explorer por exemplo, que
receber as pginas HTML enviadas de um
diretrio configurado no servidor.
Adicionalmente ao envio e recebimento de
pginas estticas formatadas, pode-se
utilizar a linguagem Advpl do AP5 para
processar pginas mistas, que contm
cdigo Advpl e comandos HTML de
formatao. Tais pginas sero processadas
no AP5 Server, e ento enviadar para o Web
Browser, que ir format-las de acordo com
os comandos HTML contidos. Tambm
possvel executar diretamente funes
compiladas no repositrio do AP5, atravs
de um request HTTP (por exemplo, atravs
de um POST em um formulrio em HTML,
Figura 2 - Internet Explorer 5 acessando o AP5 Server como um ou de um link, ou mesmo diretamente na
servidor HTTP linha de URL do Web Browser. O mesmo
vale para qualquer outra aplicao que seja
capaz de efetuar comandos GET ou POST utilizando o protocolo HTTP).

Para habilitar o servio de HTTP no AP5 Server, os seguintes grupos devem ser criados no arquivo de configuraes
(AP5SRV.INI):

[HTTP] Onde as chaves so:

Enable=1 Grupo HTTP
Path=C:\AP5\HTTP - Enable indica se habilita/desabilita o servio;
RPCServer=SERVERKEY - Path indica o diretrio 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 configuraes do
Port=1234 AP5 Server onde sero executadas as chamadas de funes Advpl
GetProc=<funo> atravs de RPC (por requests HTTP);
PostProc=<funo> - RPCEnv indica o nome do grupo que contm as configuraes de
ambiente para a execuo das funes requisitadas em RPC;
[SERVERKEY] - RPCTimeOut indica o tempo em segundos que a thread de execuo
TYPE=TCPIP RPC permanecer no ar (e conseqentemente com todo o ambiente
Server=172.16.1.1 preparado para ser utilizado em uma prxima execuo de RPC via
Port=5024 HTTP);
- Port a porta utilizada para a conexo dos Web Browsers;

Advanced Protheus - AP5 Conectividade e Advpl ASP 11

CopyRight 2000 Release A Microsiga Software S.A.
 - GetProc e PostProc so parmetros opcionais que podem ser utilizados para interceptar os comandos GET
e POST que caem no AP5 Server. Quando um comando desses requisitado ao servidor e uma destas
chaves est em uso, a funo informada executada e receber um parmetro com o nome da pgina,
arquivo ou funo, originalmente requisitado.
Grupo <SERVIDOR> (no exemplo, SERVERKEY)
- TYPE indica o tipo de conexo que ser efetuada entre o servidor atual (que o AP5 Server encarregado de
responder os requests HTTP) e o servidor de RPC (que o encarregado de executar as rotinas em Advpl);
- Server indica o nome ou endereo IP do servidor encarregado da execuo das rotinas em Advpl (RPC).
Note que estes servidor no precisa necessariamente ser um servidor diferente do utilizado para responder
aos requests HTTP (aquele que trabalha como Web Server);
- Port a porta utilizada para conexo ao Servidor RPC.

Quando uma URL requisitada atravs de um Web Browser (seja atravs de um comando POST, um link ou
diretamente atravs do campo de URL do Browser), essa requisio recebida pelo AP5 Server que a tratar do
seguinte modo:

Extenso do Descrio O que acontece Exemplo

arquivo
Nenhuma Um endereo http Ao chamar um endereo 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 Pginas HTML, A pgina HTML, ou qualquer que seja o http://servidor/cadastro.htm
ou outra arquivos texto, arquivo, ser simplesmente enviado ao ou
extenso arquivos de imagem, Web Browser, sendo que este o http://servidor/imagem.gif
qualquer. som, vdeo, etc. responsvel pela sua
traduo/interpretao.
.APL uma chamada Quando o AP5 Server receber um request http://servidor/acerto.apl
direta a uma funo deste tipo, a funo chamada (no exemplo ou
do repositrio do func.apl, a funo chamada func, sem a http://servidor/runprog.apl
AP5. extenso) ser executada no AP5 Server
configurado na chave RPCSERVER no
ambiente definido pela chave RPCENV.
O que dever ser retornado pela funo
uma string, que ser enviada para o Web
Browser.
.APH uma chamada para Uma pgina Advpl ASP uma pgina http://servidor/activepage.apl
uma pgina ativa HTML contendo cdigo interpretvel no ou
(uma pgina em servidor. Tais pginas so criadas http://servidor/cadastro.apl
ADVPL ASP). utilizando qualquer editor de texto ou
editor HTML, e devem ter SEMPRE a
extenso .APH. Devem ser compiladas
atravs do AP5 IDE. Durante a
compilao, o AP5 Server transforma essa
pgina em uma funo interna que ser
executada da mesma maneira que aquelas
chamadas .APL explicadas anteriormente.
Como tambm so funes, as pginas
em Advpl ASP devem ser chamadas do
Web Browser com a extenso .APL
exatamente como explicado
anteriormente.

Advanced Protheus - AP5 Conectividade e Advpl ASP 12

CopyRight 2000 Release A Microsiga Software S.A.
Criando funes APL
A princpio, todas as funes contidas no repositrio podem ser executadas diretamente atravs de uma requisio
HTTP ao AP5 Server. Porm, alguns detalhes devem ser considerados:

Uma funo executada no momento do recebimento de uma requisio HTTP executada como um JOB,
ou seja, no contem interface. Por isso, tais funes no podem conter comandos de interface, como criao
de janelas ou exibio de helps e mensagens de alerta;

A nica interface possvel a utilizada no client HTTP. Por isso, tais funes devem SEMPRE retornar uma
string de caracteres. Aps o processamento da funo, essa string de retorno ser enviada diretamente ao
client HTTP e este ser o responsvel por sua interpretao. Por exemplo, utilizando um Web Browser
como client pode-se retornar a string de comandos HTML diretamente. O HTML ento ser propriamente
exibido no Web Browser;

Qualquer retorno diferente de uma string de caracteres gerar um erro que ser enviado aplicao client
HTTP (o erro gerado Invalid Proc Return);

O AP5 Server passa alguns parmetros para as funes chamadas. Isso significa que ao criar funes para
serem utilizadas em resposta s requisies HTTP, deve-se criar o cabealho da funo com estes
parmetros. No obrigatrio utilizar os mesmos nomes de parmetros sugeridos abaixo quando criar
diretamente estas funes. Porm, como so esses os nomes utilizados no ADVPL ASP explicado mas a
frente, aconselhvel utiliz-los por motivo de padronizao:
- __aCookies: Este parmetro recebe um array bidimensional com os Cookies criados na aplicao client
HTTP (por exemplo, no Internet Explorer 5). Pode-se utiliz-lo para checar validaes mantidas nas
mquinas client por exemplo. Para maiores detalhes, consulte a documentao do HTML ou do Web
Browser utilizado.

- __aPostParms: Este parmetro recebe um array bidimensional com os campos contidos em um

formulrio HTML recebido atravs de um comando POST. Cada item deste array contm um array
com o nome do campo e o valor informado. Por exemplo, para um formulrio com dois campos para
digitao (um chamado nome e o outro chamado endereco), que enviam os dados para a funo
cadastro.apl atravs de um POST, a funo receber o array __aPostParms da seguinte forma:
{
{nome, NOME DIGITADO NA PAGINA HTML},
{endereco, ENDERECO DIGITADO NA PAGINA HTML}
}
A funo pode tratar os dados recebidos neste array para realizar um processamento especfico com
tais informaes. Para campos onde no possvel a entrada de dados e sim a escolha de uma
informao pr-definida (como por exemplo um checkbox), o item somente existir no array caso o
campo tenha sido selecionado no formulrio HTML (por exemplo, se o checkbox for marcado).

- __nProcID: Contm o Handle da Thread de execuo daquela funo. A utilizao deste parmetro
ser explicada juntamente com o tpico ADVPL ASP posteriormente;

- __aProcParms: Este parmetro recebe um array bidimensional com os parmetros enviados na linha de
URL do Web Browser. Por exemplo, na execuo de uma funo via linha de URL do Web Browser
como:
http://servidor/vende.apl?cod=000001&nome=PRODUTO DE TESTE&quant=20
a funo chamada vende receber o array __aProcParms da seguinte forma:
{
{cod, 000001},
{nome, PRODUTO DE TESTE},
{quant, 20}
}
Advanced Protheus - AP5 Conectividade e Advpl ASP 13
CopyRight 2000 Release A Microsiga Software S.A.
 A funo pode tratar estes dados recebidos para realizar processamentos especficos. muito til
tambm para criar links de execuo diretamente atravs de um Web Browser.

- __cHTTPPage: Esse parmetro recebe o nome da pgina, arquivo ou funo originalmente requisitada
para o AP5 Server. utilizado quando as chaves GETPROC e POSTPROC (explicadas anteriormente)
so habilitadas no arquivo de configuraes do AP5 Server. A funo configurada ir receber nesse
parmetro o nome original requisitado e poder executar algum processamento especfico para
continuar o processo (retornando a prpria funo original) ou desviar para outra pgina, por exemplo.

Exemplo de funo APL

A funo a seguir um bom exemplo para ser executado atravs de um Web Browser como o Internet Explorer ou o
Netscape Navigator. Ela retorna uma string contendo a pgina HTML onde est escrita a mensagem Hello World e
a lista de parmetros passados na linha de URL. Para test-la, crie um arquivo novo no AP5 IDE, cole o cdigo
abaixo e salve o arquivo como WEBDEMO.PRW. Aps compilar o programa, basta chamar em um Web Browser
uma URL como:

http://localhost/u_webdemo.apl?cod=000001&desc=DESCRICAO DO PRODUTO&qtd=2

Cdigo da funo:

#include "rwmake.ch"

User Function WebDemo(__aCookies,__aPostParms,__nProcID,__aProcParms,__cHTTPPage)

Local cHTML := ""
Local i

// Coloca uma mensagem em HTML

cHTML += '<p><h1 align="center">Hello World!!!</h1></p>'

// Coloca um separador de linha em HTML

cHTML += '<hr>'

If Len(__aProcParms) = 0
cHTML += '<p>Nenhum parmetro informado na linha de URL.'
Else
For i := 1 To Len(__aProcParms)

cHTML += '<p>Parmetro: ' + __aProcParms[i,1] + ' - Valor: ' +

__aProcParms[i,2] + '</p>'

Next i
Endif

Return(cHTML)

Para crias as funes que sero utilizadas em chamadas via um Web Browser, ou seja, em
qualquer request HTTP, deve-se seguir o procedimento normal de criao de funes no
AP5: utilizando o AP5 IDE para a edio e para a compilao.
Note que no caso de funes do usurio (User Function) o nome chamado na URL do
Browser tambm dever conter o U_ no comeo da funo, por exemplo:
http://servidor/u_webrelato.apl
E deve-se sempre indicar a extenso .APL para que o AP5 Server identifique que uma funo a ser
executada.

Advanced Protheus - AP5 Conectividade e Advpl ASP 14

CopyRight 2000 Release A Microsiga Software S.A.
O ADVPL ASP
Uma pgina ASP (Active Server Pages) uma pgina HTML contendo cdigo interpretvel em uma linguagem
compreensvel ao servidor HTTP em uso. Por exemplo, o IIS da Microsoft utiliza o VBScript para criar suas pginas
ASP, do mesmo modo que o AP5 utiliza o ADVPL. Uma pgina ASP uma combinao de script HTML e cdigo
interpretvel. No ADVPL ASP esse cdigo padro xBase, portanto a preocupao maior daqueles que j conhecem
e trabalham com o AP5 e desejam desenvolver pginas ativas para aplicaes Web utilizando essa facilidade
conhecer HTML.

Caractersticas do ADVPL ASP

Os arquivos ADVPL ASP tm a extenso padro .APH. So arquivos texto e devem ser adicionados a um projeto no
AP5 IDE e compilados da mesma maneira que os programas tradicionais. A diferena que o AP5 Server
identificar que se trata de um ADVPL ASP e executar uma espcie de tradutor (parser) antes que a compilao
seja executada. Este parser ir transformar todo o arquivo em uma funo nica, que receber os mesmos parmetros
das funes APL simples, como explicado anteriormente, e retornar uma string. O desenvolvedor no precisa se
preocupar em retornar HTML algum, pois o APH tambm um arquivo HTML. A funo que foi gerada na
compilao ir se encarregar de retornar o HTML contido no arquivo, depois que o cdigo foi processado.

Por se tornar uma funo no momento da compilao, no possvel utilizar a clusula

FUNCTION para criar outras funes dentro de um arquivo APH. Caso exista essa
necessidade, tais funes devem ser criadas em um arquivo PRW tradicional e chamadas de
dentro do APH.
Do mesmo modo que as demais funes, o arquivo APH tambm deve ser executado
(atravs da URL do Browser, por exemplo) com a extenso .APL.
A extenso APH para o nome dos arquivos obrigatria. Qualquer outra extenso usada no nome do
arquivo no ser reconhecida e o parser no ser executado antes da compilao.

Assim como outros ASPs, a diferenciao entre script HTML e cdigo efetuada atravs dos caracteres <% para
indicao de abertura de cdigo e %> para indicao do encerramento de cdigo.
Por exemplo, o HTML abaixo contm um pedao de cdigo ADVPL separado pelos delimitadores:

<html>
<head>
<title>ADVPL ASP Demo</title>
</head>

<body>
<p>Bem vindo ao mundo do ADVPL ASP!</p>

<%
// Soma os 100 primeiros nmeros
Local i, nSoma := 0
For i := 1 To 100

NSoma += i

Next i
%>

</body>
</html>

Quando este arquivo for requisitado ao AP5 Server (atravs de uma chamada em URL por exemplo) o cdigo entre
os delimitadores ser executado, porm o script colocado ao redor do cdigo ser mantido exatamente como se
encontra.

Advanced Protheus - AP5 Conectividade e Advpl ASP 15

CopyRight 2000 Release A Microsiga Software S.A.
A grande vantagem de se criar arquivos ADVPL ASP em relao a criar funes APL simples, decorre do fato de
que no necessrio conhecer to profundamente HTML e que nas funes APL simples o desenvolvedor deve se
preocupar em retornar todo o HTML necessrio para a correta exibio no Web Browser. E tambm, como o
ADVPL ASP mistura o script HTML com o cdigo interpretvel, pode-se criar um arquivo APH utilizando o editor
desejado (como o Microsoft FrontPage por exemplo) e inserir o cdigo necessrio entre o script. Outro detalhe
importante que pode-se utilizar as estruturas de fluxo da linguagem ADVPL para repetir comandos do prprio
script HTML (por exemplo, colocar um comando de script HTML dentro de um comando While em ADVPL):

<% While !EOF() %>

<B> Esta linha ser repetida no HTML at ocorrer o fim de arquivo </B>
<%
dbSkip()
EndDo
%>

Note que tambm pode existir diferentes blocos de cdigo interpretvel separados pelos delimitadores, dentro de um
mesmo arquivo.

To importante quanto mesclar cdigo interpretvel com script de formatao HTML, utilizar os comandos
ADVPL para alterar o script de formatao. Ou seja, colocar o contedo de variveis, campos, etc, diretamente no
HTML que ser enviado aplicao client (ao Browser por exemplo). Isso pode ser realizado atravs dos
delimitadores de avaliao. Os delimitadores de avaliao so <%= para abertura e %> para encerramento.
Diferentemente dos delimitadores de cdigo interpretvel, estes devem sempre estar na mesma linha. Com eles
pode-se criar uma linha de script HTML, cujo contedo contm uma expresso que ser avaliada em tempo de
execuo:

<b>Esta linha HTML, mas a data exibida aqui: <%= Time() %> foi obtida em
tempo de execuo.</b>

No exemplo acima, a linha HTML ser retornada para o Browser com o resultado da funo time (ou seja, a hora
atual no servidor) inserido no texto.

Utilizando todos esses conceitos, pode-se criar toda uma apliao Web baseada no AP5. Ou seja, o processamento e
acesso aos dados fica por conta do AP5 Server, e a interface fica por conta do Browser (utilizando o HTML). Abaixo
um exemplo de um relatrio de clientes criado utilizando o ADVPL ASP. Para test-lo basta copiar o cdigo, salv-
lo como WEBREL.APH e compilar o arquivo atravs do AP5 IDE:

<html>
<head>

<% //Funo para manuteno do ambiente %>

<%= HTMLProcID(__nProcID) %>

<title>ADVPL ASP DEMO</title>

</head>

<%
#define FIELD_CODDE "FROM_CODE"
#define FIELD_CODATE "TO_CODE"
#define FIELD_LOCDE "FROM_LOCAL"
#define FIELD_LOCATE "TO_LOCAL"

// Criao das variveis com os parmetros recebidos atravs

// do array __aProcParms

Local cCodDe,cCodAte,cLocDe,cLocAte
Local nPos

nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_CODDE })

If nPos != 0
cCodDe := __aProcParms[nPos,2]
Advanced Protheus - AP5 Conectividade e Advpl ASP 16
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>Relatrio de Produtos</u></h3>
</td>
</tr>
<tr>
<td>
<p align="left"><b>Data de gerao</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>Parmetro</b></font></th>
<th width="327" height="24" bgcolor="#008080" align="left"><font
color="#FFFFFF"><b>Valor</b></font></th>
</tr>

<%
// "Impresso" dos parmetros

Advanced Protheus - AP5 Conectividade e Advpl ASP 17

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 parmetro 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>Cdigo</b></font></th>
<th width="50%" align="left" bgcolor="#336699"><font
color="#FFFFFF"><b>Descrio</b></font></th>
<th width="7%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Local</b></font></th>
<th width="17%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Quantidade
em Estoque</b></font></th>
<th width="14%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Custo
Mdio</b></font></th>
</tr>

<%
While !EOF() .And. xFilial("SB1") == SB1->B1_FILIAL .And. SB1->B1_COD <= cCodAte;
.And. SB1->B1_LOCPAD <= cLocAte

SB2->(dbSetOrder(1))
SB2->(dbSeek(xFilial("SB2")+SB1->B1_COD+SB1->B1_LOCPAD,.F.))
%>
<tr>
<td 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 18

CopyRight 2000 Release A Microsiga Software S.A.
</html>

Aps ter o cdigo compilado, pode-se visualizar o resultado acessando atravs de um Web Browser como o Internet
Explorer a seguinte URL:

http://servidor/h_webrel.apl

Advanced Protheus - AP5 Conectividade e Advpl ASP 19

CopyRight 2000 Release A Microsiga Software S.A.