Web Programaao Advpl para Web

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
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
1
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 desenvo lvedor 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
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
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.
2
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
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:
3
 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ńú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
4
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.
5
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
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írá 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
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
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
Instances=1,3
;; Configuração da seção httpo default para atender à requisições de .apl e .apw
[http]
6
Enable=1
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
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.
7
02. Alias virtual HttpCookies
Revisão: 08/12/2003
Abrangência
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
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
conout('GET '+str(nI,3)+' = '+aInfo[nI])
Next
04. Alias virtual HttpPost

Revisão: 08/12/2003
Abrangência
Através do alias virtual HttpPost, podemos consultar os campos submetidos ào servidor através do método POST.
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
conout('POST '+str(nI,3)+' = '+aInfo[nI])
Next
05. Alias virtual HttpHeadIn

Revisão: 08/12/2003
Abrangência
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.
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'
8
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
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 à
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
9
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
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
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
10
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
Sintaxe
CLOSE QUERY cAlias
Parâmetros
Argumento Tipo Descrição
Alias sob o qual o cursor da Query foi aberto. Caso o alias passado como parâmetro não se encontre aberto , a função não gera nenhuma ocorrência de
cAlias Caracter
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
Sintaxe
OPEN QUERY <cQuery> ALIAS <cAlias> [ [NOCHANGE] ]
Parâmetros
<cQuery> Caracter cQuery corresponde à String contendo a Query a ser 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 Advpl. Não pode ser especificado
ALIAS <cAlias> Caracter
um nome de alias já em uso, senão a aplicação será finalizada com a ocorrência de erro "Alias already in Use"
[NOCHANGE] Caracter Caso especificada a cláusola NOCHANGE na abertura da 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
Sintaxe
WEB EXTENDED END <cHtml> [ START <cFnStart> ]
Parâmetros
cHtml corresponde à variavel que será utilizada para armazenar a String Html que será retornada ao Browser solicitante do processamento. Deve ser
<cHtml> Caracter
especificada uma variável String , com conteúdo vazio. ("")
cFnStart corresponde ào nome de uma função Advpl que será executada para pré-validar a execução do resto do código. A função deve ser passada
START <cFnStart> Caracter
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
Sintaxe
WEB EXTENDED INIT <cHtml> [ START <cFnStart> ]
Parâmetros
cHtml corresponde à variavel que será utilizada para armazenar a String Html que será retornada ao Browser solicitante do processamento. Deve ser
<cHtml> Caracter
especificada uma variável String , com conteúdo vazio. ("")
cFnStart corresponde ào nome de uma função Advpl que será executada para pré-validar a execução do resto do código. A função deve ser passada
START <cFnStart> Caracter
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.
11
Infra-Estrutura APWEBEX - EnvUser.APL - Exemplo de Uso com ERP
Revisão: 16/12/2003
Abrangência
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 += '
12
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
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
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
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(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(cRelacao) // 2x3
conout(cInfo) // ---Informação Adicional---
Infra-Estrutura APWEBEX - Exemplo da função HEXSTRDUMP

Revisão: 15/12/2003
Abrangência
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
13
// 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
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.
'+HtmlNoTags(cIn
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')
14
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
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
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
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
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
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.
15
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
Sintaxe
APWEXADDERR ( [ cTitulo ] , [ cInfo ] ) --> .T.
Parâmetros
cTitulo corresponde a um título identificador da informação. Deve ter no máximo 20 caracteres. Os caracteres acima da vigésima posição serão
cTitulo Caracter
ignorados.
cInfo Caracter cInfo corresponde à Informação a ser acrescentada ao 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
Sintaxe
CAPITALACE ( < cString > ) --> cStrCapital
Parâmetros
cString Caracter String a ser convertida.
Retorno
Tipo Descrição
Caracter String resultante convertida para munúsculo , com as primeiras letras das 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
Sintaxe
CTON ( < cString > , < nBase > ) --> nNumero
Parâmetros
cString Caracter cString corresponde à representação de um número em outra base numérica, compreendida entre 2 e 36.
nBase Numérico nBase corresponde à base numérica utilizada pelo numero 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
Sintaxe
ESCAPE ( < cString > ) --> cEscaped
Parâmetros
cString Caracter cString é uma sequência de caracteres a ser processada.
Retorno
Tipo Descrição
Caracter cEscaped corresponde à string original , com os caracteres reservados 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()
16
EXECINPAGE
Revisão: 12/12/2003
Abrangência
Sintaxe
EXECINPAGE ( < cAPHPage > ) --> cHTMLPage
Parâmetros
cAPHPage Caracter Corresponde ào nome do APH que deve ser executado, 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
Sintaxe
EXISTPAGE ( < cAphFile > ) --> lFound
Parâmetros
cAphFile Caracter Nome do arquivo APH, sem extensão e sem path , a ser verificado.
Retorno
Tipo Descrição
Caracter Retorna um valor booleano indicando se o arquivo APH especificado está 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
Sintaxe
EXISTUSRPAGE ( < cAhuFile > ) --> lExist
Parâmetros
cAhuFile Caracter Nome do arquivo AHU, sem extensão e sem path , a ser verificado
Retorno
Tipo Descrição
Lógico Retorna um valor booleano indicando se o arquivo APH especificado está 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
Sintaxe
GETJOBPROFSTRING ( < cKey > , < cDefault > ) --> cKeyValue
Parâmetros
cKey Caracter cKey corresponde à chave da seção de configuração da Working Thread atual a ser retornada.
cDefault Caracter Valor default (string) a ser retornado pela função caso a chave especificada não sehja encontrada no .INI
Retorno
Tipo Descrição
Caracter Conteudo da Chave solicitada . Caso a chave não seja encontrada , é retornado o conteudo de cDefault . Caso esta função não seja executada a partir de uma Working Thread , ela
17
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
Sintaxe
GETWEXVERSION ( ) --> cBuildId
Retorno
Tipo Descrição
Caracter Corresponde à String Identificadora da versão , no formato <LIB> 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
(HTTP) Indica que a versão foi compilada com a configuracão de envio progressivo de 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
Sintaxe
HEXSTRDUMP ( < cString > , [ nStart ] , [ nLength ] ) --> cHExDump
Parâmetros
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 1. Caso este parâmetro não seja informado , o
nStart Numérico
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 nStart. Caso este parâmetro não
nLength Numérico
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 caracteres em Ansi. Os caracteres de
Caracter
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
Sintaxe
HTMLNOTAGS ( < cStrHtml > ) --> cStrNoTags
Parâmetros
cStrHtml Caracter cStrHtml corresponde a uma String que não pode conter caracteres Html interpretáveis.
Retorno
Tipo Descrição
Caracter String original com os caracteres interpretáveis Html < > & " convertidos 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
Lógico A função retornará .T. caso o ambiente de execução atual seja uma 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
18
Sintaxe
ISEMAIL ( < cEMail > ) --> lEmailOk
Parâmetros
cEMail Caracter cEmail corresponde a string a ser analizada , contendo um e apenas um endereço de e-mail.
Retorno
Tipo Descrição
Caracter Retorna .T. caso a sring recebida como parâmetro atenda às definições de 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
Sintaxe
LOWERACE ( < cString > ) --> cStrLower
Parâmetros
cString Caracter cString é a sequência de caracteres a ser convertida para 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
Sintaxe
NTOC ( < nNumero > , < nBase > , < nTamStr > ) --> cString
Parâmetros
nNumero Numérico nNumero é o valor numérico , em base devimal , a ser convertido.
nBase Numérico nBase corresponde à base binária a ser utilizada para converter nNumero.
nTamStr Numérico nTamStr corresponde ao tamanho da string representando o numero na base desejada .
Retorno
Tipo Descrição
Caracter cString corresponde ao numero convertido para a base numérica 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
Sintaxe
REDIRPAGE ( < cUrl > , [ cTarget ] , [ nTime ] ) --> cScript
Parâmetros
cUrl Caracter Link para onde o script deve apontar o redirecionamento
cTarget Caracter Destino do redirecionamento. Caso não especificado , o default é _self.
nTime Numérico Tempo (em segundos) de delay antes do redirecionamento ser executado.
Retorno
Tipo Descrição
Caracter Script Html / JavaScript que , ao ser executado no Browser (client) , 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
Sintaxe
RETSQLACE ( < cStrFind > ) --> cStrQuery
Parâmetros
cStrFind Caracter cStrFind corresponde à sequência de caracteres a ser procurada , podendo conter caracteres maiúsculos e minúsculos , com ou sem acentuação.
Retorno
Tipo Descrição
Caracter cStrQuery corresponde à string de busca a ser utilizada na query, 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 .
19
RETSQLCOND
Revisão: 12/12/2003
Abrangência
Sintaxe
RETSQLCOND ( < cAliases > ) --> cSqlWhere
Parâmetros
cAliases Caracter Lista contendo um ou mais aliases , separados por vírgula , a serem considerados para a montagem da expressão de validação.
Retorno
Tipo Descrição
Caracter Corresponde à expressão SQL para filtrar os dados através da cláusula 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
Sintaxe
RETSQLDEL ( < cAliases > ) --> cSqlWhere
Parâmetros
Retorno
Tipo Descrição
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
Sintaxe
RETSQLFIL ( < cAliases > , [ cCompFil ] ) --> cSQlWhere
Parâmetros
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.
cCompFil Caracter Caso não 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
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
Sintaxe
RETSQLTAB ( < cAliasList > ) --> cStrQuery
Parâmetros
cAliasList Caracter String contendo um ou mais alias , separados por virgula , a terem seus nomes físicos determinados.
Retorno
Tipo Descrição
Caracter String contendo nomes fisicos e alias identificadores dos aliases recebidos como parâmetro.
Descrição
20
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
Sintaxe
SEPARA ( < cString > , < cToken > , < lEmpty > ) --> aTokens
Parâmetros
cString Caracter String com a sequência de caracteres a ser "parseada"
cToken Caracter cToken corresponde à string a ser utilizada como separador para delimitar as informações.
lEmpty Caracter lEmpty identifica se caso um intervalo vazio entre tokens deve ser retornado como um elemento do array. Caso não especificado , o Default é .T.
Retorno
Tipo Descrição
Caracter Array de uma dimensão contendo os elementos parseados pela rotina 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
Sintaxe
UNESCAPE ( < cString > ) --> cUnEscaped
Parâmetros
cString Caracter cString é a string a ter os caracteres em formato escape convertidos.
Retorno
Tipo Descrição
Caracter cUnescaped corresponde à string recebida como parâmwetro , com os 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
Sintaxe
UPPERACE ( < cString > ) --> cStrUpper
Parâmetros
cString Caracter String a ser convertida. Pode conter também acentos .
Retorno
Tipo Descrição
Caracter Retorna a string original com todas as letras mauisculas , inclusive as 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
Sintaxe
UPSTRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [ nCount ] ) --> cNewString
Parâmetros
cString Caracter cString corresponde à sequência de caracteres ou campo memo a ser pesquisado.
cSearch Caracter Corresponde à sequência de caracteres a ser procurada em cString
cReplace corresponde à sequência de caracteres que deve substituir a string cSearch. Caso não seja especificado, as ocorrências de cSearch em cString
cReplace Caracter
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 cReplace. Se este argumento for omitodo
nStart Numérico
, 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 não seja especificado , o default é
nCount Numérico
substituir todas as coorências encontradas.
Retorno
Tipo Descrição
Caracter A função UPSTRTRAN retorna uma nova string, com as ocorrências 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
21
Sintaxe
VALTOSQL ( < xExpressao > ) --> cQryExpr
Parâmetros
xExpressao (Qualquer) Valor Advpl a ser convertido para utilização em Query. 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
Sintaxe
VARINFO ( < cId > , < xVar > , [ nMargem ] , [ lHtml ] , [ lEcho ] ) --> cVarInfo
Parâmetros
cId Caracter cId corresponde a um nome atribuído à variável para análise. Internamente , apenas é utilizado para prefixar o retorno das informações da VarInfo.
xVar (Qualquer) Variável de qualquer tipo a ser examinada
nMargem Numérico Corresponde à margem esquerda inicial de espaços da String de retorno , multiplicado por 5. Default = 0
lHtml Lógico Identifica se a String de retorno será montada em formato Html (.T. / Default ) ou ASCII (.F.)
lEcho Lógico Define se o Echo do retorno deve ser enviado ao console do Protheus Server , caso habilitado. ( Default = .T. )
Retorno
Tipo Descrição
Caracter String contendo o "Dump" da análise da variável. Caso lHtml seja .T. , 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
Sintaxe
WEBINFO ( ) --> cHtmlInfo
Retorno
Tipo Descrição
Caracter cHTMLInfo corresponde à string HTML contendo as informações da 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]
22
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
[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
[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.
Revisão: 13/04/2004
Abrangência
[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"

Revisão: 13/04/2004
Abrangência
[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
[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
[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
[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
23
Revisão: 13/04/2004
Abrangência
[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
[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
[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

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
[APWEXERR_0013] Argument #1 Error : Parameter required.

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.

Revisão: 13/04/2004

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
[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
[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
24
[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
[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
[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
[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
[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
[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
[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
[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 (...
25
Revisão: 13/04/2004
Abrangência
[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
[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
Sintaxe
01. STARTWEBEX ( [ NIL ] ) --> lSucess
Parâmetros
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. , caso contrário .F. . Uma vez
Lógico
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
Sintaxe
02. CONNECTWEBEX ( < cFnLink > ) --> cHtmlVld
Parâmetros
Função chamada através do Link . Por exemplo , um link no browse chamando http://localhost/w_teste.apw?Opc=03 , seria recebido neste parâmetro a
cFnLink Caracter
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 contrário , a string retornada é devolvida ao Browser
Caracter
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
Sintaxe
03. RESETWEBEX ( < cFnLick > ) --> cHtmlAdd
Parâmetros
cFnLick Caracter cFnLink corresponde à função Advpl que foi chamada e processada imediatamente antes da chamada deste ponto de entrada.
Retorno
Tipo Descrição
Caracter Este ponto de entrada DEVE retornar uma string , podendo ser inclusive uma string vazia. A String retornada será acrescentada ao Codigo Html a ser retornado ao Browser
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.
26
04. FINISHWEBEX
Revisão: 10/12/2003
Abrangência
Sintaxe
04. FINISHWEBEX ( ) --> NIL
Parâmetros
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
Sintaxe
05. ENDSESSION ( < cSessionId > ) --> NIL
Parâmetros
cSessionId Caracter cSessionId corresponde à string identificadora das sessions 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
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 ponto de entrada retorne uma String
Caracter
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
27
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
</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.
28
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
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>
29
<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
#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
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;
30
}
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 "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.
31

Web Programaao Advpl para Web

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Web Programaao Advpl para Web

Enviado por

Direitos autorais:

Formatos disponíveis

Programação Advpl para WEB

01. O Servidor Protheus como um servidor HTTP

O Servidor Protheus como um servidor HTTP

Princípio de Funcionamento do HTTP

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

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

<% While !EOF() %>

02. Executando funções Advpl via HTTP

Princípio de Funcionamento do HTTP

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

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

<% While !EOF() %>

<% IF !lOk %>

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

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

04. Desenvolvimento de Funções .APL

{ {“nome”, “NOME DIGITADO NA PAGINA HTML”},

Exemplo de função APL

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

// Coloca uma mensagem em HTML

// Coloca um separador de linha em HTML

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

05. Desenvolvimento de Funções .APW

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

01. Recepção de parâmetros por Alias Virtuais

03. Alias virtual HttpGet

04. Alias virtual HttpPost

05. Alias virtual HttpHeadIn

07. Alias virtual HttpSession

User Function TstSession()

WEB EXTENDED INIT cHtml

cHtml += cEcho + '<hr>'

WEB EXTENDED END

08. Envio simultâneo de HTML ao Browser

09. Configurações específicas APWEBEX

11. Monitoramento de Sites em WEBEX

User Function SiteMonitor()

// Verifica se a working Thread está conectada com o TOP ...

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

// Executa uma query de contagem de registros de uma tabela do sistema

OPEN QUERY cQuery ALIAS 'TMPCOUNT'

// Se está tudo certo , retorna um HTML informando que está tudo OK

Return '(SITE OK) '+dtos(date())+' '+time()

Comandos - CLOSE QUERY

Comandos - OPEN QUERY

Comandos - WEB EXTENDED END

Comandos - WEB EXTENDED INIT

Ponto de entrada executado na inicialização de cada Working Thread ( ONSTART )

USER Function StartWebEx()

USER Function WebExError(oError,cErrorLog,cHtml)

// Monta mensagem de erro mais amigavel ...

cPAram1 := 'Teste de Parametro 01-02'

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" ,

Infra-Estrutura APWEBEX - Exemplo da função GETJOBPROFSTRING

Infra-Estrutura APWEBEX - Exemplo da função GETPARVALUE

// Busca apenas no array ateste1

Infra-Estrutura APWEBEX - Exemplo da função HEXSTRDUMP

User Function DumpTest()

WEB EXTENDED INIT cHtml

// Gera a string com o Dump do arquivo

// Mostra o Dump no console

// Gera HTML para a visualização do DUMP

User Function WebDemo(aCookies,aPostParms,nProcID,aProcParms,__cHTTPPage)