microsiga advpl web services com protheus

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 LIB de 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 separados em Aplicaes Server e Aplicaes Cliente, respectivamente. Nos tpicos 'Comandos' e 'Funes', so abortadas respectivamente as diretivas e funes da Lib de Infra-estrutura do ERP disponibilizadas para o desenvolvimento de ambas as aplicaes, Cliente e Server. No tpico 'Exemplos Advpl', so demonstrados os exemplos 'atmicos' de uso das funes e comandos.

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 o statement WSCLIENT.

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.

COMANDOS - ENDWSSERVICE Reviso: 22/04/2004

Abrangncia


Sintaxe

ENDWSSERVICE [ self ]

Parmetros


Esta instruo no recebe nenhum parmetro.

Descrio

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

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


COMANDOS - ENDWSSTRUCT Reviso: 22/04/2004

Abrangncia


Sintaxe

ENDWSSTRUCT [ self ]

Parmetros


Esta instruo no recebe parmetros

Descrio

Atravs desta instruo, encerra-se a declarao de uma estrutura a ser utilizada em um Web Service, iniciada com o statement WSSTRUCT.

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


COMANDOS - WSCLIENT Reviso: 22/04/2004

Abrangncia


Sintaxe

WSCLIENT cClientName

Parmetros

Argumento Tipo Descrio

cClientName Caracter

cClientName corresponde 'a classe do Web Service a ser gerada.

Descrio

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

Para encerrar a declarao da classe, utilizada a instruo ENDWSCLIENT.


COMANDOS - WSDATA Reviso: 30/04/2004

Abrangncia


Sintaxe

WSDATA cVarNAme AS [ ARRAY OF ] cVarType [ OPTIONAL ]

Parmetros


cVarNAme Caracter

cVarName corresponde ao nome da propriedade a declarar.

AS Caracter

Separador para indicar o tipo da propriedade.

ARRAY OF Caracter

cVarType corresponde a um Tipo Soap / compatvel de varivel a ser utilizado no servio. Veja os tipos suportados abaixo na Tabela A - Tipos de Dados

cVarType Caracter

cVarType corresponde a um Tipo Soap / compatvel de varivel a ser utilizado no servio. Veja os tipos suportados 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 propriedade de uma classe para WebServices, 'Cliente' ou 'Server'.

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


COMANDOS - WSMETHOD Reviso: 22/04/2004

Abrangncia

Verso 7.10

Sintaxe

WSMETHOD cMethodName [ WSRECEIVE ] [ WSSEND ] [ WSSERVICE ]

Parmetros


cMethodName Caracter

cMethodName corresponde 'ao nome do mtodo do Web Service.

WSRECEIVE Caracter

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

WSSEND Caracter

Atravs desta instruo , declaramos um e apenas um parmetro de retorno de um Web Service .

WSSERVICE Caracter

cServiceName corresponde ao nome da classe do servio ao 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 no desenvilvimento :

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

Ao utilizarmos a instruo WSMETHOD dentro da declarao de uma classe WSSERVICE, informamos apenas o primeiro parmetro ( cMethodName ) . Porm, ao declarar o fonte propriamente dito do mtodo, todos os parmetros desta instruo so obrigatrios.


COMANDOS - WSSERVICE Reviso: 22/04/2004

Abrangncia


Sintaxe

WSSERVICE cServiceName [ DESCRIPTION ] [ NAMESPACE ]

Parmetros


cServiceName Caracter

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

DESCRIPTION Caracter

cDescr corresponde descrio do Servio, mostrada na tela de ndice de servios, e fornecida tambm jonto do WSDL gerado pelo servidor Protheus para o servio especificado.

NAMESPACE Caracter

cClsNS corresponde o NameSpace sob o qual este servio deve ser publicado.

Descrio

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

Dentro da estrutura de uma Classe 'Server' de Web Services, devemos declarar os mtodos disponibilizados da classe, e declaramos todas as propriedades , parmetros e retornos 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 estrutura bsica :

WSSERVICE DESCRIPTION NAMESPACE

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

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

ENDWSSSERVICE

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


COMANDOS - WSSTRUCT Reviso: 22/04/2004

Abrangncia


Sintaxe

WSSTRUCT cSructName

Parmetros


cSructName Caracter

cStructName corresponde ao nome da estrutura a ser criada. Obedee 'as regras de nomenclatura de funes Advpl.

Descrio

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


Exemplo de uso da funo GETWSCERROR Reviso: 22/04/2004

Abrangncia


No exemplo abaixo, ilustrado o tratamento de erro sugerido para uma chamada de um mtodo 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 a ocorrncia

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

Exemplo de uso da funo GETWSCVER Reviso: 22/04/2004

Abrangncia


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

User Function ShowVersions() Local cCliVers := GetWSCVer() MsgStop(cCliVers) Return

Exemplo de uso da funo GETWSSVER Reviso: 22/04/2004

Abrangncia


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

User Function ShowVersion() Local cSrvVers := GETWSSVER() MsgStop(cSrvVers) Return

Exemplo de uso da funo SETSOAPFAULT Reviso: 30/04/2004

Abrangncia


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

No exemplo 02, retornamos um Soap-Fault, indicando que no estava disponvel um recurso no servidor para o processamento requisitado. Neste, retornamos que o Fault Code 'SOAPFAULT_RECEIVER', pois o pacote no foi processado no por ter algum 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 indica que 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 (...)

Funes GETWSCERROR Reviso: 22/04/2004

Abrangncia

Verso 7.10

Sintaxe

GETWSCERROR ( [ nInfo ] ) --> xErrorInfo

Parmetros


nInfo Numrico

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

1 - Retorna uma String contendo o Resumo do Erro COMPLETO (DEFAULT) 2 = Retorna uma String contendo o soap:fault_code , caso disponvel . 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 o erro seja um soap_Fault.

Retorno

Tipo Descrio

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

Descrio

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

Caso a execuo de um mtodo 'Client' de Web Services retorne .F., deve ser utilizada a funo GetWSCError(), para identificar a origem da ocorrncia. Durante uma operao de execuo de um mtodo 'Client' de WebServices, so possveis ocorrncias de erro das seguintes naturezas, em momentos especficos :

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

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 foi alimentado. Se e somente se os parmetros informados sejam vlidos, o pacote SOAP montado 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 o mesmo no foi localizado ou 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 do Server. Aps a portagem, caso o pacote devolvido no esteja em conformidade com a declarao do servio, ou o servidor devolveu um html ao invs de um xml 'SOAP'.

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

Funes GETWSCVER Reviso: 22/04/2004

Abrangncia


Sintaxe

GETWSCVER ( ) --> cVersion

Retorno

Tipo Descrio

Caracter cVersion 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 , atravs desta funo possvel obter a string contendo a indentificao da verso de Build da LIB de Infra-Estrutura do Web Services 'Cliente'.

Funes GETWSSVER Reviso: 22/04/2004

Abrangncia


Sintaxe

GETWSSVER ( ) --> cVersion

Retorno

Tipo Descrio

Caracter cVersion 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 desta funo possvel obter a string contendo a indentificao da verso de Build da LIB de Infra-Estrutura do Web Services 'Server'.

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 descrio reduzida , referindo-se ao tipo do erro , por exemplo : Erro de argumento , Parametro Invalido , Falha de Arquivo ,...

cString Caracter

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

nFCode Numrico

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

cFactor Caracter

Atravs de CFActor , possvel especificar explicitamente qual node / atributo do XML / Soap que no foi processado e/ou ocasionou a falha . Deve ser utilizado o formato anyURI ( ref namespace http://www.w3.org/2001/XMLSchema ) para especifcar o node / atributo que ocasionou a falha.

cFDetail Caracter Atravs de cFDetail , possvel especificar para fins internos de processamento maiores detalhes sobre uma ocorrncia de erro, especificamente relacionada o processamento do corpo ("body") de um pacote SOAP.

Retorno

Tipo Descrio Lgico Esta funo sempre retorna .T. (true)

Descrio

Utilizada no desenvolvimento de uma aplicao 'Server' de WebServices, atravs desta funo 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 ocorrncias relacionadas a validade dos dados, recebidos no pacote de parametros enviados pelo 'Cliente', como parmetros invalidos ou fora da faixa de dados permitida pela rotina, ou ocorrncias relacionadas ao 'Server', como a falta de um determinado recurso no server para o processamento, como uma falha de acesso a base de dados, ou qualquer outra razo implementada no servio.

Tabela A - FAULT CODES

nFCode

Constante Descrio 1 SOAPFAULT_VERSIONMISMATCH NameSpace invlido

encontrado no processamento do Soap:Body

2 SOAPFAULT_MUSTUNDERSTAND Refere-se a falha de interpretao de um node / atributo contido no Soap:Header, especificado com o atributo mustUnderstand 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 do pacote SOAP est utilizando um encoding-type no suportado pelo server.

5 SOAPFAULT_SENDER Refere-se a uma ocorrncia de erro e/ou falha de processamento da aao, por algum tipo de inconsistncia relacionada a falta de um ou mais dados necessrios ao processamento. Indica uma ocorrncia que requer que o pacote SOAP seja remontado para que seja realizada uma nova tentativa de acesso.

6 SOAPFAULT_RECEIVER Refere-se a uma ocorrncia de erro e/ou falha de processamento por razes que no esto especificamente relacionadas ao conteudo do pacote SOAp e/ou parametros recebidos, porm relacionados 'a uma falha no Receptor do Servio, como por exemplo o servidor estar bloqueado para manuteno. Este tipo de ocorrncia no indica que existe falha no pacote enviado, mas cosuma-se utilizar para indicar uma ocorrncia relacionada naquele instante de tempo ; possivelmente estando disponvel posteriormente .

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

Funes SOAPDTGETD Reviso: 22/04/2004

Abrangncia

Verso 8.11

Sintaxe

SOAPDTGETD ( < cDateTime > ) --> dDate

Parmetros

Argumento Tipo Descrio 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.

Funes SOAPDTGETT Reviso: 22/04/2004

Abrangncia

Verso 8.11

Sintaxe

SOAPDTGETT ( < cDateTmie > ) --> cTime

Parmetros

Argumento Tipo Descrio 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

Funes SOAPDTMOUNT Reviso: 22/04/2004

Abrangncia

Verso 8.11

Sintaxe

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

Parmetros

Argumento Tipo Descrio dData Data Data a ser considerada para a montagem do 'DateTime'

cTmie Caracter

Horrio, no formato hh:mm:ss, a ser considerado, para a montagem do 'DateTime'

Retorno

Tipo Descrio

Caracter String 'SOAP', correspondendo Data e Horrios especificados, no formato DATETIME.

Descrio

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

Funes WSCLASSNEW Reviso: 27/04/2004

Abrangncia


Sintaxe

WSCLASSNEW ( < cSrvStruct > ) --> oNewStruct

Parmetros


cSrvStruct Caracter

Especifique o nome da estrutura "Server" de Webservices para a criao do Objeto.

Retorno

Tipo Descrio

Objeto A 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 utilizada como uma estrutura 'Server'. A utilizao 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 utilizar esta instruo para inicializar uma estrutura criada em um fonte 'Client' em Advpl; pois as estruturas client possuem as definies do mtodo NEW() de cada uma, com as devidas inicializaes de parmetros inetrentes ao servio.

Funes WSDLDBGLEVEL Reviso: 22/04/2004

Abrangncia


Sintaxe

WSDLDBGLEVEL ( < nLevel > ) --> NIL

Parmetros


nLevel Numrico

Atravs de nLevel , definimos qual o nvel de informaes a ser mostrado : 0 (default ) = sem informaes adicionais , 1 = Apenas pacote de retorno e 2 = Informaes e pacote de Envio e Retorno . Obs: Devemos chamar esta funao apos inicializado o Objeto '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' de informaes adicionais pertinentes execuo de um mtodo 'Client' de Web Services , a ser mostrado no console do servidor Protheus ( caso habilitado ) , permitindo ainda parametrizar um nvel de detalhamento das informaes a serem mostradas.

Observaes

O valor informado na chamada desta funo, ser mantido e considerado por todos os mtodos de servios 'Client' em Advpl, executados a partir de ento nesta Thread, at que a aplicao seja finalizada, ou esta funo seja chamada novamente. Esta funo deve ser utilizada nica e exclusivamente para fins de depurao, pois a mesma onera a performance da aplicao 'Client'.

Aplicaes 'Server' em Advpl Reviso: 22/04/2004

Abrangncia


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

A criao de um 'Server' de Web Services em Advpl consiste na montagem de uma classe Advpl especial, chamada WSSERVICE, onde cada mtodo da classe uma ao do 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-Estrutura do ERP a camada de troca de dados, recepo, pr-validao 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' solicitante do proessamento, alm de 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 de processamento.

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 'Server' utilizando-se do Protheus. Basta escrever uma classe que receba nenhum, um ou mais que um parmetro e devolva obrigatoriamente um retorno; configurar o Protheus Server para habilitar a interface HTTP e os Web Services, que a Lib faz todo o resto.

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 as solicitaes 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 configurao manual de um ambiente de Working Threads Extended ( WEBEX ), tambm no inicializador. A diferena entre ambas que a segunda opo permite especificar maiores detalhes do ambiente de execuo do servio, permite a configurao de servios e Web Sites simultaneamente, e tambm atendimento diferenciado de processamento para mais de um host e diretrios virtuais. Quando utilizamos o Protheus 8, devemos utilizar o novo assistente de configurao do servidor Protheus - MP8WIZARD, para instalar e configurar o mdulo de WebServices.

Segue abaixo um exemplo documentado de como configurar o servidor Protheus para WebServices, utilizando a chave [WEBSERVICES].

Observao : Esta configurao exige que a seo HTTP no esteja configurada no servidor Protheus. Esta configurao ir internamente habilitar o servio de HTTP e configurar 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 requisies Conout=0 ; ( Opcional ) Permite a exibio de informaes dos status internos do servio ( default = 0 : desabilitado ) . Utilizado APENAS para depurao, em casos especficos, pois prejudica significativamente a 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 do ERP sero utilizados para a montagem do ambiente de processamento das requisies. NameSpace = http://localhost ; ( Opcional ) Permite especificar o nome do namespace '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 atendimento s solicitaes de processamento do(s) servio(s) ( default = host atualmente utilizado )

Para configurar o WebService manualmente, deve ser inicialmente habilitado o servio de HTTP do servidor Protheus, configurar um processo WEBEX, apontando para funes internas de processamento dos Web Services, e configurar um host atravs do qual as requisioes processamento sero atendidas. Veja no exemplo abaixo :

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

[localhost] ;; A ttulo de exemplo, configuramos o host da estao local. Defaultpage=wsindex.apw ResponseJob=WSTESTE

[WSTESTE] ; Configuracao do job para atender os WebServices TYPE=WEBEX ;; ( Obrigatrio ) Tipo do Job para Web Services deve ser WEBEX

ONSTART=__WSSTART ;; ( Obrigatrio ) configurao fixa para Web Services ONCONNECT=__WSCONNECT ;; ( Obrigatrio ) configurao fixa para Web Services Environment=ENVTESTE ;; Especifique qual ambiente (environment)do servidor Protheus que ir atender os WebServices. INSTANCES=2,5 ;; ( Obrigatrio ) Indica qual a quantidade minima (default ) e mxima de processos ( Threads ) que sero colocados na memria para atender s solicitaes de processamento do(s) servio(s) publicado(s). Conout=0 ;; ( Opcional ) Permite a exibio de informaes dos status internos do servio ( default = 0 : desabilitado ) . Utilizado APENAS para depurao, em casos especficos, 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 do ERP sero utilizados para a montagem do ambiente de processamento das requisies. NameSpace = http://localhost/ ;; ( Opcional ) Permite especificar o nome do namespace '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 atendimento s 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 uma interface HTTP de consulta ao ndice de servios publicados. Para tal, basta re-iniciar o servidor Protheus aps a configurao ser realizada, abrir um Web Browser ( por exemplo, o Internet Explorer ), e acessar o link http:///wsindex.apw . No caso

do exemplo de configurao acima, basta digitarmos http://localhost/wsindex.apw , e nos 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 o link http://localhost/wsindex.apw . Utilizando o Protheus8, ser mostrada uma tela semelhante vista abaixo:

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

Cada servio ativo um link para uma pgina, onde so mostrados todos os mtodos do servio, e onde apresentado tambm um link atravs do qual o servidor Protheus fornecer a descrio do servio (WSDL). Logo abaixo mostrado o exemplo da tela de detalhes do servio CFGTABLE.

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 o documento WSDL deste servio.

Cada mtodo do servio disponibilizado tambm um link, para uma pgina onde so mostrados 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 repositrio atual, a inteface de consulta habilita a funcionalidade de teste do WebService, atravs da interface http, mostrando no final da tela o boto "testar". Ao clicar neste, montada uma tela em HTML para que os parmetros do servio sejam preenchidos. Aps os parmetros preenchidos e submetidos, o pacote de retorno do servio e seu respectivo status retornado no Browse.

02. Criando um WebService 'Server' com o Protheus Reviso: 23/04/2004

Abrangncia


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

Uma vez configurado e habilitado os WebServices no servidor Protheus, deve ser inicialmente determinados os mtodos aos quais o servio se destina; para ento determinar os parmetros e retorno de cada mtodo. Uma vez determinadas estas informaes, deve ser codificada uma classe especial em Advpl , chamada WSSERVICE, que constituir o servio propriamente dito.

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

03. Regras para codificao de um WebService Reviso: 30/04/2004

Abrangncia


Viso Geral

Para a codificao de um webservice, foram criadas em Advpl instrues especiais de declarao de classe, especficas para WebServices, que suportam nomes 'longos' no nome da classe, mtodos e propriedades. A utilizao destes comandos exige a declarao do #include 'apwebsrv.ch' no topo do cdigo-fonte; e exige tambm a ateno 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 s caracteristicas operacionais do ambiente de 'Working Threads' utilizado pelo Web Services. Ao executar um mtodo do WebServices, o ambiente ser mantido no ar, aguardando uma nova requisio de processamento, de qualquer servio ou mtodo, e de qualquer cliente. De modo que, ao desenvolver um servio, no devemos deixar abertos as "Querys" utilizadas no mtodo, filtros setados em tabelas principais, eu configuraes especficas no-padro do ambiente, realizadas para o processamento de um mtodo especfico; pois isto pode causar impacto no funcionamento de todos os WebServices 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 A e Z, os caracteres numricos compreendidos entre 0 e 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 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 mesmo nome no mesmo repositrio.

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 dados bsicos e/ou outras estruturas em um nivo tipo de informao, que ser utilizada como parmetro e/ou retorno em um ou mais mtodos do servio.

Nomenclatura das propriedades - parmetros e retorno

Cada parmetro e retorno de todos os mtodos de um servio devem ser declarados como uma propriedade da classe do Servio. Para dar nome a estes, so vlidas as mesmas regras de nomenclatura de Servios, no podendo haver um dado com o mesmo nome de um servio ou estrutura j declarados anteriormente.

04. Tipos Bsicos de Dados - 'Server' Reviso: 23/04/2004

Abrangncia


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

So considerados e suportados pelo Protheus, quando da declarao dos parmetros e retorno, 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 podemos especificar a palavra "String" em letras maisculas. A palavra STRING, escrita desta maneira, interpretada pelo pr-compilador do Protheus como sendo uma constante, ocasionando erro de sintaxe da compilao do WebService.

05. Estruturas - Tipos complexos Reviso: 23/04/2004

Abrangncia


Definio de Estrutura

Uma estrutura ( tambm conhecida por Complex Type ), constitui uma classe especial do Advpl, chamada WSSTRUCT, criada especificamente para WebServices. Devemos criar 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 informaes definido, por exemplo, os dados cadastrais de um cliente, devemos criar uma estrutura para agrupar estes dados. Vale ressaltar que a declarao de uma estrutura no amarra a mesma o servio em questo, de modo que a mesma estrutura pode ser utilizada para mais de um servio compilado no repositrio. Caso a estrutura criada seja especfica para o servio em questo, recomendado que seja dado um nome mesma que etnha a ver com o servio o qual ela pertena, pois no possvel compilar mais de uma estrutura de mesmo nome no repositrio.

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 do Servio, bem como seus parmetros e respectivo retorno.

Parmetros

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

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

Codificando o mtodo em Advpl

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

Quando escrevemos um mtodo de um WebService, e o mesmo recebe uma solicitao de processamento, as propriedades declaradas como parmetros do mtodo so alimentadas, e o mtodo executado. Por tratarem-se de propriedades, o cdigo fonte Advpl dever interagir com estas propriedades, prefixando-as com '::' dois pontos seguidos), ou 'self:' , sendo isto vlido tanto para os parmetros do mtodo, como para a propriedade 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 de WebService existem sempre dois retornos : A propriedade de retorno do mtodo, e o retorno efetivo do mtodo ao final do processamento.

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

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

Exemplo

WSMETHOD GetDate WSRECEIVE NULLPARAM WSSEND Horario WSSERVICE ServerTime

If dow(date())=1 // Seta um soap_fault, informando que este servio no disponvel aos domingos SetSoapFault('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 de retorno deve ser preenchida. Caso ela no seja preenchida, a LIB ir retornar o client solicitante um pacote de SOAP Fault, indicando que houve um erro no processamento do servio, e registrar um error.log na estao servidora. Ser gerado tambm uma ocorrncia de erro, caso o mtodo retorne .T., porm a funo SetSoapFault() tenha sido chamada durante a execuo do mtodo. A ocorrncia gerada : RETURN .T. WITH SOAP FAULT 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' solicitante do processamento um Soap:Fault , com a ocorrncia de erro : RETURN .F. WITH SOAP FAULT EXCEPTION EMPTY.

07. Tratamento de Erro dos WebServices Reviso: 27/04/2004

Abrangncia


Dada a infra-estrutura envolvida no processamento dos WebServices, a rotina de tratamento 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 ocorrncias de inconsistncias de parmetros de chamada do servio, inconsistncias de retorno, ocorrncias de erro fatal de processamento na aplicao, e ocorrncias de processamento 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 do ambiente 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 est descrita em "Utilizao do SOAP FAULT".

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 determinado processamento, deve ser retornado ao mesmo um pacote SOAP, que indica a causa da falha. Este pacote conhecido por 'SOAP FAULT'. A rotina de tratamento de erro fatal de execuio do WebService, quando da ocorrncia de tal, gera automaticamente um 'SOAP FAULT' com a descrio resumida da ocorrncia o client solicitante.

Dado que, a camada da lib, responsvel pela interpretao do pacote SOAP recebido pelo 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, e condizentes com o esperado; para ento realizar o processamento e retornar o client solicitante.

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 comunicao da infra-estruruta de WebServices, realiza automaticamente os tratamentos de protocolo, formato do pacote SOAP e parmetros obrigatrios. Caso exista alguma inconsistncia na chamada de um servio, que incorra em alguma destas excesses, o servio solicitado no chamado, e o servidor Protheus devolve automaticamente o client solicitante um Soap-Fault, indicando o que aconteceu.

Estas ocorrncias de Soap-Fault so mostradas no console do servidor Protheus, e so armazenadas tambm no arquivo error.log do ambiente utilizado.

Soap-Faults padro aps processamento do servio

A camada de comunicao da infra-estruruta de WebServices valida tambm a montagem do pacote de retorno. Caso exista alguma propriedade de retorno obrigatrio do servio que no esteja alimentada de forma correta, o servidor Protheus devolve automaticamente o client solicitante um Soap-Fault, indicando que ocorreu um erro interno no servidor de WebServices.

09. Servio de Exemplo : SERVERTIME Reviso: 27/04/2004

Abrangncia


Inicialmente, o exemplo proposto tm o objetivo de montar um WebService que retorne o horrio no servidor Protheus. Para tal, ser criado um servio, com apenas (inicialmente) um mtodo. A este servio, 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 parmetro para 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 no receber 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 de programa, e nele escrever o servio. A numerao disposta esquerda do cdigo-fonte meramente ilustrativa, no devendo ser digitada. Ela utilizada mais abaixo, onde este cdigo detalhado linha a linha.

1 #INCLUDE 'PROTHEUS.CH' 2 #INCLUDE 'APWEBSRV.CH' 3 4 WSSERVICE SERVERTIME 5 WSDATA Horario as String 6 WSMETHOD GetServerTime 7 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 definies dos comandos ADVPL e demais constantes

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

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

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

Linha 6 Dentro da estritura deste servio, informado que um dos mtodos do servio chama-se GetServerTime . Linha 7 Como no so necessrias mais propriedades ou metodos neste servio, a estrutura 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 ele receber o parametro NULLPARAM ), e informado que seu retorno ser o dado Horario ( declarado na classe do servio como uma propriedade, do tipo String ) .

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

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 o link atravs do qual o WSDL deste servio est sendo fornecido, e utilizarmos de uma ferramenta 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; porm existe 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, e compil-lo no mesmo repositrio do ambiente utilizado pelo WebServices 'Server', que a prpria interface de ndice de Servios ir permitir o teste do mesmo.

Falhas de Carga dos Servios Reviso: 06/05/2004

Abrangncia


Neste tpico so abordadas as mensagens de ocorrncias relacionadas carga dos servios.

Durante a inicializao do engine de Web Services, os servios compilados so validados, e um ambiente montado por thread para o atendimento de solicitaes de processamento. Neste processo, existem ocorrncias, relacionadas montagem do ambiente, que podem impossibilitar a operao dos WebServices como um todo; e ocorrncias que podem invalidar apenas um servio, em caso ed inconsistncia da declarao do mesmo.

Erro de Estrutura : ARRAY OF em parametro de en... Reviso: 27/04/2004

Abrangncia


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

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 de WebServices 'Server'.

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

Erro de Estrutura : Estrutura Indefinida. Reviso: 27/04/2004

Abrangncia


[XXX] : Erro de Estrutura : Estrutura Indefinida.

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

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

Erro de Estrutura : Nome de Estrutura Invlido ... Reviso: 27/04/2004

Abrangncia


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

Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando o nome de uma determinada estrutura [XXX] foi especificado com um nome igual a um tipo bsico de informao. Esta ocorrncia invalida apenas o servio que utiliza a determinada estrutura.

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

Erro de Mtodo : Estrutura de Entrada no 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 propriedade no fonte construtor do servio.

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

Erro de Mtodo : Estrutura de Retorno no encon... Reviso: 27/04/2004

Abrangncia


[XXX] : [YYY] : Erro de Mtodo : Estrutura de Retorno 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 propriedade da classe XXX

Erro de Mtodo : Estrutura de Retorno no pode ... Reviso: 27/04/2004

Abrangncia


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

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

Verifique e corrija o cdigo-fonte.

Erro de Mtodo : Mtodo [XXX] do Servio [YYY] ... Reviso: 27/04/2004

Abrangncia


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

Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando um determinado mtodo [XXX], referente o servio [YYY], foi codificado, porm no foi declarado no construtur do Web Service. Esta ocorrncia invalida apenas o servio que utiliza a determinada estrutura.

Verifique e corrija o cdigo-fonte e proceda com a declarao do mtodo no construtor do servio.

Erro de Mtodo : Nome de Mtodo Invlido - Tipo... Reviso: 27/04/2004

Abrangncia


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

Durante a etapa de validao dos servios, na carga dos WebServices, esta ocorrncia reproduzida quando o nome de uma determinada mtodo [XXX] foi especificado com um nome igual a um tipo bsico de informao. Esta ocorrncia invalida apenas o servio que utiliza o determinado mtodo.

Verifique e corrija o cdigo-fonte e a declarao do nome do mtodo.

Erro de Estrutura : Redundancia de Estruturas 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 e outras 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 ), quando algum erro fatal ocorra na carga dos WebServices. Os detalhes sobre a ocorrncia fatal so mostrados no console do servidor Protheus, e gravados no arquivo error.log do ambiente em uso.

Ocorrncias de Erro Fatal - AUTOMATIC URLLOCATION FAILED Reviso: 22/04/2004

Abrangncia


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

Quando no definimos esta URL, a lib de WebServices identifica automaticamente sob qual host o servio foi acessado. Esta operao no possvel quando o header HTTP do pacote informe uma operao diferente de "GET" ou "POST", ou o servidor Protheus est 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, o WebService no processado, e o processamento abortado com a ocorrncia de erro acima.

Ocorrncias de Erro Fatal - BUILD [XXX] USING WEBSERVICES HTTPS NOT SUPPORTED Reviso: 22/04/2004

Abrangncia


Quando da carga inicial dos WebServices 'Server', a configurao URLLOCATION criticada pela Lib. Caso seja especificado que o acesso ser realizado via 'HTTPS', e o build atual do servidor Protheus utilizado ainda no suporta a utilizao do WebService sob o protocolo HTTPS.

INVALID URLLOCATION [XXX] ON [YYY] Reviso: 22/04/2004

Abrangncia


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

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

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

Ocorrncias de Erro Fatal - REQUIRED Return 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 , a mesma deveria ser um 'Array' Advpl, contendo no mnimo um elemento; porm o array no continha nenhum elemento.

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

Ocorrncias de Erro Fatal - REQUIRED Return 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 , a mesma deveria ser 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 esteja alimentada com um contedo do tipo [Y], em conformidade com a declarao da propriedade no servio.

Ocorrncias de Erro Fatal - Return property [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 deveria ser um 'Array' Advpl, contendo elementos do typo [Y], porm, ao invs da propriedade ser 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 esteja alimentada com um array,

Ocorrncias de Erro Fatal - Return property [X] AS OBJECT Type [Y] Unexpect .. Reviso: 23/04/2004

Abrangncia


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


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

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

Ocorrncias de Erro Fatal - Return property [X] Type [Y] Unexpected Valtype .. 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 deveria ser 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 esteja alimentada com um contedo do tipo [Y], em conformidade com a declarao da propriedade no servio.

Ocorrncias de Erro Fatal - UNKNOW ERROR : 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 as consistncias internas realizadas tm uma mensagem de retorno. Quando do final da execuo do servio, independentemente de ocorrer um processamento com sucesso ou com falha ( SoapFault ), verificado se o tratamento efetuado gerou um pacote com a mensagem de retorno.

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

Ocorrncias de Erro Fatal - [SVC] : [METHOD] as [X] : Tipo Inesperado de Ret.. 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, o processamento 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 do mtodo seja sempre .T. ou .F.

Aplicaes Protheus 'Client' de WebServices 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 processamento do Servio, realizar a chamada, e tratar o pacote de retorno do servio e suas respectivas excesses.

Embora existam Web Services que podem ser acessados via Http direto, apenas passando parmetros via URL, o client de Web Services do Protheus tm seu foco e recursos direcionados apenas a servios que possuam interface de comunicao que realize POST de pacotes de dados XML em formato SOAP. O Protheus possui ferramentas 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 Protheus gere automaticamente, em Advpl, uma classe 'Client' para a comunicao e utilizao do mesmo.

Para tal, basta obtermos o endereo internet ( URL ) do WSDL desejado, criar um novo arquivo-fonte, e acessar o menu 'Ferramentas -> Gerar Cliente WebServices...'. Para cada servio que se tenha a necessidade de gerao de um fonte client, recomenda-se fortemente que cada fonte client seja gerado em um arquivo independente e exclusivo para 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 servidor Protheus que ir buscar o documento WSDL solicitado. De modo que, a estao servidora utilizada no ambiente deve ter acesso o endereo solicitado.

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 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 exemplo 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 ilustrativo, a definio do servio obtida diretamente via http, atravs do link http://localhost/SERVERTIME.apw?WSDL

Caso este link seja acessado atravs de um Web Browser ( Internet .Explorer., por exemplo ), ser exibido no browse um documento XML correspondendo a definio do servio.


Abrangncia


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

Ao ser gerado 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 deve ser inserida e/ou alterada 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, necessrio criar um novo arquivo .PRX no IDE, especificamente para conter as classes deste servio . Ento, deve ser acessado o menu Ferramentas, opo Gerar Ciente Webservices . 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 ser mostrado um texto semelhante ao abaixo :

Estabelecendo conexo com o server... Por favor aguarde. Obtendo descrio do WebService... Finalizando conexo com o server... 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

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

cSoap += '' cSoap += ''

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.

O cabealho do fonte contm informaes sobre a localizao do WSDL utilizado para a gerao do fonte, data e hora de gerao e verso do engine de Web Services utilizado . Logo abaixo, a declarao de uma classe client de Web Services ( 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.


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 para utilizar a classe de Web Services client para 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 Else 11 alert('Erro de Execuo : '+GetWSCError()) 12 Endif 13 14 Return

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

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

do Web Services client, obtida atravs da sintaxe ():New()

Linha 8 executado o 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 .

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 a ocorrncia de erro, deve ser utilizada a funo GetWSCerror(), que retorna uma string com o resumo da ocorrncia .

Linha 13 O programa de teste finalizado com um Return


Abrangncia


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 a mostrada abaixo:

No ambiente montado para teste, o Servidor de Web Services e o client esto no Protheus, compilados no mesmo Repositrio de Objetos . Para fins didticos, possvel simular uma ocorrncia de falha no client, ao 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 . Deve ser obtida uma tela semelhante a exemplificada abaixo :


Abrangncia


Passo 5 : Obtendo informaes de debug

Visto at o passo 4, um exemplo completo de um client funcionando perfeitamente . Agora, possvel imaginar 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 nvel de detalhamento de informaes adicionais relacionadas ao Web Service ; informaes estas que sero mostradas no Console do Server Protheus ( caso habilitado ) . a Funo para definir o nvel de detalhe chama-se WSDLDbgLevel(), 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 do servidor 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/SERVERTIME.apw / DOCUMENT NameSpace http://automan:8000/webservice/ SoapAction http://automan:8000/webservice/GETSERVERTIME Called from GETSERVERTIME ( 137) Called from U_TESTCLIENT ( 10) ---------------------------------- SOAPSEND -----------------------------------

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

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

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

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 dados listados abaixo. Para permitir a manipulao de cada tipo, utilizando variveis Advpl, so utilizados os tipos bsicos do Advpl para tratar 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

INT INTEGER BYTE FLOAT DOUBLE UNSIGNEDLONG UNSIGNEDINT DECIMAL 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

STRING DATETIME CHAR (**) BASE64BINARY

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

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

BOOLEAN

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 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, o WSDL considerado invlido, e o fonte client no gerado.

WSCERR001 / No h SOAP: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 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.

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 uma estrutura bsica ( SimpleType ), onde foi especificado um 'enumeration' ( lista de parametros vlidos pr-determinada ), so suportados os seguintes tipos bsicos de parmetros, listados abaixo :

STRING FLOAT DOUBLE DECIMAL INT INTEGER LONG UNSIGNEDINT UNSIGNEDLONG

Caso o WSDL contenha um 'enumeration', utilizando um tipo de dado diferente dos declarados acima, o processo de gerao de fonte abortado com a ocorrncia de erro acima, onde o 'enumeration' no suportado identificado em e , correspondendo o nome do parmetro e tipo utilziado, respectivamente.

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 os parmetros e estruturas utilizadas pelos mtodos do servio,at que todas as estruturas utilizadas sejam processadas.

Quando deste processamento, uma estrutura contenha um determinado elemento, que aponte 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 .

WSCERR006 / WSDL invlido ou no suportado. Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR006 / WSDL invlido ou no suportado.


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

WSCERR007 / WSDL invlido ou no suportado. 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 for especificado sem definio de tipo, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima.

WSCERR008 / Retorno NULLPARAM invlido. Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR008 / Retorno NULLPARAM invlido.


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

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, no reproduzida at o momento. Quando do processamento de um WSDL, os parmetros e mensagens especificadas no WSDL so identificados internamente como parmetros de entrada , parmetro de sada , ou entrada e saida. Caso, aps a anlise inicial de parmetros, algum parmetro no seja enquadrado nestas definies, o processamento de gerao abortado com a ocorrncia acima.

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 os parmetros e estruturas utilizadas pelos mtodos do servio, at que todas as estruturas utilizadas sejam processadas.

Quando deste processamento, caso uma estrutura complexa no contenha a especificao de seus elementos internos e a mesma no contenha nenhuma referncia ao SCHEMA ou outra estrutura, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, informando em [STRUCT_TYPE], o nome da estrutura incompleta.

WSCERR011 / Retorno NULLPARAM invlido. Reviso: 22/04/2004

Abrangncia

Verso 8.11

WSCERR011 / Retorno NULLPARAM invlido.


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

Observao : Esta ocorrncia semelhante ocorrncia WSCERR008, porm esta ocorrncia (011) refere-se uma sub-estrutura do servio , e a primeira (008) refere-se um parmetro / estrutura de primeiro nvel do servio.

WSCERR012 / INTERNAL ERROR (X) Reviso: 29/04/2004

Abrangncia


WSCERR012 / INTERNAL ERROR (X)

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

Observao : Esta ocorrncia semelhante WSCERR009, porem esta indica uma falha em outro ponto da rotina interna de anlise.

WSCERR013 / [SOAP_TYPE] UNEXPECTED TYPE. Reviso: 22/04/2004

WSCERR013 / [SOAP_TYPE] UNEXPECTED TYPE.


Quando deste processamento, um parmetro de tipo bsico no se encontre entre os tipos bsicos suportados pelo engine 'Client' de WebServices do Protheus, a gerao do fonte abortada com esta ocorrncia, indicando em SOAP_TYPE o tipo no suportado.

WSCERR014 / INVALID NULLPARAM INIT Reviso: 28/04/2004

Abrangncia


WSCERR014 / INVALID NULLPARAM INIT


Quando deste processamento, para cada propriedade da estrutura do servio so montadas as rotinas de inicializao de cada uma delas. Caso a rotina de gerao de fonte receba a instruo de inicializar a propriedade reservada 'NULLPARAM', o processamento abortado com esta ocorrncia.

Esta ocorrncia poderia ser causada por uma falha na validao inicial do WSDL, ou pela declarao de uma propriedade do tipo 'NULLPARAM'; e at o momento no foi reproduzida.

WSCERR015 / Node [XXX] as [YYY] on SOAP Resp ... Reviso: 28/04/2004

Abrangncia


WSCERR015 / Node [XXX] as [YYY] on SOAP Response not found.

Esta ocorrncia reproduzida, quando da utilizao de um fonte Client de WebServices, no momento que o client est desmontando o pacote SOAP retornado pelo servio.

Caso o servio utilize um soap-style RPC, e o node [XXX], correspondente ao retorno esperado do tipo [YYY] no for encontrado no pacote, o processamento do pacote de retorno abortado com esta ocorrncia.

Esta ocorrncia capturada pelo prprio fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravps da funo GetWSCError()

WSCERR016 / Requisio HTTPS no suportada ... Reviso: 28/04/2004

Abrangncia


WSCERR016 / Requisio HTTPS no suportada neste Build. [XXX]

Esta ocorrncia de erro reproduzida, quando da gerao de um fonte de WebServices 'Client', utilizando o Protheus IDE. Quando informada uma URL para buscar a definio do servio (WSDL), utilizando o protocolo HTTPS; porm o Build do Protheus atual no suporta o tratamento de webservices em HTTPS, a gerao do cdigo-fonte abortada com esta ocorrncia de erro.

Para gerar um fonte 'Client' de WebServices, que utilize o protocolo HTTPS, o Build do Protheus deve ser atualizado.

WSCERR017 / HTTP[S] Retuisio retornou [NIL] Reviso: 28/04/2004

Abrangncia


WSCERR017 / HTTP[S] Requisio retorn

microsiga advpl web services com protheus

Documents