Desenvolvendo Webservices para Protheus

WEBSERVICES
Terminologias / Glossrio
Reviso: 16/06/2005
Abrangncia Verso 7.10 Verso 8.11
WSDL : ( Web Services Description Language ) : Trata-se de um documento, em formato de acordo com as definies de Web Services, atravs do qual um provedor de um servio prov a discriminao detalhada das funcionalidades de um servio. Este documento em geral fornecido atravs de uma URL, apontando para o servidor que prov o servio. Utilizando este documento, o Protheus capaz de gerar automaticamente um 'Fonte Client' para estabelecer a conexo e utilizao do servio, atravs da gerao de uma classe 'Client' em Advpl. Web Service 'Client' : Aplicao desenvolvida partir de uma definio (WSDL) publicada e disponibilizada por uma aplicao 'Server'. A aplicao 'client' deve ser capaz de se comunicar com a aplicao Server, utilizando mensagens em XML/SOAP, segundo as regras fornecidas pelo Web Services Server atravs do WSDL. Web Service 'Server' : Aplicao desenvolvida para tornar disponvel um recurso, processamento ou informao, juntamente com sua definio (WSDL), para tornar possvel o desenvolvimento de uma aplicao 'Client' que ir solicitar a execuo da aplicao server e obter o retorno desta. 'Fonte Client' : Cdigo fonte Advpl, gerado pela ferramenta do IDE 'Gerar Cliente WebServices...', a partir de uma definio WSDL publicada em um servidor HTTP ou disponibilizada em um arquivo .WSDL. 'Tipo bsico' : So chamados de tipos bsicos, uma lista de tipos de informaes 'nativa' ,implementada na definio dos WebServices. 'Estrutura' : chamada de estrutura, uma classe intermediria de dados para Web Services, cuja funo definir uma informao, que consiste no agrupamento de outras informaes e/ou estruturas. 'SOAP' - Sigla de Simple Objetc Access Protocol, ou protocolo simples de acesso a objetos. O SOAP um padro aberto, baseado em XML, criado pela Microsoft, Ariba e IBM para padronizar a transferncia de dados entre aplicaes. Pode ser usado em combinao com vrios outros protocolos comuns da Internet, como HTTP e SMTP.
'XML' - Sigla de Extensible Markup Language, o XML uma linguagem baseada em tags semelhante ao HTML. Sua principal caracterstica a extensibilidade. Quem emite um documento XML pode criar tags personalizadas, que so definidas num documento anexo, que tem extenso XSD. 'XSD' - Sigla de XML Schema Definition. Arquivo associado a um documento XML que descreve e valida os dados no documento, permitindo a criao de tipos de dados personalizados e regras especficas para os mesmos. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services
Web Services com Protheus

Reviso: 27/04/2004
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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / 04. Tipos Bsicos de Dados - 'Server'
Topo da Pgina
COMANDOS
ENDWSCLIENT
Reviso: 22/04/2004
Sintaxe ENDWSCLIENT [ self ] Parmetros Argumento self Tipo (NULO) Descrio 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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / WSCLIENT
Topo da Pgina
ENDWSSERVICE
Reviso: 22/04/2004
Sintaxe ENDWSSERVICE [ self ] Parmetros Argumento self Tipo (NULO) Descrio 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. Observao : A utilizao deste comando exige a declarao do #include 'APWEBSRV.CH' no fonte Advpl. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / WSSERVICE
Topo da Pgina
ENDWSSTRUCT
Reviso: 22/04/2004
Sintaxe ENDWSSTRUCT [ self ] Parmetros Argumento self Tipo (NULO) Descrio 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. Observao : A utilizao deste comando exige a declarao do #include 'APWEBSRV.CH' no fonte Advpl. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / WSSTRUCT Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / 05. Estruturas - Tipos complexos
WSCLIENT
Reviso: 22/04/2004
Sintaxe WSCLIENT cClientName Parmetros Argumento cClientName Tipo Caracter Descrio 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. Observao : A utilizao deste comando exige a declarao do #include 'APWEBSRV.CH' no fonte Advpl. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / ENDWSCLIENT Principal / A Tecnologia Protheus / Web Services / Comandos / WSDATA Principal / A Tecnologia Protheus / Web Services / Comandos / WSSERVICE
WSDATA
Reviso: 30/04/2004
Sintaxe WSDATA cVarNAme AS [ ARRAY OF ] cVarType [ OPTIONAL ] Parmetros Argumento cVarNAme AS ARRAY OF Tipo Caracter Caracter Caracter Descrio cVarName corresponde ao nome da propriedade a declarar. Separador para indicar o tipo da propriedade. 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 corresponde a um Tipo Soap / compatvel de varivel a ser utilizado no servio. Veja os tipos suportados abaixo na Tabela A - Tipos de Dados Caso especificado , definimos que esta propriedade opcional no contexto do Web Service .
cVarType OPTIONAL
Caracter Caracter
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. Observao : A utilizao deste comando exige a declarao do #include 'APWEBSRV.CH' no fonte Advpl. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm
Principal / A Tecnologia Protheus / Web Services / Comandos / WSCLIENT Principal / A Tecnologia Protheus / Web Services / Comandos / WSSERVICE Principal / A Tecnologia Protheus / Web Services / Comandos / WSSTRUCT Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / 04. Tipos Bsicos de Dados - 'Server'
WSMETHOD
Reviso: 22/04/2004
Sintaxe WSMETHOD cMethodName [ WSRECEIVE <param_in,...> ] [ WSSEND <param_out> ] [ WSSERVICE <service_name> ] Parmetros Argumento cMethodName Tipo Caracter Descrio cMethodName corresponde 'ao nome do mtodo do Web Service. 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. Atravs desta instruo , declaramos um e apenas um parmetro de retorno de um Web Service . cServiceName corresponde ao nome da classe do servio ao qual o mtodo atual pertence.
WSRECEIVE <param_in,...> WSSEND <param_out> WSSERVICE <service_name>
Caracter
Caracter Caracter
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.
Observao : A utilizao deste comando exige a declarao do #include 'APWEBSRV.CH' no fonte Advpl. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / 06. Mtodos 'Server' em Advpl - Caractersticas
WSSERVICE
Reviso: 22/04/2004
Sintaxe WSSERVICE cServiceName [ DESCRIPTION <cDescr> ] [ NAMESPACE <cClsNS> ] Parmetros Argumento cServiceName Tipo Caracter Descrio 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 . 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. cClsNS corresponde o NameSpace sob o qual este servio deve ser publicado.
DESCRIPTION <cDescr> NAMESPACE <cClsNS>
Caracter
Caracter
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 <cSvcName> DESCRIPTION <cDescr> NAMESPACE <cClsNS>
WSDATA <xDataName> AS <xDataType> (... demais propriedades, parmetros e retornos ...) WSMETHOD <MethodName> (... demais mtodos da classe ...) ENDWSSSERVICE (... fonte(s) do(s) mtodo(s)s desta classe ...) Observao : A utilizao deste comando exige a declarao do #include 'APWEBSRV.CH' no fonte Advpl. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / ENDWSSERVICE Principal / A Tecnologia Protheus / Web Services / Comandos / WSCLIENT Principal / A Tecnologia Protheus / Web Services / Comandos / WSDATA
WSSTRUCT
Reviso: 22/04/2004
Sintaxe WSSTRUCT cSructName Parmetros Argumento cSructName Tipo Caracter Descrio 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. Observao : A utilizao deste comando exige a declarao do #include 'APWEBSRV.CH' no fonte Advpl.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Comandos Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / ENDWSSTRUCT Principal / A Tecnologia Protheus / Web Services / Comandos / WSDATA Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / 05. Estruturas - Tipos complexos
EXEMPLOS ADVPL
Web Services - Viso Geral

Reviso: 22/04/2004
Introduo
Visto de forma simples, um Web Service uma classe publicada em um servidor de aplicao, para acesso externo. De modo que, um programa de software client ir solicitar ao server um processamento de uma ao / mtodo do servio, enviando o(s) parmetro(s) ao mesmo atravs de uma string XML, formatada no padro SOAP (Simple Object Access Protocol), e o servio retornar ao client uma string XML de resposta, tambm formatada no padro SOAP. Diferentemente dos Web Sites, que so apresentaes de dados feitas para serem vistas em um browser por um internauta, um Web Service construdo para ser acessado diretamente por outro servio ou programa de software. Os servios podem ser combinados entre si e com outras aplicaes para construir servios interativos e inteligentes. A universalidade de um Web Service, entre outros fatores, reside justamente na maneira de disponibilizar uma espcie de manual do servio, chamado de WSDL ( Web Services Description Language ), que nada mais do que uma descrio detalhada do servio, que capaz de resumir em um nico documento os mtodos de um servio, os parmetros, retornos e detalhes do mesmo. Um documento WSDL de tal forma completo que praticamente elimina a necessidade de qualquer tipo de contato direto entre o desenvolvedor de um Servio (server) e o analista que ir montar um client para interagir com ele. Tambm foi idealizado o uso do protocolo HTTP originalmente para a troca de pacotes de requisio e retorno de processamento, pois a maioria dos sistemas operacionais tm recursos para suport-lo ; e foi escolhido o formato SOAP por ser um padro aberto, criado pela Microsoft, Ariba e IBM para padronizar a transferncia de dados em diversas aplicaes, que utiliza como veculo o universalmente conhecido XML ( Extended MarkUp Language ) .
Principais usos
As aplicaes utilizando Web Services tm um leque de possibilidades de uso muito grande. Atualmente utiliza-se Web Services para a troca de dados / integrao entre sistemas multi-plataforma ou no, disponibilizao de ferramentas e dados para consulta remota, integraes B2B e B2C, enfim : Todo e qualquer processamento que seja interessante disponibilizar de uma forma mais abrangente.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services
Exemplo de uso da funo GETWSCVER

Reviso: 22/04/2004
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
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Exemplos Advpl Veja tambm Principal / A Tecnologia Protheus / Web Services / Funes / GETWSCVER
Topo da Pgina
Exemplo de uso da funo GETWSSVER

Reviso: 22/04/2004
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
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Exemplos Advpl
Topo da Pgina
Exemplo de uso da funo SETSOAPFAULT

Reviso: 30/04/2004
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 (...)
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Exemplos Advpl Veja tambm
Principal / A Tecnologia Protheus / Web Services / Funes / SETSOAPFAULT FUNES
GETWSCERROR
Reviso: 22/04/2004
Sintaxe GETWSCERROR ( [ nInfo ] ) --> xErrorInfo Parmetros Argumento Tipo Descrio 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.
nInfo
Numrico
Retorno Tipo (Qualquer) Descrio 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 .
Exemplos Exemplo de uso da funo GETWSCERROR Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente / Ocorrncias de Erro / WSCERR048 / SOAP FAULT [FAULT_CODE] ( POST em ...
GETWSCVER
Reviso: 22/04/2004
Sintaxe GETWSCVER ( ) --> cVersion Retorno Tipo Caracter Descrio 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'. Exemplos Exemplo de uso da funo GETWSCVER Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes
GETWSSVER
Reviso: 22/04/2004
Sintaxe GETWSSVER ( ) --> cVersion Retorno Tipo Caracter Descrio 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'. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes
SETSOAPFAULT
Reviso: 30/04/2004
Sintaxe SETSOAPFAULT ( < cError > , < cString > , [ nFCode ] , [ cFactor ] , [ cFDetail ] ) --> .T. Parmetros Argumento cError Tipo Caracter Descrio 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 ,... 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 , ... 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 ) 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. 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.
cString
Caracter
nFCode
Numrico
cFactor
Caracter
cFDetail
Caracter
Retorno Tipo Lgico Descrio 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 1 SOAPFAULT_VERSIONMISMATCH

2
SOAPFAULT_MUSTUNDERSTAND
SOAPFAULT_DTDNOTSUPPORTED
Descrio NameSpace invlido encontrado no processamento do Soap:Body Refere-se a falha de interpretao de um node / atributo contido no Soap:Header, especificado com o atributo mustUnderstand setado para 'true' A String Soap enviada como parmetro continha um DTD (Document Type Definition).
SOAP est utilizando um encoding-type no suportado pelo server.
SOAPFAULT_DATAENCODINGUNKNOWN O HEader ou o Body do pacote
SOAPFAULT_SENDER
SOAPFAULT_RECEIVER
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. 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' Exemplos Exemplo de uso da funo SETSOAPFAULT Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente / Ocorrncias de Erro / WSCERR048 / SOAP FAULT [FAULT_CODE] ( POST em ...
Topo da Pgina
SOAPDTGETD
Reviso: 22/04/2004
Abrangncia Verso 8.11
Sintaxe SOAPDTGETD ( < cDateTime > ) --> dDate Parmetros Argumento cDateTime Tipo Caracter Descrio String, no formato "Soap" DateTime, a ser considerada.
Retorno Tipo Data Descrio 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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes
SOAPDTGETT
Reviso: 22/04/2004
Sintaxe SOAPDTGETT ( < cDateTmie > ) --> cTime Parmetros Argumento cDateTmie Tipo Caracter Descrio String, no formato "Soap" DateTime, a ser considerada.
Retorno Tipo Caracter Descrio 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
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes
SOAPDTMOUNT
Reviso: 22/04/2004
Sintaxe SOAPDTMOUNT ( < dData > , < cTmie > ) --> cDateTmie Parmetros Argumento dData cTmie Tipo Data Caracter Descrio Data a ser considerada para a montagem do 'DateTime' Horrio, no formato hh:mm:ss, a ser considerado, para a montagem do 'DateTime'
Retorno Tipo Caracter Descrio 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.
Topo da Pgina
WSCLASSNEW
Reviso: 27/04/2004
Sintaxe WSCLASSNEW ( < cSrvStruct > ) --> oNewStruct Parmetros Argumento cSrvStruct Tipo Caracter Descrio Especifique o nome da estrutura "Server" de Webservices para a criao do Objeto.
Retorno Tipo Objeto Descrio 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.
Grupos Relacionados
Principal / A Tecnologia Protheus / Web Services / Funes
Topo da Pgina
WSDLDBGLEVEL
Reviso: 22/04/2004
Sintaxe WSDLDBGLEVEL ( < nLevel > ) --> NIL Parmetros Argumento Tipo Descrio 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.
nLevel
Numrico
Retorno Tipo (NULO) Descrio 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
Aplicaes 'Server' em Advpl

Reviso: 22/04/2004
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 InfraEstrutura 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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server
02. Criando um WebService 'Server' com o Protheus

Reviso: 23/04/2004
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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server
Topo da Pgina
03. Regras para codificao de um WebService

Reviso: 30/04/2004
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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server
04. Tipos Bsicos de Dados - 'Server'

Reviso: 23/04/2004
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 Date Integer Float
Dado Advpl do tipo String. Dado Advpl do tipo Data. Dado Advpl do Tipo numrico (apenas numeros inteiros.) Dado Advpl do Tipo numrico (pode conter numeros inteiros e no-inteiros.) Boolean Dado Advpl do Tipo Booleano ( lgico ) . Base64Binary Dado Advpl do Tipo String Binria , aceitando todos os Caracteres da Tabela ASCII , de CHR(0) a CHR(255)
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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / WSDATA
Principal / A Tecnologia Protheus / Web Services / Web Services com Protheus
Topo da Pgina
05. Estruturas - Tipos complexos

Reviso: 23/04/2004
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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / ENDWSSTRUCT Principal / A Tecnologia Protheus / Web Services / Comandos / WSSTRUCT
06. Mtodos 'Server' em Advpl - Caractersticas

Reviso: 26/04/2004
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 <SERVICO> : <METODO> 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 <SERVICO> : <METODO> RETURN .F. WITH SOAP FAULT EXCEPTION EMPTY.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server
Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / WSMETHOD
07. Tratamento de Erro dos WebServices

Reviso: 27/04/2004
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". Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server
08. Utilizao do SOAP FAULT

Reviso: 30/04/2004
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. Grupos Relacionados
Principal / A Tecnologia Protheus / Web Services / Aplicaes Server Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente / Ocorrncias de Erro / WSCERR048 / SOAP FAULT [FAULT_CODE] ( POST em ...
09. Servio de Exemplo : SERVERTIME

Reviso: 16/05/2008
Abrangncia Verso 10.1 Verso 7.10 Verso 8.11
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 cdigofonte 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 SERVERTIME 10 ::Horario := TIME() 11 Return .T. Linha 1 especificada a utilizao do Include Protheus.ch, contendo as definies dos comandos ADVPL e demais constantes
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.
Linha 2
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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente / Aplicaes Protheus 'Client' de WebServices
FALHAS DE CARGA DO SERVIO
Falhas de Carga dos Servios

Reviso: 06/05/2004
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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Erro de Estrutura : ARRAY OF em parametro de en...

Reviso: 27/04/2004
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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Topo da Pgina
Erro de Estrutura : Estrutura Indefinida.

Reviso: 27/04/2004
[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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Topo da Pgina
Erro de Estrutura : Nome de Estrutura Invlido ...

Reviso: 27/04/2004
[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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Topo da Pgina
Erro de Mtodo : Estrutura de Entrada no encon...

Reviso: 27/04/2004
[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
Grupos Relacionados
Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Topo da Pgina
Erro de Mtodo : Estrutura de Retorno no encon...

Reviso: 27/04/2004
[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
[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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Topo da Pgina
Erro de Mtodo : Mtodo [XXX] do Servio [YYY] ...

Reviso: 27/04/2004
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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Erro de Mtodo : Nome de Mtodo Invlido - Tipo...

Reviso: 27/04/2004
[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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
Redundancia de Estruturas
Reviso: 27/04/2004
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 <A>, que tem dentro dela uma outra propriedade que do tipo <A>, ou a estrutura <A> tm uma propriedade de tipo <B>, e <B> por sua vez tem uma propriedade do Tipo <A>. Verifique e corrija o cdigo-fonte e corrija a declarao das estruturas envolvidas. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Falhas de Carga dos Servios
WSDL Server ONLOAD ERROR - Falha Interna na ...

Reviso: 27/04/2004
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.
Topo da Pgina
OCORRNCIAS DE ERRO FATAL
Ocorrncias de erro fatal e tratamento de erro

Reviso: 26/04/2004
As ocorrncias de erro fatal relacionadas nesta seo referem-se falhas de carga do engine de WebServices como um todo e ocorrncias de falha de processamento quando da chamada para execuo dos servios. Em cada documento, discriminado um resumo da ocorrncia, sua possvel causa e possveis solues.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Ocorrncias de Erro Fatal
Topo da Pgina
AUTOMATIC URLLOCATION FAILED

Reviso: 22/04/2004
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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Ocorrncias de Erro Fatal
Topo da Pgina
BUILD [XXX] USING WEBSERVICES HTTPS NOT SUPPORTED

Reviso: 22/04/2004
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.
Topo da Pgina
INVALID URLLOCATION [XXX] ON [YYY]

Reviso: 22/04/2004
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'
Topo da Pgina
REQUIRED Return property [X] AS ARRAY OF [Y] IS ..

Reviso: 23/04/2004
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.
REQUIRED Return property [X] Type [Y] Unexpect ...

Reviso: 23/04/2004
REQUIRED Return property [X] Type [Y] Unexpected Valtype [Z] 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 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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Ocorrncias de Erro Fatal
Topo da Pgina
Return property [X] AS ARRAY Type [Y] Unexpected..

Reviso: 23/04/2004
Return property [X] AS ARRAY Type [Y] Unexpected Valtype [Z]
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 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, Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Ocorrncias de Erro Fatal
Return property [X] AS OBJECT Type [Y] Unexpect ..

Reviso: 23/04/2004
Return property [X] AS OBJECT Type [Y] Unexpected Valtype [Z] 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 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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Ocorrncias de Erro Fatal
Topo da Pgina
Return property [X] Type [Y] Unexpected Valtype ..

Reviso: 23/04/2004
Return property [X] Type [Y] Unexpected Valtype [Z] 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 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.
Topo da Pgina
UNKNOW ERROR : EMPTY HTTP RETURN

Reviso: 29/04/2004
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.
[SVC] : [METHOD] as [X] : Tipo Inesperado de Ret..

Reviso: 06/05/2004
[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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / Ocorrncias de Erro Fatal
APLICAES CLIENTE
Aplicaes Protheus 'Client' de WebServices

Reviso: 30/04/2004
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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente Veja tambm Principal / A Tecnologia Protheus / Web Services / Aplicaes Server / 09. Servio de Exemplo : SERVERTIME
Gerao de Client em Advpl - Passo 01

Reviso: 30/04/2004
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. Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente

Reviso: 30/04/2004
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 += '<GETSERVERTIME xmlns='http://localhost/'>' cSoap += '</GETSERVERTIME>' oXmlRet := SvcSoapCall( Self,cSoap,; 'http://localhost/GETSERVERTIME',; 'DOCUMENT','http://localhost/',) ::cGETSERVERTIMERESULT := xGetInfo( oXmlRet, '_GETSERVERTIMERESPONSE:_GETSERVERTIMERESULT:TEXT', '' )
END WSMETHOD oXmlRet := NIL Return .T.
O fonte acima constitui uma Classe em Advpl, gerada para realizar a interface com a classe original publicada no Server, j realizando os tratamentos adequados para realizar a comunicao via http com o servidor onde o servio est publicado. Vale obvervar que, as linhas em negrito no fonte acima no foram inseridas pelo assistente do IDE, mas acrescentadas a este documento para fins didticos. 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.
Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Cliente
Topo da Pgina

Reviso: 22/04/2004
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 2 3 4 5 6 7 8 9 #INCLUDE 'PROTHEUS.CH' User Function TestClient() Local oSvc := NIL oSvc := WSSERVERTIME():New() If oSvc:GETSERVERTIME() alert('Horrio no Servidor : '+ oSvc:cGETSERVERTIMERESULT)
10 11 12 13 14 Linha 1 Linha 3 Linha 4 Linha 6 Linha 8 Linha 9
Else alert('Erro de Execuo : '+GetWSCError()) Endif Return declarada a utilizao do Include Protheus.ch, contendo as definies dos comandos ADVPL e demais constantes Inicia-se a definio da User Function para utilizar o Web Service Uma varivel local declarada para conter o Objeto do Web Service client Utilizando-se do servio, a varivel oSvc alimentada com uma onva instncia do Web Services client, obtida atravs da sintaxe <NOME_DO_SERVICO>():New() 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 . Caso o servio tenha sido executado com sucesso, o retorno esperado alimenrado na propriedade cGetServerTimeResult do objeto do servio. Caso contrrio ( retorno .F. ), ocorreu alguma falha na chamada do servio, como por exemplo o servidor no estava no ar, demorou muito pra responder ( time-out ), entre outras. Para 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 . O programa de teste finalizado com um Return
Linha 11
Linha 13
Topo da Pgina

Reviso: 22/04/2004
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 :

Reviso: 22/04/2004
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 ) 1 2 Sem informaes adicionais. Apenas String SOAP de retorno do Server. 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 ----------------------------------<?xml version='1.0' encoding='utf-8'?> <soap:Envelope xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd=' http://www.w3.org/2001/XMLSchema' xmlns:soap='http://schemas.xmlsoap.org/soap/en velope/'> <soap:Body> <GETSERVERTIME xmlns='http://automan:8000/webservice/'> </GETSERVERTIME> </soap:Body> </soap:Envelope> --------------------------------------------------------------------------------------------------------------- POST RETURN --------------------------------<?xml version='1.0' encoding='utf-8'?><soap:Envelope xmlns:xsi='http://www.w3.or g/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:so ap='http://schemas.xmlsoap.org/soap/envelope/'><soap:Body><GETSERVERTIM ERESPONSE xmlns='http://automan:8000/webservice/'><GETSERVERTIMERESULT>10:37:10< /GETSERVE RTIMERESULT></GETSERVERTIMERESPONSE></soap:Body></soap:Envelope> ------------------------------------------------------------------------------Fim Thread (siga0984, AUTOMAN) BytesIn 73 BytesOut 75
O texto marcado em azul claro so as mensagens informativas a respeito da chamada do WebService, informando a URL chamada, o estilo soap de troca de dados ( document ), o NameSpace e o SoapAction utilizados. O Texto marcado em verde (SOAPSEND) informa o conteudo do pacote Soap que foi enviado ( postado ) ao Servidor, e o conteudo em amarelo ( POST RETURN ) informa o contedo do pacote Soap devolvido pelo Server referente 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 .
Tipos de dados suportados - 'Client'

Reviso: 22/04/2004
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

Desenvolvendo Webservices para Protheus

Diunggah oleh

Informasi Dokumen

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Desenvolvendo Webservices para Protheus

Diunggah oleh

Hak Cipta:

Format Tersedia

WEBSERVICES

Abrangncia Verso 7.10 Verso 8.11

Web Services com Protheus

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

WSRECEIVE <param_in,...> WSSEND <param_out> WSSERVICE <service_name>

Abrangncia Verso 7.10 Verso 8.11

DESCRIPTION <cDescr> NAMESPACE <cClsNS>

Abrangncia Verso 7.10 Verso 8.11

Web Services - Viso Geral

Abrangncia Verso 7.10 Verso 8.11

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services

Exemplo de uso da funo GETWSCVER

Abrangncia Verso 7.10 Verso 8.11

Exemplo de uso da funo GETWSSVER

Abrangncia Verso 7.10 Verso 8.11

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Exemplos Advpl

Exemplo de uso da funo SETSOAPFAULT

Abrangncia Verso 7.10 Verso 8.11

Principal / A Tecnologia Protheus / Web Services / Funes / SETSOAPFAULT FUNES

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

Abrangncia Verso 7.10 Verso 8.11

nFCode Constante 1 SOAPFAULT_VERSIONMISMATCH

SOAPFAULT_DATAENCODINGUNKNOWN O HEader ou o Body do pacote

Abrangncia Verso 8.11

Retorno Tipo Data Descrio Retorna a data identificada na String cDateTime

Abrangncia Verso 8.11

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

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes

Abrangncia Verso 8.11

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes

Abrangncia Verso 7.10 Verso 8.11

Principal / A Tecnologia Protheus / Web Services / Funes

Abrangncia Verso 7.10 Verso 8.11

Retorno Tipo (NULO) Descrio Esta funo sempre retorna NIL

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Funes

Aplicaes 'Server' em Advpl

Abrangncia Verso 7.10 Verso 8.11

02. Criando um WebService 'Server' com o Protheus

Abrangncia Verso 7.10 Verso 8.11

03. Regras para codificao de um WebService

Abrangncia Verso 7.10 Verso 8.11

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server

04. Tipos Bsicos de Dados - 'Server'

Abrangncia Verso 7.10 Verso 8.11

String Date Integer Float

Principal / A Tecnologia Protheus / Web Services / Web Services com Protheus

05. Estruturas - Tipos complexos

Abrangncia Verso 7.10 Verso 8.11

06. Mtodos 'Server' em Advpl - Caractersticas

Abrangncia Verso 7.10 Verso 8.11

Grupos Relacionados Principal / A Tecnologia Protheus / Web Services / Aplicaes Server

Veja tambm Principal / A Tecnologia Protheus / Web Services / Comandos / WSMETHOD

07. Tratamento de Erro dos WebServices

Abrangncia Verso 7.10 Verso 8.11

08. Utilizao do SOAP FAULT