Você está na página 1de 141

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 InfraEstrutura 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 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 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 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, podese 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):
<% 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, e seu resultado inserido como
parte do Html retornado o Browse :
<b>Esta linha HTML, mas o horrio exibido aqui: <%= Time() %> foi obtido em tempo
de execuo no Servidor.</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 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
<%
IF !lOk
nErro++
Endif
%>

CERTO
<% IF !lOk %>
<% nErro++ %>
<% Endif %>

CERTO
<% IF !lOk

; nErro++ ; Endif %>

ERRADO
<% IF !lOk %><% nErro++ %> -- 2 aberturas e fechamentos na mesma linha
<% Endif %>

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

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 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 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, podese 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):
<% 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, e seu resultado inserido como
parte do Html retornado o Browse :
<b>Esta linha HTML, mas o horrio exibido aqui: <%= Time() %> foi obtido em tempo
de execuo no Servidor.</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 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
<%
IF !lOk
nErro++
Endif
%>

CERTO

<% IF !lOk %>


<% nErro++ %>
<% Endif %>

CERTO

<% IF !lOk

; nErro++ ; Endif %>

ERRADO
<% IF !lOk %><% nErro++ %> -- 2 aberturas e fechamentos na mesma linha
<% Endif %>

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 prcompilao . 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 podese 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:

__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).
o

__nProcID: Contm o Handle da Thread de execuo daquela funo. A


utilizao deste parmetro ser explicada juntamente com o tpico ADVPL
ASP posteriormente;

__aProcParms: Este parmetro recebe um array bidimensional com os


parmetros enviados na linha de URL do Web Browser. Por exemplo, na
execuo de uma funo via linha de URL do Web Browser como:
http://servidor/vende.apl?cod=000001&nome=PRODUTO DE
TESTE&quant=20
a funo chamada vende receber o array __aProcParms da seguinte forma:
{ {cod, 000001},
{nome, PRODUTO DE TESTE},
{quant, 20} }
A funo pode tratar estes dados recebidos para realizar processamentos
especficos. muito til tambm para criar links de execuo diretamente
atravs de um Web Browser.

__cHTTPPage: Esse parmetro 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.

__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 += '<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)

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
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.
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 .. )
<hr>
Ola Mundo HTTP
<hr>
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
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=<nome_do_ambiente> , 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 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
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
[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

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 :
<html><body>
<form method='POST' action='http://localhost/u_TstPost.apw'>
Teste : <input type='text' name='CODIGO' size='10'>
<hr>
<input type='submit'>
</form>
</body></html>
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'
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 + '<hr>'
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 .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
// 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

Alias sob o qual o cursor da Query foi aberto. Caso o alias


Caracter 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 <cQuery> ALIAS <cAlias> [ [NOCHANGE] ]
Parmetros
Argumento

Tipo

Descrio

<cQuery>

Caracter

cQuery corresponde String contendo a Query a ser


executada no banco de dados

ALIAS <cAlias>

cAlias corresponde ao nome do alias sob o qual o cursor de


retorno dos dados pesquisados ser aberto no ambiente
Caracter 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]

Caso especificada a clusola NOCHANGE na abertura da


Caracter 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 <cHtml> [ START <cFnStart> ]
Parmetros
Argumento

Tipo

Descrio

<cHtml>

cHtml corresponde variavel que ser utilizada para


armazenar a String Html que ser retornada ao Browser
Caracter
solicitante do processamento. Deve ser especificada uma
varivel String , com contedo vazio. ("")

cFnStart corresponde o nome de uma funo Advpl que


START <cFnStart> Caracter 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 <cHtml> [ START <cFnStart> ]
Parmetros
Argumento

Tipo

Descrio

<cHtml>

cHtml corresponde variavel que ser utilizada para


armazenar a String Html que ser retornada ao Browser
Caracter
solicitante do processamento. Deve ser especificada uma
varivel String , com contedo vazio. ("")

cFnStart corresponde o nome de uma funo Advpl que


START <cFnStart> Caracter 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 ERP , Reset de Ambiente , finalizao de Thread, finalizao de sessions por
time-out e customizao de mensagem de erro para o desenvolvimento de um projeto de
Web Site integrado com o ERP Microsiga.
Devemos adotar como padro para projetos que utilizam APWEBEX a criao do
arquivo "EnvUser.apl", especificamente para a definio dos pontos de entrada
utilizados pela Infra-Estrutura APWEBEX; e devemos apenas compilar os fontes dos
pontos de entrada realmente necessrios o projeto.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "APWEBEX.CH"
/*
=========================================================================
===========
Exemplo de Arquivo de Lib de Projeto APWEBEX , utilizando os pontos de
entrada
da lib para preparao de ambiente , reset de ambiente e tratamento de
erro
utilizando APWEBEX em conjunto com o ERP Microsiga
=========================================================================
=========== */
/*
--------------------------------------------------------------------------Ponto de Entrada StartWebEx( NIL ) => .T. ou .F.
Ponto de entrada executado na inicializao de cada Working Thread
( ONSTART )
a responsvel por preparar o ambiente para atender s requisies WEB
de links .apw
No recebe parmetro algum da lib , e deve retornar .T. caso tenha
inicialziado com sucesso
ou .F. em caso de falha de inicializao .
--------------------------------------------------------------------------- */
USER Function StartWebEx()

// Prepara o Ambiente ERP


PREPARE ENVIRONMENT ;
EMPRESA '01' ;
FILIAL '01'
;
TABLES "ZX1","ZX2","ZX3","ZX4","ZZ1","ZZ2","ZZ3","ZZ4","ZZ5"
Return .T.
/*
-----------------------------------------------------------------------------Ponto de Entrada ConnectWebEx(cFnName) => cHtml ou ""
Ponto de entrada executado imediatamente antes do processamento de uma
requisio de um link .APW
Recebe como parmetro o nome da funo a ser executada, passada no link.
Deve retornar uma String, que ser retornada ao ao Browser solicitante.
Caso retorne uma string
em branco (vazia) , a funo originalmente solicitada executada pela
lib.
Caso contrrio, a funo original no executada , e a string retornada
enviada ao Browser.
------------------------------------------------------------------------------ */
USER Function ConnectWebEx(cFnName)
Local cHtmlConn := ''
conout('Vou executar '+cFnName)
Return cHtmlConn
/*
-----------------------------------------------------------------------------Ponto de Entrada ResetWebEx(cFnName) => cHtml ou ""
Funo chamada imediatamente Apos a execuo de uma requisio .APW
Recebe como parmetro o nome da funo executada, e permite tambm que
seja acrescentado
algo a mais no Html a ser retornado ao Browser.
------------------------------------------------------------------------------ */
USER Function ResetWebEx(cFnName)
Local cHtmlConn := ''
conout('Terminei de executar '+cFnName)
Return cHtmlConn
/*
-----------------------------------------------------------------------------Ponto de Entrada FINISHWEBEX()
Funo chamada no fechamendo do ambiente de uma working Thread. Apos a
execuo deste ,
a Thread utilizada eliminada da memria .
------------------------------------------------------------------------------ */
USER Function FINISHWEBEX()
conout('Finalizando a Working Thread.')
Return

/*
-----------------------------------------------------------------------------Ponto de Entrada ENDSESSION(cSessionId) => NIL
Ponto de entrada chamado em uma working Thread quando a session de um
usurio ser
eliminada da memria por time-out. Recebe como parametro o Id de
sessions de usuario
que est sendo finalizado.
------------------------------------------------------------------------------ */
USER Function ENDSESSION(cSessionId)
Conout("Sesssion "+cSessionId+" limpa da memria...")
Return
/*
--------------------------------------------------------------------------Ponto de Entrada WebExError(e,cErrorLog,cHtml) => cCustomHtml ou ""
Esta funcao chamada pela rotina de tratamento de erro WEBEX , quando
ocorre um erro fatal ,
e permite que seja retornado um Html de tratamento de erro diferenciado.
Ela recebe como
parametro o objeto do erro , a mensagem ASCII que foi acrescentada ao
arquivo error.log ,
e o Html original montado pela rotina de tratamento de erro default .
IMPORTANTE : Por sem um ponto de entrada executado em um momento crtico
(tratamento
de erro ) , esta funo deve ser o mais suscinta e simples possvel , no
utilizando
sessions, banco de dados , etc....
--------------------------------------------------------------------------- */
USER Function WebExError(oError,cErrorLog,cHtml)
Local cCustomHtml := ''
// Monta mensagem de erro mais amigavel ...
cCustomHtml += ''
cCustomHtml += ''
cCustomHtml += ''
cCustomHtml += ''
cCustomHtml += ''
cCustomHtml += '
'
cCustomHtml += '
Ocorreu um erro inesperado no '
cCustomHtml += 'processamento desta pgina. O Administrador do sistema ser
notificado desta '
cCustomHtml += 'ocorrncia . Recomendamos fortemente que esta janela do
navegador seja '
cCustomHtml += 'fechada, e uma nova janela seja aberta para retornar navegao
do site.

'
cCustomHtml += '
'
cCustomHtml += '
'
cCustomHtml += ''
cCustomHtml += ''
Return cCustomHtml

Infra-Estrutura APWEBEX - Exemplo da


funo ESCAPE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Nos exemplo abaixo, utilizamos a funo escape() para formatar parmetros para inserir em
uma URL.
cUrl := 'http://localhost/webinfo.apw'
cPAram1 := 'Teste de Parametro 01-02'
cPAram2 := '#reserva#'
cPAram3 := '1+2+3'
cUrl += '?Par01=' + escape(cPAram1) + '&PAr02=' + escape(cPAram2) +
'&Par03=' + escape(cPAram3)
// O conteudo de cUrl dever ser "http://localhost/webinfo.apw?
Par01=Teste%20de%20Parametro%2001-02&PAr02=%23reserva%23&Par03=1%2B2%2B3"
, prprio para a monyahem de um link .

Infra-Estrutura APWEBEX - Exemplo da


funo GETJOBPROFSTRING
Reviso: 08/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

O exemplo abaixo , executado em uma thread iniciada a partir de um JOB WEBEX,


recupera algumas configuraes atuais em uso para este JOB.
cJobType
cInstances
cInacTime
cExpTime

:=
:=
:=
:=

GetJobProfString('type','(empty)' )
GetJobProfString('Instances','(empty)' )
GetJobProfString(InactiveTimeout','(default)' )
GetJobProfString('ExpirationTime','(default)' )

Infra-Estrutura APWEBEX - Exemplo da


funo GETPARVALUE
Reviso: 08/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

No exemplo abaixo , so montados dois arrays multi-dimensionais , com 2 dimenses , e


so realizadas buscas nos mesmos explorando todas as possibilidades de uso da funo
GetParValue()
Local aTeste1 := {}
Local aTeste2 := {}
Aadd(aTeste1,{"Alias","TMP1"})
Aadd(aTeste1,{"Relacao","2x3"})
Aadd(aTeste2,{"Alias","TMP2"})
Aadd(aTeste2,{"Info","---Informao adicional---"})
// Busca apenas no array ateste1
cAlias := GetParValue("ALIAS",aTeste1)
cRelacao := GetParValue("RELACAO",aTeste1)
cInfo := GetParValue("INFO",aTeste1)
DEFAULT cAlias := "(nao encontrado)"
DEFAULT cRelacao := "(nao encontrado)"
DEFAULT cInfo := "(nao encontrado)"
conout(cAlias) // TMP1
conout(cRelacao) // 2x3
conout(cInfo) // (nao encontrado)
// Busca apenas no array ateste2
cAlias := GetParValue("ALIAS",aTeste2)
cRelacao := GetParValue("RELACAO",aTeste2)
cInfo := GetParValue("INFO",aTeste2)
DEFAULT cAlias := "(nao encontrado)"
DEFAULT cRelacao := "(nao encontrado)"
DEFAULT cInfo := "(nao encontrado)"
conout(cAlias) // TMP2
conout(cRelacao) // (nao encontrado)
conout(cInfo) // ---Informao Adicional--// Busca em ambos os Arrays
// Primeiro no aTeste1 e depois no aTeste2
cAlias := GetParValue("ALIAS",aTeste1,aTeste2)
cRelacao := GetParValue("RELACAO",aTeste1,aTeste2)
cInfo := GetParValue("INFO",aTeste1,aTeste2)
conout(cAlias) // TMP1
conout(cRelacao) // 2x3
conout(cInfo) // ---Informao Adicional---

Infra-Estrutura APWEBEX - Exemplo da


funo HEXSTRDUMP
Reviso: 15/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Atravs do exemplo abaixo, geramos a string com o DUMP de um arquivo HTML, salvo na
pasta WEB a partir do RootPath do Environment. O Dump do arquivo ser mostrado no
Console do servidor e no Web Browser que solicitou a funo U_DumpTest.apw .
#include "protheus.ch"
#include "apwebex.ch"
User Function DumpTest()
Local cHtml := ''
Local cTXTFile := ''
Local cDump := ''
WEB EXTENDED INIT cHtml
// Le o arquivo
cTTXFile := memoread('\Web\Default.htm')
// Gera a string com o Dump do arquivo
cDump := HExStrDump(cTTXFile)
// Mostra o Dump no console
conout(cDump)
// Gera HTML para a visualizao do DUMP
cHtml := VarInfo('DUMP',Htmlnotags(cDump),,.t.,.f.)
WEB EXTENDED END
Return cHtml

/*
Exemplo do Texto mostrado no Console
HexSTRDump ( String 237 / Start 1 / Length 237 )
-----------------------------------------------------------------------------3C 48 54 4D 4C 3E 3C 48 45 41 44 3E 0D 0A 3C 4D | <HTML><HEAD>__<M
45 54 41 20 48 54 54 50 2D 45 51 55 49 56 3D 22 | ETA HTTP-EQUIV="
43 6F 6E 74 65 6E 74 2D 54 79 70 65 22 20 63 6F | Content-Type" co
6E 74 65 6E 74 3D 22 74 65 78 74 2F 68 74 6D 6C | ntent="text/html
22 0D 0A 3C 4D 45 54 41 20 48 54 54 50 2D 45 51 | "__<META HTTP-EQ
55 49 56 3D 22 70 72 61 67 6D 61 22 20 63 6F 6E | UIV="pragma" con
74 65 6E 74 3D 22 6E 6F 2D 63 61 63 68 65 22 3E | tent="no-cache">
0D 0A 3C 4D 45 54 41 20 48 54 54 50 2D 45 51 55 | __<META HTTP-EQU
49 56 3D 22 45 78 70 69 72 65 73 22 20 63 6F 6E | IV="Expires" con
74 65 6E 74 3D 22 2D 31 22 3E 0D 0A 3C 4D 45 54 | tent="-1">__<MET
41 20 48 54 54 50 2D 45 51 55 49 56 3D 22 52 65 | A HTTP-EQUIV="Re
66 72 65 73 68 22 20 63 6F 6E 74 65 6E 74 3D 22 | fresh" content="
30 3B 20 75 72 6C 3D 2F 77 5F 77 45 78 30 30 30 | 0; url=/w_wEx000
2E 61 70 77 22 3E 3C 2F 48 45 41 44 3E 0D 0A 3C | .apw"></HEAD>__<
2F 48 45 41 44 3E 3C 2F 48 54 4D 4C 3E
| /HEAD></HTML>
-----------------------------------------------------------------------------*/

Infra-Estrutura APWEBEX - Exemplo da


funo HTMLNOTAGS
Reviso: 08/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

No exemplo abaixo , a funo HtmlNoTags utilizada para permitir a utilizao de


caracteres especiais no contedo de um input para um formulrio Html.
Local cHtml := ""
Local cInput := ""
// Conteudo do campo com tags HTML intepretveis
cInput := ''
// Ao montar o Input , aplicar a HtmlNoTags() ao conteudo do mesmo.
cHtml += '

'+HtmlNoTags(

'

Infra-Estrutura APWEBEX - Exemplo da


funo REDIRPAGE
Reviso: 10/12/2003
Nos exemplos abaixo, a funo redirpage utilizada para gerar o script de
redirecionamento em duas situaes especficas.
/*
Em uma determinada funo , caso um parmetro no seja passado , o
usurio dever retornar a uma outra tela
*/
...
If empty(httpget->meuparam)
// Parmetro no informado , volta pro login
cHtml := RedirPage('/W_Login.apw')
Else
// Parametro Ok , executa o APH formteste
cHtml := ExecInpage('FormTeste')
Endif
...
/* Ao chamar uma tela de download , mostrar uma mensahem e iniciar um
download automaticamente */
...
cHtml += '
...mensagem de download...
'
// Devolve script de redirecionamento apontando para o arquivo
// com o target _blank , para ser aberto em uma nova janela.
cHtml += RedirPage('/downloads/arquivo.zip','_blank')
...

Infra-Estrutura APWEBEX - Exemplo da


funo REDIRPAGE
Reviso: 10/12/2003
Nos exemplos abaixo, a funo redirpage utilizada para gerar o script de
redirecionamento em duas situaes especficas.
/*
Em uma determinada funo , caso um parmetro no seja passado , o
usurio dever retornar a uma outra tela
*/
...
If empty(httpget->meuparam)
// Parmetro no informado , volta pro login
cHtml := RedirPage('/W_Login.apw')
Else
// Parametro Ok , executa o APH formteste
cHtml := ExecInpage('FormTeste')
Endif
...
/* Ao chamar uma tela de download , mostrar uma mensahem e iniciar um
download automaticamente */
...
cHtml += '
...mensagem de download...
'
// Devolve script de redirecionamento apontando para o arquivo
// com o target _blank , para ser aberto em uma nova janela.
cHtml += RedirPage('/downloads/arquivo.zip','_blank')
...

Infra-Estrutura APWEBEX - Exemplo da


funo RETSQLACE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

No exemplo abaixo , utilizamos a funo RetSqlAce para montar uma query de busca por
ttulo de uma determinada informao , considerando todas as possibilidades de acentuao
, independentemente de como o banco foi alimentado e/ou a string de busca foi digitada.
IMPORTANTE : Na expresso da Query , o campo da tabela deve ser passado pela funo
LOWER do BAnco , pois a funo retsqlace monta a string para busca com letras
minsculas.
cFind := 'acentuao'
cQuery := "SELECT * FROM " + RetSqlTab('ZZ1')
cQuery += "WHERE LOWER(ZZ1_TITULO) LIKE '%"+RetSqlAce(cFind)+"%'

"

Infra-Estrutura APWEBEX - Exemplo da


funo VALTOSQL
Reviso: 08/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

cQuery := "SELECT * FROM FA2010 "


cQuery += "WHERE FA2_FILIAL = " + ValToSql('02')
cQuery += "AND FA2_DTINC <= " + ValToSql(date())
O exemplo acima , caso escrito de forma a realizar as converses
especficas para cada tipo de contedo seria o equivalemte ao cdigo
abaixo :
cQuery := "SELECT * FROM FA2010 "
cQuery += "WHERE FA2_FILIAL = '02' "
cQuery += "AND FA2_DTINC <= " + DTOS( date() )

Infra-Estrutura APWEBEX - Exemplo da


funo VARINFO
Reviso: 08/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

No exemplo abaixo , gerada uma string HTML com as informaes do retorno da


chamada de duas funes bsicas da Linguagem Advpl.
User Function InfoTeste()
Local cHtml := ''
cHtml += VarInfo(Date,date())
cHtml += VarInfo(Time,time())
Return cHtml
/* Deve ser gerado um echo no Console do Servidor parecido com este
abaixo
Date -> D (

10) [08/12/2003]

Time -> C (
*/

8) [20:17:48]

Infra-Estrutura APWEBEX - Exemplo das


funes de acentuao ApWebEX
Reviso: 08/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

No exemplo abaixo, vemos a diferena de comportamento entre as funes bsicas da


Linguagem Advpl Upper() e Lower() , e a funo de Infra-estrutura Capital(), em relao
s funes da Infra-estrutura APWEBEX UpperAce() , LowerAce() e CApitalAce() ,
quando utilizamos caracteres acentuados.
cRetorno := ""
cFrase
:= "no h EXPLICAES considerando excesses PARA O
inexplicvel."
cRetorno
cRetorno
cRetorno
cRetorno
cRetorno
cRetorno
cRetorno

+=
+=
+=
+=
+=
+=
+=

"Original ..........
"Upper() ...........
"Lower() ...........
"Capital() .........
"UPPERACE() ........
"LOWERACE() ........
"CAPITALACE() ......

"
"
"
"
"
"
"

+
+
+
+
+
+
+

cFrase + CRLF
upper(cFrase) + CRLF
lower(cFrase) + CRLF
capital(cFrase) + CRLF
UPPERACE(cFrase) + CRLF
LOWERACE(cFrase) + CRLF
CAPITALACE(cFrase) + CRLF

/*
Neste ponto , a varivel cRetorno dever conter :
Original .......... no h EXPLICAES considerando excesses PARA O
inexplicvel.
Upper() ........... NO H EXPLICAES CONSIDERANDO EXCESSES PARA O
INEXPLICVEL.
Lower() ........... no h explicaes considerando excesses para o
inexplicvel.
Capital() ......... No H Explicaes Considerando Excesses Para O
Inexplicvel.
UPPERACE() ........ NO H EXPLICAES CONSIDERANDO EXCESSES PARA O
INEXPLICVEL.
LOWERACE() ........ no h explicaes considerando excesses para o
inexplicvel.
CAPITALACE() ...... No H Explicaes Considerando Excesses Para O
Inexplicvel.
*/

Infra-Estrutura APWEBEX - Exemplos das


funes NTOC e CTON
Reviso: 16/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

No exemplo abaixo , utilizamos as funes cton e ntoc para realizar converses de nmeros
em base decimal para outras bases numricas e vice-versa.
nNum1 :=
nNum2 :=

CTON('01101001',2)
CTON('00DA25FE',16)

// Converte binrio para decimal


// Converte Hexadecimal para decimal

nNum1++ // Soma 1 ao numero em nNum1


nNum2++ // Soma 1 ao numero em nNum2
cNum1 := NtoC(nNum1,2,8)
cNum2 := NtoC(nNum2,16,8)

// Converte para binrio novamente


// Converte para Hexa novamente

/*
------------------------------------------------------------------------Ao final do programa , cNum1 ser "01101010" e cNum2 ser "00DA25FF"
------------------------------------------------------------------------*/

APWEXADDERR
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
APWEXADDERR ( [ cTitulo ] , [ cInfo ] ) --> .T.
Parmetros
Argumento

Tipo

Descrio

cTitulo

cTitulo corresponde a um ttulo identificador da


Caracter informao. Deve ter no mximo 20 caracteres. Os
caracteres acima da vigsima posio sero ignorados.

cInfo

Caracter

cInfo corresponde Informao a ser acrescentada ao


ERROR.LOG em caso de erro.

Retorno
Tipo

Descrio

Lgico

Esta funo sempre retorna .T.

Descrio
Atravs da funo ApWExAddErr(), podemos acrescentar uma string de informaes
adicionais em um buffer em memria, descarregado na gerao do ERROR.LOG no caso
de uma ocorrncia de erro fatal na working thread atual.
Caso a funo seja chamada sem nenhum parmetro, a ltima ocorrncia acrescentada pela
funo eliminada da pilha interna de informaes.
ATENO : Esta funo deve ser apenas utilizada em casos de necessidade de obteno de
informaes especficas acerca de uma ocorrncia de erro no reproduzida em ambiente de
testes e/ou no depurvel, pois seu uso desnecessrio prejudica a performance da aplicao
final.

CAPITALACE
Reviso: 08/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
CAPITALACE ( < cString > ) --> cStrCapital
Parmetros
Argumento

Tipo

Descrio

cString

Caracter String a ser convertida.

Retorno
Tipo

Descrio

Caracter

String resultante convertida para munsculo , com as primeiras letras das


palavras significantes em maisculo.

Descrio
Semelhante funo de Infra-estrutura Capital() , porm converte tambm caracteres
acentuados.
A funo CapitalAce() converte todos os caracteres de uma String para 'minsculo' , e a
primeira letra das palavras significantes para maisculo, semelhante funo Capital() ,
porm considera e converte tambm caracteres acentuados em OEM e/ou ANSI.

CTON
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
CTON ( < cString > , < nBase > ) --> nNumero
Parmetros
Argumento

Tipo

Descrio

cString

Caracter

cString corresponde representao de um nmero em


outra base numrica, compreendida entre 2 e 36.

nBase

Numrico

nBase corresponde base numrica utilizada pelo numero


representado em cString.

Retorno
Tipo

Descrio

Numrico

Nmero recebido como parmetro em notao decimal ( Base 10 )

Descrio
Converte um nmero representado em String , de base 2 a 36 , para um nmero em base
decimal (10).
Observao Importante :
So considerados caracteres vlidos para compor um nmero de base 36 os 10 algarismos
numricos de 0 a 9 e os 26 caracteres alfabticos maisculos compreendidos entre A e Z.
Quaisquer caractetes presentes na String de parmetro fora desta faixa de dados e/ou fora
da base ( por exemplo , uma converso de string base 2 - binrio - da string '01001020' )
retornar -1 ( menos um ) .

ESCAPE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
ESCAPE ( < cString > ) --> cEscaped
Parmetros
Argumento

Tipo

Descrio

cString

Caracter cString uma sequncia de caracteres a ser processada.

Retorno
Tipo

Descrio

Caracter

cEscaped corresponde string original , com os caracteres reservados


utilizando a notao %HH .

Descrio
A funo Escape() deve ser utilizada para realizar converses de caracteres especiais e
reservados quando da necessidade de passagem de parmetros via URL .
A sintaxe de uma requisio via URL para a passagem de parmetros :
(link)?param=conteudo&param2=conteudo2&...
Quando passamos parmetros via url , devemos tomar o cuidado de no utilizar caracteres
reservados e especiais nos nomes e contedos de parmetros. Para realizar estas
converses, utilizamos a funo Escape()

EXECINPAGE
Reviso: 12/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
EXECINPAGE ( < cAPHPage > ) --> cHTMLPage
Parmetros
Argumento

Tipo

Descrio

cAPHPage

Caracter

Corresponde o nome do APH que deve ser executado, sem


a extenso.

Retorno
Tipo

Descrio

Caracter

cHtmlPage corresponde string HTML gerada pela pgina APH / AHU.

Descrio
Atravs da funo ExecInPage(), executamos uma pgina APH passada como parmetro. A
funo dever retornar a String HTML correspondente pgina processada.
Porm a funo ExecInPage() realiza tratamentos adicionais padro relacionaodo o
comportamento dos Projetos WEB referentes customizaes, da segunte maneira :
1. Primeiro verificado se existe uma pgina AHU compilada com o nome
cAPHPage. Caso exista , a mesma ser executada pela execinpage.
2. Caso no exista AHU com este nome , procurado pelo APH. Caso o APH exista , o
mesmo ser executado pela ExecInPage.
3. Caso no existam no RPO atual o APH nem o AHU com o nome especificado no
parmetro cAPHFile, o processamento abortado com a ocorrncia de erro
[APWEXERR_0007] APH page [<cAPHPage>] not found in .RPO
4. Antes de executar o APH ou AHU identificado nos passos anteriores, verificado se
existe um ponto de entrada ( User Function ) compilado com o mesmo nome do
APH. Caso exista , o ponto de entrada executado . Ele dever retornar uma
String HTML. Se for retornada alguma string , a funo retorna a tring retornada e
no processa o APH / AHU. Observao : A funo ExecInPage no ir executar
este tratamento da User Function com o nome de cAPHPage caso a funo
ExecInPage() esteja sendo executada atravs de uma USER FUNCTION .
Observao Importante - Envio parcial de HTML o Browser.

A funo ExecInpage(), juntamente com o APH compilado, ao serem processados iro


tentar enviar o contedo HTML para o Browser solicitante durante o processamento, de
modo que a funo normalmente ir retornar uma String vazia.
Caso seja necessria a execuo de uma pgina APH ou AHU e o no-envio da mesma para
o Browse; por exemplo para a gerao de um cdigo HTML a ser enviado via e-mail;
revemos utilizar a funo HttpSetPart(), realizando uma chamada da mesma antes da
ExecInPage() , passando o parmetro .F. para desabilitar temporariamente o envio de
HTML simultneo ao Browser, e aps a execuo da ExecInPage(), devemos re-habilitar o
envio simultneo atravs da chamada da funo HttpSetPart() com o parmetro .T.

EXISTPAGE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
EXISTPAGE ( < cAphFile > ) --> lFound
Parmetros
Argumento

Tipo

Descrio

cAphFile

Caracter

Nome do arquivo APH, sem extenso e sem path , a ser


verificado.

Retorno
Tipo

Descrio

Caracter

Retorna um valor booleano indicando se o arquivo APH especificado est


compilado no RPO do ambiente atual.

Descrio
Utilizamos a funo ExistPage() para identificarmos no ambiente atual se um determinado
arquivo .APH encontra-se compilado atualmente no RPO em uso.
Exemplo :
If ExistPage('teste')
conout('teste.aph compilado neste RPO')
Else
conout('teste.aph NAO compilado neste RPO')
Endif

EXISTUSRPAGE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
EXISTUSRPAGE ( < cAhuFile > ) --> lExist
Parmetros
Argumento

Tipo

Descrio

cAhuFile

Caracter

Nome do arquivo AHU, sem extenso e sem path , a ser


verificado

Retorno
Tipo

Descrio

Lgico

Retorna um valor booleano indicando se o arquivo APH especificado est


compilado no RPO do ambiente atual.

Descrio
Utilizamos a funo ExistUSRPage() para identificarmos no ambiente atual se um
determinado arquivo .AHU encontra-se compilado atualmente no RPO em uso.
Exemplo :
If ExistUSRPage('teste')
conout('teste.ahu compilado neste RPO')
Else
conout('teste.ahu NAO compilado neste RPO')
Endif

GETJOBPROFSTRING
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
GETJOBPROFSTRING ( < cKey > , < cDefault > ) --> cKeyValue
Parmetros
Argumento

Tipo

Descrio

cKey

Caracter

cKey corresponde chave da seo de configurao da


Working Thread atual a ser retornada.

cDefault

Caracter

Valor default (string) a ser retornado pela funo caso a


chave especificada no sehja encontrada no .INI

Retorno
Tipo

Descrio

Caracter

Conteudo da Chave solicitada . Caso a chave no seja encontrada ,


retornado o conteudo de cDefault . Caso esta funo no seja executada a
partir de uma Working Thread , ela retornar uma string em branco ("")

Descrio
Atravs desta funo , podemos recuperar as configuraes do Job da Working Thread
atual.

GETWEXVERSION
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
GETWEXVERSION ( ) --> cBuildId
Retorno
Tipo

Descrio

Caracter

Corresponde String Identificadora da verso , no formato <LIB>


V.AAMMDDHHmm . Vide Tabela A

Descrio
Esta funo no requer argumentos , e retorna o Identificador do build / verso de Release
das funes de Infra-Estrutura APWEBEX.
Observao : A data informada pela verso no corresponde ultima compilao do
RPO de um determinado Projeto WEB, mas sim data de release da LIB de InfraEstrutura APWEBEX.

Tabela A
Simbolo
Descrio
AA
Ano de gerao da Lib
MM
Ms da gerao da Lib
DD
Dia da gerao da Lib
HH
Horrio da gerao da Lib
mm
Minutos do Horrio de Gerao da Lib
Indica que a verso foi compilada com a configuraco de envio progressivo de
(HTTP) HTML simultneo para o Browse . Esta opo imprescindvel para projetos
que se utilizam desta LIB.
Por exemplo :
APWEBEX Version 3.0312021900 (HTTP)

HEXSTRDUMP
Reviso: 15/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
HEXSTRDUMP ( < cString > , [ nStart ] , [ nLength ] ) --> cHExDump
Parmetros
Argumento

Tipo

Descrio

cString

Caracter String a ser lida para a gerao do Dump

nStart

Corresponde posio inicial de cString a ser considerada


para a gerao do Dump, a partir da posio 1. Caso este
Numrico
parmetro no seja informado , o Default a posio 1 da
string.

nLength

nLength corresponde o tamanho a ser considerado para a


gerao do DUMP a partir da posio inicial recebida em
Numrico
nStart. Caso este parmetro no seja informado,
considerado o tamanho at o final da String.

Retorno
Tipo

Descrio

Caracter

O retorno da funo corresponde uma string Advpl , formatadas em 16


bytes em hexadecimal por linha , mais o separador pipe (|) , mais os 16
caracteres em Ansi. Os caracteres de controle ( codigo ascii menor que 32 )
so convertidos para visualizao para o caractere underline (_)

Descrio
Atravs da funo HexStrDump(), podemos gerar uma string em Advpl em formato de
Dump Hexadecimal a partir da string informada como parmetro, a partir de uma
determinada posio da string, considerando um nmero de bytes informado.
Caso os parmetros nPosIni e nTamString no sejam informados, o dump gerado
corresponde a string recebida como parmetro em sua totalidade.
Observao :
No devemos pasar para a funo HexStrDump uma string maior que 240 Kb , pois a
gerao da String de dump realizada em memria, sendo a string final gerada em mdia
4,2 vezes maior que a string passada como parmetro. Caso a string passada como

parmetro seja maior que 240 Kb , a execuo ser abortada com a ocorrncia de erro fatal
"string size overflow"

HTMLNOTAGS
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
HTMLNOTAGS ( < cStrHtml > ) --> cStrNoTags
Parmetros
Argumento

Tipo

Descrio

cStrHtml

Caracter

cStrHtml corresponde a uma String que no pode conter


caracteres Html interpretveis.

Retorno
Tipo

Descrio

Caracter

String original com os caracteres interpretveis Html < > & " convertidos
para caracteres no-interpretveis.

Descrio
A Funo HTMLNOTAGS converte as Tags interpretveis de uma String HTML para
TAGS no interpretveis. Este recurso normalmente utilizado quando precisamos montar
um input Html com um conteudo que nao pode ser interpretado pelo browser como uma
Tag . Esta funo apenas converte os caracteres < ( menor que ) , > ( maior que ) , & ( e
comercial ) e ( aspas duplas ) .
Recomenda-se fortemente que, na montagem do value de um input html , o contedo
do mesmo seja colocado entre aspas duplas, pois caso o contedo do value inicial do
campo contenha aspas simples ( no convertidas pela funo HtmlNoTags) , isto
poder ocasionar perda de dados e erro de sintaxe no formulrio Html.

HTTPISWEBEX
Reviso: 12/12/2003
Sintaxe
HTTPISWEBEX ( ) --> lIsApWEBEX
Retorno
Tipo

Descrio

Lgico

A funo retornar .T. caso o ambiente de execuo atual seja uma


Working Thread WEBEX , inicializada pela funo de infra-estrutura
STARTWEBEX.

Descrio
Atravs da funo HttpIsWebEx() possvel identificarmos se o programa atual est sendo
executado atravs de uma Working Thread inicializada utilizando-se as funes de InfraEstrutura APWEBEX

ISEMAIL
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
ISEMAIL ( < cEMail > ) --> lEmailOk
Parmetros
Argumento

Tipo

Descrio

cEMail

Caracter

cEmail corresponde a string a ser analizada , contendo um


e apenas um endereo de e-mail.

Retorno
Tipo

Descrio

Caracter

Retorna .T. caso a sring recebida como parmetro atenda s definies de


nomenclatura vlidos para um endereo de e-mail.

Descrio
Utilizada para validar e-mails em Advpl , a funo ISEMAIL recebe como parmetro uma
string contendo um e-mail , retornando .T. caso a string esteja em um formto vlido
respeitando a regra para nomenclatura de endereos de e-mail.
Regra : Um e-mail considerado vlido caso seja iniciado por um caracter , apenas
contenha caracteres asc de a a z e 0 a 9 , e os caracteres @ (arroba) , . (ponto) , - ( hfen) ou
_ (underline) ; e deve conter uma e apenas uma arroba , e no minimo um ponto apos a
arroba, intercalado por um caracter.

LOWERACE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
LOWERACE ( < cString > ) --> cStrLower
Parmetros
Argumento

Tipo

Descrio

cString

Caracter

cString a sequncia de caracteres a ser convertida para


letras minsculas.

Retorno
Tipo

Descrio

Caracter

String original em letras minsculas.

Descrio
A Funo LOWERACE converte todos os caracteres de uma String para minusculo ,
semelhante funo LOWER() , porm considera e converte tambm caracteres acentuados
em ANSI.

NTOC
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
NTOC ( < nNumero > , < nBase > , < nTamStr > ) --> cString
Parmetros
Argumento

Tipo

Descrio

nNumero

Numrico

nNumero o valor numrico , em base devimal , a ser


convertido.

nBase

Numrico

nBase corresponde base binria a ser utilizada para


converter nNumero.

nTamStr

Numrico

nTamStr corresponde ao tamanho da string representando


o numero na base desejada .

Retorno
Tipo

Descrio

Caracter

cString corresponde ao numero convertido para a base numrica


especificada como parmetro.

Descrio
A Funo NTOC converte um nmero em notao decimal para um nmero representado
por String utilizando uma base numrica entre 2 e 36 , preenchendo-o com 0 (zeros)
esquerda do tamanho especificado.
Observao : O Parmetro nBase deve ser especificado com um nmero entre 2 e 36 .
Caso seja passado como parmetro um nmero base fora desta faixa, o processamento
abortado com a ocorrncia de erro [APWEXERR_0022] INVALID NTOC BASE [X] , onde
<X> foi a base passada como argumento.

REDIRPAGE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
REDIRPAGE ( < cUrl > , [ cTarget ] , [ nTime ] ) --> cScript
Parmetros
Argumento

Tipo

Descrio

cUrl

Caracter Link para onde o script deve apontar o redirecionamento

cTarget

Caracter

Destino do redirecionamento. Caso no especificado , o


default _self.

nTime

Numrico

Tempo (em segundos) de delay antes do redirecionamento


ser executado.

Retorno
Tipo

Descrio

Caracter

Script Html / JavaScript que , ao ser executado no Browser (client) , chama


a pgina/objeto chamado no Link.

Descrio
A funo RedirPage utilizada quando desejamos devolver ao Browser um script que , ao
ser executado , redirecionar o Browser abertura de um link passado como parmetro.

RETSQLACE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
RETSQLACE ( < cStrFind > ) --> cStrQuery
Parmetros
Argumento

Tipo

Descrio

cStrFind

cStrFind corresponde sequncia de caracteres a ser


Caracter procurada , podendo conter caracteres maisculos e
minsculos , com ou sem acentuao.

Retorno
Tipo

Descrio

Caracter

cStrQuery corresponde string de busca a ser utilizada na query, utilizando


caracteres em minsculo.

Descrio
A funo RetSqlAce utilizada para auxiliar de montagem de querys de busca de caracteres
acentuados em bases de dados . A funo automaticamente trata a string original ,
removendo os acentos , convertendo todos os caracteres para minsculas , e trocando todas
as vogais e cedilhas da string original por uma sequncia de caracteres acentuados em
munscilas para busca posicional .

RETSQLCOND
Reviso: 12/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
RETSQLCOND ( < cAliases > ) --> cSqlWhere
Parmetros
Argumento

Tipo

Descrio

cAliases

Lista contendo um ou mais aliases , separados por vrgula ,


Caracter a serem considerados para a montagem da expresso de
validao.

Retorno
Tipo

Descrio

Caracter

Corresponde expresso SQL para filtrar os dados atravs da clusula


WHERE

Descrio
Utilizamos a funo RetSqlCond() como auxiliar na montagem de querys para busca de
dados em tabelas em conformidade com o padro adotado pelo ERP Microsiga e o Makira
Hypersite , utilizando aliases de 3 caracteres.
A funo retorna , a partir dos aliases passados como parmetro , as expresses de filtro de
dados para considerar a filial atual ( xFilial ) de acordo com o modo do arquivo
( X2_MODO ) , e para sempre desconsiderar registros deletados.
Observaes :

Esta funo foi mantida apenas por compatibilidade, pois a ordem de comparao
de campos na clusula WHERE de uma query deve procurar seguir a ordem dos
campos dos indexadores do banco para efeitos de performance . Para ganharmos
performance nas Querys , devemos ao invs de utilizar a funo RetSqlCond() ,
utilizar como primeira clasula WHERE o retorno da funo RetSqlFil()
( comparao dos campos _FILIAL , os primeiros do(s) ndice(s) do ERP ) , que
retorna apenas as comparaes de Filial , e por ltimo a funo RetSqlDel, que
retorna o script para verificao dos campos deletados ( que o ltimo campo das
chaves de ndice do ERP , utilizando TopConnect ).

Devemos tambm atentar ao fato que a funo RetSqlCond() retorna os campos


para a comparao utilizando o prefixo da expresso SQL com o Alias reduzido (3

letras) das tabelas informadas, de modo que estes alias devem ser especificados na
clusula FROM , na abertura da Query, quando utilizamos a funo RetSqlName
para retornar o nome fsico das Tabelas no Banco de Dados. A funo RqtSqlTab()
j retorna os nomes fsicos das tabelas juntamente com os alias para este fim .

RETSQLDEL
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
RETSQLDEL ( < cAliases > ) --> cSqlWhere
Parmetros
Argumento

Tipo

Descrio

cAliases

Lista contendo um ou mais aliases , separados por vrgula ,


Caracter a serem considerados para a montagem da expresso de
validao.

Retorno
Tipo

Descrio

Caracter

Corresponde expresso SQL para filtrar os dados atravs da clusula


WHERE

Descrio
Utilizamos a funo RetSqlDel() como auxiliar na montagem de querys para busca de
dados em tabelas em conformidade com o padro adotado pelo ERP Microsiga, utilizando
aliases de 3 caracteres.
A funo retorna , a partir dos aliases passados como parmetro , as expresses de filtro de
dados para considerar o campo D_E_L_E_T_ da(s) tabela(s) passada(s) como parmetro.
Observaes :

A ordem de comparao de campos na clusula WHERE de uma query deve


procurar seguir a ordem dos campos dos indexadores do banco para efeitos de
performance . Para ganharmos performance nas Querys , devemos utilizar a funo
RetSqlDEl() na montagem das ultimas consistncias da clusula WHERE de uma
Query.

Devemos tambm atentar ao fato que a funo RetSqlDel() retorna os campos para
a comparao utilizando o prefixo da expresso SQL com o Alias reduzido (3 letras)
das tabelas informadas, de modo que estes alias devem ser especificados na clusula
FROM , na abertura da Query, quando utilizamos a funo RetSqlName para
retornar o nome fsico das Tabelas no Banco de Dados. A funo RqtSqlTab() j
retorna os nomes fsicos das tabelas juntamente com os alias para este fim .

RETSQLFIL
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
RETSQLFIL ( < cAliases > , [ cCompFil ] ) --> cSQlWhere
Parmetros
Argumento

Tipo

Descrio

cAliases

Lista contendo um ou mais aliases , separados por vrgula ,


Caracter a serem considerados para a montagem da expresso de
validao.

cCompFil

Atravs de cCompFil possvel especificar uma Filial


FIXA a ser comparada com os campos FILIAL do(s)
alias(es) passados no parmetro cAliases. Caso no
Caracter
informado, os campos _FILIAL da(s) tabela(s) passadas
como parmetro em cAliases sero comparados com o
retorno da funo xFilial() de cada alias, respectivamente.

Retorno
Tipo

Descrio

Caracter

Corresponde expresso SQL para filtrar os dados atravs da clusula


WHERE

Descrio
Utilizamos a funo RetSqlFil() como auxiliar na montagem de querys para busca de dados
em tabelas em conformidade com o padro adotado pelo ERP Microsiga, utilizando aliases
de 3 caracteres.
A funo retorna , a partir dos aliases passados como parmetro , as expresses de filtro de
dados para considerar o campo filial atual ( xFilial ) de acordo com o modo de abertura
do arquivo no ERP ( X2_MODO ) .
Observao :

Devemos atentar ao fato que a funo RetSqlFil() retorna os campos para a


comparao utilizando o prefixo da expresso SQL com o Alias reduzido (3 letras)
das tabelas informadas, de modo que estes alias devem ser especificados na clusula
FROM , na abertura da Query, quando utilizamos a funo RetSqlName para

retornar o nome fsico das Tabelas no Banco de Dados. A funo RqtSqlTab() j


retorna os nomes fsicos das tabelas juntamente com os alias para este fim .

RETSQLTAB
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
RETSQLTAB ( < cAliasList > ) --> cStrQuery
Parmetros
Argumento

Tipo

Descrio

cAliasList

Caracter

String contendo um ou mais alias , separados por virgula , a


terem seus nomes fsicos determinados.

Retorno
Tipo

Descrio

Caracter

String contendo nomes fisicos e alias identificadores dos aliases recebidos


como parmetro.

Descrio
Utilizamos a funo RetSqlTab() como auxiliar na montagem de query's quando
trabalhamos com o padro de Tabelas ERP Microsiga, que utilizam nomenclarura de alias
com 3 Caracteres.
A funo recebe como parmetro um ou mais alias, separados por vrgula, de tabelas que
desejam ser utilizadas na query, e retorna os nomes fisicos das tabelas e seus respectivos
alias para serem inseridos na query.

SEPARA
Reviso: 15/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
SEPARA ( < cString > , < cToken > , < lEmpty > ) --> aTokens
Parmetros
Argumento

Tipo

Descrio

cString

Caracter String com a sequncia de caracteres a ser "parseada"

cToken

Caracter

lEmpty

lEmpty identifica se caso um intervalo vazio entre tokens


Caracter deve ser retornado como um elemento do array. Caso no
especificado , o Default .T.

cToken corresponde string a ser utilizada como separador


para delimitar as informaes.

Retorno
Tipo

Descrio

Caracter

Array de uma dimenso contendo os elementos parseados pela rotina


levando-se em conta o separador passado como parametro.

Descrio
Atravs da funco SEPARA(), pode-se parsear uma string de elementos a partir de um
determinado separador , sendo retornado um Array com os elementos identificados na
String.
Exemplo :
aInfo := Separa('1,2,,4',',',.f.) // Resulta {'1','2','4'}
aInfo := Separa('1,2,,4',',',.t.) // Resulta {'1','2','','4'}

Observao :
Para realizar a anlise de uma string, cujo delimitador tenha apenas 1 byte, e as ocorrncias
de dois separadores juntos sejam ignoradas na gerao do array, a funo separa() utiliza a
funo StrTokArr(), funo escrita em C no Protheus Server, mais rpida para este
processamento. Apenas existe a necessidade de utilizarmos a funo Separa() caso as
ocorrncias de dois separadores juntas devam ser consideradas no array de resultado e/ou a
string utilizada como separador possua mais que 1 byte de tamanho.

UNESCAPE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
UNESCAPE ( < cString > ) --> cUnEscaped
Parmetros
Argumento

Tipo

Descrio

cString

Caracter

cString a string a ter os caracteres em formato escape


convertidos.

Retorno
Tipo

Descrio

Caracter

cUnescaped corresponde string recebida como parmwetro , com os


caracteres originalmente em notao escape ( %HH ) convertidos para
ASCII

Descrio
Realiza a operao inversa funo Escape() , convertendo os caracteres especiais em
notao %HH em caracteres ASCII.
Observao : Apenas sero convertidos os caracteres originalmente tratados pela
funo Escape()

UPPERACE
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
UPPERACE ( < cString > ) --> cStrUpper
Parmetros
Argumento

Tipo

Descrio

cString

Caracter String a ser convertida. Pode conter tambm acentos .

Retorno
Tipo

Descrio

Caracter

Retorna a string original com todas as letras mauisculas , inclusive as letras


acentuadas.

Descrio
A Funo UPPERACE converte todos os caracteres de uma String para mai\usculo ,
semelhante funo UPPER() , porm considera e converte tambm caracteres acentuados
em OEM e ANSI

UPSTRTRAN
Reviso: 15/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
UPSTRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [ nCount ] ) -->
cNewString
Parmetros
Argumento

Tipo

Descrio

cString

Caracter cString corresponde sequncia de caracteres ou campo

memo a ser pesquisado.


Corresponde sequncia de caracteres a ser procurada em
cString

cSearch

Caracter

cReplace

cReplace corresponde sequncia de caracteres que deve


substituir a string cSearch. Caso no seja especificado, as
Caracter
ocorrncias de cSearch em cString sero substitudas por
uma string nula ("")

nStart

nStart corresponde o nimero sequencial da primeira


ocorrncia de cSEarch em cString a ser substituda por
Numrico cReplace. Se este argumento for omitodo , o default 1
( um ) . Caso seja passado um numero menor que 1, a
funo retornar uma string em branco ("")

nCount

nCount corresponde o nmero mximo de trocas que


dever ser realizada pela funo . Caso este argumento no
Numrico
seja especificado , o default substituir todas as
coorncias encontradas.

Retorno
Tipo

Descrio

Caracter

A funo UPSTRTRAN retorna uma nova string, com as ocorrncias


especificadas de cSearch trocadas para cReplace, conforme
parmetrizao.

Descrio
Similar funo Strtran(), porm realiza a busca da ocorrncia da string considerando letras
maisculas e minsculas. A funo Strtran() case-sensitive, e a funo UpStrtran() no.

VALTOSQL
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
VALTOSQL ( < xExpressao > ) --> cQryExpr
Parmetros
Argumento

Tipo

Descrio

xExpressao

Valor Advpl a ser convertido para utilizao em Query.


(Qualquer) Pode ser dos tipos "C" Caracter , "N" Numrico e "D"
Data.

Retorno
Tipo

Descrio

Caracter

Expresso a ser acrescentada na Query.

Descrio
A Funo VALTOSQL() utilizada como auxiliar na montagem de Query's , convertendo
um contedo varivel Advpl para a string correspondente a ser acrescentada na Query.
Podemos passar como parmetro uma Expresso do tipo C Caracter , D Data ou N
Numrica.

A expresso Catacter ser colocada entre aspas simples, sendo removidas as aspas
simples contidas na mesma , caso existam .

Uma expresso numrica ser simplesmente convertida para caracter , com


aproximao de 2 casas decimais.

Uma expresso Data ser convertida para formato ANSI ( AAAAMMDD ) , entre
aspas simples.

VARINFO
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
VARINFO ( < cId > , < xVar > , [ nMargem ] , [ lHtml ] , [ lEcho ] ) --> cVarInfo
Parmetros
Argumento

Tipo

Descrio

cId

Caracter

cId corresponde a um nome atribudo varivel para


anlise. Internamente , apenas utilizado para prefixar o
retorno das informaes da VarInfo.

xVar

(Qualquer) Varivel de qualquer tipo a ser examinada

nMargem

Numrico

Corresponde margem esquerda inicial de espaos da


String de retorno , multiplicado por 5. Default = 0

lHtml

Lgico

Identifica se a String de retorno ser montada em formato


Html (.T. / Default ) ou ASCII (.F.)

lEcho

Lgico

Define se o Echo do retorno deve ser enviado ao console


do Protheus Server , caso habilitado. ( Default = .T. )

Retorno
Tipo

Descrio

Caracter

String contendo o "Dump" da anlise da varivel. Caso lHtml seja .T. ,


retorna String em formato HTML . , seno retorna string ASCII com
quebras CRLF.

Descrio
A Funo VARINFO() gera um texto ASCII e/ou Html , com possibilidade de ECHO para o
Console do Protheus Server ( caso habilitado ) , com as informaes sobre o contedo de
uma varivel de memria Advpl , de qualquer tipo .
Cada tipo de varivel possui um tratamento para converso em String :

CodeBlock : exibido apenas o tipo da mesma (B)

Array : Todos os nveis e elementos do mesmo so explorados recursivamente.

Objeto : No caso de um Objeto de XML e/ou Web Services, so exploradas todas as


suas propriedades recursivamente.

(demais tipos) : So convertidos para String atravs da funo AllToChar

Observao : O segundo parmetro ( xVar ) deve ser uma varivel Advpl que deve existir
no escopo de variveis. Caso a varivel no exista, o processamento abortado com a
ocorrncia de erro "Variable does not exist" . Para saber se uma determinada varivel
existe no escopo da execuo da funo atual, deve ser utilizada a funo Advpl TYPE(),
onde passamos a varivel a ter seu tipo determinado como string ( entre aspas ) .

WEBINFO
Reviso: 12/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
WEBINFO ( ) --> cHtmlInfo
Retorno
Tipo

Descrio

Caracter

cHTMLInfo corresponde string HTML contendo as informaes da


requisio HTTP.

Descrio
A funo WebInfo() foi desenvolvida para ser chamada atravs de uma requisio http , via
link .apl ou .apw , e ela identifica todos os parmetros recebidos via uma requisio http:
Parmetros via get , post , o header HTTP, os Cookies, o content-type , Legth , Contentdisposition , SoapRaction (ao SOAP para requisies de WebSErvices ) , e
OtherContent ( caso o contedo postado no seja um text/html )
Esta funo retorna uma pgina Html com todas estas informaes, e utilizada no
desenvolvimento de projetos. quando temos a necessidade prtica de recuperarmos todas as
informales provenientes de uma requisio HTTP. Adicionalmente , a funo WebInfo
Por exemplo, com o Protheus configurado para atender requisies de links .apl via HTTP ,
chame a funo WebInfo.apl atravs do link :
http://localhost/webinfo.apl?param1=teste&param2=outroteste
Ser exibido no Web Browser uma tela semelhante tela abaixo :
__aCookies -> ARRAY ( 0) [...]
__aPostParms -> ARRAY (

0) [...]

__nProcId -> N ( 10) [1169539314]


__aProcParms -> ARRAY (
__httpPage -> C (

0) [...]

0) []

__HttpHeader -> ARRAY ( 8) [...]


__HttpHeader[1] -> C ( 25) [GET /webinfo.apl HTTP/1.1]
__HttpHeader[2] -> C ( 172) [Accept: image/gif, image/x-xbitmap, image/jpeg,
image/pjpeg, application/x-shockwave-flash, application/vnd.ms-excel, application/vnd.mspowerpoint, application/msword, */*]
__HttpHeader[3] -> C ( 22) [Accept-Language: pt-br]
__HttpHeader[4] -> C ( 30) [Accept-Encoding: gzip, deflate]
__HttpHeader[5] -> C ( 61) [If-Modified-Since: Wed, 10 Dec 2003 12:24:29 GMT;
length=1003]
__HttpHeader[6] -> C ( 81) [User-Agent: Mozilla/4.0 (compatible; MSIE 6.0;
Windows NT 5.1; .NET CLR 1.0.3705)]
__HttpHeader[7] -> C ( 13) [Host: automan]
__HttpHeader[8] -> C ( 22) [Connection: Keep-Alive]
HttpRCtType() -> C (

0) []

HttpRCtLen() -> N ( 10) [


HttpRCtDisp() -> C (

0) []

SoapRAction() -> C (

0) []

HttpOtherContent() -> C (

-1]

0) []

Caso a mesma requisio seja realizada atravs de link .apw , utilizando-se a tecnologia
WEBEX , dever ser exibida uma tela semelhante tela abaixo :
aHeaders -> ARRAY ( 9) [...]
aHeaders[1] -> C ( 25) [GET /webinfo.apw HTTP/1.1]
aHeaders[2] -> C ( 172) [Accept: image/gif, image/x-xbitmap, image/jpeg,
image/pjpeg, application/x-shockwave-flash, application/vnd.ms-excel, application/vnd.mspowerpoint, application/msword, */*]
aHeaders[3] -> C ( 22) [Accept-Language: pt-br]
aHeaders[4] -> C ( 30) [Accept-Encoding: gzip, deflate]
aHeaders[5] -> C ( 61) [If-Modified-Since: Tue, 09 Dec 2003 21:23:03
GMT; length=1480]
aHeaders[6] -> C ( 81) [User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT
5.1; .NET CLR 1.0.3705)]
aHeaders[7] -> C ( 21) [Host: apwebex.automan]
aHeaders[8] -> C ( 22) [Connection: Keep-Alive]
aHeaders[9] -> C ( 41) [Cookie: SESSIONID=1071153371; AP5PROCID=0]
httpCookies -> ARRAY ( 2) [...]
httpCookies[1] -> C ( 9) [SESSIONID]
httpCookies[2] -> C ( 9) [AP5PROCID]
SESSIONID -> C ( 10) [1071153371]
AP5PROCID -> C (

1) [0]

httpPost -> ARRAY (


httpGet -> ARRAY (
HttpRCtType() -> C (

0) [...]
0) [...]
0) []

HttpRCtLen() -> N ( 10) [


HttpRCtDisp() -> C (

0) []

SoapRAction() -> C (

0) []

HttpOtherContent() -> C (

-1]

0) []

[APWEXERR_0000] INVALID PROC


RETURN TYPE [X] ...
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0000] INVALID PROC RETURN TYPE [X] from [Y]


Descrio / Causa : Na Infra-Estrutura ApWebEx, de acordo com o mdulo WEB em uso,
chamada durante a inicializao da Working Thread no ambiernte WEBEX uma funo
especfica [Y] para inicializao adicional de ambiente, e a lib exige um retorno do tipo
Booleano ( .T. ou .F. ) , indicando se a inicializao adicional foi executada com sucesso ou
no. Caso este ponto de entrada retorne um valor cujo tipo no seja booleano, esta
mensagem de erro apresentada no console do Server e acrescentada o arquivo
ERROR.LOG
Soluo : Verifique o fonte do ponto de entrada e assegure-se que o mesmo est retornando
um valor Advpl do tipo 'L' Lgico.

[APWEXERR_0001] INVALID APWEX


CALL
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0001] INVALID APWEX CALL


Descrio / causa : Ao solicitarmos ao servidor Protheus o processamento de uma funo
Advpl atravs de um link .apw, utilizando a infra-estrutura ApWebex, existem funes
especficas da linguagem que no podem ser executadas diretamente neste tipo de
ambiente, por tratarem-se de funes exclusivas para processamentos iniciados atravs de
um Remote, e funes que no permitem chamada direta via link. Caso alguma destas
funes seja chamada diretamente via URL, esta ocorrncia de erro reproduzida.

[APWEXERR_0003] INVALID PROC


RETURN TYPE [X] ...

Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0003] INVALID PROC RETURN TYPE [X] from [Y]


Descrio / causa : Quando uma working thread do ambiente ApWebEx, recebe uma
solicitao de processamento atravs de um link .apw, de acordo com o mdulo web
utilizado, pode ser chamada uma funo intermediria [Y], antes do processamento da
funo chamada no link ou depois do processamento concludo.
A lib exige que estas funes internedirias retornem um contedo Advpl do tipo
"STRING". Caso a funo [Y] chamada pela lib retorne um contedo Advpl diferente de
"STRING", o tipo de varivel retornado mostrado em [X] e a Working Thread finalizada
com esta ocorrncia de erro.
Soluo : Verifque o cdigo-fonte da funo [Y], para certificar-se que seu retorno sempre
ser um contedo Advpl do tipo "STRING"

[APWEXERR_0004] INVALID PROC


RETURN TYPE [X] ...
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0004] INVALID PROC RETURN TYPE [X] FUNCTION [YYY]


Descrio / causa : Quando solicitado o servidor Protheus o processamento de uma
funo atravs de um link .apw, a funo executada sempre dever retornar um contedo
Advpl do tipo "STRING". Caso o contedo retornado pelo processamento da funo
[YYY] retorne um tipo [X], diferente de "STRING", a working thread finalizada com esta
ocorrncia de erro, onde [YYY] indica a funo chamada atravs do link .apw e [X] indica
o tipo de contedo invlido retornado
Soluo : Verifique o fonte da funo [YYY] e certifique-se que a funo sempre retorne
um contedo do tipo "STRING"

[APWEXERR_0005] Function XXX


requires APWEBEX ...
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0005] Function XXX requires APWEBEX Routines.


Descrio / causa : Ao desenvolvermos uma aplicao para utilziar a infra-estrutura
ApWebEx, utilizando o #include 'apwebex.ch' e os comandos WEB EXTENDED INIT ...
END, devemos nos assegurar de estarmos executando esta funo em um ambiente de
working threads, configurados com o tipo WEBEX, utilizando as funes da infra-estrutura
ApWebEx ( StartWebex , ConnectWebEx ... ) para inicializao e processamento da
requisio via link .apw .
Se uma funo [XXX], escrita para ser chamada exclusivamente neste tipo de ambinete,
seja chamada diretamente via Protheus Remote, ou outro tipo de processamento que no
seja uma working thread inicializada pelas funes de infra-estrutura ApWebEx, a funo
abortada com esta ocorrncia de erro. Isto tambm consistem em uma proteo, para que
uma funo projetada para ser executada em um tipo de ambiente ( working threads
ApWebEx ) no seja erroneamente executada em outro ambiente.
Soluo : Verifique se a funo chamada realmente est sendo executada no ambiente
apropriado.

[APWEXERR_0006] START Function


XXX Invalid Ret ...
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0006] START Function XXX Invalid Return Type [Y]


Descrio / causa : Quando utilizado o comando WEB EXTENDED INIT, especificando
uma funo [XXX] de pr-validao de execuo, atravs da clusula START, a funo
especificada dever retornar um contedo do tipo "STRING". Caso a funo [XXX] retorne
um contedo no vazio, de tipo [Y], diferente de "STRING", o processamento da working
thread abortado com esta ocorrncia de erro.
Soluo : Verifique o fonte da funo [XXX] e assegure-se que a execuo desta retorne
um contedo do tipo "STRING"

[APWEXERR_0007] APH page [XXX] not


found in .RPO
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0007] APH page [XXX] not found in .RPO


Descrio / causa : Ao utilizarmos a funo ExecInPage(), no desenvolvimento de
aplicaes utilizando as funes de infra-estrutura ApWebex, a mesma possui tratamento
automtico para buscar primeiramente por uma pgina AHU compilada no repositrio de
objetos do ambiente. Caso no seja encontrado uma pgina .ahu, a funo procura por uma
pgina .aph. Se nenhuma pgina com o nome especificado no for encontrada, o
processamento abortado com esta ocorrncia de erro.
Soluo : Verifique se a funo que originou a chamada da ExecInPage() passou o nome
do APH / AHU de forma correta, e se a pgina chamada est realmente presente e/ou foi
compilada no repositrio do projeto em questo.

[APWEXERR_0008] OPEN QUERY


ERROR : NO CONNECTION
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0008] OPEN QUERY ERROR : NO CONNECTION


Descrio / causa : Ao utilizarmos o comando OPEN QUERY, caso no exista uma
conexo ativa com o TOPConnect, o processamento em execuo abortado com esta
ocorrncia de erro.
Soluo : Certifique-se de que a chamada deste comando est sendo realizada atravs de
uma working thread que possua uma conexo ativa com o TOPConnect.

[APWEXERR_0009] RetSqlCond failed to


read X2_MODO
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0009] Failed to read X2_MODO Alias [XXX]


Descrio / causa : Quando utilizada a funo RetSqlFil() como auxiliar na montagem
de querys, a mesma tenta determinar se o(s) alia(s) utilizado(s) na Query esto configurados
no ambiente ERP atual no SX2 em modo 'C' Compartilhado ou 'E' Exclusivo. Caso o
alias [XXX] no seja encontrado na tabela SX2, ou a tabela SX2 no esteja aberta no
momento da execuo desta, no possvel identificar o modo de acesso do alias
especificado, e a execuo encerrada com esta ocorrncia de erro.
Soluo : Verifique se a funo RetSqlFil() e/ou RetSqlCond() est recebendo o(s) alia(s)
corretos, todos em letras maisculas; caso especificados mais de um alias, todos estejam
separados por vrgulas, e que a tabela SX2 do ERP esteja aberta para a correta identificao
dos tratamentos de FILIAL para a montagem da condio para Query.

[APWEXERR_0010] ERP FINAL


ROUTINE CALLED
Reviso: 13/04/2004
[APWEXERR_0010] ERP FINAL ROUTINE CALLED
Descrio / causa : Quando executamos uma funo em uma working thread inicializada
com as funes de infra-estrutura ApWebEx, a funo final(), utilizada internamente pelas
funes de infra-estrutura do ERP Microsiga, possui neste ambiente um tratamento
diferenciado. Caso ela seja executada , a working thread finalizada com esta ocorrncia
de erro.
Soluo : A funo final() no deve ser utilizada como um recurso de finalizao de
aplicao WEB, porm ela utilizada internamente por funes da infra-estrutura ERP, no
caso de uma ocorrncia fatal que impea um determinado processamento, e ganhou esta
proteo na Lib ApWebEx para permitir o desenvolvimento de aplicaes integradas
WEB / ERP.
Caso reproduzida uma ocorrncia de erro desta natureza, verifique nos detalhes do erro qual
funo que estava em execuo e qual o motivo da finalizao da working thread. Este
motivo est especificado no campo "Erp Message", mostrado nos detalhes da ocorrncia de
erro.

[APWEXERR_0011] Argument #0 Error :


Parameter ...
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0011] Argument #0 Error : Parameter required.


Descrio / causa : Quando utilizada a funo ApWExAddErr(cTitle,cInfo), para
informar rotina de tratamento de erro da infra-estrutura ApWebEx, uma informao
adicional a ser acrescentada no LOG de erro, os parmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"
Soluo : Esta ocorrncia de erro informa que o parmetro cTitle no foi especificado ou
est vazio, porm o parmetro cInfo foi especificado. Verifique o cdigo-fonte e corriga a
chamada da funo.

[APWEXERR_0012] Argument #0 Error :


Expected C->X
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0012] Argument #0 Error : Expected C->X


Descrio / causa : Quando utilizada a funo ApWExAddErr(cTitle,cInfo), para
informar rotina de tratamento de erro da infra-estrutura ApWebEx, uma informao
adicional a ser acrescentada no LOG de erro, os parmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"
Soluo : Esta ocorrncia de erro informa que o parmetro cTitle foi especificado com um
tipo [X], que no "STRING". Verifique o cdigo-fonte e corrija o parmetro passado para
a funo.

[APWEXERR_0013] Argument #1 Error :


Parameter ...
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0013] Argument #1 Error : Parameter required.


Descrio / causa : Quando utilizada a funo ApWExAddErr(cTitle,cInfo), para
informar rotina de tratamento de erro da infra-estrutura ApWebEx, uma informao
adicional a ser acrescentada no LOG de erro, os parmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"
Soluo : Esta ocorrncia de erro informa que o parmetro cInfo no foi especificado ou
est vazio, porm o parmetro cTitle foi informado. Verifique o cdigo-fonte e corrija a
chamada desta funo.

[APWEXERR_0014] Argument #1 Error :


Expected C->X
Reviso: 13/04/2004
[APWEXERR_0014] Argument #1 Error : Expected C->X
Descrio / causa : Quando utilizada a funo ApWExAddErr(cTitle,cInfo), para
informar rotina de tratamento de erro da infra-estrutura ApWebEx, uma informao
adicional a ser acrescentada no LOG de erro, os parmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"
Soluo : Esta ocorrncia de erro informa que o parmetro cInfo foi especificado com um
tipo de dado [X] que no "STRING". Verifique o cdigo-fonte e corrija a chamada desta
funo.

[APWEXERR_0020] INVALID JOB


[XXX] TYPE [YYY]
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0020] INVALID JOB [XXX] TYPE [YYY]


Descrio / causa : Esta ocorrncia de erro indica que as configuraes do Job [XXX], de
working threads para utilizao no ambiente ApWebEx, est identificado com um TYPE
[XXX] invlido.
Durante a inicializao de uma working thread, verificado o tipo do Job configurado no
arquivo de configurao. Apenas so vlidos os valores WEB e/ou WEBEX, de acordo com
o mdulo web em uso. Caso a configurao especifique um TYPE diferente de WEB ou
WEBEX, a configurao no vlida, e a working thread abortada antes de estar
disponvel para atender requisies de links .apw, gerando uma ocorrncia de erro no
console do servidor Protheus, tambm gravada no arquivo ERROR.LOG
Soluo : Para solucionar esta ocorrncia, basta verificar a configurao do Job [XXX]
utilizado para inicializar as working threads e especificar um tipo adequado ( WEB ou
WEBEX ), de acordo com o mdulo em uso.

[APWEXERR_0021] UNABLE TO GET


JOB NAME
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

[APWEXERR_0021] UNABLE TO GET JOB NAME


Descrio / causa : Esta ocorrncia de erro indica que o processo atual em execuo no
foi originado pela configurao de um processo WEB ou WEBEX , ou a funo de
inicializao de ambiente STARTWEBEX no foi chamada atravs de um evento
ONSTART de JOB, como por exemplo um AP Remote.
Soluo : Caso esta ocorrncia seja reproduzida, cerifique-se que a funo de inicializao
das working threads ( STARTWEBEX ) esteja sendo chamada atravs de um processo
configurado com TYPE=WEB ou WEBEX, de acordo com o mdulo web em uso.

[APWEXERR_0022] <T> Function [X] of


Module [Y] ...
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0022] <Start / Connect> Function [X] of Module [Y] not found in Rpo.
Descrio / causa : Esta ocorrncia de erro reproduzida quando, ao configurar um
mdulo web [Y], a funo [X] de inicializao ou conexo referente ao mdulo no foi
encontrada no repositrio de objetos do ambiente em uso pela aplicao web.
Soluo : Certifique-se que o repositrio em uso atualmente possui as funes pertinentes
o modulo configurado.

[APWEXERR_0023] UNSUPPORTED
BREAK CONTROL
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0023] UNSUPPORTED BREAK CONTROL


Descrio / causa : Ao utilizar as funes de Infra-Estrutura APWEBEX, quando da
chamada de uma funo atrav de Link .apw , desde a chamada original at a passagem
pelos pontos de pr e ps-validao de processamento, a rotina de tratamento de erro
habilitada de controle interno e exclusivo da Infra-Estrutura ApWebEx.
Caso o comando BREAK seja chamado em algum destes pontos, a execuo abortada , e
na rotina de tratamento de execuo, no h o registro de controle de erro, de modo que a
working thread abortada com esta ocorrncia de erro.
Soluo : Certifique-se que no cdiugo fonte da aplicao no seja utilizado o comando
BREAK.
OBSERVAO : Como esta ocorrncia tratada em um ponto de retorno interno, o
ponto de entrada WEBEXERROR no executado, sendo retornada ao usurio a
mensagem padro de Erro.

[APWEXERR_0024] <T> Function [X] of


Module [Y] ...
Reviso: 13/04/2004
Abrangncia
Verso 8.11

LIB WEBEX

[APWEXERR_0024] <Start / Connect / Finish > Function [X] of Module [Y] not found
in Rpo.
Descrio / causa : Esta ocorrncia de erro reproduzida quando, ao configurar um
mdulo web [Y], a funo [X] de inicializao, conexo ou finalizao, referente ao
mdulo, no foi encontrada no repositrio de objetos do ambiente em uso pela aplicao
web.
Soluo : Certifique-se que o repositrio em uso atualmente possui as funes pertinentes
o modulo configurado.

[APWEXERR_0025] Unknow SIGAWEB


Module [Y]
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

[APWEXERR_0025] Unknow SIGAWEB Module [Y]


Descrio / causa : Quando da configurao de um mdulo web para os tratamentos
internos das funes de infra-estrutura ApWebEx, devemos especificar uma sigla de um
mdulo Web vlido e tratado pela lib de infra-esturtura. Os mdulos atualmente
implementados na lib so :

DW - Data WareHouse

BSC - Balanced ScoreCard

MAK - Modulo WEBEX Makira

GE - Gesto Educacional

GPR - Gesto de Pesquisa e Resultado

TCF - Terminal do Funcionario ( RH ONLINE )

PP - Portal PRotheus ( WebServices )

SAV - Sala de Aprendizagem Virtual

GAC - Gesto de Acervos

WPS - WebPrint & WebSpool

Caso no seja fornecida uma sigla vlida na chave SIGAWEB, na seo de configurao
das working threads, as mesmas no entraro no ar, e sero abortadas com esta ocorrncia
de erro.
Soluo : Verifique a chave de configurao SIGAWEB e preencha-a com uma sigla de
mdulo vlida para a verso de repositrio / ambiente em uso.

[APWEXERR_0026] Web Services Test


POST ERROR.
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

[APWEXERR_0026] Web Services Test POST ERROR..


Descrio / causa : Quando utilizamos a interface de testes de web services client da
ferramenta WebAdmin, caso ocorra uma falha estrutural no servio Client ou uma
impossibilidade de recuperar todos os dados postados no fomulrio de testes, o
processamento interrompido com esta ocorrncia de erro.

[APWEXERR_0027] INVALID NTOC


BASE [NNN]
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0027] INVALID NTOC BASE [NNN]


Descrio / causa : Ao utilizar a funo ntoc(), deve-se atentar ao limite de base numrica
para converso, que pode ser um nmero entre 2 e 36. Caso a base passada como parmetro
para a funo ntoc() esteja fora destes limites, o processamento abortado com a
ocorrncia acima , informando em NNN a base utilizada.
Soluo : Verifique a chamada da funo ntoc() no fonte e certifique-se que est sendo
informado um nmero entre 2 e 36.

[APWEXERR_0028] MODULE [Y]


REQUIRES JOB TYPE=WEBEX
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0028] MODULE [Y] REQUIRES JOB TYPE=WEBEX


Descrio / causa : Esta ocorrncia de erro informa que a configurao de working threads
utilizada para este mdulo web no possui o tipo adequado configurado. O Mdulo [Y]
utilizado requer um job para working threads configurado com TYPE=WEBEX, porm
esta configurao est atualmente configurada como WEB.
Soluo : Verifique a configurao das working threads deste mdulo web e certifique-se
que a configurao TYPE est setada para WEBEX.

[APWEXERR_0029] MODULE [Y]


REQUIRES JOB TYPE=WEB
Reviso: 13/04/2004
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

[APWEXERR_0029] MODULE [Y] REQUIRES JOB TYPE=WEB


Descrio / causa : Esta ocorrncia de erro informa que a configurao de working threads
utilizada para este mdulo web no possui o tipo adequado configurado. O Mdulo [Y]
utilizado requer um job para working threads configurado com TYPE=WEB, porm esta
configurao est atualmente configurada como WEBEX.
Soluo : Verifique a configurao das working threads deste mdulo web e certifique-se
que a configurao TYPE est setada para WEB.

[APWEXERR_0030] NO WEB
LICENCES AVAILABLE (...
Reviso: 13/04/2004
Abrangncia
Verso 8.11

LIB WEBEX

[APWEXERR_0030] NO WEB LICENCES AVAILABLE


Descrio / causa : Esta ocorrncia de erro, indica que no h mais licenas Protheus i
disponveis para a utilizao da aplicao Web. Adicionalmente esta ocorrncia,
informado adicionalmente a informao "WEB LICENSE STATUS [NNNN]", onde nnnn
indica o cdigo de erro do HardLock utilizado para controle de licenas.
Soluo : Verifique na lista completa de status de retorno do HarkLock , disponvel em
(pendente), para certificar-se da origem desta ocorrncia e ento tomar uma ao corretiva.

[APWEXERR_0031] WARNING : WEB


LICENSES WILL EXP...
Reviso: 13/04/2004
Abrangncia
Verso 8.11

LIB WEBEX

[APWEXERR_0031] WARNING : WEB LICENSES WILL EXPIRES


Web Licenses will expires in NN day(s)
Descrio / causa : Esta ocorrncia consiste em uma advertncia, registrada no arquivo
error.log do ambiente em uso pela aplicao Web, registrada uma vez ao dia, a partir do
instante que faltam apenas 10 dias ou menos para que as licenas web ( Protheus i ) da
aplicao expirem. O nmero de dias que restam para as licenas vencerem especificado
adicionalmente em [NN].
Soluo : Providencie a atualizao das licenas Protheus i da aplicao web junto
Microsiga.

Pontos de Entrada - APWEBEX


Reviso: 30/04/2004
Abrangncia
Verso 8.11
Quando da utilizao da infra-estrutura APWEBEX, especificamente o mdulo 'MAK'
( Makira ), so disponibilizados os pontos de entrada relacionados neste tpico, para
permitir customizar e interceptar os eventos de Inicializao da Thread ( U_StartWebEx ),
atendimento a requisies de links .apw antes de processar a funo
principal ( U_ConnectWebEx ), atendimento a requisies de links .apw aps processada a
funo principal ( U_ResetWebEx ), finalizao da Thread ( U_FinishWebEx ), finalizao
de session de usurio por Time-out ( U_EndSession ), e customizao da mensagem de erro
HTML, quando da ocorrncia de algum erro fatal na aplicao ( U_WEBEXERROR ).
Quando utilizada a infra-estrutura APWEBEX para um mdulo do padro, estes pontos de
entrada no tem efeito. Fica a critrio de cada mdulo a disponibilizao de pontos de
entrada para interceptar estes eventos. Para saber quais pontos foram implementados para
um mdulo web do padro, deve ser consultada a documentao do mdulo
correspondente.

01. STARTWEBEX
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
01. STARTWEBEX ( [ NIL ] ) --> lSucess
Parmetros
Argumento

Tipo

Descrio

NIL

(NULO) Este ponto de entrada no recebe parmetros.

Retorno
Tipo

Descrio

Lgico

lSucess corresponde o status de montagem de ambiente. Caso o ambiente


tenha sido montado com sucesso , o ponto de entrada deve retornar .T. ,
caso contrrio .F. . Uma vez retornado .F. , o Protheus ir eliminar esta
Working Thread da memria.

Descrio
Este ponto de entrada executado na inicializao de cada Working Thread,
quando utilizada a configurao para a Lib APWEBEX.
Atravs dele, devemos iniciar o ambiente necessrio o atendimento das requisies de
processamento via Browser , atravsde links .apw, tais como a abertura de dicionrios e
conexo com o Banco de Dados.
Grupos Relacionados
Principal / A Tecnologia Protheus / Programao Advpl para WEB / Infra-Estrutura
APWEBEX / Pontos de Entrada

02. CONNECTWEBEX
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
02. CONNECTWEBEX ( < cFnLink > ) --> cHtmlVld
Parmetros
Argumento

Tipo

Descrio

cFnLink

Funo chamada atravs do Link . Por exemplo , um link


Caracter no browse chamando http://localhost/w_teste.apw?Opc=03
, seria recebido neste parmetro a string "W_TESTE"

Retorno
Tipo

Descrio

Caracter

Caso retornada uma string em branco , a execuo da funo originalmente


chamada no link .apw prossegue normalmente. Caso contrrio , a string
retornada devolvida ao Browser solicitante , e a funo chamada atravs
do link no executada.

Descrio
Este ponto de entrada executado imediatamente antes do processamento de uma
requisio realizada atravs de um browser para processamento de uma funo Advpl ,
atravs de um link .apw , permitindo realizar uma pr-validao antes de cada
processamento solicitado atravs do Browser.

03. RESETWEBEX
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
03. RESETWEBEX ( < cFnLick > ) --> cHtmlAdd
Parmetros
Argumento

Tipo

Descrio

cFnLick

cFnLink corresponde funo Advpl que foi chamada e


Caracter processada imediatamente antes da chamada deste ponto de
entrada.

Retorno
Tipo

Descrio

Caracter

Este ponto de entrada DEVE retornar uma string , podendo ser inclusive
uma string vazia. A String retornada ser acrescentada ao Codigo Html a
ser retornado ao Browser

Descrio
Este ponto de entrada executado imediatamente aps o processamento de uma requisio
de processamento Advpl atravs de um Web Browser utilizando as configuraes e Lib
APWEBEX.
Ele permite que seja executado um processamento adicional aps o processamento de cada
requisio .apw , e aida permite um retorno de html adicional ao browser.
Vale a pena lembrar que este ponto no ser executado em caso de erro fatal no ponto de
entrada U_CONNECTWEBEX ou na execuo da funo principal chamada atravs do
Link.

04. FINISHWEBEX
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
04. FINISHWEBEX ( ) --> NIL
Parmetros
Argumento

Tipo Descrio

Retorno
Tipo

Descrio

(NULO)

O Retorno deste ponto de entrada no utilizado.

Descrio
Este ponto de entrada executado quando da finalizao ( Fechamento ) de uma Working
Thread APWEBEX. No recebe parmetros , e no requer retorno. Ele permite que seja
executado um procedimento qualquer no momento da sada de uma Working Thread, seja
por time-out ou por tempo total de permanncia no ar.

05. ENDSESSION
Reviso: 10/12/2003
Abrangncia
Verso 7.10

Verso 8.11

LIB WEBEX

Sintaxe
05. ENDSESSION ( < cSessionId > ) --> NIL
Parmetros
Argumento

Tipo

Descrio

cSessionId

Caracter

cSessionId corresponde string identificadora das sessions


deste usurio.

Retorno
Tipo

Descrio

(NULO)

O retorno deste ponto de entrada deve ser nulo

Descrio
Atravs deste ponto de entrada , podemos executar uma rotina Advpl quando da finalizao
das sessions de um usurio por time-out de inatividade. O Retorno deste ponto de entrada
no utilizado, devendo ser nulo (NIL).
Apenas devemos compilar este ponto de entrada no Projeto caso realmente exista a
necessidade de ser executado um processamento especfico relacionado finalizao das
sessions de um usurio. Vale a pena ressaltar tambm que este ponto de entrada apenas
chamado na finalizao das sessions por tempo de inatividade. Caso seja utilizada a funo
httpfreesession() para limpar da memria as sessions do usurio atual em uma Working
Thread, este ponto de entrada no ser chamado.

06. WEBEXERROR
Reviso: 16/12/2003
Abrangncia
LIB WEBEX
Sintaxe
06. WEBEXERROR ( < oErrorObj > , < cErrorLog > , < cErrorHtml > ) --> cMsgHtml
Parmetros
Argumento

Tipo

Descrio

oErrorObj

Objeto Objeto do Erro Advpl.

cErrorLog

Caracter Mensagem ASCII que ser gravada no arquivo error.log

cErrorHtml

Caracter Mensagem Html original da rotina de tratamento de Erro

Retorno
Tipo

Descrio

Caracter

Retorno opcional. Caso retornado NIL ou string vazia , ser retornado ao


usuario o html de erro gerado pela rotina de tratamento standard. Caso o
ponto de entrada retorne uma String HTML , ela ser mostrada ao usurio
no ligar do Html gerado pela rotina de tratamento de erro.

Descrio
Este ponto de entrada ser chamado no caso de uma ocorrncia de erro fatal Advpl durante
a execuo de uma Working Thread em ambiente / Lib APWEBEX, permitindo a
montagem de uma mensagem de erro HTML customizada a ser devolvida o usurio.
Este ponto de entrada recebe como parmetros o objeto do erro , a descrio ASCII
completa do erro gravada no error.log , e o HTML default montado pela da rotina de
tratamento de erro que ser devolvido ao usuario. Atravs da utilizao deste ponto de
entrada , possvel gerar um Html diferenciado conforme a necessidade, para mostrar a
ocorrncia de erro e/ou maiores instrues ao usurio.
OBSERVAES

Independentemente do retorno deste ponto de entrada , a Working Thread que


apresentou ocorrencia de erro ser derrubada apos o retorno do Html para o
Browser , e o arquivo error.log ser gerado normalmente . Caso este ponto de
entrada retorne uma string em branco , ser mostrado ao usurio a mensagem
de erro Html default gerada pela rotina de tratamento de erro.

Este ponto de entrada ser chamado apenas caso a ocorrncia de erro esteja
relacionada com uma chamada de funo via link .apw, aplicando-se apenas
funo .apw chamada e os pontos de entrada U_CONNECTWEBEX e
U_RESETWEBEX. Em caso de ocorrncias de erro no start da Thread
(U_STARTWEBEX), na finalizao da Thread ( U_FINISHWEBEX ) e na
finalizao de sessions de usurio por time-out ( U_ENDSESSION ), o ponto de
entrada U_WEBEXERROR no ser chamado .

Recomenda-se fortemente que , na montagem da funo deste ponto de entrada ,


no seja utilizado nenhum recurso Advpl que dependa de ambiente , disco , base
de dados ou Session , limitando-se apenas customizar uma mensagem de
ocorrncia de erro ao usurio .
Caso seja reproduzida alguma ocorrncia de erro neste ponto de entrada, isto
far a aplicao ( Protheus Server ) enviar ao Browser um Html gerado pela
rotina de tratamento de erro default do Protheus.

A HREF - ncoras e espaos


Reviso: 11/12/2003
Quando passamos parmetros de uma pgina para outra , via query string (URL) , devemos
ter o cuidado de no deixar espao(s) em branco entre parmetros na montagem da URL.
Quando utilizamos o Internet Explorer os espaos em branco so convertidos (*)
automativamente para a sequncia String %20, porm quando utilizamos o Netscape,
quando colocamos um espao em branco em um parmetro , o NetScape IGNORA tudo o
que vem aps o primeiro espao em branco , perdendo assim os demais parmetros.
Consideremos o exemplo abaixo :
<a href='/webinfo.apw?par1=123 &par2=345'>Link</a>
No Internet Explorer no haver problemas (*) , pois os espaos sero convertidos. No
Netscape , o parmetro par2 no ser colocado na URL... A forma correta deve ser
<a href='/webinfo.apw?par1=123%20%20%20&par2=345'>Link</a>
Quando a chamada gerada dinamicamente , devemos utilizar a funo escape() , para
converter caracteres reservados e espaos da stringlist para a notao Hexadecimal (%HH)
para serem enviados corretamente pela URL
<a href='webinfo.apw?par1=<%=Escape(cCodigo)%>&par2=345'>Link</a>
Observao : Vale a pena lembrar que a funo escape() deve ser aplicada apenas os
contedos da stringlist, pois se por exemplo for convertido pela escape() o caracter
separador de parmetros & ( e Comercial ), este caractere ser interpretado como DADO e
no como separador, comprometendo o funcionamento do link.

Combo / Select em Html : Recuperando


valores
Reviso: 11/12/2003
Examinemos o exemplo abaixo , onde criamos um formulrio HTML com um 'Combo Box'
( tag <SELECT> do HTML), de seleo nica , e queremos saber qual o valor que o
usurio selecionou para , por exemplo , validar uma escolha no Browse ( Client ) :
<HTML><BODY>
<form name='exemplo' method='post' action='w_wxxx.apl'>
<SELECT NAME='teste' onChange='javascript:muda()'>
<OPTION VALUE='1'>Valor 1
<OPTION VALUE='2'>Valor 2
<OPTION VALUE='3'>Valor 3
<OPTION VALUE='4'>Valor 4
<OPTION VALUE='5'>Valor 5
</SELECT>
</form>
</BODY></HTML>
<SCRIPT LANGUAGE='JavaScript'>
function muda()
{
// Mostra qual o usuario selecionou
alert(document.exemplo.teste.value);
}
</SCRIPT>
No Internet Explorer , este cdigo funciona perfeitamente . Porm , o NetScape mosstrar o
contedo como null, pois ele no atribui uma propriedade value a um combo partindo de
uma seleo.
Para que seja recuperado o valor do elemento selecionado , utilizamos o cdigo abaixo ,
compatvel com ambos os Browsers.
document.exemplo.teste.options[document.exemplo.teste.selectedIndex].value
Note que utilizamos o array options do controle teste para obter o valor correto , utilizando
o ndice que est selecionado. A funo muda poderia ficar assim:

<SCRIPT LANGUAGE='JavaScript'>
function muda()
{
var val_combo =
document.exemplo.teste.options[document.exemplo.teste.selectedIndex].value;
// Mostra qual o usuario selecionou
alert(val_combo);
}
</SCRIPT>

Diferenas entre os Navegadores IE e


Konqueror
Reviso: 13/04/2004
1. Atualizao de frames com window.open
Ocorrencia : Para chamar uma nova pgina no IE, cujo destino ser o frame atual ou
pgina atual do Browser, podemos usar a funo javascript : window.open( 'xxx.apw',
'_self' ) . No IE (Interbet Explorer) o link chamado aberto no mesmo frame de onde a
instruo chamada, mas no Konqueror esta instruo abre uma nova janela com o nome
'_self'.
Soluo : Utilize a instruo JavaScript window.location para atualizar o endereo da
janela atual ou frame especificado. Por exemplo , window.location='xxx.apw'

Estrutura de Frames em HTML


Reviso: 15/12/2003
Abrangncia
Verses Anteriores
Analisemos a estrutura de frames abaixo :
<HTML>
<frameset framespacing='0' border='0' cols='100,100' frameborder='0'>
<frame name='fr_not' scrolling='no' border='0' marginwidth=8 marginheight=0
src='w_winf067.apl'>
<frame Name='fr_Area' src='' Marginwidth='0' Marginheight='0' Framespacing='0'
Border='0' Frameborder='0' scrolling='auto'>
<noframes>Seu browser no suporta frames</noframes>
</frameset>
</HTML>

Dicas teis

Procurem sempre utilizar a TAG <noframes> para mostrar uma mensagem de erro
no Browse se o mesmo no possuir o recurso de interpretao de frames ( caso este
de navegadores do I.E. 3.0 ou inferiores e netscape 3.0 ou inferiores).

Sempre especifique TODOS os sources (src) de cada frame. Caso seja necessrio
uma pgina em branco como um dos frames , para criao dinmica ou algo
parecido , utilize o source about:blank

Caso um frame da estrutura no tenha a tag src='...' preenchida , o Netscape


mostrar uma janela com a seguinte mensagem quando se entra na pgina de
frames:
'The document contained no data.
Try again later , or contact the server's administrator.'

A tag <body> no suportada. na declarao dos frames. Jamais usem esta tag em
uma estrutura de frames.

Mostrando campos MEMO em Html


Reviso: 15/12/2003
Abrangncia
Verses Anteriores
Para visualizar o contedo de um campo MEMO em uma pgina HTML , devemos realizar
algumas converses de caracteres para o efeito desejado. Em HTML , temos dois modos de
interpretao :
1) Default -> Interpretao HTML , os Caractetes CRLF ( chr(13) / chr(10) ) no so
considerados como pulo de linha , de modo que as quebras de linha so de acordo com o
design aplicado e/ou o tamanho disponvel no browse para a visualizao do dado.
2) Pr-formatado -> Interpretao semelhante um arquivo ASCII , utiliza um tipo de letra
'Regular Type' , mono-espaada , considerando os cdigos CRLF como quebra de linha ,
independente do design aplicado. Definimos uma area a ser interpretada como texto prformatado atravs das tags <pre> ... </pre>
A soluo mais comum para a visualizao de campos Memo ( inclusive foi a soluco
adotada aki no Banco de Conhecimento - DEM ) , a de trocar os cdigos CRLF pela tag
'<br>' , para apenas realizar um pulo de linha no fim do pargrafo. Apenas para textos de
Exemplos de Cdigo ADVPL so utilizadas as tag <pre> .. </pre>, para que a quebra de
linha seja unica e exclusivamente realizada no CRLF , mesmo que o tamanho da tela no

permita mostrar esta quebra ( caso este no qual a tela ou frame ganha uma barra de scroll no
Web Browser ) .
Exemplo ( em arquivo .aph )

<%=strtran( XXX->XXX_MEMO , chr(13)+chr(10) , '<br>' )%>


Caso tenhamos tags interpretveis dentro do memo , que no devam ser interpretadas pelo
browse , mas sim constar como contedo do campo , devemos utilizar a funcao
HtmlNoTags , dentro da expresso anteriormente montada :

<%=strtran( HtmlNoTags(XXX->XXX_MEMO) , chr(13)+chr(10) , '<br>' )%>


Se a funo HtmlNoTags receber como parametro o retorno da StrTran , sero mostrados na
tela as tags '<br>' , que originalmente devem ser interpretadas pelo browse como quebras
de linha.

Refresh em Html / JavaScript


Reviso: 15/12/2003
Abrangncia
Verses Anteriores
Em Html, para setar um refresh automatico da pgina em <n> segundos, utiliza-se uma
etiqueta meta , na seguinte sintaxe :
<meta HTTP-EQUIV='REFRESH' content='<n> [; URL=<url>']>
<n> Tempo em segundos
[<url>] Endereco a ser carregado. (opcional)
Em Javascript, para setar a execuo de uma funo automaticamente em um intervalo de
tempo, podemos utilizar a funo setTimeOut()
Funo setTimeout(<cFunc>,<nTime>)
Ambiente JavaScript
Parametros :
<cFunc> = Nome da funcao em Java a executar
<nTime> = intervalo de execucao (milisegundos)
Observao : Nas funes de Infra-Estrutura APWEBEX, foi criada a funo Advpl
RedirPage(), que monta o script de redirecionamento conforme os parmetros recebidos,
podendo ser especificado o tempo de espera para o redirecionamento e um TARGET
diferenciado para o redirecionamento.

Funes com ADVPL ASP


Reviso: 26/07/2004
Abrangncia
Verso 5.07

Verso 5.08

Verso 6.09

Verso 7.10

Verso 8.11

O cdigo abaixo representa o arquivo ms01.APH, que


contm a parte para Login
de um usuario
<html>
<h2 align="center"> Login </h2>
<hr>
<form name="form1" method="post" action="w_ms02.apw">
<p>Nome : <input name="txt_Nome" type="text" id="txt_Nome"
size="25"></p>
<p>Senha : <input name="txt_Senha" type="password" id="txt_Senha"
size="3" maxlength="3"></p>
<hr>
<p><input type="submit" value="Ok"></p>
</form>
</html>

O cdigo abaixo representa o arquivo ms02.APH, que


contm a parte do formulrio
<html>
<head>
<title>ADVPL ASP</title>
</head>
<script language="javascript">
//Codigo JavaScript no qual no permite que o formulrio seja enviado sem
//que seus campos tenham sido preechidos.
function envia()
{
var oFrm = document.forms[0];
if ( oFrm.txt_Nome.value == "" || oFrm.txt_Pre.value == "" ||

oFrm.txt_Fone.value == "" ||
oFrm.txt_End.value == "" )
{
alert( "Preencha Todos Os Dados Do Formulrio" );
return;
}
oFrm.action = "w_ms03.apw";
oFrm.submit();
}
</script>
<body>
<h2 align="center"> Formulrio</h2>
<hr>
<p>Bem Vindo <%=HttpSession->Usuario%></p>
<form name="form" method="post" action="">
<p>Nome : <input name="txt_Nome" type="text" id="txt_Nome"
size="25" value=""></p>
<p>Telefone : <input name="txt_Pre" type="text"
id="txt_Pre" size="3"> <input name="txt_Fone" type="text"
id="txt_Fone" size="10"></p>
<p>Endereo : <input name="txt_End" type="text"
id="txt_End" size="25"></p>
<p><input type="button" value="Enviar"
onClick="envia()"></p>
</form>
<hr>
</body>
</html>

O cdigo abaixo representa o arquivo ms03.APH, que


contm uma tabela que exibe os dados
preenchidos no formulrio, mais um contador do total de
vezes que foi realizado esse formulrio
<HTML>
<table width="200" border="1">
<tr>
<td width="95">Nome</td>
<td colspan="2"><%=HttpPost->txt_Nome%></td>
</tr>
<tr>
<td width="95">Telefone</td>
<td width="75"><%=HttpPost->txt_Pre %></td>
<td width="75"><%=HttpPost->txt_Fone%></td>
</tr>
<tr>
<td>Endereo;</td>

<td colspan="2"><%=HttpPost->txt_End%></td>
</tr>
<tr>
<td width="95">Contador</td>
<td colspan="2"><%=HttpSession->Contador%></td>
</tr>
</table>
<P>
<input name="Reset" type="reset" value="Voltar"
onClick="window.location = 'w_ms02.apw'">
</P>
</HTML>

O cdigo abaixo representa o arquivo ms01.PRW, que


contm as funes escritas em ADVPL ASP

#INCLUDE "PROTHEUS.CH"
#DEFINE ID "Admin"
#DEFINE SENHA "123"
web function ms01()
//A funo executada quando chamada atravs do browser.
return h_ms01()
web function ms02()
//Verifica se a primeira vez q usurio faz login.
conout( ID, SENHA )
if empty( HttpSession->Usuario )
//Verifica se os campos foram preenchidos.
if empty( HttpPost->txt_Nome ) .And. empty( HttpPost>txt_Senha)
return "Nome e Senha no informados!!"
endif
//Verifica usurio e senha.
if HttpPost->txt_Nome != ID
return "Usurio Invlido!!"
endif
if HttpPost->txt_Senha != SENHA
return "Senha Invlida!!"
endif
//Seta o nome do usuario.
HttpSession->Usuario := HttpPost->txt_Nome
endif
return h_ms02()

web function ms03()


//Verifica se a Sesssion j foi iniciada.
if empty( HttpSession->Contador )
HttpSession->Contador := 1
//caso tenha sido, incrementa o contador.
else
HttpSession->Contador++
endif
return h_ms03()

Upload de arquivo via HTTP


Reviso: 05/10/2004
Abrangncia
Verso 7.10

Verso 8.11

Este exemplo de ADVPL ASP mostra como realizar o upload de um arquivo via HTTP.
O cdigo abaixo representa o arquivo "ms01.APH", que contm um formulrio
para indicar o local do aquivo para upload.
<html>
<head>
<title>Exemplo Upload</title>
</head>
<body>
<table width="500" border="1" align="center" cellpadding="0"
cellspacing="0">
<tr>
<td width="28%" align="right">Path do arquivo : </td>
<td width="2%"> </td>
<td width="70%"><%=httpPost->txtFile%></td>
</tr>
<tr>
<td align="right">Tamanho : </td>
<td> </td>
<td><%=LengthFile%></td>
</tr>
</table>
</body>
</html>
O cdigo abaixo representa o arquivo "upload.APH", que contm um
formulrio para exibir alguns dados do aquivo enviado.
A parte mais importante desse cdigo, se refere a propriedade
(enctype="multipart/form-data") dentro da tag
, essa propriedade garante que o arquivo seja enviado corretamente.
<html>
<head>
<title>Exemplo Upload</title>
<script>
function jUpFile()
{
if( document.form.txtFile.value == "" )
{
alert( "Informe o nome do arquivo clicando em
Browse..." );
return;
}

document.form.action = "w_upFile.apw";
document.form.submit();

}
</script>
</head>
<body>
<form name="form" action="" enctype="multipart/form-data" method="post">
<p align="center">
<font face="Arial, Helvetica, sans-serif" size="3"><b>Exemplo de
upload de arquivos em ADVPL ASP</b></font><br>
<br>
<input name="txtFile" type="file" id="txtFile" size="50">
<br>
<br>
<input name="btnSub" type="button" id="btnSub" value="Subir arquivo"
onClick="jUpFile()">
</p>
</form>
</body>
</html>
O cdigo abaixo representa o arquivo "upload.PRW", que contm as funes
escritas em ADVPL ASP.
#INCLUDE "PROTHEUS.CH"
#INCLUDE "FILEIO.CH"
Web Function upFile()
Local nH := FOpen( httpPost->txtFile, 0 + 64 )
Private LengthFile := 0
LengthFile := fSeek( nH, 0, FS_END )
Return h_RespUpFile()

HTML
Reviso: 13/04/2004
HTML, abreviao para 'HyperText Markup Language', que significa 'Linguagem de
Formatao de HyperTexto'
HTML a formatao padro adotada para a publicao de HyperTexto na Internet (World
Wide Web). O HTML consiste em uma formatao no-proprietria, baseada no SGML (
Standard Generalized Markup Language ), e pode ser criada e processada por um grande
nmero de ferramentas, desde editores de texto-plano ( como o NotePad, por exemplo), at
sofisticados 'softwares de autoria' WYSIWYG (What You See Is What You Get) .
Basicamente, o HTML utiliza-se dos marcadores < e > para estruturar e formatar texto. Por
exemplo:
Letra normal, <b>negrito</b> e <u>sublinhado </u>
A linha de texto acima, representada em um Web Browser, seria mostrada assim :
Letra normal, negrito e sublinhado

HTTP
Reviso: 13/04/2004
HTTP a abreviao de 'Hyper Text Transfer Protocol', que significa 'Protocolo de
Transferncia de Hyper-Texto'.
O HTTP um protocolo em nvel de aplicao para distribuio de informaes. Trata-se
de um protocolo genrico, que pode ser utilizado para muitas outras aplicaes alm de
transferncia de hypertexto, como nomear servidores e trocas de informaes entre sistemas
integrados, utilizando-se suas extenses, cdigos de erro, mtodos de requisio e
cabealhos (Headers). Uma caracterstica importante do HTTP a tipagem e normalizao
da representao da informao, permitindo a construo de sistemas independente do
modo pelo qual os dados esto sendo transferidos.

Threads e working threads


Reviso: 13/04/2004
O que uma Thread?
A maioria dos programadores est familiarizada com programas de execuo sequncial.
Voc provavelmente j deve ter escrito um programa que mostra 'Ol Mundo' ou ordena
uma lista de nomes, ou calcula uma lista de nmeros primos. Estes programas so
sequenciais, e cada um deles tm um comeo, uma sequncia de execuo e um final . Em
qualquer momento da execuo do programa, temos apenas um ponto de execuo.
Uma Thread semelhante o programa descrito acima, tendo um comeo, meio e fim.
Porm, uma Thread em si no um programa, pois ela no se executa : ela roda (com) o
programa !
Por definio : Uma Thread o fluxo seqencial de controle nico dentro de um
programa.
No h nada de novo ou especial sobre programas sequenciais executados em uma simples
thread. A grande sacada consiste no uso de Mltiplas Threasds dentro de uma aplicao,
todas em execuo simultnea, porm cada uma realizando tarefas diferentes.
De tal modo que, por estarem realizando tatefas independenres, cada thread possui o seu
prprio contexto de execuo, alocao de memria e controle de pilha de execuo
(Stack). O cdigo em execuo em uma Thread trabalha dentro de seu contexto especfico,
de modo que vrias outras documentaes referem-se ao 'contexto de execuo' como
sendo um sinnimo de Thread.
Working threads
Damos o nome de 'working thread' quando so iniciadas mais de uma thread independente
na aplicao, e todas as threads iniciadas so colocadas em 'modo de espera' (idle),
aguardando uma solicitao de processamento da aplicao. Mais de uma solicitao pode
ser realizada, e o ncleo da aplicao encarrega-se de distribuir os processamentos entre as
threads disponiveis. Terminado o processamento de uma thread, a mesma retorna ao 'modo
de espera', estando pronta novamente para atender uma nova solicitao. Este recurso
possibilita um ganho significativo de performance, por no haver a necessidade de criar e
finalizar uma nova thread para cada solicitao de processamento.