Você está na página 1de 143

Programação Advpl para WEB

Revisão: 27/04/2004

Abrangência

Versão 7.10 Versão 8.11

Este tópico engloba todo o conhecimento e informações necessárias para usufruirmos da


tecnologia implementada na ferramenta Protheus e de sua Infra-Estrutura, para o
desenvolvimento de aplicações orientadas à Internet.

O objetivo desta seção é centralizar as informações pertinentes ao desenvolvimento de


projetos WEB, em uma ferramenta que permita o acesso e atualizações destes dados de
maneira rápida e dinâmica, além de mostrar uma boa parte do que é possível fazer
utilizando-se dos recursos disponíveis na ferramenta Protheus.

Para que seja possível compreender as funcionalidades e tecnologias envolvidas no


processo de desenvolvimento de uma aplicação WEB, utilizando-se da
ferramenta Protheus, é de fundamental importância que os tópicos deste grupo sejam
lidos e assimilados, pois nos mesmos encontram-se as informações que servem de base
para a compreensão e consequente melhor aproveitamento dos recursos disponíveis.

Para se ter uma idéia superficial do poder do Protheus como servidor http, esta
aplicação ( DEM - Documentação Eletrônica Microsiga ) foi escrita em Advpl-ASP,
utilizando uma compilação do Server Protheus ISAPI , integrado com o IIS 5, utilizando
um Banco de Dados SQL Server 2000 através do TopConnect 4, utilizando se de
Working Threads Extended (WEBEX) e das funções de Infra-Estrutura da lib
APWEBEX.
01. O Servidor Protheus como um
servidor HTTP
Revisão: 27/04/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 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 requisições dos protocolos HTTP e/ou FTP, do
mesmo modo que outros servidores conhecidos no mercado (por exemplo, o IIS –
Internet Information Server, da Microsoft (R) ou o Apache para Linux). Assim, basta ter
o Protheus para poder criar sua própria Intranet num ambiente de rede local, ou publicar
o endereço IP da máquina com o servidor Protheus na Internet e executar funções
através de RPC ou simplesmente criar o seu próprio Web Site com páginas HTML
estáticas ou dinâmicas.

Serviço de HTTP

O protocolo HTTP (Hyper Text Transfer Protocol) é o protocolo utilizado na


comunicação entre um servidor e um Web Browser. É o protocolo utilizado para o
envio e recebimento de páginas formatadas em padrões SGML (HTML,XML, etc). Este
protocolo se baseia principalmente em dois comandos: GET e POST. O comando GET
é utilizado para obter alguma informação do servidor HTTP e o POST para “postar”
informações para o servidor. Mas adiante, será mais fácil compreender onde tais
comandos são utilizados no servidor Protheus.

Utilizando o servidor Protheus como um servidor HTTP, o mesmo poderá ser acessado
através de um Web Browser como o Internet Explorer por exemplo, que receberá as
páginas HTML enviadas de um diretório configurado no servidor. Adicionalmente ao
envio e recebimento de páginas estáticas formatadas, pode-se utilizar a linguagem
Advpl do Protheus para processar páginas mistas, que contém código Advpl e
comandos HTML de formatação. Tais páginas serão processadas no servidor Protheus,
e então enviadar para o Web Browser, que irá formatá-las de acordo com os comandos
HTML contidos. Também é possível executar diretamente funções compiladas no
repositório do Protheus, através de um request HTTP (por exemplo, através de um
POST em um formulário em HTML, ou de um link, ou mesmo diretamente na linha de
URL do Web Browser. O mesmo vale para qualquer outra aplicação que seja capaz de
efetuar comandos GET ou POST utilizando o protocolo HTTP).

Páginas Dinâmicas e Advpl ASP

Quando é utilizado o servidor Protheus para desenvolvimento de aplicações Web, é


possível lançar mão do recurso de criação de páginas dinâmicas, isto é, uma
requisição HTTP realizada ào Server Protheus, devidamente configurado para atendê-
la, dispara o processamento de uma função no Servidor, e esta função encarrega-se de
devolver ào usuário uma página HTML com o resultado do processamento.

Para viabilizar o desenvolvimento deste tipo de função, foi criado um tipo de arquivo
especial no Protheus IDE, com a extensão .APH, onde é inserido um conteúdo Html a
ser enviado ao Web Browser, e instruções Advpl que serão processadas no momento em
que a página for solicitada ao servidor Protheus, sendo possível de forma
prática 'mesclar' um conteúdo gerado por este processamento à uma página Html para
ser retornado ào Web Browser.

Nos tópicos abaixo relacionados, será visto em mais detalhes as configurações


necessárias para atender à estas requisições, as características particulares de cada uma
delas, e as funções de infra-estrutura criadas para auxiliar o desenvolvimento de
aplicações Web.

Além da criação de arquivos, foi disponibilizado no repositório padrão do Protheus as


funções de infra-estrutura ApWebEx, desenvolvidas para permitir um melhor
aproveitamento dos recursos disponibilizados pela ferramenta Protheus para o
desenvolvimento de soluções Web. Estas funcionalidades são exploradas no tópico
Infra-Estrutura ApWebEx.

02. Executando funções Advpl via HTTP


Revisão: 28/04/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Princípio de Funcionamento do HTTP

A utilização do protocolo HTTP não envolve o uso de uma conexão persistente entre o
Web Browser e o Servidor HTTP : Isto significa que, ao ser solicitada uma página,
imagem ou até o processamento de uma função, o Web Browser abre uma conexão com
o Server HTTP, realiza a solicitação e fica com a conexão aberta, aguardando pelo
retorno do Server. Quando o server já houver enviado os dados solicitados, a conexão é
fechada .

Processamento de Funções
Para o retorno de páginas estáticas, imagens e demais arquivos via HTTP, o servidor
identifica o que está sendo solicitado pelo Web Browser através da extensão do Link.
Por exemplo, ao receber uma soilicitação 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 extensões de Link para permitir a


execução de funções Advpl através de uma requisição HTTP : A extensão .APL e a
extrensão .APW . Quando o servidor recebe uma requisição via HTTP, por exemplo da
url http://oservidor/time.apl, e está corretamente configurado para atender à esta
requisição, 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 .

Características comuns do processamento de funções Advpl via HTTP

Independente da extensão de link utilizada, existem características e pré-requisitos


comuns ao funcionamento de ambas as requisições, que seguem abaixo :

A função, seja Advpl ou uma função compilada no Repositório, 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 requisição não ter relação alguma com a interface Remote
do Protheus, não é possível utilizar determinadas funções Advpl que foram
escritas exclusivamente para esta interface, como por exemplo as funções
MsgStop, Alert, e demais funções e objetos de Interface de Janelas.

O que irá diferenciar uma função executada via link .apl e .apw será as etapas de
execução das mesmas. Esta característica de funcionamento será melhor esclarecida
após a leitura dos tópicos sobre desenvolvimento de funções .apl e desenvolvimento
de funções .apw

03. Páginas dinâmicas - O Advpl ASP


Revisão: 26/04/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Uma página ASP (Active Server Pages) é uma página HTML contendo código
interpretável em uma linguagem compreensível ao servidor HTTP em uso. Por
exemplo, o IIS da Microsoft utiliza o VBScript para criar suas páginas ASP, do mesmo
modo que o Protheus utiliza o ADVPL. Uma página ASP é uma combinação de script
HTML e código interpretável. No ADVPL ASP esse código é padrão xBase, portanto a
preocupação maior daqueles que já conhecem e trabalham com o Protheus e desejam
desenvolver páginas ativas para aplicações Web utilizando essa facilidade é conhecer
HTML.

Características do ADVPL ASP - Arquivos .APH

Os arquivos ADVPL ASP têm a extensão padrão .APH. São arquivos texto e devem ser
adicionados a um projeto no Protheus IDE e compilados da mesma maneira que os
programas tradicionais. A diferença é que o Protheus Server identificará que se trata de
um ADVPL ASP e executará uma espécie de tradutor (parser) antes que a compilação
seja executada. Este parser irá transformar todo o arquivo em uma função única, que
receberá os mesmos parâmetros das funções APL simples, como explicado
anteriormente no Item 'Desenvolvendo Funções .APL', e retornará uma string.

O desenvolvedor não precisa se preocupar em retornar HMTL algum, pois o APH


também é um arquivo HTML. A função que foi gerada na compilação irá se encarregar
de retornar o HTML contigo no arquivo, depois que o código foi processado. Um
Arquivo APH gera no repositório de Objetos do Protheus uma função com o mesmo
nome do arquivo , porém prefixada com H_ + nome_do_arquivo_aph

Por se tornar uma função no momento da compilação, não é possível utilizar a cláusula
FUNCTION para criar outras funções dentro de um arquivo APH. Caso exista essa
necessidade, tais funções devem ser criadas em um arquivo PRW tradicional e
chamadas de dentro do APH.

A extensão APH para o nome dos arquivos é obrigatória. Qualquer outra extensão usada
no nome do arquivo não será reconhecida e o parser do IDE não será executado durante
a compilação. Foi criada também a extensão de arquivos .AHU ( Aph de Usuário ), que
possui o mesmo tratamento de Parser do aruqivo APH , gerando uma função prefixada
com L_ . A diferença é que a função gerada pelo AHU pode ser gerada sem a
necessiade de autorização de compilação com permissão para substituir fontes
microsiga , por tratar-se de um Aph de Usuário, qeuivalente à uma User Function .

Assim como outros ASP´s, a diferenciação entre script HTML e código é efetuada
através dos caracteres <% para indicação de abertura de código e %> para indicação do
encerramento de código. Por exemplo, o HTML abaixo contém um pedaço de código
ADVPL separado pelos delimitadores:

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


<body>
<p>Bem vindo ao mundo do ADVPL ASP!</p>
<%
// Soma os 100 primeiros números
Local i, nSoma := 0
For i := 1 To 100
NSoma += i
Next i
%>
</body>
</html>

Quando este arquivo for requisitado ao Protheus Server (através de uma chamada em
URL por exemplo) o código entre os delimitadores será executado, porém o script
colocado ao redor do código será mantido exatamente como se encontra. Por exemplo :

http://localhost/H_WEBDEMO.APL

A grande vantagem de se utilizar dos arquivos ADVPL ASP em relação a criar funções
APL simples, decorre do fato de que nas funções APL simples o desenvolvedor deve se
preocupar em retornar todo o HTML necessário para a correta exibição no Web
Browser.

E também, como o ADVPL ASP mistura o script HTML com o código interpretável,
pode-se criar um arquivo APH utilizando o editor desejado (como o Microsoft
FrontPage, por exemplo) e inserir nele os códigos Advpl necessários entre as Tags.
Outro detalhe importante é que pode-se utilizar as estruturas de fluxo da linguagem
ADVPL para repetir comandos do próprio script HTML (por exemplo, colocar um
comando de script HTML dentro de um comando While em ADVPL):

<% While !EOF() %>


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

Note que também pode existir diferentes blocos de código interpretável separados pelos
delimitadores, dentro de um mesmo arquivo.

Tão importante quanto mesclar código interpretável com script de formatação HTML, é
utilizar os comandos ADVPL para alterar o script de formatação. Ou seja, colocar o
conteúdo de variáveis, campos, etc, diretamente no HTML que será enviado à aplicação
client (ao Browser por exemplo). Isso pode ser realizado através dos delimitadores de
avaliação. Os delimitadores de avaliação são <%= para abertura e %> para
encerramento. Diferentemente dos delimitadores de código interpretável, estes devem
sempre estar na mesma linha. Com eles pode-se criar uma linha de script HTML, cujo
conteúdo contém uma expressão que será avaliada em tempo de execução, e seu
resultado inserido como parte do Html retornado ào Browse :

<b>Esta linha é HTML, mas o horário exibido aqui: <%= Time() %> foi obtido em
tempo de execução no Servidor.</b>

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

Utilizando todos esses conceitos, pode-se criar toda uma aplicação 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


utilização dos delimitadores de execução e avaliação Advpl :

1. A Abertura e fechamendo dos delimitadores de execução <% ... %> devem estar
isoladas em suas respectivas linhas, não devendo ter qualquer conteudo adicional, nem
duas aberturas e fechamentos na mesma linha. Partindo dessa premissa, veja abaixo
alguns exemplos de como inserir o código 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 avaliação <%= ... %> , podemos ter várias aberturas e
fechamentos na mesma lionha , porém não podemos ter uma abertura e seu respectivo
fechamento em linhas diferentes.
3. Uma linha qualquer em um arquivo .APH nao deve conter mais do que 150
Caracteres, pois o Parser insere caracteres de controle em cada linha do mesmo durante
a pré-compilação . e a linha final resultante não pode ultrapassar 254 caracteres, pois
neste caso isto impossibilita a compilação do APH.
02. Executando funções Advpl via HTTP
Revisão: 28/04/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Princípio de Funcionamento do HTTP

A utilização do protocolo HTTP não envolve o uso de uma conexão persistente entre o
Web Browser e o Servidor HTTP : Isto significa que, ao ser solicitada uma página,
imagem ou até o processamento de uma função, o Web Browser abre uma conexão com
o Server HTTP, realiza a solicitação e fica com a conexão aberta, aguardando pelo
retorno do Server. Quando o server já houver enviado os dados solicitados, a conexão é
fechada .

Processamento de Funções

Para o retorno de páginas estáticas, imagens e demais arquivos via HTTP, o servidor
identifica o que está sendo solicitado pelo Web Browser através da extensão do Link.
Por exemplo, ao receber uma soilicitação 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 extensões de Link para permitir a


execução de funções Advpl através de uma requisição HTTP : A extensão .APL e a
extrensão .APW . Quando o servidor recebe uma requisição via HTTP, por exemplo da
url http://oservidor/time.apl, e está corretamente configurado para atender à esta
requisição, 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 .

Características comuns do processamento de funções Advpl via HTTP

Independente da extensão de link utilizada, existem características e pré-requisitos


comuns ao funcionamento de ambas as requisições, que seguem abaixo :

A função, seja Advpl ou uma função compilada no Repositório, 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 requisição não ter relação alguma com a interface Remote
do Protheus, não é possível utilizar determinadas funções Advpl que foram
escritas exclusivamente para esta interface, como por exemplo as funções
MsgStop, Alert, e demais funções e objetos de Interface de Janelas.
O que irá diferenciar uma função executada via link .apl e .apw será as etapas de
execução das mesmas. Esta característica de funcionamento será melhor esclarecida
após a leitura dos tópicos sobre desenvolvimento de funções .apl e desenvolvimento
de funções .apw
03. Páginas dinâmicas - O Advpl ASP
Revisão: 26/04/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

Uma página ASP (Active Server Pages) é uma página HTML contendo código
interpretável em uma linguagem compreensível ao servidor HTTP em uso. Por
exemplo, o IIS da Microsoft utiliza o VBScript para criar suas páginas ASP, do mesmo
modo que o Protheus utiliza o ADVPL. Uma página ASP é uma combinação de script
HTML e código interpretável. No ADVPL ASP esse código é padrão xBase, portanto a
preocupação maior daqueles que já conhecem e trabalham com o Protheus e desejam
desenvolver páginas ativas para aplicações Web utilizando essa facilidade é conhecer
HTML.

Características do ADVPL ASP - Arquivos .APH

Os arquivos ADVPL ASP têm a extensão padrão .APH. São arquivos texto e devem ser
adicionados a um projeto no Protheus IDE e compilados da mesma maneira que os
programas tradicionais. A diferença é que o Protheus Server identificará que se trata de
um ADVPL ASP e executará uma espécie de tradutor (parser) antes que a compilação
seja executada. Este parser irá transformar todo o arquivo em uma função única, que
receberá os mesmos parâmetros das funções APL simples, como explicado
anteriormente no Item 'Desenvolvendo Funções .APL', e retornará uma string.

O desenvolvedor não precisa se preocupar em retornar HMTL algum, pois o APH


também é um arquivo HTML. A função que foi gerada na compilação irá se encarregar
de retornar o HTML contigo no arquivo, depois que o código foi processado. Um
Arquivo APH gera no repositório de Objetos do Protheus uma função com o mesmo
nome do arquivo , porém prefixada com H_ + nome_do_arquivo_aph

Por se tornar uma função no momento da compilação, não é possível utilizar a cláusula
FUNCTION para criar outras funções dentro de um arquivo APH. Caso exista essa
necessidade, tais funções devem ser criadas em um arquivo PRW tradicional e
chamadas de dentro do APH.

A extensão APH para o nome dos arquivos é obrigatória. Qualquer outra extensão usada
no nome do arquivo não será reconhecida e o parser do IDE não será executado durante
a compilação. Foi criada também a extensão de arquivos .AHU ( Aph de Usuário ), que
possui o mesmo tratamento de Parser do aruqivo APH , gerando uma função prefixada
com L_ . A diferença é que a função gerada pelo AHU pode ser gerada sem a
necessiade de autorização de compilação com permissão para substituir fontes
microsiga , por tratar-se de um Aph de Usuário, qeuivalente à uma User Function .
Assim como outros ASP´s, a diferenciação entre script HTML e código é efetuada
através dos caracteres <% para indicação de abertura de código e %> para indicação do
encerramento de código. Por exemplo, o HTML abaixo contém um pedaço de código
ADVPL separado pelos delimitadores:

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


<body>
<p>Bem vindo ao mundo do ADVPL ASP!</p>
<%
// Soma os 100 primeiros números
Local i, nSoma := 0
For i := 1 To 100
NSoma += i
Next i
%>
</body>
</html>

Quando este arquivo for requisitado ao Protheus Server (através de uma chamada em
URL por exemplo) o código entre os delimitadores será executado, porém o script
colocado ao redor do código será mantido exatamente como se encontra. Por exemplo :

http://localhost/H_WEBDEMO.APL

A grande vantagem de se utilizar dos arquivos ADVPL ASP em relação a criar funções
APL simples, decorre do fato de que nas funções APL simples o desenvolvedor deve se
preocupar em retornar todo o HTML necessário para a correta exibição no Web
Browser.

E também, como o ADVPL ASP mistura o script HTML com o código interpretável,
pode-se criar um arquivo APH utilizando o editor desejado (como o Microsoft
FrontPage, por exemplo) e inserir nele os códigos Advpl necessários entre as Tags.
Outro detalhe importante é que pode-se utilizar as estruturas de fluxo da linguagem
ADVPL para repetir comandos do próprio script HTML (por exemplo, colocar um
comando de script HTML dentro de um comando While em ADVPL):

<% While !EOF() %>


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

Note que também pode existir diferentes blocos de código interpretável separados pelos
delimitadores, dentro de um mesmo arquivo.

Tão importante quanto mesclar código interpretável com script de formatação HTML, é
utilizar os comandos ADVPL para alterar o script de formatação. Ou seja, colocar o
conteúdo de variáveis, campos, etc, diretamente no HTML que será enviado à aplicação
client (ao Browser por exemplo). Isso pode ser realizado através dos delimitadores de
avaliação. Os delimitadores de avaliação são <%= para abertura e %> para
encerramento. Diferentemente dos delimitadores de código interpretável, estes devem
sempre estar na mesma linha. Com eles pode-se criar uma linha de script HTML, cujo
conteúdo contém uma expressão que será avaliada em tempo de execução, e seu
resultado inserido como parte do Html retornado ào Browse :

<b>Esta linha é HTML, mas o horário exibido aqui: <%= Time() %> foi obtido em
tempo de execução no Servidor.</b>

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

Utilizando todos esses conceitos, pode-se criar toda uma aplicação 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


utilização dos delimitadores de execução e avaliação Advpl :

1. A Abertura e fechamendo dos delimitadores de execução <% ... %> devem estar
isoladas em suas respectivas linhas, não devendo ter qualquer conteudo adicional, nem
duas aberturas e fechamentos na mesma linha. Partindo dessa premissa, veja abaixo
alguns exemplos de como inserir o código 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 avaliação <%= ... %> , podemos ter várias aberturas e
fechamentos na mesma lionha , porém não podemos ter uma abertura e seu respectivo
fechamento em linhas diferentes.

3. Uma linha qualquer em um arquivo .APH nao deve conter mais do que 150
Caracteres, pois o Parser insere caracteres de controle em cada linha do mesmo durante
a pré-compilação . e a linha final resultante não pode ultrapassar 254 caracteres, pois
neste caso isto impossibilita a compilação do APH.
04. Desenvolvimento de Funções .APL
Revisão: 27/04/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

A princípio, todas as funções contidas no repositório podem ser executadas diretamente


através de uma requisição HTTP, via link com extensão .apl, ao Protheus Server.
Porém, alguns detalhes devem ser considerados:

Uma função executada no momento do recebimento de uma requisição HTTP é


executada como um JOB, ou seja, não contem interface. Por isso, tais funções
não podem conter comandos de interface, como criação de janelas ou exibição
de helps e mensagens de alerta;
A única interface possível é a utilizada no client HTTP. Por isso, tais funções
devem SEMPRE retornar uma string de caracteres. Após o processamento da
função, essa string de retorno será enviada diretamente ao client HTTP e este
será o responsável por sua interpretação. Por exemplo, utilizando um Web
Browser como client pode-se retornar a string de comandos HTML diretamente.
O HTML então será propriamente exibido no Web Browser;
Qualquer retorno diferente de uma string de caracteres gerará um erro que será
enviado à aplicação client HTTP (o erro gerado é “Invalid Proc Return”);
O servidor Protheus passa alguns parâmetros para as funções chamadas. Isso
significa que ao criar funções para serem utilizadas em resposta às requisições
HTTP, deve-se criar o cabeçalho da função com estes parâmetros. Não é
obrigatório utilizar os mesmos nomes de parâmetros sugeridos abaixo quando
criar diretamente estas funções. Porém, como são esses os nomes utilizados no
ADVPL ASP explicado mas a frente, é aconselhável utilizá-los por motivo de
padronização:

o __aCookies: Este parâmetro recebe um array bidimensional com os


Cookies criados na aplicação client HTTP (por exemplo, no Internet
Explorer 5). Pode-se utilizá-lo para checar validações mantidas nas
máquinas client por exemplo. Para maiores detalhes, consulte a
documentação do HTML ou do Web Browser utilizado.
o __aPostParms: Este parâmetro recebe um array bidimensional com os
campos contidos em um formulário HTML recebido através de um
comando POST. Cada item deste array contém um array com o nome do
campo e o valor informado. Por exemplo, para um formulário com dois
campos para digitação (um chamado nome e o outro chamado endereco),
que enviam os dados para a função cadastro.apl através de um POST, a
função receberá o array __aPostParms da seguinte forma:
{ {“nome”, “NOME DIGITADO NA PAGINA HTML”},
{“endereco”, “ENDERECO DIGITADO NA PAGINA HTML”} }

A função pode tratar os dados recebidos neste array para realizar um


processamento específico com tais informações. Para campos onde não é
possível a entrada de dados e sim a escolha de uma informação pré-
definida (como por exemplo um checkbox), o item somente existirá no
array caso o campo tenha sido selecionado no formulário HTML (por
exemplo, se o checkbox for marcado).
o __nProcID: Contém o Handle da Thread de execução daquela função. A
utilização deste parâmetro será explicada juntamente com o tópico
ADVPL ASP posteriormente;
o __aProcParms: Este parâmetro recebe um array bidimensional com os
parâmetros enviados na linha de URL do Web Browser. Por exemplo, na
execução de uma função via linha de URL do Web Browser como:
http://servidor/vende.apl?cod=000001&nome=PRODUTO DE
TESTE&quant=20
a função chamada vende receberá o array __aProcParms da seguinte
forma:

{ {“cod”, “000001”},
{“nome”, “PRODUTO DE TESTE”},
{“quant”, “20”} }

A função pode tratar estes dados recebidos para realizar processamentos


específicos. É muito útil também para criar links de execução
diretamente através de um Web Browser.

o __cHTTPPage: Esse parâmetro foi criado originbalmente para recebe o


nome da página, arquivo ou função originalmente requisitada para o
Protheus Server, porém não foi utilizado e permaneceu por
compatibilidade.Caso consultado, ele retorna uma string em branco.
o __aHTTPHead: Esse parâmetro recebe um array com os Headers do
cabeçalho da requisição HTTP enviados pelo Web Browser.

Exemplo de função APL

A função a seguir é um bom exemplo para ser executado através de um Web Browser.
Ela retorna uma string contendo a página HTML onde está escrita a mensagem “Hello
World” e a lista de parâmetros passados na linha de URL. Para testá-la, crie um arquivo
novo no Protheus IDE, cole o código abaixo e salve o arquivo como WEBDEMO.PRW.
Após compilar o programa, basta chamar em um Web Browser uma URL como:

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

Código da função:
#include 'rwmake.ch'

User Function
WebDemo(__aCookies,__aPostParms,__nProcID,__aProcParms,__cHTTPPage)
Local cHTML := ''
Local i

// Coloca uma mensagem em HTML


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

// Coloca um separador de linha em HTML


cHTML += '<hr>'

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

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


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

Next i
Endif

Return(cHTML)

Importante

Para crias as funções que serão utilizadas em chamadas via um Web Browser, ou seja,
em qualquer request HTTP, deve-se seguir o procedimento normal de criação de
funções no AP5: utilizando o AP5 IDE para a edição e para a compilação.

Note que no caso de funções do usuário (User Function) o nome chamado na URL do
Browser também deverá conter o U_ no começo da função, por exemplo:

http://servidor/u_WebDemo.apl

Configuração Mínima

Em tópico à parte é explicada toda a configuração referente à seção http do Protheus


Server. A configuração abaixo é a mínima necessária 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 configuração, reinicie o server Protheus e chame via WebBrowser a url :

http://localhost/time.apl
Deverá ser mostrada no Browse o horário atual, no formato hh:mm:ss, no Servidor, pois
este é o resultado da função Advpl TIME() .

O Protheus atendendo à requisições .apl

Quando solicitado através de um Web Browser um processamento de uma função via


link .apl, a função solicitada deve ser responsável por abrir o ambiente necessário ào
processamento, conectar com o Banco de Dados caso necessário, realizar o
processamento e retornar a String Html ao Web Browser.

Este ambiente criado é fechado imediatamente após o término do processamento, o que


exige muito do Servidor da aplicação em se tratando de uma aplicação web com vários
usuários efetuando acessos simultâneos. Para atender com mais eficiência às requisições
de processamento de um projeto web, foi implementada no Protheus a tecnologia de
'Working Threads', explicada em mais detalhes no tópico 'Desenvolvimento de Funções
.apw'.
05. Desenvolvimento de Funções .APW
Revisão: 26/04/2004

Abrangência

Versão 6.09 Versão 7.10 Versão 8.11

Diferença de Funcionamento entre links .APL e .APW

Como visto em tópicos anteriores, ao desenvolver uma função para ser executada via
link .apl, a função deve ser responsável pela abertura do ambiente e inicializações
necessárias para um processamento qualquer, e após ser finalizado este processamento,
o ambiente montado e utilizado é fechado automaticamente, de modo que cada
requisição de processamento de usuário através de link .apl irá iniciar uma nova Thread,
onde o ambiente deverá ser preparado novamente. A programação neste tipo de
ambiente exige muito do servidor Protheus.

Visando dar perfornance às aplicações 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 configuração especial de job, que
permite configurar um´número pré-definido de Threads no Servidor, as quais terão o
ambiente de execução preparado e inicializado através de uma função Advpl, onde cada
working thread é deixada na memória do servidor em modo de espera (stand-by), de
modo que, um usuário, ao acessar um link .apw, o servidor Protheus irá direcionar a
requisição de processamento à uma working thread que estiver em stand-by, e, após o
processamento ser efetuado e o HTML ser retornado ao Browser, a working thread
retorna novamente ao estado de stand-by, voltando a estar disponível para atender à
uma nova requisição, do mesmo ou de outro usuário navegando no site / aplicação Web.

A utilização de Working Threads exige a definição mínima de duas funções Advpl, que
serão executadas em dois momentos distintos : A primeira função é responsável pela
inicialização do ambiente comum de execução de requisições, devendo estabelecer
conexão com a Base de Dados utilizada, abrir as tabelas utilizadas no Site e preparar as
variáveis comuns de utilização da aplicação. A segunda função será responsável por
encapsular a requisição do usuário realizada a partir do Web Browse : Ela receberá
como parâmetro o nome do link digitado e macro-executar a função correspondente,
realizando o tratamento de erro e retorno.

Deste modo, um ambiente uma vez inicializado não é fechado, e pode ser utilizado por
vários usuários que estão 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 configuráveis no Protheus : a Working Thread
WEB, e a Working Thread WEBEX ( abreviação de WEB EXtended ). Ambas possuem
basicamente o mesmo princípio de funcionamento, porém o que muda entre ambas é a
recepção de parâmetros e a utilização de Sessions nativas do Server Protheus. Para
visualizarmos melhor estas diferenças, vejamos com um detalhe um pouco maior os
modelos de função de inicialização de ambiente e conexão para ambas as configurações
de Working Threads, WEB e WEBEX.

Working Threads WEB

Para nos utilizarmos das Working Threasd WEB, devemos criar as funções
responsáveis pela inicialização de ambiente e a função de conexão.

A função de inicialização de ambiente não recebe parâmetro algum, realizar a


preparação do ambiente comum de execução de requisições, e deve retornar um valor
booleano (.T.) verdadeiro caso o ambiente tenha sido inicializado com sucesso, ou (.F.)
falso no caso de alguma condição ou erro que torne o ambiente montado por esta thread
não operacional, caso este em que a Thread é removida da memória após a inicialização.

A função de conexão recebe os mesmos seis parâmetros de uma função chamada via
link .apl, e um sétimo parametro, String, que contém apenas o nome da função chamada
no link . Por exemplo, a chamada de um link http://localhost/u_teste.apw, no sétimo
parâmetro da função de conexão a string 'u_teste'. A função de conexão deve ter
tratamento de erro próprio e diferenciado, e sempre deverá retornar um conteúdo do tipo
String.

Working Threads WEBEX

Para nos utilizarmos das Working Threasd WEBEX, devemos também criar as funções
responsáveis pela inicialização de ambiente e a função de conexão.

A função de inicialização comporta-se de maneira idêntica a de inicialização WEB, não


recebendo parâmetro algum, e devendo retornar um valor booleano (.T.) verdadeiro
caso o ambiente tenha sido inicializado com sucesso , ou (.F.) falso no caso de alguma
condição ou erro que torne o ambiente montado por esta thread não operacional, caso
este em que a Thread é removida da memória após a inicialização.

A função de conexão não recebe diretamente parâmetro algum ! Isso mesmo : Todos os
parâmetros recebidos em versões anteriores através de Arrays, são recebidos agora por
Alias Virtuais de alta velocidade :

HttpGet
HttpPost
HttpCookies
HttpHeadIn

Cada um destes alias virtuais é responsável respectivamente pela recepção de


parâmetros via GET , POST , COOKIES e Header HTTP da requisição.
Também foram implementados os Alias virtuais HttpHeadOut e HttpSession , para
respecrivamente permitir alterar ou adicionar informações do Header HTTP de retorno
de processamento de uma requisição e utilização de variáveis tipo SESSION por
usuário Web. Estes recursos são detalhados nos tópicos WEBEX - Detalhamento de
Operação e posteriores.

O Futuro das aplicações WEB no Protheus

Após o desenvolvimento de aplicações em ambiente WEBEX, e dados os ótimos


resultados obtidos, recomenda-se fortemente que as aplicações web desenvolvidas
utilizando-se o Protheus Server, sejam escritas em conformidade para a utilização dos
recursos WEBEX.

Para facilitar tal desenvolvimento, em paralelo à tecnologia disponibilizada na


aplicação, já está integrada com a Infra-Estrutura disponível no repositório padrão do
Microsiga Protheus 8 , as funções da Infra-Estrutura ApWebEx, escritas e publicadas
para melhor atender às necessidades comuns verificadas no decorrer do
desenvolvimento de uma aplicação Web.

Os recursos disponíveis nesta lib estão documentados nos tópicos Infra-Estrutura


APWEBEX e posteriores , englobando comandos , funções , exemplos e dicas de
utilização destes recursos.
06. Configurando o Server Protheus para
HTTP
Revisão: 28/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

As configurações de http do Server Protheus permitem a configuração de sites estáticos


e dinâmicos , com a criação de um ou mais hosts de acesso, criação de pastas virtuais, e
dites dinâmicos com resposta para links .apl e .apw simultaneamente. Neste documento
abrangeremos um resumo exemplificado das configurações HTTP do Server Protheus.
As seções abaixo devem ser inseridas no arquivo de configurações do servidor Protheus
( mp8srv.ini )

Configuração Mínima

[http]
Enable=1
Path=c:\Ap_Data\http

Observação: Vale lembrar que , após ter inserido a configuração do [http] no INI do
Protheus, é importante baixar o Server e subir novamente.

Com esta configuração, habilitamos o Server Protheus como um servidor de arquivos e


páginas estáticas , com o HTTP na porta padrão (80), e utilizando o diretorio em
c:\Ap_data\Http como diretório raiz de publicações WEB. Como não há configuração
de host específica, um arquivo nesta pasta poserá ser acessado através dos hosts
http://localhost ( desde que o browse seja aberto na estação servidora ) ,
http://nnn.nnn.nnn.nnn ( IP da estação servidora ) ou http://xxxxxxxxxx ( nome da
estação servidora ) . Por exemplo : Dentro da pasta configurada na chave PATH do
HTTP, crie um arquivo chamado default.htm , com o seguinte conteúdo ( 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 à requisições .apl


Agora, vamos habilitar este host para atender à requisições de funções, através de link
.apl. Para tal , precisamos apenas do nome de um Environment (ambiente) configurado
no .INI . Podemos usar o próprio ambinete do ERP . Basta acrescentarmos na seção http
a chave Environment=<nome_do_ambiente> , para que este ambiente passe a atender
ào processamento de funções Advpl através de links .apl. Por exemlo , caso o ambiente
configurado para o ERP chame-se EnvADS710 , basta acrescentar na seção http a
chave Environment=EnvADS710 . O .INI ficaria conforme abaixo :

[http]
Enable=1
Path=c:\Ap_Data\http
Environment=EnvADS710

Para testar a execução de funções , abra um Web Browse na estação servidora, e acesse
o link http://localhost/time.apl . ISto´irá executar a função Advpl TIME() , que retornará
ao Browse uma string contendo o horário atual no servidor no formato HH:MM:SS

Atendendo à requisições .apw

A configuração para atendimento de requisições de processamento http através de links


.apw envolve a criação de uma nova seção no .INI , com um nome não-específico, para
configurar o tipo de job que irá executar o processamento ( WEB ou WEBEX ) ,
juntamente com as funções responsáveis pela inicialização e conexão das Threads
Advpl , e na seção http configuramos uma chave chamada ResponseJob , apontando
para a seção de configuração do JOB.

Por exemplo , para configurarmos o atendimento de requisições .apw em um ambiente


ERP , utilizando a infra-estrutura APWEBEX , vamos criar uma seção chamada
ERP_APWEBEX, apontando para as funções da Infra-Estrutura APWEBEX
correspondentes :

[ERP_APWEBEX]
type=WEBEX
onstart=STARTWEBEX
onconnect=CONNECTWEBEX
Environment=EnvADS710
Instances=1,3
SigaWeb=MAK

Através desta configuração, especificamos um Job do tipo WEBEX , onde a função de


inicialização utilizada será a STARTWEBEX , a função de conexão será a
CONNECTWEBEX ( ambas da Infra-estrutura APWEBEX ) , que utilizarão o
ambiente AnvADS710 para processamento, e serão colocadas no ar apenas uma
Working Thread para atendimento de processamento, até o máximo de 3 Threads. As
threads colocadas no ar acima do número mínimo ( no exemplo, apenas 1 ) , são
colocadas 'on-demand' caso sejam realizadas requisições .apw ao Servidor e não hajam
Working Threads dispovíveis no momento e o número de Working Threads no ar ainda
não tenha atingido o máximo definido. Através da configuração SigaWeb=MAK,
informamos ao sistema, que a mesma está sendo utilizada para o desenvolvimento de
um módulo específico, e não estamos utilizando um módulo Web da ferramenta
Protheus 8. Caso a configuração SigaWeb não seja informada, o valor 'MAK' é
assumido como default.

Agora , para que esta seção de Jobs seja utilizada para o atendimento efetivo de
requisições .;apw , devemos estecificá-la na seção http , através da chave REsponseJob.
No caso , inserimos a chave ResponseJob=ERP_APWEBEX , fincando a seção HTTP
conforme abaixo:

[http]
Enable=1
Path=c:\Ap_Data\http
Environment=EnvADS710
ResponseJob=ERP_APWEBEX

Como as requisições via .apl e via .apw são independentes , é possível configurar a
seção http para que Environments diferentes respondam à requisições .apl e .apw , ou
que não sejam atendidas requisições .apl , apenas .apw .

Configurando a seção http para multi-host

Todas as configurações acima vistas pertencem à seção default do HTTP . De modo que
, tanto faz acessarmos o servidor pelo nome como pelo IP, que o resultado serrá o
mesmo. Porém, para a utilização de demais recursos, como diretórios virtuais e mais de
um site no mesmo servidor , precisamos configurar um host de acesso.

Por exemplo, vamos criar uma configuração 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 seção 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 seção com este nome .

Nesta seção do INI , devemos no mínimo especificar um Path de acesso àos arquivos, e
as demais configurações vistas até agora da seção http são opcionais. A configuração
PORT do HTTP em um host não é suportada: Não é possível 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 através de LOCALHOST ou do IP
do Server , será permitido o acesso às funcionalidades configuradas na seção HTTP.
Caso seja acessado via nome do servidor ( http://srvteste ) , serão acessados os arquivos
de outra pasta , e as requisições .apl serão atendidas pelo Ambiente EnvTOP710 .

Utilizando este tipo de configuração, podemos subir vários sites diferentes na mesma
aplicação servidor Protheus, cada qual com o seu diretório raiz de publicações , seus
ambientes independentes, atendendo ou nâo à requisições .apl e/ou .apw.

Configurando diretórios virtuais


Ao configurar um host específico, podemos acrescentar ao mesmo uma barra "/",
seguido de um nome para acesso à um diretório virtual, criando desse modo um
endereço de acesso composto por um host e um diretório, que pode se comportar como
um outro site, com os arquivos publicados em um path específico, que poderá atender
requisições de links .apl e/ou .apw sob um outro ambiente e configuração distinta.

Utilizando diretórios virtuais, é possível, dentro do mesmo host, instalar várias


aplicações web independentes, todas acessíveis sob o mesmo endereçõ base, alterando
apenas o diretório de acesso. Por exemplo, utilizando como host principal o nome do
equipamento , "servertst", podemos instalar o módulo Web "Portal Protheus" sob o host
"servertst/portal", o módulo TCF sob o host "servertst/rhonline", e no host "servertst"
podemos configurar um site estático em Html , com uma apresentação institucional e
links para os demais módulos.

Observações Importantes

Ao configurarmos um Host, ele herda as configurações de atendimento de requisições


.apl e .apw especificados na seção HTTP ! De modo que o host do exemplo continuará a
atender requisições .apw , porém no ambiente EnvADS710.

Visto desta forma, recomendamos fortemente que a seção [http] possua apenas
especificado um Path em disco que esteja vazio, e seja criada uma ou mais
configurações de host com as suas devidas propriedades especificas.

Todas as demais chaves relacionadas à configuração HTTP e aos Jobs WEB e WEBEX
são opcionais, para atender à necessiades específicas. Estas chaves estão explicadas em
maiores detalhes no DEM , na seção XXX

Configurando diretórios virtuais

Da mesma forma que a criação de hosts, podemos criar um novo host utilizando a barra
de divisão '/' 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 documentação que deve estar disponçivel na web , utilizando
também o host http://srvteste . Porém , o host srvteste já aponta para o diretório
c:\Ap_data\Testes.

Com o recurso de criação de diretorio virtual no HTTP , criamos apenas uma nova
entrada do mesmo host , colocando no nome do mesmo uma barra de divisão'/' , seguido
do nome de uma pasta a ser acessada via HTTP ( que não precisa necessariamente
existir no disco) , e dentro desta seção acrescentar a chave path , apontando para o
diretório 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
endereço http://srvteste/info , a partir dele serão 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 configurações acima
exemplificadas :

;; Configuiracao de Working Threads usando a infra-estrutura APWEBEX


[ERP_APWEBEX]
type=WEBEX
onstart=STARTWEBEX
onconnect=CONNECTWEBEX
Environment=EnvADS710
Instances=1,3

;; Configuração da seção httpo default para atender à requisições de .apl e .apw


[http]
Enable=1
Path=c:\Ap_Data\http
Environment=EnvADS710
ResponseJob=ERP_APWEBEX
SigaWeb=MAK

;; Configuração do host srvteste para atender requisições via .apl através do


environment EnvTOP710
[srvteste]
Path=c:\Ap_Data\Testes
Environment=EnvTOP710

;; Configuração 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
Revisão: 27/04/2004

Abrangência

Versão 8.11

A Infra-Estrutura APWEBEX

Visando o melhor aproveitamento da tecnologia de working threads, implementada no


servidor Protheus para o processamento de requisições de uma aplicação web, foram
desenvolvidas funções de apoio, miscelânea e infra-estrutura, compiladas no repositório
padrão de Infra-Estrutura do ERP Microsiga, visando simplificar e auxiliar o
desenvolvimento de uma solução web. A este conjunto de funções , demos o nome de
"Lib de Infra-Estrutura APWEBEX", que engloba atualmente os tratamentos comuns às
funções de inicialização de ambiente e conexão ( atendimento de requisições http via
link .apw ), com seus respectivos pontos de entrada, comandos e funções de miscelânea
comuns àos projetos de soluções web integradas com o ERP.

Como utilizar este recurso no desenvolvimento de soluções ?

As funções pertinentes à Infra-Estrutura APWEBEX já estão implementadas no


repositório padrão da ferramenta Protheus 8, e os comandos específicos que envolvem
este recurso encontram-se no arquivo header 'apwebex.ch', disponibilizado também
jonto com a ferramenta Protheus 8.

A utilização destes recursos para integração de aplicações envolve a leitura desta


documentação, onde será visto com maiores detalhes as possibilidades de uso da
ferramenta, como a integração de uma aplicação Web com um ambiente e
funcionalidades do ERP Microsiga.

Como usufruir desta documentação ?

Todos os tópicos pertencentes à este grupo são direcionados ào desenvolvimento de


soluções web utilizando as funções de Infra-Estrutura APWEBEX, além de ser
explicado com detalhes o funcionamento da tecnologia WEBEX do Protheus, e dos
recursos nativos da ferramenta, englobando os comandos e funções publicados,
exemplos de códigos Advpl utilizando estes recursos, configuração da ferramenta e
mensagens de ocorrências de erro das funções e comandos, com possíveis causas e
soluções.

É fortemente recomendado que os documentos constantes neste grupo fossem


apreciados, antes de aprofundar-se nas informações dos próximos tópicos.
01. Recepção de parâmetros por Alias
Virtuais
Revisão: 30/04/2004

Abrangência

Versão 7.10 Versão 8.11

A recepção de parâmetros vindos do Web Browser, quando utilizamos Working


Threads do tipo WEBEX, através de links .apw, é realizada através de Alias Virtuais
específicos, ao invés de receber as informações GET , POST e HEADER em array,
quando executamos a chamada através de link .apl. A nomenclatura de 'Alias Virtual'
foi adotada, pois a sintaxe do código-fonte é exatamente a mesma utilizada quando
desejamos acessar um campo de uma tabela aberta, através de um alias.

Em um ambiente montado para atender à requisições via link .apw utilizando Working
Threads WEBEX , podemos nos utilizar dos seguintes alias virtuais :

HttpCookies
HttpGet
HttpPost
HttpHeadIn
HttpHeadOut
HttpSession

HttpCookies

Através do alias virtual HttpCookies, é possível consultar os Cookies do Header Http


enviados pelo Browser, e criar ou alterar o conteúdo de um cookie a ser devolvido ào
Browser. Um cookie, visto de forma geral, é um parâmetro ao qual atribuímos um
nome, que uma vez devolvido ào Browse solicitante, é re-enviado ao Protheus a partir
da próxima requisição realizada pelo Browser.

HttpGet

Para receber os parâmetros enviados através da URL (método 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 parâmetros submetidos (enviados) pelo Browser através do método


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 recepção e tratamento das informações recebidas através do Header do pacote


HTTP, foi criado o alias virtual HttpHeadIn, que além de consultar as informações
constantes no Header HTTP proveinente da requisição do usuário, permite também
acesso à propriedades da conexão atual do usuário, como o IP do usuário solicitante, por
exemplo.

HttpHeadOut

Através deste alias virtual de retorno, podemos alterar ou criar um parâmetro no Header
de retorno HTTP do Protheus , a ser devolvido ào Browser solicitante de uma requisição
de processamento.

HttpSession

O alias virtual HttpSession foi criado para possibilitar a criação de variáveis 'session'
por usuário do site, com controle de identificação nativa da ferramenta através de um
cookie de identificação , chamado SESSIONID. No tópico 'Alias Virtual HttpSession' é
explicado em detalhes o funcionamento deste mecanismo.

Este recurso nos permite criar , atricuir conteúdo e consultar conteúdo de uma variável
relacionada ào usuário que está realizando uma requisição http. Podemos armazenar em
uma variável de Session os seguintes tipos de variáveis : A (array) , C (character) , D
(data), L (lógica) e N (numérica) . Não são suportados O (Objetos) e/ou B (Code
Blocks).

Limitações de uso dos alias virtuais para recebimento de parãmetros

Dadas as características operacionais e de acesso àos alias virtuais, devemos estar


atentos à nomenclatura de campos de um formulário HTML, para serem recuperados
com sucesso pelos alias virtuais correspondentes. A nomenclatura de campos do
formulário deve obedecer à regra de criação de variáveis em Advpl : O campo do
formulário deve sempre ser iniciado com um caracter alfabético, pode conter letras ou
algarismos no nome, e o caracter "_" ( underline ). Não são permititos espaçõs, hífen ou
caracteres acentuados como nome de um campo. Caso utilizado um nome de campo
fora do padrão suportado, o conteúdo do mesmo não será recuperável em Advpl.
02. Alias virtual HttpCookies
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Através do alias virtual HttpCookies, é possível consultar os Cookies do Header Http


enviados pelo Browser, e criar ou alterar o conteúdo de um cookie a ser devolvido ào
Browser. Uma variável de Cookie retorna um tipo Advpl String , e apenas aceita uma
atruibuição de String. Vale lembrar também que um cookie é um recurso do Browser
que está realizando a requisição, e existe um limite de tamanho para o total de Cookies
utilizados. Este limite costuma ser próximo a 1024 Bytes .

Trata-se portanto de uma propriedade de leitura e gravação, dispnível apenas quando a


função Advpl é executada através de uma requisição http via link .apw utilizando a
configuração de Working Threads WEBEX.

Utilização de Cookies

A utilização de Cookies têm objetivo prático restrito à aplicações onde haja a


necessidade implícita de termos uma informação relacionada ào browser utilizado pelo
usuário atual, que devam ser interpretadas independente do usuário estar logado ou não
( isto é , independam diretamente de sessions ).

Um exemplo prático disto é o desenvolvimento de um site onde o conteúdo dinâmico é


retornado ao usuário em mais de um idioma. Na entrada do site, apresentamos um
formulário ao usuário onde o mesmo irá escolher o idioma de sua preferência. Mesmo
que a session de login deste usuário expire no servidor, o cookie com o idioma
selecionado ainda está no Browser, de modo que a próxima requisição do usuário pode
ser codificada para direcioná-lo para a página de login do site com as mensagens
no idioma que o mesmo já estava navegando.

Lendo o valor de um Cookie

Através dos exemplos abaixo , lemos o valor do Cookie de identificação do úsuário, e


um cookie de usuário criado para identificar no Browse qual é o idioma utilizado pelo
usuário atual.

cUserId := HttpCookies->USERID // Retorna o Cookie identificador do usuário do


Protheus
cIdioma := HttpCookies->SiteLang // Retorna o conteúdo 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 criação de um Cookie é realizada através da atrubuição de um valor diretamente ào


cookie desejado. Por exemplo :

HttpCookies->MeuCookie := 'TESTE'

A criação de um Cookie merece uma atenção especial, pois um Cookie é retornado ào


browser através do Header de Retorno HTTP. De modo que, para que a criação de um
cookie seja realizada com sucesso , o mesmo deve ser criado antes de haver qualquer
processamento de APH / AHU, caso este que não seria mais possível a criação do
Cookie, pois o Header de Retorno HTTP já teria sido enviado ào browser solicitante.
03. Alias virtual HttpGet
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Através do alias virtual HttpGet, podemos consultar se uma determinada propriedade


nos foi enviada através da URL ( método GET ).

Trata-se portanto de uma propriedade de leitura (read-only), disponível apenas quando a


função Advpl é executada através de uma requisição http via link .apw utilizando a
configuração de Working Threads WEBEX.

Consultando um Parâmetro

O retorno da consulta de um parâmetro pode ter dois tipos : NIL , caso o parâmetro não
tenha sido enviado , ou String , contendo o conteúdo do parâmetro. Por exemplo, vamos
realizar uma requisição a um link .apw , passando pela URL o parâmetro IMAGEM ,
com o contéúdo TESTE :

http://localhost/u_TesteGet.apw?imagem=teste&cor=azul

Para recuperarmos em Advpl o conteúdo dos parâmetros imagem e cor , utilizamos:

cImagem := HttpGet->imagem
cCor := HttpGet->cor

Podemos inserir também um tratamento default : Caso algum parâmetro não seja
enviado ( resulte NIL ) , assumimos um valor para o mesmo

DEFAULT cImagem := 'LogoAp8'


DEFAULT cCor := 'amarelo'

Existe também uma propriedade do alias virtual HttpGet chamada aGets , onde
podemos recuperar um array de strings , contendo a lista com os nomes dos parâmetros
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
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Através do alias virtual HttpPost, podemos consultar os campos submetidos ào servidor


através do método POST.

Trata-se portanto de uma propriedade de leitura (read-only), disponível apenas quando a


função Advpl é executada através de uma requisição http via link .apw utilizando a
configuração de Working Threads WEBEX.

Consultando um Parâmetro

O retorno da consulta de um parâmetro pode ter dois tipos : NIL , caso o parâmetro não
tenha sido enviado , ou String , contendo o conteúdo do parâmetro. Por exemplo, vamos
realizar uma requisição a um link .apw , através de um formulário html com método
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 conteúdo do campo CODIGO, utilizamos:

cCodigo := HttpPOST->Codigo

Existe também uma propriedade do alias virtual chamada aPost , onde podemos
recuperar um array de strings , contendo a lista com os nomes dos parâmetros 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
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Através do alias virtual HttpHeadIn, podemos consultar os parâmetros enviados pelo


Browser solicitante enviados através do Header HTTP ao realizar uma requisição ao
Protheus Server.

Trata-se portanto de uma propriedade de leitura (read-only), disponível apenas quando a


função Advpl é executada através de uma requisição http via link .apw utilizando a
configuração de Working Threads WEBEX.

Consultando um Parâmetro

O retorno da consulta de um parâmetro pode ter dois tipos : NIL , caso o parâmetro não
tenha sido enviado , ou String , contendo o conteúdo do parâmetro. 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)

Observação Importante :

Qualquer parâmetro no Header HTTP que contenha um ou mais caracteres inválidos


para a nomenclatura de variáveis Advpl , ( como por exemplo o User-Agent , que
contém um hífen ), são trocados pelo caractere '_' underline , para ser possível a leitura
da propriedade.

Propriedades especiais

HttpHeadIn->aHeaders

Retorna um Array de Strings , contendo todas as linhas do Header HTTP da requisição.

HttpHeadIn->main

Retorna o nome da função chamda através da URL , sem a extensão e sem o host. Por
exemplo , ao chamar o link http://localhost/u_tstHEader.apw , o conteúdo de
HttpHeadin->main será 'u_tstHEader'
HttpHeadIn->REMOTE_ADDR

Retorna uma string , no formato nnn.nnn.nnn.nnn , o IP da estação que realizou a


requisição.

httpHeadIn->REMOTE_PORT

Retorna um valor Advpl numérico , informando a porta utilizada para realizar a


requisição.

06. Alias virtual HttpHeadOut


Revisão: 08/12/2003

Abrangência

Versão 7.10 LIB WEBEX

Através deste alias virtual de retorno, podemos alterar ou criar um parâmetro no Header
de retorno HTTP do Protheus , a ser devolvido ào Browser solicitante de uma requisição
de processamento.

Trata-se portanto de uma propriedade de retorno, disponível apenas quando a função


Advpl é executada através de uma requisição http via link .apw utilizando a
configuração de Working Threads WEBEX.

A criação de uma linha no Header HTTP merece uma atenção especial, pois para que a
operação 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
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Através do alias virtual httpSession, podemos criar e consultar variáveis do tipo


'session', relacionadas ào usuário que realizou a requisição através do Browser.

Para diferenciar os usuários que estão navegando num site, o Protheus busca por um
cookie identificador de usuário, retornado para o browser a cada requisição de link .
APW, chamado SESSIONID. Caso o Protheus receba este cookie, ele identifica quais
sessions pertencem a este usuário.

Quando um usuário realiza a primeira requisição http ao Protheus, o Protheus não


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 função advpl através de httpSession-
>SESSIONID.

Quando criamos uma variável de session, ela pode ser acessada nas próximas
requisições provenientes deste mesmo usuário. Caso uma variável de session consultada
não exista, ela retorna o valor NIL (nulo). Vejamos os exemplos abaixo :

Criando variáveis Session

HttpSession->UserId := '123'
HttpSession->UserName := U_GetUserName()

Nas linhas acima , criamos uma session para o usuário atual , chamada UserId , com o
conteúdo do tipo String, e criamos outra session chamada UserName , com o retorno da
função U_GetUserName()

Consultando variáveis Session

Ao consultar uma variável 'session', sempre devemos prever que a mesma não 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 atribuído `a mesma.

If HttpSession->UserId = NIL
// Session ainda não foi criada ! Usuário não está logado.
conout('Usuario não está logado')
Else
// Session já criada, o usuário 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 usuário
chamou esta função específica. Damos o nome da session de MyCounter, que irá conter
um número. No primeiro acesso do usuário, a session não existe ( = NIL ), e é criada
com o valor numérico 1 (um). A partir das próximas requisições realizadas ao Protheus
através desta página ( através do botão 'Refresh' do Browser, por exemplo ) , a session
já existe, sendo somado o valor 1 ào conteúdo já existente, e devolvido ào browser
solicitante um Html informando quantas chamadas já foram realizadas por este usuário.

#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

Após 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 , peça 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 requisições simultâneas de links .APW em paralelo , desde


que estejam disponíveis o numero de Working Threads necessário 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 três requisições de .apw para o Protheus Server , e caso
extistam 3 working threads disponíveis naquele momento , as três requisições são
atendidas em paralelo.

Por outro lado , se em duas destas três requisições faz-se necessária a atualização e/ou
consulta a uma variável de Session ( httpsession ) , este processamento em paralelo ,
caso não fosse tratado , poderia gerar perdas no conteúdo da session caso a mesma
session fosse atualizada simultaneamente.

Para resolver esta questão, de maneira a não sobrecarregar o Servidor com solicitações
de Processamento Sequencial ( Critical Sessions ) , foi montado um esquema de Lock
de Session de Usuário automático, com liberação automática após o processamento do
APW, ou liberação manual através da chamada da função HttpLeaveSession() antes do
processamento ser terminado.

Exemplificando a aplicação prática e funcionamento deste conceito , partimos de um


ambiente hipotético utilizando 3 frames , onde um usuário realiza uma requisição à
função que retornará o source HTML da página de frames, e a mesma ao chegar no
Browser, faz o mesmo realizar as três requisições simultaneamente, todas elas referentes
ao mesmo usuário. Porém , o primeiro e o segundo frames realizam uma operação
qualquer com uma ou mais variáveis da Session do usuário , e o terceiro frame realiza
um outro processamento que não depende da consulta de nenhuma variável da Session :
As três requisições referente a este usu;ario serão processadas simultaneamente por
working Threads diferentes ( vamos supor que naquele momento haviam três Working
Threads disponíveis) ; porém quando uma das duas working Threads que tentarem
acesso à uma variável de Session daquele usuário , 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 usuário está com a bandeira , então a thread atual pega a bandeira para
ela; senão o processamento da Thread é congelado no aguardo da liberação da bandeira.

A liberação da bandeira ocorre automaticamente no retorno da Working Thread para o


Browser , antes da chamada do ponto de entrada para Reset do Ambiente, através da
chamada na KlibEx da função HttpLeaveSession(). Caso seja viável para o usuário
liberar as sessions antes do retorno da função , ele pode utilizar-se da função
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 irão concorrer pela banceira de


atualização de conteúdo 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 não utiliza
nenhuma variável da session , será processado sem depender de nenhum dos outros dois
frames anteriores.

Quando utilizamos ASP ( Microsoft Active Server Pages ) , o mesmo realiza uma
serialização de requisições de páginas ASP por usuário, de modo que , caso o mesmo
usuário solicite três frames .asp , as requisições de processamento chegarão ao Servidor
ASP simultaneamente , mas a bandeira de processamento é unica por página .asp ,
sendo liberada apenas apos o término do processamento da página , de modo que ,
mesmo que nenhuma das páginas faça uso de sessions , todas as páginas deste usuário
serão processadas em sequência.

08. Envio simultâneo de HTML ao


Browser
Revisão: 30/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

As aplicações web desenhadas para utilizar a Infra-Estrutura APWEBEX contam com o


recurso de "Envio simultâneo de Html ao Browser" durante o processamento de uma
página Advpl-ASP ( .APH e/ou .AHU ) .

Este recurso é habilitado através do Protheus IDE, nas opções de configuração de


compilação do ambiente em questão; mais especificamente habilitado através do
CheckBox "[ ] Exibir conteúdo do Advpl ASP progressivamente no Browser".

Ao habilitamos esta configuração, todos os arquivos APH e AHU são parseados


fazendo internamente o uso da função HttpSend(), de modo que mesmo antes do
processamento estar concluído , o Html gerado já está sendo enviado ào Browser qoe o
solicitou.

A utilização deste recurso provê um ganho de performance subtancial na aplicação


final. Todos os projetos desenvolvidos com esta tecnologia ( Infra-Estrutura
APWEBEX ) devem ter esta configuração de compilação habilitada no IDE. Vale
lembrar que, caso este recurso não esteja habilitado; ao habilitá-lo, os arquivos .aph e
.ahu do projeto necessitam ser recompilados para que esta configuração tenha o efeito
desejado.

Pode existir a necessidade de um processamento de um APH ou AHU não enviar o


script Html gerado diretamente ao Browser. Para tal situação, podemos desabilitar
temporariamente este recurso de envio de html progressivo em tempo de execução,
permitindo assim, por exemplo, uma função chamar em sequência dois arquivos APH ,
um para gerar um conteúdo Html a ser enviado via e-mail , armazenado em uma
variável 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 simultâneo do Script HTML ào browser em


tempo de execução, utilize a função HttpSetPart()
09. Configurações específicas APWEBEX
Revisão: 26/04/2004

Abrangência

Versão 7.10 Versão 8.11

Ao utilizarmos as funções de Infra-estrutura APWEBEX, existem recursos da lib que


exigem uma configuração adicional para serem utilizados.

Envio de e-mail automático através da Rotina de Tratamento de Erro do Site

Em caso de erro fatal na aplicação Web, a própria rotina de tratamento de erro pode ser
configurada para enviar um e-mail ào Administrador do sistema. Para tal, é necessário
inserir as chaves abaixo na seção do ambiente em uso para o site :

ErrorSMTP= (endereço do servidor SMTP a ser usado para o envio do e-mail )


ErrorMail= ( um ou mais endereços de e-mail a receber op e-mail de erro, separados por
virgula )
ErrorFrom= ( um e apenas um endereço de e-mail a ser usado como remetente do aviso
de erro )
ErrorLogin = ( nome de usuario de login no servidor de SMTP, caso necessário )
ErrorPassword= ( senha do usuario de login no servidor de SMTP, caso necessário )

WebAdmin - Login alternativo

A infra-estrutura APWEBEX exige um usuário e senha para entrar no módulo de


administração WebAdmin. Para validar o login, é utilizado o arquivo de senhas do ERP.
O usuário deve ser o 'Administrador' ou pertencer ao grupo de administradores para ter
acesso ào WebAdmin. Caso não seja viável usar este arquivo de senhas para validar o
login, podemos inserir uma chave adicional ( AdmLogin ) no Environment em uso pela
aplicação Web, e configurar nela a senha do usuário 'Administrador' para login no
WebAdmin. Caso esta chave seja configurada, o arquivo de senhas do ERP não 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 , é possível utilizar uma configuração específica para a troca do


repositório de objetos em uso no site, sem que seja necessário parar o servidor para isso.
Por default , a pasta de upload chama-se '\SwapRPO\', e deve existir na estrutura
de diretório do ambiente utilizado, a partir do diretório raiz do ambiente ( RootPath ).

RpoUpload= ( pasta de upload alternativa, a partir do RootPath do ambiente )


10. Recomendações finais
Revisão: 17/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Para todo o desenvolvimento de soluções, temos em mãos uma diversidade de recursos,


desenhados para melhor atender às necessidades e adequar-se às caracteristicas da
aplicação. Dada a flexibilidade dos recursos, recomenda-se aos desenvolvedores
adotarem um padrão de desenvolvimento e ter em foco a eficiência da aplicação final,
tanto no aspecto funcional como na codificação .

Lançando mão da experiência em desenvolvimento de aplicações web adquiridas nos


últimos anos, nos tópicos abaixo estão relacionadas algumas medidas tomadas no
desenvolvimento de aplicações que nos são muito úteis no decorrer de um projeto.

Nomenclatura de Funções

Para o desenvolvimento de aplicações web, foi criado o 'Statement' WEB FUNCTION


para a declaração de funções referentes à projetos web. Este comando , na prática ,
apenas prefixa a declaração da função com W_ , porém a sua utilização identifica que a
função em questão foi construída única e exclusivamente para ser chamada a partir de
uma requisição HTTP . Em adendo à este, devemos utilizar os comandos WEB
EXTENDED INIT ... END , disponivels no Include 'apwebex.ch' , para proteger a
função de ser chamada em um ambiente que não o APWEBEX.

Separando a Interface do Processamento

Ao desenvolver utilizando Advpl ASP , páginas APH / AHU, recomenda-se separar o


processamento da Interface, do seguinte modo : Criar uma Web Function para a
chamdada de umna página com conteúdo dinâmico via link .apw , e um arquivo .APH
ou .AHU de mesmo nome , que será chamado internamente , de modo que o código-
fonte escrito na Web Function seja responsável para gerar as informações a serem
disponibilizadas para o usuário , e o .APH contenha apenas a 'máscara' destas
informações e o mínimo de instruções Advpl possível para a montagem da página. Este
processo facilita a manutenção de amobos os códigos, pois o Web Designer que irá
realizar um ajuste no APH não terá que 'desviar' do fonte Advpl inserido na página , e o
Analista / Programador que fará a manutenção no código Advpl preocupar-se-á apenas
com o código responsável para a geração dos dados que serão mascarados.

Utilização das Funções de Infra-Estrutura

Através dos comandos e funções disponibilizadas na Infra-Estrutura APWEBEX, não


têmos a necessidade de recriar partes comuns de código para todos os projetos que se
utilizem desta tecnologia, além de permitir através de pontos de entrada
estrategicamente colocados na ferramenta um nível altíssimo de customização para os
projetos desenvolvidos com esta tecnologia, de maneira prática e objetiva.
11. Monitoramento de Sites em WEBEX
Revisão: 17/12/2003

Abrangência

LIB WEBEX

O Objetivo de uma função de Monitoramento de Sites é testar as funcionalidades


básicas 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 função específica para o site , que irá determinar se o mesmo está operacional
. Esta função será chamada através de link .apw

Vejamos o exemplo abaixo, escrito para um site cujas bases de dados estão num SQL ,
acessadas via TopConnect. Neste exemplo , a função chamada será
http://servidor/U_SiteMonitor.apw , e caso esteja tudo certo , ela retornará a string
'(SITE OK)' , seguido da data e horário da execução 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


informação 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
requisição à 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 conexão com o TOP'
Endif

// Verifica se as tabelas principais estão abertas ....

If select('SA1')=0
Return 'Tabela SA1 não está aberta !!!'
Endif

If select('SC5')=0
Return 'Tabela SC5 não 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
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

CLOSE QUERY cAlias

Parâmetros

Argumento Tipo Descrição


Alias sob o qual o cursor da Query foi aberto. Caso o alias
cAlias Caracter passado como parâmetro não se encontre aberto , a função
não gera nenhuma ocorrência de erro.

Descrição

Através do comando Close Query , realizamos o fechamento de uma query aberta


através do comando OPEN QUERY.

ATENÇÃO : Uma query aberta pelo comando OPEN QUERY deve ser fechada
pelo comando CLOSE QUERY . Poderíamos fechar o alias aberto através de uma
Query simplesmente com a função DbCloseArea(), porém isto deixaria em aberto
elementos internos de controle criados pelo comando OPEN QUERY.
Comandos - OPEN QUERY
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

OPEN QUERY <cQuery> ALIAS <cAlias> [ [NOCHANGE] ]

Parâmetros

Argumento Tipo Descrição


cQuery corresponde à String contendo a Query a ser
<cQuery> Caracter
executada no banco de dados
cAlias corresponde ao nome do alias sob o qual o cursor
de retorno dos dados pesquisados será aberto no ambiente
ALIAS <cAlias> Caracter Advpl. Não pode ser especificado um nome de alias já em
uso, senão a aplicação será finalizada com a ocorrência de
erro "Alias already in Use"
Caso especificada a cláusola NOCHANGE na abertura da
[NOCHANGE] Caracter query , a string em cQuery não será submetida à função
ChangeQuery()

Descrição

Através do comando OPEN QUERY , realizamos a abertura de uma Query de busca no


Banco de Dados através do RDD TOPCONN , retornando os dados consultados através
de um 'ALIAS' Advpl.

Caso a Query nao possa ser aberta, por erro de sintaxe , devido à thread atual não estar
conectada com o TopConnect , ou outro erro , será gerado um log de erro , informando
o Alias , o Stack ( Pilha de Chamadas ) de execucão , e o conteúdo da Query para
Debug.

OBSERVAÇÕES IMPORTANTES

Na montagem da string da Query , devemos especificar os comandos SQL , alias


e nomes de campos em letras maiúsculas.
Quando utilizamos o comando OPEN QUERY , não precisamos passar a
expressão da Query através da função ChangeQuery(). Este proceduimento já é
realizado internamente pelo comando OPEN QUERY. Para que a query não seja
submetida à função ChangeQuery(), devemos utilizar o parâmetro
NOCHANGE.
A utilização deste comando é implícita à LIB APWEBEX , e necessita da
utilização do #include 'Apwebex.ch'

Comandos - WEB EXTENDED END


Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

WEB EXTENDED END <cHtml> [ START <cFnStart> ]

Parâmetros

Argumento Tipo Descrição


cHtml corresponde à variavel que será utilizada para
armazenar a String Html que será retornada ao Browser
<cHtml> Caracter
solicitante do processamento. Deve ser especificada uma
variável String , com conteúdo vazio. ("")
cFnStart corresponde ào nome de uma função Advpl que
START
Caracter será executada para pré-validar a execução do resto do
<cFnStart>
código. A função deve ser passada SEM parênteses () .

Descrição

Devemos utilizar este comando para fechar uma seção aberta pelo comando WEB
EXTENDED INIT . Para cada ocorrência do comando WEB EXTENDED INIT , deve-
se ter um fechamento da mesma através do comando WEB EXTENDED END ,
devendo haver apenas uma ocorrência desta estrutura por função.

A utilização deste comando é implicita à Working Threads inicializadas pela Lib


APWEBEX , e a definição do mesmo está no arquivo #include 'apwebex.ch' , que deve
ser declarado no início do arquivo fonte Advpl.
Comandos - WEB EXTENDED INIT
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

WEB EXTENDED INIT <cHtml> [ START <cFnStart> ]

Parâmetros

Argumento Tipo Descrição


cHtml corresponde à variavel que será utilizada para
armazenar a String Html que será retornada ao Browser
<cHtml> Caracter
solicitante do processamento. Deve ser especificada uma
variável String , com conteúdo vazio. ("")
cFnStart corresponde ào nome de uma função Advpl que
START
Caracter será executada para pré-validar a execução do resto do
<cFnStart>
código. A função deve ser passada SEM parênteses () .

Descrição

Devemos utilizar este comando , juntamente com o comando WEB EXTENDED END
quando montamos uma funcão ( Web Function ) que foi construída para ser chamada a
partir de um Web Browser , quando nos utilizamos das funções de Infra-Estrutura
APWEBEX.

Através dele , é realizada uma pré-validação que certifica que a execução da função
somente será realizada caso a thread atual seja realmente uma Thread montada no
ambiente WEBEX, além de podermos inserir uma pré-validação (START) de execução
específica para esta função.

Caso seja especificada uma função na cláusula START, a mesma deverá retornar uma
String. Retornando uma String em branco , o processamento da função original será
efetuado normalmente . Caso a função retorne uma string não-vazia , esta string será
retornada para a variável cHtml , e o processamento do programa será desviado para a
linha do código-fonte imediatamente posterior ào comando WEB EXTENDED END .

Para cada ocorrência do comando WEB EXTENDED INIT , deve-se ter um fechamento
da mesma através do comando WEB EXTENDED END , devendo haver apenas uma
ocorrência desta estrutura por função.

A utilização deste comando é implicita à Working Threads inicializadas pela Lib


APWEBEX , e a definição do mesmo está no arquivo #include 'apwebex.ch' , que deve
ser declarado no início do arquivo fonte Advpl.
Infra-Estrutura APWEBEX - EnvUser.APL -
Exemplo de Uso com ERP
Revisão: 16/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Através do exemplo prático abaixo , utilizamos em um código fonte Advpl os pontos de


entrada disponibilizados na Infra-Estrutura APWEBEX para realizar a preparação de
um ambiente ERP , Reset de Ambiente , finalização de Thread, finalização de sessions
por time-out e customização de mensagem de erro para o desenvolvimento de um
projeto de Web Site integrado com o ERP Microsiga.

Devemos adotar como padrão para projetos que utilizam APWEBEX a criação do
arquivo "EnvUser.apl", especificamente para a definição dos pontos de entrada
utilizados pela Infra-Estrutura APWEBEX; e devemos apenas compilar os fontes
dos pontos de entrada realmente necessários ào projeto.

#INCLUDE "PROTHEUS.CH"
#INCLUDE "APWEBEX.CH"

/*
======================================================================
==============
Exemplo de Arquivo de Lib de Projeto APWEBEX , utilizando os pontos de
entrada
da lib para preparação 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 inicialização de cada Working Thread (


ONSTART )
É a responsável por preparar o ambiente para atender às requisições
WEB de links .apw
Não recebe parâmetro algum da lib , e deve retornar .T. caso tenha
inicialziado com sucesso
ou .F. em caso de falha de inicialização .
----------------------------------------------------------------------
------ */

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
requisição de um link .APW
Recebe como parâmetro o nome da função 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 função originalmente solicitada é executada pela
lib.
Caso contrário, a função original não é 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 ""
Função chamada imediatamente Apos a execução de uma requisição .APW
Recebe como parâmetro o nome da função executada, e permite também 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()
Função chamada no fechamendo do ambiente de uma working Thread. Apos a
execução deste ,
a Thread utilizada é eliminada da memória .
----------------------------------------------------------------------
--------- */
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
usuário será
eliminada da memória 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 memória...")
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
crítico (tratamento
de erro ) , esta função deve ser o mais suscinta e simples possível ,
não 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 página. O Administrador do sistema será


notificado desta '

cCustomHtml += 'ocorrência . Recomendamos fortemente que esta janela do


navegador seja '

cCustomHtml += 'fechada, e uma nova janela seja aberta para retornar à


navegação do site.

'
cCustomHtml += '
'
cCustomHtml += '

'
cCustomHtml += ''
cCustomHtml += ''

Return cCustomHtml
Infra-Estrutura APWEBEX - Exemplo da
função ESCAPE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Nos exemplo abaixo, utilizamos a função escape() para formatar parâmetros 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" , próprio para a monyahem de
um link .
Infra-Estrutura APWEBEX - Exemplo da
função GETJOBPROFSTRING
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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


recupera algumas configurações atuais em uso para este JOB.

cJobType := GetJobProfString('type','(empty)' )
cInstances := GetJobProfString('Instances','(empty)' )
cInacTime := GetJobProfString(InactiveTimeout','(default)' )
cExpTime := GetJobProfString('ExpirationTime','(default)' )
Infra-Estrutura APWEBEX - Exemplo da
função GETPARVALUE
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

No exemplo abaixo , são montados dois arrays multi-dimensionais , com 2 dimensões ,


e são realizadas buscas nos mesmos explorando todas as possibilidades de uso da
função GetParValue()

Local aTeste1 := {}
Local aTeste2 := {}

Aadd(aTeste1,{"Alias","TMP1"})
Aadd(aTeste1,{"Relacao","2x3"})

Aadd(aTeste2,{"Alias","TMP2"})
Aadd(aTeste2,{"Info","---Informação 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) // ---Informação 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) // ---Informação Adicional---
Infra-Estrutura APWEBEX - Exemplo da
função HEXSTRDUMP
Revisão: 15/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Através 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 função
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 visualização 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
função HTMLNOTAGS
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

No exemplo abaixo , a função HtmlNoTags é utilizada para permitir a utilização de


caracteres especiais no conteúdo de um input para um formulário Html.

Local cHtml := ""


Local cInput := ""

// Conteudo do campo com tags HTML intepretáveis


cInput := ''

// Ao montar o Input , aplicar a HtmlNoTags() ao conteudo do mesmo.


'+HtmlNoTa
cHtml += ' '
Infra-Estrutura APWEBEX - Exemplo da
função REDIRPAGE
Revisão: 10/12/2003

Nos exemplos abaixo, a função redirpage é utilizada para gerar o script de


redirecionamento em duas situações específicas.

/*
Em uma determinada função , caso um parâmetro não seja passado , o
usuário deverá retornar a uma outra tela
*/

...
If empty(httpget->meuparam)
// Parâmetro não 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
função REDIRPAGE
Revisão: 10/12/2003

Nos exemplos abaixo, a função redirpage é utilizada para gerar o script de


redirecionamento em duas situações específicas.

/*
Em uma determinada função , caso um parâmetro não seja passado , o
usuário deverá retornar a uma outra tela
*/

...
If empty(httpget->meuparam)
// Parâmetro não 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
função RETSQLACE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

No exemplo abaixo , utilizamos a função RetSqlAce para montar uma query de busca
por título de uma determinada informação , considerando todas as possibilidades de
acentuação , independentemente de como o banco foi alimentado e/ou a string de busca
foi digitada.

IMPORTANTE : Na expressão da Query , o campo da tabela deve ser passado pela


função LOWER do BAnco , pois a função retsqlace monta a string para busca com
letras minúsculas.

cFind := 'acentuação'
cQuery := "SELECT * FROM " + RetSqlTab('ZZ1')
cQuery += "WHERE LOWER(ZZ1_TITULO) LIKE '%"+RetSqlAce(cFind)+"%' "
Infra-Estrutura APWEBEX - Exemplo da
função VALTOSQL
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 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 conversões


específicas para cada tipo de conteúdo seria o equivalemte ao código
abaixo :

cQuery := "SELECT * FROM FA2010 "


cQuery += "WHERE FA2_FILIAL = '02' "
cQuery += "AND FA2_DTINC <= " + DTOS( date() )
Infra-Estrutura APWEBEX - Exemplo da
função VARINFO
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

No exemplo abaixo , é gerada uma string HTML com as informações do retorno da


chamada de duas funções básicas 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
funções de acentuação ApWebEX
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

No exemplo abaixo, vemos a diferença de comportamento entre as funções básicas da


Linguagem Advpl Upper() e Lower() , e a função de Infra-estrutura Capital(), em
relação às funções da Infra-estrutura APWEBEX UpperAce() , LowerAce() e
CApitalAce() , quando utilizamos caracteres acentuados.

cRetorno := ""
cFrase := "não há EXPLICAÇÕES considerando excessões PARA O
inexplicável."

cRetorno += "Original .......... " + cFrase + CRLF


cRetorno += "Upper() ........... " + upper(cFrase) + CRLF
cRetorno += "Lower() ........... " + lower(cFrase) + CRLF
cRetorno += "Capital() ......... " + capital(cFrase) + CRLF
cRetorno += "UPPERACE() ........ " + UPPERACE(cFrase) + CRLF
cRetorno += "LOWERACE() ........ " + LOWERACE(cFrase) + CRLF
cRetorno += "CAPITALACE() ...... " + CAPITALACE(cFrase) + CRLF

/*

Neste ponto , a variável cRetorno deverá conter :

Original .......... não há EXPLICAÇÕES considerando excessões PARA O


inexplicável.

Upper() ........... NãO Há EXPLICAÇÕES CONSIDERANDO EXCESSõES PARA O


INEXPLICáVEL.
Lower() ........... não há explicaÇÕes considerando excessões para o
inexplicável.
Capital() ......... Não Há ExplicaÇÕes Considerando Excessões Para O
Inexplicável.

UPPERACE() ........ NÃO HÁ EXPLICAÇÕES CONSIDERANDO EXCESSÕES PARA O


INEXPLICÁVEL.
LOWERACE() ........ não há explicações considerando excessões para o
inexplicável.
CAPITALACE() ...... Não Há Explicações Considerando Excessões Para O
Inexplicável.

*/
Infra-Estrutura APWEBEX - Exemplos das
funções NTOC e CTON
Revisão: 16/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

No exemplo abaixo , utilizamos as funções cton e ntoc para realizar conversões de


números em base decimal para outras bases numéricas e vice-versa.

nNum1 := CTON('01101001',2) // Converte binário para decimal


nNum2 := CTON('00DA25FE',16) // Converte Hexadecimal para decimal

nNum1++ // Soma 1 ao numero em nNum1


nNum2++ // Soma 1 ao numero em nNum2

cNum1 := NtoC(nNum1,2,8) // Converte para binário novamente


cNum2 := NtoC(nNum2,16,8) // Converte para Hexa novamente

/* -------------------------------------------------------------------
------
Ao final do programa , cNum1 será "01101010" e cNum2 será "00DA25FF"
----------------------------------------------------------------------
--- */
APWEXADDERR
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

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

Parâmetros

Argumento Tipo Descrição


cTitulo corresponde a um título identificador da
cTitulo Caracter informação. Deve ter no máximo 20 caracteres. Os
caracteres acima da vigésima posição serão ignorados.
cInfo corresponde à Informação a ser acrescentada ao
cInfo Caracter
ERROR.LOG em caso de erro.

Retorno

Tipo Descrição
Lógico Esta função sempre retorna .T.

Descrição

Através da função ApWExAddErr(), podemos acrescentar uma string de informações


adicionais em um buffer em memória, descarregado na geração do ERROR.LOG no
caso de uma ocorrência de erro fatal na working thread atual.

Caso a função seja chamada sem nenhum parâmetro, a última ocorrência acrescentada
pela função é eliminada da pilha interna de informações.

ATENÇÃO : Esta função deve ser apenas utilizada em casos de necessidade de


obtenção de informações específicas acerca de uma ocorrência de erro não reproduzida
em ambiente de testes e/ou não depurável, pois seu uso desnecessário prejudica a
performance da aplicação final.
CAPITALACE
Revisão: 08/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

CAPITALACE ( < cString > ) --> cStrCapital

Parâmetros

Argumento Tipo Descrição


cString Caracter String a ser convertida.

Retorno

Tipo Descrição
String resultante convertida para munúsculo , com as primeiras letras das
Caracter
palavras significantes em maiúsculo.

Descrição

Semelhante à função de Infra-estrutura Capital() , porém converte também caracteres


acentuados.

A função CapitalAce() converte todos os caracteres de uma String para 'minúsculo' , e a


primeira letra das palavras significantes para maiúsculo, semelhante à função Capital() ,
porém considera e converte também caracteres acentuados em OEM e/ou ANSI.
CTON
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

CTON ( < cString > , < nBase > ) --> nNumero

Parâmetros

Argumento Tipo Descrição


cString corresponde à representação de um número em
cString Caracter
outra base numérica, compreendida entre 2 e 36.
nBase corresponde à base numérica utilizada pelo numero
nBase Numérico
representado em cString.

Retorno

Tipo Descrição
Numérico Número recebido como parâmetro em notação decimal ( Base 10 )

Descrição

Converte um número representado em String , de base 2 a 36 , para um número em base


decimal (10).

Observação Importante :

São considerados caracteres válidos para compor um número de base 36 os 10


algarismos numéricos de 0 a 9 e os 26 caracteres alfabéticos maiúsculos compreendidos
entre A e Z. Quaisquer caractetes presentes na String de parâmetro fora desta faixa de
dados e/ou fora da base ( por exemplo , uma conversão de string base 2 - binário - da
string '01001020' ) retornará -1 ( menos um ) .
ESCAPE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

ESCAPE ( < cString > ) --> cEscaped

Parâmetros

Argumento Tipo Descrição


cString Caracter cString é uma sequência de caracteres a ser processada.

Retorno

Tipo Descrição
cEscaped corresponde à string original , com os caracteres reservados
Caracter
utilizando a notação %HH .

Descrição

A função Escape() deve ser utilizada para realizar conversões de caracteres especiais e
reservados quando da necessidade de passagem de parâmetros via URL .

A sintaxe de uma requisição via URL para a passagem de parâmetros é:

(link)?param=conteudo&param2=conteudo2&...

Quando passamos parâmetros via url , devemos tomar o cuidado de não utilizar
caracteres reservados e especiais nos nomes e conteúdos de parâmetros. Para realizar
estas conversões, utilizamos a função Escape()
EXECINPAGE
Revisão: 12/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

EXECINPAGE ( < cAPHPage > ) --> cHTMLPage

Parâmetros

Argumento Tipo Descrição


Corresponde ào nome do APH que deve ser executado,
cAPHPage Caracter
sem a extensão.

Retorno

Tipo Descrição
Caracter cHtmlPage corresponde à string HTML gerada pela página APH / AHU.

Descrição

Através da função ExecInPage(), executamos uma página APH passada como


parâmetro. A função deverá retornar a String HTML correspondente à página
processada.

Porém a função ExecInPage() realiza tratamentos adicionais padrão relacionaodo ào


comportamento dos Projetos WEB referentes à customizações, da segunte maneira :

1. Primeiro é verificado se existe uma página AHU compilada com o nome


cAPHPage. Caso exista , a mesma será executada pela execinpage.
2. Caso não exista AHU com este nome , é procurado pelo APH. Caso o APH
exista , o mesmo será executado pela ExecInPage.
3. Caso não existam no RPO atual o APH nem o AHU com o nome especificado
no parâmetro cAPHFile, o processamento é abortado com a ocorrência 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 função retorna a
tring retornada e não processa o APH / AHU. Observação : A função
ExecInPage não irá executar este tratamento da User Function com o nome de
cAPHPage caso a função ExecInPage() esteja sendo executada através de uma
USER FUNCTION .

Observação Importante - Envio parcial de HTML ào Browser.

A função ExecInpage(), juntamente com o APH compilado, ao serem processados irão


tentar enviar o conteúdo HTML para o Browser solicitante durante o processamento, de
modo que a função normalmente irá retornar uma String vazia.

Caso seja necessária a execução de uma página APH ou AHU e o não-envio da mesma
para o Browse; por exemplo para a geração de um código HTML a ser enviado via e-
mail; revemos utilizar a função HttpSetPart(), realizando uma chamada da mesma antes
da ExecInPage() , passando o parâmetro .F. para desabilitar temporariamente o envio de
HTML simultâneo ao Browser, e após a execução da ExecInPage(), devemos re-
habilitar o envio simultâneo através da chamada da função HttpSetPart() com o
parâmetro .T.
EXISTPAGE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

EXISTPAGE ( < cAphFile > ) --> lFound

Parâmetros

Argumento Tipo Descrição


Nome do arquivo APH, sem extensão e sem path , a ser
cAphFile Caracter
verificado.

Retorno

Tipo Descrição
Retorna um valor booleano indicando se o arquivo APH especificado está
Caracter
compilado no RPO do ambiente atual.

Descrição

Utilizamos a função 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
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

EXISTUSRPAGE ( < cAhuFile > ) --> lExist

Parâmetros

Argumento Tipo Descrição


Nome do arquivo AHU, sem extensão e sem path , a ser
cAhuFile Caracter
verificado

Retorno

Tipo Descrição
Retorna um valor booleano indicando se o arquivo APH especificado está
Lógico
compilado no RPO do ambiente atual.

Descrição

Utilizamos a função 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
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

GETJOBPROFSTRING ( < cKey > , < cDefault > ) --> cKeyValue

Parâmetros

Argumento Tipo Descrição


cKey corresponde à chave da seção de configuração da
cKey Caracter
Working Thread atual a ser retornada.
Valor default (string) a ser retornado pela função caso a
cDefault Caracter
chave especificada não sehja encontrada no .INI

Retorno

Tipo Descrição
Conteudo da Chave solicitada . Caso a chave não seja encontrada , é
Caracter retornado o conteudo de cDefault . Caso esta função não seja executada a
partir de uma Working Thread , ela retornará uma string em branco ("")

Descrição

Através desta função , podemos recuperar as configurações do Job da Working Thread


atual.
GETWEXVERSION
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

GETWEXVERSION ( ) --> cBuildId

Retorno

Tipo Descrição
Corresponde à String Identificadora da versão , no formato <LIB>
Caracter
V.AAMMDDHHmm . Vide Tabela A

Descrição

Esta função não requer argumentos , e retorna o Identificador do build / versão de


Release das funções de Infra-Estrutura APWEBEX.

Observação : A data informada pela versão não corresponde à ultima compilação


do RPO de um determinado Projeto WEB, mas sim à data de release da LIB de
Infra-Estrutura APWEBEX.

Tabela A
Simbolo Descrição
AA Ano de geração da Lib
MM Mês da geração da Lib
DD Dia da geração da Lib
HH Horário da geração da Lib
mm Minutos do Horário de Geração da Lib
Indica que a versão foi compilada com a configuracão de envio progressivo de
(HTTP) HTML simultâneo para o Browse . Esta opção é imprescindível para projetos
que se utilizam desta LIB.

Por exemplo :

APWEBEX Version 3.0312021900 (HTTP)


HEXSTRDUMP
Revisão: 15/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

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

Parâmetros

Argumento Tipo Descrição


cString Caracter String a ser lida para a geração do Dump
Corresponde à posição inicial de cString a ser
considerada para a geração do Dump, a partir da posição
nStart Numérico
1. Caso este parâmetro não seja informado , o Default é a
posição 1 da string.
nLength corresponde ào tamanho a ser considerado para a
geração do DUMP a partir da posição inicial recebida em
nLength Numérico
nStart. Caso este parâmetro não seja informado, é
considerado o tamanho até o final da String.

Retorno

Tipo Descrição
O retorno da função corresponde à uma string Advpl , formatadas em 16
bytes em hexadecimal por linha , mais o separador pipe (|) , mais os 16
Caracter
caracteres em Ansi. Os caracteres de controle ( codigo ascii menor que 32
) são convertidos para visualização para o caractere underline (_)

Descrição

Através da função HexStrDump(), podemos gerar uma string em Advpl em formato de


Dump Hexadecimal a partir da string informada como parâmetro, a partir de uma
determinada posição da string, considerando um número de bytes informado.

Caso os parâmetros nPosIni e nTamString não sejam informados, o dump gerado


corresponde a string recebida como parâmetro em sua totalidade.

Observação :
Não devemos pasar para a função HexStrDump uma string maior que 240 Kb , pois a
geração da String de dump é realizada em memória, sendo a string final gerada em
média 4,2 vezes maior que a string passada como parâmetro. Caso a string passada
como parâmetro seja maior que 240 Kb , a execução será abortada com a ocorrência de
erro fatal "string size overflow"

HTMLNOTAGS
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

HTMLNOTAGS ( < cStrHtml > ) --> cStrNoTags

Parâmetros

Argumento Tipo Descrição


cStrHtml corresponde a uma String que não pode conter
cStrHtml Caracter
caracteres Html interpretáveis.

Retorno

Tipo Descrição
String original com os caracteres interpretáveis Html < > & " convertidos
Caracter
para caracteres não-interpretáveis.

Descrição

A Função HTMLNOTAGS converte as Tags interpretáveis de uma String HTML para


TAGS não interpretáveis. Este recurso é normalmente utilizado quando precisamos
montar um input Html com um conteudo que nao pode ser interpretado pelo browser
como uma Tag . Esta função 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


conteúdo do mesmo seja colocado entre aspas duplas, pois caso o conteúdo do
value inicial do campo contenha aspas simples ( não convertidas pela função
HtmlNoTags) , isto poderá ocasionar perda de dados e erro de sintaxe no
formulário Html.
HTTPISWEBEX
Revisão: 12/12/2003

Sintaxe

HTTPISWEBEX ( ) --> lIsApWEBEX

Retorno

Tipo Descrição
A função retornará .T. caso o ambiente de execução atual seja uma
Lógico Working Thread WEBEX , inicializada pela função de infra-estrutura
STARTWEBEX.

Descrição

Através da função HttpIsWebEx() é possível identificarmos se o programa atual está


sendo executado através de uma Working Thread inicializada utilizando-se as funções
de Infra-Estrutura APWEBEX
ISEMAIL
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

ISEMAIL ( < cEMail > ) --> lEmailOk

Parâmetros

Argumento Tipo Descrição


cEmail corresponde a string a ser analizada , contendo um
cEMail Caracter
e apenas um endereço de e-mail.

Retorno

Tipo Descrição
Retorna .T. caso a sring recebida como parâmetro atenda às definições de
Caracter
nomenclatura válidos para um endereço de e-mail.

Descrição

Utilizada para validar e-mails em Advpl , a função ISEMAIL recebe como parâmetro
uma string contendo um e-mail , retornando .T. caso a string esteja em um formáto
válido respeitando a regra para nomenclatura de endereços de e-mail.

Regra : Um e-mail é considerado válido caso seja iniciado por um caracter , apenas
contenha caracteres asc de a a z e 0 a 9 , e os caracteres @ (arroba) , . (ponto) , - ( hífen)
ou _ (underline) ; e deve conter uma e apenas uma arroba , e no minimo um ponto apos
a arroba, intercalado por um caracter.
LOWERACE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

LOWERACE ( < cString > ) --> cStrLower

Parâmetros

Argumento Tipo Descrição


cString é a sequência de caracteres a ser convertida para
cString Caracter
letras minúsculas.

Retorno

Tipo Descrição
Caracter String original em letras minúsculas.

Descrição

A Função LOWERACE converte todos os caracteres de uma String para “minusculo” ,


semelhante à função LOWER() , porém considera e converte também caracteres
acentuados em ANSI.
NTOC
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

NTOC ( < nNumero > , < nBase > , < nTamStr > ) --> cString

Parâmetros

Argumento Tipo Descrição


nNumero é o valor numérico , em base devimal , a ser
nNumero Numérico
convertido.
nBase corresponde à base binária a ser utilizada para
nBase Numérico
converter nNumero.
nTamStr corresponde ao tamanho da string representando
nTamStr Numérico
o numero na base desejada .

Retorno

Tipo Descrição
cString corresponde ao numero convertido para a base numérica
Caracter
especificada como parâmetro.

Descrição

A Função NTOC converte um número em notação decimal para um número


representado por String utilizando uma base numérica entre 2 e 36 , preenchendo-o com
“0” (zeros) à esquerda do tamanho especificado.

Observação : O Parâmetro nBase deve ser especificado com um número entre 2 e 36 .


Caso seja passado como parâmetro um número base fora desta faixa, o processamento é
abortado com a ocorrência de erro [APWEXERR_0022] INVALID NTOC BASE [X] ,
onde <X> foi a base passada como argumento.
REDIRPAGE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

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

Parâmetros

Argumento Tipo Descrição


cUrl Caracter Link para onde o script deve apontar o redirecionamento
Destino do redirecionamento. Caso não especificado , o
cTarget Caracter
default é _self.
Tempo (em segundos) de delay antes do
nTime Numérico
redirecionamento ser executado.

Retorno

Tipo Descrição
Script Html / JavaScript que , ao ser executado no Browser (client) ,
Caracter
chama a página/objeto chamado no Link.

Descrição

A função RedirPage é utilizada quando desejamos devolver ao Browser um script que ,


ao ser executado , redirecionará o Browser à abertura de um link passado como
parâmetro.
RETSQLACE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

RETSQLACE ( < cStrFind > ) --> cStrQuery

Parâmetros

Argumento Tipo Descrição


cStrFind corresponde à sequência de caracteres a ser
cStrFind Caracter procurada , podendo conter caracteres maiúsculos e
minúsculos , com ou sem acentuação.

Retorno

Tipo Descrição
cStrQuery corresponde à string de busca a ser utilizada na query,
Caracter
utilizando caracteres em minúsculo.

Descrição

A função RetSqlAce é utilizada para auxiliar de montagem de querys de busca de


caracteres acentuados em bases de dados . A função automaticamente trata a string
original , removendo os acentos , convertendo todos os caracteres para minúsculas , e
trocando todas as vogais e cedilhas da string original por uma sequência de caracteres
acentuados em munúscilas para busca posicional .
RETSQLCOND
Revisão: 12/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

RETSQLCOND ( < cAliases > ) --> cSqlWhere

Parâmetros

Argumento Tipo Descrição


Lista contendo um ou mais aliases , separados por vírgula ,
cAliases Caracter a serem considerados para a montagem da expressão de
validação.

Retorno

Tipo Descrição
Corresponde à expressão SQL para filtrar os dados através da cláusula
Caracter
WHERE

Descrição

Utilizamos a função RetSqlCond() como auxiliar na montagem de querys para busca de


dados em tabelas em conformidade com o padrão adotado pelo ERP Microsiga e o
Makira Hypersite , utilizando aliases de 3 caracteres.

A função retorna , a partir dos aliases passados como parâmetro , as expressões 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.

Observações :

Esta função foi mantida apenas por compatibilidade, pois a ordem de


comparação de campos na cláusula 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 invés de
utilizar a função RetSqlCond() , utilizar como primeira claúsula WHERE o
retorno da função RetSqlFil() ( comparação dos campos _FILIAL , os primeiros
do(s) índice(s) do ERP ) , que retorna apenas as comparações de Filial , e por
último a função RetSqlDel, que retorna o script para verificação dos campos
deletados ( que é o último campo das chaves de índice do ERP , utilizando
TopConnect ).
Devemos também atentar ao fato que a função RetSqlCond() retorna os campos
para a comparação utilizando o prefixo da expressão SQL com o Alias reduzido
(3 letras) das tabelas informadas, de modo que estes alias devem ser
especificados na cláusula FROM , na abertura da Query, quando utilizamos a
função RetSqlName para retornar o nome físico das Tabelas no Banco de Dados.
A função RqtSqlTab() já retorna os nomes físicos das tabelas juntamente com os
alias para este fim .
RETSQLDEL
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

RETSQLDEL ( < cAliases > ) --> cSqlWhere

Parâmetros

Argumento Tipo Descrição


Lista contendo um ou mais aliases , separados por vírgula ,
cAliases Caracter a serem considerados para a montagem da expressão de
validação.

Retorno

Tipo Descrição
Corresponde à expressão SQL para filtrar os dados através da cláusula
Caracter WHERE

Descrição

Utilizamos a função RetSqlDel() como auxiliar na montagem de querys para busca de


dados em tabelas em conformidade com o padrão adotado pelo ERP Microsiga,
utilizando aliases de 3 caracteres.

A função retorna , a partir dos aliases passados como parâmetro , as expressões de filtro
de dados para considerar o campo D_E_L_E_T_ da(s) tabela(s) passada(s) como
parâmetro.

Observações :

A ordem de comparação de campos na cláusula 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
função RetSqlDEl() na montagem das ultimas consistências da cláusula
WHERE de uma Query.
Devemos também atentar ao fato que a função RetSqlDel() retorna os campos
para a comparação utilizando o prefixo da expressão SQL com o Alias reduzido
(3 letras) das tabelas informadas, de modo que estes alias devem ser
especificados na cláusula FROM , na abertura da Query, quando utilizamos a
função RetSqlName para retornar o nome físico das Tabelas no Banco de Dados.
A função RqtSqlTab() já retorna os nomes físicos das tabelas juntamente com os
alias para este fim .

RETSQLFIL
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

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

Parâmetros

Argumento Tipo Descrição


Lista contendo um ou mais aliases , separados por vírgula ,
cAliases Caracter a serem considerados para a montagem da expressão de
validação.
Através de cCompFil é possível especificar uma Filial
FIXA a ser comparada com os campos FILIAL do(s)
alias(es) passados no parâmetro cAliases. Caso não
cCompFil Caracter
informado, os campos _FILIAL da(s) tabela(s) passadas
como parâmetro em cAliases serão comparados com o
retorno da função xFilial() de cada alias, respectivamente.

Retorno

Tipo Descrição
Corresponde à expressão SQL para filtrar os dados através da cláusula
Caracter WHERE

Descrição

Utilizamos a função RetSqlFil() como auxiliar na montagem de querys para busca de


dados em tabelas em conformidade com o padrão adotado pelo ERP Microsiga,
utilizando aliases de 3 caracteres.
A função retorna , a partir dos aliases passados como parâmetro , as expressões de filtro
de dados para considerar o campo filial atual ( xFilial ) de acordo com o modo de
abertura do arquivo no ERP ( X2_MODO ) .

Observação :

Devemos atentar ao fato que a função RetSqlFil() retorna os campos para a


comparação utilizando o prefixo da expressão SQL com o Alias reduzido (3
letras) das tabelas informadas, de modo que estes alias devem ser especificados
na cláusula FROM , na abertura da Query, quando utilizamos a função
RetSqlName para retornar o nome físico das Tabelas no Banco de Dados. A
função RqtSqlTab() já retorna os nomes físicos das tabelas juntamente com os
alias para este fim .

RETSQLTAB
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

RETSQLTAB ( < cAliasList > ) --> cStrQuery

Parâmetros

Argumento Tipo Descrição


String contendo um ou mais alias , separados por virgula ,
cAliasList Caracter
a terem seus nomes físicos determinados.

Retorno

Tipo Descrição
String contendo nomes fisicos e alias identificadores dos aliases recebidos
Caracter
como parâmetro.

Descrição

Utilizamos a função RetSqlTab() como auxiliar na montagem de query's quando


trabalhamos com o padrão de Tabelas ERP Microsiga, que utilizam nomenclarura de
alias com 3 Caracteres.
A função recebe como parâmetro um ou mais alias, separados por vírgula, 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
Revisão: 15/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

SEPARA ( < cString > , < cToken > , < lEmpty > ) --> aTokens

Parâmetros

Argumento Tipo Descrição


cString Caracter String com a sequência de caracteres a ser "parseada"
cToken corresponde à string a ser utilizada como
cToken Caracter
separador para delimitar as informações.
lEmpty identifica se caso um intervalo vazio entre tokens
lEmpty Caracter deve ser retornado como um elemento do array. Caso não
especificado , o Default é .T.

Retorno

Tipo Descrição
Array de uma dimensão contendo os elementos parseados pela rotina
Caracter
levando-se em conta o separador passado como parametro.

Descrição

Através da funcão 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'}
Observação :

Para realizar a análise de uma string, cujo delimitador tenha apenas 1 byte, e as
ocorrências de dois separadores juntos sejam ignoradas na geração do array, a função
separa() utiliza a função StrTokArr(), função escrita em C no Protheus Server, mais
rápida para este processamento. Apenas existe a necessidade de utilizarmos a função
Separa() caso as ocorrências 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
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

UNESCAPE ( < cString > ) --> cUnEscaped

Parâmetros

Argumento Tipo Descrição


cString é a string a ter os caracteres em formato escape
cString Caracter
convertidos.

Retorno

Tipo Descrição
cUnescaped corresponde à string recebida como parâmwetro , com os
Caracter caracteres originalmente em notação escape ( %HH ) convertidos para
ASCII

Descrição

Realiza a operação inversa à função Escape() , convertendo os caracteres especiais em


notação %HH em caracteres ASCII.

Observação : Apenas serão convertidos os caracteres originalmente tratados pela


função Escape()
UPPERACE
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

UPPERACE ( < cString > ) --> cStrUpper

Parâmetros

Argumento Tipo Descrição


cString Caracter String a ser convertida. Pode conter também acentos .

Retorno

Tipo Descrição
Retorna a string original com todas as letras mauisculas , inclusive as
Caracter
letras acentuadas.

Descrição

A Função UPPERACE converte todos os caracteres de uma String para “mai\usculo” ,


semelhante à função UPPER() , porém considera e converte também caracteres
acentuados em OEM e ANSI

UPSTRTRAN
Revisão: 15/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

UPSTRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [ nCount ] ) -->
cNewString
Parâmetros

Argumento Tipo Descrição


cString corresponde à sequência de caracteres ou campo
cString Caracter
memo a ser pesquisado.
Corresponde à sequência de caracteres a ser procurada em
cSearch Caracter
cString
cReplace corresponde à sequência de caracteres que deve
substituir a string cSearch. Caso não seja especificado, as
cReplace Caracter
ocorrências de cSearch em cString serão substituídas por
uma string nula ("")
nStart corresponde ào núimero sequencial da primeira
ocorrência de cSEarch em cString a ser substituída por
nStart Numérico cReplace. Se este argumento for omitodo , o default é 1 (
um ) . Caso seja passado um numero menor que 1, a
função retornará uma string em branco ("")
nCount corresponde ào número máximo de trocas que
deverá ser realizada pela função . Caso este argumento
nCount Numérico
não seja especificado , o default é substituir todas as
coorências encontradas.

Retorno

Tipo Descrição
A função UPSTRTRAN retorna uma nova string, com as ocorrências
Caracter especificadas de cSearch trocadas para cReplace, conforme
parâmetrização.

Descrição

Similar à função Strtran(), porém realiza a busca da ocorrência da string considerando


letras maiúsculas e minúsculas. A função Strtran() é case-sensitive, e a função
UpStrtran() não.
VALTOSQL
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

VALTOSQL ( < xExpressao > ) --> cQryExpr

Parâmetros

Argumento Tipo Descrição


Valor Advpl a ser convertido para utilização em Query.
xExpressao (Qualquer) Pode ser dos tipos "C" Caracter , "N" Numérico e "D"
Data.

Retorno

Tipo Descrição
Caracter Expressão a ser acrescentada na Query.

Descrição

A Função VALTOSQL() é utilizada como auxiliar na montagem de Query's ,


convertendo um conteúdo variável Advpl para a string correspondente a ser
acrescentada na Query.

Podemos passar como parâmetro uma Expressão do tipo “C” Caracter , “D” Data ou
“N” Numérica.

A expressão Catacter será colocada entre aspas simples, sendo removidas as


aspas simples contidas na mesma , caso existam .
Uma expressão numérica será simplesmente convertida para caracter , com
aproximação de 2 casas decimais.
Uma expressão Data será convertida para formato ANSI ( AAAAMMDD ) ,
entre aspas simples.
VARINFO
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

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

Parâmetros

Argumento Tipo Descrição


cId corresponde a um nome atribuído à variável para
cId Caracter análise. Internamente , apenas é utilizado para prefixar o
retorno das informações da VarInfo.
xVar (Qualquer) Variável de qualquer tipo a ser examinada
Corresponde à margem esquerda inicial de espaços da
nMargem Numérico
String de retorno , multiplicado por 5. Default = 0
Identifica se a String de retorno será montada em formato
lHtml Lógico
Html (.T. / Default ) ou ASCII (.F.)
Define se o Echo do retorno deve ser enviado ao console
lEcho Lógico
do Protheus Server , caso habilitado. ( Default = .T. )

Retorno

Tipo Descrição
String contendo o "Dump" da análise da variável. Caso lHtml seja .T. ,
Caracter retorna String em formato HTML . , senão retorna string ASCII com
quebras CRLF.

Descrição

A Função VARINFO() gera um texto ASCII e/ou Html , com possibilidade de ECHO
para o Console do Protheus Server ( caso habilitado ) , com as informações sobre o
conteúdo de uma variável de memória Advpl , de qualquer tipo .

Cada tipo de variável possui um tratamento para conversão em String :

CodeBlock : É exibido apenas o tipo da mesma (B)


Array : Todos os níveis e elementos do mesmo são explorados recursivamente.
Objeto : No caso de um Objeto de XML e/ou Web Services, são exploradas
todas as suas propriedades recursivamente.
(demais tipos) : São convertidos para String através da função AllToChar

Observação : O segundo parâmetro ( xVar ) deve ser uma variável Advpl que deve
existir no escopo de variáveis. Caso a variável não exista, o processamento é abortado
com a ocorrência de erro "Variablçe does not exist" . Para saber se uma determinada
variável existe no escopo da execução da função atual, deve ser utilizada a função
Advpl TYPE(), onde passamos a variável a ter seu tipo determinado como string ( entre
aspas ) .

WEBINFO
Revisão: 12/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

WEBINFO ( ) --> cHtmlInfo

Retorno

Tipo Descrição
cHTMLInfo corresponde à string HTML contendo as informações da
Caracter
requisição HTTP.

Descrição

A função WebInfo() foi desenvolvida para ser chamada através de uma requisição http ,
via link .apl ou .apw , e ela identifica todos os parâmetros recebidos via uma requisição
http: Parâmetros via get , post , o header HTTP, os Cookies, o content-type , Legth ,
Content-disposition , SoapRaction (ação SOAP para requisições de WebSErvices ) , e
OtherContent ( caso o conteúdo postado não seja um text/html )

Esta função retorna uma página Html com todas estas informações, e é utilizada no
desenvolvimento de projetos. quando temos a necessidade prática de
recuperarmos todas as informalções provenientes de uma requisição HTTP.
Adicionalmente , a função WebInfo

Por exemplo, com o Protheus configurado para atender requisições de links .apl via
HTTP , chame a função WebInfo.apl através 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 ( 0) [...]

__httpPage -> C ( 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.ms-powerpoint, 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) [ -1]

HttpRCtDisp() -> C ( 0) []

SoapRAction() -> C ( 0) []

HttpOtherContent() -> C ( 0) []

Caso a mesma requisição seja realizada através 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.ms-powerpoint, 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 ( 0) [...]

httpGet -> ARRAY ( 0) [...]

HttpRCtType() -> C ( 0) []

HttpRCtLen() -> N ( 10) [ -1]

HttpRCtDisp() -> C ( 0) []

SoapRAction() -> C ( 0) []

HttpOtherContent() -> C ( 0) []
[APWEXERR_0000] INVALID PROC
RETURN TYPE [X] ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / Causa : Na Infra-Estrutura ApWebEx, de acordo com o módulo WEB em


uso, é chamada durante a inicialização da Working Thread no ambiernte WEBEX uma
função específica [Y] para inicialização adicional de ambiente, e a lib exige um retorno
do tipo Booleano ( .T. ou .F. ) , indicando se a inicialização adicional foi executada com
sucesso ou não. Caso este ponto de entrada retorne um valor cujo tipo não seja
booleano, esta mensagem de erro é apresentada no console do Server e acrescentada ào
arquivo ERROR.LOG

Solução : Verifique o fonte do ponto de entrada e assegure-se que o mesmo está


retornando um valor Advpl do tipo 'L' Lógico.

[APWEXERR_0001] INVALID APWEX


CALL
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0001] INVALID APWEX CALL

Descrição / causa : Ao solicitarmos ao servidor Protheus o processamento de uma


função Advpl através de um link .apw, utilizando a infra-estrutura ApWebex, existem
funções específicas da linguagem que não podem ser executadas diretamente neste tipo
de ambiente, por tratarem-se de funções exclusivas para processamentos iniciados
através de um Remote, e funções que não permitem chamada direta via link. Caso
alguma destas funções seja chamada diretamente via URL, esta ocorrência de erro é
reproduzida.
[APWEXERR_0003] INVALID PROC
RETURN TYPE [X] ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Quando uma working thread do ambiente ApWebEx, recebe uma
solicitação de processamento através de um link .apw, de acordo com o módulo web
utilizado, pode ser chamada uma função intermediária [Y], antes do processamento da
função chamada no link ou depois do processamento concluído.

A lib exige que estas funções internediárias retornem um conteúdo Advpl do tipo
"STRING". Caso a função [Y] chamada pela lib retorne um conteúdo Advpl diferente
de "STRING", o tipo de variável retornado é mostrado em [X] e a Working Thread é
finalizada com esta ocorrência de erro.

Solução : Verifque o código-fonte da função [Y], para certificar-se que seu retorno
sempre será um conteúdo Advpl do tipo "STRING"
[APWEXERR_0004] INVALID PROC
RETURN TYPE [X] ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Quando solicitado ào servidor Protheus o processamento de uma


função através de um link .apw, a função executada sempre deverá retornar um
conteúdo Advpl do tipo "STRING". Caso o conteúdo retornado pelo processamento da
função [YYY] retorne um tipo [X], diferente de "STRING", a working thread é
finalizada com esta ocorrência de erro, onde [YYY] indica a função chamada através do
link .apw e [X] indica o tipo de conteúdo inválido retornado

Solução : Verifique o fonte da função [YYY] e certifique-se que a função sempre


retorne um conteúdo do tipo "STRING"
[APWEXERR_0005] Function XXX
requires APWEBEX ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0005] Function XXX requires APWEBEX Routines.

Descrição / causa : Ao desenvolvermos uma aplicação 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 função em um ambiente
de working threads, configurados com o tipo WEBEX, utilizando as funções da infra-
estrutura ApWebEx ( StartWebex , ConnectWebEx ... ) para inicialização e
processamento da requisição via link .apw .

Se uma função [XXX], escrita para ser chamada exclusivamente neste tipo de ambinete,
seja chamada diretamente via Protheus Remote, ou outro tipo de processamento que não
seja uma working thread inicializada pelas funções de infra-estrutura ApWebEx, a
função é abortada com esta ocorrência de erro. Isto também consistem em uma
proteção, para que uma função projetada para ser executada em um tipo de ambiente (
working threads ApWebEx ) não seja erroneamente executada em outro ambiente.

Solução : Verifique se a função chamada realmente está sendo executada no ambiente


apropriado.
[APWEXERR_0006] START Function
XXX Invalid Ret ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Quando é utilizado o comando WEB EXTENDED INIT,


especificando uma função [XXX] de pré-validação de execução, através da cláusula
START, a função especificada deverá retornar um conteúdo do tipo "STRING". Caso a
função [XXX] retorne um conteúdo não vazio, de tipo [Y], diferente de "STRING", o
processamento da working thread é abortado com esta ocorrência de erro.

Solução : Verifique o fonte da função [XXX] e assegure-se que a execução desta


retorne um conteúdo do tipo "STRING"
[APWEXERR_0007] APH page [XXX]
not found in .RPO
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Ao utilizarmos a função ExecInPage(), no desenvolvimento de


aplicações utilizando as funções de infra-estrutura ApWebex, a mesma possui
tratamento automático para buscar primeiramente por uma página AHU compilada no
repositório de objetos do ambiente. Caso não seja encontrado uma página .ahu, a função
procura por uma página .aph. Se nenhuma página com o nome especificado não for
encontrada, o processamento é abortado com esta ocorrência de erro.

Solução : Verifique se a função que originou a chamada da ExecInPage() passou o


nome do APH / AHU de forma correta, e se a página chamada está realmente presente
e/ou foi compilada no repositório do projeto em questão.
[APWEXERR_0008] OPEN QUERY
ERROR : NO CONNECTION
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0008] OPEN QUERY ERROR : NO CONNECTION

Descrição / causa : Ao utilizarmos o comando OPEN QUERY, caso não exista uma
conexão ativa com o TOPConnect, o processamento em execução é abortado com esta
ocorrência de erro.

Solução : Certifique-se de que a chamada deste comando está sendo realizada através
de uma working thread que possua uma conexão ativa com o TOPConnect.
[APWEXERR_0009] RetSqlCond failed
to read X2_MODO
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0009] Failed to read X2_MODO Alias [XXX]

Descrição / causa : Quando é utilizada a função RetSqlFil() como auxiliar na


montagem de querys, a mesma tenta determinar se o(s) alia(s) utilizado(s) na
Query estão configurados no ambiente ERP atual no SX2 em modo 'C' Compartilhado
ou 'E' Exclusivo. Caso o alias [XXX] não seja encontrado na tabela SX2, ou a tabela
SX2 não esteja aberta no momento da execução desta, não é possível identificar o modo
de acesso do alias especificado, e a execução é encerrada com esta ocorrência de erro.

Solução : Verifique se a função RetSqlFil() e/ou RetSqlCond() está recebendo o(s)


alia(s) corretos, todos em letras maiúsculas; caso especificados mais de um alias, todos
estejam separados por vírgulas, e que a tabela SX2 do ERP esteja aberta para a correta
identificação dos tratamentos de FILIAL para a montagem da condição para Query.
[APWEXERR_0010] ERP FINAL
ROUTINE CALLED
Revisão: 13/04/2004

[APWEXERR_0010] ERP FINAL ROUTINE CALLED

Descrição / causa : Quando executamos uma função em uma working thread


inicializada com as funções de infra-estrutura ApWebEx, a função final(), utilizada
internamente pelas funções de infra-estrutura do ERP Microsiga, possui neste ambiente
um tratamento diferenciado. Caso ela seja executada , a working thread é finalizada
com esta ocorrência de erro.

Solução : A função final() não deve ser utilizada como um recurso de finalização de
aplicação WEB, porém ela é utilizada internamente por funções da infra-estrutura ERP,
no caso de uma ocorrência fatal que impeça um determinado processamento, e ganhou
esta proteção na Lib ApWebEx para permitir o desenvolvimento de aplicações
integradas WEB / ERP.

Caso reproduzida uma ocorrência de erro desta natureza, verifique nos detalhes do erro
qual função que estava em execução e qual o motivo da finalização da working thread.
Este motivo está especificado no campo "Erp Message", mostrado nos detalhes da
ocorrência de erro.
[APWEXERR_0011] Argument #0 Error
: Parameter ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0011] Argument #0 Error : Parameter required.

Descrição / causa : Quando é utilizada a função ApWExAddErr(cTitle,cInfo), para


informar à rotina de tratamento de erro da infra-estrutura ApWebEx, uma informação
adicional a ser acrescentada no LOG de erro, os parâmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"

Solução : Esta ocorrência de erro informa que o parâmetro cTitle não foi especificado
ou está vazio, porém o parâmetro cInfo foi especificado. Verifique o código-fonte e
corriga a chamada da função.
[APWEXERR_0012] Argument #0 Error
: Expected C->X
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Quando é utilizada a função ApWExAddErr(cTitle,cInfo), para


informar à rotina de tratamento de erro da infra-estrutura ApWebEx, uma informação
adicional a ser acrescentada no LOG de erro, os parâmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"

Solução : Esta ocorrência de erro informa que o parâmetro cTitle foi especificado com
um tipo [X], que não é "STRING". Verifique o código-fonte e corrija o parâmetro
passado para a função.
[APWEXERR_0013] Argument #1 Error
: Parameter ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0013] Argument #1 Error : Parameter required.

Descrição / causa : Quando é utilizada a função ApWExAddErr(cTitle,cInfo), para


informar à rotina de tratamento de erro da infra-estrutura ApWebEx, uma informação
adicional a ser acrescentada no LOG de erro, os parâmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"

Solução : Esta ocorrência de erro informa que o parâmetro cInfo não foi especificado
ou está vazio, porém o parâmetro cTitle foi informado. Verifique o código-fonte e
corrija a chamada desta função.
[APWEXERR_0014] Argument #1 Error
: Expected C->X
Revisão: 13/04/2004

[APWEXERR_0014] Argument #1 Error : Expected C->X

Descrição / causa : Quando é utilizada a função ApWExAddErr(cTitle,cInfo), para


informar à rotina de tratamento de erro da infra-estrutura ApWebEx, uma informação
adicional a ser acrescentada no LOG de erro, os parâmetros cTitle e cInfo,quando
especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"

Solução : Esta ocorrência de erro informa que o parâmetro cInfo foi especificado com
um tipo de dado [X] que não é "STRING". Verifique o código-fonte e corrija a chamada
desta função.
[APWEXERR_0020] INVALID JOB
[XXX] TYPE [YYY]
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Esta ocorrência de erro indica que as configurações do Job [XXX],
de working threads para utilização no ambiente ApWebEx, está identificado com um
TYPE [XXX] inválido.

Durante a inicialização de uma working thread, é verificado o tipo do Job configurado


no arquivo de configuração. Apenas são válidos os valores WEB e/ou WEBEX, de
acordo com o módulo web em uso. Caso a configuração especifique um TYPE diferente
de WEB ou WEBEX, a configuração não é válida, e a working thread é abortada antes
de estar disponível para atender à requisições de links .apw, gerando uma ocorrência de
erro no console do servidor Protheus, também gravada no arquivo ERROR.LOG

Solução : Para solucionar esta ocorrência, basta verificar a configuração do Job [XXX]
utilizado para inicializar as working threads e especificar um tipo adequado ( WEB ou
WEBEX ), de acordo com o módulo em uso.
[APWEXERR_0021] UNABLE TO GET
JOB NAME
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11

[APWEXERR_0021] UNABLE TO GET JOB NAME

Descrição / causa : Esta ocorrência de erro indica que o processo atual em execução
não foi originado pela configuração de um processo WEB ou WEBEX , ou a função de
inicialização de ambiente STARTWEBEX não foi chamada através de um evento
ONSTART de JOB, como por exemplo um AP Remote.

Solução : Caso esta ocorrência seja reproduzida, cerifique-se que a função de


inicialização das working threads ( STARTWEBEX ) esteja sendo chamada através de
um processo configurado com TYPE=WEB ou WEBEX, de acordo com o módulo web
em uso.
[APWEXERR_0022] <T> Function [X]
of Module [Y] ...
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0022] <Start / Connect> Function [X] of Module [Y] not found in


Rpo.

Descrição / causa : Esta ocorrência de erro é reproduzida quando, ao configurar um


módulo web [Y], a função [X] de inicialização ou conexão referente ao módulo não foi
encontrada no repositório de objetos do ambiente em uso pela aplicação web.

Solução : Certifique-se que o repositório em uso atualmente possui as funções


pertinentes ào modulo configurado.
[APWEXERR_0023] UNSUPPORTED
BREAK CONTROL
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0023] UNSUPPORTED BREAK CONTROL

Descrição / causa : Ao utilizar as funções de Infra-Estrutura APWEBEX, quando da


chamada de uma função atravé de Link .apw , desde a chamada original até a passagem
pelos pontos de pré e pós-validação 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 execução é abortada
, e na rotina de tratamento de execução, não há o registro de controle de erro, de modo
que a working thread é abortada com esta ocorrência de erro.

Solução : Certifique-se que no códiugo fonte da aplicação não seja utilizado o comando
BREAK.

OBSERVAÇÃO : Como esta ocorrência é tratada em um ponto de retorno


interno, o ponto de entrada WEBEXERROR não é executado, sendo retornada ao
usuário a mensagem padrão de Erro.
[APWEXERR_0024] <T> Function [X]
of Module [Y] ...
Revisão: 13/04/2004

Abrangência

Versão 8.11 LIB WEBEX

[APWEXERR_0024] <Start / Connect / Finish > Function [X] of Module [Y] not
found in Rpo.

Descrição / causa : Esta ocorrência de erro é reproduzida quando, ao configurar um


módulo web [Y], a função [X] de inicialização, conexão ou finalização, referente ao
módulo, não foi encontrada no repositório de objetos do ambiente em uso pela aplicação
web.

Solução : Certifique-se que o repositório em uso atualmente possui as funções


pertinentes ào modulo configurado.
[APWEXERR_0025] Unknow
SIGAWEB Module [Y]
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11

[APWEXERR_0025] Unknow SIGAWEB Module [Y]

Descrição / causa : Quando da configuração de um módulo web para os tratamentos


internos das funções de infra-estrutura ApWebEx, devemos especificar uma sigla de um
módulo Web válido e tratado pela lib de infra-esturtura. Os módulos atualmente
implementados na lib são :

DW - Data WareHouse
BSC - Balanced ScoreCard
MAK - Modulo WEBEX Makira
GE - Gestão Educacional
GPR - Gestão de Pesquisa e Resultado
TCF - Terminal do Funcionario ( RH ONLINE )
PP - Portal PRotheus ( WebServices )
SAV - Sala de Aprendizagem Virtual
GAC - Gestão de Acervos
WPS - WebPrint & WebSpool

Caso não seja fornecida uma sigla válida na chave SIGAWEB, na seção de
configuração das working threads, as mesmas não entrarão no ar, e serão abortadas com
esta ocorrência de erro.

Solução : Verifique a chave de configuração SIGAWEB e preencha-a com uma sigla de


módulo válida para a versão de repositório / ambiente em uso.
[APWEXERR_0026] Web Services Test
POST ERROR.
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11

[APWEXERR_0026] Web Services Test POST ERROR..

Descrição / causa : Quando utilizamos a interface de testes de web services client da


ferramenta WebAdmin, caso ocorra uma falha estrutural no serviço Client ou uma
impossibilidade de recuperar todos os dados postados no fomulário de testes, o
processamento é interrompido com esta ocorrência de erro.
[APWEXERR_0027] INVALID NTOC
BASE [NNN]
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

[APWEXERR_0027] INVALID NTOC BASE [NNN]

Descrição / causa : Ao utilizar a função ntoc(), deve-se atentar ao limite de base


numérica para conversão, que pode ser um número entre 2 e 36. Caso a base passada
como parâmetro para a função ntoc() esteja fora destes limites, o processamento é
abortado com a ocorrência acima , informando em NNN a base utilizada.

Solução : Verifique a chamada da função ntoc() no fonte e certifique-se que está sendo
informado um número entre 2 e 36.
[APWEXERR_0028] MODULE [Y]
REQUIRES JOB TYPE=WEBEX
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Esta ocorrência de erro informa que a configuração de working


threads utilizada para este módulo web não possui o tipo adequado configurado. O
Módulo [Y] utilizado requer um job para working threads configurado com
TYPE=WEBEX, porém esta configuração está atualmente configurada como WEB.

Solução : Verifique a configuração das working threads deste módulo web e certifique-
se que a configuração TYPE está setada para WEBEX.
[APWEXERR_0029] MODULE [Y]
REQUIRES JOB TYPE=WEB
Revisão: 13/04/2004

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

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

Descrição / causa : Esta ocorrência de erro informa que a configuração de working


threads utilizada para este módulo web não possui o tipo adequado configurado. O
Módulo [Y] utilizado requer um job para working threads configurado com
TYPE=WEB, porém esta configuração está atualmente configurada como WEBEX.

Solução : Verifique a configuração das working threads deste módulo web e certifique-
se que a configuração TYPE está setada para WEB.
[APWEXERR_0030] NO WEB
LICENCES AVAILABLE (...
Revisão: 13/04/2004

Abrangência

Versão 8.11 LIB WEBEX

[APWEXERR_0030] NO WEB LICENCES AVAILABLE

Descrição / causa : Esta ocorrência de erro, indica que não há mais licenças Protheus i
disponíveis para a utilização da aplicação Web. Adicionalmente à esta ocorrência, é
informado adicionalmente a informação "WEB LICENSE STATUS [NNNN]", onde
nnnn indica o código de erro do HardLock utilizado para controle de licenças.

Solução : Verifique na lista completa de status de retorno do HarkLock , disponível em


(pendente), para certificar-se da origem desta ocorrência e então tomar uma ação
corretiva.
[APWEXERR_0031] WARNING : WEB
LICENSES WILL EXP...
Revisão: 13/04/2004

Abrangência

Versão 8.11 LIB WEBEX

[APWEXERR_0031] WARNING : WEB LICENSES WILL EXPIRES

Web Licenses will expires in NN day(s)

Descrição / causa : Esta ocorrência consiste em uma advertência, registrada no arquivo


error.log do ambiente em uso pela aplicação Web, registrada uma vez ao dia, a partir
do instante que faltam apenas 10 dias ou menos para que as licenças web ( Protheus i )
da aplicação expirem. O número de dias que restam para as licenças vencerem é
especificado adicionalmente em [NN].

Solução : Providencie a atualização das licenças Protheus i da aplicação web junto à


Microsiga.
Pontos de Entrada - APWEBEX
Revisão: 30/04/2004

Abrangência

Versão 8.11

Quando da utilização da infra-estrutura APWEBEX, especificamente o módulo 'MAK' (


Makira ), são disponibilizados os pontos de entrada relacionados neste tópico, para
permitir customizar e interceptar os eventos de Inicialização da Thread ( U_StartWebEx
), atendimento a requisições de links .apw antes de processar a função principal (
U_ConnectWebEx ), atendimento a requisições de links .apw após processada a função
principal ( U_ResetWebEx ), finalização da Thread ( U_FinishWebEx ), finalização de
session de usuário por Time-out ( U_EndSession ), e customização da mensagem de
erro HTML, quando da ocorrência de algum erro fatal na aplicação (
U_WEBEXERROR ).

Quando utilizada a infra-estrutura APWEBEX para um módulo do padrão, estes pontos


de entrada não tem efeito. Fica a critério de cada módulo a disponibilização de pontos
de entrada para interceptar estes eventos. Para saber quais pontos foram implementados
para um módulo web do padrão, deve ser consultada a documentação do módulo
correspondente.
01. STARTWEBEX
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

01. STARTWEBEX ( [ NIL ] ) --> lSucess

Parâmetros

Argumento Tipo Descrição


NIL (NULO) Este ponto de entrada não recebe parâmetros.

Retorno

Tipo Descrição
lSucess corresponde ào status de montagem de ambiente. Caso o ambiente
tenha sido montado com sucesso , o ponto de entrada deve retornar .T. ,
Lógico
caso contrário .F. . Uma vez retornado .F. , o Protheus irá eliminar esta
Working Thread da memória.

Descrição

Este ponto de entrada é executado na inicialização de cada Working Thread,


quando utilizada a configuração para a Lib APWEBEX.

Através dele, devemos iniciar o ambiente necessário ào atendimento das requisições de


processamento via Browser , atravésde links .apw, tais como a abertura de dicionários e
conexão com o Banco de Dados.

Grupos Relacionados
Principal / A Tecnologia Protheus / Programação Advpl para WEB / Infra-Estrutura
APWEBEX / Pontos de Entrada
02. CONNECTWEBEX
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

02. CONNECTWEBEX ( < cFnLink > ) --> cHtmlVld

Parâmetros

Argumento Tipo Descrição


Função chamada através do Link . Por exemplo , um link
no browse chamando
cFnLink Caracter
http://localhost/w_teste.apw?Opc=03 , seria recebido neste
parâmetro a string "W_TESTE"

Retorno

Tipo Descrição
Caso retornada uma string em branco , a execução da função
originalmente chamada no link .apw prossegue normalmente. Caso
Caracter
contrário , a string retornada é devolvida ao Browser solicitante , e a
função chamada através do link não é executada.

Descrição

Este ponto de entrada é executado imediatamente antes do processamento de uma


requisição realizada através de um browser para processamento de uma função Advpl ,
através de um link .apw , permitindo realizar uma pré-validação antes de cada
processamento solicitado através do Browser.
03. RESETWEBEX
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

03. RESETWEBEX ( < cFnLick > ) --> cHtmlAdd

Parâmetros

Argumento Tipo Descrição


cFnLink corresponde à função Advpl que foi chamada e
cFnLick Caracter processada imediatamente antes da chamada deste ponto
de entrada.

Retorno

Tipo Descrição
Este ponto de entrada DEVE retornar uma string , podendo ser inclusive
Caracter uma string vazia. A String retornada será acrescentada ao Codigo Html a
ser retornado ao Browser

Descrição

Este ponto de entrada é executado imediatamente após o processamento de uma


requisição de processamento Advpl através de um Web Browser utilizando as
configurações e Lib APWEBEX.

Ele permite que seja executado um processamento adicional após o processamento de


cada requisição .apw , e aida permite um retorno de html adicional ao browser.

Vale a pena lembrar que este ponto não será executado em caso de erro fatal no ponto
de entrada U_CONNECTWEBEX ou na execução da função principal chamada através
do Link.
04. FINISHWEBEX
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

04. FINISHWEBEX ( ) --> NIL

Parâmetros

Argumento Tipo Descrição

Retorno

Tipo Descrição
(NULO) O Retorno deste ponto de entrada não é utilizado.

Descrição

Este ponto de entrada é executado quando da finalização ( Fechamento ) de uma


Working Thread APWEBEX. Não recebe parâmetros , e não requer retorno. Ele permite
que seja executado um procedimento qualquer no momento da saída de uma Working
Thread, seja por time-out ou por tempo total de permanência no ar.
05. ENDSESSION
Revisão: 10/12/2003

Abrangência

Versão 7.10 Versão 8.11 LIB WEBEX

Sintaxe

05. ENDSESSION ( < cSessionId > ) --> NIL

Parâmetros

Argumento Tipo Descrição


cSessionId corresponde à string identificadora das sessions
cSessionId Caracter
deste usuário.

Retorno

Tipo Descrição
(NULO) O retorno deste ponto de entrada deve ser nulo

Descrição

Através deste ponto de entrada , podemos executar uma rotina Advpl quando da
finalização das sessions de um usuário por time-out de inatividade. O Retorno deste
ponto de entrada não é utilizado, devendo ser nulo (NIL).

Apenas devemos compilar este ponto de entrada no Projeto caso realmente exista a
necessidade de ser executado um processamento específico relacionado à finalização
das sessions de um usuário. Vale a pena ressaltar também que este ponto de entrada
apenas é chamado na finalização das sessions por tempo de inatividade. Caso seja
utilizada a função httpfreesession() para limpar da memória as sessions do usuário atual
em uma Working Thread, este ponto de entrada não será chamado.
06. WEBEXERROR
Revisão: 16/12/2003

Abrangência

LIB WEBEX

Sintaxe

06. WEBEXERROR ( < oErrorObj > , < cErrorLog > , < cErrorHtml > ) --> cMsgHtml

Parâmetros

Argumento Tipo Descrição


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 Descrição
Retorno opcional. Caso retornado NIL ou string vazia , será retornado ao
usuario o html de erro gerado pela rotina de tratamento standard. Caso o
Caracter
ponto de entrada retorne uma String HTML , ela será mostrada ao usuário
no ligar do Html gerado pela rotina de tratamento de erro.

Descrição

Este ponto de entrada será chamado no caso de uma ocorrência de erro fatal Advpl
durante a execução de uma Working Thread em ambiente / Lib APWEBEX, permitindo
a montagem de uma mensagem de erro HTML customizada a ser devolvida ào usuário.

Este ponto de entrada recebe como parâmetros o objeto do erro , a descrição 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. Através da utilização deste ponto de
entrada , é possível gerar um Html diferenciado conforme a necessidade, para mostrar a
ocorrência de erro e/ou maiores instruções ao usuário.

OBSERVAÇÕES

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 usuário
a mensagem de erro Html default gerada pela rotina de tratamento de erro.
Este ponto de entrada será chamado apenas caso a ocorrência de erro esteja
relacionada com uma chamada de função via link .apw, aplicando-se
apenas à função .apw chamada e àos pontos de entrada
U_CONNECTWEBEX e U_RESETWEBEX. Em caso de ocorrências de
erro no start da Thread (U_STARTWEBEX), na finalização da Thread (
U_FINISHWEBEX ) e na finalização de sessions de usuário por time-out (
U_ENDSESSION ), o ponto de entrada U_WEBEXERROR não será
chamado .

Recomenda-se fortemente que , na montagem da função deste ponto de


entrada , não seja utilizado nenhum recurso Advpl que dependa de ambiente ,
disco , base de dados ou Session , limitando-se apenas à customizar uma
mensagem de ocorrência de erro ao usuário .

Caso seja reproduzida alguma ocorrência de erro neste ponto de entrada, isto
fará a aplicação ( Protheus Server ) enviar ao Browser um Html gerado pela
rotina de tratamento de erro default do Protheus.
A HREF - Âncoras e espaços
Revisão: 11/12/2003

Quando passamos parâmetros de uma página para outra , via query string (URL) ,
devemos ter o cuidado de não deixar espaço(s) em branco entre parâmetros na
montagem da URL. Quando utilizamos o Internet Explorer os espaços em branco são
convertidos (*) automativamente para a sequência String %20, porém quando
utilizamos o Netscape, quando colocamos um espaço em branco em um parâmetro , o
NetScape IGNORA tudo o que vem após o primeiro espaço em branco , perdendo assim
os demais parâmetros.

Consideremos o exemplo abaixo :

<a href='/webinfo.apw?par1=123 &par2=345'>Link</a>

No Internet Explorer não haverá problemas (*) , pois os espaços serão convertidos. No
Netscape , o parâmetro par2 não 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 função escape() , para


converter caracteres reservados e espaços da stringlist para a notação Hexadecimal
(%HH) para serem enviados corretamente pela URL

<a href='webinfo.apw?par1=<%=Escape(cCodigo)%>&par2=345'>Link</a>

Observação : Vale a pena lembrar que a função escape() deve ser aplicada apenas àos
conteúdos da stringlist, pois se por exemplo for convertido pela escape() o caracter
separador de parâmetros & ( e Comercial ), este caractere será interpretado como
DADO e não como separador, comprometendo o funcionamento do link.
Combo / Select em Html : Recuperando
valores
Revisão: 11/12/2003

Examinemos o exemplo abaixo , onde criamos um formulário HTML com um 'Combo


Box' ( tag <SELECT> do HTML), de seleção única , e queremos saber qual o valor que
o usuário 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 código funciona perfeitamente . Porém , o NetScape


mosstrará o conteúdo como null, pois ele não atribui uma propriedade value a um
combo partindo de uma seleção.

Para que seja recuperado o valor do elemento selecionado , utilizamos o código abaixo ,
compatível 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 função 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>

Diferenças entre os Navegadores IE e


Konqueror
Revisão: 13/04/2004

1. Atualização de frames com window.open

Ocorrencia : Para chamar uma nova página no IE, cujo destino será o frame atual ou
página atual do Browser, podemos usar a função javascript : window.open( 'xxx.apw',
'_self' ) . No IE (Interbet Explorer) o link chamado é aberto no mesmo frame de onde a
instrução é chamada, mas no Konqueror esta instrução abre uma nova janela com o
nome '_self'.

Solução : Utilize a instrução JavaScript window.location para atualizar o endereço da


janela atual ou frame especificado. Por exemplo , window.location='xxx.apw'

Estrutura de Frames em HTML


Revisão: 15/12/2003

Abrangência

Versões 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 não suporta frames</noframes>
</frameset>
</HTML>
Dicas úteis

Procurem sempre utilizar a TAG <noframes> para mostrar uma mensagem de


erro no Browse se o mesmo não possuir o recurso de interpretação 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
necessário uma página em branco como um dos frames , para criação dinâmica
ou algo parecido , utilize o source about:blank
Caso um frame da estrutura não tenha a tag src='...' preenchida , o Netscape
mostrará uma janela com a seguinte mensagem quando se entra na página de
frames:

'The document contained no data.


Try again later , or contact the server's administrator.'

A tag <body> não é suportada. na declaração dos frames. Jamais usem esta tag
em uma estrutura de frames.

Mostrando campos MEMO em Html


Revisão: 15/12/2003

Abrangência

Versões Anteriores

Para visualizar o conteúdo de um campo MEMO em uma página HTML , devemos


realizar algumas conversões de caracteres para o efeito desejado. Em HTML , temos
dois modos de interpretação :

1) Default -> Interpretação HTML , os Caractetes CRLF ( chr(13) / chr(10) ) não são
considerados como pulo de linha , de modo que as quebras de linha são de acordo com
o design aplicado e/ou o tamanho disponível no browse para a visualização do dado.

2) Pré-formatado -> Interpretação semelhante à um arquivo ASCII , utiliza um tipo de


letra 'Regular Type' , mono-espaçada , considerando os códigos CRLF como quebra de
linha , independente do design aplicado. Definimos uma area a ser interpretada como
texto pré-formatado através das tags <pre> ... </pre>

A solução mais comum para a visualização de campos Memo ( inclusive foi a solucão
adotada aki no Banco de Conhecimento - DEM ) , é a de trocar os códigos CRLF pela
tag '<br>' , para apenas realizar um pulo de linha no fim do parágrafo. Apenas para
textos de Exemplos de Código ADVPL são utilizadas as tag <pre> .. </pre>, para que a
quebra de linha seja unica e exclusivamente realizada no CRLF , mesmo que o tamanho
da tela não 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 interpretáveis dentro do memo , que não devam ser interpretadas
pelo browse , mas sim constar como conteúdo do campo , devemos utilizar a funcao
HtmlNoTags , dentro da expressão anteriormente montada :

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


)%>

Se a função HtmlNoTags receber como parametro o retorno da StrTran , serão


mostrados na tela as tags '<br>' , que originalmente devem ser interpretadas pelo browse
como quebras de linha.

Refresh em Html / JavaScript


Revisão: 15/12/2003

Abrangência

Versões Anteriores

Em Html, para setar um refresh automatico da página 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 execução de uma função automaticamente em um intervalo


de tempo, podemos utilizar a função setTimeOut()

Função setTimeout(<cFunc>,<nTime>)
Ambiente JavaScript
Parametros :
<cFunc> = Nome da funcao em Java a executar
<nTime> = intervalo de execucao (milisegundos)

Observação : Nas funções de Infra-Estrutura APWEBEX, foi criada a função Advpl


RedirPage(), que monta o script de redirecionamento conforme os parâmetros recebidos,
podendo ser especificado o tempo de espera para o redirecionamento e um TARGET
diferenciado para o redirecionamento.
Funções com ADVPL ASP
Revisão: 26/07/2004

Abrangência

Versão 5.07 Versão 5.08 Versão 6.09 Versão 7.10 Versão 8.11

O código abaixo representa o arquivo ms01.APH, que


contém 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 código abaixo representa o arquivo ms02.APH, que


contém a parte do formulário

<html>

<head>
<title>ADVPL ASP</title>
</head>
<script language="javascript">
//Codigo JavaScript no qual não permite que o formulário 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 Formulário" );
return;
}

oFrm.action = "w_ms03.apw";
oFrm.submit();
}

</script>
<body>
<h2 align="center"> Formulário</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>Endereço : <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 código abaixo representa o arquivo ms03.APH, que


contém uma tabela que exibe os dados
preenchidos no formulário, mais um contador do total
de vezes que foi realizado esse formulário

<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>Endereço;</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 código abaixo representa o arquivo ms01.PRW, que


contém as funções escritas em ADVPL ASP

#INCLUDE "PROTHEUS.CH"

#DEFINE ID "Admin"
#DEFINE SENHA "123"

web function ms01()

//A função é executada quando é chamada através do browser.

return h_ms01()

web function ms02()


//Verifica se é a primeira vez q usuário 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 não informados!!"
endif

//Verifica usuário e senha.


if HttpPost->txt_Nome != ID
return "Usuário Inválido!!"
endif
if HttpPost->txt_Senha != SENHA
return "Senha Inválida!!"
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
Revisão: 05/10/2004

Abrangência

Versão 7.10 Versão 8.11

Este exemplo de ADVPL ASP mostra como realizar o upload de um arquivo via HTTP.

O código abaixo representa o arquivo "ms01.APH", que contém um


formulário 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 código abaixo representa o arquivo "upload.APH", que contém um


formulário para exibir alguns dados do aquivo enviado.

A parte mais importante desse código, 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 código abaixo representa o arquivo "upload.PRW", que contém as


funções 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
Revisão: 13/04/2004

HTML, abreviação para 'HyperText Markup Language', que significa 'Linguagem de


Formatação de HyperTexto'

HTML é a formatação padrão adotada para a publicação de HyperTexto na Internet


(World Wide Web). O HTML consiste em uma formatação não-proprietária, baseada no
SGML ( Standard Generalized Markup Language ), e pode ser criada e processada por
um grande número 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
Revisão: 13/04/2004

HTTP é a abreviação de 'Hyper Text Transfer Protocol', que significa 'Protocolo de


Transferência de Hyper-Texto'.

O HTTP é um protocolo em nível de aplicação para distribuição de informações. Trata-


se de um protocolo genérico, que pode ser utilizado para muitas outras aplicações além
de transferência de hypertexto, como nomear servidores e trocas de informações entre
sistemas integrados, utilizando-se suas extensões, códigos de erro, métodos de
requisição e cabeçalhos (Headers). Uma característica importante do HTTP é a tipagem
e normalização da representação da informação, permitindo a construção de sistemas
independente do modo pelo qual os dados estão sendo transferidos.
Threads e working threads
Revisão: 13/04/2004

O que é uma Thread?

A maioria dos programadores está familiarizada com programas de execução


sequêncial. Você provavelmente já deve ter escrito um programa que mostra 'Olá
Mundo' ou ordena uma lista de nomes, ou calcula uma lista de números primos. Estes
programas são sequenciais, e cada um deles têm um começo, uma sequência de
execução e um final . Em qualquer momento da execução do programa, temos apenas
um ponto de execução.

Uma Thread é semelhante ào programa descrito acima, tendo um começo, meio e fim.
Porém, uma Thread em si não é um programa, pois ela não se executa : ela roda (com) o
programa !

Por definição : Uma Thread é o fluxo seqüencial de controle único dentro de um


programa.

Não há nada de novo ou especial sobre programas sequenciais executados em uma


simples thread. A grande sacada consiste no uso de Múltiplas Threasds dentro de uma
aplicação, todas em execução simultânea, porém cada uma realizando tarefas diferentes.

De tal modo que, por estarem realizando tatefas independenres, cada thread possui o seu
próprio contexto de execução, alocação de memória e controle de pilha de execução
(Stack). O código em execução em uma Thread trabalha dentro de seu contexto
específico, de modo que várias outras documentações referem-se ao 'contexto de
execução' como sendo um sinônimo de Thread.

Working threads

Damos o nome de 'working thread' quando são iniciadas mais de uma thread
independente na aplicação, e todas as threads iniciadas são colocadas em 'modo de
espera' (idle), aguardando uma solicitação de processamento da aplicação. Mais de uma
solicitação pode ser realizada, e o núcleo da aplicação encarrega-se de distribuir os
processamentos entre as threads disponçiveis. Terminado o processamento de uma
thread, a mesma retorna ao 'modo de espera', estando pronta novamente para atender à
uma nova solicitação. Este recurso possibilita um ganho significativo de performance,
por não haver a necessidade de criar e finalizar uma nova thread para cada solicitação
de processamento.