Advanced Protheus - AP5

AP5 Web Conectividade e AdvPL ASP

CopyRight 2000 Microsiga Software S.A.

Advanced Protheus - AP5 Web Conectividade e Advpl ASP Microsiga Software S.A.

CopyRight 2000

Sumrio
Advanced Protheus - AP5...............................................................................................................................................1

AP5 WEB CONECTIVIDADE E ADVPL ASP......................................................................................................1 COPYRIGHT 2000 MICROSIGA SOFTWARE S.A...........................................................................................1 SUMRIO.....................................................................................................................................................................2 AP5 WEB - CONECTIVIDADE.................................................................................................................................3 RPC ENTRE O AP5 E OUTRAS APLICAES..........................................................................................................................4
A API de comunicao com o AP5......................................................................................................................................4 O Controle ActiveX.............................................................................................................................................................9

RPC ATRAVS DA INTERNET...............................................................................................................................................10

O AP5 Server como um servidor Web.....................................................................................................................................10 Servios de FTP.................................................................................................................................................................10 Servios de HTTP..............................................................................................................................................................11 Criando funes APL...............................................................................................................................................................13 Exemplo de funo APL....................................................................................................................................................14 O ADVPL ASP........................................................................................................................................................................16 Caractersticas do ADVPL ASP.........................................................................................................................................16

Advanced Protheus - AP5 Web Conectividade e Advpl ASP Microsiga Software S.A.

CopyRight 2000

AP5 Web - Conectividade

O AP5 Server o centro de funcionamento do Advanced Protheus. o encarregado pelo processamento das aplicaes, gerenciamento das conexes e compilao de programas. E uma de suas principais caractersticas a alta conectividade. Ou seja, o AP5 pode ser integrado a diferentes solues ou sistemas, atravs da utilizao de uma API de acesso (contida em uma DLL) ou um controle ActiveX, ou mesmo diretamente atravs da Web (via protocolo HTTP ou FTP). Isso permite outras aplicaes a terem acesso a execuo de funes (jobs) no AP5, utilizando o conceito de RPC. RPC (Remote Procedure Call) significa Chamada Remota de Procedimentos, ou seja, atravs de uma aplicao externa (ou atravs da Internet) possvel executar no AP5 rotinas criadas em ADVPL. Tais rotinas podero realizar todo o tipo de tarefa desejada, como por exemplo cadastrar um pedido, um cliente, ou emitir um relatrio em formato HTML, retornando informaes aplicao externa. A utilizao da API de acesso e do controle ActiveX mais indicada para aplicaes desenvolvidas em outras linguagens e que necessitem interagir com o AP5. J com o acesso via Internet, possvel criar toda uma aplicao Web que alie o poder de processamento do AP5 com a facilidade de formatao de interface do HTML.

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

RPC Entre o AP5 e Outras Aplicaes

So duas as opes para realizar RPC entre uma aplicao externa e o AP5: Uma API de acesso, utilizando a DLL (Dinamic Link Library) chamada AP5DCONN.DLL; Um controle ActiveX , utilizado atravs do arquivo AP5CONNXCONTROL.OCX. Ambas opes tm as mesmas funcionalidades: Conexo a um ou mais servidores AP5; Acesso a algumas funes gerenciais, como obteno de lista de usurios conectados, envio de mensagens, e gerenciamento das conexes; Execuo de jobs e procs. Os jobs podem ser executados no AP5 sem que necessariamente a aplicao externa aguarde pelo retorno. Podem assim permanecer executando no AP5 Server enquanto a aplicao externa realiza outras tarefas, ou mesmo executa outros jobs. Os procs entretanto, sempre faro com que a aplicao externa aguarde o retorno do AP5; Os jobs ou procs so funes contidas no repositrio do AP5 (incluindo as funes criadas por usurios User Function). A aplicao externa pode, sempre atravs da DLL ou da OCX, enviar parmetros e receber o retorno destas funes, segundo os tipos de dados vlidos: Caracter, numrico, lgico, data e array; A conexo ao AP5 sempre efetuada atravs do protocolo TCP/IP. O acesso ao AP5 Server somente ser efetuado se a correta senha e usurio forem informados. A checagem dessa senha efetuada pelo Advanced, e deve ser mantida atravs do SIGACFG. O usurio informado deve ser o Administrador do sistema ou pertencer ao grupo Administradores; Geralmente a utilizao de uma dessas opes ser indicada para aplicaes 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, necessrio a DLL de comunicao do AP5 chamada AP5CONN.DLL. Por isso, sempre que for necessrio utilizar uma dessas opes, a DLL de comunicao deve estar em um path localizvel pelo Windows e deve estar atualizada em relao ao AP5 Server em que a aplicao externa tentar se conectar.

A API de comunicao com o AP5

Para utilizar a API de comunicao do AP5, necessrio conhecer a linguagem em que a aplicao externa est escrita, a ponto de poder utilizar o conceito de DLLs do Windows. Qualquer linguagem de programao que suportar a utilizao de DLLs poder utilizar a API de comunicao. Diferentemente do controle ActiveX, a DLL de comunicao no pode ser tratada como um objeto, porm podem existir vrias instncias de comunicao, o que permite a comunicao com diferentes servidores do AP5 simultneamente. O processo de utilizao resume-se em: 1. 2. 3. 4. 5. Criao de uma instncia de comunicao; Conexo ao AP5 Server; Utilizao efetiva: Execuo de rotinas, obteno do retorno, etc; Desconexo; Destruio da instncia de comunicao.

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

Para tal, existem as seguintes funes disponibilizadas na DLL de comunicao:

AP5CreateConnControl
Descrio: Parmetros: Criao de uma instncia de comunicao com o AP5 Server. Pode-se criar diferentes instncias de comunicao, acessando um ou mais servidores do AP5. cServer: char * - Nome ou endereo IP do servidor para a conexo; nPort: int - Porta do socket TCP/IP utilizada para a conexo; cEnvironment: char * - Ambiente utilizado para a execuo de processos; cUser: char * - Usurio do sistema para validao da conexo. O usurio informado deve pertencer ao grupo Administradores do sistema; cPassWord: char * - Senha do usurio informado, para validao da conexo. int - Retorna o Handle da instncia criada. Este Handle retornado dever ser informado em todas as demais funes de comunicao, para identificao da instncia que ser utilizada.
nAP5 = AP5CreateConnControl(APSERVER, 1024, ENVIRONMENT, Administrador, )

Retorno: Sintaxe:

AP5DestroyConnControl
Descrio: Destruio de uma instncia de comunicao com o AP5 Server. Aps a utilizao da API, e antes de encerrar a execuo da aplicao externa, necessrio destruir o Handle criado com a funo anterior para a liberao de memria. nObjectID: int - Handle da instncia criada com a funo anterior. bool - Retorna verdadeiro ou falso, indicando a execuo com sucesso da funo.
lOk = AP5DestroyConnControl(nAP5)

Parmetros: Retorno: Sintaxe:

AP5Connect
Descrio: Conexo a um AP5 Server. Esta funo no deve ser confundida com a funo AP5CreateConnControl. Esta funo ir realizar a conexo com o AP5 Server indicado durante a criao da instncia informada como parmetro. nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. atravs do Handle que definido em qual servidor, porta e ambiente os processos sero executados. bool - Retorna verdadeiro ou falso, indicando se a conexo foi efetuada com sucesso.
lOk = AP5Connect(nAP5)

Parmetros: Retorno: Sintaxe:

AP5Disconnect
Descrio: Desconexo de um AP5 Server. Esta funo no deve ser confundida com a funo AP5DestroyConnControl. Esta funo ir encerrar a conexo ativa com um AP5 Server, da instncia informada como parmetro. nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. Sem retorno.
AP5Disconnect(nAP5)

Parmetros: Retorno: Sintaxe:

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

AddNullParam, AddNumericParam, AddStringParam, AddLogicalParam, AddDateParamAsDouble, AddDateParamAsString, AddArrayParam

Descrio: Estas funes so utilizadas para a execuo de processos em um servidor AP5. Podem ser utilizadas somente aps uma conexo ser ativada. Um processo executado em um servidor AP5 pode necessitar de parmetros, que devero ser enviados ao servidor antes da execuo do processo atravs da utilizao destas funes. Os tipos de dados que podem ser enviados so: Numrico (int), Caracter (char *), Lgico (bool), Data (enviado como caracter char * - ou como numrico - int) e Array (variant). nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. atravs do Handle que definido para qual servidor o parmetro ser enviado; xParametro: indefinido - O tipo de dado do parmetro depender da funo utilizada, segundo os tipos de dados permitidos explicados acima. bool - Retorna verdadeiro ou falso, indicando se o parmetro pde ser enviado ao AP5 Server com sucesso.
lOk = AddNumericParam(nAP5,5) ou lOk = AddStringParam(nAP5,TEXTO) ou lOk = AddLogicalParam(nAP5,true)

Parmetros:

Retorno: Sintaxe:

ResultAsNumeric, ResultAsString, ResultAsLogical, ResultAsDate, ResultAsDateString, ResultAsArray

Descrio: Parmetros: Estas funes so utilizadas para obter o retorno do AP5 Server aps a execuo de um processo. nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo. Apenas para as funes ResultAsString e ResultAsDateString: cBuffer: char * - Buffer de caracteres alocado para receber o retorno em formato caracter; nSize: int - Tamanho do buffer passado no parmetro anterior. O tipo de dado do retorno depender da funo utilizada, segundo os tipos de dados definidos anteriormente. Para as funes ResultAsString e ResultAsDateString o retorno ser o tamanho do buffer preenchido.
nRet = ResultAsNumeric(nAP5) ou lRet = ResultAsLogical(nAP5) ou ResultAsString(nAP5,cBuffer,nSize)

Retorno:

Sintaxe:

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

AP5BuildNumber
Descrio: Parmetros: Funo utilizada para obter o nmero do build de compilao da API de conexo ao AP5. nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo; cBuild: char * - Buffer de caracteres para receber o nmero do build; nSize: int - Tamanho do buffer passado no segundo parmetro. int - Retorna o tamanho do buffer contendo o nmero do build.
AP5BuildNumber(nAP5,cBuffer,nSize)

Retorno: Sintaxe:

PrepareEnv
Descrio: Funo utilizada para preparar o ambiente do sistema, ou seja, abrir arquivos, criar variveis, e tornar o ambiente de execuo da aplicao externa em relao ao AP5 Server, o mais parecido possvel com o que realizado pelos mdulos do sistema. nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo; cEnv: char * - Ambiente que ser utilizado para a abertura dos arquivos; cEmp: char * - Cdigo da empresa do sistema (dois dgitos) que dever ser aberta; cFil: char * - Cdigo da filial que ser utilizada (dois dgitos); aTables: variant Este parmetro deve ser um array variant (para detalhes, consulte a documentao da linguagem utilizada) contendo as siglas das tables que devero ser abertas (por exemplo SB1). bool - Retorna verdadeiro ou falso, indicando o sucesso da execuo da funo.
PrepareEnv(nAP5,ENVIRONMENMT,99,01,aTables)

Parmetros:

Retorno: Sintaxe:

StartJob
Descrio: Esta funo permite a execuo de um processo (job) em um AP5 Server. O processo executado pode ser qualquer um dos existentes no repositrio definido pelo ambiente informado, incluindo as funes criadas pelo usurio (User Function). Pode tambm receber parmetros, bem como retornar um valor para a aplicao externa, sempre utilizando-se das funes descritas anteriormente. A execuo de um processo resume-se em: A) 1. Enviar os parmetros (se existirem); 2. Executar o processo e aguardar sua finalizao; 3. Obter o resultado (se existir). B) 1. Enviar os parmetros (se existirem); 2. Executar o processo sem aguardar sua finalizao; Os processos so executados em threads de execuo separadas. Isso permite aplicao externa que esteja utilizando a API, optar por executar o processo e continuar trabalhando enquanto o mesmo est em execuo. Porm, somente poder obter um retorno quando esperar at que o processo termine de ser executado. Obs.: Como estes processos so executados sem que uma instncia do AP5 Remote esteja ativa, devem ser criados sem nenhum comando de interface (criao de janelas, comandos de alerta, help, etc). Se um comando de interface for utilizado no cdigo ADVPL de um processo, a execuo deste atravs da API gerar um erro de execuo. Advanced Protheus - AP5 Conectividade e Advpl ASP CopyRight 2000 Release A Microsiga Software S.A. 7

Parmetros:

nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo; cEnv: char * - Ambiente que ser utilizado para a execuo do processo; cFunc: char * - Nome do processo ou funo que ser executado no AP5 Server; lWait: bool - Verdadeiro ou Falso indicando se a aplicao externa dever ou no aguardar pelo trmino da execuo do processo. bool - Retorna verdadeiro ou falso, indicando se o processo foi iniciado com sucesso.
StartJob(nAP5,ENVIRONMENMT,MESEXTENSO,true)

Retorno: Sintaxe:

CallProc
Descrio: Esta funo tem o mesmo objetivo que a anterior, porm sempre aguardar o trmino do processo para que o controle volte aplicao externa, e tem algumas diferenas conceituais: A) No se pode escolher o ambiente no qual o processo ser executado. Os processos executados pela CallProc sero sempre executados no ambiente indicado na criao da instncia com a funo AP5CreateConnControl; B) Um processo executado atravs da funo StartJob, comear de um ambiente totalmente novo. Porm, os processos executados pela funo CallProc mantm o ambiente da ltima execuo. Assim, o valor de variveis criadas, os arquivos abertos, etc, so mantidos na prxima execuo. nObjectID: int - Handle da instncia que ser utilizada para a execuo desta funo; cFunc: char * - Nome do processo ou funo que ser executado no AP5 Server. Bool - Retorna verdadeiro ou falso, indicando se o processo foi finalizado com sucesso.
CallProc(nAP5,CALCEST)

Parmetros: Retorno: Sintaxe:

Com a utilizao da API, pode-se criar toda uma aplicao, em Visual Basic por exemplo, que executar funes do sistema Advanced como o usurio faria atravs do AP5 Remote:
Dim nAP5 As Integer Dim cRes As String nAP5 = AP5CreateConnControl(APSERVER, 1024, ENVIRONMENT, Administrador, ) If AP5Connect(nAP5) Then AddNumericParam(nAP5,5) lOk = CallProc(nAP5,MESEXTENSO) If lOk Then ResultAsString(nAP5,cRes) Else CRes = No foi possvel obter o ms por extenso End if AP5Disconnect(nAP5) End if AP5DestroyConnControl(nAP5)

Importante: A notao dos tipos de dados e da sintaxe mencionados na descrio das funes segue o padro de linguagens como a linguagem C. Deve-se considerar os exemplos de sintaxe conforme a linguagem utilizada. Todas as funes 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 parmetro para a funo chamada. A aplicao externa tambm ser responsvel por liberar a memria do buffer alocado. Advanced Protheus - AP5 Conectividade e Advpl ASP CopyRight 2000 Release A Microsiga Software S.A. 8

O Controle ActiveX
O controle ActiveX tem as mesmas funcionalidades da API. Porm o formato de utilizao diferenciado. O controle ActiveX um objeto que deve ser registrado no computador onde ser utilizado e durante a execuo da aplicao externa, dever ser criado, utilizado e destruido ao final. Para maiores detalhes, consulte a documentao da linguagem utilizada ou a documentao do conceito ActiveX na pgina da Microsoft (http://www.microsoft.com).

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

RPC atravs da Internet

O RPC atravs da Internet realizado diretamente com o AP5 Server utilizando o protocolo HTTP. Isto significa que possvel criar pginas 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 atravs do protocolo HTTP. Neste ltimo caso possvel tambm utilizar uma conexo direta TCP/IP (via socket). Para realizar o RPC utilizando o protocolo HTTP diretamente com o AP5 Server, no necessrio a utilizao de um servidor Web de terceiros, pois o AP5 Server tambm 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 requisies 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 prpria Intranet num ambiente de rede local, ou publicar o endereo IP da mquina com o AP5 Server na Internet e executar funes atravs de RPC ou simplesmente criar o seu prprio Web Site com pginas HTML estticas e/ou dinmicas.

Servios de FTP
O protocolo FTP (File Transfer Protocol) permite a transferncia de arquivos entre um servidor e uma aplicao client de FTP (com um Web Browser como o Internet Explorer, por exemplo). Utilizando o AP5 Server como um servidor FTP, os usurios podero remotamente baixar arquivos disponibilizados em um diretrio configurvel no servidor. Pode-se tambm habilitar um recurso de auto-atualizao para o AP5 Remote, que ir automaticamente baixar arquivos compactados para se auto atualizar quando necessrio. Para habilitar o servio de FTP no AP5 Server, o seguinte grupo deve ser criado no arquivo de configuraes (AP5SRV.INI): [FTP] Enable=1 Path=C:\AP5\FTP Port=21 Onde as chaves so: - Enable indica se habilita ou desabilita este servio; - Path indica o diretrio onde o AP5 Server localizar os arquivos para disponibilizar no FTP; - Port a porta usada para conexo das aplicao client. Figura 1 - Internet Explorer 5 acessando a rea de FTP do AP5 Server O recurso de auto-atualizao encontrado no AP5 Remote funciona atravs da deteco de diferenas na verso das DLLs locais (ou seja, que se encontram juntamente com o executvel do AP5 Remote). Quando isto ocorre, o usurio questionado sobre a execuo da auto-atualizao. Se tudo estiver corretamente configurado no arquivo de configurao do AP5 Remote (AP5RMT.INI para maiores detalhes, consulte a documentao do AP5 Remote), ao escolher que deseja tentar uma auto-atualizao, o AP5 Remote ir abrir uma conexo FTP com o Server configurado e baixar os arquivos compactados (com a extenso .CAB) contendo as DLLs e executveis mais atualizados. Os arquivos sero ento descompactados localmente para a atualizao. Advanced Protheus - AP5 Conectividade e Advpl ASP 10 CopyRight 2000 Release A Microsiga Software S.A.

Servios de HTTP
O protocolo HTTP (HyperText Transmission Protocol) o protocolo utilizado na comunicao entre um servidor e um Web Browser. o protocolo utilizado para o envio e recebimento de pginas formatadas em padres SGML (HTML,XML, etc). Este protocolo se baseia principalmente em dois comandos: GET e POST. O comando GET utilizado para obter alguma informao do servidor HTTP e o POST para postar informaes para o servidor. Mais adiante, ser mais fcil compreender onde tais comandos so utilizados no AP5 Server. Utilizando o AP5 Server como um servidor HTTP, o mesmo poder ser acessado atravs de um Web Browser como o Internet Explorer por exemplo, que receber as pginas HTML enviadas de um diretrio configurado no servidor. Adicionalmente ao envio e recebimento de pginas estticas formatadas, pode-se utilizar a linguagem Advpl do AP5 para processar pginas mistas, que contm cdigo Advpl e comandos HTML de formatao. Tais pginas sero processadas no AP5 Server, e ento enviadar para o Web Browser, que ir format-las de acordo com os comandos HTML contidos. Tambm possvel executar diretamente funes compiladas no repositrio do AP5, atravs de um request HTTP (por exemplo, atravs de um POST em um formulrio em Figura 2 - Internet Explorer 5 acessando o AP5 Server como um HTML, ou de um link, ou mesmo servidor HTTP diretamente na linha de URL do Web Browser. O mesmo vale para qualquer outra aplicao que seja capaz de efetuar comandos GET ou POST utilizando o protocolo HTTP). Para habilitar o servio de HTTP no AP5 Server, os seguintes grupos devem ser criados no arquivo de configuraes (AP5SRV.INI): [HTTP] Enable=1 Path=C:\AP5\HTTP RPCServer=SERVERKEY RPCEnv=ENVIRONMENT RpcTimeOut=40 Port=1234 GetProc=<funo> PostProc=<funo> [SERVERKEY] TYPE=TCPIP Server=172.16.1.1 Port=5024 Onde as chaves so: Grupo HTTP - Enable indica se habilita/desabilita o servio; - Path indica o diretrio 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 configuraes do AP5 Server onde sero executadas as chamadas de funes Advpl atravs de RPC (por requests HTTP); - RPCEnv indica o nome do grupo que contm as configuraes de ambiente para a execuo das funes requisitadas em RPC; - RPCTimeOut indica o tempo em segundos que a thread de execuo RPC permanecer no ar (e conseqentemente com todo o ambiente preparado para ser utilizado em uma prxima execuo de RPC via HTTP); - Port a porta utilizada para a conexo dos Web Browsers;

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

- GetProc e PostProc so parmetros 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 funo informada executada e receber um parmetro com o nome da pgina, arquivo ou funo, originalmente requisitado. Grupo <SERVIDOR> (no exemplo, SERVERKEY) - TYPE indica o tipo de conexo 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 endereo IP do servidor encarregado da execuo das rotinas em Advpl (RPC). Note que estes servidor no precisa necessariamente ser um servidor diferente do utilizado para responder aos requests HTTP (aquele que trabalha como Web Server); - Port a porta utilizada para conexo ao Servidor RPC.

Quando uma URL requisitada atravs de um Web Browser (seja atravs de um comando POST, um link ou diretamente atravs do campo de URL do Browser), essa requisio recebida pelo AP5 Server que a tratar do seguinte modo:

Extenso do Descrio arquivo

Nenhuma Um endereo http nico, sem um nome de arquivo definido. Pginas HTML, arquivos texto, arquivos de imagem, som, vdeo, etc. uma chamada direta a uma funo do repositrio do AP5.

O que acontece
Ao chamar um endereo 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. A pgina HTML, ou qualquer que seja o arquivo, ser simplesmente enviado ao Web Browser, sendo que este o responsvel pela sua traduo/interpretao. Quando o AP5 Server receber um request deste tipo, a funo chamada (no exemplo func.apl, a funo chamada func, sem a extenso) ser executada no AP5 Server configurado na chave RPCSERVER no ambiente definido pela chave RPCENV. O que dever ser retornado pela funo uma string, que ser enviada para o Web Browser. Uma pgina Advpl ASP uma pgina HTML contendo cdigo interpretvel no servidor. Tais pginas so criadas utilizando qualquer editor de texto ou editor HTML, e devem ter SEMPRE a extenso .APH. Devem ser compiladas atravs do AP5 IDE. Durante a compilao, o AP5 Server transforma essa pgina em uma funo interna que ser executada da mesma maneira que aquelas chamadas .APL explicadas anteriormente. Como tambm so funes, as pginas em Advpl ASP devem ser chamadas do Web Browser com a extenso .APL exatamente como explicado anteriormente.

Exemplo
http://servidor/

.HTM;.HTML ou outra extenso qualquer. .APL

http://servidor/cadastro.htm ou http://servidor/imagem.gif http://servidor/acerto.apl ou http://servidor/runprog.apl

.APH

uma chamada para uma pgina ativa (uma pgina em ADVPL ASP).

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

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

Criando funes APL

A princpio, todas as funes contidas no repositrio podem ser executadas diretamente atravs de uma requisio HTTP ao AP5 Server. Porm, alguns detalhes devem ser considerados: Uma funo executada no momento do recebimento de uma requisio HTTP executada como um JOB, ou seja, no contem interface. Por isso, tais funes no podem conter comandos de interface, como criao de janelas ou exibio de helps e mensagens de alerta; A nica interface possvel a utilizada no client HTTP. Por isso, tais funes devem SEMPRE retornar uma string de caracteres. Aps o processamento da funo, essa string de retorno ser enviada diretamente ao client HTTP e este ser o responsvel por sua interpretao. Por exemplo, utilizando um Web Browser como client pode-se retornar a string de comandos HTML diretamente. O HTML ento ser propriamente exibido no Web Browser; Qualquer retorno diferente de uma string de caracteres gerar um erro que ser enviado aplicao client HTTP (o erro gerado Invalid Proc Return); O AP5 Server passa alguns parmetros para as funes chamadas. Isso significa que ao criar funes para serem utilizadas em resposta s requisies HTTP, deve-se criar o cabealho da funo com estes parmetros. No obrigatrio utilizar os mesmos nomes de parmetros sugeridos abaixo quando criar diretamente estas funes. Porm, como so esses os nomes utilizados no ADVPL ASP explicado mas a frente, aconselhvel utiliz-los por motivo de padronizao: - __aCookies: Este parmetro recebe um array bidimensional com os Cookies criados na aplicao client HTTP (por exemplo, no Internet Explorer 5). Pode-se utiliz-lo para checar validaes mantidas nas mquinas client por exemplo. Para maiores detalhes, consulte a documentao do HTML ou do Web Browser utilizado. __aPostParms: Este parmetro recebe um array bidimensional com os campos contidos em um formulrio HTML recebido atravs de um comando POST. Cada item deste array contm um array com o nome do campo e o valor informado. Por exemplo, para um formulrio com dois campos para digitao (um chamado nome e o outro chamado endereco), que enviam os dados para a funo cadastro.apl atravs de um POST, a funo receber o array __aPostParms da seguinte forma: { {nome, NOME DIGITADO NA PAGINA HTML}, {endereco, ENDERECO DIGITADO NA PAGINA HTML} } A funo pode tratar os dados recebidos neste array para realizar um processamento especfico com tais informaes. Para campos onde no possvel a entrada de dados e sim a escolha de uma informao pr-definida (como por exemplo um checkbox), o item somente existir no array caso o campo tenha sido selecionado no formulrio HTML (por exemplo, se o checkbox for marcado). __nProcID: Contm o Handle da Thread de execuo daquela funo. A utilizao deste parmetro ser explicada juntamente com o tpico ADVPL ASP posteriormente; __aProcParms: Este parmetro recebe um array bidimensional com os parmetros enviados na linha de URL do Web Browser. Por exemplo, na execuo de uma funo via linha de URL do Web Browser como: http://servidor/vende.apl?cod=000001&nome=PRODUTO DE TESTE&quant=20 a funo chamada vende receber o array __aProcParms da seguinte forma: { {cod, 000001}, {nome, PRODUTO DE TESTE}, {quant, 20}

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

} A funo pode tratar estes dados recebidos para realizar processamentos especficos. muito til tambm para criar links de execuo diretamente atravs de um Web Browser. __cHTTPPage: Esse parmetro recebe o nome da pgina, arquivo ou funo originalmente requisitada para o AP5 Server. utilizado quando as chaves GETPROC e POSTPROC (explicadas anteriormente) so habilitadas no arquivo de configuraes do AP5 Server. A funo configurada ir receber nesse parmetro o nome original requisitado e poder executar algum processamento especfico para continuar o processo (retornando a prpria funo original) ou desviar para outra pgina, por exemplo.

Exemplo de funo APL

A funo a seguir um bom exemplo para ser executado atravs de um Web Browser como o Internet Explorer ou o Netscape Navigator. Ela retorna uma string contendo a pgina HTML onde est escrita a mensagem Hello World e a lista de parmetros passados na linha de URL. Para test-la, crie um arquivo novo no AP5 IDE, cole o cdigo abaixo e salve o arquivo como WEBDEMO.PRW. Aps 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 Cdigo da funo:
#include "rwmake.ch" User Function WebDemo(__aCookies,__aPostParms,__nProcID,__aProcParms,__cHTTPPage) Local cHTML := "" Local i // Coloca uma mensagem em HTML cHTML += '<p><h1 align="center">Hello World!!!</h1></p>' // Coloca um separador de linha em HTML cHTML += '<hr>' If Len(__aProcParms) = 0 cHTML += '<p>Nenhum parmetro informado na linha de URL.' Else For i := 1 To Len(__aProcParms) cHTML += '<p>Parmetro: ' + __aProcParms[i,1] + ' __aProcParms[i,2] + '</p>' Next i Endif Return(cHTML) Valor: ' +

Para crias as funes que sero utilizadas em chamadas via um Web Browser, ou seja, em qualquer request HTTP, deve-se seguir o procedimento normal de criao de funes no AP5: utilizando o AP5 IDE para a edio e para a compilao. Note que no caso de funes do usurio (User Function) o nome chamado na URL do Browser tambm dever conter o U_ no comeo da funo, por exemplo: http://servidor/u_webrelato.apl E deve-se sempre indicar a extenso .APL para que o AP5 Server identifique que uma funo a ser executada. Advanced Protheus - AP5 Conectividade e Advpl ASP 14 CopyRight 2000 Release A Microsiga Software S.A.

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

O ADVPL ASP
Uma pgina ASP (Active Server Pages) uma pgina HTML contendo cdigo interpretvel em uma linguagem compreensvel ao servidor HTTP em uso. Por exemplo, o IIS da Microsoft utiliza o VBScript para criar suas pginas ASP, do mesmo modo que o AP5 utiliza o ADVPL. Uma pgina ASP uma combinao de script HTML e cdigo interpretvel. No ADVPL ASP esse cdigo padro xBase, portanto a preocupao maior daqueles que j conhecem e trabalham com o AP5 e desejam desenvolver pginas ativas para aplicaes Web utilizando essa facilidade conhecer HTML.

Caractersticas do ADVPL ASP

Os arquivos ADVPL ASP tm a extenso padro .APH. So arquivos texto e devem ser adicionados a um projeto no AP5 IDE e compilados da mesma maneira que os programas tradicionais. A diferena que o AP5 Server identificar que se trata de um ADVPL ASP e executar uma espcie de tradutor (parser) antes que a compilao seja executada. Este parser ir transformar todo o arquivo em uma funo nica, que receber os mesmos parmetros das funes APL simples, como explicado anteriormente, e retornar uma string. O desenvolvedor no precisa se preocupar em retornar HTML algum, pois o APH tambm um arquivo HTML. A funo que foi gerada na compilao ir se encarregar de retornar o HTML contido no arquivo, depois que o cdigo foi processado. Por se tornar uma funo no momento da compilao, no possvel utilizar a clusula FUNCTION para criar outras funes dentro de um arquivo APH. Caso exista essa necessidade, tais funes devem ser criadas em um arquivo PRW tradicional e chamadas de dentro do APH. Do mesmo modo que as demais funes, o arquivo APH tambm deve ser executado (atravs da URL do Browser, por exemplo) com a extenso .APL. A extenso APH para o nome dos arquivos obrigatria. Qualquer outra extenso usada no nome do arquivo no ser reconhecida e o parser no ser executado antes da compilao. Assim como outros ASPs, a diferenciao entre script HTML e cdigo efetuada atravs dos caracteres <% para indicao de abertura de cdigo e %> para indicao do encerramento de cdigo. Por exemplo, o HTML abaixo contm um pedao de cdigo 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 nmeros Local i, nSoma := 0 For i := 1 To 100 NSoma += i Next i %> </body> </html>

Quando este arquivo for requisitado ao AP5 Server (atravs de uma chamada em URL por exemplo) o cdigo entre os delimitadores ser executado, porm o script colocado ao redor do cdigo ser mantido exatamente como se encontra. Advanced Protheus - AP5 Conectividade e Advpl ASP 16 CopyRight 2000 Release A Microsiga Software S.A.

A grande vantagem de se criar arquivos ADVPL ASP em relao a criar funes APL simples, decorre do fato de que no necessrio conhecer to profundamente HTML e que nas funes APL simples o desenvolvedor deve se preocupar em retornar todo o HTML necessrio para a correta exibio no Web Browser. E tambm, como o ADVPL ASP mistura o script HTML com o cdigo interpretvel, pode-se criar um arquivo APH utilizando o editor desejado (como o Microsoft FrontPage por exemplo) e inserir o cdigo necessrio entre o script. Outro detalhe importante que pode-se utilizar as estruturas de fluxo da linguagem ADVPL para repetir comandos do prprio 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 tambm pode existir diferentes blocos de cdigo interpretvel separados pelos delimitadores, dentro de um mesmo arquivo. To importante quanto mesclar cdigo interpretvel com script de formatao HTML, utilizar os comandos ADVPL para alterar o script de formatao. Ou seja, colocar o contedo de variveis, campos, etc, diretamente no HTML que ser enviado aplicao client (ao Browser por exemplo). Isso pode ser realizado atravs dos delimitadores de avaliao. Os delimitadores de avaliao so <%= para abertura e %> para encerramento. Diferentemente dos delimitadores de cdigo interpretvel, estes devem sempre estar na mesma linha. Com eles pode-se criar uma linha de script HTML, cujo contedo contm uma expresso que ser avaliada em tempo de execuo: <b>Esta linha HTML, mas a data exibida aqui: <%= Time() %> foi obtida em tempo de execuo.</b> No exemplo acima, a linha HTML ser retornada para o Browser com o resultado da funo time (ou seja, a hora atual no servidor) inserido no texto. Utilizando todos esses conceitos, pode-se criar toda uma apliao 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 relatrio de clientes criado utilizando o ADVPL ASP. Para test-lo basta copiar o cdigo, salv-lo como WEBREL.APH e compilar o arquivo atravs do AP5 IDE:
<html> <head> <% //Funo para manuteno do ambiente %> <%= HTMLProcID(__nProcID) %> <title>ADVPL ASP DEMO</title> </head> <% #define #define #define #define FIELD_CODDE FIELD_CODATE FIELD_LOCDE FIELD_LOCATE "FROM_CODE" "TO_CODE" "FROM_LOCAL" "TO_LOCAL"

// Criao das variveis com os parmetros recebidos atravs // do array __aProcParms Local cCodDe,cCodAte,cLocDe,cLocAte Local nPos nPos := aScan(__aProcParms,{|x| Upper(AllTrim(x[1])) == FIELD_CODDE }) If nPos != 0 cCodDe := __aProcParms[nPos,2]

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

Else Endif

cCodDe := ""

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>Relatrio de Produtos</u></h3> </td> </tr> <tr> <td> <p align="left"><b>Data de gerao</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>Parmetro</b></font></th> <th width="327" height="24" bgcolor="#008080" align="left"><font color="#FFFFFF"><b>Valor</b></font></th> </tr> <% // "Impresso" dos parmetros

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

Local i For i := 1 To Len(__aProcParms) %> %></td> %></td> </tr> <% Next i %> </table> <% Else %> <b>Nenhum parmetro informado.</b> <% Endif %> </center> </div> <p align="left">&nbsp;</p> <% // Abertura dos arquivos e posicionamento do ponteiro If Select("SB2") == 0 .Or. Select("SB1") == 0 RpcSetEnv ( "99", "01", "", "","","", {"SB1","SB2"} ) Endif dbSelectArea("SB1") dbSetOrder(1) dbSeek(xFilial("SB1")+cCodDe+cLocDe,.T.) <tr> <td width="181" height="24" bgcolor="#FFFFCC"><%= __aProcParms[i,1] <td width="327" height="24" bgcolor="#FFFFCC"><%= __aProcParms[i,2]

%> <table border="1" cellpadding="0" width="100%" cellspacing="0"> <tr> <th width="12%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Cdigo</b></font></th> <th width="50%" align="left" bgcolor="#336699"><font color="#FFFFFF"><b>Descrio</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 Mdio</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%" <td width="50%" <td width="7%" <td width="17%" <td width="14%" </tr> EndDo %> </table> </body> dbSkip() bgcolor="#FFFFCC"><%= bgcolor="#FFFFCC"><%= bgcolor="#FFFFCC"><%= bgcolor="#FFFFCC"><%= bgcolor="#FFFFCC"><%= HTMLAllTrim(SB1->B1_COD) HTMLAllTrim(SB1->B1_DESC) HTMLAllTrim(SB2->B2_LOCAL) SB2->B2_QATU "R$" + Str(SB2->B2_CM1,8,2) %></td> %></td> %></td> %></td> %></td>

%>

<%

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

</html>

Aps ter o cdigo compilado, pode-se visualizar o resultado acessando atravs de um Web Browser como o Internet Explorer a seguinte URL: http://servidor/h_webrel.apl

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