Descrição: Texto desenvolvido para estudantes de Java
esse manual tem o intuito de trazer a programacao do controle
python
Lógica de ProgramaçãoDescrição completa
Descrição completa
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 ace ssado 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 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 infrainfra -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. Infra
02. Executando funções f unçõ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 sol icitado 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 requi siçã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 HTT P Independente da extensão 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 d inâmicas - O Advpl ASP Revisão: 26/04/2004 Abrangência Versão 5.07
Versão 5.08
Versão 6.09
Versão 7.10
Versão 8.11
Uma página ASP (Active Server Pages) é uma página HTML contendo código interpretável em uma linguagem compreensível ao servidor HTTP em uso. Por
exemplo, o IIS da Microsoft utiliza o VBScript para criar suas páginas ASP, do mesmo
modo que o Protheus utiliza o ADVPL. Uma página ASP é uma combinação de script HTML e código interpretável. No ADVPL ASP esse código é padrão xBase, portanto a preocupação maior daqueles que já conhecem e trabalham com o Protheus e desejam desenvolver páginas ativas para aplicações Web utilizando essa facilidade é conhecer HTML.
Características do ADVPL ASP Arquivos .APH -
Os arquivos ADVPL ASP têm a extensão padrão .APH. São arquivos texto e dev em 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: ADVPL ASP Demo
Bem vindo ao mundo do ADVPL ASP!
<% // Soma os 100 primeiros números Local i, nSoma := 0 For i := 1 To 100 NSoma += i Next i %>
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 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() %> Esta linha será repetida no HTML até ocorrer o f im de arquivo arquiv o <% 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 : Esta linha é HTML, mas o horário exibido aqui: <%= Time() %> foi obtido em tempo de execução no Servidor.
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 fic a 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 !lOk
; nErro++ nErro++ ; Endif 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 li nha 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 f unçõ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 HTT P : 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 Independente 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 S tring, 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 d inâmicas - O Advpl ASP Revisão: 26/04/2004 Abrangência Versão 5.07
Versão 5.08
Versão 6.09
Versão 7.10
Versão 8.11
Uma página ASP (Active Server Pages) é uma página HTML contendo código interpretável em uma linguagem compreensível ao servidor HTTP em uso. Por
exemplo, o IIS da Microsoft utiliza o VBScript para criar suas páginas ASP, do mesmo modo que o Protheus utiliza o ADVPL. Uma página ASP é uma combinação de script HTML e código interpretável. No ADVPL ASP esse código é padrão xBase, portanto a preocupação maior daqueles que já conhecem e trabalham com o Protheus e desejam desenvolver páginas ativas para aplicações Web utilizando essa facilidade é conhecer HTML.
Características do ADVPL ASP Arquivos .APH -
Os arquivos ADVPL ASP têm a extensão padrão .APH. São arquivos texto e devem ser
adicionados a um projeto no Protheus IDE e compilados da mesma maneira que os programas tradicionais. A diferença é que o Protheus Server identificará que se trata de um ADVPL ASP e executará uma espécie de tradutor (parser) antes que a compilação seja executada. Este parser irá transformar todo o arquivo em uma função única, que receberá os mesmos parâmetros das funções APL simples, como explicado anteriormente no Item 'Desenvolvendo Funções .APL', e retornará uma string.
O desenvolvedor não precisa se preocupar em retornar HMTL algum, pois o APH também é um arquivo HTML. A função que foi gerada na compilação irá se encarregar de retornar o HTML contigo no arquivo, depois que o código foi processado. Um Arquivo APH gera no repositório de Objetos do Protheus uma função com o mesmo nome do arquivo , porém prefixada com H_ + nome_do_arquivo_aph Por se tornar uma função no momento da compilação, não é possível utilizar a cláusula FUNCTION para criar outras funções dentro de um arquivo APH. Caso exista essa necessidade, tais funções devem ser criadas em um arquivo PRW tradicional e chamadas de dentro do APH.
A extensão APH para o nome dos arquivos é obrigatória. Qualquer outra extensão usada no nome do arquivo não será reconhecida e o parser do IDE não será executado durante a compilação. Foi criada também a extensão de arquivos .AHU ( Aph de Usuário ), que possui o mesmo tratamento de Parser do aruqivo APH , gerando uma função prefixada
com L_ . A diferença é que a função gerada pelo AHU pode ser gerada sem a necessiade de autorização de compilação com permissão para substituir fontes microsiga , por tratar-se de um Aph de Usuário, qeuivalente à uma User Function .
Assim como outros ASP´s, a diferenciação entre script HTML e código é efetuada através dos caracteres <% para indicação de abertura de código e %> para indicação do encerramento de código. Por exemplo, o HTML abaixo contém um pedaço de código ADVPL separado pelos delimitadores: ADVPL ASP Demo
Bem vindo ao mundo mu ndo do ADVPL ASP!
<% // Soma os 100 primeiros números Local i, nSoma := 0 For i := 1 To 100 NSoma += i Next i %>
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 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() %> Esta linha será repetida no HTML até ocorrer o fim de arquivo <% 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 : Esta linha é HTML, mas o horário exibido aqui: <%= Time() %> foi obtido em tempo de execução no Servidor.
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 con ta 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 inseri r 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 !lOk
; nErro++ nErro++ ; Endif 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 li nha do mesmo durante a pré-compilação . e a linha final resultante não pode ultrapassar 254 caracteres, pois neste caso isto impossibilita a compilação do APH.
04. Desenvolvimento de Funções .APL Revisão: 27/04/2004 Abrangência Versão 5.07
Versão 5.08
Versão 6.09
Versão 7.10
Versão 8.11
A princípio, todas as funções contidas no repositório podem ser executadas diretamente através de uma requisição HTTP, via link com extensão .apl, ao Protheus Server. Porém, alguns detalhes devem ser considerados: Uma função executada no momento do recebimento de uma requisição HTTP é executada como um JOB, ou seja, não contem interface. Por isso, tais funções não podem conter comandos de interface, como criação de janelas ou exibição de helps e mensagens de alerta; A única interface possível é a utilizada no client HTTP. Por isso, tais funções devem SEMPRE retornar uma string de caracteres. Após o processamento da função, essa string de retorno será enviada diretamente ao client HTTP e este será o responsável por sua interpretação. Por exemplo, utilizando um Web Browser como client pode-se retornar a string de comandos HTML diretamente. O HTML então será propriamente exibido no Web Browser; Qualquer retorno diferente de uma string de caracteres gerará um erro que será enviado à aplicação client HTTP (o erro gerado é “Invalid Proc Return”); O servidor Protheus passa alguns parâmetros para as funções chamadas . Isso significa que ao criar funções para serem utilizadas em resposta às requisições HTTP, deve-se criar o cabeçalho da função com estes parâmetros. Não é obrigatório utilizar os mesmos nomes de parâmetros sugeridos abaixo quando criar diretamente estas funções. Porém, como são esses os nomes utilizados no ADVPL ASP explicado mas a frente, é aconselhável utilizá-los por motivo de padronização: o
o
__aCookies: Este parâmetro recebe um array bidimensional com os Cookies criados na aplicação client HTTP (por exemplo, no Internet Explorer 5). PodePode-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. __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 o
o
exemplo, se o checkbox for marcado). __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; __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=PRODUT http://servidor/vende.apl?cod=000001&nome= PRODUTO O 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
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. __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 http://localhost/u_webdemo.apl?cod=000001&desc=DESCR ICAO DO PRODUTO&qtd=2 Código da função:
#include 'rwmake.ch' User Function WebDemo(__aCookies,__aPostPa WebDemo(__aCo okies,__aPostParms,__nProcID,_ rms,__nProcID,__aProcParms,__c _aProcParms,__cHTTPPage) HTTPPage) Local cHTML := '' Local i // Coloca uma mensagem em HTML cHTML += '
Hello World!!!
' World!!!' // Coloca um separador de linha em HTML cHTML += ' ' If Len(__aProcParms) = 0 cHTML += '
Nenhum parâmetro informado na linha de URL.' Else For i := 1 To Len(__aProcParms) cHTML += '
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 comp ilaçã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 servid or ) 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 f inalizado inalizado 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 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 é thread é deixada na memória do servi dor 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 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 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 anteri ores 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 InfraInfra -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 InfraInfra-Estrutura
APWEBEX e posteriores , englobando comandos , funções , exemplos e dicas de utilização destes recursos.
06. Configurando o Server Protheus para HTTP Revisão: 28/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
As configurações de http do Server Protheus permitem a configuração de sites estáticos e dinâmicos , com a criação de um ou mais hosts de acesso, criação de pastas virtuais, e dites dinâmicos com resposta para links .apl e .apw simultaneamente. Neste documento abrangeremos um resumo exemplificado das configurações HTTP do Server Protheus. As seções abaixo devem ser inseridas no arquivo de configurações do servidor Protheus ( mp8srv.ini )
Configuração Mínima [http] Enable=1 \ Path=c: \ Ap_Data \ http 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 Http como diretório raiz de publicações WEB. Como não há configuração \ Ap_data 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 .. ) Ola Mundo HTTP Agora , abra um Web Browser no mesmo equipamento, e digite na
url : http://localhost : Ao acessar esta url , deverá ser mostrado na tela do Browse huas barras horizontais e o texto 'Ola Mundo HTTP' entre elas . Atendendo à 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= Environment= , 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= Environment=EnvADS710 EnvADS710 . O .INI ficaria conforme abaixo : [http] Enable=1 Path=c: \ \ Ap_Data \ http http Environment=EnvADS710
Para testar a execução de funções , abra um Web Browse na estação servidora, e acesse o link http://localhost/time.apl . ISto´irá executar a função Advpl TIME() , que retornará ao Browse uma string contendo o horário atual no servidor no formato HH:MM:SS
Atendendo à requisições .apw A configuração para atendimento de requisições de processamento http através de links .apw envolve a criação de uma nova seção no .INI , com um nome não-específico, para
configurar o tipo de job que irá executar o processamento ( WEB ou WEBEX ) , juntamente com as funções responsáveis pela inicialização e conexão das Threads Advpl , e na seção http configuramos uma chave chamada ResponseJob , apontando para a seção de configuração do JOB.
Por exemplo , para configurarmos o atendimento de requisições .apw em um ambiente ERP , utilizando a infra -estrutura APWEBEX , vamos criar uma seção chamada ERP_APWEBEX, ERP_APW EBEX, apontando para as funções da Infra-Estrutura APWEBEX correspondentes : [ERP_APWEBEX] type=WEBEX onstart=STARTWEBEX onconnect=CONNECTWEBEX Environment=EnvADS710 Instances=1,3 SigaWeb=MAK
Através desta configuração, especificamos um Job do tipo WEBEX , onde a função de inicialização utilizada será a STARTWEBEX , a função de conexão será a CONNECTWEBEX ( ambas da Infra-estrutura APWEBEX ) , que utilizarão o ambiente AnvADS710 para processamento, e serão colocadas no ar apenas uma Working Thread para atendimento de processamento, até o máximo de 3 Threads. As threads colocadas no ar acima do número mínimo ( no exemplo, apenas 1 ) , são colocadas 'on-demand' caso sejam realizadas requisições .apw ao Servidor e não hajam Working Threads dispovíveis no momento e o número de Working Threads no ar ainda não tenha atingido o máximo definido. Através da configuração SigaWeb=MAK, informamos ao sistema, que a mesma está sendo utilizada para o desenvolvimento de
um módulo específico, e não estamos utilizando um módulo Web da ferramenta
Protheus 8. Caso a configuração SigaWeb não seja informada, o valor 'MAK' é
assumido como default. Agora , para que esta seção de Jobs seja utilizada para o atendimento efetivo de requisições .;apw , devemos estecificá-la na seção http , através da chave REsponseJob. No caso , inserimos a chave ResponseJob=ERP_APWEBEX , fincando a seção HTTP conforme abaixo: [http] Enable=1 Path=c: \ \ Ap_Data \ http http Environment=EnvADS710 ResponseJob=ERP_APWEBEX ResponseJo b=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 . host Configurandoo a seção http para multi - host Configurand
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 n ome . 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 protheus em mais de uma porta HTTP. [srvteste] Path=c: \ \ Ap_Data \ Testes 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. Configurandoo diretórios virtuais Configurand
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 "serve rtst/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
Configurandoo diretórios virtuais Configurand
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 Docs ) , que contenha que exista uma pasta no disco ( por exemplo , c: \ Ap_data \ Docs \ Ap_data 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. Testes. \ Ap_data Com o recurso de criação de diret orio 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. Docs. De modo que , ao ser acessado via url o \ Ap_Data endereço http://srvteste/info , a partir dele serão acessados os arquivos da pasta c: \ \ Ap_Data Ap_Data \ Docs 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 defau lt para atender à requisições de .apl e .apw [http] Enable=1 Path=c: \ \ Ap_Data \ http http Environment=EnvADS710 ResponseJob=ERP_APWEBEX SigaWeb=MAK ;; Configuração do host srvteste para atender requisições via .apl através do environment EnvTOP710 [srvteste] \ Path=c: \ Ap_Data \ Testes 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 A Infra-- Estrutura Estrutura APWEBEX
Visando o melhor aproveitamento da tecnologia de w orking 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", 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 InfraInfra -Estrutura APWEBEX, além de ser
explicado com detalhes o funcionamento da tecnologia WEBEX do Protheus, e dos recursos nativos da ferramenta, englobando os comandos e funções publicados, exemplos de códigos Advpl utilizando estes recursos, configuração da ferramenta e mensagens de ocorrências de erro das funções e comandos, com possíveis causas e soluções. É fortemente recomendado que os documentos constantes neste grupo fossem apreciados, antes de aprofundar -se nas informações dos próximos tópicos.
01. Recepção de parâmetros por Alias Virtuais Revisão: 30/04/2004 Abrangência Versão 7.10
Versão 8.11
A recepção de parâmetros vindos do
Web Browser, quando utilizamos Working Threads do tipo WEBEX, através de links .apw, é realizada através de Alias Virtuais específicos, ao invés de receber as informações GET , POST e HEADER em array, quando executamos a chamada através de link .apl. A nomenclatura de 'Alias Virtual' foi adotada, pois a sintaxe do código -fonte é exatamente a mesma utilizada quando desejamos acessar um campo de uma tabela aberta, através de um alias. Em um ambiente montado para atender à requisições via link .apw utilizando Working Threads WEBEX , podemos nos utilizar dos seguintes alias virtuais : HttpCookies HttpGet HttpPost HttpHeadIn HttpHeadOut HttpSession HttpCookies Através do alias virtual HttpCookies, é possível consultar os Cookies do Header Http
enviados pelo Browser, e criar ou alterar o conteúdo de um cookie a ser devolvido ào Browser. Um cookie, visto de forma geral, é um parâmetro ao qual atribuímos um nome, que uma vez devolvido ào Browse solicitante, é re-enviado ao Protheus a partir da próxima requisição realizada pelo Browser.
HttpGet
Para receber os parâmetros enviados através da URL (método GET do HTTP) , já devidamente convertidos e tratados, utilizamos o alias virtual HttpGet, onde acessamos pelo nome a propriedade desejada, e caso a mesma tenha sido enviada pelo Browser, a mesma é retornada como uma String. HttpPost
Para receber os parâmetros submetidos (enviados) pelo Browser através do método POST, já devidamente convertidos e tratados, utilizamos o alias virtual HttpPost, onde
acessamos pelo nome a propriedade desejada, e caso a mesma tenha sido enviada pelo Browser, a mesma é retornada como uma String. HttpHeadIn
Para a recepção e tratamento das informações recebidas através do Header do pacote HTTP, foi criado o alias virtual HttpHeadIn, que além de consultar as informações constantes no Header HTTP proveinente da requisição do usuário, permite também acesso à propriedades da conexão atual do usuário, como o IP do usuário solicitante, por exemplo. HttpHeadOut
Através deste alias virtual de retorno, podemos alterar ou criar um parâmetro no Header de retorno HTTP do Protheus , a ser devolvido ào Browser solicitante de uma requisição de processamento. HttpSession
O alias virtual HttpSession foi criado para possibilitar a criação de variáveis 'session' por usuário do site, com controle de identificação nativa da ferramenta através de um cookie de identificação , chamado SESSIONID. No tópico 'Alias Virtual HttpSession' é explicado em detalhes o funcionamento deste mecanismo. Este recurso nos permite criar , atricuir conteúdo e consultar conteúdo de uma variável relacionada ào usuário que está realizando uma requisição http. Podemos armazenar em uma variável de Session os seguintes tipos de variáveis : A (array) , C (character) , D (data), L (lógica) e N (numérica) . Não são suportados O (Objetos) e/ou B (Code Blocks). Limitações de uso dos alias virtuais para recebimento de parãmetros
Dadas as características operacionais e de acesso àos alias virtuais, devemos estar atentos à nomenclatura de campos de um formulário HTML, para serem recuperados com sucesso pelos alias virtuais correspondentes. A nomenclatura de campos do
formulário deve obedecer à regra de criação de variáveis em Advpl : O campo do formulário deve sempre ser iniciado com um caracter alfabético, pode conter letras ou algarismos no nome, e o caracter "_" ( underline ). Não são permititos espaçõs, hífen ou caracteres acentuados como nome de um campo. Caso utilizado um nome de campo fora do padrão suportado, o conteúdo do mesmo não será recuperável em Advpl.
02. Alias virtual HttpCookies Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Através do alias virtual HttpCookies, é possível consultar os Cookies do Header Http enviados pelo Browser, e criar ou alterar o conteúdo de um cookie a ser devolvido ào Browser. Uma variável de Cookie retorna um tipo Advpl String , e apenas aceita uma atruibuição de String. Vale lembrar também que um cookie é um recurso do Browser que está realizando a requisição, e existe um limite de tamanho para o total de Cookies utilizados. Este limite costuma ser próximo a 1024 Bytes . Trata-se portanto de uma propriedade de leitura e gravação, dispnível apenas quando a função Advpl é executada através de uma requisição http via link .apw utilizando a configuração de Working Threads WEBEX. Utilização de Cookies
A utilização de Cookies têm objetivo prático restrito à aplicações onde haja a necessidade implícita de termos uma informação relacionada ào browser utilizado pelo usuário atual, que devam ser interpretadas independente do usuário estar logado ou não ( isto é , independam i ndependam diretamente de sessions ). Um exemplo prático disto é o desenv olvimento 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 iden tificador do usuário do Protheus cIdioma := HttpCookies->SiteLang // Retorna o conteúdo conteúdo do cookie SiteLang 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 := HttpCookiesHttpCookies->aCookies For nI := 1 to len(aInfo) // Mostra no console do Server todos os cookies recebidos. conout(' Cookie 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' HttpCookies
A criação de um Cookie merece uma atenção especial, pois um Cookie é retornado ào browser através do Header de Retorno HTTP. De modo que, para que a criação de um cookie seja realizada com sucesso , o mesmo deve ser criado antes de haver qualquer processamento de APH / AHU, caso este que não seria mais possível a criação do Cookie, pois o Header de Retorno HTTP já teria sido enviado ào browser solicitante.
03. Alias virtual HttpGet Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Através do alias virtual HttpGet, podemos consultar se uma determinada propriedade nos foi enviada através da URL ( método GET ). Trata-se portanto de uma propriedade de leitura (read -only), disponível apenas quando a função Advpl é executada através de uma requisição http via link .apw utilizando a conf iguração iguração de Working Threads WEBEX. Consultando um Parâmetro
O retorno da consulta de um parâmetro pode ter t er 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 DEFAULT cCor := 'amarelo'
Existe também uma propriedade do alias virtual HttpGet chamada aGets , onde podemos recuperar um array de strings , contendo a lista com os nomes dos parâmetros enviados pelo browser solicitante . Por exemplo : aInfo := HttpGet ->aGets For nI := 1 to len(aInfo) conout('GET '+str(nI,3)+' = '+aInfo[nI]) Next
04. Alias virtual HttpPost Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Através do alias virtual HttpPost, podemos consultar os campos submetidos ào ser vidor através do método POST.
Trata-se portanto de uma propriedade de leitura (read -only), disponível apenas quando a função Advpl é executada através de uma requisição http via link .apw utilizando a configuração de Working Threads WEBEX. Consultando um Parâmetro
O retorno da consulta de um parâmetro pode ter t er 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 co m método POST, partindo do Html abaixo : Para recuperarmos em Advpl o conteúdo do campo CODIGO , utilizamos: cCodigo := HttpPOST ->Codigo
Existe também uma propriedade do alias virtual chamada aPost , onde podemos recuperar um array de strings , contendo a lista com os nomes dos parâmetros enviados
pelo browser solicitante . Por exemplo : aInfo := HttpPost ->aPost For nI := 1 to len(aInfo) conout('POST '+str(nI,3)+' = '+aInfo[nI]) '+aInfo[nI]) Next
05. Alias virtual HttpHeadIn Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Através do alias virtual HttpHeadIn, podemos consultar os parâmetros enviados pelo
Browser solicitante enviados através do Header HTTP ao realizar uma requisição ao Protheus Server.
Trata-se portanto de uma propriedade de leitura (read -only), disponível apenas quando a função Advpl é executada através de uma requisição http via link .apw utilizando a configuração de Working Threads WEBEX. Consultando um Parâmetro
O retorno da consulta de um parâmetro pode ter t er 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 UserUser-Agent , enviado pelo Browser solicitante contendo uma String identiificando o modelo de Browser utilizado : cUserAgent := HttpheadinHttpheadin->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 HttpHeadIn
Retorna um Array de Strings , contendo todas as linhas do Header HTTP da requisição. HttpHeadIn-->main HttpHeadIn
Retorna o nome da função chamda através da URL , sem a extensão e sem o host. Por exemplo , ao chamar o link http://localhost/u_tstHEader.apw , o conteúdo de HttpHeadin->main será 'u_tstHEader'
HttpHeadIn->REMOTE_ADDR HttpHeadIn-
Retorna uma string , no formato nnn.nnn.nnn.nnn , o IP da estação que realizou a requisição. httpHeadIn-->REMOTE_PORT httpHeadIn
Retorna um valor Advpl numérico , informando a porta utilizada para realizar a requisição.
06. Alias virtual HttpHeadOut Revisão: 08/12/2003 Abrangência Versão 7.10
LIB WEBEX
Através deste alias virtual de retorno, podemos alterar ou criar um parâmetro no Header de retorno HTTP do Protheus , a ser devolvido ào Browser solicitante de uma requisição de processamento. Trata-se portanto de uma propriedade de retorno, disponível apenas quando a função Advpl é executada através de uma requisição http via link .apw utilizando a configuração de Working Threads WEBEX. A criação de uma linha no Header HTTP merece uma atenção especial, pois para que a operação realizada com sucesso , o header deve ser criado antes de haver qualquer processamento de APH / AHU, pois neste caso o Header de Retorno HTTP já teria sido enviado ào browser solicitante.
07. Alias virtual HttpSession Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Através do alias virtual httpSession, podemos criar e consultar variáveis do tipo 'session', relacionadas ào usuário que realizou a requisição através do Browser. erenciar os usuários que estão navegando num site, o Protheus busca por um Para dif erenciar 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 i nicializa 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 consul tada 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 , co m o conteúdo do tipo String, e criamos outra session chamada UserName , com o retorno da função U_GetUserNam U_GetUserName() e()
Consultando variáveis Session
Ao consultar uma variável 'session', sempre devemos prever que a mesma não pode ter t er sido criada, de modo que a consulta pode retornar NIL, ou caso a session já exista , retornará o valor do tipo que foi atribuído `a mesma. If HttpSession->UserId HttpSession->UserId = NIL
// Session ainda não foi criada ! Usuário não está logado. // Session conout('Usuario não está logado') Else // Sess // 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 httpSessionhttpSession ->mycounter = NIL cEcho := 'Inicializando contador' Conout(cEcho) cHtml += cEcho httpSession-->mycounter := 1 httpSession Else httpSession->myc httpSession ->mycounter++ ounter++ cEcho := 'contador em '+str(httpSession '+str(httpSession-->mycounter,3) conout(cEcho) Endif cHtml += cEcho + '' 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 onte , sem necessariamente aguardar pelo encerramento httpLeaveSession() no seu f onte efetivo e reset de ambiente da Working Thread. Logo , retornando ao exemplo acima , os Frames 1 e 2 irão concorrer pela banceira de atualização de conteúdo de sessions, onde o primeiro frame que a ser executado pegará a bandeira para ele e atualizará a session , e o segundo frame irá esperar o primeiro liberar a bandeira para continuar a ser processado; e o terceiro frame , como não utiliza nenhuma variável da session , será processado sem depender de nenhum dos outros dois frames anteriores. Quando utilizamos ASP ( Microsoft Active Server Pages ) , o mesmo realiza uma serialização de requisições de páginas ASP por usuário, de modo que , caso o mesmo usuário solicite três frames .asp , as requisições de processamento chegarão ao Servidor ASP simultaneamente , mas a bandeira de processamento é unica por página .asp , sendo liberada apenas apos o término do processamento da página , de modo que ,
mesmo que nenhuma das páginas faça uso de sessions , todas as páginas deste usuário serão processadas em sequência.
08. Envio simultâneo de HTML ao Browser Revisão: 30/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
As aplicações web desenhadas para utilizar a Infra -Estrutura APWEBEX contam com o recurso de "Envio simultâneo de Html ao Browser" durante o processamento de uma página Advpl-ASP ( .APH e/ou .AHU ) . Este recurso é habilitado através do Protheus IDE, nas opções de configuração de compilação do ambiente em questão; mais especificamente habilitado através do CheckBox "[ ] Exibir conteúdo do Advpl ASP progressivamente no Browser". Ao habilitamos esta configuração, todos os arquivos APH e AHU são parseados
fazendo internamente o uso da função HttpSend(), de modo que mesmo antes do processamento estar concluído , o Html gerado já está sendo enviado ào Browser qoe o solicitou. A utilização deste recurso provê um ganho de performance subtancial na aplicação final. Todos os projetos desenvolvidos com esta tecnologia ( Infra -Estrutura APWEBEX ) devem ter esta configuração de compilação habilitada no IDE. Vale lembrar que, caso este recurso não esteja habilitado; ao habilitá-lo, os arquivos .aph e .ahu do projeto necessitam ser recompilados para que esta configuração tenha o efeito desejado. Pode existir a necessidade de um processamento de um APH ou AHU não enviar o script Html gerado diretamente ao Browser. Para tal situação, podemos desabilitar temporariamente este recurso de envio de html progressivo em tempo de execução, permitindo assim, por exemplo, uma função chamar em sequência dois arquivos APH , um para gerar um conteúdo Html a ser enviado via e-mail , armazenado em uma variável Advpl , e outro APH para a montagem de uma tela de status, que será enviada ào Browser solicitante. Para habilitar e/ou desabilitar o envio simultâneo do Script HTML
tempo de execução, utilize a função HttpSetPart()
ào browser em
09. Configurações específicas APWEBEX Revisão: 26/04/2004 Abrangência Versão 7.10
Versão 8.11
Ao utilizarmos as funções de Infra -estrutura APWEBEX, existem recursos da lib que exigem uma configuração adicional para serem utilizados. Envio de e- mail automático através da Rotina de Tratamento de Erro do Site Em caso de erro fatal na aplicação Web, a própria rotina de tratamento de erro pode ser configurada para enviar um e-mail ào Administrador do sistema. Para tal, é necessário
inserir as chaves abaixo na seção do ambiente em uso para o site : ErrorSMTP= (endereço do servidor SMTP a ser usado para o envio do e -mail ) ErrorMail= ( um ou mais endereços de ee-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 SwapRPO \ ',', e deve existir na estrutura de diretório do ambiente utilizado, a partir do diretório raiz do ambiente ( RootPath ). RpoUpload= ( pasta de upload alternativa, a partir do RootPath do ambiente )
10. Recomendações finais Revisão: 17/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Para todo o desenvolvimento de soluções, temos em mãos uma diversidade de recursos, desenhados para melhor atender às necessidades e adequar-se às caracteristicas da aplicação. Dada a flexibilidade dos recursos, recomenda-se aos desenvolvedores adotarem um padrão de desenvolvimento e ter em foco a eficiência da aplicação final, tanto no aspecto funcional como na codificação . Lançando mão da experiência em desenvolvimento de aplicações web adquiridas nos últimos anos, nos tópicos abaixo estão relacionadas algumas medidas tomadas no desenvolvimento de aplicações que nos são muito úteis no decorrer de um projeto. Nomenclatura de Funções
Para o desenvolvimento de aplicações web, foi criado o 'Statement' WEB FUNCTION para a declaração de funções referentes à projetos web. Este comando , na prática , apenas prefixa a declaração da função com W_ , porém a sua utilização identifica que a função em questão foi construída única e exclusivame nte 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 Int erface 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ódigofonte 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 se--á apenas com o código responsável para a geração dos dados que serão mascarados.
Utilização das Funções de InfraInfra - Estrutura 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é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() !TCIsConnected() Return 'Working Thread perdeu a conexão com o TOP' Endif // Verifica se as tabelas principais estão abertas .... If select('SA1')=0 Return 'Tabela SA1 não está aberta !!!' Endif If select('SC5')=0 Return 'Tabela SC5 não está aberta !!!' Endif
// Executa uma query de contagem de registros de uma tabela do sistema cQuery := 'SELECT count(*) as QTDREC from SA1010' OPEN QUERY cQuery ALIAS 'TMPCOUNT' nQtdRec := TMPCOUNT ->QTDREC CLOSE QUERY 'TMPCOUNT' If nQtdRec=0 Return 'Falha na Contagem de registros / Query SA1' Endif // Se está tudo certo , retorna um HTML informando que está tudo OK Return '(SITE OK) '+dtos(date())+ '+dtos(date())+' ' '+time()
Comandos - CLOSE QUER QUERY Y Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe CLOSE QUERY cAlias Parâmetros Argumento cAlias
Tipo
Descrição Alias sob o qual o cursor da Query foi aberto. Caso o alias Caracter passado como parâmetro não se encontre aberto , a função não gera nenhuma ocorrência de erro.
Descrição Através do comando Close Query , realizamos o fechamento de uma query aberta através do comando OPEN QUERY. ATENÇÃO : Uma query aberta pelo comando OPEN QUERY deve ser fechada pelo comando CLOSE QUERY . Poderíamos fechar o alias aberto através de uma Query simplesmente com a função DbCloseArea(), porém isto deixaria em aberto elementos internos de controle criados pelo comando OPEN QUERY.
Comandos - OPEN QUERY Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe OPEN QUERY ALIAS [ [NOCHANGE] ] Parâmetros Argumento
ALIAS
Tipo
Descrição cQuery corresponde à String contendo a Query a ser Caracter executada no banco de dados cAlias corresponde ao nome do alias sob o qual o cursor de retorno dos dados pesquisados será aberto no ambiente Caracter Advpl. Não pode ser especificado um nome de alias já em uso, senão a aplicação será finalizada com a ocorrência de erro "Alias already in Use"
[NOCHANGE]
Caso especificada a cláusola NOCHANGE na abertura da Caracter query , a string em cQuery não será submetida à função ChangeQuery()
Descrição Através do comando OPEN QUERY , realizamos a abertura de uma Query de busca no Banco de Dados através do RDD TOPCONN , retornando os dados consultados através de um 'ALIAS' Advpl.
Caso a Query nao possa ser aberta, por erro de sintaxe , devido à thread atual não estar conectada com o TopConnect , ou outro erro , será gerado um log de erro , informando o Alias , o Stack ( Pilha de Chamadas ) de execucão , e o conteúdo da Query para Debug.
OBSERVAÇÕES IMPORTANTES Na montagem da string da Query , devemos especificar os comandos SQL , alias e nomes de campos em letras maiúsculas. Quando utilizamos o comando OPEN QUERY , não precisamos passar a expressão da Query através da função ChangeQuery(). Este proceduimento já é realizado internamente pelo comando OPEN QUERY. Para que a query não seja submetida à função ChangeQuery(), devemos utilizar o parâmetro NOCHANGE.
A utilização deste comando é implícita à LIB APWEBEX , e necessita da utilização do #include 'Apwebex.ch'
Comandos - WEB EXTENDED END Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe WEB EXTENDED END [ START ] Parâmetros Argumento
Tipo
Descrição cHtml corresponde à variavel que será utilizada para
Caracter
armazenar a String Html que será retornada ao Browser
START
solicitante do processamento. Deve ser especificada uma variável String , com conteúdo vazio. ("") cFnStart corresponde ào nome de uma função Advpl que Caracter será executada para pré-validar a execução do resto do código. A função deve ser passada SEM parênteses () .
Descrição Devemos utilizar este comando para fechar uma seção aberta pelo comando WEB EXTENDED INIT . Para cada ocorrência do comando WEB EXTENDED INIT , devese ter um fechamento da mesma através do comando WEB EXTENDED END , devendo haver apenas uma ocorrência desta estrutura por função. A utilização deste comando é implicita à
Working Threads inicializadas pela Lib APWEBEX , e a definição do mesmo está no arquivo #include 'apwebex.ch' , que deve ser declarado no início do arquivo fonte Advpl.
Comandos - WEB EXTENDED INIT Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe WEB EXTENDED INIT [ START ] Parâmetros Argumento
Tipo
Descrição cHtml corresponde à variavel que será utilizada para
Caracter
armazenar a String Html que será retornada ao Browser
solicitante do processamento. Deve ser especificada uma variável String , com conteúdo vazio. ("")
START
cFnStart corresponde ào nome de uma função Advpl que Caracter será executada para pré-validar a execução do resto do código. A função deve ser passada SEM parênteses () .
Descrição Devemos utilizar este comando , juntamente com o comando WEB EXTENDED END quando montamos uma funcão ( Web Function ) que foi construída para ser chamada a partir de um Web Browser , quando nos utilizamos das funções de Infra -Estrutura APWEBEX.
Através dele , é realizada uma pré-validação que certifica que a execução da função somente será realizada caso a thread atual seja realmente uma Thread montada no ambiente WEBEX, além de podermos inserir uma pré-validação (START) de execução específica para esta função. Caso seja especificada uma função na cláusula START, a mesma deverá retornar uma String. Retornando uma String em branco , o processamento da função original será efetuado normalmente . Caso a função reto rne uma string nãonã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 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 e stá no arquivo #include 'apwebex.ch' , que deve
ser declarado no início do arquivo fonte Advpl.
Infra-Estrutura APWEBEX - EnvU EnvUser ser.APL .APL Exemplo de Uso com ERP Revisão: 16/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Através do exemplo prático abaixo , utilizamos em um código fonte Advpl os pontos de entrada disponibilizados na Infra-Estrutura APWEBEX para realizar a preparação de um ambiente ERP , Reset de Ambiente , finalização de Thread, finalização de sessions por time-out e customização de mensagem de erro para o desenvolvimento de um projeto de Web Site integrado com o ERP Microsiga. Devemos adotar como padrão para projetos que utilizam APWEBEX a criação do arquivo "EnvUser.apl", especificamente para a definição dos pontos de entrada utilizados pela Infra -Estrutura APWEBEX; e devemos apenas compilar os fontes dos pontos de entrada realmente necessários ào projeto. #INCLUDE "PROTHEUS.CH" #INCLUDE "APWEBEX.CH" /* ============================ ============= ============================== ============================= =========================== ============= ============== Exemplo de Arquivo de Lib de Projeto APWEBEX , utilizando os pontos de entrada da lib para preparação de ambiente , reset de ambiente e tratamento de erro utilizando APWEBEX em conjunto com o ERP Microsiga ============================ ============= ============================== ============================= =========================== ============= ============== ============= = */ /* ----------------------------------------------------------------------------------------------------------------------------------------Ponto de Entrada StartWebEx( NIL ) => .T. ou .F. Ponto de entrada executado na inicialização de cada Working Thread ( ONSTART ) É a responsável por preparar o ambiente para atender às requisições WEB de links .apw Não recebe parâmetro algum da lib , e deve retornar .T. caso tenha inicialziado com sucesso ou .F. em caso de falha de inicialização . -------------------------------------------------------------------------------------------------------------------------------------------- */ USER Function StartWebEx() // Prepara o Ambiente ERP PREPARE ENVIRONMENT ;
EMPRESA '01' ; FILIAL '01' ; TABLES "ZX1","ZX2","Z "ZX1","ZX2","ZX3","ZX4","ZZ1" X3","ZX4","ZZ1","ZZ2","ZZ3","Z ,"ZZ2","ZZ3","ZZ4","ZZ5" Z4","ZZ5" Return .T. /* -------------------------------------------------------------------------------------------------------------------------------------------Ponto de Entrada ConnectWebEx(cFn ConnectWebEx(cFnName) Name) => 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 solicitada é executada pela lib. Caso contrário, a função original não é executada , e a string retornada é enviada ao Browser. ----------------------------------------------------------------------------------------------------------------------------------------------- */ USER Function ConnectWebEx(c ConnectWebEx(cFnName) FnName) Local cHtmlConn := '' conout('Vou executar '+cFnName) Return cHtmlConn /* -------------------------------------------------------------------------------------------------------------------------------------------Ponto de Entrada ResetWebEx(cFnName) ResetWebEx(cFnName) => cHtml ou "" Função chamada chamada imediatamente imediatamente Apos a execução de uma requisição 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(cFn ResetWebEx(cFnName) Name) Local cHtmlConn := '' conout('Terminei conout('Termi nei 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 conout('Final izando 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 Conout("Sesss ion "+cSessionId+" limpa da memória...") Return /* ----------------------------------------------------------------------------------------------------------------------------------------Ponto de Entrada WebExError(e,cErrorLog,cHtml) 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(oEr WebExError(oError,cErrorLog,c ror,cErrorLog,cHtml) Html) Local cCustomHtml := '' // Monta mensagem de erro mais amigavel ... cCustomHtml += '' cCustomHtml += '' cCustomHtml += '' cCustomHtml += '' cCustomHtml += '' cCustomHtml += ' '
cCustomHtml += ' Oc orr orreu eu um err erro o inesperado no ' cCustomHtml += 'processamento 'processamento desta página. página. O Administ nistrador rador do sistem sistema será notificado desta ' cCustomHtml += 'ocorr 'ocorrência ência . Recomendamos fortemente fortemente que esta janela janela do navegador seja seja ' cCustomHtml += 'fechada, 'fechada, e uma nova janela seja janela seja aberta para retornar à
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função ESCAPE Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Nos exemplo abaixo, utilizamos a função escape() para formatar parâmetros para inserir em uma URL. cUrl := 'http://localho 'http://localhost/webinfo.apw st/webinfo.apw' ' cPAram1 := 'Teste de Parametro 01 -02' cPAram2 := '#reserva#' cPAram3 := '1+2+3' cUrl += '?Par01=' + escape(cPAram1) + '&PAr02=' + escape(cPAram2) + '&Par03=' + escape(cPAram escape(cPAram3) 3) // O conteudo de cUrl deverá ser "http://localhost/webinfo.ap "http://local host/webinfo.apw?Par01=Teste% w?Par01=Teste%20de%20Parametr 20de%20Parametro%2001 o%2001 02&PAr02=%23reserva%23&Par03 02&PAr02=%23r eserva%23&Par03=1%2B2%2B3" =1%2B2%2B3" , próprio para a monyahem de um link .
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função GETJOBPROFSTR GETJOBPROFSTRING ING Revisão: 08/12/2003 Abrangência
Versão 7.10
Versão 8.11
LIB WEBEX
O exemplo abaixo , executado em uma thread iniciada a partir de um JOB WEBEX, recupera algumas configurações atuais em uso para este JOB. cJobType cInstances cInacTime cExpTime
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função GETPARVALUE Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
No exemplo abaixo , são montados dois arrays multimulti -dimensionais , com 2 dimensões , e são realizadas buscas nos mesmos explorando todas as pos sibilidades de uso da
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função HEXSTRDUMP Revisão: 15/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Através do exemplo abaixo, geramos a string com o DUMP de um arquivo HTML, salvo na pasta WEB a partir do RootPath do Environment. O Dump do arquivo será mostrado no Console do servidor e no Web Browser que solicitou a função
U_DumpTest.apw .
#include "protheus.ch" #include "apwebex.ch" User Function DumpTest() Local cHtml := '' Local cTXTFile := '' Local cDump := '' WEB EXTENDED INIT cHtml // Le o arquivo cTTXFile := memoread(' \Web\Default.htm') // Gera a string com o Dump do arquivo cDump := HExStrDump(cT HExStrDump(cTTXFile) TXFile) // Mostra o Dump no console conout(cDump) // Gera HTML para a visualização do DUMP cHtml := VarInfo('DUMP' VarInfo('DUMP',Htmlnotags(cD ,Htmlnotags(cDump),,.t.,.f.) ump),,.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 4C 3E 3C 48 45 41 41 44 3E 0D 0A 3C 3C 4D | ____ 0D 0A 3C 4D 45 54 41 20 48 54 54 50 2D 45 51 55 | __<META HTTP -EQU 49 56 3D 22 45 45 78 70 69 72 65 65 73 22 20 63 6F 6F 6E | IV="Expires" IV="Expires" con 74 65 6E 74 3D 22 2D 31 22 3E 0D 0A 3C 4D 45 54 | tent=" -1">____< .apw">__< 2F 48 45 41 44 3E 3C 2F 48 54 4D 4C 3E | /HEAD> ----------------------------------------------------------------------------------------------------------------------------------------------*/
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função HTMLNOT HTMLNOTAGS AGS Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
No exemplo abaixo , a função HtmlNoTags é utilizada para permitir a utilização de caracteres especiais no conteúdo de um input para um formulário Html. Local cHtml := "" Local cInput := "" // Conteudo do campo com tags HTML intepretáveis cInput := '' // Ao montar o Input , aplicar a HtmlNoTags() ao conteudo do mesmo. cHtml += '
'+HtmlNoTa
'
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função REDIRP REDIRPAGE AGE 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 RedirPage('/W_Login.apw') _Login.apw') Else // Parametro Ok , executa o APH formteste cHtml := ExecInpage('F ExecInpage('FormTeste') ormTeste') Endif ... /* Ao chamar uma tela de download , mostrar uma mensahem e iniciar um download automaticamente */ ... cHtml += ' ...mensagem de download... '
// Devolve script de redirecionamen redirecionamento to apontando para o arquivo // com o target _blank , para ser aberto em uma nova janela. cHtml += RedirPage('/do RedirPage('/downloads/arquiv wnloads/arquivo.zip','_blank' o.zip','_blank') ) ...
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função REDIRP REDIRPAGE AGE 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 RedirPage('/W_Login.apw') _Login.apw') Else // Parametro Ok , executa o APH formteste cHtml := ExecInpage('F ExecInpage('FormTeste') ormTeste') Endif ... /* Ao chamar uma tela de download , mostrar uma mensahem e iniciar um download automaticamente */ ... cHtml += ' ...mensagem de download... '
// Devolve script de redirecionamen redirecionamento to apontando para o arquivo // com o target _blank , para ser aberto em uma nova janela. cHtml += RedirPage('/do RedirPage('/downloads/arquivo wnloads/arquivo.zip','_blank' .zip','_blank') ) ...
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função RETSQLACE Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
No exemplo abaixo , utilizamos a função RetSqlAce para montar uma query de busca por título de uma determinada informação , considerando todas as possibilidades de acentuação , independentemente de como o banco foi alimentado e/ou a string de busca foi digitada. IMPORTANTE : Na expressão da Query , o campo da tabela deve ser passado pela IMPORTANTE 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' RetSqlTab('ZZ1') ) cQuery += += "WHERE LOWER(ZZ1_TIT LOWER(ZZ1_TITULO) ULO) LIKE '%"+RetSqlAce(c '%"+RetSqlAce(cFind)+"%' Find)+"%'
"
Infra-Estrutura APWEBEX APWEBEX - Exemplo da função fun ção VAL ALTOSQ TOSQL L Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
cQuery := "SELECT * FROM FA2010 " cQuery += "WHERE FA2_FILIAL = " + ValToSql('02') cQuery += "AND FA2_DTINC <= " + ValToSql(date 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 APWEBEX - Exemplo da função funç ão VARINF VARINFO O Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
No exemplo abaixo , é gerada uma string HTML com as informações do retorno da chamada de duas funções básicas da Linguagem Advpl. User Function InfoTeste() Local cHtml := '' cHtml += VarInfo(‘Date’ VarInfo(‘Date’,date()) ,date()) cHtml += VarInfo(‘Time‘ VarInfo(‘Time‘,time()) ,time()) Return cHtml /* Deve ser gerado um echo no Console do Servidor parecido com este abaixo Date -> D ( Time -> C ( */
10) [08/12/2003] 8) [20:17:48]
Infra-Estrutura APWEBEX APWEBEX - Exemplo das funções de acentuação ApWebEX Revisão: 08/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
No exemplo abaixo, vemos a diferença de comportamento entre as funções básicas da Linguagem Advpl Upper() e Lower() , e a função de Infra-estrutura Capital(), em relação às funções da Infra-estrutura APWEBEX UpperAce() , LowerAce() e CApitalAce() , quando utilizamos caracteres acentuados. cRetorno := "" cFrase := "não há EXPLICAÇÕES considerando excessões PARA O inexplicável." cRetorno cRetorno cRetorno cRetorno cRetorno cRetorno cRetorno
/* 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 APWEBEX - Exemplos das funções NTOC e CTON Revisão: 16/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
No exemplo abaixo , utilizamos as funções cton e ntoc para realizar conversões de números em base decimal para outras bases numéricas e vice -versa. nNum1 := nNum2 :=
// Converte binário para decimal // Converte Hexadecimal para decimal
nNum1++ // Soma 1 ao numero em nNum1 nNum2++ // Soma 1 ao numero em nNum2 cNum1 := NtoC(nNum1,2,8 NtoC(nNum1,2,8) ) cNum2 := NtoC(nNum2,16,8) NtoC(nNum2,16,8)
// Converte para binário novamente // Converte Converte para Hexa novamente novamente
/* -------------------------------------------------------------------------------------------------------------------------------------Ao final do programa , cNum1 será "01101010" e cNum2 será "00DA25FF" ----------------------------------------------------------------------------------------------------------------------------------------- */
APWEXADDERR Revisão: 13/04/2004 Abrangência Versão 7.10
Descrição cTitulo corresponde a um título identificador da Caracter informação. Deve ter no máximo 20 caracteres. Os caracteres acima da vigésima posição serão ignorados.
cInfo
Caracter
cInfo corresponde à Informação a ser acrescentada ao ERROR.LOG em caso de erro.
Retorno Tipo Lógico
Descrição Esta função sempre retorna .T.
Descrição Através da função ApWExA ApWExAddErr(), ddErr(), podemos acrescentar uma string de informações
adicionais em um buffer em memória, descarregado na geração do ERROR.LOG no caso de uma ocorrência de erro fatal na working thread atual. Caso a função seja chamada sem nenhum parâmetro, a última ocorrência acrescentada pela função é eliminada da pilha interna de informações. ATENÇÃO : Esta função deve ser apenas utilizada em casos de necessidade de obtenção de informações específicas acerca de uma ocorrência de erro não reproduzida em ambiente de testes e/ou não depurável, pois seu uso desnecessário prejudica a performance da aplicação final.
CAPITALACE Revisão: 08/12/2003 Abrangência Versão 7.10
Descrição String resultante convertida para munúsculo , com as primeiras letras das palavras significantes em maiúsculo.
Descrição Semelhante à função de InfraInfra-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.
Descrição cString corresponde à representação de um número em Caracter outra base numérica, compreendida entre 2 e 36. nBase corresponde à base numérica utilizada pelo numero Numérico representado em cString.
Retorno Tipo Numérico
Descrição Número recebido como parâmetro em notação decimal ( Base 10 )
Descrição Converte um número representado em String , de base 2 a 36 , para um número em base decimal (10). Observação Importante :
São considerados caracteres válidos para compor um número de base 36 os 10 algarismos numéricos de 0 a 9 e os 26 caracteres alfabéticos maiúsculos compreendidos entre A e Z. Quaisquer caractetes presentes na String de parâmetro fora desta faixa de dados e/ou fora da base ( por exemplo , uma conversão de string base 2 - binário - da string '01001020' ) retornará -1 ( menos um ) .
ESCAPE Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe ESCAPE ( < cString > ) --> cEscaped
Parâmetros Argumento cString
Tipo Descrição Caracter cString é uma sequência de caracteres a ser processada.
Retorno Tipo Caracter
Descrição 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 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¶m2=conteudo2&...
Quando passamos parâmetros via url , devemos tomar o cuidado de não utilizar caracteres reservados e especiais nos nomes e conteúdos de parâmetros. Para realizar estas conversões, utilizamos a função Escape()
EXECINPAGE Revisão: 12/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe EXECINPAGE ( < cAPHPage > ) --> cHTMLPage
Parâmetros Argumento cAPHPage
Tipo
Descrição Corresponde ào nome do APH que deve ser executado, Caracter sem a extensão.
Retorno Tipo Caracter
Descrição 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] [APWEXERR_000 7] APH page [] not f ound 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 email; 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 rehabilitar o envio simultâneo através da chamada da função HttpSetPart() com o parâmetro .T.
EXISTPAGE Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe EXISTPAGE ( < cAphFile > ) -- > lFound
Parâmetros Argumento cAphFile
Tipo
Descrição Nome do arquivo APH, sem extensão e sem path , a ser Caracter 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') ExistPage('teste') conout('teste.aph conout('teste.a ph compilado neste RPO') Else conout('teste.aph conout('teste.a ph NAO compilado neste RPO') Endif
EXISTUSRPAGE Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição Nome do arquivo AHU, sem extensão e sem path , a ser Caracter verificado
Retorno Tipo Lógico
Descrição 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') ExistUSRPage('teste') conout('teste.ahu conout('teste.a hu compilado neste RPO') Else conout('teste.ahu conout('teste.a hu NAO compilado neste RPO') Endif
GETJOBPROFSTRING Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição cKey corresponde à chave da seção de configuração da Caracter Working Thread atual a ser retornada. Valor default (string) a ser retornado pela função caso a Caracter chave especificada não sehja encontrada no .INI
Retorno Tipo Caracter
Descrição 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 retornará uma string em branco ("")
Descrição Através desta função , podemos recuperar as configurações do Job da Working Thread atual.
GETWEXVERSION Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe GETWEXVERSION ( ) --> cBuildId
Retorno Tipo Caracter
Descrição Corresponde à String Identificadora da versão , no formato V.AAMMDDHHmm V.AAMMD DHHmm . 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
Ano de geração da Lib Mês da geração da Lib MM Dia da geração da Lib DD Horário da geração da Lib HH mm Minutos do Horário de Geração da Lib Indica que a versão foi compilada com a configuracão de envio progressivo de (HTTP) HTML simultâneo para o Browse . Esta opção é imprescindível para projetos que se utilizam desta LIB. AA
Por exemplo : APWEBEX Version 3.0312021900 (HTTP)
HEXSTRDUMP Revisão: 15/12/2003 Abrangência Versão 7.10
Tipo Descrição 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 Numérico 1. Caso este parâmetro não seja informado , o Default é a posição 1 da string. nLength corresponde ào tamanho a ser considerado para a geração do DUMP a partir da posição inicial recebida em Numérico nStart. Caso este parâmetro não seja informado, é considerado o tamanho até o final da String.
Retorno Tipo Caracter
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 contr ole ( 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" overflow"
HTMLNOTAGS Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição cStrHtml corresponde a uma String que não pode conter Caracter caracteres Html interpretáveis.
Retorno Tipo Caracter
Descrição 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.
Descrição A função retornará .T. caso o ambiente de execução atual seja uma Working Thread WEBEX , inicializada pela função de infra i nfra-estrutura STARTWEBEX.
Descrição Através da função HttpIsWebEx() é possível identificarmos se o programa atual está sendo executado através de uma Working Thread inicializada utilizando-se as funções de Infra-Estrutura APWEBEX
ISEMAIL Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe ISEMAIL ( < cEMail > ) --> -- > lEmailOk
Parâmetros Argumento cEMail
Tipo
Descrição cEmail corresponde a string a ser analizada , contendo um Caracter e apenas um endereço de e -mail.
Retorno Tipo Caracter
Descrição 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. e-mail é considerado válido caso seja iniciado por um caracter , apenas Regra : Um econtenha caracteres asc de a a z e 0 a 9 , e os caracteres @ (arroba) , . (ponto) , - ( hífen) ou _ (underline) ; e deve conter uma e apenas uma arroba , e no minimo um ponto apos a arroba, intercalado por um caracter.
LOWERACE Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe LOWERACE ( < cString > ) --> cStrLower
Parâmetros Argumento cString
Tipo
Descrição cString é a sequência de caracteres a ser convertida para Caracter letras minúsculas.
Retorno Tipo Caracter
Descrição 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.
Descrição nNumero é o valor numérico , em base devimal , a ser Numérico convertido. nBase corresponde à base binária a ser utilizada para Numérico converter nNumero. nTamStr corresponde ao tamanho da string representando Numérico o numero na base desejada .
Retorno Tipo Caracter
Descrição 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 , preenchendopreenchendo-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 foi a base passada como argumento.
REDIRPAGE Revisão: 10/12/2003 Abrangência Versão 7.10
Tipo Descrição Caracter Link para onde o script deve apontar o redirecionamento Destino do redirecionamento. Caso não especificado , o Caracter default é _self. Tempo (em segundos) de delay antes do Numérico 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 de volver ao Browser um script que , ao ser executado , redirecionará o Browser à abertura de um link passado como parâmetro.
RETSQLACE Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição cStrFind corresponde à sequência de caracteres a ser Caracter procurada , podendo conter caracteres maiúsculos e minúsculos , com ou sem acentuação.
Retorno Tipo Caracter
Descrição cStrQuery corresponde à stri ng 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 .
RETSQLCOND Revisão: 12/12/2003 Abrangência Versão 7.10
Descrição Lista contendo um ou mais aliases , separados por vírgula , Caracter a serem considerados para a montagem da expressão d e validação.
cAliases Retorno Tipo Caracter
Descrição 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 primei ros do(s) índice(s) do ERP ) , que retorna apenas as comparações de Filial , e por último a função RetSqlDel, que retorna o script para verificação dos campos
deletados ( que é o último campo das chaves de índice do ERP , utilizando TopConnect ). Devemos também atentar ao fato que a função RetSqlCond() retorna os campos para a comparação utilizando o prefixo da expressão SQL com o Alias reduzido (3 letras) das tabelas informadas, de modo que estes alias devem ser especificados na cláusula FROM , na abertura da Query, quando utilizamos a função RetSqlName para retornar o nome físico das Tabelas no Banco de Dados. A função RqtSqlTab() já retorna os nomes físicos das tabelas juntamente com os alias para este fim .
RETSQLDEL Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição Lista contendo um ou mais aliases , separados por vírgula , Caracter a serem considerados para a montagem da expressão de validação.
cAliases Retorno Tipo Caracter
Descrição Corresponde à expressão SQL para filtrar os dados através da cláusula WHERE
Descrição Utilizamos a função RetSqlDel() como auxiliar na montagem de querys para busca de dados em tabelas em conformidade com o padrão adotado pelo ERP Microsiga, utilizando aliases de 3 caracteres. A função retorna , a partir dos aliases passados como parâmetro , as expressões de filtro de dados para considerar o campo D_E_L_E_T_ da(s) tabela(s) passada(s) como parâmetro. Observações :
A ordem de comparação de campos na cláusula WHERE de uma query deve procurar seguir a ordem dos campos dos indexadores do banco para efeitos de performance . Para ganharmos performance nas Querys , devemos utilizar a função RetSqlDEl() na montagem das ultimas u ltimas consistências da cláusula WHERE de uma Query.
Devemos também atentar ao fato que a função RetSqlDel() retorna os campos para a comparação utilizando o prefixo da expressão SQL com o Alias reduzido (3 letras) das tabelas informadas, de modo que estes alias devem ser
especificados na cláusula FROM , na abertura da Query, quando utilizamos a função RetSqlName para retornar o nome físico das Tabelas no Banco de Dados. A função RqtSqlTab() já retorna os nomes físicos das tabelas juntamente com os alias para este fim .
RETSQLFIL Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição Lista contendo um ou mais aliases , separados por vírgula , Caracter a serem considerados para a montagem da expressão de validação. Através de cCompFil é possível especificar uma Filial FIXA a ser comparada com os campos FILIAL do(s)
cCompFil
Caracter
alias(es) passados no parâmetro cAliases. 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 Caracter
Descrição Corresponde à expressão SQL para filtrar os dados através da cláusula WHERE
Descrição Utilizamos a função RetSqlFil() como auxiliar na montagem de querys para busca de dados em tabelas em conformidade com o padrão adotado pelo ERP Microsiga, utilizando aliases de 3 caracteres.
A função retorna , a partir dos aliases passados como parâmetro , as expressões de filtro de dados para considerar o campo filial atual ( xFilial ) de acordo com o modo de abertura do arquivo no ERP ( X2_MODO ) .
Observação : Devemos atentar ao fato que a função RetSqlFil() retorna os campos para a comparação utilizando o prefixo da expressão SQL com o Alias reduzido (3 letras) das tabelas informadas, de modo que estes alias devem ser especificados na cláusula FROM , na abertura da Query, quando utilizamos a função RetSqlName para retornar o nome físico das Tabelas no Banco de Dados. A função RqtSqlTab() já retorna os nomes físicos das tabelas juntamente com os alias para este fim .
RETSQLTAB Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição String contendo um ou mais alias , separados por virgula , Caracter a terem seus nomes físicos determinados.
Retorno Tipo Caracter
Descrição String contendo nomes fisicos e alias identificadores dos aliases recebidos
como parâmetro.
Descrição Utilizamos a função RetSqlTab() como auxiliar na montagem de query's quando trabalhamos com o padrão de Tabelas ERP Microsiga, que utilizam nomenclarura de alias com 3 Caracteres.
A função recebe como parâmetro um ou mais alias, separados por vírgula, de tabelas que desejam ser utilizadas na query, e retorna os nomes fisicos das tabelas e seus respectivos alias para serem inseridos na query.
SEPARA Revisão: 15/12/2003 Abrangência Versão 7.10
Tipo Descrição Caracter String com a sequência de caracteres a ser "parseada" cToken corresponde à string a ser utilizada como Caracter separador para delimitar as informações. lEmpty identifica se caso um intervalo vazio entre tokens Caracter deve ser retornado como um elemento do array. Caso não especificado , o Default é .T.
Retorno Tipo Caracter
Descrição 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(), podepode -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 Separa('1,2,,4',',',.f.) ',',',.f.) // Resulta {'1','2','4'} aInfo := Separa('1,2,,4',',',.t.) Separa('1,2,,4',',',.t.) // Resulta {'1','2','','4 {'1','2','','4'} '}
Observação :
Para realizar a análise de uma string, cujo delimitador tenha apenas 1 byte, e as ocorrências de dois separadores juntos sejam ignoradas na geração do array, a função separa() utiliza a função StrTokArr(), função escrita em C no Protheus Server, mais rápida para este processamento. Apenas existe a necessidade de utilizarmos a função Separa() caso as ocorrências de dois separadores juntas devam ser consideradas no array de resultado e/ou a string utilizada como separador possua mais que 1 byte de tamanho.
UNESCAPE Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe UNESCAPE ( < cString > ) -- > cUnEscaped
Parâmetros Argumento cString
Tipo
Descrição cString é a string a ter os caracteres em formato escape Caracter convertidos.
Retorno Tipo Caracter
Descrição 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 Versão 7.10
Tipo Descrição 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 Versão 7.10
Descrição cString corresponde à sequência de caracteres ou campo Caracter memo a ser pesquisado. Corresponde à sequência de caracteres a ser procurada em Caracter cString cReplace corresponde à sequência de caracteres que deve substituir a string cSearch. Caso não seja especificado, as Caracter ocorrências de cSearch em cString serão substituídas por uma string nula ("")
nStart
nStart corresponde ào núimero sequencial da primeira ocorrência de cSEarch em cString a ser substituída por Numérico cReplace. Se este argumento for omitodo , o default é 1 ( um ) . Caso seja passado um numero menor que 1, a função retornará uma string em branco ("")
nCount
nCount corresponde ào número máximo de trocas que deverá ser realizada pela função . Caso este argumento Numérico não seja especificado , o default é substituir todas as coorências encontradas.
Retorno Tipo Caracter
Descrição 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 Strtra n() é casecase-sensitive, e a função UpStrtran() não.
VALTOSQL Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição Valor Advpl a ser convertido para utilização em Query.
xExpressao
(Qualquer) Pode ser dos tipos "C" Caracter , "N" Numérico e "D" Data.
Retorno Tipo Caracter
Descrição 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 remov idas as aspas simples contidas na mesma , caso existam . Uma expressão numérica será simplesmente convertida para caracter , com aproximação de 2 casas decimais. Uma expressão Data será convertida para formato ANSI ( AAAAMMDD ) , entre aspas simples.
VARINFO Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição 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
lHtml
(Qualquer) Variável de qualquer tipo a ser examinada Corresponde à margem esquerda inicial de espaços da Numérico String de retorno , multiplicado por 5. Default = 0 Identifica se a String de retorno será montada em formato Lógico
lEcho
Lógico
nMargem
Html (.T. / Default ) ou ASCII (.F.)
Define se o Echo do retorno deve ser enviado ao console do Protheus Server , caso habilitado. ( Default = .T. )
Retorno Tipo Caracter
Descrição 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) CodeBlock : 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 t ipo determinado como string ( entre aspas ) .
WEBINFO Revisão: 12/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe WEBINFO ( ) --> cHtmlInfo
Retorno Tipo
Descrição
Caracter
cHTMLInfo corresponde à string HTML contendo as informações da cHTMLInfo 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¶m2=outroteste Será exibido no Web Browser uma tela semelhante à tela abaixo : __aCookies -> ARRAY (
0) [...]
__aPostParms -> ARRAY ( ARRAY (
0) [...]
__nProcId --> N ( 10) [1169539314] __nProcId __aProcParms -> ARRAY ( __httpPage -> C (
0) [...]
0) []
__HttpHeader -> ARRAY ( 8) [...] __HttpHeader __HttpHeader[1] -> C ( 25) [GET /webinfo.apl HTTP/1.1] __HttpHeader[2] -> C ( 172) [Accept: image/gif, image/gif, image/ximage/x- xbitmap, xbitmap, image/jpeg, image/pjpeg, application/xapplication/x-shockwave shockwave-- flash, flash, application/vnd.msapplication/vnd.ms -excel, application/vnd.ms-- powerpoint, application/vnd.ms powerpoint, application/msword, */*] __HttpHeader[3] -> C ( 22) [Accept - Language: Language: pt -br] __HttpHeader[4] -> C ( 30) [Accept - Encoding: Encoding: gzip, deflate] __HttpHeader[5] -> C ( 61) [If - Modified Modified -Since: Wed, 10 Dec 2003 12:24:29 GMT; length=1003] __HttpHeader[6] -> C ( 81) [User - Agent: 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 Keep-- Alive] Alive] HttpRCtType() -> C (
0) []
HttpRCtLen() -> N ( 10) [ HttpRCtDisp() -> C (
0) []
SoapRAction() -> C (
0) []
HttpOtherContent() -> C ( C (
-1]
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/ximage/x- xbitmap, xbitmap, image/jpeg, image/pjpeg, application/xapplication/x-shockwave shockwave-- flash, flash, application/vnd.msapplication/vnd.ms -excel, application/vnd.ms-- powerpoint, application/vnd.ms powerpoint, application/msword, */*] aHeaders[3] -> C ( 22) [Accept - Language: Language: pt -br] aHeaders[4] -> C ( 30) [Accept - Encoding: Encoding: gzip, deflate] aHeaders[5] -> C ( 61) [If - Modified Modified -Since: Tue, 09 Dec 2003 21:23:03 GMT; length=1480]
aHeaders[6] -> C ( 81) [User - Agent: 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 Keep-- Alive] aHeaders[9] -> C ( 41) [Cookie: SESSIONID=1 SESSIONID=1071153371; 071153371; AP5PROCID=0] httpCookies -> ARRAY ( 2) [...] httpCookies[1] -> C ( 9) [SESSIONID] httpCookies[2] -> C ( 9) [AP5PROCID] SESSIONID -> C ( 10) [1071153371] AP5PROCID -> C ( httpPost -> ARRAY ( httpPost -
1) [0] 0) [...]
httpGet --> ARRAY ( httpGet
0) [...]
HttpRCtType() -> C (
0) []
HttpRCtLen() -> N ( 10) [ HttpRCtDisp() -> C (
0) []
SoapRAction() -> C (
0) []
HttpOtherContent() -> C (
-1]
0) []
[APWEXERR_0000] INVALID PROC RETURN TYPE [X] ... Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0000] INVALID PROC RETURN TYPE [X] from [Y] Descrição / Causa : Na InfraInfra-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 Descrição / causa : Ao solicitarmos ao servidor Protheus o processamento de uma função Advpl através de um link .apw, utilizando a infra-estrutura ApWebex, existem funções específicas da linguagem que não podem ser executadas diretamente neste tipo de ambiente, por tratarem-se de funções exclusivas para processamentos iniciados através de um Remote, e funções que não permitem chamada direta via link. Caso alguma destas funções seja chamada diretamente via URL, esta ocorrência de erro é reproduzida.
[APWEXERR_0003] INVALID PROC RETURN TYPE [X] ... Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0003] INVALID PROC RETURN TYPE [X] from [Y]
Descrição / causa : Quando uma working thread do ambiente ApWebEx, recebe uma solicitação de processamento através de um link .apw, de acordo com o módulo web utilizado, pode ser chamada uma função intermediária [Y], antes do processamento da função chamada no link ou depois do processamento concluído. A lib exige que estas funções internediárias retornem um conteúdo Advpl do tipo "STRING". Caso a função [Y] chamada pela lib retorne um conteúdo Advpl diferente
de "STRING", o tipo de variável retornado é mostrado em [X] e a Working Thread é finalizada com esta ocorrência de erro. Solução : Verifque o código-fonte da função [Y], para certificarcertificar -se que seu retorno sempre será um conteúdo Advpl do tipo "STRING"
[APWEXERR_0004] INVALID PROC RETURN TYPE [X] ... Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0004] INVALID PROC RETURN TYPE [X] FUNCTION [YYY]
Descrição / causa : Quando solicitado ào servidor Protheus o processamento de uma função através de um link .apw, a função executada sempre deverá retornar um conteúdo Advpl do tipo "STRING". Caso o conteúdo retornado pelo processamento da função [YYY] retorne um tipo [X], diferente de "STRING", a working thread é finalizada com esta ocorrência de erro, onde [YYY] indica a função chamada através do link .apw e [X] indica o tipo de conteúdo inválido retornado Solução : Verifique o fonte da função [YYY] e certifique-se que a função sempre retorne um conteúdo do tipo "STRING"
[APWEXERR_0005] Function XXX requires APWEBEX ... Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0005] Function XXX requires APWEBEX Routines. Descrição / causa : Ao desenvolvermos uma aplicação para utilziar a infra -estrutura ApWebEx, utilizando o #include 'apwebex.ch' e os comandos WEB EXTENDED INIT ... END, devemos nos assegurar de estarmos executando esta função em um ambiente de working threads, configurados com o tipo WEBEX, utilizando as funções da infraestrutura 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 ti po 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] ST START ART Function XXX Invalid Ret ... Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0006] START Function XXX Invalid Return Type [Y] Descrição / causa : Quando é utilizado o comando WEB EXTENDED INIT, especificando uma função [XXX] de pré-validação de execução, através da cláusula START, a função especificada deverá retornar um conteúdo do tipo "STRING". Caso a função [XXX] retorne um conteúdo não vazio, de tipo ti po [Y], diferente de "STRING", o processamento da working thread é abortado com esta ocorrência de erro. Solução : Verifique o fonte da função [XXX] e assegure-se que a execução desta retorne um conteúdo do tipo "STRING"
[APWEXERR_0007] APH page [XXX] not found in .RPO Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0007] APH page [XXX] not found in .RPO Descrição / causa : Ao utilizarmos a função ExecInPage(), no desenvolvimento de aplicações utilizando as funções de infrainfra -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 QUER QUERY Y ERROR : NO CONNECTION Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0008] OPEN QUERY ERROR : NO CONNECTION Descrição / causa : Ao utilizarmos o comando OPEN QUERY, caso não exista uma conexão ativa com o TOPConnect, o processamento em execução é abortado com esta ocorrência de erro.
Solução : Certifique-se de que a chamada deste comando está sendo realizada através de uma working thread que possua uma conexão ativa com o TOPConnect.
[APWEXERR_0009] RetSqlCond failed to read X2_MODO Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0009] Failed to read X2_MODO Alias [XXX] Descrição / causa : Quando é utilizada a função RetSqlFil() como auxiliar na montagem de querys, a mesma tenta determinar se o(s) alia(s) utilizado(s) na Query estão configurados no ambiente ERP atual no SX2 em modo 'C' Compartilhado ou 'E' Exclusivo. Caso o alias [XXX] não seja encontrado na tabela SX2, ou a tabela SX2 não esteja aberta no momento da execução desta, não é possível identificar o modo de acesso do alias especificado, e a execução é encerrada com esta ocorrência de erro. Solução : Verifique se a função RetSqlF RetSqlFil() il() 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 FILIAL para a montagem da condição para Query.
[APWEXERR_0010] ERP ER P 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 i nternamente 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 required. ApWExAddErr(cTitle,cInfo), para Descrição / causa : Quando é utilizada a função ApWExAddErr(cTitle,cInfo), 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 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 ti po "STRING" Solução : Esta ocorrência de erro informa que o parâmetro cTitle foi especificado com um tipo [X], que não é "STRING". Verifique o código-fonte e corrija o parâmetro passado para a função.
[APWEXERR_0013] Argument #1 Error : Parameter required. ApWExAddErr(cTitle,cInfo), para Descrição / causa : Quando é utilizada a função ApWExAddErr(cTitle,cInfo), informar à rotina de tratamento de erro da infra-estrutura ApWebEx, uma informação adicional a ser acrescentada no LOG de erro, os parâmetros cTitle e cInfo,quando especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING"
Solução : Esta ocorrência de erro informa que o parâmetro cInfo não foi especificado ou está vazio, porém o parâmetro cTitle foi informado. Verifique o código-fonte e corrija a chamada desta função.
Descrição / causa : Quando é utilizada a função ApWExAddErr(cTitle,cInfo), ApWExAddErr(cTitle,cInfo), para informar à rotina de tratamento de erro da infra-estrutura ApWebEx, uma informação adicional a ser acrescentada no LOG de erro, os parâmetros cTitle e cInfo,quando especificados, devem ser ser ambos preenchidos, e devem ser do tipo "STRING" Solução : Esta ocorrência de erro informa que o parâmetro cInfo foi especificado com código -fonte e corrija a chamada um tipo de dado [X] que não é "STRING". Verifique o códigodesta função.
[APWEXERR_0020] INVALID JOB [XXX] TYPE [YYY] Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0020] INVALID JOB [XXX] TYPE [YYY]
Descrição / causa : Esta ocorrência de erro indica que as configurações do Job [XXX], de working thread s para utilização no ambiente ApWebEx, está identificado com um TYPE [XXX] inválido. Durante a inicialização de uma working thread , é verificado o tipo do Job configurado no arquivo de configuração. Apenas são válidos os valores WEB e/ou WEBEX, de acordo com o módulo web em uso. Caso a configuração especifique um TYPE diferente de WEB ou WEBEX, a configuração não é válida, e a working thread é abortada antes de estar disponível para atender à requisições de links .apw, gerando uma ocorrência de erro no console do servidor Protheus, também gravada no arquivo ERROR.LOG Solução : Para solucionar esta ocorrência, basta verificar a configuração do Job [XXX] utilizado para inicializar as working threads e especificar um tipo adequado ( WEB ou WEBEX ), de acordo com o módulo em uso.
[APWEXERR_0021] UNABLE TO GET JOB NAME Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
[APWEXERR_0021] UNABLE TO GET JOB NAME Descrição / causa : Esta ocorrência de erro indica que o processo atual em execução não foi originado pela configuração de um processo WEB ou WEBEX , ou a função de inicialização de ambiente STARTWEBEX não foi chamada através de um evento ONSTART de JOB, como por exemplo um AP Remote. Solução : Caso esta ocorrência seja reproduzida, cerifique -se que a função de inicialização das working threads ( STARTWEBEX ) esteja sendo chamada através de um processo configurado com TYPE=WEB ou WEBEX, de acordo com o módulo web em uso.
[APWEXERR_0022] Function [X] of Module [Y] ... Revisão: 13/04/2004 Abrangência
Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0022] [APWEXERR_002 2] 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] UNSUPPOR U NSUPPORTED TED BREAK CONTROL Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0023] UNSUPPORTED BREAK CONTROL Descrição / causa : Ao utilizar as funções de Infra -Estrutura APWEBEX, quando da chamada de uma função atravé de Link .apw , desde a chamada original até a passagem pelos pontos de pré e pós -validação de processamento, a rotina de tratamento de erro habilitada é de controle interno e exclusivo da Infra-Estrutura ApWebEx. Caso o comando BREAK seja chamado em algum destes pontos, a execução é abortada , e na rotina de tratamento de execução, não há o registro de controle de erro, de modo que a working thread é abortada com esta ocorrência de erro. Solução : Certifique-se que no códiugo fonte da aplicação não seja utilizado o comando BREAK.
OBSERVAÇÃO : Como esta ocorrência é tratada em um ponto de retorno interno, o ponto de entrada WEBEXERROR não é executado, sendo retornada ao usuário a mensagem padrão de Erro.
[APWEXERR_0024] Function [X] of Module [Y] ... Revisão: 13/04/2004 Abrangência
Versão 8.11
LIB WEBEX
[APWEXERR_0024] [APWEXERR_002 4] Function [X] of Module [Y] not found in Rpo.
Descrição / causa : Esta ocorrência de erro é reproduzida quando, ao configurar um módulo web [Y], a função [X] de inicialização, conexão ou finalização, referente ao módulo, não foi encontrada no repositório de objetos do ambiente em uso pela aplicação web. Solução : Certifique-se que o repositório em uso atualmente possui as funções pertinentes ào modulo configurado.
[APWEXERR_0025] Unknow SIGAWEB Module [Y] Revisão: 13/04/2004 Abrangência Versão 7.10
Descrição / causa : Quando da configuração de um módulo web para os tratamentos internos das funções de infra-estrutura ApWebEx, devemos especificar uma sigla de um módulo Web válido e tratado pela lib de infra-esturtura. Os módulos atualmente implementados na lib são : DW - Data WareHouse BSC - Balanced ScoreCard MAK - Modulo WEBEX Makira GE - Gestão Educacional GPR - Gestão de Pesquisa e Resultado TCF - Terminal do Funcionario ( RH ONLINE ) PP - Portal PRotheus ( WebServices ) SAV - Sala de Aprendizagem Virtual GAC - Gestão de Acervos WPS - WebPrint & WebSpool Caso não seja fornecida uma sigla válida na chave SIGAWEB, na seção de
configuração das working threads, as mesmas não entrarão no ar, e serão abortadas com esta ocorrência de erro.
Solução : Verifique a chave de configuração SIGAWEB e preencha-a com uma sigla de módulo válida para a versão de repositório / ambiente em uso.
[APWEXERR_0026] Web Services Test POST ERROR. Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
[APWEXERR_0026] [APWEXERR_00 26] Web Services Test POST ERROR..
Descrição / causa : Quando utilizamos a interface de testes de web services client da erramenta WebAdmin, caso ocorra uma falha estrutural no serviço Client ou uma f erramenta impossibilidade de recuperar todos os dados postados no fomulário de testes, o processamento é interrompido com esta ocorrência de erro.
[APWEXERR_0027] INVALID NTOC BASE [NNN] Revisão: 13/04/2004 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
[APWEXERR_0027] INVALID NTOC BASE [NNN] Descrição / causa : Ao utilizar a função ntoc(), deve-se atentar ao limite de base numérica para conversão, que pode ser um número entre 2 e 36. Caso a base passada como parâmetro para a função ntoc() esteja fora destes limites, o processamento é abortado com a ocorrência acima , informando em NNN a base utilizada. Solução : Verifique a chamada da função ntoc() no fonte e certifique-se que está sendo informado um número entre 2 e 36.
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.
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 LICENCE LICE NCESS AV AVAIL AILABL ABLE E (.. (.... Revisão: 13/04/2004 Abrangência Versão 8.11
LIB WEBEX
[APWEXERR_0030] NO WEB LICENCES AVAILABLE
Descrição / causa : Esta ocorrência de erro, indica que não há mais licenças Protheus i disponíveis para a utilização da aplicação Web. Adicionalmente à esta ocorrência, é informado adicionalmente a informação "WEB LICENSE STATUS [NNNN]", onde nnnn indica o código de erro do HardLock utilizado para controle de licenças. Solução : Verifique na lista completa de status de retorno do HarkLock , disponível em (pendente), para certificar-se da origem desta ocorrência e então tomar uma ação corretiva.
[APWEXE RR_0031] [APWEXERR_00 31] WARNING WARNING : WEB LICENSES LICENS ES WILL EXP... EXP... Revisão: 13/04/2004 Abrangência Versão 8.11
LIB WEBEX
[APWEXERR_0031] [APWEXERR_00 31] WA RNING : 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 impleme ntados para um módulo web do padrão, deve ser consultada a documentação do módulo correspondente.
01. STARTWEBEX Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe 01. STARTWEBEX ( [ NIL ] ) -- > lSucess
Parâmetros Argumento NIL
Tipo
Descrição (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 retornado .F. , o Protheus irá eliminar esta Working Thread da memória.
Lógico
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 Tecnolo gia Protheus / Programa ção Advpl para WEB / InfraPrincipal Infra-Estrutura APWEBEX / Pontos de Entrada
02. CONNECTWEBEX Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição Função chamada através do Link . Por exemplo , um link no browse chamando Caracter http://localhost/w_teste.apw?Opc=03 , seria recebido neste parâmetro a string "W_TEST "W_TESTE" E"
Retorno Tipo Caracter
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 solicitante , e a função chamada através do link não é executada.
Descrição Este ponto de entrada é executado imediatamente antes do processamento de uma requisição realizada através de um browser para processamento de uma função Advpl , através de um link .apw , permitindo realizar uma pré-validação antes de cada processamento solicitado através do Browser.
03. RESETWEBEX Revisão: 10/12/2003 Abrangência Versão 7.10
Descrição cFnLink corresponde à função Advpl que foi chamada e Caracter processada imediatamente antes da chamada deste ponto de entrada.
Retorno Tipo Caracter
Descrição 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.
04. FINISHWEBEX Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe 04. FINISHWEBEX ( ) --> NIL
Parâmetros Argu mento
Tipo Descrição
Retorno Tipo (NULO)
Descrição O Retorno deste ponto de entrada não é utilizado.
Descrição Este ponto de entrada é executado quando da finalização ( Fechamento ) de uma Working Thread APWEBEX. Não recebe parâmetros , e não requer retorno. Ele permite que seja executado um procedimento qualquer no momento da saída de uma Working Thread, seja por time-out ou por tempo total de permanência no ar.
05. ENDSESSION Revisão: 10/12/2003 Abrangência Versão 7.10
Versão 8.11
LIB WEBEX
Sintaxe 05. ENDSESSION ( < cSessionId > ) --> NIL
Parâmetros Argumento
Tipo
cSessionId
Caracter
Descrição cSessionId corresponde à string identificadora das sessions deste usuário.
Retorno Tipo (NULO)
Descrição 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.
Descrição Objeto do Erro Advpl. Mensagem ASCII que será gravada no arquivo error.log Mensagem Html original da rotina de tratamento de Erro
Retorno Tipo Caracter
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 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 Independentemente 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, aplic ando-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. Pr otheus.
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 : Link
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 Link =345'>Link
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 &par r1=<%=Escape(cCodigo)%>&par2=345'>Link 2=345'>Link
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 parâmetros & ( e Comercial ), este caractere será interpretado como DADO e não como separador, comprometendo o funcionamento do link.
Combo / Select em Html : Recuperando valores Revisão: 11/12/2003 Examinemos o exemplo abaixo , onde criamos um formulário HTML com um 'Combo Box' ( tag