Treinamento ADVPL ASP - Webservice

Curso de Introdução a Plataforma ADVPL/ASP e Webservice

Aprenda de uma forma simples ,objetiva e direta os principais conceitos do ADVPL/ASP e WebService. O curso apresenta o ADVPL/ASP, a linguagem utilizado produzida para o desenvolvimento de aplicações baseadas na Web. Além de apresentar os principais conceitos Webservice incluindo exemplos de Montagem de um Cliente em Protheus.

Curso de Introdução a Plataforma ADVPL/ASP – WebService 1

"Essa mensagem é destinada exclusivamente ao seu destinatário e pode conter informações confidenciais, protegidas por sigilo profissional ou cuja divulgação seja proibida por lei. O uso não autorizado de tais informações é proibido e está sujeito às penalidades cabíveis."

Índice Analítico

Capítulo 1 – Arquitetura da ADVPL ASP ..................................................... 4Introdução ........................................................................................................4Repositório de Objetos......................................................................................4APO (Advanced Protheus Object)................................................................…..4Representação gráfica do processamento........................................................5Ferramentas de Produção.................................................................................6

Capítulo 2 – Variáveis......................................................................................7Introdução .........................................................................................................7Nomenclatura das Variáveis .............................................................................7Declarando Variáveis ........................................................................................7Operadores .......................................................................................................8

Capítulo 3 – Estrutura da ADVPL ASP..........................................................09Introdução …………….………….......................................................................09Exemplo ...........................................................................................................09

Capítulo 4 – Estruturas de Controle ............................................................11Instrução if .. then .. else ..elseif .....………………………………………….......11Instrução Do case ...........................................................................................15Loops............................……………………….…………………………….…......15

Capítulo 5 – Recuperando Dados enviados por Post e Get ......................16Recuperando Dados com Metódo POST ................................……………......16Recuperando Dados com Metódo GET ..........................................................18

Capítulo 6 – Acessando Base de Dados.....................................................22Introdução ......................................................................................................22Inserindo dados em uma tabela......................................................................24

Capítulo 7 – Web Services em ADVPL - CLIENT .......................................28Introdução ......................................................................................................28Termos Técnicos ...........................................................................................28



Definição do Serviço em Advpl - Client .........................................................29Passos para a utilização do Fonte - Client ....................................................29Passo 1 : Determinar como obter o WSDL do serviço desejado...................30Passo 2 : Gerar o Fonte AdvPl do Client usando o Assistente do IDE .........31Passo 3 : Criar um fonte para a obtenção do horário ...................................34 Passo 4 : Executar o programa de testes......................................................35Passo 5 : Obter informações de “debug”........................................................36Web Services Client – Codigos de Erro.........................................................38

Capítulo 8 – Web Services em ADVPL - SERVER ....................................48Introdução .....................................................................................................48Termos Técnicos ..........................................................................................48Definição do Serviço em Advpl - Server .......................................................49Declaração de um Web Service – SERVER em Advpl.................................50Regras para Nomenclatura dos Serviços / Estruturas / Dados e Métodos...51Nomenclatura dos Serviços...........................................................................51Nomenclatura de Estruturas..........................................................................51Nomenclatura de Dados ( Campos ) ............................................................51Tipos de Dados Básicos................................................................................52Métodos ( Ações ) ........................................................................................53Publicando um WEB Service no Protheus - Configuração...........................53Web Services – Ponto de Entrada WSSTART.............................................55



Capítulo 1 - Arquitetura da ADVPL ASP

Introdução

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

Uma característica fundamental da ADVPL ASP é que o script é executado no servidor, protegendo totalmente a propriedade intelectual e também eliminando o trabalho do programador de se preocupar com qual browser o usuário estaria utilizando para visualizar as páginas, devido a incompatibilidade. Outra caracteristica é o processamento do lado do servidor.

Repositório de Objetos

O repositório do AP7 é um conjunto de Objetos ADVPL ASP (APOs) compilado de acordo com a Environment definida no AP7 IDE que podem ser utilizados a qualquer momento de uma aplicação.

APO (Advanced Protheus Object)

O APO é conhecido como um Objeto ou um programa ADVPL. Um conjunto de APOs formam um repositório que estão armazenados dentro do AP7 Web Server conforme descrito anteriormente.



RepositórioAPOs

.aph

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

Representação gráfica do processamento.

A seguir dispomos os vários comportamento ou resposta do AP7 Server para cada tipo de solicitação.

Extensão do arquivo

Descrição O que aconteceExemplo

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

Ao chamar um endereço URL sem informar arquivo nenhum, o AP7 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

.APW É uma chamada direta a uma função do repositório do AP7.

Quando o AP7 Server receber um request deste tipo, a função chamada (no exemplo func.apw, a função chamada é func, sem a extensão) será executada no AP7 Server configurado na chave [nome_do_server].O que deverá ser retornado pela função é uma string, que será enviada para o Web Browser.

http://servidor/acerto.apwouhttp://servidor/runprog.apw

.APH É uma chamada Uma página Advpl ASP é uma página http://servidor/



Resposta HTML

Solicitação func.APW Cliente

APOs(repositório)

AP7Web Server

http://servidor/

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

HTML mesclada com código executável ou interpretável no server. 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 AP7 IDE. Durante a compilação, o AP7 Server transforma essa página em uma função interna que será executada da mesma maneira que aquelas chamadas .apw explicadas anteriormente.Como são funções também, as páginas em Advpl ASP devem ser chamadas do Web Browser com a extensão .apw

activep.apwouhttp://servidor/cadastro.apw

Ferramentas de Produção

Para aculturar-se em ADVPL ASP é fundamental ter conhecimento em HTML, pois uma página sempre haverá código ADVPL ASP mesclado com HTML.

Os arquivos que contém o código para gerar as páginas de seu site são arquivos texto, portanto, você pode utilizar qualquer editor de texto do mercado.

Utilizaremos o AP7 IDE para escrever nossos códigos ADVPL ASP com HTML, porem utilizaremos também uma ferramenta que nos auxilie no HTML. Existem várias no mercado, mas as mais familiares são Dreamweaver da Macromedia, FrontPage e o Visual Studio da Microsoft entre outros .

Capítulo 2 - Variáveis

Introdução

Variáveis é um espaço temporário na memória RAM que pode ser manipulado.



Nomenclatura das variáveis

No Hypersite seguimos uma padronização de nomenclaturas para facilitar o entendimento dos complexos scripts.

nXXXX = variável Numeric (númerico). Quando você se deparar com uma variável que possui o prefixo n significa que o conteúdo dela é um valor númerico. Ex.: nVLUN = 100

dXXXX = variável Date (data). Quando você se deparar com uma variável que possui o prefixo d significa que o conteúdo dela é uma data. Ex.: dDTPG = 14/08/2000 cXXXX = variável Char ou String (texto). Quando você se deparar com uma variável que possui o prefixo c significa que o conteúdo dela é um texto. Ex.: cDTPG = Makira lXXXX = variável logic (lógico). Quando você se deparar com uma variável que possui o prefixo l significa que o conteúdo dela é um valor lógico (verdadeiro ou falso). Ex.: lATIVO = F

Declarando variáveis

A declaração das variáveis é obrigatório na ADVPL ASP. Há dois tipos de variáveis a Local e a Private.

Utiliza-se uma variável Public quando há necessidade de armazenar o conteúdo dela durante toda a navegação do usuário dentro do site, ao contrário da Local que é utilizada momentaneamente.

Operadores

Operador Descrição= Comparação (igual)= = Comparação (exatamente igual):= Atribuição!= ou <> Diferente



Capítulo 3 – Estrutura da ADVPL ASP

Introdução

Todas as páginas escritas deverão ser referenciadas a um programa APL seguindo sempre a mesma nomenclatura. A seguir temos a estrutura de um arquivo APW.



Exemplo

Montaremos a seguir um programa fonte simples que retorna a Data do sistema. Ele terá o nome de RetDate, a chamada no browser deve ser http://nome_do_server/u_RetDate.apw. Abaixo damos a descrição de cada parte da chama.

Endereço do Server: http://nome_do server. Informa o endereço do server onde esta compilada a página. Por default o server esta na porta 80 portanto não é necessário informar a porta, caso contrario a porta deveria ser informa com : (dois pontos) e o número da porta após o nome do serve. Ex.: http://nome do_server:82/u_RetDate.apw

Programa: U_RetDate.apwNomenclatura do nome :U_nnnnnnn.apw

U_ : Informa que que uma User Function (Função de Usuário). W_ (Web Function) e (Function) são exclusiva para o desenvolvimento interno da Microsiga Software S\A. Portanto clientes não conseguiram compilar Web Function e Function, somente User Function.

nnnnnnn: nome da Função.apw: extensão de uma página ADVPL ASP

#INCLUDE "PROTHEUS.CH" //Include obrigatório#INCLUDE "APWEBSRV.CH" //Include obrigatório #INCLUDE "WEBEXDEFS.CH" //Include obrigatório

//comentarios sobre autor, data, descrição, retorno, etc. Opcional/* --------------------------------------------------------------------------------------Funcao RetDateAutor AntonioData 07/09/2003



http://nomedo_server:82/u_RetDate.apw

http://nome_do_server/u_RetDate.apw

Descricao Retorna a Data Retorno Retorno da Data do Sistema-------------------------------------------------------------------------------------- */User Function RetDate() // Clientes da Microsiga Software S\A devem sempre desenvolver User Function. Utilza-se Function, Web Function para desenvolvimento interno da Microsiga Software S\A.

Local cHtml //declaração da variável de retorno [ Espaco para declaracao de Variaveis e chamada de Metodos]

// Inicializacao do Ambiente **obrigatorioWeb Extended Init cHtml start "w_log_clire" //Opcional

cHtml := Date() //atribui a data do Sistema. Normalmente palavras em outra cor que aparecem no IDE são palavras reservadas ou funções do internas do sistema.

[ Espaco reservado para o processamento, criação de cursores , etc,,, ]

// Fechamento de ambiente ** obrigatorioWeb EXTENDED EndReturn cHtml // Esse será o retorno da Função RetDate

Capítulo 4 – Estruturas de Controle

Instrução if .. then .. else ..elseif

A ADVPL ASP suporta as seguintes estruturas de decisão:

IF <condição><Instrução>

Elseif



<Instrução>Else

<Instrução>Endif

Exercício: Vamos exemplificar a condição IF. O programa a seguir vai verificar se no momento da execução a hora for menor que 12 hs então enviará a mensagem “Bom dia !” caso contrário a mensagem será “Boa tarde !”.

1. Vamos criar um novo Projeto no AP7 IDE.a. Selecione a opção do menu “Projetos” e em seguida “Novos”

2. Digite o seguinte script e logo a seguir leia a explicação passo a passo:Obs.: Em todos os scripts contidos nesta documentação será utilizado a numeração de linhas para fazer referência às linhas do código facilitando a explicação, portanto, ao inseri-lo não considere os números.

3. Este código abaixo será o nosso arquivo .apw, portanto ao salvá-lo informe a sua extensão.

1 User Function ex001()23 Local cHTML:=""45 Web Extended Init cHtml67 cHTML:= l_ex001() // ou h_ex001()9 Web EXTENDED End1011 Return cHTML Na linha 1 temos a declaraçäo de uma User function , montada para ser chamada atraves do Browser. Na sua declaracao, ela ganha um prefixo (U_) Daremos o nome para nossa função de ex001.

Na linha 3 definimos a variável cHTML como local e sem conteúdo inicial “” (em branco)

Na linha 5 chamamos o comando Web Extended Init, que inicializa o procedimento de montagem do ambiente necessario à abertura de tabelas e utilização das demais funcoes, entre outras funcionalidades posteriormente explanadas. Esta função é obrigatória.



Na linha 7 atribuímos à variável cHTML o retorno da função l_ex001 (para ex001.aph) ou h_ex001 (para ex001.ahu), retornando o HTML . O que diferência a necessidade de uma ou outra Sintax é o ambiente de compilação: para arquivos compilados localmente nos cliente eles devem ser obrigatóriamente .AHU para os compilados na Microsiga ambos são aceitos.

Na linha 9 chamamos o comando WEB EXTENDED END, que informa ao servidor para fechar o ambiente . Esta função é obrigatória. Entre outras funcionalidades internas, a WEB EXTENDED END coloca no Html identificadores internos, tratamentos de erro, entre outros, indispensável para o funcionamento do mecanismo como um todo. Nao deve haver mais nenhum processamento apos WEB END

Na linha 11 obtemos o retorno da variável cHTML, que é devolvido para o Browser.

4. Agora, nos vamos escrever o código do arquivo APH (ou AHU) , portanto, salve este novo arquivo como ex001.aph (ou ex001.ahu). Neste momento estaremos solicitando ao servidor a hora atual se a hora atual for menor que 12 então enviaremos a seguinte mensagem ao usuário “Bom dia !!!” se a hora for maior que 12 então será enviado a seguinte mensagem ao usuário “Boa tarde !!!”. Note que, sempre que houver a necessidade de enviar uma informação ao browser processada a partir de um arquivo .apw, essa informação deve estar contida dentro de um arquivo APH (ou AHU).

1 <html>2 <body>34 <%5 local n6 7 n := left(time(),2)8 if val(n) < 12 9 %>10 Bom Dia !!!



11 <%12 Else13 %>14 Boa Tarde !!!15 <%16 Endif17 %>1819 </body>20 </html>

Na linha 1 e 2 encontramos as tags <html> e <body> que como vimos faz parte do inicio e corpo de um documento HTML.

Na linha 4 temos o indicador de script (<%), que tem como objetivo informar ao browser que daquele ponto em diante há um código ADVPL ASP a ser executado. Sempre que for iniciar um script ADVPL ASP utiliza-se o indicador (<%) e para finalizar um script utiliza-se o indicador (%>).

Na linha 5 estamos declarando a variável n como uma variável local.

Na linha 7 temos o código n := left(time(),2). Utilizamos a função time() para retornar a hora atual no formato hh:mm:ss, utilizamos a função left(string,posição) para retornar apenas as horas (hh) do conteúdo da função time(). Este conteúdo será armazenado na variável n

Na linha 8 utilizamos a condição IF para verificar se n é menor que 12, lembrando que estamos trabalhando com time de 24 hs.

Na linha 9 estamos indicando com (%>) o final do primeiro bloco de script.

Na linha 10 colocamos um texto HTML

Na linha 11 iniciamos novamente um bloco de código com o indicador (<%)

Na linha 12 colocamos o comando Else que faz parte da condição IF. Que é executado se a condição inicial não for verdadeira.

Na linha 13 colocamos novamente o indicado (<%) para iniciar um bloco de código.



Nas linhas 14 e 15 colocamos a mensagem a ser enviada ao usuário caso a condição em IF for falsa e fechamos o bloco de código.

Na linha 16 encerramos a condição IF com ENDIF.

Na linhas 17 e posteriores encerramos o bloco de código e também informamos ao browser que o documento HTML acaba por aqui.

Para executar o programa, certifique-se que o mesmo já foi compilado e em seguida carregue o browser e digite a seguinte URL: http://servidor:porta/u_ex001.apw , onde:

Servidor: é o nome do servidor onde está instalado o AP7 Web Server

Porta: é o número da porta que o administrador configurou o AP7 Web Server, está informação encontra-se no arquivo AP7srv.ini.

Por default, a configuracao de porta do servidor Http do Protheus é habilitado na porta 80, default do protocolo HTTP, de modo que nao precisamos informar a porta no Browser, a não ser que alteremos as configurações iniciais para habilitar o servidor em uma porta diferente da 80

Instrução Do case

Outra estrutura que veremos agora é a instrução Case que funciona da mesma maneira que a instrução IF. Possibilitando criar lista de expressões para cada condição.A estrutura da instrução Case é a seguinte:

Do CaseCase <primeira condição >

<instrucoes>



ATENÇÃO: sempre que for finalizado um programa deve-se compilar o mesmo. É neste processo que o repositório será alimentado com as novas funcionalidades.

Case <segunda condição ><instruções>

Otherwise<instruções>

EndCase

Loops

Os Loops são utilizados quando há a necessidade de percorrer n vezes o mesmo conjunto de instruções. Muito utilizado por exemplo para ler um bloco de registros em uma base de dados.

For <variável> := <início> to <fim> [ step <passo> ]<Instrução>

Next

O parâmetro step não é obrigatório, e indica qual o incremento utilizado para a variavel. (default=1)

While <condição><Instrução>

Enddo

Capítulo 5 – Recuperando Dados enviados por Post e Get

Recuperando Dados com Metódo POST

Formulário é uma página HTML contendo controles de entrada como textbox, listbox, radio buttom, check buttom e botões de execução.



A finalidade de se utilizar um formulário é manipular de alguma forma os dados informados pelo usuário. Para isso temos em ADVPL ASP funções com a RQryStr, que nos retorna o conteudo de cada campo.

Há dois métodos para se retornar o conteúdo de um formulário, o método POST e o GET, o primeiro que tem como característica passar o conteúdo dos campos de maneira oculta, não aparece na linha de URL do browser.

HttpPost-><NOME DA VARIÁVEL> HttpGet-><NOME DA VARIÁVEL> HttpSession-><NOME DA SESSÃO>

Descrição: retorna o conteúdo dos campos de um formulário.

Parâmetros: <NOME DA VARIÁVEL> informe o nome do campo informado na propriedade name do formulário.

Exercício: Vamos exemplificar a recuperação de dados utilizando o método POST

Vamos criar um formulário em HTML. Note que informaremos o método POST e a ação http://nomeDoServidor/w_ex002.apw dentro da tag Form.

<html><body bgcolor="#FFFFFF"><form method="post" action="http://localhost/u_ex002.apw"> <p>Nome: <input type="text" name="field_nome"> <br> Idade: <input type="text" name="field_idade"> <br> <input type="submit" name="Submit" value="Enviar"> </p> </form></body></html>

Agora vamos escrever o código em ADVPL ASP para nosso arquivo APW



1 User Function ex002()23 Local cHTML:=""4 Private cNome, cIdade56 cNome := HttpSession->field_nome7 cIdade := HttpSession->field_idade89 WEB EXTENDED INIT cHtml10 11 cHTML:= H_teste001()12 13 WEB EXTENDED END1415 Return cHTML

Na linha 1 estamos chamando a função User Function, sempre obrigatória.

Nas linhas 2 e 3 estamos definindo as variáveis a serem utilizadas no código. Note que as variáveis cNome e cIdade são do tipo Private que também podem ser lidas no APH.

Na linha 6 estamos atribuindo para a variável cNome o conteudo do campo field_nome utilizando a função HttpPost-><NOME DA VARIÁVEL>. O mesmo serve para a linha 7.

As linhas 9,11,13 e 15 já foram explicadas nos exercícios anteriores.Agora vamos escrever o código do arquivo APH

1 <html> 2 <body bgcolor="#FFFFFF">nome: <%=cNome %> <P>4 idade: <%=cIdade %>5 </body>6 </html>

Nas linhas 1 e 2 estamos informando ao browser que o documento HTML está iniciando

Na linha 3 temos o texto nome: em HTML e em seguida indicamos com <% o início de um bloco de código ADVPL ASP, onde estamos retornando ao browser o conteudo da variável cNome, que neste momento está armazenada a string que você digitou no campo nome do formulário.



O processamento deste exercício é simples, entenda que no primeiro momento apresentamos uma documento HTML com um formulário com os campos Nome e Idade para o usuário preencher, após o usuário informar os dados e clicar no botão Enviar, é enviado uma solicitação ao servidor para ele executar a User Function ex002 que informamos na propriedade action do formulário. Quando está solicitação chega ao servidor o mesmo já possui o conteudo dos campos do formulário e como nos codificamos, atribuímos o conteudo das variáveis com o conteudo dos campos e finalmente apresentamos o conteudo delas ao usuário utilizando o arquivo APH (ou AHU).

Recuperando Dados com Metódo GET

O método GET passa o conteúdo dos campos do formulário através da URL. O conteúdo dos campos serão retornados no parâmetro HttpGet-><NOME DA VARIÁVEL>.

A diferença básica entre o método Get e o Post é que o primeiro mostra na linha de URL do browser o conteúdo dos campos informados no formulário, podendo ser visualizado pelo usuário.

Exercício 003: Vamos exemplificar a recuperação de dados utilizando o método GetVamos criar um formulário em HTML. Note que informaremos o método GET e a ação http://nomedoServidor/u_ex003.apw dentro da tag Form.

<html><head><title>Metodo GET</title></head>

<body bgcolor="#FFFFFF"><form method="get" action="http://nistal:1200/u_ex003.apw"> <table width="22%" align="center"> <tr bgcolor="#006699"> <td colspan="2"> <div align="center"><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><b><font color="#FFFFFF">METÓDO GET</font></b></font></div>



</td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Nome:</font></td> <td width="83%"> <input type="text" name="field_nome"> </td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Sobrenome:</font></td> <td width="83%"> <input type="text" name="field_snome"> </td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Curso:</font></td> <td width="83%"> <input type="text" name="field_curso"> </td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"> <div align="center"> <input type="submit" name="Submit" value="Enviar"> </div> </td> <td width="83%"> </td> </tr> </table></form></body></html>

Agora vamos escrever o código do arquivo apw.

1 User Function ex003()23 Local cHTML:=""4 Private cNome, cSNome, cCurso56 Web Extended Init cHtml7 cNome := HttpGet->field_nome 8 cSNome := HttpGet->field_snome



9 cCurso := HttpGet->field_curso 1011 cHTML:=H_ex003()12 13 Web Extended End1415 Return cHTML

Na linha 1 estamos declarando a função User Function, sempre obrigatória. Na linha 6 estamos chamando o comando Web Extended Init cHtml para iniciar um ambiente de trabalho web.

Na linha 7 temos o seguinte código cNome := HttpGet->field_nome que está chamando a função HttpGet-> enviando os dois parâmetros e atribuindo o retorno dela a variável cNome.

Na linha 8 temos o seguinte código cSNome := HttpGet->field_snome que está chamando a função HttpGet-> enviando os dois parâmetros e atribuindo o retorno dela a variável cSNome.

Na linha 7 temos o seguinte código cCurso := HttpGet->field_curso que está chamando a função HttpGet-> enviando os dois parâmetros e atribuindo o retorno dela a variável cCurso.

Agora vamos escrever o código do arquivo APH

<html><body bgcolor="#FFFFFF"><table width="75%"> <tr> <td colspan="2"> <div align="left"><b>Dados informados no formulário</b></div> </td> </tr> <tr> <td width="12%" height="14">Nome:</td>



<td width="88%" height="14"><%= cNome %></td> </tr> <tr> <td width="12%">Sobrenome:</td> <td width="88%"><%= cSNome %></td> </tr> <tr> <td width="12%">Curso:</td> <td width="88%"><%= cCurso %></td> </tr> </table></body></html>

Capítulo 6 – Acessando Base de Dados

Introdução

Há duas maneiras de acessar e manipular uma base de dados, uma é utilizando o CodeBase (.DBF) outra maneira é através do TOPCONNECT que possibilita o acesso a vários banco de dados (SQL, INFORMIX, etc).

Exercício 004: Vamos exemplificar uma consulta a uma base de dados. A seguir temos o arquivo .apw, que tem como objetivo criar o ambiente no AP7 Web Server, conforme a função vista.



1 User Function ex004()23 Local cHTML:=""45 Web Extended Init cHtml68 cHTML:= h_ex004910 Web Extended End1112 Return cHTML

Arquivo ex004.aph

<html><body bgcolor="#FFFFFF"><table width="75%" border="0" cellpadding="0" cellspacing="1" bgcolor="#EEEEEE"> <tr bgcolor="#003366"> <td colspan="3"> <div align="center"><font color="#FFFFFF"><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2">CONSULTA BASE DE DADOS</font></b></font></div> </td> </tr> <tr bgcolor="#003399"> <td> <div align="center"><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#FFFFFF">Código</font></b></div> </td> <td> <div align="center"><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#FFFFFF">Descrição</font></b></div> </td> <td>

<div align="center"><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#FFFFFF">Quantidade em Estoque

Unitário</font></b></div> </td> </tr><%

dbselectarea('FA2') dbgotop()while !Eof()

%>



<tr bgcolor="#FFFFFF"> <td><%=FA2_COD %></td> <td><%=FA2_DESCR %></td> <td><%=FA2_QTDEST %></td> </tr><%

dbskip() enddo %>

</table>

</body></html>

Observe o bloco de código em negrito, o comando dbselectarea('FA2') seleciona a tabela FA2 que contém os dados que necessitamos para a consulta. O comando dbgotop() posiciona-se no primeiro registro da tabela FA2. A seguir utilizamos o loop while !Eof() que determina a execução do código adiante até que a condição !Eof() (End of File) for verdadeira. As instruções dentro do loop são para retornar o conteúdo dos campos FA2_COD, FA2_DESCR e FA2_QTDEST dentro das Tags <td>. E finalmente executamos o comando dbskip() que posiciona-se no próximo registro.

Inserindo dados em uma tabela

Exercício 5 Vamos fazer um exercício que tenha como objetivo inserir um registro na tabela FA2 e em seguida apresentaremos todos os registros desta tabela no browser.

1. Primeiramente, vamos criar o arquivo .aph (ou .ahu), que tem como objetivo formar um formulário para que o usuário insira os dados (código do produto, descrição do produto e quantidade em estoque).

<html><head>



<title>Inserindo Registros</title><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></head>

<body bgcolor="#FFFFFF"><form method="POST" action="http://localhost/w_ex005.apw"> <table width="22%" align="center"> <tr bgcolor="#006699"> <td colspan="2"> <div align="center"><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><b><font color="#FFFFFF">Inserindo Registros</font></b></font></div> </td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Cod:</font></td> <td width="83%"> <input type="text" name="field_cod"> </td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Descricao:</font></td> <td width="83%"> <input type="text" name="field_descr"> </td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Qtde. Estoque:</font></td> <td width="83%"> <input type="text" name="field_qtdest"> </td> </tr> <tr bgcolor="#EEEEEE"> <td width="17%"> <div align="center"> <input type="submit" name="Submit" value="Inserir"> </div> </td>



<td width="83%"> </td> </tr> </table></form></body></html>

Note que neste código utilizamos o método POST no formulário, visto anteriormente nesta apostila.

Agora vamos escrever o código do arquivo .apw, é nele que iremos escrever os comandos para recuperar os dados enviados pelo formulário e em seguida grava-los na base de dados.

1 User Function ex005()23 Local cHTML:=""4 Local cCod, cDescr, nQtdEst56 Web Extended Init cHtml7910 // Recupera os dados do formulário.11 cCod := HttpPost->field_cod12 nQtdEst := HttpPost->field_qtdest13 cDescr := HttpPost->field_descr1415 // Grava os dados.16 If RecLock('FA2',.t.)17 FA2->FA2_COD := cCOD18 FA2->FA2_DESCR := cDescr19 FA2->FA2_QTDEST := val(nQtdEst)20 MSUnlock()22 cHTML:=H_ex004Else CHtml := WebAlert(“Erro ao incluir registro.”)

Endif

2324 Web Extended End25



27 Return cHTML

Nas linhas 3 e 4 estamos declarando as variáveis como locais que serão utilizadas no decorrer do programa;

Na linha 6 estamos comunicando ao AP7 Web Server que será inicializada uma conexão web;

Na linha 10 temos um comentário. Tudo que estiver após os caracteres “//” e na mesma linha não serão considerados no momento da compilação;

Nas linhas 11,12 e 13 estamos recuperando os dados enviados para o Server através do formulário. Os dados código do produto, descrição do produto e quantidade em estoque serão armazenados nas variáveis cCod, cDescr e nQtdEst respectivamente. Note que a variável nQtdEst inicia a sua nomenclatura com o caracter n porque a mesma é uma variável do tipo númerica.

Na linha 15 temos outro comentário.Na linha 16 estamos inicializando o processo para gravar um registro na tabela. O comando RecLock('FA2',.t.) tem como objetivo travar o registro a ser gravado para que nenhum outro usuário que esteja executando o mesmo programa grave no mesmo número de registro. Este comando retornará .t. (true) se a condição for verdadeira, ou seja se ninguém estiver tentando gravar no mesmo número de registro;

Na linha 17 estamos gravando o conteudo da variável cCod no campo FA2_Cod da tabela FA2. Note que para gravar um registro utilizamos o comando REPLACE;

Na linha 18 estamos gravando o conteudo da variável cDescr no campo FA2_DESCR da tabela FA2. Note que para gravar um registro utilizamos o comando REPLACE;

Na linha 19 temos um diferencial entre as duas linha anteriores, pois antes de mandar gravar o dado na base de dados, estamos convertendo a variável nQtdEst em um valor númerico.

Na linha 20 estamos liberando o registro para ser manipulado com o comando MSUnLock().



Na linha 22 note que estamos solicitando a execução do arquivo ex004, ou seja, este arquivo foi escrito no exercício anterior e tem como objetivo listar os registros da base de dados FA2, concluindo, estamos reutilizando o código do exercício anterior para finalizar o nosso programa.

Capítulo 7 –Web Services em ADVPL - CLIENT

Introdução

Quando um Web Service é criado e disponibilizado , junto dele também é disponibilizada a definição do serviço , seus argumentos , estruturas e retornos (WSDL) . Para nos utilizarmos de um Web Service , precisamos montar um programa - Client que seja capaz de montar um “envelope” SOAP com os dados necessários ào processamento do Serviço , realizar a chamada , e tratar o respectivo retorno e excessões .

Embora existam Web Services que podem ser acessados via Http “direto” , apenas passando parâmetros via URL , o Client de Web Services do Advanced Protheus têm seu foco e recursos direcionados apenas à serviços que possuam



interface de comunicação que realize POST de pacotes de dados XML em formato SOAP.

Termos Técnicos

SOAP - Sigla de Simple Objetc Access Protocol, ou protocolo simples deacesso a objetos. O SOAP é um padrão aberto, baseado em XML, criado pelaMicrosoft, Ariba e IBM para padronizar a transferência de dados entre aplicações.Pode ser usado em combinação com vários outros protocolos comuns da Internet,como HTTP e SMTP.WSDL - Web Service Description Language. Submetida à W3C - o órgãopadronizador da Internet - . A linguagem WSDL define regras baseadas em XMLpara descrever serviços web.WEB SERVICES - programa completo ou componente de software residentenum servidor web.XML - Sigla de Extensible Markup Language, o XML é uma linguagem baseadaem tags semelhante ao HTML. Sua principal característica é a extensibilidade. Quememite um documento XML pode criar tags personalizadas, que são explicadas numdocumento anexo, que tem extensão XSD.XSD - Sigla de XML Schema Definition. Arquivo associado a um documentoXML que descreve e valida aos dados no documento. Assim como as linguagens de programação, os XSDs aceitam dados de diferentes tipos, como números, data e moeda.

Definição do Serviço em Advpl - Client

Para a criação do código-fonte de um Client de um Web Service , foi criada uma ferramenta de geração automática do fonte a partir da definição do Serviço (WSDL) , integrada ao IDE , e foram criadas classes especiais reservadas em Advpl para a montagem de tal fonte .

Ao gerarmos um fonte client para um WEB Service, este conterá as definições dos métodos / ações do serviço , a(s) estrutura(s) utilizada(s) no mesmo , e a(s) classe(s) intermediária(s) de uso interno para montagem e desmontagem da(s) estrutura(s) ; visando o encapsulamento de todos os tratamentos de envio e recebimento de dados através de pacotes SOAP.



O Fonte gerado através do assistente de criação de fonte deve preferencialmente ser gerado e compilado em um arquivo exclusivo , destinado unica e exclusivamente a este código. E , por tratar-se de uma classe Advpl gerada a partir da definição de um serviço , não devemos inserir e/ou alterar nenhuma das definições geradas pelo assistente , pois as mesmas serão perdidas caso o fonte seja gerado novamente .

Passos para a utilização do Fonte - Client

Partindo de uma classe de Web Services Client , gerado com o Assistente de Services Client do IDE , devemos seguir alguns passos para a utilização desta classe em nosso sistema. Sâo eles :

1 Criar uma variável ( preferêncialmente local ) para armazenar o objeto do Web Service

2 Inicializar o objeto do WebSErvice ( WsServico():New() ) 3 Verificar os parâmetros e seus respectivos tipos a serem utilizados no

método , declarados no serviço. 4 Atribuir no(s) parametro(s) necessários à chamada do método ps valores

desejados ou chame diretamente o método , passando os parametros necessários na chamada do mesmo.

5 Verficar o retorno do método . Caso este tenha retornado .T. , o processamento foi executado com sucesso e a(s) propriedade(s) de retorno do método está(ão) alimentada(s)

6 Caso retorne .F. , ocorreu uma falha na requisição e/oui processamento do Serviço . Para recuperar os detalhes da falha , utilizamos a funcao GetWSCError()

Criação de um Web Service CLIENT – Passo a Passo

Objetivo : Criar um WebService Client em Advpl , que utilize o serviço exemplificado no tópico “Criação de um WebService – SERVER passo a passo. “

Passo 1 : Determinar como obter o WSDL do serviço desejado

A maioria das definições WSDL dos serviços disponiveis na WEB são acessados através de uma URL , em geral apontando para o servidor onde o serviço está publicado , contendo o nome do serviço na url e um sufixo ?WSDL



ou .WSDL na Url. Nâo há padrão definido para tal , de modo que cada servidor pode disponibilizar ( ou não ) o WSDL de uma maneira diferente . O WSDL de alguns serviços restritos ( como por execmplo o serviço de busca na base de dados do Google ) são disponibilizados em arquivo ASCII , enviados por e-mail , apos um cadastro no site e autorização da empresa para o uso do serviço por ele provido. No nosso exemplo , a definição do serviço é obtida diretamente via http , através do link http://localhost/SERVERTIME.apw?WSDL

Caso vc execute este link através de um Web Browser ( Internet .Explorer. , por exemplo ) , será exibido no browse um arquivo em XML correspondendo à definição do serviço , conforme exemplo abaixo :

<?xml version="1.0" encoding="utf-8" ?> <definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:s0="http://localhost/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" targetNamespace="http://localhost/" xmlns="http://schemas.xmlsoap.org/wsdl/">

<types><s:schema elementFormDefault="qualified" targetNamespace="http://localhost/"><s:element name="GETSERVERTIME"><s:complexType><s:sequence /> </s:complexType> </s:element>

<s:element name="GETSERVERTIMERESPONSE"><s:complexType><s:sequence><s:element minOccurs="1" maxOccurs="1" name="GETSERVERTIMERESULT" type="s:string" /> </s:sequence> </s:complexType> </s:element> </s:schema> </types>

<message name="GETSERVERTIMESOAPIN"><part name="parameters" element="s0:GETSERVERTIME" /> </message>

<message name="GETSERVERTIMESOAPOUT"><part name="parameters" element="s0:GETSERVERTIMERESPONSE" /> </message>

<portType name="SERVERTIMESOAP"><operation name="GETSERVERTIME"><input message="s0:GETSERVERTIMESOAPIN" /> <output message="s0:GETSERVERTIMESOAPOUT" /> </operation> </portType>

<binding name="SERVERTIMESOAP" type="s0:SERVERTIMESOAP"><soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" /> <operation name="GETSERVERTIME"><soap:operation soapAction="http://localhost/GETSERVERTIME" style="document" /> <input><soap:body use="literal" /> </input>



http://localhost/SERVERTIME.apw?WSDL#%23















http://localhost/SERVERTIME.apw?WSDL

<output><soap:body use="literal" /> </output> </operation> </binding>

<service name="SERVERTIME"><port name="SERVERTIMESOAP" binding="s0:SERVERTIMESOAP"><soap:address location="http://localhost/SERVERTIME.apw" /> </port> </service> </definitions>

Passo 2 : Gerar o Fonte AdvPl do Client usando o Assistente do IDE

Ao gerarmos um fonte client para um WEB Service, este fonte conterá as definições dos metodos do serviço , a(s) estrutura(s) utilizada(s) no mesmo , e a(s) classe(s) intermediária(s) de uso interno para montagem e desmontagem da(s) estrutura(s) ; visando o encapsulamento de todos os tratamentos de envio e recebimento de dados através de pacotes SOAP.

O Fonte gerado através do assistente de criação de fonte deve preferencialmente ser gerado e compilado em um arquivo exclusivo , destinado unica e exclusivamente a este código. E , por tratar-se de uma classe Advpl gerada a partir da definição de um serviço , não devemos inserir e/ou alterar nenhuma das definições geradas pelo assistente , pois as mesmas serão perdidas caso o fonte seja gerado novamente .

Para geração do fonte Client em Advpl para utilizar este serviço , devemos criar um novo arquivo .PRX no IDE , especificamente para conter as classes deste serviço . Então , acessamos o menu “Ferramentas”, opção “Gerar Ciente Wbservices” . Neste momento , será mostrado na tela um pop-up semelhante ao mnostrado abaixo :

No campo de entrada de dados , devemos digitar a URL de onde o servidor irá obter a definição do WebSErvice. ( no nosso caso , http://localhost/SERVERTIME.apw?WSDL ) . Após a confirmação da janela



http://localhost/SERVERTIME.apw?WSDL




acima , caso o processamento ocorra com suicesso , na janela de mensagens do Ide será mostrado um texto semelhante ao abaixo :

Estabelecendo conexão com o server...Por favor aguarde. Obtendo descrição do WebService...Finalizando conexão com o server...Ok

E , na janela do novo arquivo criado , deverá ser criado um código-fonte semelhante ao mostrado abaixo :

#INCLUDE "PROTHEUS.CH"#INCLUDE "APWEBSRV.CH"

--- header do serviço ---/* ================================================================WSDL Location http://localhost/SERVERTIME.apw?WSDL Gerado em 12/30/02 17:21:29Observações Código-Fonte gerado por ADVPL WSDL Client 1.021217 B Alterações neste arquivo podem causar funcionamento incorreto e serão perdidas caso o código-fonte seja gerado novamente.================================================================ */

/* -------------------------------------------------------------------------------WSDL Service WSSERVERTIME------------------------------------------------------------------------------- */

--- declaração da Classe Client do WebService , com metodos e propriedades utilizadas ---

WSCLIENT WSSERVERTIME

WSMETHOD NEWWSMETHOD GETSERVERTIME

WSDATA _URL AS StringWSDATA cGETSERVERTIMERESULT AS string

ENDWSCLIENT

--- declaração do método NEW , para a criação do Objeto / Serviço ---WSMETHOD NEW WSCLIENT WSSERVERTIME

::_URL := NIL ::cGETSERVERTIMERESULT := ""

Return Self

/* -------------------------------------------------------------------------------WSDL Method GETSERVERTIME of Service WSSERVERTIME------------------------------------------------------------------------------- */



--- Definição do método , que recebe os parâmetros de chamada , executa o serviço e alimenta as propriedades de retorno do metodo , contendo os encapsulamentos

necessários para tratamento de excessões ---

WSMETHOD GETSERVERTIME WSSEND NULLPARAM WSRECEIVE cGETSERVERTIMERESULT WSCLIENT WSSERVERTIMELocal cSoap := "" , oXmlRet

BEGIN WSMETHOD

DEFAULT ::_URL := "http://localhost/SERVERTIME.apw"

cSoap += '<GETSERVERTIME xmlns="http://localhost/">'cSoap += "</GETSERVERTIME>"

oXmlRet := SvcSoapCall( Self,cSoap,; "http://localhost/GETSERVERTIME",; "DOCUMENT","http://localhost/",)

::cGETSERVERTIMERESULT := xGetInfo( oXmlRet , "_GETSERVERTIMERESPONSE:_GETSERVERTIMERESULT:TEXT" , "" )

END WSMETHOD

oXmlRet := NILReturn .T.

O fonte acima constitui uma Classe em Advpl , gerada para realizar a interface com a classe original publicada no Server, já realizando os tratamentos adequados para realizar a comunicação via http com o servidor onde o serviço está publicado. Vale obvervar que as linhas em negrito no fonte acima nâo foram inseridas pelo assistente do IDE , mas acrescentadas a este documento para fins didáticos.

Nele , observamos um caheçalho , contendo informações sobre a localização do WSDL utilizado para a geração do fonte , data e hora de geração e versão do engine de WebServices utilizado . Logo abaixo , a declaração de uma cliasse Client de WebServices ( WSCLIENT WSSERVERTIME ) , com o método new() para inicialização das propriedades advpl da classe . E , em seguida , a declaração do método de busca de Horário ( WSMETHOD GETSERVERTIME ) , que não envia parâmetro algum , e retorna o horário atual do server em :: cGETSERVERTIMERESULT , com todos os tratamentos necessários embutidos.

Passo 3 : Criar um fonte que utilize esta classe para a obtenção do horário.



Agora , criamos um novo arquivo no IDE , e montamos uma função para utilizar a classe de Web Services Client para obter o horário no servidor.

1 #INCLUDE "PROTHEUS.CH"23 User Function TestClient()4 Local oSvc := NIL56 oSvc := WSSERVERTIME():New()78 If oSvc:GETSERVERTIME()9 alert("Horário no Servidor : "+ oSvc:cGETSERVERTIMERESULT)10 Else11 alert("Erro de Execução : "+GetWSCError())12 Endif1314 Return

Linha 1 Declaramos a utilização do Include “Protheus.ch” , contendo as definições dos comandos ADVPL e demais constantes

Linha 3 Criamos uma User Function para utilizar o Web ServiceLinha 4 Declaramos uma variável local para conter o Objeto do Web Service ClientLinha 6 Para utilizarmos o serviço , alimentamos a variável oSvc com uma onva

instância do Web Services Client , obtida através da sintaxe <NOME_DO_SERVICO>():New()

Linha 8 Chamamos a execuão do Método GetServerTime a partir do Objeto do serviço oSrv , sem passar qualquer parametro. O retorno de um método do client pode ser .T. (true) em caso de execução com sucesso ou .F. (false) em caso de falha de execução .

Linha 9 Caso o serviço tenha sido executado com sucesso , o retorno esperado é alimenrado na propriedade cGetServerTimeResult do objeto do serviço.

Linha 11 Caso contrário ( retorno .F. ) , ocorreu alguma falha na chamada do serviço, como por exemplo o servidor não estava no ar, demorou muito pra responder ( time-out ) , entre outras. Para recuperarmos maiores detalhes sobre a ocorrência de erro , utilizamos a função GetWSCerror() , que retorna uma string com o resumo da ocorrência .

Linha 13 Finalizamos o programa de teste com um Return



Passo 4 : Executar o programa de testes

Abra uma nova instância do Ap Remote , e execute a função U_TESTCLIENT . Caso o Web Service esteja no ar e funcionando, e o fonte client seja devidamente compilado e sem erros , o resultado esperado é uma janela semelhante à mostrada abaixo :

No ambiente que montamos para teste , o Servidor de WebServices e o Client estâo no Protheus , compilados no mesmo Repositório de Objetos . Então , vamos desabilitar o Server HTTP do Protheus (colocando enable=0 na chave [http] do arquivo de consiguração do servidor) , re-iniciar o Server Protheus , e executar o programa client novamente . Devemos obter uma tela semelhante à exemplificada abaixo :

Passo 5 : Obter informações de “debug”

Visto até o passo 4 , vemos um client funcionando perfeitamente . Agora , imaginemos que , durante o desenvolvimento e testes do client do serviço , façam-se necessárias determinadas informações internas ‘as rotinas de execução do serviço no Client Advpl . Para tal , foi criada uma função que permite definir em tempo de execução , um nivel de detalhamento de



informações adicionais relacionadas ao Web Service ; informações estas que serão mostradas no Console do Server Protheus ( caso habilitado ) . a Função para definir o nivel de detalhe chama-se WSDLDbgLevel() , e recebe um número como parâmetro :

0 ( default ) Sem informações adicionais.

1 Apenas String SOAP de retorno do Server.

2 Strings Soap de Envio e Retorno.

Então , na linha 7 , vamos acrescentar a instrução WSDLDbgLevel(2) , para ativar o nivel mais completo de informacoes adicionais , e vamos obervar no console do servidor as mensagens apresentadas durante a execução do fonte de testes do client . Devemos obter um echo no console do server semelhante ao exemplo abaixo :

Iniciando Thread (siga0984, AUTOMAN)...-------------------------------------------------------------------------------SvcSoapCall to http://automan:8000/webservice/SERVERTIME.apw / DOCUMENTNameSpace http://automan:8000/webservice/SoapAction http://automan:8000/webservice/GETSERVERTIMECalled from GETSERVERTIME ( 137)Called from U_TESTCLIENT ( 10)---------------------------------- SOAPSEND -----------------------------------<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body><GETSERVERTIME xmlns="http://automan:8000/webservice/"></GETSERVERTIME> </soap:Body></soap:Envelope>---------------------------------------------------------------------------------------------------------------- POST RETURN ---------------------------------<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:so



ap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><GETSERVERTIMERESPONSE xmlns="http://automan:8000/webservice/"><GETSERVERTIMERESULT>10:37:10</GETSERVERTIMERESULT></GETSERVERTIMERESPONSE></soap:Body></soap:Envelope>-------------------------------------------------------------------------------Fim Thread (siga0984, AUTOMAN) BytesIn 73 BytesOut 75

O texto marcado em azul claro são as mensagens informativas a respeito da chamada do WebService , informando a URL chamada , o estilo soap de troca de dados ( document ) , o NameSpace e o SoapAction utilizados. O Texto marcado em verde (SOAPSEND) informa o conteudo do pacote Soap que foi enviado ( postado ) ao Servidor , e o conteudo em amarelo ( POST RETURN ) informa o conteúdo do pacote Soap devolvido pelo Server referente à esta solicitação.

Quando ocorre um erro qualquer , relacionado ‘a execução do Client Web Services , o método chamado retorna .F. , e o erro pode ser recuperado através da função GetWSCerror() , vista anteriormente . Para cada excessão prevista no Client , existe um código de erro correspondente, todos eles prefixados com WSCERR . A maioria das ocorrências está relacionada ‘a geração do Código fonte do Client Advpl utilizado-se o IDE. Todas as ocorrenctas de excessão tratadas peço Web Services Client Advpl estão relacionadas no Tópico Web Services Client – Códigos de Erro .

Web Services Client – Codigos de Erro

WSCERR000 / WSDL não suportado : Existem <N> Serviços declarados.

Por definição , um WSDL deve conter um e apenas um serviço declarado , com um ou mais métodos . Caso sejam identificados mais de um serviço no mesmo WSDL , no momento da geração do fonte , o processo é abortado com esta mensagem , informando em <N> o numero de serviços identificados no WSDL.

WSCERR001 / Não há Bindings SOAP para a geração do Serviço.



Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , uma vez identificado o serviço , o gerador de código procura a declaração dos BINDINGS no WSDL. Caso esta declaração não esteja presente , a rotina considera o WSDL incompleto , e aborta o processo de geração de código com esta mensagem .

WSCERR002 / <STRUCT_NAME> / <STRUCT_TYPE> (B) Estrutura não encontrada.

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , são analisados todos os parâmetros e estruturas utilizadas pelos métodos do serviço . Caso alguma estrutura seja declarada no serviço, porém não seja encontrada a identificação da mesma no WSDL , este é considerado inválido , sendo o processo abortado com a mensagem acima , onde a estrutura não encontrada é identificada em <STRUCT_NAME> e <STRUCT_TYPE>

WSCERR003 / Enumeration não suportado : <STRUCT_NAME> / <STRUCT_TYPE>

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , são analisados todos os parâmetros e estruturas utilizadas pelos métodos do serviço . Quando encontrada uma estrutura "simpletype" com um "enumeration" ( lista de parametros válidos pré-determinada ) , os tipos suportados até a versão 'ADVPL WSDL Client 1.021119 B' são : STRING, FLOAT, DOUBLE, DECIMAL, INT, INTEGER, UNSIGNEDLONG, UNSIGNEDINT, LONG . Caso o WSDL contenha um "enumeration" com uma lista de itens de algum tipo que não os declarados acima ( tipo não supirtado ) , o processamento é abortado com a mensagem acima , onde o "enumeration" não suportado é identificado em <STRUCT_NAME> e <STRUCT_TYPE>

WSCERR004 / Apontamento de pendência 001B em Implementação para (<N>) <STRUCT_NAME>

Apos a análise inicial dos parametros e estruturas utilizadas no serviço , as estruturas pendentes são analizadas recursivamente até que todas as estruturas utilizadas sejam processadas. Quando deste processamento , uma estrutura contenha um elemento que aponte para uma outra estrutura , e esta for encontrada registrada não como uma estrutura ( complextype ) ; o WSDL é



considerado inválido , e o processo de geração é abortado com a mensagem acima, identificando a estrutura pendente em <STRUCT_NAME>

WSCERR005 / Apontamento de pendência 001A em Implementação para (<N>) <STRUCT_NAME>

Similar ao WSCERR004 , esta ocorrência é reproduzida quando uma estrutura contenha um elemento que aponte para uma outra estrutura , e esta segunda estrutura não for encontrada no WSDL ; consequentemente o processo de geração é abortado com a mensagem acima, identificando a estrutura pendente em <STRUCT_NAME>

WSCERR006 / 01 Empty ParamName : aMsg <N>

Quando da análise de parâmetros ( Messages ) a partir de um WSDL , Caso um Message não tenha nome definido , O WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima, identificando em <N> o elemento Interno do array de Messages do gerador de código Advpl .

WSCERR007 / 01 Empty ParamType for <PARAM_NAME> : aMsg <N>

Quando da análise de parâmetros ( Messages ) a partir de um WSDL , Caso um Message não tenha um tipo definido , O WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima, identificando em <PARAM_NAME> o nome do Message incompleto , e em <N> o elemento Interno do array de Messages do gerador de código Advpl .

WSCERR008 / Retorno NULLPARAM inválido

Quando da montagem do código fonte Advpl , a partir de um WSDL , caso um parâmetro de retorno seja identificado como NULO ( NULLPARAM ) , O WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima.

WSCERR009 / 01 Param IO (<X>) unknow

Esta mensagem é uma ocorrência interna de erro do gerador , não reproduzida até o momento. Ela poderá ser reproduzida quando da análise do array interno de parâmetros , e este não contenha uma definição de IO De estrutura válido . Caso este erro se reproduza , entre em contato com <XXX>

WSCERR010 / Type <STRUCT_TYPE> não contém Definição ASTRUCTIN



Quando da análise de estruturas pendentes a partir de um WSDL , caso uma estrutura complexa não contenha a especificação de seus elementos internos, e a mesma não contenha nenhuma referência ao SCHEMA ou a outra estrutura , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima, identificando em <STRUCT_TYPE> o nome da estrutura incmpleta.

WSCERR011 / Retorno NULLPARAM inválido -> Idêntico ao WSCERR008

WSCERR012 / 01 Param IO (<X>) unknow -> Identico ao WSCERR009

WSCERR013 / ReturnData não implementado : <SOAP_TYPE>

Quando da geração das expressões de conversão de valores de SOAP para Advpl , caso um parametro SOAP não seja suportado para conversão , o processo de geração é abortado com a mensagem acima, identificando em <SOAP_TYPE> o tipo do dado não suportado para conversão .

WSCERR014 / InitType NULLPARAM não implementado.

Esta mensagem é uma ocorrência interna de erro do gerador , não reproduzida até o momento.

WSCERR015 / Node '+cObjName+' as '+cObjType+' on SOAP Response not found.

*** Ocorrência de erro de execução do Client , reproduzida quando do processamento de um pacote SOAP retornado por um Web SErvice cuja definição de trocas de dados SOAP utilize o Style = RPC , e um node de retorno de um Array de Estruturas obrigatório definido no WSDL não foi encontrado no pacote retornado. ***

WSCERR016 / Requisição HTTPS não suportada.

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , podemos especificar um arquivo na unidade de disco do servidor , ou uma definicão WSDL piblicada em um servidor WEB



HTTP . O Protocolo HTTPS ainda não é suportado para operações com WEB Services.

WSCERR017 / Requisição HTTP retornou NIL.

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , quando especificamos uma definicão WSDL piblicada em um servidor WEB HTTP , caso o servidor não seja encontrado , o processo é abortado com a mensagem acima. Verifique se a a URL digitada está em formato válido , se existe entrada no DNS da sua conexão de rede para resolver o IP do servidor especificado , e se o mesmo está em operação normal.

WSCERR018 / Requisição HTTP retornou EMPTY.

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , quando especificamos uma definicão WSDL piblicada em um servidor WEB HTTP , caso o servidor seja encojntado , porém não haja nenhum tipo de retorno por parte do mesmo , o processo é abortado com a mensagem acima. Verifique se a URL está digitada corretamente e se o servidor está em operação normal.

WSCERR019 / Arquivo não encontrado.

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , quando especificamos uma definicão WSDL salva em um arquivo na unidade de disco do SErvidor , caso o arquivo especificado não seja encontrado , o processo é abortado com a mensagem acima. Verifique se o arquivo especificado está digitado em formato válido , e se o mesmo realmente existe.

WSCERR020 / Falha de Abertura do Arquivo / FERROR <FERROR_NUM>

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , quando especificamos uma definicão WSDL salva em um arquivo na unidade de disco do SErvidor , caso não seja possível a abertura do arquivo para a leituda da definicão , o processo é abortado com a mensagem acima , identificando o código ADVPL de Falha de Abertura em <FERROR_NUM> . Verifique se o arquivo especificado não está sendo utilizado por outro programa , e se o usuário que subiu o Server Protheus têm direitos de acesso de rede à pasta\arquivo especificada.

WSCERR021 / <EXTRA_INFO> WSDL Parsing <PARSER_ERROR>



Esta ocorrência é reproduzida no momento da geração de um codigo-fonte a partir de um WSDL , caso este apresente alguma inconsistência , como um erro de sintaxe ou estrutura, em nível de documento XML. Caso reproduzida êsta ocorrência , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando em EXTRA_INFO o "source" do WSDL , e em <PARSER_ERROR> maiores detalhes sobre a inconsistência detectada.

WSCERR022 / <EXTRA_INFO> WSDL Parsing <PARSER_WARNING>

Similar à ocorrência WSCERR021 , esta ocorrência é reproduzida no momento da geração de um codigo-fonte a partir de um WSDL , caso este apresente alguma inconsistência em nível de documento XML. Caso reproduzida êsta ocorrência , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando em EXTRA_INFO o "source" do WSDL , e em <PARSER_WARNING> maiores informações sobre a inconsistência detectada.

WSCERR023 / <EXTRA_INFO> Falha ao Importar WSDL : Todos os parâmetros VAZIOS

Esta ocorrência é reproduzida no momento da geração de um codigo-fonte a partir de um WSDL , caso este , após tratramento do Parser , não resulte nenhum conteudo. Neste caso , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando em EXTRA_INFO o "source" do WSDL .

WSCERR024 / Message <MESSAGE_NAME> não encontrada.

Esta ocorrência é reproduzida no momento da geração de um codigo-fonte a partir de um WSDL , quando é especificado um parâmetro no BINDING do serviço , porém o mesmo não foi declarado no Message do mesmo. Neste caso , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando em MESSAGE_NAME o nome do parâmetro especificado no Bindings não encontrado.

WSCERR025 / Binding <SERVICE_BINDING> não Encontrado.

Esta ocorrência é reproduzida no momento da geração de um codigo-fonte a partir de um WSDL , quando é especificado um binding no serviço ,



porém o mesmo não foi declarado na seção Bindings do mesmo. Neste caso , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando em SERVICE_BINDING nome do parâmetro especificado no Serviço não encontrado.

WSCERR026 / targetNamespace não definido no WSDL.

Quando da análise do header de um WSDL , não for localizado o atributo que identifica o namespace default utilizado pelo WSDL ( TargetNamespace ) , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima .

WSCERR027 / <SERVICE_NAME> : Bind_Operation não encontrada em aBind[<N>]

Quando da análise da estrutura de um WSDL , não for localizado uma operação definida do serviço na seção BINDINGS do mesmo , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando o servico em <SERVICE_NAME> , e o elemento do array de controle interno de Bindings em <N>

WSCERR028 / PortType <PORT_TYPE> não Encontrado em aPort

Quando da análise da estrutura de um WSDL , não for localizado uma operação definida do serviço na seção PORTTYPE do mesmo , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando o porttype não encontrado em <PORT_TYPE>.

WSCERR029 / PortType <PORT_TYPE> não contém operações.

Quando da análise da estrutura de um WSDL , for localizado o PORTTYPE do serviço , porém o mesmo não contiver a definição interna de parâmetros , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando o porttype inconsistente em <PORT_TYPE>.

WSCERR030 / Declaracao de estrutura pendente não suportada com <STRUCT_TYPE>

Quando do processamento de estruturas pendentes do WSDL , em momento de geração de fonte , as estruturas pendentes devem ser estruturas tipo COMPLEXTYPE. Não são suportados outros tipos neste ponto da rotina .



Neste caso , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando o tipo da estrutura em processamento no momento em <STRUCT_TYPE>

WSCERR031 / NameSpace indefinido para <STRUCT_NAME>

Quando do processamento de estruturas pendentes , identificadas como sendo externas ào WSDL atual , especificadas por um IMPORT ou REF , caso a estrutura seja declarada sem o referido namespace , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando a estrutura em <STRUCT_NAME>

WSCERR032 / (X) NameSpace (<SHORT_NAMESPACE>) para Type <STRUCT_TYPE> não encontrado.

Quando do processamento de estruturas pendentes , identificadas como sendo externas ào WSDL atual , especificadas por um IMPORT ou REF , o namespace da mesma deve estar declarado no header do WSDL. Caso ele não seja encontrado, o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando o alias do namespace em <SHORT_NAMESPACE> , e a estrutura em <STRUCT_TYPE>.

WSCERR033 / Import para NameSpace <LONG_MANESPACE> não encontrado.

Complementar ao erro WSCERR032 , este é reproduzido quando o namespace idenfiicado para o parâmetro seja externo ao WSDL , porém a URL para processamento do mesmo não seja especificada através de um <IMPORT...> no WSDL . Neste caso , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando o namespace em <LONG_NAMESPACE> .

WSCERR034 / Location VAZIO para Import do NameSpace <LONG_MANESPACE>

Complementar ao erro WSCERR033 , este é reproduzido quando a declaração da URL / Location do namespace externo não esteja declarado no <IMPORT...> no WSDL . Neste caso , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando o namespace em <LONG_NAMESPACE> .

WSCERR035 / Definição aType para <STRUCT_TYPE> não encontrada.



Quando do processamento de estruturas pendentes , identificadas como sendo externas ào WSDL atual , especificadas por um IMPORT ou REF , o namespace da mesma é identificado e importado , e todo o esquema é re-processado. No reprocessamento , caso o parâmetro pendente não seja encontrado , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando a estrutura em <STRUCT_TYPE>.

WSCERR036 / 03 ParamRef não suportado : <REFERENCIA> from <PARAM_NAME> / <STRUCT_NAME>

Qundo da validação de estruturas complexas , caso a mesma não possua tipo definido , e não seja uma referência externa ao WSDL , ela deve ser uma referência ao próprio SCHEMA. Caso seja especificada qualquer outro tipo de referência , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando a referência em <REFERENCIA> , e os detalhes sobre o parametro / estrutura em <PARAM_NAME> / <STRUCT_NAME>

WSCERR037 / Estrutura Interna Inesperada em (<PARAM_NAME>)

Quando da validação de estruturas complexas , caso a mesma tenha passado por todas as interpretações cabiveis de uma estrutura , e mesmo assim não foi possível identificá-la , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando a estrutura em <PARAM_NAME>

WSCERR038 / 02 Empty ParamName for <PARAM_NAME> aType[<N1>][<N2>]

Quando da validação de estruturas complexas , caso a mesma tenha passado por todas as interpretações cabiveis de uma estrutura , porém seu nome não foi declarado , o WSDL é considerado inválido , e o processo de geração é abortado com a mensagem acima , identificando a estrutura em <PARAM_NAME>

WSCERR039 / Unexpected DumpType <OBJ_TYPE>

Quando da utilização da função XMLDataSet , para a interpretação de um objeto de retorno XML em formato DataSet , caso não seja passado um objeto



Advpl de tipo válido ( Objeto XML ou Array ) , o processamento é abortado , mostrando a mensagem acima , identificando o tipo de parâmetro recebido em <OBJ_TYPE>

WSCERR040 / Unexpected SCHEMA Type <OBJ_TYPE>

Quando da utilização da função XMLDataSchema , para determinar os dados recebidos por um retorno de um Web Service que retorna uma referência ao Schema , e não seja passado à função um Objeto Advpl de Tipo Válido ( Objeto Xml ou Array ) , o processamento é abortado , mostrando a mensagem acima , identificando o tipo de parâmetro recebido em <OBJ_TYPE>

WSCERR041 / <NOTNIL_MESSAGE>

Durante a identificação do retorno de um Web Service , caso algum parâmetro obrigatorio do serviço não esteja presente no pacote de retorno , o processamento é abortado com a mensagem acima , identificando em NOTNIL_MESSAGE o parametro que não veio preenchido.

WSCERR042 / URL Location não especificada.

No momento de postar o pacote SOAP de parâmetros para um Web Service , é verificada a propriedade reservada _URL do Objeto do Serviço. Caso a mesma esteja fora re-definida para NIL ou “” , o processamento é abortado com a mensagem acima. Antes da postagem dos dados.

WSCERR043 / SoapStyle Desconhecido : " <SOAP_STYLE>

No momento de enviar o pacote de parâmetros para um Web Service , é verificado o SoapStyle utilizado pelo serviço . Caso o mesmo não seja DOCUMENT ou RPC , o processamento é abortado com a mensagem acima, identificando o SoapStyle utilizado em <SOAP_STYLE>.

WSCERR044 / Não foi possível POST em <URL_LOCATION>

Apos montado o pacote de envio para a solicitação de processamento do serviço , o pacote é enviado à url discriminada no serviço. Caso o Servidor de destino do pacote não seja localizado no DNS ou não esteja no ar ,o processamento é abortado com a mensagem acima ,e a url de destino é especifiacada em <URL_LOCATION>



WSCERR045 / Retorno VAZIO de POST em <URL_LOCATION>

Apos montado o pacote de envio para a solicitação de processamento do serviço , o pacote é enviado à url discriminada no serviço. Caso o pacote seja enviado , porém o retorno do servidor seja um pacote Vazio , o processamento é abortado com a mensagem acima ,e a url de destino é especifiacada em <URL_LOCATION>

WSCERR046 / XML Warning <PARSER_WARNING> ( POST em <URL_LOCATION> )

Apos montado e enviado o pacote de envio para a solicitação de processamento do serviço , o pacote SOAP retornado é analizado para a alimentacao dos parametros Advpl . Caso o pacote retornado apresente alguma incionsistência em nivel de documento XML , o processamento é abortado com a mensagem acima , identificando a inconsistência em <PARSER_WARNING> e a url de destino é especifiacada em <URL_LOCATION>

WSCERR047 / XML Error <PARSER_ERROR> ( POST em <URL_LOCATION> )

Apos montado e enviado o pacote de envio para a solicitação de processamento do serviço , o pacote SOAP retornado é analizado para a alimentacao dos parametros Advpl . Caso o pacote retornado apresente algum erro de sintaxe ou estrutura em nivel de documento XML , o processamento é abortado com a mensagem acima , identificando o erro em <PARSER_ ERROR > e a url de destino é especifiacada em <URL_LOCATION>

WSCERR048 / SOAP FAULT <FAULT_CODE> ( POST em <URL_LOCATION> ) : [<FAULT_STRING>]

Apos analizado o pacote SOAP retornado do serviço , caso o mesmo apresente uma ocorrência de falha do tipo SOAP:FAULT , o processamento é abortado com a mensagem acima , identificando o soap_code em FAULT_CODE , e a string contendo os detalhes da ocorrência gerada pelo Server em FAULT_STRING , e a url de destino do pacote <URL_LOCATION>

WSCERR049 / SOAP RESPONSE (RPC) não encontrado.

Durante a analize do pacote SOAP retornado do serviço , caso o mesmo utilize um soapType = RPC , e o node de resposta não seja encontrado no pacote , o processamento é abortado com a mensagem acima .



WSCERR050 / SOAP RESPONSE REF <REFERENCE_ID> (RPC) não encontrado.

Durante a analize do pacote SOAP retornado do serviço , caso o mesmo utilize um soapType = RPC , e o node de resposta aponte para un outro node via referência , e este novo node não seja encontrado no pacote , o pacote é considerado inválido e o processamento é abortado com a mensagem acima , mostrando o identificador de referência nao encontrado em REFERENCE_ID

WSCERR051 / SOAP RESPONSE RETURN (RPC) não encontrado.

Durante a analize do pacote SOAP retornado do serviço , caso o mesmo utilize um soapType = RPC , e o node de resposta não aponte para nenhuma referência , o node de retorno està dentro do nivel de resposta . Caso o node de retorno não seja encontrado neste nivel , o pacote de retorno é considerado inválido , e o processamento é abortado com a mensagem acima .

WSCERR052 / Enumeration FAILED on <STRUCT_TYPE>

Durante a montagem do pacote de envio de dados para a requisição de um processamento de um Web Service , caso um parâmetro de um tipo simples contiver um “enumeration” , e for alimentado pelo client com um valor não constante na lista do Enumeration , o processamento é abortado antes da requisicão ser realizada , com a mensagem acima , identificando o tipo da estrutura inválida em <STRUCT_TYPE>

WSCERR053 / WSRPCGetNode (Object) not found.

Quando da analise do retorno de um processamento de um Web Service , utilizando soap:style = RPC , no momento de analise de um retorno de uma estrutura complexa , caso o node referente à mesma nào seja localizado no pacote de retorno , o pacote de retorno é considerado inválido , e o processamento é abortado com a mensagem acima.

WSCERR054 / Binding SOAP não localizado no WSDL.

Durante a geração do codigo-fonte para Client Advpl a partir de uma definição de serviço (WSDL) , uma vez identificado o serviço , o gerador de



código procura a declaração dos BINDINGS no WSDL. Dentre os bindings encontrados , apenas são processados os bindings que transportam dados no formato SOAP . Caso nenhum binding do serviço utilize SOAP , o processo de geração do fonte client é abortado , retornando esta ocorrência.

WSCERR055 / Invalid Property Type (<TYPE1>) for <PROPERTY> ( <TYPE2> )

Quando da utilização de uma classe client de um Web Service em Advpl , as propriedades da classe devem ser alimentadas com os tipos Advpl apropriados. Caso uma determinada propriedade do Objeto seja alimentada com um tipo não concordante com a declaração do método / estrutura , no nomento do pacote SOAP ser montado , todas as propriedades usadas pelo método são validadas antes do envio . Caso alguma propriedade <PROPERTY> esteja alimentada com um tipo de dado Advpl <TYPE1> , porém o tipo esperado era <TYPE2> , o processamento é abortado com a ocorrÊncia de erro acima.

Observação : Esta validação está disponível a partir da versão ADVPL WSDL Client 1.030523 e superiores. Em versões anteriores , ocorria um erro Interno “Type Mismatch” ou “Argument Error” dentro da função WSSoapValue.

WSCERRINT / <INTERNAL_ERROR>

Esta ocorrência aponta um erro interno no engine de processamento do client Web Services . Caso esta ocorrência seja reproduzida , entre em contato com Departamento de Tecnologia da Microsiga Software S/A.



Capítulo 8 - Web Services em ADVPL - SERVER

Introdução

Visto de forma simples , um Web Service é uma classe que pode ser acessada via protocolo http. De modo que , um programa de Software “client” irá solicitar ao “server” um processamento de uma ação / método do serviço , enviando o(s) parâmetro(s) ao mesmo através de uma string XML , formatada no padrão SOAP (Simple Object Access Protocol) , e o serviço retornará ao client uma string XML de resposta , também formatada no padrão SOAP.

Diferentemente dos Web Sites, que são apresentações de dados feitas para serem vistas em um browser por um internauta , um Web Service é construído para ser acessado diretamente por outro serviço ou programa de Software. Os serviços podem ser combinados entre si e com outras aplicações para construir serviços interativos e inteligentes.

A universalidade de um Web Service , entre outros fatores , reside justamente na maneira de disponibilizar uma espécie de “manual” do serviço , chamado de WSDL ( Web Services Description Language ) , que nada mais é do que uma descrição detalhada do serviço , que é capaz de resumir em um único documento os métodos de um serviço , os parâmetros , retornos e detalhes do mesmo. Um documento WSDL é de tal forma completo que praticamente elimina a necessidade de qualquer tipo de contato direto entre o desenvolvedor de um Servico (server) e o analista que irá montar um client para interagir com ele. Também foi idealizado o uso do protocolo HTTP originalmente para a troca de pacotes de requisição e retorno de processamento pois a maioria dos sistemas operacionais têm recursos para suportá-lo ; e foi escolhido o formato SOAP por ser um padrão aberto, criado pela Microsoft, Ariba e IBM para padronizar a transferência de dados em diversas aplicações, que utiliza como veículo o universalmente conhecido XML ( Extended MarkUp Language ) .

Termos Técnicos

SOAP - Sigla de Simple Objetc Access Protocol, ou protocolo simples deacesso a objetos. O SOAP é um padrão aberto, baseado em XML, criado pelaMicrosoft, Ariba e IBM para padronizar a transferência de dados entre aplicações.Pode ser usado em combinação com vários outros protocolos comuns da Internet,como HTTP e SMTP.



WSDL - Web Service Description Language. Submetida à W3C - o órgãopadronizador da Internet - . A linguagem WSDL define regras baseadas em XMLpara descrever serviços web.WEB SERVICES - programa completo ou componente de software residentenum servidor web.XML - Sigla de Extensible Markup Language, o XML é uma linguagem baseadaem tags semelhante ao HTML. Sua principal característica é a extensibilidade. Quememite um documento XML pode criar tags personalizadas, que são explicadas numdocumento anexo, que tem extensão XSD.XSD - Sigla de XML Schema Definition. Arquivo associado a um documentoXML que descreve e valida aos dados no documento. Assim como as linguagens de programação, os XSDs aceitam dados de diferentes tipos, como números, data emoeda.

Definição de um Web Service – SERVER em Advpl

Inicialmente veremos neste documento as atribuições e funcionalidades dos Web Services direcionados à uma aplicação SERVER , e num momento posterior a funcionalidade de uma aplicação CLIENT em detalhes . A criação de um Web Service em Advpl consiste na montagem de uma classe Advpl especial , chamada WSSERVICE , onde cada método da classe é uma ação do Web Service. Caberá àos fontes dessa classe o processamento de uma requisição e a geração do respectivo retorno , cabendo então à Lib de Web Services do AP7 a camada de troca de dados , recepção e tratamento do pacote SOAP , as conversões de dados cabíveis do XML para as propriedades de parâmetro da classe Advpl e a montagem do pacote SOAP a partir das propriedades de retorno setadas pelo método executado e retorná-lo ao Client, além de prover ào client o documento WSDL referente ào serviço compilado no Repositório de Objetos Advpl .

Este método de programação em camadas permite encapsular on tratamentos internos , em se tratando de protocolo HTTP , SOAP e WSDL , tornando relativamente fácil a missão de criar um Web Serviçe utilizando-se do Advanved Protheus. Basta escrever uma classe que receba um ou mais parâmetros e devolva um retorno , ambos tratados pelo fonte como um tipo de dado Advpl básico; configurar o Server Protheus para habilitar a interface HTTP e os Web Services , que a Lib faz todo o resto.



Declaração de um Web Service – SERVER em Advpl

Vejamos abaixo um esboço contendo as instruções Advpl necessárias para a declaração de um Web Service – SERVER em Advpl . Para a utilização destes comandos , faz-se necessária a declaração do arquivo de header Advpl APWEBSRV.CH .

WSSERVICE <Nome_do_Servico> // Declaração do Serviço

WSDATA <Nome_Campo1> as [ARRAY OF] <Tipo_do_campo1> [OPTIONAL]

(... demais propriedades , parâmetros e retornos ... )

WSMETHOD <Nome_do_Metodo>(... demais métodos ...)

ENDWSSERVICE

WSSTRUCT <Nome_da_Estrutura> // Declaração da(s) Estrututra(s) ( opcionais )

WSDATA <Nome_Campo1> as [ARRAY OF] <Tipo_do_campo1> [OPTIONAL]

( ... demais campos da estrutura ... )

ENDWSSTRUCT

// --- Fontes do(s) método(s) declarado(s) no Serviço ---

WSMETHOD < Metodo> WSRECEIVE < Campo_In>[, Campo_In2,...] WSSEND < Campo_Out>( ... Processamento do serviço a partir dos parametros , e alimentação do retorno <Nome_campo_out> ... )



Regras para Nomenclatura dos Serviços / Estruturas / Dados e Métodos

1. Nomenclatura dos Serviços

<Nome_do_servico> Deve ser iniciado por um caracter alfabético , e deve conter apenas os caracteres alfabéticos compreendidos entre A ... Z , os caracteres numéricos compreendidos entre 0 ... 9 , podendo também ser utilizado o caracter “_” (underline ) . Um serviço não pode ter um nome de uma palavra reservada Advpl , e não pode ter o nome igual a um tipo básico de campo ( STRING , INTEGER , FLOAT , DATE , BOOLEAN ) .

2. Nomenclatura de Estruturas

WSSTRUCT <Nome_da_Estrutura> // Declaração de Estrututras ( opcionais )

<Nome_da_Estrutura> Obedece às mesmas regras de nomenclatura de Serviços , não podendo haver uma estrutura com o mesmo nome de um serviço declarado.

Uma estrutura é um agrupamento de dados básicos, criado como uma classe especial (WSSTRUCT) em Advpl. Procedemos com a criação de uma estrutura para um serviço quanto temos a necessidade de definir que um conjunto de dados básicos pode ser agrupado em um tipo de informação que será utilizada como parâmetro e/ou retorno em um ou mais metodos do serviço.

3. Nomenclatura de Dados ( Campos )

WSDATA <Nome_Campo> as [ARRAY OF] <Tipo_campo> [OPTIONAL]

<Nome_Campo> Obedece às mesmas regras de nomenclatura de Serviços , não podendo haver um dado com o mesmo nome de um serviço ou estrutura já declarados.



[ARRAY OF] Caso especificado , indica que este dado poderá ter mais de uma ocorrência , sendo tratado como um Array em Advpl .

<Tipo_Campo> Pode ser um tipo básico de dado (String , Date , Integer , Float , Boolean ) , ou pode ser uma estrutura declarada .

[OPTIONAL] Caso especificado , indica que a especificação deste dado nos pacotes de envio e/ou retorno é opcional.

*** Restições de uso da instrução ARRAY OF : Não é permitido o uso da instrução ARRAY OF quando declaramos dados utilizados para entrada de dados dentro da declaração do serviço. Para tal , precisamos criar uma estrutura intermediária para “encapsular” o array.

Tipos de Dados Básicos

String Dado Advpl do tipo String.Date Dado Advpl do tipo Data.Integer Dado Advpl do Tipo numérico , apenas numeros inteiros.Float Dado Advpl do Tipo numérico , pode conter numeros inteiros e

não-inteiros.Boolean Dado Advpl do Tipo Booleano ( lógico ) .Base64Binary* Dado Advpl do Tipo String Binária , aceitando todos os

Caracteres da Tabela ASCII , de CHR(0) a CHR(255)

* A implementação do Campo Base64Binary está disponível apenas a partir de repositórios gerados após Março / 2003 ( A partir da versão ADVPL WSDL Server 1.030306 ) .

*** Campos Obrigatórios / Opcionais : Por default , um campo declarado sem a cláusula OPTINAL , é obrigatório . Sendo obrigatório , isto significa que o node ou tag SOAP referente ao mesmo deverá ser especificado no pacote XML – Soap onde o campo for utilizado, seja ele um parâmetro ou retorno . No processamento de um serviço , os dados enviados pelo client como parâmetro na requisição são lidos do pacote SOAP e atribuidos às propriedades do método do respectivo serviço, e caso um dado não seja passado ao serviço , é atribuído ao mesmo o conteúdo NIL. A partir da versão “ADVPL WSDL Server 1.030103 B” , foi implementado o tratamento de excessão no Server para gerar um Soap



Fault automático , caso algum parametro obrigatório não seja recebido na solicitação de processamento.

4. Métodos ( Ações )

WSMETHOD <Metodo> WSRECEIVE <Cpo_In>[, Cpo_In2,...] WSSEND <Cpo_Out>

<Metodo> Obedece às mesmas regras de nomenclatura de Serviços , não podendo haver um serviço ou estrutura declarados com o mesmo nome.

Ao declarar o método , obrigatoriamente devemos especificar um ou mais campos declarados dentro do serviço a serem utilizados para a entrada de dados , e apenas um campo para saída de dados do método . Os campos podem ser de tipos básicos ou estruturas. Dentro do método , fazemos referências às propriedades da estrutura , segundo a nomenclatura de acesso à propriedades de objetos Advpl ( prefixo :: ) . Caso desejemos declarar um serviço que não requer nenhum parâmetro , devemos especificar que o mesmo recebe o parâmetro reservado NULLPARAM .

Publicando um WEB Service no Protheus - Configuração

Um WebService em Advpl utiliza-se de Working Threads (**) para atender às solicitações de processamento em um host http , de modo que , para publicar e habilitar um Web Service em um servidor Protheus , devemos primeiramente habilitar o serviço de publicações web ( http ) do Protheus , através da seção [http] do Arquivo de Inicialização do Servidor ( Ap7Srv.ini ) .

Feito isso , existem duas maneiras de habilitar o WebService : Através da criação da seção [webservices] no Arquivo de Configuração do Server , ou através da configuração manual de um ambiente de Working Threads Extended ( WEBEX ) , também no inicializador. A diferença entre ambas é que a segunda opçao permite especificar maiores detalhes do ambiente de execução do serviço , permite a configuração de serviços e Web sites simultaneamente e multi-hosting . Quando nos utilizamos do server HTTP do Protheus apenas para Web Services , utilizamos com grande eficácia a configuração através da seção [webservices]

[WebServices]



Enable=0 ; Indica se o service está habilitado (1) ou não (0).Environment=ENVTESTE ; Indica qual environment do Server que irá

atender às requisiçõesConout=1 ; Permite a exibição de informações dos status internos do

serviço ( default = 0 : desabilitado ) Trace=1 ; Habilita a grevação de um arquivo de log ( wsstrace.log ) ,

contendo as informações sobre todas as chamadas e status do Web Service ( default = 0 )

PrepareIn=01,01 ; Permite especificar qual a empresa e filial do ERP serão utilizados para a montagem do ambiente de processamento das requisições.

NameSpace = http://localhost ; Permite especificar o nome do namespace utilizado pelo serviço ( default = host atualmente utilizado )

URLLocation = http://localhost ; Permite especificar a url responsável pelo atendimento ‘as solicitações de processamento do serviço ( default = host atualmente utilizado )

Para configurar o WebService manualmente , devemos além de habilitar o server http , devemos também configurar um Job do tipo WEBEX , apontando para funcoes internas de processamento dos WebServices , configurar um host cujas requisiçoes de links apw seram atendidas por este job. Veja exemplo do job abaixo :

[http] ; configuração do serviço httpEnable=1Port=80Path=c:\Ap7\Http

[localhost] ; Configuraçao do host localResponseJob=WSTESTE

[WSTESTE] ; Configuracao do jobTYPE=WEBEX ; Tipo do Job para WebServices deve ser WEBEX ONSTART=__WSSTART ; configuração fixa para webservicesONCONNECT=__WSCONNECT ; configuração fixa para webservices Environment=ENVTESTE ; Indica qual environment do Server que irá

atender às requisiçõesINSTANCES=2,5 ; Indica qual a quantidade minima (default ) e maxima

de threads ( ambientes ) que serão colocados no ar para atender à solicitações de processamento do serviço publicado.



http://localhost/

http://localhost/

Conout=1 ; Permite a exibição de informações dos status internos do serviço ( default = 0 : desabilitado )

Trace=1 ; Habilita a grevação de um arquivo de log ( wsstrace.log ) , contendo as informações sobre todas as chamadas e status do Web Service ( default = 0 )

PrepareIn=01,01 ; Permite especificar qual a empresa e filial do ERP serão utilizados para a montagem do ambiente de processamento das requisições.

NameSpace = http://localhost/ ; Permite especificar o nome do namespace utilizado pelo serviço ( default = host atualmente utilizado )

URLLocation = http://localhost/ ; Permite especificar a url responsável pelo atendimento ‘as solicitações de processamento do serviço ( default = host atualmente utilizado )

Web Services – Ponto de Entrada WSSTART

O ambiente de execução das Threads dos Web Services automaticamente monta um ambiente ERP , utilizando a empresa e filial especificadas no parametro PREPAREIN na configuração dos WebServices, quando informado o mesmo.

Caso seja necessário alguma inicialização especifica para as Threads destinadas ao Web Services , foi disponibilizado o Ponto de Entrada WSSTART(cERPEmp,cERPFil) . Vale lembrar que , quando compilamos este ponto de entrada no repositório de Objetos , cabe ào ponto de entrada realizar a inicialização do ambiente, de modo que o parâmetro PREPAREIN apenas será lido , e seu conteúdo será passado como parâmetro ao ponto de entrada.Caso o ponto de entrada seja compilado , e não seja preenchido o parametro PREPAREIN , o ponto de entrada receberá a empresa e/ou filial em branco (“”).



http://localhost/

http://localhost/

Treinamento ADVPL ASP - Webservice

Documents

Transcript of Treinamento ADVPL ASP - Webservice