Você está na página 1de 60

Curso de Introduo 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 aplicaes
baseadas na Web. Alm de apresentar
os principais conceitos Webservice
incluindo exemplos de Montagem de um
Cliente em Protheus.

Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

ndice Analtico
Captulo 1 Arquitetura da ADVPL ASP ..................................................... 4
Introduo ........................................................................................................4
Repositrio de Objetos......................................................................................4
APO (Advanced Protheus Object)..................................................................4
Representao grfica do processamento........................................................5
Ferramentas de Produo.................................................................................6
Captulo 2 Variveis......................................................................................7
Introduo .........................................................................................................7
Nomenclatura das Variveis .............................................................................7
Declarando Variveis ........................................................................................7
Operadores .......................................................................................................8
Captulo 3 Estrutura da ADVPL ASP..........................................................09
Introduo ........................................................................09
Exemplo ...........................................................................................................09
Captulo 4 Estruturas de Controle ............................................................11
Instruo if .. then .. else ..elseif ............11
Instruo Do case ...........................................................................................15
Loops....................................15
Captulo 5 Recuperando Dados enviados por Post e Get ......................
16
Recuperando Dados com Metdo POST ......................................16
Recuperando Dados com Metdo GET ..........................................................18

Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Captulo 6 Acessando Base de Dados.....................................................22


Introduo ......................................................................................................22
Inserindo dados em uma tabela......................................................................24
Captulo 7 Web Services em ADVPL - CLIENT .......................................28
Introduo ......................................................................................................28
Termos Tcnicos ...........................................................................................28
Definio do Servio em Advpl - Client .........................................................29
Passos para a utilizao do Fonte - Client ....................................................29
Passo 1 : Determinar como obter o WSDL do servio desejado...................30
Passo 2 : Gerar o Fonte AdvPl do Client usando o Assistente do IDE .........31
Passo 3 : Criar um fonte para a obteno do horrio ...................................34
Passo 4 : Executar o programa de testes......................................................35
Passo 5 : Obter informaes de debug........................................................36
Web Services Client Codigos de Erro.........................................................38
Captulo 8 Web Services em ADVPL - SERVER ....................................48
Introduo .....................................................................................................48
Termos Tcnicos ..........................................................................................48
Definio do Servio em Advpl - Server .......................................................49
Declarao de um Web Service SERVER em Advpl.................................50
Regras para Nomenclatura dos Servios / Estruturas / Dados e Mtodos...51
Nomenclatura dos Servios...........................................................................51
Nomenclatura de Estruturas..........................................................................51
Nomenclatura de Dados ( Campos ) ............................................................51
Tipos de Dados Bsicos................................................................................52
Mtodos ( Aes ) ........................................................................................53
Publicando um WEB Service no Protheus - Configurao...........................53
Web Services Ponto de Entrada WSSTART.............................................55

Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Captulo 1 - Arquitetura da ADVPL ASP


Introduo
Uma pgina ASP (Active Server Pages) uma pgina HTML contendo
cdigo interpretveis em uma linguagem compreensvel ao servidor
HTTP em uso. Por exemplo, o IIS (Internet Information Server) da
Microsoft recepciona scripts em VBScript ou o JavaScript para criar suas
pginas ASP, do mesmo modo que o AP7 Web Server recepciona a
ADVPL ASP. Uma pgina ASP uma combinao de script HTML e
cdigo interpretvel. No ADVPL ASP esse cdigo padro xBase,
portanto a preocupao maior daqueles que j conhecem e trabalham
com o AP7 e desejam desenvolver pginas ativas para aplicaes Web
utilizando essa facilidade conhecer HTML.
Uma caracterstica fundamental da ADVPL ASP que o script
executado no servidor, protegendo totalmente a propriedade intelectual e
tambm eliminando o trabalho do programador de se preocupar com qual
browser o usurio estaria utilizando para visualizar as pginas, devido a
incompatibilidade. Outra caracteristica o processamento do lado do
servidor.
Repositrio de Objetos
O repositrio 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 aplicao.
Repositrio

Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

APOs
.aph

APO (Advanced Protheus Object)


O APO conhecido como um Objeto ou um programa ADVPL. Um
conjunto de APOs formam um repositrio que esto armazenados dentro
do AP7 Web Server conforme descrito anteriormente.
Quando uma URL requisitada atravs de um Browser (seja atravs de
um Formulrio HTML, um link ou diretamente atravs do campo de URL
do Browser), essa requisio recebida pelo AP7 Server que a tratar do
seguinte modo:

Representao grfica do processamento.


Solicitao func.APW

Cliente
AP7
Resposta HTML

APOs
(repositrio
)

Web Server

A seguir dispomos os vrios comportamento ou resposta do AP7 Server


para cada tipo de solicitao.
Extenso
do arquivo
Nenhuma

Descrio

O que acontece

Exemplo

Um endereo http Ao chamar um endereo URL sem


http://servidor/
nico, sem um
informar arquivo nenhum, o AP7 Server
nome de arquivo ir procurar o arquivo chamado
definido.
DEFAULT.HTM para enviar ao Web
Browser que efetuou o request.

Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

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

.APH

Pginas HTML,
arquivos texto,
arquivos de
imagem, som,
vdeo, etc.
uma chamada
direta a uma
funo do
repositrio do
AP7.

A pgina HTML, ou qualquer que seja o http://servidor/


arquivo, ser simplesmente enviado ao cadastro.htm
Web Browser, sendo que este o
ou
responsvel pela sua traduo/
http://servidor/
interpretao.
imagem.gif
Quando o AP7 Server receber um
http://servidor/
request deste tipo, a funo chamada acerto.apw
(no exemplo func.apw, a funo
ou
chamada func, sem a extenso) ser http://servidor/
executada no AP7 Server configurado runprog.apw
na chave [nome_do_server].
O que dever ser retornado pela funo
uma string, que ser enviada para o
Web Browser.

uma chamada Uma pgina Advpl ASP uma pgina http://servidor/


para uma pgina HTML mesclada com cdigo executvel activep.apw
ativa (uma pgina ou interpretvel no server. Tais pginas ou
em ADVPL ASP). so criadas utilizando qualquer editor http://servidor/
de texto ou editor HTML, e devem ter cadastro.apw
SEMPRE a extenso .APH. Devem ser
compiladas atravs do AP7 IDE.
Durante a compilao, o AP7 Server
transforma essa pgina em uma funo
interna que ser executada da mesma
maneira que aquelas chamadas .apw
explicadas anteriormente.
Como so funes tambm, as pginas
em Advpl ASP devem ser chamadas do
Web Browser com a extenso .apw

Ferramentas de Produo
Para aculturar-se em ADVPL ASP fundamental ter conhecimento em
HTML, pois uma pgina sempre haver cdigo ADVPL ASP mesclado
com HTML.
Os arquivos que contm o cdigo para gerar as pginas de seu site so
arquivos texto, portanto, voc pode utilizar qualquer editor de texto do
mercado.
Utilizaremos o AP7 IDE para escrever nossos cdigos ADVPL ASP com
HTML, porem utilizaremos tambm uma ferramenta que nos auxilie no
HTML. Existem vrias no mercado, mas as mais familiares so
Dreamweaver da Macromedia, FrontPage e o Visual Studio da Microsoft
entre outros .
Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Captulo 2 - Variveis
Introduo
Variveis um espao temporrio na memria RAM que pode ser
manipulado.
Nomenclatura das variveis
No Hypersite seguimos uma padronizao de nomenclaturas para facilitar
o entendimento dos complexos scripts.
nXXXX = varivel Numeric (nmerico). Quando voc se deparar com uma
varivel que possui o prefixo n significa que o contedo dela um valor
nmerico. Ex.: nVLUN = 100
dXXXX = varivel Date (data). Quando voc se deparar com uma varivel
que possui o prefixo d significa que o contedo dela uma data. Ex.:
dDTPG = 14/08/2000
cXXXX = varivel Char ou String (texto). Quando voc se deparar com
uma varivel que possui o prefixo c significa que o contedo dela um
texto. Ex.: cDTPG = Makira
lXXXX = varivel logic (lgico). Quando voc se deparar com uma
varivel que possui o prefixo l significa que o contedo dela um valor
lgico (verdadeiro ou falso). Ex.: lATIVO = F
Declarando variveis
A declarao das variveis obrigatrio na ADVPL ASP. H dois tipos de
variveis a Local e a Private.
Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Utiliza-se uma varivel Public quando h necessidade de armazenar o


contedo dela durante toda a navegao do usurio dentro do site, ao
contrrio da Local que utilizada momentaneamente.
Operadores

Operador
=
==
:=
!= ou <>

Descrio
Comparao (igual)
Comparao (exatamente igual)
Atribuio
Diferente

Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Captulo 3 Estrutura da ADVPL ASP

Introduo
Todas as pginas escritas devero 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 descrio de
cada parte da chama.
Endereo do Server: http://nome_do server. Informa o endereo do server
onde esta compilada a pgina. Por default o server esta na porta 80
portanto no necessrio informar a porta, caso contrario a porta deveria
ser informa com : (dois pontos) e o nmero da porta aps 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 (Funo de Usurio). W_
(Web Function) e (Function) so exclusiva para o desenvolvimento interno
da Microsiga Software S\A. Portanto clientes no conseguiram compilar
Web Function e Function, somente User Function.
nnnnnnn: nome da Funo
Curso de Introduo a Plataforma ADVPL/ASP WebService

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

.apw: extenso de uma pgina ADVPL ASP

#INCLUDE "PROTHEUS.CH" //Include obrigatrio


#INCLUDE "APWEBSRV.CH" //Include obrigatrio
#INCLUDE "WEBEXDEFS.CH" //Include obrigatrio
//comentarios sobre autor, data, descrio, 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 //declarao da varivel 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 so palavras reservadas ou funes
do internas do sistema.
[ Espaco reservado para o processamento, criao de cursores , etc,,, ]

Curso de Introduo a Plataforma ADVPL/ASP WebService

10

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

// Fechamento de ambiente ** obrigatorio


Web EXTENDED End
Return cHtml // Esse ser o retorno da Funo RetDate

Captulo 4 Estruturas de Controle


Instruo if .. then .. else ..elseif
A ADVPL ASP suporta as seguintes estruturas de deciso:
IF <condio>
<Instruo>
Elseif
<Instruo>
Else
<Instruo>
Endif
Exerccio: Vamos exemplificar a condio IF. O programa a seguir vai verificar se
no momento da execuo a hora for menor que 12 hs ento enviar a
mensagem Bom dia ! caso contrrio a mensagem ser Boa tarde !.
1. Vamos criar um novo Projeto no AP7 IDE.
a. Selecione a opo do menu Projetos e em seguida Novos
2. Digite o seguinte script e logo a seguir leia a explicao passo a passo:
Obs.: Em todos os scripts contidos nesta documentao ser utilizado a
numerao de linhas para fazer referncia s linhas do cdigo facilitando
a explicao, portanto, ao inseri-lo no considere os nmeros.
3. Este cdigo abaixo ser o nosso arquivo .apw, portanto ao salv-lo
informe a sua extenso.

Curso de Introduo a Plataforma ADVPL/ASP WebService

11

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

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 declarao de uma User function , montada para ser


chamada atraves do Browser. Na sua declaracao, ela ganha um prefixo
(U_) Daremos o nome para nossa funo de ex001.
Na linha 3 definimos a varivel cHTML como local e sem contedo 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 utilizao das demais funcoes, entre outras funcionalidades
posteriormente explanadas. Esta funo obrigatria.
Na linha 7 atribumos varivel cHTML o retorno da funo l_ex001 (para
ex001.aph) ou h_ex001 (para ex001.ahu), retornando o HTML . O que
diferncia a necessidade de uma ou outra Sintax o ambiente de
compilao: para arquivos compilados localmente nos cliente eles devem
ser obrigatriamente .AHU para os compilados na Microsiga ambos so
aceitos.
Na linha 9 chamamos o comando WEB EXTENDED END, que informa ao
servidor para fechar o ambiente . Esta funo obrigatria. Entre outras
funcionalidades internas, a WEB EXTENDED END coloca no Html
identificadores internos, tratamentos de erro, entre outros, indispensvel
para o funcionamento do mecanismo como um todo. Nao deve haver
mais nenhum processamento apos WEB END
Na linha 11 obtemos o retorno da varivel cHTML, que devolvido para o
Browser.
4. Agora, nos vamos escrever o cdigo do arquivo APH (ou AHU) , portanto,
salve este novo arquivo
como ex001.aph (ou ex001.ahu). Neste
Curso de Introduo a Plataforma ADVPL/ASP WebService

12

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

momento estaremos solicitando ao servidor a hora atual se a hora atual


for menor que 12 ento enviaremos a seguinte mensagem ao usurio
Bom dia !!! se a hora for maior que 12 ento ser enviado a seguinte
mensagem ao usurio Boa tarde !!!. Note que, sempre que houver a
necessidade de enviar uma informao ao browser processada a partir de
um arquivo .apw, essa informao 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 cdigo ADVPL
ASP a ser executado. Sempre que for iniciar um script ADVPL ASP utilizase o indicador (<%) e para finalizar um script utiliza-se o indicador (%>).
Curso de Introduo a Plataforma ADVPL/ASP WebService

13

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Na linha 5 estamos declarando a varivel n como uma varivel local.


Na linha 7 temos o cdigo n := left(time(),2). Utilizamos a funo time()
para retornar a hora atual no formato hh:mm:ss, utilizamos a funo left
(string,posio) para retornar apenas as horas (hh) do contedo da
funo time(). Este contedo ser armazenado na varivel n
Na linha 8 utilizamos a condio 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 cdigo com o indicador (<
%)
Na linha 12 colocamos o comando Else que faz parte da condio IF. Que
executado se a condio inicial no for verdadeira.
Na linha 13 colocamos novamente o indicado (<%) para iniciar um bloco
de cdigo.
Nas linhas 14 e 15 colocamos a mensagem a ser enviada ao usurio
caso a condio em IF for falsa e fechamos o bloco de cdigo.
Na linha 16 encerramos a condio IF com ENDIF.
Na linhas 17 e posteriores encerramos o bloco de cdigo e tambm
informamos ao browser que o documento HTML acaba por aqui.
ATENO: sempre que for finalizado um programa deve-se compilar
o mesmo. neste processo que o repositrio 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:
Curso de Introduo a Plataforma ADVPL/ASP WebService

14

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Servidor: o nome do servidor onde est instalado o AP7 Web


Server
Porta: o nmero da porta que o administrador configurou o AP7
Web Server, est informao 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 no ser que alteremos as
configuraes iniciais para habilitar o servidor em uma porta diferente da
80

Instruo Do case
Outra estrutura que veremos agora a instruo Case que funciona da
mesma maneira que a instruo IF. Possibilitando criar lista de
expresses para cada condio.
A estrutura da instruo Case a seguinte:
Do Case
Case <primeira condio >
<instrucoes>
Case <segunda condio >
<instrues>
Otherwise
<instrues>
EndCase
Loops
Os Loops so utilizados quando h a necessidade de percorrer n vezes o
mesmo conjunto de instrues. Muito utilizado por exemplo para ler um
bloco de registros em uma base de dados.
For <varivel> := <incio> to <fim> [ step <passo> ]
<Instruo>
Curso de Introduo a Plataforma ADVPL/ASP WebService

15

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Next
O parmetro step no obrigatrio, e indica qual o incremento utilizado
para a variavel. (default=1)
While <condio>
<Instruo>
Enddo

Captulo 5 Recuperando Dados enviados por Post e Get


Recuperando Dados com Metdo POST
Formulrio uma pgina HTML contendo controles de entrada como
textbox, listbox, radio buttom, check buttom e botes de execuo.
A finalidade de se utilizar um formulrio manipular de alguma forma os
dados informados pelo usurio. Para isso temos em ADVPL ASP funes
com a RQryStr, que nos retorna o conteudo de cada campo.
H dois mtodos para se retornar o contedo de um formulrio, o mtodo
POST e o GET, o primeiro que tem como caracterstica passar o contedo
dos campos de maneira oculta, no aparece na linha de URL do browser.

HttpPost-><NOME DA VARIVEL>
HttpGet-><NOME DA VARIVEL>
HttpSession-><NOME DA SESSO>
Descrio: retorna o contedo dos campos de um formulrio.
Parmetros:
<NOME DA VARIVEL> informe o nome do campo
informado na propriedade name do formulrio.

Curso de Introduo a Plataforma ADVPL/ASP WebService

16

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Exerccio: Vamos exemplificar a recuperao de dados utilizando o


mtodo POST
Vamos criar um formulrio em HTML. Note que informaremos o mtodo
POST e a ao 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 cdigo em ADVPL ASP para nosso arquivo APW
1 User Function ex002()
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 funo User Function, sempre


obrigatria.
Nas linhas 2 e 3 estamos definindo as variveis a serem utilizadas no
cdigo. Note que as variveis cNome e cIdade so do tipo Private que
tambm podem ser lidas no APH.
Curso de Introduo a Plataforma ADVPL/ASP WebService

17

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Na linha 6 estamos atribuindo para a varivel cNome o conteudo do


campo field_nome utilizando a funo HttpPost-><NOME DA VARIVEL>.
O mesmo serve para a linha 7.
As linhas 9,11,13 e 15 j foram explicadas nos exerccios anteriores.
Agora vamos escrever o cdigo 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 incio de um bloco de cdigo ADVPL ASP, onde estamos retornando
ao browser o conteudo da varivel cNome, que neste momento est
armazenada a string que voc digitou no campo nome do formulrio.
O processamento deste exerccio simples, entenda que no primeiro
momento apresentamos uma documento HTML com um formulrio com
os campos Nome e Idade para o usurio preencher, aps o usurio
informar os dados e clicar no boto Enviar, enviado uma solicitao ao
servidor para ele executar a User Function ex002 que informamos na
propriedade action do formulrio. Quando est solicitao chega ao
servidor o mesmo j possui o conteudo dos campos do formulrio e como
nos codificamos, atribumos o conteudo das variveis com o conteudo
dos campos e finalmente apresentamos o conteudo delas ao usurio
utilizando o arquivo APH (ou AHU).

Recuperando Dados com Metdo GET


O mtodo GET passa o contedo dos campos do formulrio atravs da
URL. O contedo dos campos sero retornados no parmetro HttpGet><NOME DA VARIVEL>.

Curso de Introduo a Plataforma ADVPL/ASP WebService

18

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

A diferena bsica entre o mtodo Get e o Post que o primeiro mostra


na linha de URL do browser o contedo dos campos informados no
formulrio, podendo ser visualizado pelo usurio.
Exerccio 003: Vamos exemplificar a recuperao de dados utilizando o
mtodo Get
Vamos criar um formulrio em HTML. Note que informaremos o mtodo
GET e a ao 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, sansserif"><b><font color="#FFFFFF">MET&Oacute;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%">
Curso de Introduo a Plataforma ADVPL/ASP WebService

19

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

<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%">&nbsp;</td>
</tr>
</table>
</form>
</body>
</html>
Agora vamos escrever o cdigo do arquivo apw.
1 User Function ex003()
2
3
Local cHTML:=""
4
Private cNome, cSNome, cCurso
5
6
Web Extended Init cHtml
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 funo User Function, sempre


obrigatria.
Na linha 6 estamos chamando o comando Web Extended Init cHtml para
iniciar um ambiente de trabalho web.
Na linha 7 temos o seguinte cdigo cNome := HttpGet->field_nome
que est chamando a funo HttpGet-> enviando os dois parmetros e
atribuindo o retorno dela a varivel cNome.
Na linha 8 temos o seguinte cdigo cSNome := HttpGet->field_snome
que est chamando a funo HttpGet-> enviando os dois parmetros e
atribuindo o retorno dela a varivel cSNome.
Curso de Introduo a Plataforma ADVPL/ASP WebService

20

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Na linha 7 temos o seguinte cdigo cCurso := HttpGet->field_curso


que est chamando a funo HttpGet-> enviando os dois parmetros e
atribuindo o retorno dela a varivel cCurso.

Agora vamos escrever o cdigo do arquivo APH


<html>
<body bgcolor="#FFFFFF">
<table width="75%">
<tr>
<td colspan="2">
<div align="left"><b>Dados informados no formul&aacute;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>

Curso de Introduo a Plataforma ADVPL/ASP WebService

21

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Captulo 6 Acessando Base de Dados


Introduo
H duas maneiras de acessar e manipular uma base de dados, uma
utilizando o CodeBase (.DBF) outra maneira atravs do TOPCONNECT
que possibilita o acesso a vrios banco de dados (SQL, INFORMIX, etc).
Exerccio 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 funo vista.
1 User Function ex004()
2
3
Local cHTML:=""
4
5
Web Extended Init cHtml
6
8
cHTML:= h_ex004
9
10 Web Extended End
11
12 Return cHTML
Arquivo ex004.aph
<html>
<body bgcolor="#FFFFFF">
<table width="75%" border="0" cellpadding="0" cellspacing="1" bgcolor="#EEEEEE">
<tr bgcolor="#003366">
Curso de Introduo a Plataforma ADVPL/ASP WebService

22

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

<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&oacute;digo</font></b></div>
</td>
<td>
<div align="center"><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2"
color="#FFFFFF">Descri&ccedil;&atilde;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&aacute;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 cdigo em negrito, o comando dbselectarea('FA2')


seleciona a tabela FA2 que contm 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
execuo do cdigo adiante at que a condio !Eof() (End of File) for
Curso de Introduo a Plataforma ADVPL/ASP WebService

23

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

verdadeira. As instrues dentro do loop so para retornar o contedo dos


campos FA2_COD, FA2_DESCR e FA2_QTDEST dentro das Tags <td>. E
finalmente executamos o comando dbskip() que posiciona-se no prximo
registro.

Inserindo dados em uma tabela


Exerccio 5 Vamos fazer um exerccio 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 formulrio para que o usurio insira os dados (cdigo
do produto, descrio 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, sansserif"><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%">
Curso de Introduo a Plataforma ADVPL/ASP WebService

24

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

<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%">&nbsp;</td>
</tr>
</table>
</form>
</body>
</html>
Note que neste cdigo utilizamos o mtodo POST no formulrio, visto
anteriormente nesta apostila.
Agora vamos escrever o cdigo do arquivo .apw, nele que iremos escrever
os comandos para recuperar os dados enviados pelo formulrio e em
seguida grava-los na base de dados.
1 User Function ex005()
2
3
Local cHTML:=""
Curso de Introduo a Plataforma ADVPL/ASP WebService

25

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

4
5
6

Local cCod, cDescr, nQtdEst


Web Extended Init cHtml

7
9
10 // Recupera os dados do formulrio.
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 variveis como locais que sero
utilizadas no decorrer do programa;
Na linha 6 estamos comunicando ao AP7 Web Server que ser
inicializada uma conexo web;
Na linha 10 temos um comentrio. Tudo que estiver aps os caracteres
// e na mesma linha no sero considerados no momento da
compilao;
Nas linhas 11,12 e 13 estamos recuperando os dados enviados para o
Server atravs do formulrio. Os dados cdigo do produto, descrio do
produto e quantidade em estoque sero armazenados nas variveis
cCod, cDescr e nQtdEst respectivamente. Note que a varivel nQtdEst
Curso de Introduo a Plataforma ADVPL/ASP WebService

26

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

inicia a sua nomenclatura com o caracter n porque a mesma uma


varivel do tipo nmerica.
Na linha 15 temos outro comentrio.
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 usurio que esteja executando o
mesmo programa grave no mesmo nmero de registro. Este comando
retornar .t. (true) se a condio for verdadeira, ou seja se ningum
estiver tentando gravar no mesmo nmero de registro;
Na linha 17 estamos gravando o conteudo da varivel 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 varivel 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 varivel nQtdEst em um valor nmerico.
Na linha 20 estamos liberando o registro para ser manipulado com o
comando MSUnLock().
Na linha 22 note que estamos solicitando a execuo do arquivo ex004,
ou seja, este arquivo foi escrito no exerccio anterior e tem como objetivo
listar os registros da base de dados FA2, concluindo, estamos reutilizando
o cdigo do exerccio anterior para finalizar o nosso programa.

Curso de Introduo a Plataforma ADVPL/ASP WebService

27

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Captulo 7 Web Services em ADVPL - CLIENT


Introduo
Quando um Web Service criado e disponibilizado , junto dele tambm
disponibilizada a definio do servio , 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
necessrios o processamento do Servio , realizar a chamada , e tratar o
respectivo retorno e excesses .
Embora existam Web Services que podem ser acessados via Http
direto , apenas passando parmetros via URL , o Client de Web Services do
Advanced Protheus tm seu foco e recursos direcionados apenas servios que
possuam interface de comunicao que realize POST de pacotes de dados XML
em formato SOAP.
Termos Tcnicos
SOAP - Sigla de Simple Objetc Access Protocol, ou protocolo simples de
acesso a objetos. O SOAP um padro aberto, baseado em XML, criado pela
Microsoft, Ariba e IBM para padronizar a transferncia de dados entre
aplicaes.
Pode ser usado em combinao com vrios outros protocolos comuns da
Internet,
Curso de Introduo a Plataforma ADVPL/ASP WebService

28

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

como HTTP e SMTP.


WSDL - Web Service Description Language. Submetida W3C - o rgo
padronizador da Internet - . A linguagem WSDL define regras baseadas em XML
para descrever servios 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 caracterstica a extensibilidade.
Quem
emite um documento XML pode criar tags personalizadas, que so explicadas
num
documento anexo, que tem extenso 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 programao, os XSDs aceitam dados de diferentes tipos, como nmeros,
data e moeda.

Definio do Servio em Advpl - Client


Para a criao do cdigo-fonte de um Client de um Web Service , foi
criada uma ferramenta de gerao automtica do fonte a partir da definio do
Servio (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
definies dos mtodos / aes do servio , a(s) estrutura(s) utilizada(s) no
mesmo , e a(s) classe(s) intermediria(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 atravs de pacotes SOAP.
O Fonte gerado atravs do assistente de criao de fonte deve
preferencialmente ser gerado e compilado em um arquivo exclusivo , destinado
unica e exclusivamente a este cdigo. E , por tratar-se de uma classe Advpl
gerada a partir da definio de um servio , no devemos inserir e/ou alterar
nenhuma das definies geradas pelo assistente , pois as mesmas sero
perdidas caso o fonte seja gerado novamente .

Passos para a utilizao do Fonte - Client


Curso de Introduo a Plataforma ADVPL/ASP WebService

29

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Partindo de uma classe de Web Services Client , gerado com o Assistente


de Services Client do IDE , devemos seguir alguns passos para a utilizao
desta classe em nosso sistema. So eles :
1 Criar uma varivel ( preferncialmente local ) para armazenar o objeto do
Web Service
2 Inicializar o objeto do WebSErvice ( WsServico():New() )
3 Verificar os parmetros e seus respectivos tipos a serem utilizados no
mtodo , declarados no servio.
4 Atribuir no(s) parametro(s) necessrios chamada do mtodo ps valores
desejados ou chame diretamente o mtodo , passando os parametros
necessrios na chamada do mesmo.
5 Verficar o retorno do mtodo . Caso este tenha retornado .T. , o
processamento foi executado com sucesso e a(s) propriedade(s) de
retorno do mtodo est(o) alimentada(s)
6 Caso retorne .F. , ocorreu uma falha na requisio e/oui processamento
do Servio . Para recuperar os detalhes da falha , utilizamos a funcao
GetWSCError()

Criao de um Web Service CLIENT Passo a Passo


Objetivo : Criar um WebService Client em Advpl , que utilize o servio
exemplificado no tpico Criao de um WebService SERVER passo a passo.

Passo 1 : Determinar como obter o WSDL do servio desejado


A maioria das definies WSDL dos servios disponiveis na WEB so
acessados atravs de uma URL , em geral apontando para o servidor onde o
servio est publicado , contendo o nome do servio na url e um sufixo ?WSDL
ou .WSDL na Url. No h padro definido para tal , de modo que cada servidor
pode disponibilizar ( ou no ) o WSDL de uma maneira diferente . O WSDL de
alguns servios restritos ( como por execmplo o servio de busca na base de
dados do Google ) so disponibilizados em arquivo ASCII , enviados por e-mail ,
apos um cadastro no site e autorizao da empresa para o uso do servio por
ele provido. No nosso exemplo , a definio do servio obtida diretamente via
http , atravs do link http://localhost/SERVERTIME.apw?WSDL
Curso de Introduo a Plataforma ADVPL/ASP WebService

30

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Caso vc execute este link atravs de um Web Browser


( Internet .Explorer. , por exemplo ) , ser exibido no browse um arquivo em
XML correspondendo definio do servio , conforme exemplo abaixo :

Curso de Introduo a Plataforma ADVPL/ASP WebService

31

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

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

Curso de Introduo a Plataforma ADVPL/ASP WebService

32

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

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
definies dos metodos do servio , a(s) estrutura(s) utilizada(s) no mesmo , e a
(s) classe(s) intermediria(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 atravs de pacotes SOAP.
O Fonte gerado atravs do assistente de criao de fonte deve
preferencialmente ser gerado e compilado em um arquivo exclusivo , destinado
unica e exclusivamente a este cdigo. E , por tratar-se de uma classe Advpl
gerada a partir da definio de um servio , no devemos inserir e/ou alterar
nenhuma das definies geradas pelo assistente , pois as mesmas sero
perdidas caso o fonte seja gerado novamente .
Para gerao do fonte Client em Advpl para utilizar este servio ,
devemos criar um novo arquivo .PRX no IDE , especificamente para conter as
classes deste servio . Ento , acessamos o menu Ferramentas, opo 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 definio do WebSErvice. ( no nosso caso , http://localhost/
SERVERTIME.apw?WSDL ) . Aps a confirmao da janela acima , caso o
processamento ocorra com suicesso , na janela de mensagens do Ide ser
mostrado um texto semelhante ao abaixo :
Estabelecendo conexo com o server...
Por favor aguarde. Obtendo descrio do WebService...
Finalizando conexo com o server...
Curso de Introduo a Plataforma ADVPL/ASP WebService

33

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Ok
E , na janela do novo arquivo criado , dever ser criado um cdigo-fonte
semelhante ao mostrado abaixo :
#INCLUDE "PROTHEUS.CH"
#INCLUDE "APWEBSRV.CH"
--- header do servio --/* ================================================================
WSDL Location http://localhost/SERVERTIME.apw?WSDL
Gerado em
12/30/02 17:21:29
Observaes
Cdigo-Fonte gerado por ADVPL WSDL Client 1.021217 B
Alteraes neste arquivo podem causar funcionamento incorreto
e sero perdidas caso o cdigo-fonte seja gerado novamente.
================================================================ */
/* ------------------------------------------------------------------------------WSDL Service WSSERVERTIME
------------------------------------------------------------------------------- */
--- declarao 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
--- declarao do mtodo NEW , para a criao do Objeto / Servio --WSMETHOD NEW WSCLIENT WSSERVERTIME
::_URL
:= NIL
::cGETSERVERTIMERESULT := ""
Return Self
/* ------------------------------------------------------------------------------WSDL Method GETSERVERTIME of Service WSSERVERTIME
------------------------------------------------------------------------------- */
--- Definio do mtodo , que recebe os parmetros de chamada , executa o servio e alimenta
as propriedades de retorno do metodo , contendo os encapsulamentos necessrios para
tratamento de excesses --WSMETHOD GETSERVERTIME WSSEND NULLPARAM WSRECEIVE cGETSERVERTIMERESULT WSCLIENT
WSSERVERTIME
Local cSoap := "" , oXmlRet
BEGIN WSMETHOD

Curso de Introduo a Plataforma ADVPL/ASP WebService

34

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

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 comunicao via http com o servidor onde o servio
est publicado. Vale obvervar que as linhas em negrito no fonte acima no foram
inseridas pelo assistente do IDE , mas acrescentadas a este documento para
fins didticos.
Nele , observamos um cahealho , contendo informaes sobre a
localizao do WSDL utilizado para a gerao do fonte , data e hora de gerao
e verso do engine de WebServices utilizado . Logo abaixo , a declarao de
uma cliasse Client de WebServices ( WSCLIENT WSSERVERTIME ) , com o
mtodo new() para inicializao das propriedades advpl da classe . E , em
seguida , a declarao do mtodo de busca de Horrio ( WSMETHOD
GETSERVERTIME ) , que no envia parmetro algum , e retorna o horrio atual
do server em :: cGETSERVERTIMERESULT , com todos os tratamentos
necessrios embutidos.

Passo 3 : Criar um fonte que utilize esta classe para a obteno do


horrio.
Agora , criamos um novo arquivo no IDE , e montamos uma funo para
utilizar a classe de Web Services Client para obter o horrio no servidor.
Curso de Introduo a Plataforma ADVPL/ASP WebService

35

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#INCLUDE "PROTHEUS.CH"
User Function TestClient()
Local oSvc := NIL
oSvc := WSSERVERTIME():New()
If oSvc:GETSERVERTIME()
alert("Horrio no Servidor : "+ oSvc:cGETSERVERTIMERESULT)
Else
alert("Erro de Execuo : "+GetWSCError())
Endif
Return

Linha 1
Linha 3
Linha 4
Client
Linha 6
Linha 8

Linha 9
Linha 11

Linha 13

Declaramos a utilizao do Include Protheus.ch , contendo as


definies dos comandos ADVPL e demais constantes
Criamos uma User Function para utilizar o Web Service
Declaramos uma varivel local para conter o Objeto do Web Service
Para utilizarmos o servio , alimentamos a varivel oSvc com uma onva
instncia do Web Services Client , obtida atravs da sintaxe
<NOME_DO_SERVICO>():New()
Chamamos a execuo do Mtodo GetServerTime a partir do Objeto do
servio oSrv , sem passar qualquer parametro. O retorno de um mtodo
do client pode ser .T. (true) em caso de execuo com sucesso ou .F.
(false) em caso de falha de execuo .
Caso o servio tenha sido executado com sucesso , o retorno esperado
alimenrado na propriedade cGetServerTimeResult do objeto do servio.
Caso contrrio ( retorno .F. ) , ocorreu alguma falha na chamada do
servio, como por exemplo o servidor no estava no ar, demorou muito
pra responder ( time-out ) , entre outras. Para recuperarmos maiores
detalhes sobre a ocorrncia de erro , utilizamos a funo GetWSCerror
() , que retorna uma string com o resumo da ocorrncia .
Finalizamos o programa de teste com um Return

Curso de Introduo a Plataforma ADVPL/ASP WebService

36

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Passo 4 : Executar o programa de testes


Abra uma nova instncia do Ap Remote , e execute a funo
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 esto no Protheus , compilados no mesmo Repositrio de Objetos .
Ento , vamos desabilitar o Server HTTP do Protheus (colocando enable=0 na
chave [http] do arquivo de consigurao do servidor) , re-iniciar o Server
Protheus , e executar o programa client novamente . Devemos obter uma tela
semelhante exemplificada abaixo :

Passo 5 : Obter informaes de debug


Visto at o passo 4 , vemos um client funcionando perfeitamente . Agora ,
imaginemos que , durante o desenvolvimento e testes do client do servio ,
faam-se necessrias determinadas informaes internas as rotinas de
execuo do servio no Client Advpl . Para tal , foi criada uma funo que
permite definir em tempo de execuo , um nivel de detalhamento de
Curso de Introduo a Plataforma ADVPL/ASP WebService

37

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

informaes adicionais relacionadas ao Web Service ; informaes estas que


sero mostradas no Console do Server Protheus ( caso habilitado ) . a Funo
para definir o nivel de detalhe chama-se WSDLDbgLevel() , e recebe um nmero
como parmetro :
0 ( default )
1
2

Sem informaes adicionais.


Apenas String SOAP de retorno do Server.
Strings Soap de Envio e Retorno.

Ento , na linha 7 , vamos acrescentar a instruo WSDLDbgLevel(2) ,


para ativar o nivel mais completo de informacoes adicionais , e vamos obervar
no console do servidor as mensagens apresentadas durante a execuo 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
Curso de Introduo a Plataforma ADVPL/ASP WebService

38

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

ap="http://schemas.xmlsoap.org/soap/
envelope/"><soap:Body><GETSERVERTIMERESPONSE
xmlns="http://automan:8000/
webservice/"><GETSERVERTIMERESULT>10:37:10</GETSERVE
RTIMERESULT></GETSERVERTIMERESPONSE></soap:Body></soap:Envelope>
------------------------------------------------------------------------------Fim Thread (siga0984, AUTOMAN) BytesIn 73 BytesOut 75
O texto marcado em azul claro so 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 contedo do pacote Soap devolvido pelo Server referente esta
solicitao.
Quando ocorre um erro qualquer , relacionado a execuo do Client Web
Services , o mtodo chamado retorna .F. , e o erro pode ser recuperado atravs
da funo GetWSCerror() , vista anteriormente . Para cada excesso prevista no
Client , existe um cdigo de erro correspondente, todos eles prefixados com
WSCERR . A maioria das ocorrncias est relacionada a gerao do Cdigo
fonte do Client Advpl utilizado-se o IDE. Todas as ocorrenctas de excesso
tratadas peo Web Services Client Advpl esto relacionadas no Tpico Web
Services Client Cdigos de Erro .

Web Services Client Codigos de Erro


WSCERR000 / WSDL no suportado : Existem <N> Servios declarados.
Por definio , um WSDL deve conter um e apenas um servio
declarado , com um ou mais mtodos . Caso sejam identificados mais de um
servio no mesmo WSDL , no momento da gerao do fonte , o processo
abortado com esta mensagem , informando em <N> o numero de servios
identificados no WSDL.
WSCERR001 / No h Bindings SOAP para a gerao do Servio.
Curso de Introduo a Plataforma ADVPL/ASP WebService

39

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Durante a gerao do codigo-fonte para Client Advpl a partir de uma


definio de servio (WSDL) , uma vez identificado o servio , o gerador de
cdigo procura a declarao dos BINDINGS no WSDL. Caso esta declarao
no esteja presente , a rotina considera o WSDL incompleto , e aborta o
processo de gerao de cdigo com esta mensagem .
WSCERR002 / <STRUCT_NAME> / <STRUCT_TYPE> (B) Estrutura no
encontrada.
Durante a gerao do codigo-fonte para Client Advpl a partir de uma
definio de servio (WSDL) , so analisados todos os parmetros e estruturas
utilizadas pelos mtodos do servio . Caso alguma estrutura seja declarada no
servio, porm no seja encontrada a identificao da mesma no WSDL , este
considerado invlido , sendo o processo abortado com a mensagem acima ,
onde a estrutura no encontrada identificada em <STRUCT_NAME> e
<STRUCT_TYPE>
WSCERR003 / Enumeration no suportado : <STRUCT_NAME> /
<STRUCT_TYPE>
Durante a gerao do codigo-fonte para Client Advpl a partir de uma
definio de servio (WSDL) , so analisados todos os parmetros e estruturas
utilizadas pelos mtodos do servio . Quando encontrada uma estrutura
"simpletype" com um "enumeration" ( lista de parametros vlidos prdeterminada ) , os tipos suportados at a verso 'ADVPL WSDL Client 1.021119
B' so : STRING, FLOAT, DOUBLE, DECIMAL, INT, INTEGER,
UNSIGNEDLONG, UNSIGNEDINT, LONG . Caso o WSDL contenha um
"enumeration" com uma lista de itens de algum tipo que no os declarados
acima ( tipo no supirtado ) , o processamento abortado com a mensagem
acima , onde o "enumeration" no suportado identificado em
<STRUCT_NAME> e <STRUCT_TYPE>
WSCERR004 / Apontamento de pendncia 001B em Implementao para
(<N>) <STRUCT_NAME>
Apos a anlise inicial dos parametros e estruturas utilizadas no servio ,
as estruturas pendentes so 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 no como uma estrutura ( complextype ) ; o WSDL

Curso de Introduo a Plataforma ADVPL/ASP WebService

40

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

considerado invlido , e o processo de gerao abortado com a mensagem


acima, identificando a estrutura pendente em <STRUCT_NAME>
WSCERR005 / Apontamento de pendncia 001A em Implementao para
(<N>) <STRUCT_NAME>
Similar ao WSCERR004 , esta ocorrncia reproduzida quando uma
estrutura contenha um elemento que aponte para uma outra estrutura , e esta
segunda estrutura no for encontrada no WSDL ; consequentemente o processo
de gerao abortado com a mensagem acima, identificando a estrutura
pendente em <STRUCT_NAME>
WSCERR006 / 01 Empty ParamName : aMsg <N>
Quando da anlise de parmetros ( Messages ) a partir de um WSDL ,
Caso um Message no tenha nome definido , O WSDL considerado invlido , e
o processo de gerao abortado com a mensagem acima, identificando em
<N> o elemento Interno do array de Messages do gerador de cdigo Advpl .
WSCERR007 / 01 Empty ParamType for <PARAM_NAME> : aMsg <N>
Quando da anlise de parmetros ( Messages ) a partir de um WSDL ,
Caso um Message no tenha um tipo definido , O WSDL considerado invlido ,
e o processo de gerao 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 cdigo Advpl .
WSCERR008 / Retorno NULLPARAM invlido
Quando da montagem do cdigo fonte Advpl , a partir de um WSDL , caso
um parmetro de retorno seja identificado como NULO ( NULLPARAM ) , O
WSDL considerado invlido , e o processo de gerao abortado com a
mensagem acima.
WSCERR009 / 01 Param IO (<X>) unknow
Esta mensagem uma ocorrncia interna de erro do gerador , no
reproduzida at o momento. Ela poder ser reproduzida quando da anlise do
array interno de parmetros , e este no contenha uma definio de IO De
estrutura vlido . Caso este erro se reproduza , entre em contato com <XXX>

Curso de Introduo a Plataforma ADVPL/ASP WebService

41

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

WSCERR010 / Type <STRUCT_TYPE> no contm Definio ASTRUCTIN


Quando da anlise de estruturas pendentes a partir de um WSDL , caso
uma estrutura complexa no contenha a especificao de seus elementos
internos, e a mesma no contenha nenhuma referncia ao SCHEMA ou a outra
estrutura , o WSDL considerado invlido , e o processo de gerao abortado
com a mensagem acima, identificando em <STRUCT_TYPE> o nome da
estrutura incmpleta.
WSCERR011 / Retorno NULLPARAM invlido
ao WSCERR008
WSCERR012 / 01 Param IO (<X>) unknow
WSCERR009

-> Idntico

-> Identico ao

WSCERR013 / ReturnData no implementado : <SOAP_TYPE>


Quando da gerao das expresses de converso de valores de SOAP
para Advpl , caso um parametro SOAP no seja suportado para converso , o
processo de gerao abortado com a mensagem acima, identificando em
<SOAP_TYPE> o tipo do dado no suportado para converso .
WSCERR014 / InitType NULLPARAM no implementado.
Esta mensagem uma ocorrncia interna de erro do gerador , no
reproduzida at o momento.
WSCERR015 / Node '+cObjName+' as '+cObjType+' on SOAP Response not
found.
*** Ocorrncia de erro de execuo do Client , reproduzida quando do
processamento de um pacote SOAP retornado por um Web SErvice cuja
definio de trocas de dados SOAP utilize o Style = RPC , e um node de retorno
de um Array de Estruturas obrigatrio definido no WSDL no foi encontrado no
pacote retornado. ***
WSCERR016 / Requisio HTTPS no suportada.

Curso de Introduo a Plataforma ADVPL/ASP WebService

42

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Durante a gerao do codigo-fonte para Client Advpl a partir de uma


definio de servio (WSDL) , podemos especificar um arquivo na unidade de
disco do servidor , ou uma definico WSDL piblicada em um servidor WEB
HTTP . O Protocolo HTTPS ainda no suportado para operaes com WEB
Services.
WSCERR017 / Requisio HTTP retornou NIL.
Durante a gerao do codigo-fonte para Client Advpl a partir de uma
definio de servio (WSDL) , quando especificamos uma definico WSDL
piblicada em um servidor WEB HTTP , caso o servidor no seja encontrado , o
processo abortado com a mensagem acima. Verifique se a a URL digitada est
em formato vlido , se existe entrada no DNS da sua conexo de rede para
resolver o IP do servidor especificado , e se o mesmo est em operao normal.
WSCERR018 / Requisio HTTP retornou EMPTY.
Durante a gerao do codigo-fonte para Client Advpl a partir de uma
definio de servio (WSDL) , quando especificamos uma definico WSDL
piblicada em um servidor WEB HTTP , caso o servidor seja encojntado , porm
no 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 operao normal.
WSCERR019 / Arquivo no encontrado.
Durante a gerao do codigo-fonte para Client Advpl a partir de uma
definio de servio (WSDL) , quando especificamos uma definico WSDL salva
em um arquivo na unidade de disco do SErvidor , caso o arquivo especificado
no seja encontrado , o processo abortado com a mensagem acima. Verifique
se o arquivo especificado est digitado em formato vlido , e se o mesmo
realmente existe.
WSCERR020 / Falha de Abertura do Arquivo / FERROR <FERROR_NUM>
Durante a gerao do codigo-fonte para Client Advpl a partir de uma
definio de servio (WSDL) , quando especificamos uma definico WSDL salva
em um arquivo na unidade de disco do SErvidor , caso no seja possvel a
abertura do arquivo para a leituda da definico , o processo abortado com a
mensagem acima , identificando o cdigo ADVPL de Falha de Abertura em
<FERROR_NUM> . Verifique se o arquivo especificado no est sendo utilizado
Curso de Introduo a Plataforma ADVPL/ASP WebService

43

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

por outro programa , e se o usurio que subiu o Server Protheus tm direitos de


acesso de rede pasta\arquivo especificada.
WSCERR021 / <EXTRA_INFO> WSDL Parsing <PARSER_ERROR>
Esta ocorrncia reproduzida no momento da gerao de um codigofonte a partir de um WSDL , caso este apresente alguma inconsistncia , como
um erro de sintaxe ou estrutura, em nvel de documento XML. Caso reproduzida
sta ocorrncia , o WSDL considerado invlido , e o processo de gerao
abortado com a mensagem acima , identificando em EXTRA_INFO o "source"
do WSDL , e em <PARSER_ERROR> maiores detalhes sobre a inconsistncia
detectada.
WSCERR022 / <EXTRA_INFO> WSDL Parsing <PARSER_WARNING>
Similar ocorrncia WSCERR021 , esta ocorrncia reproduzida no
momento da gerao de um codigo-fonte a partir de um WSDL , caso este
apresente alguma inconsistncia em nvel de documento XML. Caso
reproduzida sta ocorrncia , o WSDL considerado invlido , e o processo de
gerao abortado com a mensagem acima , identificando em EXTRA_INFO o
"source" do WSDL , e em <PARSER_WARNING> maiores informaes sobre a
inconsistncia detectada.
WSCERR023 / <EXTRA_INFO> Falha ao Importar WSDL : Todos os
parmetros VAZIOS
Esta ocorrncia reproduzida no momento da gerao de um codigofonte a partir de um WSDL , caso este , aps tratramento do Parser , no resulte
nenhum conteudo. Neste caso , o WSDL considerado invlido , e o processo
de gerao abortado com a mensagem acima , identificando em EXTRA_INFO
o "source" do WSDL .
WSCERR024 / Message <MESSAGE_NAME> no encontrada.
Esta ocorrncia reproduzida no momento da gerao de um codigofonte a partir de um WSDL , quando especificado um parmetro no BINDING
do servio , porm o mesmo no foi declarado no Message do mesmo. Neste
caso , o WSDL considerado invlido , e o processo de gerao abortado com
a mensagem acima , identificando em MESSAGE_NAME o nome do parmetro
especificado no Bindings no encontrado.
Curso de Introduo a Plataforma ADVPL/ASP WebService

44

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

WSCERR025 / Binding <SERVICE_BINDING> no Encontrado.


Esta ocorrncia reproduzida no momento da gerao de um codigofonte a partir de um WSDL , quando especificado um binding no servio ,
porm o mesmo no foi declarado na seo Bindings do mesmo. Neste caso , o
WSDL considerado invlido , e o processo de gerao abortado com a
mensagem acima , identificando em SERVICE_BINDING nome do parmetro
especificado no Servio no encontrado.
WSCERR026 / targetNamespace no definido no WSDL.
Quando da anlise do header de um WSDL , no for localizado o atributo
que identifica o namespace default utilizado pelo WSDL ( TargetNamespace ) , o
WSDL considerado invlido , e o processo de gerao abortado com a
mensagem acima .
WSCERR027 / <SERVICE_NAME> : Bind_Operation no encontrada em
aBind[<N>]
Quando da anlise da estrutura de um WSDL , no for localizado uma
operao definida do servio na seo BINDINGS do mesmo , o WSDL
considerado invlido , e o processo de gerao 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> no Encontrado em aPort
Quando da anlise da estrutura de um WSDL , no for localizado uma
operao definida do servio na seo PORTTYPE do mesmo , o WSDL
considerado invlido , e o processo de gerao abortado com a mensagem
acima , identificando o porttype no encontrado em <PORT_TYPE>.
WSCERR029 / PortType <PORT_TYPE> no contm operaes.
Quando da anlise da estrutura de um WSDL , for localizado o
PORTTYPE do servio , porm o mesmo no contiver a definio interna de
parmetros , o WSDL considerado invlido , e o processo de gerao
abortado com a mensagem acima , identificando o porttype inconsistente em
<PORT_TYPE>.

Curso de Introduo a Plataforma ADVPL/ASP WebService

45

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

WSCERR030 / Declaracao de estrutura pendente no suportada com


<STRUCT_TYPE>
Quando do processamento de estruturas pendentes do WSDL , em
momento de gerao de fonte , as estruturas pendentes devem ser estruturas
tipo COMPLEXTYPE. No so suportados outros tipos neste ponto da rotina .
Neste caso , o WSDL considerado invlido , e o processo de gerao
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
invlido , e o processo de gerao abortado com a mensagem acima ,
identificando a estrutura em <STRUCT_NAME>
WSCERR032 / (X) NameSpace (<SHORT_NAMESPACE>) para Type
<STRUCT_TYPE> no 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 no
seja encontrado, o WSDL considerado invlido , e o processo de gerao
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> no
encontrado.
Complementar ao erro WSCERR032 , este reproduzido quando o
namespace idenfiicado para o parmetro seja externo ao WSDL , porm a URL
para processamento do mesmo no seja especificada atravs de um
<IMPORT...> no WSDL . Neste caso , o WSDL considerado invlido , e o
processo de gerao abortado com a mensagem acima , identificando o
namespace em <LONG_NAMESPACE> .
WSCERR034 / Location VAZIO para Import do NameSpace
<LONG_MANESPACE>

Curso de Introduo a Plataforma ADVPL/ASP WebService

46

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Complementar ao erro WSCERR033 , este reproduzido quando a


declarao da URL / Location do namespace externo no esteja declarado no
<IMPORT...> no WSDL . Neste caso , o WSDL considerado invlido , e o
processo de gerao abortado com a mensagem acima , identificando o
namespace em <LONG_NAMESPACE> .
WSCERR035 / Definio aType para <STRUCT_TYPE> no 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 reprocessado. No reprocessamento , caso o parmetro pendente no seja
encontrado , o WSDL considerado invlido , e o processo de gerao
abortado com a mensagem acima , identificando a estrutura em
<STRUCT_TYPE>.
WSCERR036 / 03 ParamRef no suportado : <REFERENCIA> from
<PARAM_NAME> / <STRUCT_NAME>
Qundo da validao de estruturas complexas , caso a mesma no possua
tipo definido , e no seja uma referncia externa ao WSDL , ela deve ser uma
referncia ao prprio SCHEMA. Caso seja especificada qualquer outro tipo de
referncia , o WSDL considerado invlido , e o processo de gerao
abortado com a mensagem acima , identificando a referncia em
<REFERENCIA> , e os detalhes sobre o parametro / estrutura em
<PARAM_NAME> / <STRUCT_NAME>
WSCERR037 / Estrutura Interna Inesperada em (<PARAM_NAME>)
Quando da validao de estruturas complexas , caso a mesma tenha
passado por todas as interpretaes cabiveis de uma estrutura , e mesmo assim
no foi possvel identific-la , o WSDL considerado invlido , e o processo de
gerao abortado com a mensagem acima , identificando a estrutura em
<PARAM_NAME>
WSCERR038 / 02 Empty ParamName for <PARAM_NAME> aType[<N1>]
[<N2>]
Quando da validao de estruturas complexas , caso a mesma tenha
passado por todas as interpretaes cabiveis de uma estrutura , porm seu
Curso de Introduo a Plataforma ADVPL/ASP WebService

47

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

nome no foi declarado , o WSDL considerado invlido , e o processo de


gerao abortado com a mensagem acima , identificando a estrutura em
<PARAM_NAME>
WSCERR039 / Unexpected DumpType <OBJ_TYPE>
Quando da utilizao da funo XMLDataSet , para a interpretao de um
objeto de retorno XML em formato DataSet , caso no seja passado um objeto
Advpl de tipo vlido ( Objeto XML ou Array ) , o processamento abortado ,
mostrando a mensagem acima , identificando o tipo de parmetro recebido em
<OBJ_TYPE>
WSCERR040 / Unexpected SCHEMA Type <OBJ_TYPE>
Quando da utilizao da funo XMLDataSchema , para determinar os
dados recebidos por um retorno de um Web Service que retorna uma referncia
ao Schema , e no seja passado funo um Objeto Advpl de Tipo Vlido
( Objeto Xml ou Array ) , o processamento abortado , mostrando a mensagem
acima , identificando o tipo de parmetro recebido em <OBJ_TYPE>
WSCERR041 / <NOTNIL_MESSAGE>
Durante a identificao do retorno de um Web Service , caso algum
parmetro obrigatorio do servio no esteja presente no pacote de retorno , o
processamento abortado com a mensagem acima , identificando em
NOTNIL_MESSAGE o parametro que no veio preenchido.
WSCERR042 / URL Location no especificada.
No momento de postar o pacote SOAP de parmetros para um Web
Service , verificada a propriedade reservada _URL do Objeto do Servio. 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 parmetros para um Web Service ,
verificado o SoapStyle utilizado pelo servio . Caso o mesmo no seja
DOCUMENT ou RPC , o processamento abortado com a mensagem acima,
identificando o SoapStyle utilizado em <SOAP_STYLE>.

Curso de Introduo a Plataforma ADVPL/ASP WebService

48

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

WSCERR044 / No foi possvel POST em <URL_LOCATION>


Apos montado o pacote de envio para a solicitao de processamento do
servio , o pacote enviado url discriminada no servio. Caso o Servidor de
destino do pacote no seja localizado no DNS ou no 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 solicitao de processamento do
servio , o pacote enviado url discriminada no servio. Caso o pacote seja
enviado , porm 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 solicitao de
processamento do servio , o pacote SOAP retornado analizado para a
alimentacao dos parametros Advpl . Caso o pacote retornado apresente alguma
incionsistncia em nivel de documento XML , o processamento abortado com a
mensagem acima , identificando a inconsistncia 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 solicitao de
processamento do servio , 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 servio , caso o mesmo
apresente uma ocorrncia de falha do tipo SOAP:FAULT , o processamento
Curso de Introduo a Plataforma ADVPL/ASP WebService

49

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

abortado com a mensagem acima , identificando o soap_code em


FAULT_CODE , e a string contendo os detalhes da ocorrncia gerada pelo
Server em FAULT_STRING , e a url de destino do pacote <URL_LOCATION>
WSCERR049 / SOAP RESPONSE (RPC) no encontrado.
Durante a analize do pacote SOAP retornado do servio , caso o mesmo
utilize um soapType = RPC , e o node de resposta no seja encontrado no
pacote , o processamento abortado com a mensagem acima .
WSCERR050 / SOAP RESPONSE REF <REFERENCE_ID> (RPC) no
encontrado.
Durante a analize do pacote SOAP retornado do servio , caso o mesmo
utilize um soapType = RPC , e o node de resposta aponte para un outro node via
referncia , e este novo node no seja encontrado no pacote , o pacote
considerado invlido e o processamento abortado com a mensagem acima ,
mostrando o identificador de referncia nao encontrado em REFERENCE_ID
WSCERR051 / SOAP RESPONSE RETURN (RPC) no encontrado.
Durante a analize do pacote SOAP retornado do servio , caso o mesmo
utilize um soapType = RPC , e o node de resposta no aponte para nenhuma
referncia , o node de retorno est dentro do nivel de resposta . Caso o node de
retorno no seja encontrado neste nivel , o pacote de retorno considerado
invlido , 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 requisio de
um processamento de um Web Service , caso um parmetro de um tipo simples
contiver um enumeration , e for alimentado pelo client com um valor no
constante na lista do Enumeration , o processamento abortado antes da
requisico ser realizada , com a mensagem acima , identificando o tipo da
estrutura invlida 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 no seja localizado no
Curso de Introduo a Plataforma ADVPL/ASP WebService

50

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

pacote de retorno , o pacote de retorno considerado invlido , e o


processamento abortado com a mensagem acima.

WSCERR054 / Binding SOAP no localizado no WSDL.


Durante a gerao do codigo-fonte para Client Advpl a partir de uma
definio de servio (WSDL) , uma vez identificado o servio , o gerador de
cdigo procura a declarao dos BINDINGS no WSDL. Dentre os bindings
encontrados , apenas so processados os bindings que transportam dados no
formato SOAP . Caso nenhum binding do servio utilize SOAP , o processo de
gerao do fonte client abortado , retornando esta ocorrncia.
WSCERR055 / Invalid Property Type (<TYPE1>) for <PROPERTY>
( <TYPE2> )
Quando da utilizao 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 no concordante com a declarao do mtodo / estrutura , no nomento
do pacote SOAP ser montado , todas as propriedades usadas pelo mtodo so
validadas antes do envio . Caso alguma propriedade <PROPERTY> esteja
alimentada com um tipo de dado Advpl <TYPE1> , porm o tipo esperado era
<TYPE2> , o processamento abortado com a ocorrncia de erro acima.
Observao : Esta validao est disponvel a partir da verso ADVPL WSDL
Client 1.030523 e superiores. Em verses anteriores , ocorria um erro Interno
Type Mismatch ou Argument Error dentro da funo WSSoapValue.
WSCERRINT / <INTERNAL_ERROR>
Esta ocorrncia aponta um erro interno no engine de processamento do
client Web Services . Caso esta ocorrncia seja reproduzida , entre em contato
com Departamento de Tecnologia da Microsiga Software S/A.

Curso de Introduo a Plataforma ADVPL/ASP WebService

51

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Captulo 8 - Web Services em ADVPL - SERVER


Introduo
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 ao / mtodo do servio ,
enviando o(s) parmetro(s) ao mesmo atravs de uma string XML , formatada no
padro SOAP (Simple Object Access Protocol) , e o servio retornar ao client
uma string XML de resposta , tambm formatada no padro SOAP.
Diferentemente dos Web Sites, que so apresentaes de dados feitas
para serem vistas em um browser por um internauta , um Web Service
construdo para ser acessado diretamente por outro servio ou programa de
Software. Os servios podem ser combinados entre si e com outras aplicaes
para construir servios interativos e inteligentes.
A universalidade de um Web Service , entre outros fatores , reside
justamente na maneira de disponibilizar uma espcie de manual do servio ,
chamado de WSDL ( Web Services Description Language ) , que nada mais do
que uma descrio detalhada do servio , que capaz de resumir em um nico
documento os mtodos de um servio , os parmetros , 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.
Tambm foi idealizado o uso do protocolo HTTP originalmente para a troca de
pacotes de requisio e retorno de processamento pois a maioria dos sistemas
operacionais tm recursos para suport-lo ; e foi escolhido o formato SOAP por
ser um padro aberto, criado pela Microsoft, Ariba e IBM para padronizar a

Curso de Introduo a Plataforma ADVPL/ASP WebService

52

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

transferncia de dados em diversas aplicaes, que utiliza como veculo o


universalmente conhecido XML ( Extended MarkUp Language ) .
Termos Tcnicos
SOAP - Sigla de Simple Objetc Access Protocol, ou protocolo simples de
acesso a objetos. O SOAP um padro aberto, baseado em XML, criado pela
Microsoft, Ariba e IBM para padronizar a transferncia de dados entre
aplicaes.
Pode ser usado em combinao com vrios outros protocolos comuns da
Internet,
como HTTP e SMTP.
WSDL - Web Service Description Language. Submetida W3C - o rgo
padronizador da Internet - . A linguagem WSDL define regras baseadas em XML
para descrever servios 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 caracterstica a extensibilidade.
Quem
emite um documento XML pode criar tags personalizadas, que so explicadas
num
documento anexo, que tem extenso 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 programao, os XSDs aceitam dados de diferentes tipos, como nmeros,
data e
moeda.

Definio de um Web Service SERVER em Advpl


Inicialmente veremos neste documento as atribuies e funcionalidades
dos Web Services direcionados uma aplicao SERVER , e num momento
posterior a funcionalidade de uma aplicao CLIENT em detalhes . A criao de
um Web Service em Advpl consiste na montagem de uma classe Advpl
especial , chamada WSSERVICE , onde cada mtodo da classe uma ao do
Web Service. Caber os fontes dessa classe o processamento de uma
Curso de Introduo a Plataforma ADVPL/ASP WebService

53

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

requisio e a gerao do respectivo retorno , cabendo ento Lib de Web


Services do AP7 a camada de troca de dados , recepo e tratamento do pacote
SOAP , as converses de dados cabveis do XML para as propriedades de
parmetro da classe Advpl e a montagem do pacote SOAP a partir das
propriedades de retorno setadas pelo mtodo executado e retorn-lo ao Client,
alm de prover o client o documento WSDL referente o servio compilado no
Repositrio de Objetos Advpl .
Este mtodo de programao em camadas permite encapsular on
tratamentos internos , em se tratando de protocolo HTTP , SOAP e WSDL ,
tornando relativamente fcil a misso de criar um Web Servie utilizando-se do
Advanved Protheus. Basta escrever uma classe que receba um ou mais
parmetros e devolva um retorno , ambos tratados pelo fonte como um tipo de
dado Advpl bsico; configurar o Server Protheus para habilitar a interface HTTP
e os Web Services , que a Lib faz todo o resto.

Declarao de um Web Service SERVER em Advpl


Vejamos abaixo um esboo contendo as instrues Advpl necessrias
para a declarao de um Web Service SERVER em Advpl . Para a utilizao
destes comandos , faz-se necessria a declarao do arquivo de header Advpl
APWEBSRV.CH .
WSSERVICE <Nome_do_Servico>

// Declarao do Servio

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


[OPTIONAL]
(... demais propriedades , parmetros e retornos ... )
WSMETHOD <Nome_do_Metodo>
(... demais mtodos ...)
ENDWSSERVICE
WSSTRUCT <Nome_da_Estrutura>
Estrututra(s) ( opcionais )

// Declarao da(s)

Curso de Introduo a Plataforma ADVPL/ASP WebService

54

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

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


[OPTIONAL]
( ... demais campos da estrutura ... )
ENDWSSTRUCT
// --- Fontes do(s) mtodo(s) declarado(s) no Servio --WSMETHOD < Metodo> WSRECEIVE < Campo_In>[, Campo_In2,...] WSSEND
< Campo_Out>
( ... Processamento do servio a partir dos parametros , e alimentao do
retorno <Nome_campo_out> ... )

Regras para Nomenclatura dos Servios / Estruturas / Dados e


Mtodos
1. Nomenclatura dos Servios
<Nome_do_servico>
Deve ser iniciado por um caracter alfabtico , e
deve conter apenas os caracteres alfabticos compreendidos entre A ... Z , os
caracteres numricos compreendidos entre 0 ... 9 , podendo tambm ser
utilizado o caracter _ (underline ) . Um servio no pode ter um nome de uma
palavra reservada Advpl , e no pode ter o nome igual a um tipo bsico de
campo ( STRING , INTEGER , FLOAT , DATE , BOOLEAN ) .

2. Nomenclatura de Estruturas
WSSTRUCT <Nome_da_Estrutura>
Estrututras ( opcionais )

// Declarao de

Curso de Introduo a Plataforma ADVPL/ASP WebService

55

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

<Nome_da_Estrutura>

Obedece s mesmas regras de nomenclatura de


Servios , no podendo haver uma estrutura com o
mesmo nome de um servio declarado.

Uma estrutura um agrupamento de dados bsicos, criado como uma


classe especial (WSSTRUCT) em Advpl. Procedemos com a criao de uma
estrutura para um servio quanto temos a necessidade de definir que um
conjunto de dados bsicos pode ser agrupado em um tipo de informao que
ser utilizada como parmetro e/ou retorno em um ou mais metodos do servio.

3. Nomenclatura de Dados ( Campos )


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

Obedece s mesmas regras de nomenclatura de


Servios , no podendo haver um dado com o
mesmo nome de um servio ou estrutura j
declarados.

[ARRAY OF]

Caso especificado , indica que este dado poder ter


mais de uma ocorrncia , sendo tratado como um
Array em Advpl .

<Tipo_Campo>

Pode ser um tipo bsico de dado (String , Date ,


Integer , Float , Boolean ) , ou pode ser uma estrutura
declarada .

[OPTIONAL]

Caso especificado , indica que a especificao deste


dado nos pacotes de envio e/ou retorno opcional.

*** Resties de uso da instruo ARRAY OF : No permitido o uso da


instruo ARRAY OF quando declaramos dados utilizados para entrada de
dados dentro da declarao do servio. Para tal , precisamos criar uma estrutura
intermediria para encapsular o array.

Tipos de Dados Bsicos


String

Dado Advpl do tipo String.

Curso de Introduo a Plataforma ADVPL/ASP WebService

56

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Date
Integer
Float

Dado Advpl do tipo Data.


Dado Advpl do Tipo numrico , apenas numeros inteiros.
Dado Advpl do Tipo numrico , pode conter numeros inteiros e
no-inteiros.
Boolean
Dado Advpl do Tipo Booleano ( lgico ) .
Base64Binary* Dado Advpl do Tipo String Binria , aceitando todos os
Caracteres da Tabela ASCII , de CHR(0) a CHR(255)
* A implementao do Campo Base64Binary est disponvel apenas a partir
de repositrios gerados aps Maro / 2003 ( A partir da verso ADVPL
WSDL Server 1.030306 ) .
*** Campos Obrigatrios / Opcionais : Por default , um campo declarado sem
a clusula OPTINAL , obrigatrio . Sendo obrigatrio , 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 parmetro ou retorno . No
processamento de um servio , os dados enviados pelo client como parmetro
na requisio so lidos do pacote SOAP e atribuidos s propriedades do mtodo
do respectivo servio, e caso um dado no seja passado ao servio , atribudo
ao mesmo o contedo NIL. A partir da verso ADVPL WSDL Server 1.030103
B , foi implementado o tratamento de excesso no Server para gerar um Soap
Fault automtico , caso algum parametro obrigatrio no seja recebido na
solicitao de processamento.

4. Mtodos ( Aes )
WSMETHOD <Metodo> WSRECEIVE <Cpo_In>[, Cpo_In2,...] WSSEND
<Cpo_Out>
<Metodo>

Obedece s mesmas regras de nomenclatura de


Servios , no podendo haver um servio ou
estrutura declarados com o mesmo nome.

Ao declarar o mtodo , obrigatoriamente devemos especificar um ou mais


campos declarados dentro do servio a serem utilizados para a entrada de
dados , e apenas um campo para sada de dados do mtodo . Os campos
podem ser de tipos bsicos ou estruturas. Dentro do mtodo , fazemos
referncias s propriedades da estrutura , segundo a nomenclatura de acesso
propriedades de objetos Advpl ( prefixo :: ) . Caso desejemos declarar um
Curso de Introduo a Plataforma ADVPL/ASP WebService

57

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

servio que no requer nenhum parmetro , devemos especificar que o mesmo


recebe o parmetro reservado NULLPARAM .

Publicando um WEB Service no Protheus - Configurao


Um WebService em Advpl utiliza-se de Working Threads (**) para atender
s solicitaes de processamento em um host http , de modo que , para publicar
e habilitar um Web Service em um servidor Protheus , devemos primeiramente
habilitar o servio de publicaes web ( http ) do Protheus , atravs da seo
[http] do Arquivo de Inicializao do Servidor ( Ap7Srv.ini ) .
Feito isso , existem duas maneiras de habilitar o WebService : Atravs da
criao da seo [webservices] no Arquivo de Configurao do Server , ou
atravs da configurao manual de um ambiente de Working Threads Extended
( WEBEX ) , tambm no inicializador. A diferena entre ambas que a segunda
opao permite especificar maiores detalhes do ambiente de execuo do
servio , permite a configurao de servios e Web sites simultaneamente e
multi-hosting . Quando nos utilizamos do server HTTP do Protheus apenas para
Web Services , utilizamos com grande eficcia a configurao atravs da seo
[webservices]
[WebServices]
Enable=0 ; Indica se o service est habilitado (1) ou no (0).
Environment=ENVTESTE ; Indica qual environment do Server que ir
atender s requisies
Conout=1 ; Permite a exibio de informaes dos status internos do
servio ( default = 0 : desabilitado )
Trace=1 ; Habilita a grevao de um arquivo de log ( wsstrace.log ) ,
contendo as informaes sobre todas as chamadas e status do Web Service
( default = 0 )
PrepareIn=01,01 ; Permite especificar qual a empresa e filial do ERP
sero utilizados para a montagem do ambiente de processamento das
requisies.
NameSpace = http://localhost ; Permite especificar o nome do namespace
utilizado pelo servio ( default = host atualmente utilizado )
URLLocation = http://localhost ; Permite especificar a url responsvel pelo
atendimento as solicitaes de processamento do servio ( default = host
atualmente utilizado )
Curso de Introduo a Plataforma ADVPL/ASP WebService

58

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Para configurar o WebService manualmente , devemos alm de habilitar o


server http , devemos tambm configurar um Job do tipo WEBEX , apontando
para funcoes internas de processamento dos WebServices , configurar um host
cujas requisioes de links apw seram atendidas por este job. Veja exemplo do
job abaixo :
[http] ; configurao do servio http
Enable=1
Port=80
Path=c:\Ap7\Http
[localhost] ; Configuraao do host local
ResponseJob=WSTESTE
[WSTESTE] ; Configuracao do job
TYPE=WEBEX ; Tipo do Job para WebServices deve ser WEBEX
ONSTART=__WSSTART ; configurao fixa para webservices
ONCONNECT=__WSCONNECT ; configurao fixa para webservices
Environment=ENVTESTE ; Indica qual environment do Server que ir
atender s requisies
INSTANCES=2,5 ; Indica qual a quantidade minima (default ) e maxima
de threads ( ambientes ) que sero colocados no ar para atender solicitaes
de processamento do servio publicado.
Conout=1 ; Permite a exibio de informaes dos status internos do
servio ( default = 0 : desabilitado )
Trace=1 ; Habilita a grevao de um arquivo de log ( wsstrace.log ) ,
contendo as informaes sobre todas as chamadas e status do Web Service
( default = 0 )
PrepareIn=01,01 ; Permite especificar qual a empresa e filial do ERP
sero utilizados para a montagem do ambiente de processamento das
requisies.
NameSpace = http://localhost/ ; Permite especificar o nome do
namespace utilizado pelo servio ( default = host atualmente utilizado )
URLLocation = http://localhost/ ; Permite especificar a url responsvel
pelo atendimento as solicitaes de processamento do servio ( default = host
atualmente utilizado )

Curso de Introduo a Plataforma ADVPL/ASP WebService

59

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."

Web Services Ponto de Entrada WSSTART


O ambiente de execuo das Threads dos Web Services
automaticamente monta um ambiente ERP , utilizando a empresa e filial
especificadas no parametro PREPAREIN na configurao dos WebServices,
quando informado o mesmo.
Caso seja necessrio alguma inicializao 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 repositrio de Objetos , cabe o ponto de entrada realizar a
inicializao do ambiente, de modo que o parmetro PREPAREIN apenas ser
lido , e seu contedo ser passado como parmetro ao ponto de entrada.Caso o
ponto de entrada seja compilado , e no seja preenchido o parametro
PREPAREIN , o ponto de entrada receber a empresa e/ou filial em branco ().

Curso de Introduo a Plataforma ADVPL/ASP WebService

60

"Essa mensagem destinada exclusivamente ao seu destinatrio e pode conter informaes confidenciais,
protegidas por sigilo profissional ou cuja divulgao seja proibida por lei. O uso no autorizado de tais
informaes proibido e est sujeito s penalidades cabveis."