Infra-estrutura APWEBEX 1

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

1.1. 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 enviadas 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).

1.2. 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
ao Server Protheus, devidamente configurado para atendê-la, dispara o processamento de uma
função no Servidor, e esta função encarrega-se de devolver ao 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 ao 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.
1
 Infra-estrutura APWEBEX 2

2. Executando funções AdvPL via HTTP

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 solicitaçã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 extensã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

3. Páginas dinâmicas - O AdvPL ASP

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
 Infra-estrutura APWEBEX 3

3.1. 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 arquivo APH , gerando uma função prefixada com L_ . A
diferença é que a função gerada pelo AHU pode ser gerada sem a necessidade de autorização de
compilação com permissão para substituir fontes microsiga , por tratar-se de um Aph de
Usuário, equivalente à 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>

3
 Infra-estrutura APWEBEX 4

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 ao
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) .

4
 Infra-estrutura APWEBEX 5

Importante

Ao codificar 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 fechamento dos delimitadores de execução <% ... %> devem estar isoladas em
suas respectivas linhas, não devendo ter qualquer conteúdo 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. Quanto aos delimitadores de avaliação <%= ... %> , podemos ter várias aberturas e
fechamentos na mesma linha , porém não podemos ter uma abertura e seu respectivo
fechamento em linhas diferentes.

3. Uma linha qualquer em um arquivo .APH não 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.

5
 Infra-estrutura APWEBEX 6

4. Desenvolvimento de Funções .APL

A princípio, todas as funções contidas no repositório podem ser executadas diretamente através
de uma requisição HTTP, via link com extensão .apl, ao Protheus Server. Porém, alguns
detalhes devem ser considerados:

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

executada como um JOB, ou seja, não contem interface. Por isso, tais funções não
podem conter comandos de interface, como criação de janelas ou exibição de helps e
mensagens de alerta;
 Os jobs criados a partir de requisições HTTP são criados com nome de usuário
HTTP:GENPROC ;
 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).

6
 Infra-estrutura APWEBEX 7

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

7
 Infra-estrutura APWEBEX 8

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

8
 Infra-estrutura APWEBEX 9

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 Server 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 ao 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'.

5. Desenvolvimento de Funções .APW

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

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

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

9
 Infra-estrutura APWEBEX 10

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 performance 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 Threads 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 parâmetro, 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 Threads 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.

10
 Infra-estrutura APWEBEX 11

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

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

11
 Infra-estrutura APWEBEX 12

6. Configurando o Server Protheus para HTTP

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 diretório 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 poderá 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 inclusive 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 suas 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 ambiente do ERP . Basta acrescentarmos na seção http a chave
Environment=<nome_do_ambiente> , para que este ambiente passe a atender ao processamento
de funções Advpl através de links .apl. Por exemplo , caso o ambiente configurado para o ERP
chame-se EnvADS710 , basta acrescentar na seção http a chave Environment=EnvADS710 . O
.INI ficaria conforme abaixo :

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

12
 Infra-estrutura APWEBEX 13

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

Atendendo à requisições .apw

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

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

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

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

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

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

inicialização utilizada será a STARTWEBEX , a função de conexão será a CONNECTWEBEX
( ambas da Infra-estrutura APWEBEX ) , que utilizarão o ambiente AnvADS710 para
processamento, e serão colocadas no ar apenas uma Working Thread para atendimento de
processamento, até o máximo de 3 Threads. As threads colocadas no ar acima do número
mínimo ( no exemplo, apenas 1 ) , são colocadas 'on-demand' caso sejam realizadas requisições
.apw ao Servidor e não hajam Working Threads disponí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 especificá-las na seção http , através da chave ResponseJob. No caso ,
inserimos a chave ResponseJob=ERP_APWEBEX , fincando a seção HTTP conforme abaixo:

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

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

13
 Infra-estrutura APWEBEX 14

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 será 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 aos 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ço 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.

14
 Infra-estrutura APWEBEX 15

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 à necessidades 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 especificar uma 'pasta virtual' , que 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ível 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 diretório virtual no HTTP , criamos apenas uma nova entrada do
mesmo host , colocando no nome do mesmo uma barra de divisão'/' , seguido do nome de uma
pasta a ser acessada via HTTP ( que não precisa necessariamente existir no disco) , e dentro
desta seção acrescentar a chave path , apontando para o diretório desejado , da mesma maneira
utilizada para configurar um host.

No exemplo abaixo , criamos a pasta virtual info, dentro do host srvteste, apontando para o path
do disco c:\Ap_Data\Docs. De modo que , ao ser acessado via url o endereço http://srvteste/info
, a partir dele serão acessados os arquivos da pasta c:\Ap_Data\Docs

[srvteste/info]
Path=c:\Ap_Data\Docs

Vejamos agora como ficou o nosso arquivo .INI, com todas as configurações acima
exemplificadas :

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

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

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

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

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

environment EnvTOP710

15
 Infra-estrutura APWEBEX 16

[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

16