AP5 Web - Conectividade e AdvPL ASP

Advanced Protheus - AP5

AP5 Web – Conectividade e AdvPL ASP

CopyRight © 2000 Microsiga Software S.A.

Advanced Protheus - AP5 Web – Conectividade e Advpl ASP CopyRight © 2000 Microsiga Software S.A.

Sumário

AP5 WEB - CONECTIVIDADE.................................................................................................................................3

RPC ENTRE O AP5 E OUTRAS APLICAÇÕES...................................................................................................................4

A API de comunicação com o AP5.........................................................................................................................................4O Controle ActiveX.................................................................................................................................................................9

RPC ATRAVÉS DA INTERNET.........................................................................................................................................10

O AP5 Server como um servidor Web........................................................................................................................................10

Serviços de FTP.....................................................................................................................................................................10Serviços de HTTP..................................................................................................................................................................11

Criando funções APL..................................................................................................................................................................13

Exemplo de função APL........................................................................................................................................................14

O ADVPL ASP............................................................................................................................................................................15

Características do ADVPL ASP............................................................................................................................................15

Advanced Protheus - AP5 Web – Conectividade e Advpl ASP CopyRight © 2000 Microsiga Software S.A.

AP5 Web - Conectividade

O AP5 Server é o centro de funcionamento do Advanced Protheus. É o encarregado pelo processamento das aplicações, gerenciamento das conexões e compilação de programas. E uma de suas principais características é a alta conectividade. Ou seja, o AP5 pode ser integrado a diferentes soluções ou sistemas, através da utilização de uma API de acesso (contida em uma DLL) ou um controle ActiveX, ou mesmo diretamente através da Web (via protocolo HTTP ou FTP). Isso permite outras aplicações a terem acesso a execução de funções (jobs) no AP5, utilizando o conceito de RPC.RPC (Remote Procedure Call) significa Chamada Remota de Procedimentos, ou seja, através de uma aplicação externa (ou através da Internet) é possível executar no AP5 rotinas criadas em ADVPL. Tais rotinas poderão realizar todo o tipo de tarefa desejada, como por exemplo cadastrar um pedido, um cliente, ou emitir um relatório em formato HTML, retornando informações à aplicação externa.

A utilização da API de acesso e do controle ActiveX é mais indicada para aplicações desenvolvidas em outras linguagens e que necessitem interagir com o AP5. Já com o acesso via Internet, é possível criar toda uma aplicação Web que alie o poder de processamento do AP5 com a facilidade de formatação de interface do HTML.

Advanced Protheus - AP5 – Conectividade e Advpl ASP 3 CopyRight © 2000 Release A – Microsiga Software S.A.

RPC Entre o AP5 e Outras Aplicações

São duas as opções para realizar RPC entre uma aplicação externa e o AP5: Uma API de acesso, utilizando a DLL (Dinamic Link Library) chamada AP5DCONN.DLL; Um controle ActiveX , utilizado através do arquivo AP5CONNXCONTROL.OCX.

Ambas opções têm as mesmas funcionalidades: Conexão a um ou mais servidores AP5; Acesso a algumas funções gerenciais, como obtenção de lista de usuários conectados, envio de mensagens,

e gerenciamento das conexões; Execução de jobs e procs. Os jobs podem ser executados no AP5 sem que necessariamente a aplicação

externa aguarde pelo retorno. Podem assim permanecer executando no AP5 Server enquanto a aplicação externa realiza outras tarefas, ou mesmo executa outros jobs. Os procs entretanto, sempre farão com que a aplicação externa aguarde o retorno do AP5;

Os jobs ou procs são funções contidas no repositório do AP5 (incluindo as funções criadas por usuários – User Function). A aplicação externa pode, sempre através da DLL ou da OCX, enviar parâmetros e receber o retorno destas funções, segundo os tipos de dados válidos: Caracter, numérico, lógico, data e array;

A conexão ao AP5 é sempre efetuada através do protocolo TCP/IP. O acesso ao AP5 Server somente será efetuado se a correta senha e usuário forem informados. A checagem dessa senha é efetuada pelo Advanced, e deve ser mantida através do SIGACFG. O usuário informado deve ser o Administrador do sistema ou pertencer ao grupo Administradores;

Geralmente a utilização de uma dessas opções será indicada para aplicações que necessitem executar processos dentro do AP5, como por exemplo, colocar um pedido de venda diretamente na base de dados do sistema,

Importante: Para utilizar a API ou o controle ActiveX, é necessário a DLL de comunicação do AP5 chamada AP5CONN.DLL. Por isso, sempre que for necessário utilizar uma dessas opções, a DLL de comunicação deve estar em um path localizável pelo Windows e deve estar atualizada em relação ao AP5 Server em que a aplicação externa tentará se conectar.

A API de comunicação com o AP5

Para utilizar a API de comunicação do AP5, é necessário conhecer a linguagem em que a aplicação externa está escrita, a ponto de poder utilizar o conceito de DLL´s do Windows. Qualquer linguagem de programação que suportar a utilização de DLL´s poderá utilizar a API de comunicação.Diferentemente do controle ActiveX, a DLL de comunicação não pode ser tratada como um objeto, porém podem existir várias instâncias de comunicação, o que permite a comunicação com diferentes servidores do AP5 simultâneamente. O processo de utilização resume-se em:

1. Criação de uma instância de comunicação;2. Conexão ao AP5 Server;3. Utilização efetiva: Execução de rotinas, obtenção do retorno, etc;4. Desconexão;5. Destruição da instância de comunicação.


Para tal, existem as seguintes funções disponibilizadas na DLL de comunicação:

AP5CreateConnControlDescrição: Criação de uma instância de comunicação com o AP5 Server. Pode-se criar diferentes instâncias de

comunicação, acessando um ou mais servidores do AP5.

Parâmetros: cServer: char * - Nome ou endereço IP do servidor para a conexão;nPort: int - Porta do socket TCP/IP utilizada para a conexão;cEnvironment: char * - Ambiente utilizado para a execução de processos;cUser: char * - Usuário do sistema para validação da conexão. O usuário informado deve pertencer ao grupo Administradores do sistema;cPassWord: char * - Senha do usuário informado, para validação da conexão.

Retorno: int - Retorna o Handle da instância criada. Este Handle retornado deverá ser informado em todas as demais funções de comunicação, para identificação da instância que será utilizada.

Sintaxe: nAP5 = AP5CreateConnControl(“APSERVER”, 1024, “ENVIRONMENT”, “Administrador”, “”)

AP5DestroyConnControlDescrição: Destruição de uma instância de comunicação com o AP5 Server. Após a utilização da API, e antes de

encerrar a execução da aplicação externa, é necessário destruir o Handle criado com a função anterior para a liberação de memória.

Parâmetros: nObjectID: int - Handle da instância criada com a função anterior.

Retorno: bool - Retorna verdadeiro ou falso, indicando a execução com sucesso da função.

Sintaxe: lOk = AP5DestroyConnControl(nAP5)

AP5ConnectDescrição: Conexão a um AP5 Server. Esta função não deve ser confundida com a função

AP5CreateConnControl. Esta função irá realizar a conexão com o AP5 Server indicado durante a criação da instância informada como parâmetro.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função. É através do Handle que é definido em qual servidor, porta e ambiente os processos serão executados.

Retorno: bool - Retorna verdadeiro ou falso, indicando se a conexão foi efetuada com sucesso.

Sintaxe: lOk = AP5Connect(nAP5)

AP5DisconnectDescrição: Desconexão de um AP5 Server. Esta função não deve ser confundida com a função

AP5DestroyConnControl. Esta função irá encerrar a conexão ativa com um AP5 Server, da instância informada como parâmetro.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função.

Retorno: Sem retorno.

Sintaxe: AP5Disconnect(nAP5)


AddNullParam,AddNumericParam,AddStringParam,AddLogicalParam,AddDateParamAsDouble,AddDateParamAsString,AddArrayParamDescrição: Estas funções são utilizadas para a execução de processos em um servidor AP5. Podem ser utilizadas

somente após uma conexão ser ativada. Um processo executado em um servidor AP5 pode necessitar de parâmetros, que deverão ser enviados ao servidor antes da execução do processo através da utilização destas funções. Os tipos de dados que podem ser enviados são: Numérico (int), Caracter (char *), Lógico (bool), Data (enviado como caracter – char * - ou como numérico - int) e Array (variant).

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função. É através do Handle que é definido para qual servidor o parâmetro será enviado;xParametro: indefinido - O tipo de dado do parâmetro dependerá da função utilizada, segundo os tipos de dados permitidos explicados acima.

Retorno: bool - Retorna verdadeiro ou falso, indicando se o parâmetro pôde ser enviado ao AP5 Server com sucesso.

Sintaxe: lOk = AddNumericParam(nAP5,5)oulOk = AddStringParam(nAP5,“TEXTO”)oulOk = AddLogicalParam(nAP5,true)

ResultAsNumeric,ResultAsString,ResultAsLogical,ResultAsDate,ResultAsDateString,ResultAsArrayDescrição: Estas funções são utilizadas para obter o retorno do AP5 Server após a execução de um processo.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função.Apenas para as funções ResultAsString e ResultAsDateString:cBuffer: char * - Buffer de caracteres alocado para receber o retorno em formato caracter;nSize: int - Tamanho do buffer passado no parâmetro anterior.

Retorno: O tipo de dado do retorno dependerá da função utilizada, segundo os tipos de dados definidos anteriormente. Para as funções ResultAsString e ResultAsDateString o retorno será o tamanho do buffer preenchido.

Sintaxe: nRet = ResultAsNumeric(nAP5)oulRet = ResultAsLogical(nAP5)ouResultAsString(nAP5,cBuffer,nSize)


AP5BuildNumberDescrição: Função utilizada para obter o número do build de compilação da API de conexão ao AP5.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;cBuild: char * - Buffer de caracteres para receber o número do build;nSize: int - Tamanho do buffer passado no segundo parâmetro.

Retorno: int - Retorna o tamanho do buffer contendo o número do build.

Sintaxe: AP5BuildNumber(nAP5,cBuffer,nSize)

PrepareEnvDescrição: Função utilizada para preparar o ambiente do sistema, ou seja, abrir arquivos, criar variáveis, e tornar

o ambiente de execução da aplicação externa em relação ao AP5 Server, o mais parecido possível com o que é realizado pelos módulos do sistema.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;cEnv: char * - Ambiente que será utilizado para a abertura dos arquivos;cEmp: char * - Código da empresa do sistema (dois dígitos) que deverá ser aberta;cFil: char * - Código da filial que será utilizada (dois dígitos);aTables: variant – Este parâmetro deve ser um array variant (para detalhes, consulte a documentação da linguagem utilizada) contendo as siglas das tables que deverão ser abertas (por exemplo “SB1”).

Retorno: bool - Retorna verdadeiro ou falso, indicando o sucesso da execução da função.

Sintaxe: PrepareEnv(nAP5,“ENVIRONMENMT”,“99”,“01”,aTables)

StartJobDescrição: Esta função permite a execução de um processo (job) em um AP5 Server. O processo executado pode

ser qualquer um dos existentes no repositório definido pelo ambiente informado, incluindo as funções criadas pelo usuário (User Function). Pode também receber parâmetros, bem como retornar um valor para a aplicação externa, sempre utilizando-se das funções descritas anteriormente. A execução de um processo resume-se em: A)

1. Enviar os parâmetros (se existirem);2. Executar o processo e aguardar sua finalização;3. Obter o resultado (se existir).

B)1. Enviar os parâmetros (se existirem);2. Executar o processo sem aguardar sua finalização;

Os processos são executados em threads de execução separadas. Isso permite à aplicação externa que esteja utilizando a API, optar por executar o processo e continuar trabalhando enquanto o mesmo está em execução. Porém, somente poderá obter um retorno quando esperar até que o processo termine de ser executado.

Obs.: Como estes processos são executados sem que uma instância do AP5 Remote esteja ativa, devem ser criados sem nenhum comando de interface (criação de janelas, comandos de alerta, help, etc). Se um comando de interface for utilizado no código ADVPL de um processo, a execução deste através da API gerará um erro de execução.


Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;cEnv: char * - Ambiente que será utilizado para a execução do processo;cFunc: char * - Nome do processo ou função que será executado no AP5 Server;lWait: bool - Verdadeiro ou Falso indicando se a aplicação externa deverá ou não aguardar pelo término da execução do processo.

Retorno: bool - Retorna verdadeiro ou falso, indicando se o processo foi iniciado com sucesso.

Sintaxe: StartJob(nAP5,“ENVIRONMENMT”,“MESEXTENSO”,true)

CallProcDescrição: Esta função tem o mesmo objetivo que a anterior, porém sempre aguardará o término do processo

para que o controle volte à aplicação externa, e tem algumas diferenças conceituais:A) Não se pode escolher o ambiente no qual o processo será executado. Os processos

executados pela CallProc serão sempre executados no ambiente indicado na criação da instância com a função AP5CreateConnControl;

B) Um processo executado através da função StartJob, começará de um ambiente totalmente novo. Porém, os processos executados pela função CallProc mantêm o ambiente da última execução. Assim, o valor de variáveis criadas, os arquivos abertos, etc, são mantidos na próxima execução.

Parâmetros: nObjectID: int - Handle da instância que será utilizada para a execução desta função;cFunc: char * - Nome do processo ou função que será executado no AP5 Server.

Retorno: Bool - Retorna verdadeiro ou falso, indicando se o processo foi finalizado com sucesso.

Sintaxe: CallProc(nAP5,“CALCEST”)

Com a utilização da API, pode-se criar toda uma aplicação, em Visual Basic por exemplo, que executará funções do sistema Advanced como o usuário faria através do AP5 Remote:

Dim nAP5 As IntegerDim cRes As String

nAP5 = AP5CreateConnControl(“APSERVER”, 1024, “ENVIRONMENT”, “Administrador”, “”)

If AP5Connect(nAP5) ThenAddNumericParam(nAP5,5)lOk = CallProc(nAP5,“MESEXTENSO”)If lOk Then

ResultAsString(nAP5,cRes)Else

CRes = “Não foi possível obter o mês por extenso”End ifAP5Disconnect(nAP5)

End if

AP5DestroyConnControl(nAP5)

Importante: A notação dos tipos de dados e da sintaxe mencionados na descrição das funções segue o padrão de linguagens como a linguagem C. Deve-se considerar os exemplos de sintaxe conforme a linguagem utilizada.Todas as funções de caracter como ResultAsString ou AP5BuildNumber, trabalham com buffer de caracteres. Isto significa que o buffer que receberá o retorno deve ser alocado na linguagem utilizada e que o tamanho alocado deverá ser passado como parâmetro para a função chamada.

A aplicação externa também será responsável por liberar a memória do buffer alocado.


O Controle ActiveX

O controle ActiveX tem as mesmas funcionalidades da API. Porém o formato de utilização é diferenciado. O controle ActiveX é um objeto que deve ser registrado no computador onde será utilizado e durante a execução da aplicação externa, deverá ser criado, utilizado e destruido ao final. Para maiores detalhes, consulte a documentação da linguagem utilizada ou a documentação do conceito ActiveX na página da Microsoft (http://www.microsoft.com).


http://www.microsoft.com/

RPC através da Internet

O RPC através da Internet é realizado diretamente com o AP5 Server utilizando o protocolo HTTP. Isto significa que é possível criar páginas HTML que executem processos no AP5 Server, ou mesmo utilizar recursos de conectividade Wireless, como por exemplo um Palm, para acessar e executar processos diretamente no AP5 Server através do protocolo HTTP. Neste último caso é possível também utilizar uma conexão direta TCP/IP (via socket).Para realizar o RPC utilizando o protocolo HTTP diretamente com o AP5 Server, não é necessário a utilização de um servidor Web de terceiros, pois o AP5 Server também é um servidor Web.

O AP5 Server como um servidor Web

O AP5 Server 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 ou o Apache para Linux). Assim, basta ter o AP5 para poder criar sua própria Intranet num ambiente de rede local, ou publicar o endereço IP da máquina com o AP5 Server 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 e/ou dinâmicas.

Serviços de FTP

O protocolo FTP (File Transfer Protocol) permite a transferência de arquivos entre um servidor e uma aplicação client de FTP (com um Web Browser como o Internet Explorer, por exemplo). Utilizando o AP5 Server como um servidor FTP, os usuários poderão remotamente baixar arquivos disponibilizados em um diretório configurável no servidor. Pode-se também habilitar um recurso de auto-atualização para o AP5 Remote, que irá automaticamente baixar arquivos compactados para se auto atualizar quando necessário.

Para habilitar o serviço de FTP no AP5 Server, o seguinte grupo deve ser criado no arquivo de configurações (AP5SRV.INI):

[FTP]Enable=1 Path=C:\AP5\FTPPort=21

Onde as chaves são: -Enable indica se habilita ou desabilita este serviço;-Path indica o diretório onde o AP5 Server localizará os arquivos para disponibilizar no FTP;

-Port é a porta usada para conexão das aplicação client.

O recurso de auto-atualização encontrado no AP5 Remote funciona através da detecção de diferenças na versão das DLL´s locais (ou seja, que se encontram juntamente com o executável do AP5 Remote). Quando isto ocorre, o usuário é questionado sobre a execução da auto-atualização. Se tudo estiver corretamente configurado no arquivo de configuração do AP5 Remote (AP5RMT.INI – para maiores detalhes, consulte a documentação do AP5 Remote), ao escolher que deseja tentar uma auto-atualização, o AP5 Remote irá abrir uma conexão FTP com o Server configurado e baixar os arquivos compactados (com a extensão .CAB) contendo as DLL´s e executáveis mais atualizados. Os arquivos serão então descompactados localmente para a atualização.


Figura 1 - Internet Explorer 5 acessando a área de FTP do AP5 Server

Serviços de HTTP

O protocolo HTTP (HyperText Transmission 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. Mais adiante, será mais fácil compreender onde tais comandos são utilizados no AP5 Server.

Utilizando o AP5 Server como um servidor HTTP, o mesmo poderá ser acessado através de um Web Browser como o Internet Explorer por exemplo, que receberá as páginas HTML enviadas de um diretório configurado no servidor. Adicionalmente ao envio e recebimento de páginas estáticas formatadas, pode-se utilizar a linguagem Advpl do AP5 para processar páginas mistas, que contém código Advpl e comandos HTML de formatação. Tais páginas serão processadas no AP5 Server, 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 AP5, 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).

Para habilitar o serviço de HTTP no AP5 Server, os seguintes grupos devem ser criados no arquivo de configurações (AP5SRV.INI):

[HTTP]Enable=1Path=C:\AP5\HTTPRPCServer=SERVERKEY RPCEnv=ENVIRONMENTRpcTimeOut=40Port=1234GetProc=<função>PostProc=<função>

[SERVERKEY]TYPE=TCPIPServer=172.16.1.1Port=5024

Onde as chaves são: Grupo HTTP

- Enable indica se habilita/desabilita o serviço;- Path indica o diretório onde o AP5 Server localizará os arquivos

HTML e demais arquivos que forem requeridos por um Web Browser;- RPCServer indica o nome do grupo que contem as configurações do

AP5 Server onde serão executadas as chamadas de funções Advpl através de RPC (por requests HTTP);

- RPCEnv indica o nome do grupo que contém as configurações de ambiente para a execução das funções requisitadas em RPC;

- RPCTimeOut indica o tempo em segundos que a thread de execução RPC permanecerá no ar (e conseqüentemente com todo o ambiente preparado para ser utilizado em uma próxima execução de RPC via HTTP);

- Port é a porta utilizada para a conexão dos Web Browsers;


Figura 2 - Internet Explorer 5 acessando o AP5 Server como um servidor HTTP

- GetProc e PostProc são parâmetros opcionais que podem ser utilizados para interceptar os comandos GET e POST que caem no AP5 Server. Quando um comando desses é requisitado ao servidor e uma destas chaves está em uso, a função informada é executada e receberá um parâmetro com o nome da página, arquivo ou função, originalmente requisitado.

Grupo <SERVIDOR> (no exemplo, SERVERKEY)- TYPE indica o tipo de conexão que será efetuada entre o servidor atual (que é o AP5 Server encarregado de

responder os requests HTTP) e o servidor de RPC (que é o encarregado de executar as rotinas em Advpl);- Server indica o nome ou endereço IP do servidor encarregado da execução das rotinas em Advpl (RPC).

Note que estes servidor não precisa necessariamente ser um servidor diferente do utilizado para responder aos requests HTTP (aquele que trabalha como Web Server);

- Port é a porta utilizada para conexão ao Servidor RPC.

Quando uma URL é requisitada através de um Web Browser (seja através de um comando POST, um link ou diretamente através do campo de URL do Browser), essa requisição é recebida pelo AP5 Server que a tratará do seguinte modo:

Extensão do arquivo

Descrição O que acontece Exemplo

Nenhuma Um endereço http único, sem um nome de arquivo definido.

Ao chamar um endereço URL sem informar um nome de arquivo, o AP5 Server irá procurar o arquivo chamado DEFAULT.HTM para enviar ao Web Browser que efetuou o request.

http://servidor/

.HTM;.HTML ou outra extensão qualquer.

Páginas HTML, arquivos texto, arquivos de imagem, som, vídeo, etc.

A página HTML, ou qualquer que seja o arquivo, será simplesmente enviado ao Web Browser, sendo que este é o responsável pela sua tradução/interpretação.

http://servidor/cadastro.htmouhttp://servidor/imagem.gif

.APL É uma chamada direta a uma função do repositório do AP5.

Quando o AP5 Server receber um request deste tipo, a função chamada (no exemplo func.apl, a função chamada é func, sem a extensão) será executada no AP5 Server configurado na chave RPCSERVER no ambiente definido pela chave RPCENV.O que deverá ser retornado pela função é uma string, que será enviada para o Web Browser.

http://servidor/acerto.aplouhttp://servidor/runprog.apl

.APH É uma chamada para uma página ativa (uma página em ADVPL ASP).

Uma página Advpl ASP é uma página HTML contendo código interpretável no servidor. Tais páginas são criadas utilizando qualquer editor de texto ou editor HTML, e devem ter SEMPRE a extensão .APH. Devem ser compiladas através do AP5 IDE. Durante a compilação, o AP5 Server transforma essa página em uma função interna que será executada da mesma maneira que aquelas chamadas .APL explicadas anteriormente.Como também são funções, as páginas em Advpl ASP devem ser chamadas do Web Browser com a extensão .APL exatamente como explicado anteriormente.

http://servidor/activepage.aplouhttp://servidor/cadastro.apl


Criando funções APL

A princípio, todas as funções contidas no repositório podem ser executadas diretamente através de uma requisição HTTP ao AP5 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 AP5 Server 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:- __aCookies: Este parâmetro recebe um array bidimensional com os Cookies criados na aplicação client

HTTP (por exemplo, no Internet Explorer 5). Pode-se utilizá-lo para checar validações mantidas nas máquinas client por exemplo. Para maiores detalhes, consulte a documentação do HTML ou do Web Browser utilizado.

- __aPostParms: Este parâmetro recebe um array bidimensional com os campos contidos em um formulário HTML recebido através de um comando POST. Cada item deste array contém um array com o nome do campo e o valor informado. Por exemplo, para um formulário com dois campos para digitação (um chamado nome e o outro chamado endereco), que enviam os dados para a função cadastro.apl através de um POST, a função receberá o array __aPostParms da seguinte forma:{

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

}A função pode tratar os dados recebidos neste array para realizar um processamento específico com tais informações. Para campos onde não é possível a entrada de dados e sim a escolha de uma informação pré-definida (como por exemplo um checkbox), o item somente existirá no array caso o campo tenha sido selecionado no formulário HTML (por exemplo, se o checkbox for marcado).

- __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=PRODUTO DE TESTE&quant=20a 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.

- __cHTTPPage: Esse parâmetro recebe o nome da página, arquivo ou função originalmente requisitada para o AP5 Server. É utilizado quando as chaves GETPROC e POSTPROC (explicadas anteriormente) são habilitadas no arquivo de configurações do AP5 Server. A função configurada irá receber nesse parâmetro o nome original requisitado e poderá executar algum processamento específico para continuar o processo (retornando a própria função original) ou desviar para outra página, por exemplo.

Exemplo de função APL

A função a seguir é um bom exemplo para ser executado através de um Web Browser como o Internet Explorer ou o Netscape Navigator. 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 AP5 IDE, cole o código abaixo e salve o arquivo como WEBDEMO.PRW. Após compilar o programa, basta chamar em um Web Browser uma URL como:

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

Código da função:

#include "rwmake.ch"

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

// Coloca uma mensagem em HTMLcHTML += '<p><h1 align="center">Hello World!!!</h1></p>' // Coloca um separador de linha em HTMLcHTML += '<hr>' If Len(__aProcParms) = 0 cHTML += '<p>Nenhum parâmetro informado na linha de URL.'Else For i := 1 To Len(__aProcParms)

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

Next iEndif

Return(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 compilação.Note que no caso de funções do usuário (User Function) o nome chamado na URL do Browser também deverá conter o U_ no começo da função, por exemplo:http://servidor/u_webrelato.apl

E deve-se sempre indicar a extensão .APL para que o AP5 Server identifique que é uma função a ser executada.


O ADVPL ASP

Uma página ASP (Active Server Pages) é uma página HTML contendo código interpretável em uma linguagem compreensível ao servidor HTTP em uso. Por exemplo, o IIS da Microsoft utiliza o VBScript para criar suas páginas ASP, do mesmo modo que o AP5 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 AP5 e desejam desenvolver páginas ativas para aplicações Web utilizando essa facilidade é conhecer HTML.

Características do ADVPL ASP

Os arquivos ADVPL ASP têm a extensão padrão .APH. São arquivos texto e devem ser adicionados a um projeto no AP5 IDE e compilados da mesma maneira que os programas tradicionais. A diferença é que o AP5 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, e retornará uma string. O desenvolvedor não precisa se preocupar em retornar HTML 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 contido no arquivo, depois que o código foi processado.

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. Do mesmo modo que as demais funções, o arquivo APH também deve ser executado (através da URL do Browser, por exemplo) com a extensão .APL.

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 não será executado antes da compilação.

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

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

<body><p>Bem vindo ao mundo do ADVPL ASP!</p>

<%// Soma os 100 primeiros númerosLocal i, nSoma := 0For i := 1 To 100

NSoma += i

Next i%>

</body></html>

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


A grande vantagem de se criar arquivos ADVPL ASP em relação a criar funções APL simples, decorre do fato de que não é necessário conhecer tão profundamente HTML e 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 o código necessário entre o script. Outro detalhe importante é que pode-se utilizar as estruturas de fluxo da linguagem ADVPL para repetir comandos do próprio script HTML (por exemplo, colocar um comando de script HTML dentro de um comando While em ADVPL):

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

<% dbSkip()

EndDo%>

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

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

<b>Esta linha é HTML, mas a data exibida aqui: <%= Time() %> foi obtida em tempo de execução.</b>

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

Utilizando todos esses conceitos, pode-se criar toda uma apliação Web baseada no AP5. Ou seja, o processamento e acesso aos dados fica por conta do AP5 Server, e a interface fica por conta do Browser (utilizando o HTML). Abaixo um exemplo de um relatório de clientes criado utilizando o ADVPL ASP. Para testá-lo basta copiar o código, salvá-lo como WEBREL.APH e compilar o arquivo através do AP5 IDE:

<html><head>

<% //Função para manutenção do ambiente %><%= HTMLProcID(__nProcID) %>

<title>ADVPL ASP DEMO</title></head>

<%#define FIELD_CODDE "FROM_CODE"#define FIELD_CODATE "TO_CODE"#define FIELD_LOCDE "FROM_LOCAL"#define FIELD_LOCATE "TO_LOCAL"

// Criação das variáveis com os parâmetros recebidos através// do array __aProcParms

Local cCodDe,cCodAte,cLocDe,cLocAteLocal nPos

nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_CODDE })If nPos != 0

cCodDe := __aProcParms[nPos,2]


ElsecCodDe := ""

Endif

nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_CODATE })If nPos != 0

cCodAte := __aProcParms[nPos,2]Else

cCodAte := "ZZZZZZ"Endif

nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_LOCDE })If nPos != 0

cLocDe := __aProcParms[nPos,2]Else

cLocDe := ""Endif

nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_LOCATE })If nPos != 0

cLocAte := __aProcParms[nPos,2]Else

cLocAte := "ZZ"Endif

%>

<body topmargin="0" leftmargin="0">

<table border="0" cellpadding="0" cellspacing="0" width="100%"> <tr> <td> <h1 align="left">ADVPL ASP - Demo</h1> </td> </tr> <tr> <td> <hr size="5"> </td> </tr> <tr> <td> <h3 align="left"><u>Relatório de Produtos</u></h3> </td> </tr> <tr> <td> <p align="left"><b>Data de geração</b>: <%=Day(Date())%> de <%=MesExtenso(Date())%> de <%=Year(Date())%></td> </tr> <tr> <td> <hr> </td> </tr></table><div align="center"> <center> <% If Len(__aProcParms) > 0 %>

<table border="1" cellpadding="0" cellspacing="0" width="508" height="24"> <tr> <th width="181" height="24" bgcolor="#008080" align="left"><font

color="#FFFFFF"><b>Parâmetro</b></font></th> <th width="327" height="24" bgcolor="#008080" align="left"><font

color="#FFFFFF"><b>Valor</b></font></th> </tr> <% // "Impressão" dos parâmetros


Local i For i := 1 To Len(__aProcParms) %> <tr> <td width="181" height="24" bgcolor="#FFFFCC"><%= __aProcParms[i,1]

%></td> <td width="327" height="24" bgcolor="#FFFFCC"><%= __aProcParms[i,2]

%></td> </tr> <% Next i %> </table>

<% Else %> <b>Nenhum parâmetro informado.</b> <% Endif %> </center></div><p align="left"> </p>

<% // Abertura dos arquivos e posicionamento do ponteiroIf Select("SB2") == 0 .Or. Select("SB1") == 0

RpcSetEnv ( "99", "01", "", "","","", {"SB1","SB2"} )EndifdbSelectArea("SB1")dbSetOrder(1)dbSeek(xFilial("SB1")+cCodDe+cLocDe,.T.)

%>

<table border="1" cellpadding="0" width="100%" cellspacing="0"> <tr> <th width="12%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Código</b></font></th> <th width="50%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Descrição</b></font></th> <th width="7%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Local</b></font></th> <th width="17%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Quantidade em Estoque</b></font></th> <th width="14%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Custo Médio</b></font></th> </tr> <% While !EOF() .And. xFilial("SB1") == SB1->B1_FILIAL .And. SB1->B1_COD <= cCodAte; .And. SB1->B1_LOCPAD <= cLocAte SB2->(dbSetOrder(1)) SB2->(dbSeek(xFilial("SB2")+SB1->B1_COD+SB1->B1_LOCPAD,.F.)) %> <tr> <td width="12%" bgcolor="#FFFFCC"><%= HTMLAllTrim(SB1->B1_COD) %></td> <td width="50%" bgcolor="#FFFFCC"><%= HTMLAllTrim(SB1->B1_DESC) %></td> <td width="7%" bgcolor="#FFFFCC"><%= HTMLAllTrim(SB2->B2_LOCAL) %></td> <td width="17%" bgcolor="#FFFFCC"><%= SB2->B2_QATU %></td> <td width="14%" bgcolor="#FFFFCC"><%= "R$" + Str(SB2->B2_CM1,8,2) %></td> </tr> <% dbSkip() EndDo %> </table>

</body>


</html>

Após ter o código compilado, pode-se visualizar o resultado acessando através de um Web Browser como o Internet Explorer a seguinte URL:

http://servidor/h_webrel.apl


AP5 Web - Conectividade e AdvPL ASP

Documents

ap5 com

comunicao com o ap5

ap5 os jobs ou

sumrioadvanced protheus

acesso e

o advpl asp

ap5 server enquanto

jobs e