Treinamento ADVPL ASP - Web Service

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

Introdução ........................................................................................................4
Repositório de Objetos......................................................................................4
APO (Advanced Protheus Object)................................................................…..4
Representação gráfica do processamento........................................................5
Ferramentas de Produção.................................................................................6
Capítulo 2 – Variáveis......................................................................................7
Introdução .........................................................................................................7
Nomenclatura das Variáveis .............................................................................7
Declarando Variáveis ........................................................................................7
Operadores .......................................................................................................8
Capítulo 3 – Estrutura da ADVPL ASP..........................................................09

Introdução …………….………….......................................................................09
Exemplo ...........................................................................................................09
Capítulo 4 – Estruturas de Controle ............................................................11

Instrução if .. then .. else ..elseif .....………………………………………….......11
Instrução Do case ...........................................................................................15
Loops............................……………………….…………………………….…......15
Capítulo 5 – Recuperando Dados enviados por Post e Get ......................16

Recuperando Dados com Metódo POST ................................……………......16
Recuperando Dados com Metódo GET ..........................................................18
Capítulo 6 – Acessando Base de Dados.....................................................22

Introdução ......................................................................................................22
Inserindo dados em uma tabela......................................................................24
Capítulo 7 – Web Services em ADVPL - CLIENT .......................................28

Introdução ......................................................................................................28

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

Introdução .....................................................................................................48
Termos Técnicos ..........................................................................................48
Definição do Serviço em Advpl - Server .......................................................49
Declaração de um Web Service – SERVER em Advpl.................................50
Regras para Nomenclatura dos Serviços / Estruturas / Dados e Métodos...51
Nomenclatura dos Serviços...........................................................................51
Nomenclatura de Estruturas..........................................................................51
Nomenclatura de Dados ( Campos ) ............................................................51
Tipos de Dados Básicos................................................................................52
Métodos ( Ações ) ........................................................................................53
Publicando um WEB Service no Protheus - Configuração...........................53
Web 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.
Repositório
APOs
.aph
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.
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.
Solicitação func.APW
Cliente
APOs AP7
Resposta HTML Web Server
(repositório)
A seguir dispomos os vários comportamento ou resposta do AP7 Server

para cada tipo de solicitação.
Extensão Descrição O que acontece Exemplo

do arquivo
Nenhuma Um endereço Ao chamar um endereço URL sem http://servidor/
http único, sem informar arquivo nenhum, o AP7 Server
um nome de irá procurar o arquivo chamado
arquivo definido. DEFAULT.HTM para enviar ao Web
Browser que efetuou o request.
.HTM;.HTML Páginas HTML, A página HTML, ou qualquer que seja o http://servidor/cadastro.h
ou outra arquivos texto, arquivo, será simplesmente enviado ao tm
extensão arquivos de Web Browser, sendo que este é o ou
qualquer. imagem, som, responsável pela sua http://servidor/imagem.gif
vídeo, etc. tradução/interpretação.
.APW É uma chamada Quando o AP7 Server receber um http://servidor/acerto.apw
direta a uma request deste tipo, a função chamada (no ou
função do exemplo func.apw, a função chamada é http://servidor/runprog.ap
repositório do func, sem a extensão) será executada no w
AP7. 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.
.APH É uma chamada Uma página Advpl ASP é uma página http://servidor/activep.ap
para uma página HTML mesclada com código executável w
ativa (uma ou interpretável no server. Tais páginas ou
página em são criadas utilizando qualquer editor de http://servidor/cadastro.a
ADVPL ASP). texto ou editor HTML, e devem ter pw
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
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://nomedo_server:82/u_RetDate.apw
Programa: U_RetDate.apw
Nomenclatura 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 RetDate
Autor Antonio
Data 07/09/2003
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 **obrigatorio

Web 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 ** obrigatorio

Web EXTENDED End
Return 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()

2
3 Local cHTML:=""
4
5 Web Extended Init cHtml
6
7 cHTML:= l_ex001() // ou h_ex001()
9 Web EXTENDED End
10
11 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>

3
4 <%
5 local n
6
7 n := left(time(),2)
8 if val(n) < 12
9 %>
10 Bom Dia !!!
11 <%
12 Else
13 %>
14 Boa Tarde !!!
15 <%
16 Endif
17 %>
18
19 </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.
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.
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 Case
Case <primeira condição >
<instrucoes>
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
2
3 Local cHTML:=""
4 Private cNome, cIdade
5
6 cNome := HttpSession->field_nome
7 cIdade := HttpSession->field_idade
8
9 WEB EXTENDED INIT cHtml
10
11 cHTML:= H_teste001()
12
13 WEB EXTENDED END
14
15 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 Get
Vamos 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>

<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>
size="2">Sobrenome:</font></td>
<td width="83%">
<input type="text" name="field_snome">
</td>
</tr>
size="2">Curso:</font></td>
<td width="83%">
<input type="text" name="field_curso">
</td>
</tr>
<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.

2
3 Local cHTML:=""
4 Private cNome, cSNome, cCurso
5
7 cNome := HttpGet->field_nome
8 cSNome := HttpGet->field_snome
9 cCurso := HttpGet->field_curso
10
11 cHTML:=H_ex003()
12
13 Web Extended End
14
15 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

atribuindo o retorno dela a variável cSNome.
Na linha 7 temos o seguinte código cCurso := HttpGet->field_curso

atribuindo o retorno dela a variável cCurso.
Agora vamos escrever o código do arquivo APH
<html>

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

2
3 Local cHTML:=""
4
6
8 cHTML:= h_ex004
9
10 Web Extended End
11
12 Return cHTML
Arquivo ex004.aph
<html>
<table width="75%" border="0" cellpadding="0" cellspacing="1" bgcolor="#EEEEEE">
<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>
<td>
<div align="center"><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2"
color="#FFFFFF">Código</font></b></div>
</td>
<td>
color="#FFFFFF">Descrição</font></b></div>
</td>
<td>

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>
<form method="POST" action="http://localhost/w_ex005.apw">
<table width="22%" align="center">
<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>
size="2">Cod:</font></td>
<td width="83%">
<input type="text" name="field_cod">
</td>
</tr>
size="2">Descricao:</font></td>
<td width="83%">
<input type="text" name="field_descr">
</td>
</tr>
size="2">Qtde. Estoque:</font></td>
<td width="83%">

<input type="text" name="field_qtdest">
</td>
</tr>
<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.

2
3 Local cHTML:=""
4 Local cCod, cDescr, nQtdEst
5
7
9
10 // Recupera os dados do formulário.
11 cCod := HttpPost->field_cod
12 nQtdEst := HttpPost->field_qtdest
13 cDescr := HttpPost->field_descr
14
15 // Grava os dados.
16 If RecLock('FA2',.t.)
17 FA2->FA2_COD := cCOD
18 FA2->FA2_DESCR := cDescr
19 FA2->FA2_QTDEST := val(nQtdEst)

20 MSUnlock()
22 cHTML:=H_ex004
Else
CHtml := WebAlert(“Erro ao incluir registro.”)
Endif
23
24 Web Extended End
25
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 de

acesso a objetos. O SOAP é um padrão aberto, baseado em XML, criado pela
Microsoft, 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ão
padronizador da Internet - . A linguagem WSDL define regras baseadas em XML
para descrever serviços web.
WEB SERVICES - programa completo ou componente de software residente
num servidor web.
XML - Sigla de Extensible Markup Language, o XML é uma linguagem baseada
em tags semelhante ao HTML. Sua principal característica é a extensibilidade.
Quem
emite um documento XML pode criar tags personalizadas, que são explicadas
num
documento anexo, que tem extensão XSD.
XSD - Sigla de XML Schema Definition. Arquivo associado a um documento
XML 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>
<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
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:29
Observaçõ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 NEW
WSMETHOD GETSERVERTIME
WSDATA _URL AS String

WSDATA 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 WSSERVERTIME
Local 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 := NIL
Return .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"
2
3 User Function TestClient()
4 Local oSvc := NIL
5
6 oSvc := WSSERVERTIME():New()
7
8 If oSvc:GETSERVERTIME()
9 alert("Horário no Servidor : "+ oSvc:cGETSERVERTIMERESULT)
10 Else
11 alert("Erro de Execução : "+GetWSCError())
12 Endif
13
14 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 Service
Linha 4 Declaramos uma variável local para conter o Objeto do Web Service
Client

Linha 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 /
DOCUMENT

NameSpace http://automan:8000/webservice/
SoapAction http://automan:8000/webservice/GETSERVERTIME
Called 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/en
velope/"> <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.or
g/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:so
ap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><GET
SERVERTIMERESPONSE
xmlns="http://automan:8000/webservice/"><GETSERVERTIMERESULT
>10:37:10</GETSERVE
RTIMERESULT></GETSERVERTIMERESPONSE></soap:Body></soap:En
velope>
-------------------------------------------------------------------------------
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.

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>

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.

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.

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.

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.

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>

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

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.

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.

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
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
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 é

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

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.

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.

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.

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.

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 de

acesso a objetos. O SOAP é um padrão aberto, baseado em XML, criado pela
Microsoft, 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ão
padronizador da Internet - . A linguagem WSDL define regras baseadas em XML
para descrever serviços web.
WEB SERVICES - programa completo ou componente de software residente
num servidor web.
XML - Sigla de Extensible Markup Language, o XML é uma linguagem baseada
em tags semelhante ao HTML. Sua principal característica é a extensibilidade.
Quem
emite um documento XML pode criar tags personalizadas, que são explicadas
num
documento anexo, que tem extensão XSD.
XSD - Sigla de XML Schema Definition. Arquivo associado a um documento
XML 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 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ções
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 )
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 http

Enable=1
Port=80
Path=c:\Ap7\Http
[localhost] ; Configuraçao do host local

ResponseJob=WSTESTE
[WSTESTE] ; Configuracao do job

TYPE=WEBEX ; Tipo do Job para WebServices deve ser WEBEX
ONSTART=__WSSTART ; configuração fixa para webservices
ONCONNECT=__WSCONNECT ; configuração fixa para webservices
Environment=ENVTESTE ; Indica qual environment do Server que irá
atender às requisições
INSTANCES=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.
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 (“”).


Treinamento ADVPL ASP - Web Service

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Treinamento ADVPL ASP - Web Service

Enviado por

Direitos autorais:

Formatos disponíveis

Curso de Introdução a Plataforma

Aprenda de uma forma simples ,

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

Capítulo 1 – Arquitetura da ADVPL ASP ..................................................... 4

Capítulo 3 – Estrutura da ADVPL ASP..........................................................09

Capítulo 4 – Estruturas de Controle ............................................................11

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

Capítulo 6 – Acessando Base de Dados.....................................................22

Capítulo 7 – Web Services em ADVPL - CLIENT .......................................28

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

Capítulo 8 – Web Services em ADVPL - SERVER ....................................48

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

Uma característica fundamental da ADVPL ASP é que o script é

O repositório do AP7 é um conjunto de Objetos ADVPL ASP (APOs)

APO (Advanced Protheus Object)

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

Quando uma URL é requisitada através de um Browser (seja através de

Representação gráfica do processamento.

A seguir dispomos os vários comportamento ou resposta do AP7 Server

Extensão Descrição O que acontece Exemplo

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

Para aculturar-se em ADVPL ASP é fundamental ter conhecimento em

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

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

Nomenclatura das variáveis

No Hypersite seguimos uma padronização de nomenclaturas para facilitar

nXXXX = variável Numeric (númerico). Quando você se deparar com uma

cXXXX = variável Char ou String (texto). Quando você se deparar com

lXXXX = variável logic (lógico). Quando você se deparar com uma

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

Utiliza-se uma variável Public quando há necessidade de armazenar o

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

Capítulo 3 – Estrutura da ADVPL ASP

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

Todas as páginas escritas deverão ser referenciadas a um programa APL

Montaremos a seguir um programa fonte simples que retorna a Data do

Endereço do Server: http://nome_do server. Informa o endereço do server

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

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

//comentarios sobre autor, data, descrição, retorno, etc. Opcional

Local cHtml //declaração da variável de retorno

// Inicializacao do Ambiente **obrigatorio

cHtml := Date() //atribui a data do Sistema. Normalmente palavras

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

// Fechamento de ambiente ** obrigatorio

Capítulo 4 – Estruturas de Controle

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

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

Exercício: Vamos exemplificar a condição IF. O programa a seguir vai verificar

1. Vamos criar um novo Projeto no AP7 IDE.

3. Este código abaixo será o nosso arquivo .apw, portanto ao salvá-lo

1 User Function ex001()

Na linha 1 temos a declaraçäo de uma User function , montada para ser

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

Na linha 5 chamamos o comando Web Extended Init, que inicializa o

Na linha 7 atribuímos à variável cHTML o retorno da função l_ex001 (para

Na linha 9 chamamos o comando WEB EXTENDED END, que informa ao

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

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

Na linha 1 e 2 encontramos as tags <html> e <body> que como vimos faz

Na linha 4 temos o indicador de script (<%), que tem como objetivo

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()

Na linha 8 utilizamos a condição IF para verificar se n é menor que 12,