ADVPL - Web Services Com Protheus

7/22/2019 ADVPL - Web Services Com Protheus

1/140

Web Services com Protheus

Reviso: 27/04/2004

Abrangncia

Verso 7.10 Verso 8.11

O Protheus, a partir da verso AP7, possui ferramentas nativas e integradas com a LIBde Infra-Estrutura do ERP, para desenvolvimento de aplicaes 'Cliente' e 'Server',utilizando a tecnologia dos Web Services. Para melhor compreenso do assunto, os

tpicos relacionados a ambos foram didaticamente separadosem Aplicaes ServereAplicaes Cliente, respectivamente. Nos tpicos 'Comandos' e 'Funes', so abortadasrespectivamente as diretivas e funes da Lib de Infra-estrutura do ERPdisponibilizadas para o desenvolvimento de ambas as aplicaes, Cliente e Server. No

tpico 'Exemplos Advpl', so demonstrados os exemplos 'atmicos' de uso das funes ecomandos.


2/140

COMANDOS - ENDWSCLIENT

Reviso: 22/04/2004

Abrangncia


Sintaxe

ENDWSCLIENT [ self ]

Parmetros

Argumento Tipo Descrio

self (NULO) Esta instruo no recebe nenhum parmetro.

Descrio

Atravs desta instruo, encerra-se a declarao de uma classe 'Client'de Web Services,iniciada com ostatementWSCLIENT.

Esta instruo de declarao utilizada exclusivamente quando da gerao de um fonte'Cliente' de Web Services, atravs do assistente 'Gerar Cliente WebServices...' do IDE.

Observao : A utilizao deste comando exige a declarao do #include'APWEBSRV.CH'no fonte Advpl.


3/140

COMANDOS - ENDWSSERVICE

Reviso: 22/04/2004

Abrangncia


Sintaxe

ENDWSSERVICE [ self ]

Parmetros


self (NULO) Esta instruo no recebe nenhum parmetro.

Descrio

Atravs desta instruo, encerra-se a declarao de uma classe 'Server' de Web Services,iniciada com ostatementWSSERVICE.

O no-fechamento da declarao da classe ocasiona "falha de compilao" no fonte.



4/140

COMANDOS - ENDWSSTRUCT

Reviso: 22/04/2004

Abrangncia


Sintaxe

ENDWSSTRUCT [ self ]

Parmetros


self (NULO) Esta instruo no recebe parmetros

Descrio

Atravs desta instruo, encerra-se a declarao de uma estrutura a ser utilizada em umWeb Service, iniciada com ostatementWSSTRUCT.

O no-fechamento da declarao da estrutura ocasiona falha de compilao no fonte.



5/140

COMANDOS - WSCLIENT

Reviso: 22/04/2004

Abrangncia


Sintaxe

WSCLIENT cClientName

Parmetros


cClientName CaractercClientName corresponde 'a classe do Web Service a sergerada.

Descrio

Atravs desta instruo, inicia-se a declarao uma classe 'Cliente' de Web Services emAdvpl. Esta instruo de declarao utilizada exclusivamente quando da gerao deum fonte 'Cliente' de Web Services, atravs do assistente 'Gerar Cliente WebServices...',disponvel no Protheus IDE.

Para encerrar a declarao da classe, utilizada ainstruo ENDWSCLIENT.



6/140

COMANDOS - WSDATA

Reviso: 30/04/2004

Abrangncia


Sintaxe

WSDATA cVarNAme AS [ ARRAY OF ] cVarType [ OPTIONAL ]

Parmetros


cVarNAme CaractercVarName corresponde ao nome da propriedade adeclarar.

AS Caracter Separador para indicar o tipo da propriedade.

ARRAY OF CaractercVarType corresponde a um Tipo Soap / compatvel devarivel a ser utilizado no servio. Veja os tipossuportados abaixo na Tabela A -Tipos de Dados

cVarType CaractercVarType corresponde a um Tipo Soap / compatvel devarivel a ser utilizado no servio. Veja os tipossuportados abaixo na Tabela A -Tipos de Dados

OPTIONAL Caracter

Caso especificado , definimos que esta propriedade

opcional no contexto do Web Service .

Descrio

Utiliza-se esta instruo para declarar uma propriedadede uma classe paraWebServices, 'Cliente' ou 'Server'.

Uma propriedade obrigatoriamente deve ter definida seu nome e tipo, e opcionalmentepodemos definir que a mesma ter tratamento de array e/ou tratamento opcional.

Observao : A utilizao deste comando exige a declarao do #include

'APWEBSRV.CH'no fonte Advpl.


7/140

COMANDOS - WSMETHOD

Reviso: 22/04/2004

Abrangncia

Verso 7.10

Sintaxe

WSMETHOD cMethodName [ WSRECEIVE ] [ WSSEND

] [ WSSERVICE ]

Parmetros


cMethodName CaractercMethodName corresponde 'ao nome do mtodo do WebService.

WSRECEIVE

Caracter

Atravs desta instruo , declaramos quais so o(s)parametro(s) que este mtodo recebe, separados porvrgulas. Caso um mtodo no receba parmetros ,devemos declarar que o mesmo recebe o parmetroreservado NULLPARAM.

WSSEND

CaracterAtravs desta instruo , declaramos um e apenas umparmetro de retorno de um Web Service .

WSSERVICE Caracter cServiceName corresponde ao nome da classe do servioao qual o mtodo atual pertence.

Descrio

Atravs desta instruo, incia-se a declarao de um mtodo de um Web Service -'Cliente' e/ou 'Server', em Advpl . Utilizamos esta instruo em dois momentos nodesenvilvimento :

Na declarao da classe 'Server' e/ou 'Cliente' do servio.Na definio do fonte do mtodo 'propriamente dito', do respectivoWebService.

Ao utilizarmos a instruo WSMETHOD dentro da declarao de uma classeWSSERVICE, informamos apenas o primeiro parmetro ( cMethodName ) . Porm, aodeclarar o fonte propriamente dito do mtodo, todos os parmetros desta instruo soobrigatrios.



8/140

COMANDOS - WSSERVICE

Reviso: 22/04/2004

Abrangncia


Sintaxe

WSSERVICE cServiceName [ DESCRIPTION ] [ NAMESPACE ]

Parmetros


cServiceName Caracter

cServiceName corresponde o nome do Servio ( Classeem Advpl ) que ser declarado / criado. A nomenclaturade um Web Service segue a regra de nomenclatura defunes Advpl .

DESCRIPTION

Caracter

cDescr corresponde descrio do Servio, mostrada natela de ndice de servios, e fornecida tambm jonto doWSDL gerado pelo servidor Protheus para o servioespecificado.

NAMESPACE

CaractercClsNS corresponde o NameSpace sob o qual este

servio deve ser publicado.

Descrio

Atravs desta instruo, iniciamos a declarao uma classe 'Server' de WebServices emAdvpl.

Dentro da estrutura de uma Classe 'Server' de Web Services, devemos declarar osmtodos disponibilizados da classe, e declaramos todas as propriedades ,parmetros eretornos utilizados por esta classe, devidamente especificadas, utilizando as instrues

WSMETHOD e WSDATA, respectivamente.

Para encerrar a declarao da classe, utilizamos a instruo ENDWSSERVICE..

A declarao de uma classe 'Server' de Web Services deve tr a seguinte estruturabsica :

WSSERVICE DESCRIPTION NAMESPACE

WSDATA AS

(... demais propriedades, parmetros e retornos ...)


9/140

WSMETHOD

(... demais mtodos da classe ...)

ENDWSSSERVICE

(... fonte(s) do(s) mtodo(s)s desta classe ...)



10/140

COMANDOS - WSSTRUCT

Reviso: 22/04/2004

Abrangncia


Sintaxe

WSSTRUCT cSructName

Parmetros


cSructName CaractercStructName corresponde ao nome da estrutura a sercriada. Obedee 'as regras de nomenclatura de funesAdvpl.

Descrio

Atravs desta instruo , iniciamos a declarao de uma estrutura, a ser utiilzada porum Web Service 'Server', em Advpl . Dentro de uma estrutura, devemos apenasdeclarar as propriedades que a mesma contm, atravs da instruo WSDATA.Devemos finalizar a declarao da estrutura utilizando o comando ENDWSSTRUCT.



11/140

Exemplo de uso da funoGETWSCERROR

Reviso: 22/04/2004

Abrangncia


No exemplo abaixo, ilustrado o tratamento de erro sugerido para uma chamada de ummtodo atravs de um programa 'Client', desenvolvido em Advpl.

#include 'Protheus.ch'

#include 'ApWebSrv.ch'

User Function TstService

Local oService , cSvcError , cSoapFCode ,cSoapFDescr

// Cria uma instncia do servio Cliente

oService := WSTeste():New()

// Realiza a chamada do mtodo Hello() do servio.

If oService:Hello()

// Mtodo executado com sucesso.

MsgStop('Execuo OK')

Else

// Caso o mtodo retorne .F. , devemos identificar e tratar aocorrncia

cSvcError := GetWSCError() // Resumo do erro

cSoapFCode := GetWSCError(2) // Soap Fault Code

cSoapFDescr := GetWSCError(3) // Soap Fault Description

If !empty(cSoapFCode)

// Caso a ocorrncia de erro esteja com o fault_code

preenchido ,

// a mesma teve relao com a chamada do servio .

MsgStop(cSoapFDescr,cSoapFCode)

Else

// Caso a ocorrncia no tenha o soap_code preenchido

// Ela est relacionada a uma outra falha ,// provavelmente local ou interna.

MsgStop(cSvcError,'FALHA INTERNA DE EXECUCAO DO

SERVIO')

Endif

Endif

oService := NIL

Return


12/140

Exemplo de uso da funoGETWSCVER

Reviso: 22/04/2004

Abrangncia


No exemplo abaixo , obtemos a verso da Lib 'Cliente'de Web Services compilada norepositrio atual.

User Function ShowVersions()

Local cCliVers := GetWSCVer()

MsgStop(cCliVers)

Return


13/140

Exemplo de uso da funoGETWSSVER

Reviso: 22/04/2004

Abrangncia


No exemplo abaixo , obtemos a verso da Lib 'Server' de Web Services compilada norepositrio atual.

User Function ShowVersion()

Local cSrvVers := GETWSSVER()MsgStop(cSrvVers)

Return


14/140

Exemplo de uso da funoSETSOAPFAULT

Reviso: 30/04/2004

Abrangncia


No exemplo 01, partindo de um mtodo de um WebServices 'Server', caso umparmetro no atenda a faixa de dados necessria, o servio retorna ao Client solicitanteum Soap-Fault, indicando a ocorrncia de erro.

No exemplo 02, retornamos um Soap-Fault, indicando que no estava disponvel umrecurso no servidor para o processamento requisitado. Neste, retornamos que o FaultCode 'SOAPFAULT_RECEIVER', pois o pacote no foi processado no por teralgum contedo invlido, mas sim por alguma razo ligada o ambiente do servidor.

Por default, o Fault-Code de um Soap-Fault 'SOAPFAULT_SENDER', o que indicaque o servio no foi processado por alguma razo ligada o pacote de dados enviados;e indica ao client que o pacote deve ser re-montado para que o servio seja executado.

Exemplo 01

(...)

If ::Indice > 1024

SetSoapFault('Argumento Invlido','O ndice no pode ser maior que

1024.')

Return .f.

Endif

(...)

Exemplo 02

(...)

If !File('\extras\modelo.cfg')

SetSoapFault('Servio Indisponvel','',SOAPFAULT_RECEIVER)

Return .f.Endif

(...)


15/140

Funes GETWSCERROR

Reviso: 22/04/2004

Abrangncia

Verso 7.10

Sintaxe

GETWSCERROR ( [ nInfo ] ) --> xErrorInfo

Parmetros


nInfo Numrico

nInfo especifica qual informao pertinente ao erro deveser retornada, podendo ser :

1 -Retorna uma String contendo o Resumo do ErroCOMPLETO (DEFAULT)2 = Retorna uma String contendo o soap:fault_code , casodisponvel .3 = Retorna uma String contendo o soap:fault_String ,caso disponvel .4 = Retorna um Objeto XML contendo os nodes

completos com as informaes do erro , apenas caso oerro seja um soap_Fault.

Retorno

Tipo Descrio

(Qualquer)Retorna a informao do erro solicitada atravs do parmetro nInfo . CasonInfo seja 1 , 2 ou 3 , o retorno do tipo String . Caso seja tipo 4 , serretornado um Objeto XML.

Descrio

Utilizada no desenvolvimento de uma aplicao 'Client' de WebServices,atravs destafuno possvel recuperar as informaes pertinentes uma ocorrncia de erro deprocessamentode um mtodo 'Client', aps a execuo do mesmo.

Caso a execuo de um mtodo 'Client' de Web Services retorne .F.,deve ser utilizada afuno GetWSCError(), para identificar a origem da ocorrncia. Durante uma operaode execuo de um mtodo 'Client' de WebServices,so possveis ocorrncias de errodas seguintes naturezas, emmomentos especficos :


16/140

1 -Antes do pacote 'SOAP',com os parmetros e dados pertinentes requisio, serenviado.

Durante a montagem do pacote SOAP, para envio dos parmetros do mtodo solicitado

o servidor, realizada uma consistncia do(s) parmetro(s) a serem enviados, tais

como a obrigatoriedade do parmetro e o tipo Advpl com o qual o parmetro foialimentado. Se e somente se os parmetros informados sejam vlidos, o pacote SOAPmontado postado no servidor de WebServices.

2 -Ao postar o pacote 'SOAP' para o respectivo WebService

Ao postar o pacote, caso o host do Web Service utilizado ou o servidor referente omesmo no foi localizadoou no esteja no ar.

3 -Aps o envio do pacote e obteno do devido retorno do Server.

Uma vez enviado ao Server, a interface client entra em modo 'stand-by', aguardando por

um pacote de retorno SOAP doServer. Aps a portagem, caso o pacote devolvido noesteja em conformidade com a declarao do servio, ou o servidor devolveu um htmlao invs de um xml 'SOAP'.

4 -Erro Interno de execuo : Qualquer ocorrncia de erro fatal, seja antes ou depois doenvio da requisio, cuja origem no seja tratada ou prevista pelas rotinas 'Client' doServio, como por exemplo um retorno de um pacote XML com erro de sintaxe ouestruturalmente invlido .


17/140

Funes GETWSCVER

Reviso: 22/04/2004

Abrangncia


Sintaxe

GETWSCVER ( ) --> cVersion

Retorno

Tipo Descrio

CaractercVersion corresponde verso do Build da Lib 'Cliente' de WebServices,copmpilada no repositrio em uso atualmente.

Descrio

Utilizada no desenvolvimento de uma aplicao 'Cliente' de Web Services ,atravsdesta funo possvelobter a string contendo a indentificao da verso de Build daLIB de Infra-Estrutura do Web Services 'Cliente'.


18/140

Funes GETWSSVER

Reviso: 22/04/2004

Abrangncia


Sintaxe

GETWSSVER ( ) --> cVersion

Retorno

Tipo Descrio

CaractercVersion corresponde verso do Build da Lib 'Server' de WebServices,

compilada no repositrio em uso atualmente.

Descrio

Utilizada no desenvolvimento de uma aplicao 'Server' de Web Services ,atravs destafuno possvel obter a string contendo a indentificao da verso de Build da LIB deInfra-Estrutura do Web Services 'Server'.


19/140

Funes SETSOAPFAULT

Reviso: 30/04/2004

Abrangncia


Sintaxe

SETSOAPFAULT ( < cError > , < cString > , [ nFCode ] , [ cFactor ] , [ cFDetail ] ) -->.T.

Parmetros


cError Caracter

Atravs de cError deve ser especificada uma descrioreduzida , referindo-se ao tipo do erro , por exemplo :Erro de argumento , Parametro Invalido , Falha deArquivo ,...

cString Caracter

Em cString deve-se especificar um detalhe maior daocorrncia , no exatamente um detalhe tcnico , pormuma especificao objetiva da ocorrncia. Por exemplo :Parametro XXXXX forada faixa vlida de dados ,compreendida entre mmm e nnn , ...

nFCode Numrico

Fault Code : Atravs deste parametro , possvelespecificar a origem da ocorrncia da Soap Fault .Segundo a documentao do SOAP, Verso 1.2 (publicada na W3C ) , foram definidos 6 cdigos deocorrncias standard de erro , detalhados na Tabela A.Caso no seja especificado , por default assumido ocdigo 5 ( Sender )

cFactor Caracter

Atravs de CFActor , possvel especificarexplicitamente qual node / atributo do XML / Soap queno foi processado e/ou ocasionou a falha . Deve serutilizado o formato anyURI ( ref namespacehttp://www.w3.org/2001/XMLSchema ) para especifcar o

node / atributo que ocasionou a falha.

cFDetail Caracter

Atravs de cFDetail , possvel especificar para finsinternos de processamento maiores detalhes sobre umaocorrncia de erro, especificamente relacionada o

processamento do corpo ("body") de um pacote SOAP.

Retorno
http://www.w3.org/2001/XMLSchema


20/140

Tipo Descrio

Lgico Esta funo sempre retorna .T. (true)

Descrio

Utilizada no desenvolvimento de uma aplicao'Server' de WebServices,atravs destafuno possvel setar uma ocorrncia de erro tratada, referente execuo do servio,ou impossibilidade de execuo do mtodo durante a execuo do mesmo.

Dentre as razes pelas quais este tratamento utilizado, podemos citar ocorrnciasrelacionadasa validade dos dados, recebidos no pacote de parametros enviados pelo'Cliente', como parmetros invalidos ou fora da faixa de dados permitida pela rotina,ouocorrncias relacionadas ao 'Server', como a falta de um determinado recurso no serverpara o processamento,como uma falha de acessoa base de dados, ou qualquer outrarazo implementada no servio.

Tabela A -FAULT CODES

nFCode Constante Descrio

1 SOAPFAULT_VERSIONMISMATCH NameSpace invlidoencontrado no processamentodo Soap:Body

2 SOAPFAULT_MUSTUNDERSTAND Refere-sea falha deinterpretao de um node /atributo contido noSoap:Header, especificadocom o atributomustUnderstand setado para

'true'3 SOAPFAULT_DTDNOTSUPPORTED A String Soap enviada como

parmetro continha um DTD(Document Type Definition).

4 SOAPFAULT_DATAENCODINGUNKNOWN O HEader ou o Body dopacote SOAP est utilizandoum encoding-type nosuportado pelo server.

5 SOAPFAULT_SENDER Refere-se a uma ocorrnciade erro e/ou falha deprocessamento da aao, poralgum tipo de inconsistnciarelacionadaa falta de um oumais dados necessrios aoprocessamento. Indica umaocorrncia que requer que opacote SOAP seja remontadopara que seja realizada umanova tentativa de acesso.


21/140

6 SOAPFAULT_RECEIVER Refere-se a uma ocorrnciade erro e/ou falha deprocessamento por razesque no estoespecificamente relacionadasao conteudo do pacote SOAp

e/ou parametros recebidos,porm relacionados 'a umafalha no Receptor do Servio,como por exemplo o servidor

estar bloqueado paramanuteno. Este tipo deocorrncia no indica queexiste falha no pacoteenviado, mas cosuma-seutilizar para indicar umaocorrncia relacionadanaquele instante de tempo ;possivelmente estandodisponvel posteriormente .

Observao : Para utilizarmos os mnemnicos, ao invs dos nmeros, nos codigosde erro, precisamos declarar no fonte Advpl a utilizao do Include'ApWebSrv.ch'


22/140

Funes SOAPDTGETD

Reviso: 22/04/2004

Abrangncia

Verso 8.11

Sintaxe

SOAPDTGETD ( < cDateTime > ) --> dDate

Parmetros


cDateTime Caracter String, no formato "Soap" DateTime, a ser considerada.

Retorno

Tipo Descrio

Data Retorna a data identificada na String cDateTime

Descrio

A partir de uma string Advpl, contendo uma data no formato 'soap' DateTime, a funo

SoapDtGetD() retorna a data correspondente em Advpl, como um contedo do tipo 'D'Date.


23/140

Funes SOAPDTGETT

Reviso: 22/04/2004

Abrangncia

Verso 8.11

Sintaxe

SOAPDTGETT ( < cDateTmie > ) --> cTime

Parmetros


cDateTmie Caracter String, no formato "Soap" DateTime, a ser considerada.

Retorno

Tipo Descrio

Caracter Retorna o horrio identificado, no formato HH:MM:SS

Descrio

A partir de uma string Advpl, contendo uma data no formato 'soap' DateTime, a funo

SoapDtGetD() retorna o horrio correspondente em Advpl, como um contedo do tipo'C' Character, no formato HH:MM:SS


24/140

Funes SOAPDTMOUNT

Reviso: 22/04/2004

Abrangncia

Verso 8.11

Sintaxe

SOAPDTMOUNT ( < dData > , < cTmie > ) --> cDateTmie

Parmetros


dData Data Data a ser considerada para a montagem do 'DateTime'

cTmie CaracterHorrio, no formato hh:mm:ss, a ser considerado, para amontagem do 'DateTime'

Retorno

Tipo Descrio

CaracterString 'SOAP', correspondendo Data e Horrios especificados, no

formato DATETIME.

Descrio

A partir de uma Data em Advpl , e um horrio, especificado como string, a funoSoapDtMount() retorna a data e horrio especificados como uma string, no formato'Soap'DateTime.


25/140

Funes WSCLASSNEW

Reviso: 27/04/2004

Abrangncia


Sintaxe

WSCLASSNEW ( < cSrvStruct > ) --> oNewStruct

Parmetros


cSrvStruct CaracterEspecifique o nome da estrutura "Server" de Webservicespara a criao do Objeto.

Retorno

Tipo Descrio

ObjetoA funo retorna uma referncia uma nova instncia da estrutura passada

como parmetro.Caso a estrutura no exista, a funo retornar NIL.

Descrio

Atravs da funo WSClassNew(), possvel criar uma nova instncia de uma estrutura(WSSTRUCT) de WebServices, criada para ser utilizadacomo uma estrutura'Server'. Autilizao desta instuo, para criar instmcias de uma estrutura usada numa aplicao'Server' de WebServices em AdvPl, evida a necessidade de criao de um mtodo'NEW' para cada estrutura.

Observao : Embora seja possvel, no se deve utilizaresta instruo para inicializaruma estrutura criada em um fonte 'Client' em Advpl; pois as estruturas client possuemas definies do mtodo NEW() de cada uma, com as devidas inicializaes deparmetros inetrentes ao servio.


26/140

Funes WSDLDBGLEVEL

Reviso: 22/04/2004

Abrangncia


Sintaxe

WSDLDBGLEVEL (< nLevel > ) --> NIL

Parmetros


nLevel Numrico

Atravs de nLevel , definimos qual o nvel deinformaes a ser mostrado : 0 (default ) = seminformaes adicionais , 1 = Apenas pacote de retorno e 2= Informaes e pacote de Envio e Retorno .Obs: Devemos chamar esta funao apos inicializado oObjeto 'Cliente' do Web Service.

Retorno

Tipo Descrio

(NULO) Esta funo sempre retorna NIL

Descrio

Utilizada para depurao de uma aplicao 'Cliente' de Web Services em Advpl .Atravs desta funo, possvel setar, em tempo de execuo, um 'echo' deinformaesadicionais pertinentes execuo de um mtodo 'Client' de Web Services , a sermostrado no console do servidor Protheus ( caso habilitado ) , permitindo aindaparametrizar um nvel dedetalhamento das informaes a serem mostradas.

Observaes

O valor informado na chamada desta funo, ser mantido e considerado portodos os mtodos de servios 'Client' em Advpl, executados a partir de entonesta Thread, at que a aplicao seja finalizada, ou esta funo seja chamadanovamente.Esta funo deve ser utilizada nica e exclusivamente para fins de depurao,pois a mesma onera aperformancedaaplicao 'Client'.


27/140

Aplicaes 'Server' em Advpl

Reviso: 22/04/2004

Abrangncia


Neste tpico, e posteriores documentos, so detalhadas as atribuies e funcionalidadesde uma aplicao 'Server'de Web Services, utilizando o Protheus, desde a criao daaplicao at as configuraes necessrias para a publicao do Web Service.

A criao de um 'Server' de Web Services em Advpl consiste na montagem de umaclasse Advplespecial, chamada WSSERVICE, onde cada mtodo da classe uma aodo Web Service. Caber aos fontes desta classe o processamento de uma requisio e a

gerao do respectivo retorno, cabendo ento Lib de Web Services da Infra-Estruturado ERP a camada de troca de dados, recepo, pr-validao etratamento do pacoteSOAP, as converses de dados cabveis do XML para as propriedades de parmetro daclasse Advpl e a montagem do pacote SOAP a partir das propriedades de retornosetadas pelo mtodo executado e retorn-lo ao 'Client' solicitante do proessamento, almde prover o 'Cliente' o documento WSDL referente (s) classe(s) 'Server'compilada(s)no repositrio de objetos em uso e configurado para atender s requisies deprocessamento.

Este mtodo de programao em camadas permite encapsular on tratamentos internos,em se tratando de protocolo HTTP, SOAP e WSDL, tornando relativamente fcil amisso de criar um Web Servie 'Server' utilizando-se do Protheus. Basta escrever umaclasse que receba nenhum, um ou mais que um parmetro e devolva obrigatoriamenteum retorno; configurar o Protheus Server para habilitar a interface HTTP e os WebServices, que a Lib faz todo o resto.


28/140

01. WebServices 'Server' - Configurao

Reviso: 27/04/2004

Abrangncia


O Servidor Protheus como 'SERVER' de WebServices

Um WebService em Advpl utiliza-se de Working Threads (**) para atender assolicitaes de processamento atravs do protocolo HTTP.

Existem duas maneiras de habilitar o WebService : Atravs da criao da seo[WEBSERVICES] no arquivo de configurao do servidor, ou atravs da configuraomanual de um ambiente de Working Threads Extended ( WEBEX ), tambm noinicializador. A diferena entre ambas que a segunda opo permite especificarmaiores detalhes do ambiente de execuo do servio, permite a configurao deservios e Web Sites simultaneamente,e tambm atendimento diferenciado deprocessamento para mais de um host e diretrios virtuais. Quando utilizamos o Protheus8, devemos utilizaro novo assistente de configurao do servidor Protheus -MP8WIZARD, para instalar e configurar o mdulo de WebServices.

Segue abaixo umexemplo documentado de como configurar o servidor Protheus paraWebServices, utilizando a chave [WEBSERVICES].

Observao : Esta configurao exigeque a seo HTTP no esteja configurada noservidor Protheus. Esta configurao ir internamente habilitar o servio de HTTP econfigurar o processo de resposta para WebServices.

[WEBSERVICES]

Enable=1 ; ( Obrigatrio ) Indica se o service est habilitado (1) ou no (0).Environment=ENVTESTE ; ( Obrigatrio ) Indica qual environment do Server

que ir atender as requisiesConout=0 ; ( Opcional ) Permite a exibio de informaes dos status internos do

servio ( default = 0 : desabilitado ) . Utilizado APENAS para depurao, em casosespecficos, pois prejudica significativamentea performance do(s) servio(s).

Trace=0 ; ( Opcional ) Habilita a gravao de um arquivo de log ( wsstrace.log ),contendo as informaes sobre todas as chamadas e status do Web Service ( default = 0)

PrepareIn=01,01 ; (Obrigatrio) Permite especificar qual a empresa e filial doERP sero utilizados para a montagem do ambiente de processamento das requisies.

NameSpace = http://localhost; ( Opcional ) Permite especificar o nome donamespace 'default', utilizado pelo(s) servio(s) compilado(s) sem a definio de'NameSpace'.( default = host atualmente utilizado )

URLLocation = http://localhost; ( Opcional) Permite especificar a url
http://localhost/http://localhost/


29/140

responsvel pelo atendimentos solicitaes de processamento do(s) servio(s) ( default= host atualmente utilizado )

Para configurar o WebService manualmente, deve ser inicialmente habilitado oservio deHTTP do servidor Protheus,configurar um processo WEBEX, apontandopara funes internas de processamento dos Web Services, e configurar um host atravs

do qual as requisioes processamentosero atendidas. Veja no exemplo abaixo :

[HTTP] ;; Configurao do protocolo HTTPEnable=1Port=80Path=c:\Ap7\Http

[localhost];; A ttulo de exemplo, configuramos o hostda estao local.Defaultpage=wsindex.apwResponseJob=WSTESTE

[WSTESTE] ; Configuracao do job para atenderos WebServices

TYPE=WEBEX ;; ( Obrigatrio ) Tipo do Job para Web Services deve serWEBEX

ONSTART=__WSSTART ;; ( Obrigatrio ) configurao fixa para WebServices

ONCONNECT=__WSCONNECT ;; ( Obrigatrio ) configurao fixa paraWeb Services

Environment=ENVTESTE ;; Especifique qual ambiente (environment)doservidor Protheus que ir atenderos WebServices.

INSTANCES=2,5 ;; ( Obrigatrio ) Indica qual a quantidade minima (default )e mxima de processos ( Threads) que sero colocados na memria para atender ssolicitaes de processamento do(s) servio(s) publicado(s).

Conout=0 ;; ( Opcional ) Permite a exibio de informaes dos status internosdo servio ( default = 0 : desabilitado ) . Utilizado APENAS para depurao, em casosespecficos, pois prejudica significativamente a performance do(s) servio(s).

Trace=1 ;; (Opcional) 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 ; (Obrigatrio) Permite especificar qual a empresa e filial doERP sero utilizados para a montagem do ambiente de processamento dasrequisies.

NameSpace = http://localhost/;; ( Opcional ) Permite especificar o nome donamespace 'default', utilizado pelo(s) servio(s) compilado(s) sem a definio de'NameSpace'.( default = host atualmente utilizado )

URLLocation = http://localhost/;; ( Opcional) Permite especificar a url

responsvel pelo atendimentos solicitaes de processamento do(s) servio(s) ( default= host atualmente utilizado )

WSINDEX -ndice de Servios

Uma vez habilitada a configurao para Web Services, obtemos o acesso a umainterface HTTP de consulta ao ndice de servios publicados. Para tal, basta re-iniciar oservidor Protheus aps a configurao ser realizada, abrir um Web Browser ( porexemplo, o Internet Explorer ), e acessar o link http:///wsindex.apw. No caso
http://%3Cservidor%3E/wsindex.apwhttp://localhost/http://localhost/


30/140

do exemplo de configurao acima, basta digitarmos http://localhost/wsindex.apw, enos ser apresentada a interface de consulta o ndice dos servios.

Por exemplo, caso o host configuradi para os wehservices fio o host local (localhost) ,devemos acessar olink http://localhost/wsindex.apw. Utilizando o Protheus8, sermostrada uma tela semelhante vista abaixo:

Nesta interface so mostrados todos os servios compilados e disponibilizados noreopsitrio de objetos em uso no ambiente configurado. Atravs dela, possvel obtermaiores detalhes sobre cada um dos servios compilados.

Cada servio ativo um link para uma pgina, onde so mostrados todos os mtodos doservio, e onde apresentado tambm um link atravs do qual o servidor Protheusfornecera descrio do servio (WSDL). Logo abaixo mostrado o exemplo da tela dedetalhes do servio CFGTABLE.
http://localhost/wsindex.apwhttp://localhost/wsindex.apw


31/140

O Link para a obteno do WSDL encontra-se acima em 'CFGTABLE.apw?WSDL'.Basta clicar neste link , que uma nova janela do Browser ser aberta, mostrando odocumento WSDL deste servio.

Cada mtodo do servio disponibilizado tambm um link, para uma pgina onde somostrados os exemplos de pacotes SOAP que este mtodo especificamente espera para

recepo de parmetros, e o modelo do pacote de retorno do servio.

Caso o fonte-Client Advpl deste servio seja gerado e esteja compilado no repositrioatual, a inteface de consulta habilita a funcionalidade de teste do WebService, atravs dainterface http, mostrando no final da tela o boto "testar".Ao clicar neste, montadauma tela em HTML para que os parmetros do servio sejam preenchidos. Aps osparmetros preenchidos e submetidos, o pacote de retorno do servio e seu respectivostatus retornado no Browse.


32/140

02. Criando um WebService 'Server' como Protheus

Reviso: 23/04/2004

Abrangncia


Para criarmos um WebService 'Server' utilizando o Protheus, primeiro devevemoshabilitar o servidor Protheus como servidor de WebServices. Para tal, veja o documento'configurando o servidor ProtheusparaWebServices. '

Uma vez configurado e habilitado os WebServices no servidor Protheus, deve ser

inicialmente determinados os mtodos aos quais o servio se destina; para entodeterminar os parmetros e retorno de cada mtodo. Uma vez determinadas estasinformaes, deve ser codificada uma classe especial em Advpl , chamadaWSSERVICE, que constituir o servio propriamente dito.

Porm, antes de partir para a codificao, fortemente recomendado que sejam lidos osdocumentos deste tpico, onde so abortados em detalhes a infra-estrutura envolvidacom os WebServices, seu funcionamento e as particularidades de comportamento daclasse de WebServices.


33/140

03. Regras para codificao de umWebService

Reviso: 30/04/2004

Abrangncia


Viso Geral

Paraa codificao deum webservice, foram criadas em Advpl instrues especiais dedeclarao de classe, especficas para WebServices, que suportam nomes 'longos' nonome da classe, mtodos e propriedades. A utilizao destes comandos exige a

declarao do #include 'apwebsrv.ch' no topo do cdigo-fonte; e exige tambm aateno em alguns pontos e particularidades, a iniciar pela nomenclatura do servio,estruturas, mtodos e propriedades.

Caractersticas operacionais do ambiente

Devemos estar atentos ao desenvolver os mtodos de WebServices, devido scaracteristicas operacionais do ambiente de 'Working Threads' utilizado pelo WebServices. Ao executar um mtodo do WebServices, o ambiente ser mantido no ar,aguardando uma nova requisio de processamento, de qualquer servio ou mtodo, ede qualquer cliente. De modo que, ao desenvolver um servio, no devemos deixarabertos as "Querys" utilizadas no mtodo, filtros setados em tabelas principais, euconfiguraes especficas no-padro do ambiente, realizadas para o processamento deum mtodo especfico; pois isto pode causar impacto no funcionamento de todos osWebServices compilados e ativos neste servidor, com efeitos imprevisveis.

Nomenclatura dos Servios

O nome de uma classe para WebServices, deve ser iniciado por um caractere alfabtico,e deve conter apenas os caracteres alfabticos compreendidos entre Ae Z, os caracteresnumricos compreendidos entre 0e 9, podendo tambm ser utilizado o caracter _(underline ) . Um servio no pode ter um nome de uma palavra reservada Advpl, e nopode ter o nome igual a um tipo bsico de informao.

Nomenclatura de Estruturas

O nome dado uma estrutura obedece as mesmas regras de nomenclatura de Servios;no podendo haver uma estrutura com o mesmo nome de um servio declarado.Devemos estar atentos tambm o fato de uma estrutura no estar diretamente ligada o

servio em questo, de modo que no podemos compilar duas estruturas de mesmonome no mesmo repositrio.


34/140

Uma estrutura contitui um agrupamento de dados, criado como uma classe especial(WSSTRUCT) em Advpl. Devemos criar de uma estrutura para um servio, quando necessrio agrupar um conjunto de dadosbsicos e/ou outras estruturas em um nivotipo de informao, que ser utilizada como parmetro e/ou retorno em um ou maismtodos do servio.

Nomenclatura das propriedades-parmetros e retorno

Cada parmetro e retornode todos os mtodosde um servio devem ser declaradoscomo uma propriedade da classe do Servio. Para dar nome a estes,sovlidas asmesmas regras de nomenclatura de Servios, no podendo haver um dado com o mesmonome de um servio ou estrutura j declarados anteriormente.


35/140

04. Tipos Bsicos de Dados - 'Server'

Reviso: 23/04/2004

Abrangncia


Quando escrevemos um WebService 'Server', devemos especfiicar o tipo da informaode cada parmetro e retorno, em conformidade com a especificao 'SOAP', utilizadanos pacotes XML de troca de dados.

So considerados e suportados pelo Protheus, quando da declarao dos parmetros eretorno, os seguintes tipos bsicos :

String Dado Advpl do tipo String.Date Dado Advpl do tipo Data.Integer Dado Advpl do Tipo numrico(apenas numeros

inteiros.)Float 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)

Observaes

Ao declararmos uma propriedade como sendo do tipo "String", no podemosespecificar a palavra "String" em letras maisculas. A palavra STRING, escritadesta maneira, interpretada pelo pr-compilador do Protheus como sendo umaconstante, ocasionando erro de sintaxe da compilao do WebService.


36/140

05. Estruturas - Tipos complexos

Reviso: 23/04/2004

Abrangncia


Definio de Estrutura

Uma estrutura ( tambm conhecida por Complex Type), constitui uma classe especialdo Advpl, chamada WSSTRUCT, criada especificamente para WebServices. Devemoscriar uma estrutura quando temos a necessidade de agrupar mais de uma informao,incluindo tipos bsicos e/ou outras estruturas.

Ao criarmos um servio que dever receber como parmetro um grupo de informaesdefinido, por exemplo, os dados cadastrais de um cliente, devemos criar uma estruturapara agrupar estes dados. Vale ressaltar que a declarao de uma estrutura no amarra amesma o servio em questo, de modo que a mesma estrutura pode ser utilizada paramais de um servio compilado no repositrio. Caso a estrutura criada seja especficapara o servio em questo, recomendado que seja dado um nome mesma que etnha aver com o servio o qual ela pertena, pois no possvel compilar mais de umaestrutura de mesmo nome no repositrio.


37/140

06. Mtodos 'Server' em Advpl -Caractersticas

Reviso: 26/04/2004

Abrangncia


Definio

Um mtodo de um WebService consiste em uma ao a ser disponibilizada no servio.Damos a ela um nome para identificao, declaramos a mesma na estrutura da classe doServio, bem como seus parmetros e respectivo retorno.

Parmetros

Ao declarar o fonte de um mtodo, o mesmo pode receber um ou mais parmetros, detipo bsico e/ou estruturas, e inclusive pode no receber parmetro algum. Neste caso,devemos especificar que o parmetro recebido ser NULLPARAM, ou seja, nenhumparmetro.

Retorno

Um mtodo de WebServices deve obrigatoriamente tr uma propriedade de retorno.No faz parte da especificao de WebServices a criao de um mtodo que no possuaretorno.

Codificando o mtodo em Advpl

Como visto anteriormente, tanto os parmetros quanto o retorno de um mtodo deWebServices deve ser declarado como um dado da classe ( atravs da instruoWSDATA ).

Quando escrevemos um mtodo de um WebService, e o mesmo recebe uma solicitaode processamento, as propriedades declaradas como parmetros do mtodo soalimentadas, e o mtodo executado. Por tratarem-se de propriedades, o cdigo fonte

Advpl dever interagir com estas propriedades, prefixando-as com '::' dois pontosseguidos), ou 'self:' , sendo isto vlido tanto para os parmetros do mtodo, como para apropriedade de retorno.

Dada a existncia de uma LIB de Infra-Estrutura, que realiza a camada de comunicao,validao, montagem e desmontagem de pacotes; ao codificar um mtodo deWebService existem sempre dois retornos : A propriedade de retorno do mtodo, e oretorno efetivo do mtodo ao final do processamento.


38/140

O retorno efetivo do mtodo deve ser um valor booleano : Se retornado .T. (True) , istoindica LIB, que o mtodo foi executado com sucesso, e consequentemente apropriedade de retorno foi alimentada. Logo, o pacote 'SOAP' de retorno do mtodo sermontado pela LIB, e devolvida automaticamente o 'Client' que solicitou a chamada deprocessamento.

Caso o retorno efetivo do mtodo seja .F. (False), isto indica LIB que, por algumarazo tratada no fonte do mtodo, no foi possvel a execuo do mtodo. Nestecaso,devemos especificar, antes do retorno, atravs da funo SetSoapFault(), a causa daimpossibilidade de processamento.

Exemplo

WSMETHOD GetDate WSRECEIVE NULLPARAM WSSENDHorarioWSSERVICE ServerTime

If dow(date())=1// Seta um soap_fault, informando que este servio no disponvel aos domingosSetSoapFault('Metodo no disponvel','Este servio no funciona aos Domingos.')

// e retorna .F., indicando que o servio no foi processado com sucesso.Return .f.

Endif

// alimenta a propriedade de retorno::Horario := time()

// E retorna .T. indicando processamento do mtodo com sucesso

Return .T.

Ateno :

Sempre que o retorno efetivo do mtodo verdadeiro (.T. ), a propriedade deretorno deve ser preenchida. Caso ela no seja preenchida, a LIB ir retornar oclient solicitante um pacote de SOAP Fault, indicando que houve um erro noprocessamento do servio, e registrar um error.log na estao servidora. Sergerado tambm uma ocorrncia de erro, caso o mtodo retorne .T., porm afuno SetSoapFault() tenha sido chamada durante a execuo do mtodo. Aocorrncia gerada : RETURN .T. WITH SOAPFAULT EXCEPTION NOT EMPTY.Sempre que o retorno efetivo do mtodo falso (.F.), a funo SetSoapFault()

deve ser chamada, para que a LIB gere um pacote com o motivo do erro para o'Client' que solicitou o mtodo. Caso o retorno efetivo seja .F. , e a funo

SetSoapFault() no tenha sido chamada, devolvido estao'Client' solicitantedo processamento um Soap:Fault , com aocorrncia de erro :RETURN .F. WITH SOAP FAULT EXCEPTION EMPTY.


39/140

07. Tratamento de Erro dos WebServices

Reviso: 27/04/2004

Abrangncia


Dada a infra-estrutura envolvida no processamento dos WebServices, a rotinadetratamento de erro da aplicao WebServices 'Server' prev o tratamento de ocorrncias,desde advertncia de carga dos servios, at falhas de inicializao de ambiente,passando por erros que invalidam um determinado servio compilado, at as ocorrnciasde inconsistncias de parmetros de chamada do servio, inconsistncias de retorno,ocorrncias de erro fatal de processamento na aplicao, eocorrncias deprocessamento que no constituam um erro fatal, porm devem retornar um pacote de

ocorrncia de erro, conhecido por SOAP FAULT .

Os tratamentos aplicados s ocorrncias reproduxidas no momento da carga doambiente de WebServices esto relacionados no tpico "Falhas de Carga dos Servios",os relacionados ocorrncias de erro fatal de execuo dos servios esto em"Ocorrncias de Erro Fatal", e a discrminao da utilizao do Soap Fault est estdescrita em "Utilizao do SOAP FAULT".


40/140

08. Utilizao do SOAP FAULT

Reviso: 30/04/2004

Abrangncia


Quando desenvolvemos um servio, e temos a necessidade de retornar ao 'Client'solicitante do processamento, uma ocorrncia de falha no-fatal de um determinadoprocessamento, deve ser retornado ao mesmo um pacote SOAP, que indica a causa dafalha. Este pacote conhecido por 'SOAP FAULT'.A rotina de tratamento de erro fatalde execuio do WebService, quando da ocorrncia de tal, geraautomaticamente um'SOAP FAULT' com a descrio resumida da ocorrncia o client solicitante.

Dado que, a camada da lib, responsvel pela interpretao do pacote SOAP recebidopelo servio, j se encarrega de validar o formato do pacote e contedos obrigatrios,um Web Service escrito em Advpl deve, antes de realizar o processamento proposto,validar se o contedo dos parmetros est dentro da faixa de dados esperada, econdizentes com o esperado; para ento realizar o processamento e retornar o clientsolicitante.

Para inserir as excesses de execuo com Soap-Fault, em um servio 'Server',utilizamos a funo SetSoapFaut().

Soap-Faults padro do Servidor Protheus de WebServices

A camada de comunicaoda infra-estruruta de WebServices, realiza automaticamenteos tratamentos de protocolo, formato do pacote SOAP e parmetros obrigatrios. Casoexista alguma inconsistncia na chamada de um servio,que incorra em alguma destasexcesses, o servio solicitado no chamado, e o servidor Protheus devolveautomaticamente o client solicitante um Soap-Fault, indicando o que aconteceu.

Estas ocorrncias de Soap-Faultso mostradas no console do servidorProtheus, e soarmazenadas tambm no arquivo error.log do ambiente utilizado.

Soap-Faults padro aps processamento do servio

A camada de comunicaoda infra-estruruta de WebServices valida tambm amontagem do pacote de retorno.Caso exista alguma propriedade de retorno obrigatriodo servio que no esteja alimentada de forma correta, o servidor Protheus devolveautomaticamente o client solicitante um Soap-Fault, indicando que ocorreu um errointerno no servidor de WebServices.


41/140

09. Servio de Exemplo : SERVERTIME

Reviso: 27/04/2004

Abrangncia


Inicialmente, o exemplo proposto tm o objetivo de montar um WebService que retorneo horrio no servidor Protheus. Para tal, ser criado um servio, com apenas(inicialmente) um mtodo. A esteservio, daremos a ele o nome de SERVERTIME. E,ao mtodo de buscar o horrio no servidor, daremos o nome de GETSERVERTIME.

A operao de buscar o horrio atual no servidor no necessita de nenhum parmetropara a execuo. Porm, ela ter um retorno : O horrio atual , no formato 'hh:mm:ss'. A

especificao de um WebServices permite que um servio seja declarado de modo a noreceber nenhum parmetro, porm exige que o WebService sempre possua um retorno.

Codificando o Servio

Para codificar um servio, devemos utilizar o Protheus IDE, e criar um novo arquivo deprograma, e nele escrever o servio. A numerao disposta esquerda do cdigo-fonte meramente ilustrativa, no devendo ser digitada. Ela utilizada mais abaixo, onde estecdigo detalhado linha a linha.

1 #INCLUDE 'PROTHEUS.CH'2 #INCLUDE 'APWEBSRV.CH'3

4 WSSERVICE SERVERTIME

5 WSDATA Horario as String6 WSMETHOD GetServerTime7 ENDWSSERVICE

8

9 WSMETHOD GetServerTime WSRECEIVE NULLPARAM WSSEND Horario

WSSERVICE SERVERINFO

10 ::Horario := TIME()11 Return .T.

Linha 1 especificada a utilizao do Include Protheus.ch, contendo as definiesdos comandos ADVPL e demais constantes

Linha 2 Tambm especificamos a o Include ApWebSrv.ch, que contm as definiesde comandos e constantes utilizados nas declaraoes de estruturas e mtodosdos Web Services. Ele obrigatrio para o desenvolvimento de WebServices.

Linha 4 Com esta instruo, definido o inicio da classe do servio principal, ao qualdemos o nome de SERVERTIME

Linha 5 Dentro da estrutura deste servio, informado que um dos parametrosutilizados chama-se horrio, e ser do tipo String


42/140

Linha 6 Dentro da estritura deste servio, informado que um dos mtodos do serviochama-se GetServerTime .Linha 7 Comono so necessrias mais propriedades ou metodos neste servio, aestrutura do servio fechada com esta instruo..Linha 9 Aqui declarado o fonte do Mtodo GetServerTime, que no receber

parametro nenhum ( mas para efeitos de declarao deve ser informado que elereceber o parametro NULLPARAM ), e informado que seu retorno ser odado Horario ( declarado na classe do servio como uma propriedade, do tipoString ) .

Linha 10 atribudo na propriedade ::Horario da classe deste servio, o retorno dafuno Advpl Time(), que retorna a hora atual no servidor no formatoHH:MM:SS. Devemos utilizar o '::', para alimentarmos a propriedade da classeatual

Linha 11 O mtodo GetServerTime finalizado nesta linha, retornando .T. (true),indicando que o servio foi executado com sucesso.

Aps compilado o servio, deve ser acessada novamente a pgina de ndice de servios(wsindex.apw), e verificar se o novo servio compilado l se encontra.

Testando o Servio

Ao acessar a pgina de ndice, e constatarmos a existncia do servio, devemos obter olink atravs do qual o WSDL deste servio est sendo fornecido, eutilizarmos de umaferramenta para gerar um 'Client' que possibilite o uso deste servio. possvel,inclusive, utilizar o Protheus IDE para gerar o fonte 'Client' para testar o servio; pormexiste a necessidade de criar uma funo para instanciar a classe 'Client' gerada,alimentar os parmetros e testar o servio.

A partir da verso Protheus 8, podemos apenas gerar um fonte 'Client' desta classe, ecompil-lo no mesmo repositrio do ambiente utilizado pelo WebServices 'Server', que

a prpria interface de ndice de Servios ir permitir o teste do mesmo.


43/140

Falhas de Carga dos Servios

Reviso: 06/05/2004

Abrangncia


Neste tpico so abordadas as mensagens de ocorrncias relacionadas carga dosservios.

Durante a inicializao do enginede Web Services, os servios compilados sovalidados, e um ambiente montado por threadpara o atendimento de solicitaes deprocessamento. Neste processo, existem ocorrncias, relacionadas montagem doambiente, que podem impossibilitar a operao dos WebServices como um todo; e

ocorrncias que podem invalidar apenas um servio, em caso ed inconsistncia dadeclarao do mesmo.


44/140

Erro de Estrutura : ARRAY OF emparametro de en...

Reviso: 27/04/2004

Abrangncia


XXX : Erro de Estrutura : ARRAY OF em parametro de entrada direto naosuportado.

Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um parmetro [XXX] foi utilizado como parmetro de entrada

direto de um WebService, porm o mesmo foi declarado com tratamento de 'Array Of'.No suportado receber diretamente um array como parmetro de um mtodo deWebServices 'Server'.

Verifique e corrija o cdigo-fonte, e crie uma estrutura intermediria para encalsular oparmetro que deve ter tratamento de Array.

Erro de Estrutura : Estrutura

Indefinida.Reviso: 27/04/2004

Abrangncia


[XXX] : Erro de Estrutura : Estrutura Indefinida.

Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando uma propriedade da classe server foi especificado como sendo umaestrutura ( tipo no-bsico), porm a declarao da estrutura no foi localizada.

Verifique e corrija ocdigo-fonte e proceda com a declarao da referida estrutura.


45/140

Erro de Estrutura : Nome de EstruturaInvlido ...

Reviso: 27/04/2004

Abrangncia


[XXX]Erro de Estrutura : Nome de Estrutura Invlido -Tipo bsico conflitante.

Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando o nome de uma determinada estrutura [XXX]foi especificado comum nome iguala um tipo bsico de informao. Esta ocorrncia invalida apenas o

servio que utiliza a determinada estrutura.

Verifique e corrija ocdigo-fonte e a declarao do tipo da estrutura.

Erro de Mtodo : Estrutura de Entradano encon...

Reviso: 27/04/2004

Abrangncia


[XXX] : [YYY] : Erro de Mtodo : Estrutura de Entrada no encontrada.

Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi especificado com algum

parmetro de entrada [YYY],cuja declarao no foi encontrada como uma propriedadeno fonte construtor do servio.

Verifique e corrija o cdigo-fonte, e declare o parmetro YYY como uma propriedadeda classe XXX


46/140

Erro de Mtodo : Estrutura de Retornono encon...

Reviso: 27/04/2004

Abrangncia


[XXX] : [YYY] : Erro de Mtodo : Estrutura deRetorno no encontrada.

Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi especificado com uma estrutura[YYY],cuja declarao no foi encontrada como uma propriedade no fonte construtor

do servio.

Verifique e corrija o cdigo-fonte, e declare a propriedade YYY como uma propriedadeda classe XXX

Erro de Mtodo : Estrutura de Retornono pode ...

Reviso: 27/04/2004

Abrangncia


[XXX] : [YYY] : Erro de Mtodo : Estrutura de Retorno no pode ser recebida comoparmetro.

Durante a etapa de validao dos servios,na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi declarado para receber umaestrutura [YYY] e retornar a mesma estrutura [YYY] . Isto no suportado pelosWebServices do Protheus.

Verifique e corrija o cdigo-fonte.


47/140

Erro de Mtodo : Mtodo [XXX] doServio [YYY] ...

Reviso: 27/04/2004

Abrangncia


Erro de Mtodo : Mtodo[XXX] do Servio[YYY] no declarado no Servio.

Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX], referente o servio [YYY], foicodificado, porm no foi declarado no construtur do Web Service.Esta ocorrncia

invalida apenas o servio que utiliza a determinada estrutura.

Verifique e corrija ocdigo-fonte e proceda com a declarao do mtodo no construtordo servio.

Erro de Mtodo : Nome de MtodoInvlido - Tipo...

Reviso: 27/04/2004

Abrangncia


[XXX] Erro deMtodo : Nome deMtodo Invlido -Tipo bsico conflitante.

Durante a etapade validao dos servios, na carga dos WebServices, esta ocorrncia

reproduzida quando o nome de uma determinadamtodo [XXX]foi especificado comum nome igual a um tipo bsico de informao. Esta ocorrncia invalida apenas oservio que utilizao determinado mtodo.

Verifique e corrija ocdigo-fonte e a declarao do nome do mtodo.


48/140

Erro de Estrutura : Redundancia deEstruturas

Reviso: 27/04/2004

Abrangncia


Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando temos uma cadeia de estruturas, compostas por tipos bsicos eoutras estruturas, e a declarao das estruturas entre em redundncia. Por exemplo,declaramos a estrutura ,que tem dentro dela uma outra propriedade que do tipo, ou a estrutura tm uma propriedade de tipo , e por sua vez tem uma

propriedade do Tipo .

Verifique e corrija o cdigo-fonte e corrija a declarao das estruturas envolvidas.

WSDL Server ONLOAD ERROR -Falha Interna na ...

Reviso: 27/04/2004

Abrangncia


WSDL Server ONLOAD ERROR -Falha Interna na Carga do WebService

Esta ocorrencia apresentada na tela de ndice dos WebServices ( wsindex.apw ),quandoalgum erro fatalocorra na carga dos WebServices. Os detalhes sobre a

ocorrncia fatal so mostrados no console do servidor Protheus, e gravados no arquivoerror.log do ambiente em uso.


49/140

Ocorrncias de Erro Fatal - AUTOMATICURLLOCATION FAILED

Reviso: 22/04/2004

Abrangncia


Ao configurarmos um WebService 'Server', devemos especificar, atravs da chaveURLLOCATION , a url especfica para o acesso os servios.

Quando no definimos esta URL, a lib de WebServices identifica automaticamente sobqual hosto servio foi acessado. Esta operao no possvel quando o header HTTP

do pacote informe uma operao diferente de "GET" ou "POST",ou o servidor Protheusest sendo execudado em sua verso ISAPI, em conjunto com o Microsoft (R)Information Service.

Caso no seja possvel identificar o host sob o qual a chamada foi realizada, oWebService no processado, e o processamento abortado com a ocorrncia de erroacima.


50/140

Ocorrncias de Erro Fatal - BUILD [XXX]USING WEBSERVICES HTTPS NOTSUPPORTED

Reviso: 22/04/2004

Abrangncia


Quandoda carga inicial dos WebServices 'Server', a configurao URLLOCATION criticada pela Lib. Caso seja especificado que o acesso ser realizado via 'HTTPS', e obuild atual do servidor Protheus utilizado ainda no suportaa utilizao do WebService

sob o protocoloHTTPS.

INVALID URLLOCATION [XXX] ON[YYY]

Reviso: 22/04/2004

Abrangncia


Quando da configurao do servidor Protheus para WebServices, caso especificada aconfigurao URLLOCATION, porm a mesma no seja especificada com uma sintaxevlida, o processamento abortado na subida das Working Threadsdo servidor, comesta ocorrncia de erro fatal, indicando em [XXX] a url informada,e em [YYY] o nomedo arquivo de configurao do servidor Protheus.

Uma url considerada invlida, caso ela no seja iniciada com 'http://' ou 'https://', sejafinalizada com um caractere no-alfanumrico ou diferente de '/', ou possua caracteresacentuados ou espaos. So considerados vlidos apenas caracteres alfanumricos, e oscaracteres ':' (dois pontos), '.' (ponto), '/' (barra) e '-' (hfen).

Esta validao foi implementada na Infra-Estrutura de Web Services a partir da versode infra-estrutura 'ADVPL WSDL Server 1.031209'


51/140

Ocorrncias de Erro Fatal - REQUIREDReturn property [X] AS ARRAY OF [Y]IS ..

Reviso: 23/04/2004

Abrangncia


REQUIRED Return property [X] AS ARRAY OF [Y] IS EMPTY

Esta ocorrncia de erro, reproduzida quando do trmino do processamento de um

mtodo de um WebServices, na camada da LIB, quando da gerao do pacote 'SOAP'de retorno o 'Client' solicitante do servio.

Quando da identificao da propriedade [X] de retorno obrigatrio do mtodo , amesma deveria ser um 'Array' Advpl, contendo no mnimo um elemento; porm o arrayno continha nenhum elemento.

Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno esteja sendoalimentada.


52/140

Ocorrncias de Erro Fatal - REQUIREDReturn property [X] Type [Y] Unexpect...

Reviso: 23/04/2004

Abrangncia


REQUIRED Return property[X]Type [Y] Unexpected Valtype [Z]



Quando da identificao da propriedade obrigatria[X] de retorno do mtodo , amesma deveria ser alimentada com um contedo Advpl do tipo [Y], porm, ao invsdeste, ela continha um valor do tipo Advpl [Z].

Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno estejaalimentada com um contedo do tipo [Y], emconformidade com a declarao dapropriedade no servio.


53/140

Ocorrncias de Erro Fatal - Returnproperty [X] AS ARRAY Type [Y]Unexpected..

Reviso: 23/04/2004

Abrangncia


Return property[X]AS ARRAY Type [Y] Unexpected Valtype [Z]



Quando da identificao da propriedade [X] de retorno do mtodo , a mesma deveriaser um 'Array' Advpl, contendo elementos do typo [Y], porm, ao invs da propriedadeser um do Tipo A (Array), ela continha um valor do tipo Advpl [Z].

Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno estejaalimentada com um array,


54/140

Ocorrncias de Erro Fatal - Returnproperty [X] AS OBJECT Type [Y]Unexpect ..

Reviso: 23/04/2004

Abrangncia


Return property[X]ASOBJECT Type [Y] Unexpected Valtype [Z]



Quando da identificao da propriedade [X] de retorno do mtodo , a mesma deveriaser umaEstrutura ( Tipo Advpl 'O' -Objeto ) Advpl, do typo [Y], porm a propriedadede retorno continha um valor do tipo Advpl [Z].

Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno sejaalimentada com a respectiva estrutura, em conformidade com a declarao dapropridade da classe do servio.


55/140

Ocorrncias de Erro Fatal - Returnproperty [X] Type [Y] UnexpectedValtype ..

Reviso: 23/04/2004

Abrangncia


Return property[X]Type [Y] Unexpected Valtype [Z]



Quando da identificao da propriedade [X] de retorno do mtodo , a mesma deveriaser alimentada com um contedo Advpl do tipo [Y], porm, ao invs deste, ela continha

um valor do tipo Advpl [Z].

Verifique o mtodo solicitado, e certifique-se que a propriedade de retorno estejaalimentada com um contedo do tipo [Y], em conformidade com a declarao dapropriedade no servio.


56/140

Ocorrncias de Erro Fatal - UNKNOWERROR : EMPTY HTTP RETURN

Reviso: 29/04/2004

Abrangncia


Quando do processamento de uma requisio de um mtodo de WebServices 'Server',so executadas consistncias de pr-processamento e ps-processamento. Todas asconsistncias internas realizadas tm uma mensagem de retorno. Quando do final daexecuo do servio, independentemente de ocorrer um processamento com sucesso oucom falha ( SoapFault), verificado se o tratamento efetuado gerouum pacote com a

mensagem de retorno.

Caso esta ocorrncia seja reproduzida, ela indica que ocorreu uma falha no tratada, ouuma impossibilidade de gerao do pacote de retorno. At o momento, esta ocorrnciano foi reproduzida sob nenhuma condio.


57/140

Ocorrncias de Erro Fatal - [SVC] :[METHOD] as [X] : Tipo Inesperado deRet..

Reviso: 06/05/2004

Abrangncia


[SVC] : [METHOD] as [X] : Tipo Inesperado de Retorno do Mtodo.

A ocorrncia de erro acima reproduzida, quando do trmino da execuo de um

mtodo de uma classe 'Server' de WebServices. A LIB espera um valor booleano ( .T.ou .F. ) de retorno efetivo do mtodo. Caso o retorno efetivo no seja booleano, oprocessamento abortado com a ocorrncia acima, identificando o servio chamado em[SVC], o mtodo em [METHOD], e o tipo do retorno efetivo retornado em [X].

Verifique o cdigo-fonte do mtodo do servio, e certifique-se que o retorno efetivo domtodo seja sempre .T.ou .F.


58/140

Aplicaes Protheus 'Client' deWebServices

Reviso: 30/04/2004

Abrangncia


Definio de Client

Quando um Web Service 'Server' criado e disponibilizado, junto dele tambm disponibilizada a definio do servio, seus argumentos, estruturas e retornos (WSDL) .Para a utilizao de um Web Service, necessrio montar um programa client, que

seja capaz de montar um envelope SOAP com os dados necessrios ao processamentodo Servio, realizar a chamada, e tratar o pacote de retorno do servio e suas respectivasexcesses.

Embora existam Web Services que podem ser acessados via Http direto, apenaspassando parmetros via URL, o client de Web Services do Protheus tm seu foco erecursos direcionados apenas a servios que possuam interface de comunicao querealize POST de pacotes de dados XML em formato SOAP. O Protheus possuiferramentas e infra-estrutura incorporadas que permitem esta integrao.

Gerao do Client em Advpl

Utilizando o IDE, encontra-se disponvel, no menu 'Ferramentas', a opo para que,atravs de um link para a obteno do documento WSDL de um servio, o Protheusgere automaticamente, em Advpl, uma classe 'Client' para a comunicao e utilizaodo mesmo.

Para tal, basta obtermos o endereo internet ( URL) do WSDL desejado, criar um novoarquivo-fonte, e acessar o menu 'Ferramentas -> Gerar Cliente WebServices...'. Paracada servio que se tenha a necessidade de gerao de um fonte client, recomenda-sefortemente que cada fonte client seja gerado em um arquivo independente e exclusivopara este fim, e que de forma alguma este fonte gerado pelo assistente seja alterado.

Requisitos bsicos para a Gerao do Client em Advpl

O processo de gerao de fonte disparado atravs do IDE, porm o servidorProtheusque ir buscar o documento WSDL solicitado. De modo que, a estaoservidora utilizada no ambiente deve ter acesso o endereo solicitado.


59/140

Aplicaes Protheus 'Client' de WebServices- Gerao de Client em Advpl - Passo 01

Reviso: 30/04/2004

Abrangncia


Passo 1 : Determinar como obter o WSDL do servio desejado

A maioria das definies WSDL dos servios disponiveis na WEB so acessadosatravs 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 ) oWSDL de uma maneira diferente . O WSDL de alguns servios restritos ( como porexemplo o servio de busca na base de dados do Google ) so disponibilizados emarquivo ASCII, enviados por e-mail, apos um cadastro no site e autorizao da empresapara o uso do servio por ele provido.

No nosso exemplo ilustrativo, a definio do servio obtida diretamente via http,atravs do link http://localhost/SERVERTIME.apw?WSDL Caso este link sejaacessado atravs de um Web Browser ( Internet .Explorer., por exemplo ), ser exibido

no browse um documento XML correspondendo a definio do servio.
http://localhost/SERVERTIME.apw?WSDL


60/140


Reviso: 30/04/2004

Abrangncia


Passo 2 : Gerar o Fonte AdvPl do clientusando o Assistente do IDE

Ao ser gerado um fonte clientpara um Web Service, este fonte conter asdefinies 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 preferencialmenteser gerado e compilado em um arquivo exclusivo, destinado unica e exclusivamente aeste cdigo. E, por tratar-se de uma classe Advpl gerada a partir da definio de umservio, no deve ser inserida e/ou alterada nenhuma das definies geradas peloassistente, pois as mesmas sero perdidas caso o fonte seja gerado novamente .

Para gerao do fonte clientem Advpl para utilizar este servio, necessriocriar um novo arquivo .PRX no IDE, especificamente para conter as classes desteservio . Ento, deve ser acessado o menu Ferramentas, opo Gerar CienteWebservices . Neste momento, ser mostrado na tela um pop-up semelhante ao

mostrado abaixo :

No campo de entrada de dados, deve ser digitada 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 sermostrado um texto semelhante ao abaixo :

Estabelecendo conexo com o server...Por favor aguarde. Obtendo descrio do WebService...Finalizando conexo com o server...Ok
http://localhost/SERVERTIME.apw?WSDL


61/140

E, na janela do novo arquivo criado, dever ser criado um cdigo-fontesemelhante ao mostrado abaixo :

#INCLUDE 'PROTHEUS.CH'

#INCLUDE 'APWEBSRV.CH'

---header do servio ---/*

================================================================

===============

WSDL Location http://localhost/SERVERTIME .apw?WSDLGerado em 12/30/02 17:21:29

Observaes Cdigo-Fonte gerado por ADVPL WSDL Client 1.021217 BAlteraes neste arquivo podem causar funcionamento incorreto

e sero perdidas caso o cdigo-fonte seja gerado novamente.

================================================================

=============== */

/* -------------------------------------------------------------------------------

WSDL Service WSSERVERTIME

-------------------------------------------------------------------------------*/

---declarao da Classe clientdo 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 alimentaas propriedades de retorno do metodo, contendo os encapsulamentos necessrios para

tratamento deexcesses ---WSMETHOD GETSERVERTIME WSSEND NULLPARAM WSRECEIVE cGETSERVERTIMERESULT WSCLIENT

WSSERVERTIME

Local cSoap := '', oXmlRet

BEGIN WSMETHOD

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

cSoap += ''cSoap += ''

oXmlRet := SvcSoapCall( Self,cSoap,;'http://localhost/GETSERVERTIME',;'DOCUMENT','http://localhost/',)
http://localhost/',http://localhost/GETSERVERTIME',;http://localhost/'%3E'http://localhost/SERVERTIME.apw'http://localhost/SERVERTIME.apw?WSDL


62/140

::cGETSERVER TIME RESULT := xGetInfo( oXmlRet,'_GETSERVERTIMERESPONSE:_GETSERVERTIMERESULT:TEXT', '' )

END WSMETHOD

oXmlRet := NIL

Return .T.

O fonte acima constitui uma Classe em Advpl, gerada para realizar a interfacecom a classe original publicada no Server, j realizando os tratamentos adequados pararealizar a comunicao via httpcom o servidor onde o servio est publicado. Valeobvervar que, as linhas em negrito no fonte acima no foram inseridas pelo assistente doIDE, mas acrescentadas a este documento para fins didticos.

O cabealho do fonte contm informaes sobre a localizao do WSDLutilizado para a gerao do fonte, data e hora de gerao e verso do engine de WebServicesutilizado . Logo abaixo, a declarao de uma classe clientde Web Services(WSCLIENT WSSERVERTIME ), com o mtodo new() para inicializao daspropriedades advpl da classe . E, em seguida, a declarao do mtodo de busca de

Horrio ( WSMETHOD GETSERVERTIME ), que no envia parmetro algum, eretorna o horrio atual do server em :: cGETSERVERTIMERESULT, com todos ostratamentos necessrios embutidos.


63/140


Reviso: 22/04/2004

Abrangncia


Passo 3 : Criar um fonte que utilize esta classe para utilizao do WebService.

Agora, necessrio criar um novo arquivo no IDE, e montar uma funo parautilizar a classe de Web Servicesclientpara obter o horrio no servidor.

1 #INCLUDE 'PROTHEUS.CH'2

3 User Function TestClient()4 Local oSvc := NIL

5

6 oSvc := WSSERVERTIME():New()7

8 If oSvc:GETSERVERTIME()

9 alert('Horrio no Servidor : '+ oSvc:cGETSERVERTIMERESULT)10 Else11 alert('Erro de Execuo : '+GetWSCError())12 Endif

13

14 Return

Linha 1 declarada a utilizao do Include Protheus.ch, contendo as definies doscomandos ADVPL e demais constantes

Linha 3 Inicia-se a definio da User Function para utilizar o Web ServiceLinha 4 Uma varivel local declarada para conter o Objeto do Web ServiceclientLinha 6 Utilizando-se do servio, a varivel oSvc alimentada com uma onva instncia

do Web Servicesclient, obtida atravs da sintaxe():New()

Linha 8 executado o mtodo GetServerTime a partir do Objeto do servio oSrv, sempassar qualquer parametro. O retorno de um mtodo do clientpode ser .T.(true) em caso de execuo com sucesso ou .F. (false) em caso de falha de

execuo .Linha 9 Caso o servio tenha sido executado com sucesso, o retorno esperado

alimenrado na propriedade cGetServerTimeResult do objeto do servio.Linha 11 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 ser possvel recuperar maiores detalhes sobre aocorrncia de erro, deve ser utilizada a funo GetWSCerror(), que retorna umastring com o resumo da ocorrncia .

Linha 13 O programa de teste finalizado com um Return


64/140


Reviso: 22/04/2004

Abrangncia


Passo 4 : Executar o programa de testes

Abra uma nova instncia do Ap Remote, e execute a funo U_TESTCLIENT .Caso o Web Serviceesteja no ar e funcionando, e o fonte clientseja devidamentecompilado e sem erros, o resultado esperado uma janela semelhante a mostrada

abaixo:

No ambiente montado para teste, o Servidor de Web Servicese o clientestono Protheus, compilados no mesmo Repositrio de Objetos . Para fins didticos,

possvel simular uma ocorrncia de falha no client, ao desabilitar o ServerHTTP doProtheus (colocando enable=0 na chave [http] do arquivo de consigurao do servidor),re-iniciar o Server Protheus, e executar o programa clientnovamente . Deve ser obtidauma tela semelhante a exemplificada abaixo :


65/140


Reviso: 22/04/2004

Abrangncia


Passo 5 : Obtendo informaes de debug

Visto at o passo 4, um exemplo completo de um clientfuncionandoperfeitamente . Agora, possvel imaginar que, durante o desenvolvimento e testes doclientdo servio, faam-se necessrias determinadas informaes internas as rotinas

de execuo do servio no clientAdvpl . Para tal, foi criada uma funo que permitedefinir em tempo de execuo, um nvel de detalhamento de informaes adicionaisrelacionadas ao Web Service; informaes estas que sero mostradas no Console doServer Protheus ( caso habilitado ) . a Funo para definir o nvel de detalhe chama-seWSDLDbgLevel(), e recebe um nmero como parmetro :

0 ( default ) Sem informaes adicionais.

1 Apenas String SOAP de retorno do Server.

2 Strings Soap de Envio e Retorno.

Ento, na linha 7, acrescentada a instruo WSDLDbgLevel(2), para ativar o

nvel mais completo de informacoes adicionais, e possvel observar no console doservidor as mensagens apresentadas durante a execuo do fonte de testes do client.Deve ser obtido um echo no console do server semelhante ao exemplo abaixo :

Iniciando Thread (siga0984, AUTOMAN)...------------------------------------------------------------------------------- SvcSoapCall to http://automan:8000/webservice/SERVERTIM E.apw /DOCUMENT

NameSpace http://automan:8000/webservice/

SoapAction http://automan:8000/webservice/GETSERVERTIME

Called from GETSERVERTIME ( 137)Called from U_TESTCLIEN T ( 10)----------------------------------SOAPSEND -----------------------------------
http://schemas.xmlsoap.org/soap/enhttp://www.w3.org/2001/XMLSchema'http://www.w3.org/2001/XMLSchema-instance'http://automan:8000/webservice/GETSERVERTIMEhttp://automan:8000/webservice/http://automan:8000/webservice/SERVERTIME.apw


66/140

------------------------------------------------------------------------------- ---------------------------------POST RETURN ---------------------------------10:37:10

-------------------------------------------------------------------------------

Fim Thread (siga0984, AUTOMAN) BytesIn 73 BytesOut 75O 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 ) aoServidor, e o conteudo em amarelo( POST RETURN ) informa o contedo do pacoteSoap devolvido pelo Server referente a esta solicitao.

Quando ocorre um erro qualquer, relacionado a execuo do clientWebServices, o mtodo chamado retorna .F., e o erro pode ser recuperado atravs da funoGetWSCerror(), vista anteriormente . Para cada excesso prevista no client, existe umcdigo de erro correspondente, todos eles prefixados com WSCERR . A maioria dasocorrncias est relacionada a gerao do Cdigo fonte do clientAdvpl utilizado-se oIDE. Todas as ocorrenctas de excesso tratadas peo Web ServicesclientAdvpl estorelacionadas no Tpico Web ServicesclientCdigos de Erro .
http://automan:8000/webservice/'%3E%3CGETSERVERTIMERESULT%3E10:37:1http://schemas.xmlsoap.org/soap/envelope/'%3E%3Csoap:Body%3E%3CGETSERVERThttp://www.w3.org/2001/XMLSchema'http://www.w3.or/http://automan:8000/webservice/'%3E


67/140

Aplicaes Protheus 'Client' de WebServices- Tipos de dados suportados - 'Client'

Reviso: 22/04/2004

Abrangncia


At o momento, so suportadas as geraes de cdigo Advpl para WebServices 'Client',que utilizam os tipos bsicos de dadoslistados abaixo.Parapermitir a manipulao decada tipo, utilizando variveis Advpl, so utilizados os tipos bsicos do Advpl paratratar simultaneamente mais de um tipo de dado dos pacotes 'SOAP' dos WebServices.

Os tipos abaixo so disponibilizados em Advpl atravs de uma varivel de tipo 'N'

Numrica

INTINTEGERBYTEFLOATDOUBLEUNSIGNEDLONGUNSIGNEDINTDECIMAL

LONG

Os tipo abaixo disponibilizado em Advpl atravs de uma varivel de tipo 'D' Data

DATE

Os tipos abaixo so disponibilizados em Advpl atravs de uma varivel de tipo 'C'Character

STRINGDATETIMECHAR (**)BASE64BINARY

(**) O tipo CHAR corresponde uma string, contendo o nmero do caracterecorrespondente tabela ASCII

Os tipo abaixo disponibilizado em Advpl atravs de uma varivel de tipo 'L' Logica

BOOLEAN


68/140

WSCERR000 / WSDL no suportado.Existe mais de ..

Reviso: 22/04/2004

Abrangncia

Verso 8.11

[WSDL no suportado. Existe mais de um servio declarado.]

Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. Por definio, um WSDL deve conter um e apenasum 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, oWSDL considerado invlido, e o fonte client no gerado.


69/140

WSCERR001 / No hSOAP:BINDINGS para a gerao ..

Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR001 / No h SOAP:BINDINGS para a gerao do Servio.

Durante a gerao do codigo-fonte para client Advpl, a partir de uma definio deservio (WSDL), uma vez identificado o servio, o gerador de cdigo procura adeclarao 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 estamensagem.


70/140

WSCERR003 / [XXX / YYY]Enumeration no suportado

Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR003 / [XXX / YYY] Enumeration no suportado

Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao,so analisados todos os

parmetros e estruturas utilizadas pelos mtodos do servio. Quando encontrada umaestruturabsica ( SimpleType), onde foi especificado um 'enumeration' ( lista deparametros vlidos pr-determinada ), so suportados os seguintestipos bsicos deparmetros, listados abaixo :

STRINGFLOATDOUBLEDECIMALINTINTEGERLONGUNSIGNEDINTUNSIGNEDLONG

Caso o WSDL contenha um 'enumeration', utilizando um tipo de dado diferente dosdeclarados acima, oprocesso de gerao de fonte abortado com aocorrncia de erroacima, onde o 'enumeration' no suportado identificado em e ,correspondendo o nome do parmetro e tipo utilziado, respectivamente.


71/140

WSCERR004 / NAO IMPLEMENTADO( 001 / / ...

Reviso: 22/04/2004

WSCERR004 / NAO IMPLEMENTADO ( 001 / / WSDLTYPE_NAME )

Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio,at que todas as estruturasutilizadas sejam processadas.

Quando deste processamento, uma estrutura contenha um determinado elemento, queaponte para uma outra estrutura, e esta no seja encontrada no WSDL ( ocorrncia

= A ), ou seja encontrada -porm registrada no como uma estrutura (complextype)- (ocorrncia = B ), o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a estrutura pendente em.


72/140

WSCERR006 / WSDL invlido ou nosuportado.

Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR006 / WSDL invlido ou no suportado.

Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio,at que todas as estruturas

utilizadas sejam processadas.

Quando deste processamento, um parmetro de primeiro nvel (message) do WSDL forespecificado sem nome, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima.


73/140

WSCERR007 / WSDL invlido ou nosuportado.

Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR007 / WSDL invlido ou no suportado.



Quando deste processamento, um parmetro de primeiro nvel (message) do WSDL forespecificado sem definio de tipo, o WSDL considerado invlido, e o processo degerao abortado com a mensagem acima.


74/140

WSCERR008 / Retorno NULLPARAMinvlido.

Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR008 / Retorno NULLPARAM invlido.



Quando deste processamento, um parmetrode retorno do WSDL seja identificadocomo 'retorno nulo', o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima.


75/140

WSCERR009 / INTERNAL ERROR (X)

Reviso: 29/04/2004

WSCERR009 /INTERNAL ERROR(X)

Esta uma ocorrncia de erro interna do 'engine' de gerao de cdigo-fonte Advpl, noreproduzida at o momento. Quando do processamento de um WSDL, os parmetros emensagens especificadas no WSDL so identificados internamente como parmetros deentrada , parmetro de sada , ou entrada e saida. Caso, aps a anlise inicial deparmetros, algum parmetro no seja enquadrado nestas definies, o processamentode gerao abortado com a ocorrncia acima.


76/140

WSCERR010 / [STRUCT_TYPE]Estrutura / Tipo inc ...

Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR010 / [STRUCT_TYPE] Estrutura / Tipo incompleto

Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas utilizadas pelos mtodos do servio, at que todas as estruturas


Quando deste processamento, caso uma estrutura complexa no contenha aespecificao de seus elementos internos ea mesma no contenha nenhuma refernciaao SCHEMA ou outra estrutura, o WSDL considerado invlido, e o processo degerao abortado com a mensagem acima, informando em [STRUCT_TYPE], o nomeda estrutura incompleta.


77/140

WSCERR011 / Retorno NULLPARAMinvlido.

Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR011 / Retorno NULLPARAM invlido.

Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices'Client', utilizando o Protheus IDE. No processo de gerao, so analisados todos osparmetros e estruturas uti

ADVPL - Web Services Com Protheus

Documents

Transcript of ADVPL - Web Services Com Protheus