Upload
lekhanh
View
268
Download
3
Embed Size (px)
Citation preview
Programao Advpl para WEB
Reviso: 27/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Este tpico engloba todo o conhecimento e informaes necessrias para usufruirmos da
tecnologia implementada na ferramenta Protheus e de sua Infra-Estrutura, para o
desenvolvimento de aplicaes orientadas Internet.
O objetivo desta seo centralizar as informaes pertinentes ao desenvolvimento de
projetos WEB, em uma ferramenta que permita o acesso e atualizaes destes dados de
maneira rpida e dinmica, alm de mostrar uma boa parte do que possvel fazer
utilizando-se dos recursos disponveis na ferramenta Protheus.
Para que seja possvel compreender as funcionalidades e tecnologias envolvidas no
processo de desenvolvimento de uma aplicao WEB, utilizando-se da
ferramenta Protheus, de fundamental importncia que os tpicos deste grupo sejam
lidos e assimilados, pois nos mesmos encontram-se as informaes que servem de base
para a compreenso e consequente melhor aproveitamento dos recursos disponveis.
Para se ter uma idia superficial do poder do Protheus como servidor http, esta
aplicao ( DEM - Documentao Eletrnica Microsiga ) foi escrita em Advpl-ASP,
utilizando uma compilao do Server Protheus ISAPI , integrado com o IIS 5, utilizando
um Banco de Dados SQL Server 2000 atravs do TopConnect 4, utilizando se de
Working Threads Extended (WEBEX) e das funes de Infra-Estrutura da lib
APWEBEX.
01. O Servidor Protheus como um
servidor HTTP
Reviso: 27/04/2004
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10
O Servidor Protheus como um servidor
HTTP
O servidor Protheus 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 (R) ou o Apache para Linux). Assim, basta ter
o Protheus para poder criar sua prpria Intranet num ambiente de rede local, ou publicar
o endereo IP da mquina com o servidor Protheus na Internet e executar funes
atravs de RPC ou simplesmente criar o seu prprio Web Site com pginas HTML
estticas ou dinmicas.
Servio de HTTP
O protocolo HTTP (Hyper Text Transfer 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. Mas adiante, ser mais fcil compreender onde tais
comandos so utilizados no servidor Protheus.
Utilizando o servidor Protheus 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 Protheus para processar pginas mistas, que contm cdigo Advpl e
comandos HTML de formatao. Tais pginas sero processadas no servidor Protheus,
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 Protheus, atravs de um request HTTP (por exemplo, atravs de um
POST em um formulrio em HTML, ou de um link, ou mesmo diretamente na linha de
URL do Web Browser. O mesmo vale para qualquer outra aplicao que seja capaz de
efetuar comandos GET ou POST utilizando o protocolo HTTP).
Pginas Dinmicas e Advpl ASP
Quando utilizado o servidor Protheus para desenvolvimento de aplicaes Web,
possvel lanar mo do recurso de criao de pginas dinmicas, isto , uma
requisio HTTP realizada o Server Protheus, devidamente configurado para atend-
la, dispara o processamento de uma funo no Servidor, e esta funo encarrega-se de
devolver o usurio uma pgina HTML com o resultado do processamento.
Para viabilizar o desenvolvimento deste tipo de funo, foi criado um tipo de arquivo
especial no Protheus IDE, com a extenso .APH, onde inserido um contedo Html a
ser enviado ao Web Browser, e instrues Advpl que sero processadas no momento em
que a pgina for solicitada ao servidor Protheus, sendo possvel de forma
prtica 'mesclar' um contedo gerado por este processamento uma pgina Html para
ser retornado o Web Browser.
Nos tpicos abaixo relacionados, ser visto em mais detalhes as configuraes
necessrias para atender estas requisies, as caractersticas particulares de cada uma
delas, e as funes de infra-estrutura criadas para auxiliar o desenvolvimento de
aplicaes Web.
Alm da criao de arquivos, foi disponibilizado no repositrio padro do Protheus as
funes de infra-estrutura ApWebEx, desenvolvidas para permitir um melhor
aproveitamento dos recursos disponibilizados pela ferramenta Protheus para o
desenvolvimento de solues Web. Estas funcionalidades so exploradas no tpico
Infra-Estrutura ApWebEx.
02. Executando funes Advpl via HTTP
Reviso: 28/04/2004
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11
Princpio de Funcionamento do HTTP
A utilizao do protocolo HTTP no envolve o uso de uma conexo persistente entre o
Web Browser e o Servidor HTTP : Isto significa que, ao ser solicitada uma pgina,
imagem ou at o processamento de uma funo, o Web Browser abre uma conexo com
o Server HTTP, realiza a solicitao e fica com a conexo aberta, aguardando pelo
retorno do Server. Quando o server j houver enviado os dados solicitados, a conexo
fechada .
Processamento de Funes
Para o retorno de pginas estticas, imagens e demais arquivos via HTTP, o servidor
identifica o que est sendo solicitado pelo Web Browser atravs da extenso do Link.
Por exemplo, ao receber uma soilicitao da URL http://oservidor/htmls/imagem.gif, o
Server HTTP sabe que deve procurar um arquivo chamado imagem.gif, dentro da pasta
htmls a partir da pasta local no servidor configurada para armazenar os arquivos para o
acesso HTTP.
No servidor Protheus, foram implementadas duas extenses de Link para permitir a
execuo de funes Advpl atravs de uma requisio HTTP : A extenso .APL e a
extrenso .APW . Quando o servidor recebe uma requisio via HTTP, por exemplo da
url http://oservidor/time.apl, e est corretamente configurado para atender esta
requisio, o Protheus Server realiza o processamento, e informa para o Web Browser
solicitante que a string que ser retornada deve ser interpretada pelo Web Browser como
sendo um Script HTML .
Caractersticas comuns do processamento de funes Advpl via HTTP
Independente da extenso de link utilizada, existem caractersticas e pr-requisitos
comuns ao funcionamento de ambas as requisies, que seguem abaixo :
A funo, seja Advpl ou uma funo compilada no Repositrio, deve
obrigatoriamente ter um retorno do tipo String, pois o Web Browser solicitante
ser informado pelo Server Protheus que a string retornada dever ser
interpretada e mostrada pelo Browser como um HTML.
Devido origem da requisio no ter relao alguma com a interface Remote
do Protheus, no possvel utilizar determinadas funes Advpl que foram
escritas exclusivamente para esta interface, como por exemplo as funes
MsgStop, Alert, e demais funes e objetos de Interface de Janelas.
O que ir diferenciar uma funo executada via link .apl e .apw ser as etapas de
execuo das mesmas. Esta caracterstica de funcionamento ser melhor esclarecida
aps a leitura dos tpicos sobre desenvolvimento de funes .apl e desenvolvimento
de funes .apw
03. Pginas dinmicas - O Advpl ASP
Reviso: 26/04/2004
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11
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
http://oservidor/htmls/imagem.gifhttp://oservidor/time.apl
modo que o Protheus 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 Protheus e desejam
desenvolver pginas ativas para aplicaes Web utilizando essa facilidade conhecer
HTML.
Caractersticas do ADVPL ASP - Arquivos .APH
Os arquivos ADVPL ASP tm a extenso padro .APH. So arquivos texto e devem ser
adicionados a um projeto no Protheus IDE e compilados da mesma maneira que os
programas tradicionais. A diferena que o Protheus 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 no Item 'Desenvolvendo Funes .APL', e retornar uma string.
O desenvolvedor no precisa se preocupar em retornar HMTL algum, pois o APH
tambm um arquivo HTML. A funo que foi gerada na compilao ir se encarregar
de retornar o HTML contigo no arquivo, depois que o cdigo foi processado. Um
Arquivo APH gera no repositrio de Objetos do Protheus uma funo com o mesmo
nome do arquivo , porm prefixada com H_ + nome_do_arquivo_aph
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.
A extenso APH para o nome dos arquivos obrigatria. Qualquer outra extenso usada
no nome do arquivo no ser reconhecida e o parser do IDE no ser executado durante
a compilao. Foi criada tambm a extenso de arquivos .AHU ( Aph de Usurio ), que
possui o mesmo tratamento de Parser do aruqivo APH , gerando uma funo prefixada
com L_ . A diferena que a funo gerada pelo AHU pode ser gerada sem a
necessiade de autorizao de compilao com permisso para substituir fontes
microsiga , por tratar-se de um Aph de Usurio, qeuivalente uma User Function .
Assim como outros ASPs, a diferenciao entre script HTML e cdigo efetuada
atravs dos caracteres para indicao do
encerramento de cdigo. Por exemplo, o HTML abaixo contm um pedao de cdigo
ADVPL separado pelos delimitadores:
ADVPL ASP Demo
Bem vindo ao mundo do ADVPL ASP!
Quando este arquivo for requisitado ao Protheus 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. Por exemplo :
http://localhost/H_WEBDEMO.APL
A grande vantagem de se utilizar dos arquivos ADVPL ASP em relao a criar funes
APL simples, decorre do fato de 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 nele os cdigos Advpl necessrios entre as Tags.
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):
Esta linha ser repetida no HTML at ocorrer o fim de arquivo
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
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, e seu
resultado inserido como parte do Html retornado o Browse :
Esta linha HTML, mas o horrio exibido aqui: foi obtido em
tempo de execuo no Servidor.
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 aplicao Web baseada no
http://localhost/H_WEBDEMO.APL
Protheus. Ou seja, o processamento e acesso aos dados fica por conta do Protheus
Server, e a interface fica por conta do Browser (utilizando o HTML) .
Importante
Ao codigicar um arquivo .APH e/ou .AHU , devemos estar atentos s regras de
utilizao dos delimitadores de execuo e avaliao Advpl :
1. A Abertura e fechamendo dos delimitadores de execuo devem estar
isoladas em suas respectivas linhas, no devendo ter qualquer conteudo adicional, nem
duas aberturas e fechamentos na mesma linha. Partindo dessa premissa, veja abaixo
alguns exemplos de como inserir o cdigo Advpl abaixo dentro de um APH:
IF !lOk
nErro++
Endif
CERTO
CERTO
CERTO
ERRADO
-- 2 aberturas e fechamentos na mesma linha
2. Quant os delimitadores de avaliao , podemos ter vrias aberturas e
fechamentos na mesma lionha , porm no podemos ter uma abertura e seu respectivo
fechamento em linhas diferentes.
3. Uma linha qualquer em um arquivo .APH nao deve conter mais do que 150
Caracteres, pois o Parser insere caracteres de controle em cada linha do mesmo durante
a pr-compilao . e a linha final resultante no pode ultrapassar 254 caracteres, pois
neste caso isto impossibilita a compilao do APH.
02. Executando funes Advpl via HTTP
Reviso: 28/04/2004
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11
Princpio de Funcionamento do HTTP
A utilizao do protocolo HTTP no envolve o uso de uma conexo persistente entre o
Web Browser e o Servidor HTTP : Isto significa que, ao ser solicitada uma pgina,
imagem ou at o processamento de uma funo, o Web Browser abre uma conexo com
o Server HTTP, realiza a solicitao e fica com a conexo aberta, aguardando pelo
retorno do Server. Quando o server j houver enviado os dados solicitados, a conexo
fechada .
Processamento de Funes
Para o retorno de pginas estticas, imagens e demais arquivos via HTTP, o servidor
identifica o que est sendo solicitado pelo Web Browser atravs da extenso do Link.
Por exemplo, ao receber uma soilicitao da URL http://oservidor/htmls/imagem.gif, o
Server HTTP sabe que deve procurar um arquivo chamado imagem.gif, dentro da pasta
htmls a partir da pasta local no servidor configurada para armazenar os arquivos para o
acesso HTTP.
No servidor Protheus, foram implementadas duas extenses de Link para permitir a
execuo de funes Advpl atravs de uma requisio HTTP : A extenso .APL e a
extrenso .APW . Quando o servidor recebe uma requisio via HTTP, por exemplo da
url http://oservidor/time.apl, e est corretamente configurado para atender esta
requisio, o Protheus Server realiza o processamento, e informa para o Web Browser
solicitante que a string que ser retornada deve ser interpretada pelo Web Browser como
sendo um Script HTML .
Caractersticas comuns do processamento de funes Advpl via HTTP
Independente da extenso de link utilizada, existem caractersticas e pr-requisitos
comuns ao funcionamento de ambas as requisies, que seguem abaixo :
A funo, seja Advpl ou uma funo compilada no Repositrio, deve
obrigatoriamente ter um retorno do tipo String, pois o Web Browser solicitante
ser informado pelo Server Protheus que a string retornada dever ser
interpretada e mostrada pelo Browser como um HTML.
Devido origem da requisio no ter relao alguma com a interface Remote
do Protheus, no possvel utilizar determinadas funes Advpl que foram
escritas exclusivamente para esta interface, como por exemplo as funes
MsgStop, Alert, e demais funes e objetos de Interface de Janelas.
http://oservidor/htmls/imagem.gifhttp://oservidor/time.apl
O que ir diferenciar uma funo executada via link .apl e .apw ser as etapas de
execuo das mesmas. Esta caracterstica de funcionamento ser melhor esclarecida
aps a leitura dos tpicos sobre desenvolvimento de funes .apl e desenvolvimento
de funes .apw
03. Pginas dinmicas - O Advpl ASP
Reviso: 26/04/2004
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11
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 Protheus 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 Protheus e desejam
desenvolver pginas ativas para aplicaes Web utilizando essa facilidade conhecer
HTML.
Caractersticas do ADVPL ASP - Arquivos .APH
Os arquivos ADVPL ASP tm a extenso padro .APH. So arquivos texto e devem ser
adicionados a um projeto no Protheus IDE e compilados da mesma maneira que os
programas tradicionais. A diferena que o Protheus 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 no Item 'Desenvolvendo Funes .APL', e retornar uma string.
O desenvolvedor no precisa se preocupar em retornar HMTL algum, pois o APH
tambm um arquivo HTML. A funo que foi gerada na compilao ir se encarregar
de retornar o HTML contigo no arquivo, depois que o cdigo foi processado. Um
Arquivo APH gera no repositrio de Objetos do Protheus uma funo com o mesmo
nome do arquivo , porm prefixada com H_ + nome_do_arquivo_aph
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.
A extenso APH para o nome dos arquivos obrigatria. Qualquer outra extenso usada
no nome do arquivo no ser reconhecida e o parser do IDE no ser executado durante
a compilao. Foi criada tambm a extenso de arquivos .AHU ( Aph de Usurio ), que
possui o mesmo tratamento de Parser do aruqivo APH , gerando uma funo prefixada
com L_ . A diferena que a funo gerada pelo AHU pode ser gerada sem a
necessiade de autorizao de compilao com permisso para substituir fontes
microsiga , por tratar-se de um Aph de Usurio, qeuivalente uma User Function .
Assim como outros ASPs, a diferenciao entre script HTML e cdigo efetuada
atravs dos caracteres para indicao do
encerramento de cdigo. Por exemplo, o HTML abaixo contm um pedao de cdigo
ADVPL separado pelos delimitadores:
ADVPL ASP Demo
Bem vindo ao mundo do ADVPL ASP!
Quando este arquivo for requisitado ao Protheus 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. Por exemplo :
http://localhost/H_WEBDEMO.APL
A grande vantagem de se utilizar dos arquivos ADVPL ASP em relao a criar funes
APL simples, decorre do fato de 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 nele os cdigos Advpl necessrios entre as Tags.
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):
Esta linha ser repetida no HTML at ocorrer o fim de arquivo
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
http://localhost/H_WEBDEMO.APL
client (ao Browser por exemplo). Isso pode ser realizado atravs dos delimitadores de
avaliao. Os delimitadores de avaliao so 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, e seu
resultado inserido como parte do Html retornado o Browse :
Esta linha HTML, mas o horrio exibido aqui: foi obtido em
tempo de execuo no Servidor.
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 aplicao Web baseada no
Protheus. Ou seja, o processamento e acesso aos dados fica por conta do Protheus
Server, e a interface fica por conta do Browser (utilizando o HTML) .
Importante
Ao codigicar um arquivo .APH e/ou .AHU , devemos estar atentos s regras de
utilizao dos delimitadores de execuo e avaliao Advpl :
1. A Abertura e fechamendo dos delimitadores de execuo devem estar
isoladas em suas respectivas linhas, no devendo ter qualquer conteudo adicional, nem
duas aberturas e fechamentos na mesma linha. Partindo dessa premissa, veja abaixo
alguns exemplos de como inserir o cdigo Advpl abaixo dentro de um APH:
IF !lOk
nErro++
Endif
CERTO
CERTO
CERTO
ERRADO
-- 2 aberturas e fechamentos na mesma linha
2. Quant os delimitadores de avaliao , podemos ter vrias aberturas e
fechamentos na mesma lionha , porm no podemos ter uma abertura e seu respectivo
fechamento em linhas diferentes.
3. Uma linha qualquer em um arquivo .APH nao deve conter mais do que 150
Caracteres, pois o Parser insere caracteres de controle em cada linha do mesmo durante
a pr-compilao . e a linha final resultante no pode ultrapassar 254 caracteres, pois
neste caso isto impossibilita a compilao do APH.
04. Desenvolvimento de Funes .APL
Reviso: 27/04/2004
Abrangncia
Verso 5.07 Verso 5.08 Verso 6.09 Verso 7.10 Verso 8.11
A princpio, todas as funes contidas no repositrio podem ser executadas diretamente
atravs de uma requisio HTTP, via link com extenso .apl, ao Protheus 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 servidor Protheus 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:
o __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.
o __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).
o __nProcID: Contm o Handle da Thread de execuo daquela funo. A
utilizao deste parmetro ser explicada juntamente com o tpico
ADVPL ASP posteriormente;
o __aProcParms: Este parmetro recebe um array bidimensional com os
parmetros enviados na linha de URL do Web Browser. Por exemplo, na
execuo de uma funo via linha de URL do Web Browser como:
http://servidor/vende.apl?cod=000001&nome=PRODUTO DE
TESTE&quant=20
a funo chamada vende receber o array __aProcParms da seguinte
forma:
{ {cod, 000001},
{nome, PRODUTO DE TESTE},
{quant, 20} }
A funo pode tratar estes dados recebidos para realizar processamentos
especficos. muito til tambm para criar links de execuo
diretamente atravs de um Web Browser.
o __cHTTPPage: Esse parmetro foi criado originbalmente para recebe o
nome da pgina, arquivo ou funo originalmente requisitada para o
Protheus Server, porm no foi utilizado e permaneceu por
compatibilidade.Caso consultado, ele retorna uma string em branco.
o __aHTTPHead: Esse parmetro recebe um array com os Headers do
cabealho da requisio HTTP enviados pelo Web Browser.
Exemplo de funo APL
A funo a seguir um bom exemplo para ser executado atravs de um Web Browser.
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 Protheus 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 += '
Hello World!!!
'
// Coloca um separador de linha em HTML
cHTML += ''
If Len(__aProcParms) = 0
cHTML += '
Nenhum parmetro informado na linha de URL.'
Else
For i := 1 To Len(__aProcParms)
cHTML += '
Parmetro: ' + __aProcParms[i,1] + ' - Valor:
' +
__aProcParms[i,2] + '
'
Next i
Endif
Return(cHTML)
Importante
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_WebDemo.apl
Configurao Mnima
Em tpico parte explicada toda a configurao referente seo http do Protheus
Server. A configurao abaixo a mnima necessria para executar o exemplo acima
[http]
Port=80
Path=(caminho absoluto de disco para arquivos publicados no servidor )
Environment=(nome do environment do Serber que ser utilizado para o
processamento)
Para testar sua configurao, reinicie o server Protheus e chame via WebBrowser a url :
http://localhost/time.apl
http://servidor/u_WebDemo.aplhttp://localhost/time.apl
Dever ser mostrada no Browse o horrio atual, no formato hh:mm:ss, no Servidor, pois
este o resultado da funo Advpl TIME() .
O Protheus atendendo requisies .apl
Quando solicitado atravs de um Web Browser um processamento de uma funo via
link .apl, a funo solicitada deve ser responsvel por abrir o ambiente necessrio o
processamento, conectar com o Banco de Dados caso necessrio, realizar o
processamento e retornar a String Html ao Web Browser.
Este ambiente criado fechado imediatamente aps o trmino do processamento, o que
exige muito do Servidor da aplicao em se tratando de uma aplicao web com vrios
usurios efetuando acessos simultneos. Para atender com mais eficincia s requisies
de processamento de um projeto web, foi implementada no Protheus a tecnologia de
'Working Threads', explicada em mais detalhes no tpico 'Desenvolvimento de Funes
.apw'.
05. Desenvolvimento de Funes .APW
Reviso: 26/04/2004
Abrangncia
Verso 6.09 Verso 7.10 Verso 8.11
Diferena de Funcionamento entre links .APL e .APW
Como visto em tpicos anteriores, ao desenvolver uma funo para ser executada via
link .apl, a funo deve ser responsvel pela abertura do ambiente e inicializaes
necessrias para um processamento qualquer, e aps ser finalizado este processamento,
o ambiente montado e utilizado fechado automaticamente, de modo que cada
requisio de processamento de usurio atravs de link .apl ir iniciar uma nova Thread,
onde o ambiente dever ser preparado novamente. A programao neste tipo de
ambiente exige muito do servidor Protheus.
Visando dar perfornance s aplicaes WEB desenvolvidas utilizando-se o Protheus, foi
criado link .APW, que utiliza um recurso do servidor Protheus conhecido como
'working threads'. Uma wortking thread uma configurao especial de job, que
permite configurar umnmero pr-definido de Threads no Servidor, as quais tero o
ambiente de execuo preparado e inicializado atravs de uma funo Advpl, onde cada
working thread deixada na memria do servidor em modo de espera (stand-by), de
modo que, um usurio, ao acessar um link .apw, o servidor Protheus ir direcionar a
requisio de processamento uma working thread que estiver em stand-by, e, aps o
processamento ser efetuado e o HTML ser retornado ao Browser, a working thread
retorna novamente ao estado de stand-by, voltando a estar disponvel para atender
uma nova requisio, do mesmo ou de outro usurio navegando no site / aplicao Web.
A utilizao de Working Threads exige a definio mnima de duas funes Advpl, que
sero executadas em dois momentos distintos : A primeira funo responsvel pela
inicializao do ambiente comum de execuo de requisies, devendo estabelecer
conexo com a Base de Dados utilizada, abrir as tabelas utilizadas no Site e preparar as
variveis comuns de utilizao da aplicao. A segunda funo ser responsvel por
encapsular a requisio do usurio realizada a partir do Web Browse : Ela receber
como parmetro o nome do link digitado e macro-executar a funo correspondente,
realizando o tratamento de erro e retorno.
Deste modo, um ambiente uma vez inicializado no fechado, e pode ser utilizado por
vrios usurios que esto navegando no Site, o que viabiliza um grande ganho em
perfoemance e carga do Servidor.
Tipos de Working Threads
Existem dois tipos de Working Threads configurveis no Protheus : a Working Thread
WEB, e a Working Thread WEBEX ( abreviao de WEB EXtended ). Ambas possuem
basicamente o mesmo princpio de funcionamento, porm o que muda entre ambas a
recepo de parmetros e a utilizao de Sessions nativas do Server Protheus. Para
visualizarmos melhor estas diferenas, vejamos com um detalhe um pouco maior os
modelos de funo de inicializao de ambiente e conexo para ambas as configuraes
de Working Threads, WEB e WEBEX.
Working Threads WEB
Para nos utilizarmos das Working Threasd WEB, devemos criar as funes
responsveis pela inicializao de ambiente e a funo de conexo.
A funo de inicializao de ambiente no recebe parmetro algum, realizar a
preparao do ambiente comum de execuo de requisies, e deve retornar um valor
booleano (.T.) verdadeiro caso o ambiente tenha sido inicializado com sucesso, ou (.F.)
falso no caso de alguma condio ou erro que torne o ambiente montado por esta thread
no operacional, caso este em que a Thread removida da memria aps a inicializao.
A funo de conexo recebe os mesmos seis parmetros de uma funo chamada via
link .apl, e um stimo parametro, String, que contm apenas o nome da funo chamada
no link . Por exemplo, a chamada de um link http://localhost/u_teste.apw, no stimo
parmetro da funo de conexo a string 'u_teste'. A funo de conexo deve ter
tratamento de erro prprio e diferenciado, e sempre dever retornar um contedo do tipo
String.
Working Threads WEBEX
Para nos utilizarmos das Working Threasd WEBEX, devemos tambm criar as funes
responsveis pela inicializao de ambiente e a funo de conexo.
A funo de inicializao comporta-se de maneira idntica a de inicializao WEB, no
recebendo parmetro algum, e devendo retornar um valor booleano (.T.) verdadeiro
caso o ambiente tenha sido inicializado com sucesso , ou (.F.) falso no caso de alguma
condio ou erro que torne o ambiente montado por esta thread no operacional, caso
este em que a Thread removida da memria aps a inicializao.
A funo de conexo no recebe diretamente parmetro algum ! Isso mesmo : Todos os
parmetros recebidos em verses anteriores atravs de Arrays, so recebidos agora por
Alias Virtuais de alta velocidade :
HttpGet
HttpPost
HttpCookies
HttpHeadIn
Cada um destes alias virtuais responsvel respectivamente pela recepo de
parmetros via GET , POST , COOKIES e Header HTTP da requisio.
http://localhost/u_teste.apw
Tambm foram implementados os Alias virtuais HttpHeadOut e HttpSession , para
respecrivamente permitir alterar ou adicionar informaes do Header HTTP de retorno
de processamento de uma requisio e utilizao de variveis tipo SESSION por
usurio Web. Estes recursos so detalhados nos tpicos WEBEX - Detalhamento de
Operao e posteriores.
O Futuro das aplicaes WEB no Protheus
Aps o desenvolvimento de aplicaes em ambiente WEBEX, e dados os timos
resultados obtidos, recomenda-se fortemente que as aplicaes web desenvolvidas
utilizando-se o Protheus Server, sejam escritas em conformidade para a utilizao dos
recursos WEBEX.
Para facilitar tal desenvolvimento, em paralelo tecnologia disponibilizada na
aplicao, j est integrada com a Infra-Estrutura disponvel no repositrio padro do
Microsiga Protheus 8 , as funes da Infra-Estrutura ApWebEx, escritas e publicadas
para melhor atender s necessidades comuns verificadas no decorrer do
desenvolvimento de uma aplicao Web.
Os recursos disponveis nesta lib esto documentados nos tpicos Infra-Estrutura
APWEBEX e posteriores , englobando comandos , funes , exemplos e dicas de
utilizao destes recursos.
06. Configurando o Server Protheus para
HTTP
Reviso: 28/04/2004
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
As configuraes de http do Server Protheus permitem a configurao de sites estticos
e dinmicos , com a criao de um ou mais hosts de acesso, criao de pastas virtuais, e
dites dinmicos com resposta para links .apl e .apw simultaneamente. Neste documento
abrangeremos um resumo exemplificado das configuraes HTTP do Server Protheus.
As sees abaixo devem ser inseridas no arquivo de configuraes do servidor Protheus
( mp8srv.ini )
Configurao Mnima
[http]
Enable=1
Path=c:\Ap_Data\http
Observao: Vale lembrar que , aps ter inserido a configurao do [http] no INI do
Protheus, importante baixar o Server e subir novamente.
Com esta configurao, habilitamos o Server Protheus como um servidor de arquivos e
pginas estticas , com o HTTP na porta padro (80), e utilizando o diretorio em
c:\Ap_data\Http como diretrio raiz de publicaes WEB. Como no h configurao
de host especfica, um arquivo nesta pasta poser ser acessado atravs dos hosts
http://localhost ( desde que o browse seja aberto na estao servidora ) ,
http://nnn.nnn.nnn.nnn ( IP da estao servidora ) ou http://xxxxxxxxxx ( nome da
estao servidora ) . Por exemplo : Dentro da pasta configurada na chave PATH do
HTTP, crie um arquivo chamado default.htm , com o seguinte contedo ( pode ser
criado inclusove com o notepad .. )
Ola Mundo HTTP
Agora , abra um Web Browser no mesmo equipamento, e digite na url : http://localhost :
Ao acessar esta url , dever ser mostrado na tela do Browse huas barras horizontais e o
texto 'Ola Mundo HTTP' entre elas .
Atendendo requisies .apl
http://localhost/http://nnn.nnn.nnn.nnn/http://xxxxxxxxxx/http://localhost/
Agora, vamos habilitar este host para atender requisies de funes, atravs de link
.apl. Para tal , precisamos apenas do nome de um Environment (ambiente) configurado
no .INI . Podemos usar o prprio ambinete do ERP . Basta acrescentarmos na seo http
a chave Environment= , para que este ambiente passe a atender
o processamento de funes Advpl atravs de links .apl. Por exemlo , caso o ambiente
configurado para o ERP chame-se EnvADS710 , basta acrescentar na seo http a
chave Environment=EnvADS710 . O .INI ficaria conforme abaixo :
[http]
Enable=1
Path=c:\Ap_Data\http
Environment=EnvADS710
Para testar a execuo de funes , abra um Web Browse na estao servidora, e acesse
o link http://localhost/time.apl . IStoir executar a funo Advpl TIME() , que retornar
ao Browse uma string contendo o horrio atual no servidor no formato HH:MM:SS
Atendendo requisies .apw
A configurao para atendimento de requisies de processamento http atravs de links
.apw envolve a criao de uma nova seo no .INI , com um nome no-especfico, para
configurar o tipo de job que ir executar o processamento ( WEB ou WEBEX ) ,
juntamente com as funes responsveis pela inicializao e conexo das Threads
Advpl , e na seo http configuramos uma chave chamada ResponseJob , apontando
para a seo de configurao do JOB.
Por exemplo , para configurarmos o atendimento de requisies .apw em um ambiente
ERP , utilizando a infra-estrutura APWEBEX , vamos criar uma seo chamada
ERP_APWEBEX, apontando para as funes da Infra-Estrutura APWEBEX
correspondentes :
[ERP_APWEBEX]
type=WEBEX
onstart=STARTWEBEX
onconnect=CONNECTWEBEX
Environment=EnvADS710
Instances=1,3
SigaWeb=MAK
Atravs desta configurao, especificamos um Job do tipo WEBEX , onde a funo de
inicializao utilizada ser a STARTWEBEX , a funo de conexo ser a
CONNECTWEBEX ( ambas da Infra-estrutura APWEBEX ) , que utilizaro o
ambiente AnvADS710 para processamento, e sero colocadas no ar apenas uma
Working Thread para atendimento de processamento, at o mximo de 3 Threads. As
threads colocadas no ar acima do nmero mnimo ( no exemplo, apenas 1 ) , so
colocadas 'on-demand' caso sejam realizadas requisies .apw ao Servidor e no hajam
Working Threads dispovveis no momento e o nmero de Working Threads no ar ainda
no tenha atingido o mximo definido. Atravs da configurao SigaWeb=MAK,
informamos ao sistema, que a mesma est sendo utilizada para o desenvolvimento de
um mdulo especfico, e no estamos utilizando um mdulo Web da ferramenta
http://localhost/time.apl
Protheus 8. Caso a configurao SigaWeb no seja informada, o valor 'MAK'
assumido como default.
Agora , para que esta seo de Jobs seja utilizada para o atendimento efetivo de
requisies .;apw , devemos estecific-la na seo http , atravs da chave REsponseJob.
No caso , inserimos a chave ResponseJob=ERP_APWEBEX , fincando a seo HTTP
conforme abaixo:
[http]
Enable=1
Path=c:\Ap_Data\http
Environment=EnvADS710
ResponseJob=ERP_APWEBEX
Como as requisies via .apl e via .apw so independentes , possvel configurar a
seo http para que Environments diferentes respondam requisies .apl e .apw , ou
que no sejam atendidas requisies .apl , apenas .apw .
Configurando a seo http para multi-host
Todas as configuraes acima vistas pertencem seo default do HTTP . De modo que
, tanto faz acessarmos o servidor pelo nome como pelo IP, que o resultado serr o
mesmo. Porm, para a utilizao de demais recursos, como diretrios virtuais e mais de
um site no mesmo servidor , precisamos configurar um host de acesso.
Por exemplo, vamos criar uma configurao de HOST para que o servidor , caso seja
acessado pelo NOME da maquia via HTTP , seja visualizado um outro site , e apenas
sejam atendidos links .apl : Para isso , devemos criar uma nova seo no .INI , cujo
nome deve ser exatamente o host que ser acessado ( como o exemplo vamos supor que
o servidor de testes chama-se srvteste ) , logo devemos criar uma seo com este nome .
Nesta seo do INI , devemos no mnimo especificar um Path de acesso os arquivos, e
as demais configuraes vistas at agora da seo http so opcionais. A configurao
PORT do HTTP em um host no suportada: No possvel subir um server protheus
em mais de uma porta HTTP.
[srvteste]
Path=c:\Ap_Data\Testes
Environment=EnvTOP710
Deste modo, caso o servidor seja acessado via http atravs de LOCALHOST ou do IP
do Server , ser permitido o acesso s funcionalidades configuradas na seo HTTP.
Caso seja acessado via nome do servidor ( http://srvteste ) , sero acessados os arquivos
de outra pasta , e as requisies .apl sero atendidas pelo Ambiente EnvTOP710 .
Utilizando este tipo de configurao, podemos subir vrios sites diferentes na mesma
aplicao servidor Protheus, cada qual com o seu diretrio raiz de publicaes , seus
ambientes independentes, atendendo ou no requisies .apl e/ou .apw.
Configurando diretrios virtuais
http://srvteste/
Ao configurar um host especfico, podemos acrescentar ao mesmo uma barra "/",
seguido de um nome para acesso um diretrio virtual, criando desse modo um
endereo de acesso composto por um host e um diretrio, que pode se comportar como
um outro site, com os arquivos publicados em um path especfico, que poder atender
requisies de links .apl e/ou .apw sob um outro ambiente e configurao distinta.
Utilizando diretrios virtuais, possvel, dentro do mesmo host, instalar vrias
aplicaes web independentes, todas acessveis sob o mesmo endere base, alterando
apenas o diretrio de acesso. Por exemplo, utilizando como host principal o nome do
equipamento , "servertst", podemos instalar o mdulo Web "Portal Protheus" sob o host
"servertst/portal", o mdulo TCF sob o host "servertst/rhonline", e no host "servertst"
podemos configurar um site esttico em Html , com uma apresentao institucional e
links para os demais mdulos.
Observaes Importantes
Ao configurarmos um Host, ele herda as configuraes de atendimento de requisies
.apl e .apw especificados na seo HTTP ! De modo que o host do exemplo continuar a
atender requisies .apw , porm no ambiente EnvADS710.
Visto desta forma, recomendamos fortemente que a seo [http] possua apenas
especificado um Path em disco que esteja vazio, e seja criada uma ou mais
configuraes de host com as suas devidas propriedades especificas.
Todas as demais chaves relacionadas configurao HTTP e aos Jobs WEB e WEBEX
so opcionais, para atender necessiades especficas. Estas chaves esto explicadas em
maiores detalhes no DEM , na seo XXX
Configurando diretrios virtuais
Da mesma forma que a criao de hosts, podemos criar um novo host utilizando a barra
de diviso '/' para especiicar uma 'pasta virtual' , quue permite a flexibilidade de termos
uma pasta dentro de um mesmo host que se comporte como um outro host : Ainda
baseando-se no .INI montado nestes exemplos para o servidor de testes, vamos supor
que exista uma pasta no disco ( por exemplo , c:\Ap_data\Docs ) , que contenha
arquivos HTML de uma documentao que deve estar disponivel na web , utilizando
tambm o host http://srvteste . Porm , o host srvteste j aponta para o diretrio
c:\Ap_data\Testes.
Com o recurso de criao de diretorio virtual no HTTP , criamos apenas uma nova
entrada do mesmo host , colocando no nome do mesmo uma barra de diviso'/' , seguido
do nome de uma pasta a ser acessada via HTTP ( que no precisa necessariamente
existir no disco) , e dentro desta seo acrescentar a chave path , apontando para o
diretrio desejado , da mesma maneira utilizada para configurar um host.
No exemplo abaixo , criamos a pasta virtual info, dentro do host srvteste, apontando
para o path do disco c:\Ap_Data\Docs. De modo que , ao ser acessado via url o
endereo http://srvteste/info , a partir dele sero acessados os arquivos da pasta
c:\Ap_Data\Docs
http://srvteste/http://srvteste/info
[srvteste/info]
Path=c:\Ap_Data\Docs
Vejamos agora como ficou o nosso arquivo .INI, com todas as configuraes acima
exemplificadas :
;; Configuiracao de Working Threads usando a infra-estrutura APWEBEX
[ERP_APWEBEX]
type=WEBEX
onstart=STARTWEBEX
onconnect=CONNECTWEBEX
Environment=EnvADS710
Instances=1,3
;; Configurao da seo httpo default para atender requisies de .apl e .apw
[http]
Enable=1
Path=c:\Ap_Data\http
Environment=EnvADS710
ResponseJob=ERP_APWEBEX
SigaWeb=MAK
;; Configurao do host srvteste para atender requisies via .apl atravs do
environment EnvTOP710
[srvteste]
Path=c:\Ap_Data\Testes
Environment=EnvTOP710
;; Configurao da pasta virtual info , no host srvteste , para apontar para um path no
disco com documentos
[srvteste/info]
Path=c:\Ap_Data\Docs
Infra-Estrutura APWEBEX
Reviso: 27/04/2004
Abrangncia
Verso 8.11
A Infra-Estrutura APWEBEX
Visando o melhor aproveitamento da tecnologia de working threads, implementada no
servidor Protheus para o processamento de requisies de uma aplicao web, foram
desenvolvidas funes de apoio, miscelnea e infra-estrutura, compiladas no repositrio
padro de Infra-Estrutura do ERP Microsiga, visando simplificar e auxiliar o
desenvolvimento de uma soluo web. A este conjunto de funes , demos o nome de
"Lib de Infra-Estrutura APWEBEX", que engloba atualmente os tratamentos comuns s
funes de inicializao de ambiente e conexo ( atendimento de requisies http via
link .apw ), com seus respectivos pontos de entrada, comandos e funes de miscelnea
comuns os projetos de solues web integradas com o ERP.
Como utilizar este recurso no desenvolvimento de solues ?
As funes pertinentes Infra-Estrutura APWEBEX j esto implementadas no
repositrio padro da ferramenta Protheus 8, e os comandos especficos que envolvem
este recurso encontram-se no arquivo header 'apwebex.ch', disponibilizado tambm
jonto com a ferramenta Protheus 8.
A utilizao destes recursos para integrao de aplicaes envolve a leitura desta
documentao, onde ser visto com maiores detalhes as possibilidades de uso da
ferramenta, como a integrao de uma aplicao Web com um ambiente e
funcionalidades do ERP Microsiga.
Como usufruir desta documentao ?
Todos os tpicos pertencentes este grupo so direcionados o desenvolvimento de
solues web utilizando as funes de Infra-Estrutura APWEBEX, alm de ser
explicado com detalhes o funcionamento da tecnologia WEBEX do Protheus, e dos
recursos nativos da ferramenta, englobando os comandos e funes publicados,
exemplos de cdigos Advpl utilizando estes recursos, configurao da ferramenta e
mensagens de ocorrncias de erro das funes e comandos, com possveis causas e
solues.
fortemente recomendado que os documentos constantes neste grupo fossem
apreciados, antes de aprofundar-se nas informaes dos prximos tpicos.
01. Recepo de parmetros por Alias
Virtuais
Reviso: 30/04/2004
Abrangncia
Verso 7.10 Verso 8.11
A recepo de parmetros vindos do Web Browser, quando utilizamos Working
Threads do tipo WEBEX, atravs de links .apw, realizada atravs de Alias Virtuais
especficos, ao invs de receber as informaes GET , POST e HEADER em array,
quando executamos a chamada atravs de link .apl. A nomenclatura de 'Alias Virtual'
foi adotada, pois a sintaxe do cdigo-fonte exatamente a mesma utilizada quando
desejamos acessar um campo de uma tabela aberta, atravs de um alias.
Em um ambiente montado para atender requisies via link .apw utilizando Working
Threads WEBEX , podemos nos utilizar dos seguintes alias virtuais :
HttpCookies
HttpGet
HttpPost
HttpHeadIn
HttpHeadOut
HttpSession
HttpCookies
Atravs do alias virtual HttpCookies, possvel consultar os Cookies do Header Http
enviados pelo Browser, e criar ou alterar o contedo de um cookie a ser devolvido o
Browser. Um cookie, visto de forma geral, um parmetro ao qual atribumos um
nome, que uma vez devolvido o Browse solicitante, re-enviado ao Protheus a partir
da prxima requisio realizada pelo Browser.
HttpGet
Para receber os parmetros enviados atravs da URL (mtodo GET do HTTP) , j
devidamente convertidos e tratados, utilizamos o alias virtual HttpGet, onde acessamos
pelo nome a propriedade desejada, e caso a mesma tenha sido enviada pelo Browser, a
mesma retornada como uma String.
HttpPost
Para receber os parmetros submetidos (enviados) pelo Browser atravs do mtodo
POST, j devidamente convertidos e tratados, utilizamos o alias virtual HttpPost, onde
acessamos pelo nome a propriedade desejada, e caso a mesma tenha sido enviada pelo
Browser, a mesma retornada como uma String.
HttpHeadIn
Para a recepo e tratamento das informaes recebidas atravs do Header do pacote
HTTP, foi criado o alias virtual HttpHeadIn, que alm de consultar as informaes
constantes no Header HTTP proveinente da requisio do usurio, permite tambm
acesso propriedades da conexo atual do usurio, como o IP do usurio solicitante, por
exemplo.
HttpHeadOut
Atravs deste alias virtual de retorno, podemos alterar ou criar um parmetro no Header
de retorno HTTP do Protheus , a ser devolvido o Browser solicitante de uma requisio
de processamento.
HttpSession
O alias virtual HttpSession foi criado para possibilitar a criao de variveis 'session'
por usurio do site, com controle de identificao nativa da ferramenta atravs de um
cookie de identificao , chamado SESSIONID. No tpico 'Alias Virtual HttpSession'
explicado em detalhes o funcionamento deste mecanismo.
Este recurso nos permite criar , atricuir contedo e consultar contedo de uma varivel
relacionada o usurio que est realizando uma requisio http. Podemos armazenar em
uma varivel de Session os seguintes tipos de variveis : A (array) , C (character) , D
(data), L (lgica) e N (numrica) . No so suportados O (Objetos) e/ou B (Code
Blocks).
Limitaes de uso dos alias virtuais para recebimento de parmetros
Dadas as caractersticas operacionais e de acesso os alias virtuais, devemos estar
atentos nomenclatura de campos de um formulrio HTML, para serem recuperados
com sucesso pelos alias virtuais correspondentes. A nomenclatura de campos do
formulrio deve obedecer regra de criao de variveis em Advpl : O campo do
formulrio deve sempre ser iniciado com um caracter alfabtico, pode conter letras ou
algarismos no nome, e o caracter "_" ( underline ). No so permititos espas, hfen ou
caracteres acentuados como nome de um campo. Caso utilizado um nome de campo
fora do padro suportado, o contedo do mesmo no ser recupervel em Advpl.
02. Alias virtual HttpCookies
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Atravs do alias virtual HttpCookies, possvel consultar os Cookies do Header Http
enviados pelo Browser, e criar ou alterar o contedo de um cookie a ser devolvido o
Browser. Uma varivel de Cookie retorna um tipo Advpl String , e apenas aceita uma
atruibuio de String. Vale lembrar tambm que um cookie um recurso do Browser
que est realizando a requisio, e existe um limite de tamanho para o total de Cookies
utilizados. Este limite costuma ser prximo a 1024 Bytes .
Trata-se portanto de uma propriedade de leitura e gravao, dispnvel apenas quando a
funo Advpl executada atravs de uma requisio http via link .apw utilizando a
configurao de Working Threads WEBEX.
Utilizao de Cookies
A utilizao de Cookies tm objetivo prtico restrito aplicaes onde haja a
necessidade implcita de termos uma informao relacionada o browser utilizado pelo
usurio atual, que devam ser interpretadas independente do usurio estar logado ou no
( isto , independam diretamente de sessions ).
Um exemplo prtico disto o desenvolvimento de um site onde o contedo dinmico
retornado ao usurio em mais de um idioma. Na entrada do site, apresentamos um
formulrio ao usurio onde o mesmo ir escolher o idioma de sua preferncia. Mesmo
que a session de login deste usurio expire no servidor, o cookie com o idioma
selecionado ainda est no Browser, de modo que a prxima requisio do usurio pode
ser codificada para direcion-lo para a pgina de login do site com as mensagens
no idioma que o mesmo j estava navegando.
Lendo o valor de um Cookie
Atravs dos exemplos abaixo , lemos o valor do Cookie de identificao do surio, e
um cookie de usurio criado para identificar no Browse qual o idioma utilizado pelo
usurio atual.
cUserId := HttpCookies->USERID // Retorna o Cookie identificador do usurio do
Protheus
cIdioma := HttpCookies->SiteLang // Retorna o contedo do cookie SiteLang , criado
Lendo todos os Cookies recebidos
O alias virtual HttpCookie possui uma propriedade chamada aCookies, criada apenas
para consulta (read-only), que retorna um Array Advpl de Strings , contendo os nomes
dos Cookies enviados pelo Browser o Protheus . Por exemplo :
aInfo := HttpCookies->aCookies
For nI := 1 to len(aInfo)
// Mostra no console do Server todos os cookies recebidos.
conout('Cookie '+str(nI,3)+' = ' + aInfo[nI])
Next
Criando um Cookie
A criao de um Cookie realizada atravs da atrubuio de um valor diretamente o
cookie desejado. Por exemplo :
HttpCookies->MeuCookie := 'TESTE'
A criao de um Cookie merece uma ateno especial, pois um Cookie retornado o
browser atravs do Header de Retorno HTTP. De modo que, para que a criao de um
cookie seja realizada com sucesso , o mesmo deve ser criado antes de haver qualquer
processamento de APH / AHU, caso este que no seria mais possvel a criao do
Cookie, pois o Header de Retorno HTTP j teria sido enviado o browser solicitante.
03. Alias virtual HttpGet
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Atravs do alias virtual HttpGet, podemos consultar se uma determinada propriedade
nos foi enviada atravs da URL ( mtodo GET ).
Trata-se portanto de uma propriedade de leitura (read-only), disponvel apenas quando a
funo Advpl executada atravs de uma requisio http via link .apw utilizando a
configurao de Working Threads WEBEX.
Consultando um Parmetro
O retorno da consulta de um parmetro pode ter dois tipos : NIL , caso o parmetro no
tenha sido enviado , ou String , contendo o contedo do parmetro. Por exemplo, vamos
realizar uma requisio a um link .apw , passando pela URL o parmetro IMAGEM ,
com o contdo TESTE :
http://localhost/u_TesteGet.apw?imagem=teste&cor=azul
Para recuperarmos em Advpl o contedo dos parmetros imagem e cor , utilizamos:
cImagem := HttpGet->imagem
cCor := HttpGet->cor
Podemos inserir tambm um tratamento default : Caso algum parmetro no seja
enviado ( resulte NIL ) , assumimos um valor para o mesmo
DEFAULT cImagem := 'LogoAp8'
DEFAULT cCor := 'amarelo'
Existe tambm uma propriedade do alias virtual HttpGet chamada aGets , onde
podemos recuperar um array de strings , contendo a lista com os nomes dos parmetros
enviados pelo browser solicitante . Por exemplo :
aInfo := HttpGet->aGets
For nI := 1 to len(aInfo)
conout('GET '+str(nI,3)+' = '+aInfo[nI])
Next
http://localhost/u_TesteGet.apw?imagem=teste&cor=azul
04. Alias virtual HttpPost
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Atravs do alias virtual HttpPost, podemos consultar os campos submetidos o servidor
atravs do mtodo POST.
Trata-se portanto de uma propriedade de leitura (read-only), disponvel apenas quando a
funo Advpl executada atravs de uma requisio http via link .apw utilizando a
configurao de Working Threads WEBEX.
Consultando um Parmetro
O retorno da consulta de um parmetro pode ter dois tipos : NIL , caso o parmetro no
tenha sido enviado , ou String , contendo o contedo do parmetro. Por exemplo, vamos
realizar uma requisio a um link .apw , atravs de um formulrio html com mtodo
POST, partindo do Html abaixo :
Teste :
Para recuperarmos em Advpl o contedo do campo CODIGO, utilizamos:
cCodigo := HttpPOST->Codigo
Existe tambm uma propriedade do alias virtual chamada aPost , onde podemos
recuperar um array de strings , contendo a lista com os nomes dos parmetros enviados
pelo browser solicitante . Por exemplo :
aInfo := HttpPost->aPost
For nI := 1 to len(aInfo)
conout('POST '+str(nI,3)+' = '+aInfo[nI])
Next
05. Alias virtual HttpHeadIn
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Atravs do alias virtual HttpHeadIn, podemos consultar os parmetros enviados pelo
Browser solicitante enviados atravs do Header HTTP ao realizar uma requisio ao
Protheus Server.
Trata-se portanto de uma propriedade de leitura (read-only), disponvel apenas quando a
funo Advpl executada atravs de uma requisio http via link .apw utilizando a
configurao de Working Threads WEBEX.
Consultando um Parmetro
O retorno da consulta de um parmetro pode ter dois tipos : NIL , caso o parmetro no
tenha sido enviado , ou String , contendo o contedo do parmetro. Por exemplo, vamos
consultar o header http User-Agent , enviado pelo Browser solicitante contendo uma
String identiificando o modelo de Browser utilizado :
cUserAgent := Httpheadin->User_Agent
Devemos obter como retorno uma string parecida com a mostra abaixo :
Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.0.3705)
Observao Importante :
Qualquer parmetro no Header HTTP que contenha um ou mais caracteres invlidos
para a nomenclatura de variveis Advpl , ( como por exemplo o User-Agent , que
contm um hfen ), so trocados pelo caractere '_' underline , para ser possvel a leitura
da propriedade.
Propriedades especiais
HttpHeadIn->aHeaders
Retorna um Array de Strings , contendo todas as linhas do Header HTTP da requisio.
HttpHeadIn->main
Retorna o nome da funo chamda atravs da URL , sem a extenso e sem o host. Por
exemplo , ao chamar o link http://localhost/u_tstHEader.apw , o contedo de
HttpHeadin->main ser 'u_tstHEader'
http://localhost/u_tstHEader.apw
HttpHeadIn->REMOTE_ADDR
Retorna uma string , no formato nnn.nnn.nnn.nnn , o IP da estao que realizou a
requisio.
httpHeadIn->REMOTE_PORT
Retorna um valor Advpl numrico , informando a porta utilizada para realizar a
requisio.
06. Alias virtual HttpHeadOut
Reviso: 08/12/2003
Abrangncia
Verso 7.10 LIB WEBEX
Atravs deste alias virtual de retorno, podemos alterar ou criar um parmetro no Header
de retorno HTTP do Protheus , a ser devolvido o Browser solicitante de uma requisio
de processamento.
Trata-se portanto de uma propriedade de retorno, disponvel apenas quando a funo
Advpl executada atravs de uma requisio http via link .apw utilizando a
configurao de Working Threads WEBEX.
A criao de uma linha no Header HTTP merece uma ateno especial, pois para que a
operao realizada com sucesso , o header deve ser criado antes de haver qualquer
processamento de APH / AHU, pois neste caso o Header de Retorno HTTP j teria sido
enviado o browser solicitante.
07. Alias virtual HttpSession
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Atravs do alias virtual httpSession, podemos criar e consultar variveis do tipo
'session', relacionadas o usurio que realizou a requisio atravs do Browser.
Para diferenciar os usurios que esto navegando num site, o Protheus busca por um
cookie identificador de usurio, retornado para o browser a cada requisio de link .
APW, chamado SESSIONID. Caso o Protheus receba este cookie, ele identifica quais
sessions pertencem a este usurio.
Quando um usurio realiza a primeira requisio http ao Protheus, o Protheus no
recebe o cookie identificador , e automaticamente inicializa um identificador de sessions
para o mesmo, retornando o identificador ao Browser via Header HTTP. Este
identificador pode ser recuperado em uma funo advpl atravs de httpSession-
>SESSIONID.
Quando criamos uma varivel de session, ela pode ser acessada nas prximas
requisies provenientes deste mesmo usurio. Caso uma varivel de session consultada
no exista, ela retorna o valor NIL (nulo). Vejamos os exemplos abaixo :
Criando variveis Session
HttpSession->UserId := '123'
HttpSession->UserName := U_GetUserName()
Nas linhas acima , criamos uma session para o usurio atual , chamada UserId , com o
contedo do tipo String, e criamos outra session chamada UserName , com o retorno da
funo U_GetUserName()
Consultando variveis Session
Ao consultar uma varivel 'session', sempre devemos prever que a mesma no pode ter
sido criada, de modo que a consulta pode retornar NIL, ou caso a session j exista ,
retornar o valor do tipo que foi atribudo `a mesma.
If HttpSession->UserId = NIL
// Session ainda no foi criada ! Usurio no est logado.
conout('Usuario no est logado')
Else
// Session j criada, o usurio est logado
conout('Usuario est logado : ID = ' + HttpSession->UserId )
Endif
Exemplo de Funcionamento de Session
No exemplo abaixo, criamos uma session para identificar quantas vezes o usurio
chamou esta funo especfica. Damos o nome da session de MyCounter, que ir conter
um nmero. No primeiro acesso do usurio, a session no existe ( = NIL ), e criada
com o valor numrico 1 (um). A partir das prximas requisies realizadas ao Protheus
atravs desta pgina ( atravs do boto 'Refresh' do Browser, por exemplo ) , a session
j existe, sendo somado o valor 1 o contedo j existente, e devolvido o browser
solicitante um Html informando quantas chamadas j foram realizadas por este usurio.
#include 'rwmake.ch'
#include 'apwebex.ch'
User Function TstSession()
Local cHtml := '' , cEcho := ''
WEB EXTENDED INIT cHtml
If httpSession->mycounter = NIL
cEcho := 'Inicializando contador'
Conout(cEcho)
cHtml += cEcho
httpSession->mycounter := 1
Else
httpSession->mycounter++
cEcho := 'contador em '+str(httpSession->mycounter,3)
conout(cEcho)
Endif
cHtml += cEcho + ''
WEB EXTENDED END
Return cHtml
Aps compilado o fonte acima e o Server Protheus configurado e iniciado com HTTP
habilitado e as working Threads configuradas, abra um Web Browser e solicite a url
http://localhost/u_tstsession.apw . Ser mostrado no Browse a mensagem 'Inicializando
Contador'. Agora , pea um 'Refresh' desta tela ao Browser : Ser devolvida a
mensagem 'Contador em 2' ... e a cada refresh deste Browser , o contador ser
incrementado.
Uso de Sessions e Paralelismo - Comportamento do Protheus Server
O Protheus Server trata s requisies simultneas de links .APW em paralelo , desde
que estejam disponveis o numero de Working Threads necessrio para tal. Por exemplo
, em uma estrutura de Frames , onde cada um deles aponta o SRC (source) para um link
http://localhost/u_tstsession.apw
.apw , o Browser envia as trs requisies de .apw para o Protheus Server , e caso
extistam 3 working threads disponveis naquele momento , as trs requisies so
atendidas em paralelo.
Por outro lado , se em duas destas trs requisies faz-se necessria a atualizao e/ou
consulta a uma varivel de Session ( httpsession ) , este processamento em paralelo ,
caso no fosse tratado , poderia gerar perdas no contedo da session caso a mesma
session fosse atualizada simultaneamente.
Para resolver esta questo, de maneira a no sobrecarregar o Servidor com solicitaes
de Processamento Sequencial ( Critical Sessions ) , foi montado um esquema de Lock
de Session de Usurio automtico, com liberao automtica aps o processamento do
APW, ou liberao manual atravs da chamada da funo HttpLeaveSession() antes do
processamento ser terminado.
Exemplificando a aplicao prtica e funcionamento deste conceito , partimos de um
ambiente hipottico utilizando 3 frames , onde um usurio realiza uma requisio
funo que retornar o source HTML da pgina de frames, e a mesma ao chegar no
Browser, faz o mesmo realizar as trs requisies simultaneamente, todas elas referentes
ao mesmo usurio. Porm , o primeiro e o segundo frames realizam uma operao
qualquer com uma ou mais variveis da Session do usurio , e o terceiro frame realiza
um outro processamento que no depende da consulta de nenhuma varivel da Session :
As trs requisies referente a este usu;ario sero processadas simultaneamente por
working Threads diferentes ( vamos supor que naquele momento haviam trs Working
Threads disponveis) ; porm quando uma das duas working Threads que tentarem
acesso uma varivel de Session daquele usurio , o Servidor verifica se alguma outra
Thread est com o flag de acesso s sessions deste usuario : Se nenhuma outra thread
em uso por este usurio est com a bandeira , ento a thread atual pega a bandeira para
ela; seno o processamento da Thread congelado no aguardo da liberao da bandeira.
A liberao da bandeira ocorre automaticamente no retorno da Working Thread para o
Browser , antes da chamada do ponto de entrada para Reset do Ambiente, atravs da
chamada na KlibEx da funo HttpLeaveSession(). Caso seja vivel para o usurio
liberar as sessions antes do retorno da funo , ele pode utilizar-se da funo
httpLeaveSession() no seu fonte , sem necessariamente aguardar pelo encerramento
efetivo e reset de ambiente da Working Thread.
Logo , retornando ao exemplo acima , os Frames 1 e 2 iro concorrer pela banceira de
atualizao de contedo de sessions, onde o primeiro frame que a ser executado pegar
a bandeira para ele e atualizar a session , e o segundo frame ir esperar o primeiro
liberar a bandeira para continuar a ser processado; e o terceiro frame , como no utiliza
nenhuma varivel da session , ser processado sem depender de nenhum dos outros dois
frames anteriores.
Quando utilizamos ASP ( Microsoft Active Server Pages ) , o mesmo realiza uma
serializao de requisies de pginas ASP por usurio, de modo que , caso o mesmo
usurio solicite trs frames .asp , as requisies de processamento chegaro ao Servidor
ASP simultaneamente , mas a bandeira de processamento unica por pgina .asp ,
sendo liberada apenas apos o trmino do processamento da pgina , de modo que ,
mesmo que nenhuma das pginas faa uso de sessions , todas as pginas deste usurio
sero processadas em sequncia.
08. Envio simultneo de HTML ao
Browser
Reviso: 30/04/2004
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
As aplicaes web desenhadas para utilizar a Infra-Estrutura APWEBEX contam com o
recurso de "Envio simultneo de Html ao Browser" durante o processamento de uma
pgina Advpl-ASP ( .APH e/ou .AHU ) .
Este recurso habilitado atravs do Protheus IDE, nas opes de configurao de
compilao do ambiente em questo; mais especificamente habilitado atravs do
CheckBox "[ ] Exibir contedo do Advpl ASP progressivamente no Browser".
Ao habilitamos esta configurao, todos os arquivos APH e AHU so parseados
fazendo internamente o uso da funo HttpSend(), de modo que mesmo antes do
processamento estar concludo , o Html gerado j est sendo enviado o Browser qoe o
solicitou.
A utilizao deste recurso prov um ganho de performance subtancial na aplicao
final. Todos os projetos desenvolvidos com esta tecnologia ( Infra-Estrutura
APWEBEX ) devem ter esta configurao de compilao habilitada no IDE. Vale
lembrar que, caso este recurso no esteja habilitado; ao habilit-lo, os arquivos .aph e
.ahu do projeto necessitam ser recompilados para que esta configurao tenha o efeito
desejado.
Pode existir a necessidade de um processamento de um APH ou AHU no enviar o
script Html gerado diretamente ao Browser. Para tal situao, podemos desabilitar
temporariamente este recurso de envio de html progressivo em tempo de execuo,
permitindo assim, por exemplo, uma funo chamar em sequncia dois arquivos APH ,
um para gerar um contedo Html a ser enviado via e-mail , armazenado em uma
varivel Advpl , e outro APH para a montagem de uma tela de status, que ser enviada
o Browser solicitante.
Para habilitar e/ou desabilitar o envio simultneo do Script HTML o browser em
tempo de execuo, utilize a funo HttpSetPart()
09. Configuraes especficas APWEBEX
Reviso: 26/04/2004
Abrangncia
Verso 7.10 Verso 8.11
Ao utilizarmos as funes de Infra-estrutura APWEBEX, existem recursos da lib que
exigem uma configurao adicional para serem utilizados.
Envio de e-mail automtico atravs da Rotina de Tratamento de Erro do Site
Em caso de erro fatal na aplicao Web, a prpria rotina de tratamento de erro pode ser
configurada para enviar um e-mail o Administrador do sistema. Para tal, necessrio
inserir as chaves abaixo na seo do ambiente em uso para o site :
ErrorSMTP= (endereo do servidor SMTP a ser usado para o envio do e-mail )
ErrorMail= ( um ou mais endereos de e-mail a receber op e-mail de erro, separados por
virgula )
ErrorFrom= ( um e apenas um endereo de e-mail a ser usado como remetente do aviso
de erro )
ErrorLogin = ( nome de usuario de login no servidor de SMTP, caso necessrio )
ErrorPassword= ( senha do usuario de login no servidor de SMTP, caso necessrio )
WebAdmin - Login alternativo
A infra-estrutura APWEBEX exige um usurio e senha para entrar no mdulo de
administrao WebAdmin. Para validar o login, utilizado o arquivo de senhas do ERP.
O usurio deve ser o 'Administrador' ou pertencer ao grupo de administradores para ter
acesso o WebAdmin. Caso no seja vivel usar este arquivo de senhas para validar o
login, podemos inserir uma chave adicional ( AdmLogin ) no Environment em uso pela
aplicao Web, e configurar nela a senha do usurio 'Administrador' para login no
WebAdmin. Caso esta chave seja configurada, o arquivo de senhas do ERP no ser
utilizado para validar o login no WebAdmin.
AdmLogin= ( senha do Administrador para logar no WebAdmin )
Pasta alternativa para upload de Rpo via WebAdmin
No WebAdmin , possvel utilizar uma configurao especfica para a troca do
repositrio de objetos em uso no site, sem que seja necessrio parar o servidor para isso.
Por default , a pasta de upload chama-se '\SwapRPO\', e deve existir na estrutura
de diretrio do ambiente utilizado, a partir do diretrio raiz do ambiente ( RootPath ).
RpoUpload= ( pasta de upload alternativa, a partir do RootPath do ambiente )
10. Recomendaes finais
Reviso: 17/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Para todo o desenvolvimento de solues, temos em mos uma diversidade de recursos,
desenhados para melhor atender s necessidades e adequar-se s caracteristicas da
aplicao. Dada a flexibilidade dos recursos, recomenda-se aos desenvolvedores
adotarem um padro de desenvolvimento e ter em foco a eficincia da aplicao final,
tanto no aspecto funcional como na codificao .
Lanando mo da experincia em desenvolvimento de aplicaes web adquiridas nos
ltimos anos, nos tpicos abaixo esto relacionadas algumas medidas tomadas no
desenvolvimento de aplicaes que nos so muito teis no decorrer de um projeto.
Nomenclatura de Funes
Para o desenvolvimento de aplicaes web, foi criado o 'Statement' WEB FUNCTION
para a declarao de funes referentes projetos web. Este comando , na prtica ,
apenas prefixa a declarao da funo com W_ , porm a sua utilizao identifica que a
funo em questo foi construda nica e exclusivamente para ser chamada a partir de
uma requisio HTTP . Em adendo este, devemos utilizar os comandos WEB
EXTENDED INIT ... END , disponivels no Include 'apwebex.ch' , para proteger a
funo de ser chamada em um ambiente que no o APWEBEX.
Separando a Interface do Processamento
Ao desenvolver utilizando Advpl ASP , pginas APH / AHU, recomenda-se separar o
processamento da Interface, do seguinte modo : Criar uma Web Function para a
chamdada de umna pgina com contedo dinmico via link .apw , e um arquivo .APH
ou .AHU de mesmo nome , que ser chamado internamente , de modo que o cdigo-
fonte escrito na Web Function seja responsvel para gerar as informaes a serem
disponibilizadas para o usurio , e o .APH contenha apenas a 'mscara' destas
informaes e o mnimo de instrues Advpl possvel para a montagem da pgina. Este
processo facilita a manuteno de amobos os cdigos, pois o Web Designer que ir
realizar um ajuste no APH no ter que 'desviar' do fonte Advpl inserido na pgina , e o
Analista / Programador que far a manuteno no cdigo Advpl preocupar-se- apenas
com o cdigo responsvel para a gerao dos dados que sero mascarados.
Utilizao das Funes de Infra-Estrutura
Atravs dos comandos e funes disponibilizadas na Infra-Estrutura APWEBEX, no
tmos a necessidade de recriar partes comuns de cdigo para todos os projetos que se
utilizem desta tecnologia, alm de permitir atravs de pontos de entrada
estrategicamente colocados na ferramenta um nvel altssimo de customizao para os
projetos desenvolvidos com esta tecnologia, de maneira prtica e objetiva.
11. Monitoramento de Sites em WEBEX
Reviso: 17/12/2003
Abrangncia
LIB WEBEX
O Objetivo de uma funo de Monitoramento de Sites testar as funcionalidades
bsicas de um site, retornando uma mensagem HTML pr-definida , indicando que est
tudo certo , e em caso de erro , uma mensagem que procure identificar o que est de
errado.
Para sites desenvolvidos em Protheus , utilizando a tecnologia WEBEX , devemos
criar uma funo especfica para o site , que ir determinar se o mesmo est operacional
. Esta funo ser chamada atravs de link .apw
Vejamos o exemplo abaixo, escrito para um site cujas bases de dados esto num SQL ,
acessadas via TopConnect. Neste exemplo , a funo chamada ser
http://servidor/U_SiteMonitor.apw , e caso esteja tudo certo , ela retornar a string
'(SITE OK)' , seguido da data e horrio da execuo da rotina. Qualquer retorno
diferente disto poder indicar uma anomalia no funcionamento do site.
Quando hospedado um site utilizando esta tecnologia no DataCenter da Makira , esta
informao gerada pela rotina deve ser passada o depto de infra-estrutura, que
configurar um software 'Monitor de Sites', que ir realizar a cada um minuto uma
requisio url especificada , e ir emitir um alerta ao Departamento para que seja
verificado o site caso haja alguma falha na resposta.
#include "protheus.ch"
#include "apwebex.ch"
User Function SiteMonitor()
Local cQuery , nQtdRec
// Verifica se a working Thread est conectada com o TOP ...
If !TCIsConnected()
Return 'Working Thread perdeu a conexo com o TOP'
Endif
// Verifica se as tabelas principais esto abertas ....
If select('SA1')=0
Return 'Tabela SA1 no est aberta !!!'
Endif
If select('SC5')=0
Return 'Tabela SC5 no est aberta !!!'
Endif
http://servidor/U_SiteMonitor.apw
// Executa uma query de contagem de registros de uma tabela do sistema
cQuery := 'SELECT count(*) as QTDREC from SA1010'
OPEN QUERY cQuery ALIAS 'TMPCOUNT'
nQtdRec := TMPCOUNT->QTDREC
CLOSE QUERY 'TMPCOUNT'
If nQtdRec=0
Return 'Falha na Contagem de registros / Query SA1'
Endif
// Se est tudo certo , retorna um HTML informando que est tudo OK
Return '(SITE OK) '+dtos(date())+' '+time()
Comandos - CLOSE QUERY
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Sintaxe
CLOSE QUERY cAlias
Parmetros
Argumento Tipo Descrio
cAlias Caracter
Alias sob o qual o cursor da Query foi aberto. Caso o alias
passado como parmetro no se encontre aberto , a funo
no gera nenhuma ocorrncia de erro.
Descrio
Atravs do comando Close Query , realizamos o fechamento de uma query aberta
atravs do comando OPEN QUERY.
ATENO : Uma query aberta pelo comando OPEN QUERY deve ser fechada
pelo comando CLOSE QUERY . Poderamos fechar o alias aberto atravs de uma
Query simplesmente com a funo DbCloseArea(), porm isto deixaria em aberto
elementos internos de controle criados pelo comando OPEN QUERY.
Comandos - OPEN QUERY
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Sintaxe
OPEN QUERY ALIAS [ [NOCHANGE] ]
Parmetros
Argumento Tipo Descrio
Caracter cQuery corresponde String contendo a Query a ser
executada no banco de dados
ALIAS Caracter
cAlias corresponde ao nome do alias sob o qual o cursor
de retorno dos dados pesquisados ser aberto no ambiente
Advpl. No pode ser especificado um nome de alias j em
uso, seno a aplicao ser finalizada com a ocorrncia de
erro "Alias already in Use"
[NOCHANGE] Caracter
Caso especificada a clusola NOCHANGE na abertura da
query , a string em cQuery no ser submetida funo
ChangeQuery()
Descrio
Atravs do comando OPEN QUERY , realizamos a abertura de uma Query de busca no
Banco de Dados atravs do RDD TOPCONN , retornando os dados consultados atravs
de um 'ALIAS' Advpl.
Caso a Query nao possa ser aberta, por erro de sintaxe , devido thread atual no estar
conectada com o TopConnect , ou outro erro , ser gerado um log de erro , informando
o Alias , o Stack ( Pilha de Chamadas ) de execuco , e o contedo da Query para
Debug.
OBSERVAES IMPORTANTES
Na montagem da string da Query , devemos especificar os comandos SQL , alias
e nomes de campos em letras maisculas.
Quando utilizamos o comando OPEN QUERY , no precisamos passar a
expresso da Query atravs da funo ChangeQuery(). Este proceduimento j
realizado internamente pelo comando OPEN QUERY. Para que a query no seja
submetida funo ChangeQuery(), devemos utilizar o parmetro
NOCHANGE.
A utilizao deste comando implcita LIB APWEBEX , e necessita da
utilizao do #include 'Apwebex.ch'
Comandos - WEB EXTENDED END
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Sintaxe
WEB EXTENDED END [ START ]
Parmetros
Argumento Tipo Descrio
Caracter
cHtml corresponde variavel que ser utilizada para
armazenar a String Html que ser retornada ao Browser
solicitante do processamento. Deve ser especificada uma
varivel String , com contedo vazio. ("")
START
Caracter
cFnStart corresponde o nome de uma funo Advpl que
ser executada para pr-validar a execuo do resto do
cdigo. A funo deve ser passada SEM parnteses () .
Descrio
Devemos utilizar este comando para fechar uma seo aberta pelo comando WEB
EXTENDED INIT . Para cada ocorrncia do comando WEB EXTENDED INIT , deve-
se ter um fechamento da mesma atravs do comando WEB EXTENDED END ,
devendo haver apenas uma ocorrncia desta estrutura por funo.
A utilizao deste comando implicita Working Threads inicializadas pela Lib
APWEBEX , e a definio do mesmo est no arquivo #include 'apwebex.ch' , que deve
ser declarado no incio do arquivo fonte Advpl.
Comandos - WEB EXTENDED INIT
Reviso: 08/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Sintaxe
WEB EXTENDED INIT [ START ]
Parmetros
Argumento Tipo Descrio
Caracter
cHtml corresponde variavel que ser utilizada para
armazenar a String Html que ser retornada ao Browser
solicitante do processamento. Deve ser especificada uma
varivel String , com contedo vazio. ("")
START
Caracter
cFnStart corresponde o nome de uma funo Advpl que
ser executada para pr-validar a execuo do resto do
cdigo. A funo deve ser passada SEM parnteses () .
Descrio
Devemos utilizar este comando , juntamente com o comando WEB EXTENDED END
quando montamos uma funco ( Web Function ) que foi construda para ser chamada a
partir de um Web Browser , quando nos utilizamos das funes de Infra-Estrutura
APWEBEX.
Atravs dele , realizada uma pr-validao que certifica que a execuo da funo
somente ser realizada caso a thread atual seja realmente uma Thread montada no
ambiente WEBEX, alm de podermos inserir uma pr-validao (START) de execuo
especfica para esta funo.
Caso seja especificada uma funo na clusula START, a mesma dever retornar uma
String. Retornando uma String em branco , o processamento da funo original ser
efetuado normalmente . Caso a funo retorne uma string no-vazia , esta string ser
retornada para a varivel cHtml , e o processamento do programa ser desviado para a
linha do cdigo-fonte imediatamente posterior o comando WEB EXTENDED END .
Para cada ocorrncia do comando WEB EXTENDED INIT , deve-se ter um fechamento
da mesma atravs do comando WEB EXTENDED END , devendo haver apenas uma
ocorrncia desta estrutura por funo.
A utilizao deste comando implicita Working Threads inicializadas pela Lib
APWEBEX , e a definio do mesmo est no arquivo #include 'apwebex.ch' , que deve
ser declarado no incio do arquivo fonte Advpl.
Infra-Estrutura APWEBEX - EnvUser.APL -
Exemplo de Uso com ERP
Reviso: 16/12/2003
Abrangncia
Verso 7.10 Verso 8.11 LIB WEBEX
Atravs do exemplo prtico abaixo , utilizamos em um cdigo fonte Advpl os pontos de
entrada disponibilizados na Infra-Estrutura APWEBEX para realizar a preparao de
um ambiente E