Web Services com o ERP Microsiga Protheus

Contedo da TOTVS Developer Network revisado em 21/05/2012 que abrange as verses 10 e 11 Organizado por Armando Lima.

O ERP Microsiga Protheus, a partir da verso AP7, possui ferramentas nativas e integradas com a LIB de infraestrutura 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 Client, respectivamente. Nos tpicos Guia de referncia dos comandos AdvPL, da linguagem AdvPL, e Funes de WebServices, do Framework Microsiga Protheus, so abordadas respectivamente as diretivas e funes da LIB de infraestrutura do ERP disponibilizadas para o desenvolvimento de ambas as aplicaes Cliente e Server. No tpico Exemplos AdvPL, so apresentados os exemplos de uso das funes e comandos.

Web Services 'Server' 01. Web Services 'Server' - Configurao

Um Web Services em AdvPL utiliza-se de working threads para atender as solicitaes de processamento atravs do protocolo HTTP. Para isso, existem duas maneiras de habilitar um Web Services: Atravs da criao da seo [WebServices], no arquivo de configurao (appserver.ini), do TOTVS | Application Server. Configurao manual de um ambiente working threads extended (WEBEX), no arquivo de configurao (appserver.ini), do TOTVS | Application Server. A diferena entre ambas que a segunda opo permite especificar mais detalhes do ambiente de execuo do servio, configurar os servios de Web Sites simultaneamente e o atendimento diferenciado do processamento para mais de um host e diretrios virtuais. Importante: Se estiver utilizando o produto Microsiga Protheus 8.11, deve-se utilizar o assistente de configurao do servidor Microsiga Protheus - MP8WIZARD, para instalar e configurar o ambiente de Web Services. A seguir, observe um exemplo de como configurar o servidor TOTVS | Application Server para Web Services, utilizando a seo [WebServices].

Observao: Esta configurao exige que a seo [HTTP] no esteja configurada no TOTVS | Application Server. Pois, essa configurao ir internamente habilitar o servio de HTTP e configurar o processo de resposta para o Web Services. Exemplo (Configuraes do arquivo appserver.ini) [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 (padro=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 (padro=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 'padro', utilizado pelo(s) servio(s) compilado(s) sem a definio de 'NameSpace'. (Padro=host atualmente utilizado). URLLocation=http://localhost (Opcional) - Permite especificar a URL responsvel pelo atendimento s solicitaes de processamento do(s) servio(s) (padro=host atualmente utilizado). No entanto, possvel configurar o Web Service manualmente. Para isso, deve-se inicialmente habilitar o servio de HTTP, do servidor Microsiga Protheus, configurar um processo WEBEX apontando para funes internas de processamento dos Web Services e configurar um host atravs do qual as requisies de processamento sero atendidas.

Exemplo (Configurao do protocolo) [HTTP] Enable=1 (Obrigatrio) - Indica se o service est habilitado (1) ou no (0). Port=80 (Obrigatrio) - Indica qual a porta que ser utilizada pelo service. Path=c:\P10\Http Configurao do host da estao localDefaultpage=wsindex.apw (Obrigatrio) - Indica a pgina inicial que ser exibida aps a configurao do service. Essa pgina apresenta todos os WebServices habilitados e no habilitados.Ela s exibida se todas as configuraes foram efetuadas com sucesso. ResponseJob=WSTeste Configurao do job para atender aos Web Services. 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 Microsiga Protheus que ir atender aos Web Services. Instances=2.5 (Obrigatrio) - Indica qual a quantidade mnima (padro) 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 (padro=0:desabilitado). Utilizado APENAS para depurao, em casos especficos, pois prejudica significativamente a performance do(s) servio(s). Trace=1 (Opcional) - Habilita a gravao de um arquivo de log (wsstrace.log), contendo as informaes sobre todas as chamadas e status do Web Services (padro=0). PrepareIn=01,01 (Obrigatrio) - Permite especificar qual 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 'padro', utilizado pelo(s) servio(s) compilado(s) sem a definio de 'NameSpace'. (padro=host atualmente utilizado). URLLocation=http://localhost/ (Opcional) - Permite especificar a URL responsvel pelo atendimento s solicitaes de processamento do(s) servio(s) (padro=host atualmente utilizado).

Observao: Note que a porta utilizada no exemplo acima foi a 80, a porta mais genrica de todas. Por isso no foi necessrio inclu-la nos URLs de localhost. Se fosse utilizada a porta 81, ento a URL seria localhost:81.

Release 12/08/2010 Foram criados mais dois parmetros de registro de log de profiler de execuo de processos, para auxiliar na identificao de ocorrncias de performance no processamento de requisies, parmetro PROFILE (padro=0) e PROFILETIMER (padro=2). Tais parmetros so considerados a partir da atualizao da LIB/Framework AdvPL, AdvPL WSDL Server 1.100812, e da atualizao do TOTVS | Application Server com build igual ou superior a 7.00.090818P. Para registro detalhado das chamadas de funo por requisio, deve-se atualizar o TOTVS | Application Server para a build igual ou superior a 7.00.100812P. Ao habilitar o parmetro PROFILE=1, na configurao do job de Web Services, a partir da prxima requisio recebida para processamento por qualquer working thread deste job, caso a mesma permanea em processamento mais tempo em segundos do que o configurado no parmetro PROFILETIMER (padro=2), ser criada uma pasta chamada WSPROFILER, a partir do RootPath do ambiente em execuo, e dentro dela ser criado um arquivo dinamicamente, contendo todos os detalhes de processo chamado e registro de resumo de chamada de funes executadas por este processo. WSINDEX - ndice de Servios Uma vez habilitada a configurao para Web Services, obtemos acesso a uma interface HTTP de consulta ao ndice de servios publicados. Para tal, basta reiniciar o servidor TOTVS | Application Server aps a configurao ser realizada, abrir um Web Browser (por exemplo, Internet Explorer), e acessar o link http://<servidor>/wsindex.apw. No caso do exemplo de configurao acima, informe o endereo http://localhost/wsindex.apw e observe a interface de consulta ao ndice dos servios. Se estiver utilizando o sistema Microsiga Protheus 10, a tela apresentada ser semelhante ao exemplo abaixo:

Observe que, na janela acima, so apresentados todos os servios compilados e disponibilizados no repositrio de objetos em uso no ambiente configurado. Atravs dessa janela, possvel obter mais detalhes de cada um dos servios compilados. Pois, cada servio ativo um link para uma pgina que apresentar todos os mtodos do servio com um link do servidor TOTVS | Application Server que fornecer a descrio do servio (WSDL). Observe, a seguir, um exemplo com os detalhes do servio CFGTABLE.

Atravs desta janela, possvel obter a descrio do servio WSDL ao clicar no link disponvel em "Descrio do Servio (WSDL)". Ao clicar neste link,uma nova janela ser apresentada exibindo o documento WSDL do servio. Alm disso, cada mtodo do servio disponibilizado tambm um link para uma pgina onde so apresentados os exemplos de pacotes SOAP que esse mtodo especificamente espera para recepo de parmetros e o modelo de retorno do servio.

Caso, o fonte-client AdvPL do servio, seja gerado e esteja compilado no repositrio atual, a interface de consulta habilita a funcionalidade de teste do Web Services, atravs da interface HTTP, apresentado no final da tela o boto testar. Ao clicar nesse boto, ser montada uma tela HTML para que os parmetros do servio sejam preenchidos. Aps o preencher os parmetros solicitados e submet-los, o pacote de retorno do servio e seu respectivo status so retornados no browse.

02. Criando um Web Services 'Server' com o sistema Microsiga Protheus

Uma vez configurado e habilitado os Web Services, no TOTVS | Application Server, deve-se inicialmente determinar os mtodos aos quais o servio se destina para ento determinar os parmetros e retorno de cada mtodos. Aps determinar essas informaes, deve-se codificar uma classe especial da linguagem AdvPL, chamada WSService(), que constituir o servio. No entanto, antes de iniciar a codificao, expressamente recomendado que sejam lidos todos os artigos do tpico Aplicaes Server, onde so abordados em detalhes a infraestrutura envolvida com os Web Services, seu funcionamento e particularidades de comportamento da classe de Web Services.

03. Regras para codificao de um Web Service

Viso Geral Para codificao de um Web Service, foram criadas na linguagem AdvPL instrues especiais de declarao de classes, especficas para Web Services, que suportam nome longos no nome da classe, mtodos e propriedades. A utilizao destes comandos exige a declarao da #include totvswebsrv.ch, no incio do cdigo fonte, como tambm ateno a alguns pontos e particularidades, comeando pela nomenclatura do servio, estruturas, mtodos e propriedades. Caractersticas operacionais do ambiente muito importante estar atento ao desenvolver os mtodos de Web Services, devido s caractersticas operacionais do ambiente de Working Threads utilizado pelo Web Service. Ao executar um mtodo do Web Service, o ambiente ser mantido no ar, aguardando uma nova requisio de processamento, de qualquer servio ou mtodo de qualquer cliente. Deste modo, ao desenvolver um servio, no deve-se deixar abertas as queries utilizadas no mtodo, filtros setados em tabelas principais ou configuraes especficas no-padro do ambiente, realizadas para o processamento de um mtodo especfico, pois isto pode causar impacto no funcionamento de todos os Web Services compilados e ativos neste servidor, com efeitos imprevisveis. Nomenclatura dos servios O nome de uma classe para Web Service, deve ser iniciada 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 o nome de uma palavra reservada, da linguagem AdvPL, ou ter o nome igual a um tipo bsico de informao. Nomenclatura de estruturas O nome dado a uma estrutura obedece as mesmas regras da nomenclatura de servios. Ou seja, no pode haver uma estrutura com o mesmo nome de um servio declarado. Alm disso, importante estar atento ao fato de uma estrutura no estar diretamente ligada ao servio em questo, de modo que no pode-se compilar duas estruturas de mesmo nome no mesmo repositrio. Uma estrutura constitui um agrupamento de dados, criado como um comando especial (WSSTRUCT) em AdvPL. Para isso, deve-se criar de uma estrutura para um servio, quando for necessrio agrupar um conjunto de dados bsicos e/ou outras estruturas em um nico 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 da 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'

Ao escrever um Web Service 'Server', deve-se especificar o tipo de 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 TOTVS | Application Server, quando da declarao dos parmetros e retorno, os seguintes tipos bsicos: Tipo String Date Integer Float Boolean Base64Binary Descrio Dado AdvPL do tipo string. Dado AdvPL do tipo data. Dado AdvPL do tipo numrico (apenas nmeros inteiros). Dado AdvPL do tipo numrico (pode conter nmeros inteiros e no-inteiros). Dado AdvPL do tipo booleano (lgico). Dado AdvPL do tipo string binria, aceitando todos os caracteres da tabela ASCII, de CHR(0) CHR(255).

Observao: Ao declarar uma propriedade como sendo do tipo string, no pode-se especificar a palavra string em letras maisculas. A palavra STRING, escrita desta maneira, interpretada pelo pr-compilador, do TOTVS | Application Server, como sendo uma constante, ocasionando erro de sintaxe da compilao do Web Service. O Tipo de dado Base64Binary tratado automaticamente e de forma transparente no AdvPL, contemplado pelo tipo de dado "C" Caractere do AdvPL, que permite contedo binrio. Isto signfica que, quando criamos uma classe Server de Web Services, onde usamos um tipo Base64Binary, o WSDL gerado pelo Server informar o uso deste tipo de informao, e quando um programa Client enviar um contedo esperado na requisio XML com este tipo de informao, a aplicao AdvPL j receber o contedo binario equivalente, sem a necessidade explcita de converso. Isto se aplica tambm s interfaces CLIENT de Web Services : O contedo codificado em Base64Binary recebido e enviado via protocolo/requisies XML, j chega devidamente convertido para contedo binrio nas propriedades do Client em AdvPL. O tipo Base64Binary utilizado quando da necessidade de trafegar, por exemplo, contedos binrios, por exemplo ima imagem JPEG, GIF, ou outra sequncia de bytes binria, que no devem estar sujeitas a tratamento de encoding, acentuao, etc. Deve-se atentar ao limite de string do AdvPL. de 1 MB . Um contedo em String, ao ser convertido para BASE64 pode ficar at 25 % maior. Logo, uma string binria com mais de 760 Kb no ser suportada para converso em Base64Binary e vice-versa. Lembre-se que o Web Service foi criado originalmente para requisies curtas, leves e rpidas. Se existe a necessidade de trafego de grandes quantidades de dados binrios de uma vez, existem protocolos mais interessantes, como o FTP por exemplo.

05. Estruturas - Tipos complexos

Uma estrutura (tambm conhecida por complex type), constitui um comando especial da linguagem AdvPL, chamado WSSTRUCT, criado especificamente para Web Services. Desta forma, deve-se criar uma estrutura quando tiver a necessidade de agrupar mais de uma informao, inclundo tipos bsicos e/ou outras estruturas. Ao criar um servio que dever receber como parmetro um grupo de informaes definidas como, por exemplo, os dados cadastrais de um cliente, deve-se criar uma estrutura para agrupar esses dados. No entanto, vale ressaltar que, a declarao de uma estrutura no amarra a mesma ao 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 tenha a ver com o servio ao qual ela pertena, pois no possvel compilar mais de uma estrutura de mesmo nome no repositrio.

06. Mtodos 'Server' em AdvPL - Caractersticas

Definio Um mtodo de um Web Service consiste em uma ao que ser disponibilizada no servio. Para isso, 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 Web Service deve, obrigatoriamente, tr uma propriedade de retorno. No faz parte da especificao de Web Services 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 Web Service deve ser declarado com um dado da classe (atravs da instruo WSDATA). Ao escrever um mtodo de um Web Service, e o mesmo receber 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 essas 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 comunicao, validao, montagem e desmontagem de pacotes. Ao codificar um mtodo de Web Service 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 verdadeiro (.T.), 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 devolvido, automaticamente, ao client que solicitou a chamada de processamento. Caso o retorno efetivo do mtodo seja falso (.F.), indica LIB que, por alguma razo tratada no cdigo-fonte do mtodo, no foi possvel a execuo do mtodo. Neste caso, deve-se especificar, antes do retorno, atravs da funo SetSoapFault(), a causa da impossibilidade de processamento.

Exemplo 1 WSMETHOD GetDate WSRECEIVE NULLPARAM WSSEND Horario WSSERVICE ServerTimeIf 2 dow(date())=1 3 SetSoapFault('Mtodo no disponvel','Este servio no funciona aos Domingos.') // Seta um soap_fault, informando que este servio no disponvel aos domingos 4 Return .F. Endif // e retorna .F., indicando que o servio no foi processado com sucesso. 5 ::Horario := time() // alimenta a propriedade de retorno 6 Return .T. // E retorna .T. indicando processamento do mtodo com sucesso

Ateno: Sempre que o retorno efetivo do mtodo verdadeiro (.T.), a propriedade de retorno deve ser preenchida. Caso no seja preenchida, a LIB retornar ao client solicitante um pacote de SOAP Fault, indicando que houve um erro no processamento do servio, e registrar um error.log na estao servidora. Alm disso, ser gerado tambm uma ocorrncia de erro, caso o mtodo retorne verdadeiro (.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 falso (.F.), e a funo SetSoapFault() no tenha sido chamada, devolvido estao client solicitante do processamento um Soap:Fault, com a seguinte ocorrncia de erro: <SERVICO> : <METODO> RETURN .F. WITH SOAP FAULT EXCEPTION EMPTY.

07. Tratamento de erro dos Web Services

Dada a infraestrutura envolvida no processamento dos Web Services, a rotina de tratamento de erro da aplicao Web Services 'Server' prev o tratamento de ocorrncias, desde advertncia de carga dos servios, falhas de inicializao de ambiente, passando por erros que invalidam um determinado servio compilado, at as ocorrncias de inconsistncia de parmetros de chamada do servio, inconsistncia 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 reproduzidas no momento da carga do ambiente de Web Services esto relacionados no tpico Falhas de Carga dos Servios, e a discriminao da utilizao do Soap Fault est descrita no tpico Utilizao do Soap Fault.

08. Utilizao do SOAP FAULT

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 execuo do Web Service, quando da ocorrncia de tal, gera automaticamente um 'SOAP FAULT' com a descrio resumida da ocorrncia ao 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 ao client solicitante. Para inserir as excees de execuo com SOAP FAULT, em um servio 'Server', deve-se utilizar a funo SetSoapFaut(). SOAP FAULTS padro do servidor TOTVS | Application Server de Web Services A camada de comunicao da infraestrutura de Web Service realiza, automaticamente, os tratamentos de protocolo, formato do pacote SOAP e parmetros obrigatrios. Caso exista alguma inconsistncia na chamada do servio e

incorra em alguma destas excees, o servio solicitado no chamado e o servidor TOTVS | Application Server devolve automaticamente ao cliente solicitante um SOAP FAULT, indicando o que aconteceu. Essas ocorrncias de SOAP FAULT so apresentadas no console, do TOTVS | Application Server, e so armazenadas no arquivo error.log do ambiente utilizado. SOAP FAULTS padro aps processamento do servio A camada de comunicao de infraestrutura de Web Services vlida 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 TOTVS | Application Server devolve automaticamente ao client solicitante um SOAP FAULT, indicando que ocorreu um erro interno no servidor de Web Services.

09. Servio de exemplo SERVERTIME

Inicialmente, o exemplo proposto tem o objetivo de montar um Web Service que retorne o horrio no servidor Protheus. Para isso, 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 execuo. Porm, ela ter um retorno: O horrio atual, no formato hh:mm:ss. A especificao de um WebService permite que um servio seja declarado de modo a no receber nenhum parmetro, mas exige que o Web Service sempre possua um retorno. Codificando o servio

Para codificar um servio, deve-se utilizar o TOTVS | Development Studio, 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. Essa numerao utilizada mais abaixo, onde o cdigo fonte exemplo detalhado linha a linha. 1 2 3 4 5 6 7 8 9 10 11 #INCLUDE TOTVS.CH #INCLUDE TOTVSWEBSRV.CH WSSERVICE SERVERTIME WSDATA Horario as String WSMETHOD GetServerTime ENDWSSERVICE WSMETHOD GetServerTime WSRECEIVE NULLPARAM WSSEND Horario WSSERVICE SERVERTIME ::Horario := TIME() Return .T. Linha 1 - especificada a utilizao da include TOTVS.CH, contendo as definies dos comando AdvPL e demais constantes. Linha 2 - especificada a include TOTVSWebSrv.CH, que contm as definies de comandos e constantes utilizados nas declaraes de estruturas e mtodos do Web Services. Ele obrigatrio para o desenvolvimento de Web Services. Linha 4 - Com esta instruo, definido o incio da classe do servio principal, ao qual damos o nome de SERVERTIME. Linha 5 - Dentro da estrutura deste servio, informado que um dos parmetros utilizados chama-se horrio, e ser do tipo string. Linha 6 - Dentro da estrutura deste servio, informado que um dos mtodos do servio chama-se GetServerTime. Linha 7 - Como no so mais necessrias mais propriedades ou mtodos neste servio, a estrutura do servio fechada com esta instruo.

Linha 9 - Aqui declarado o fonte do mtodo GetServerTime, que no receber parmetro nenhum (mas para efeitos de declarao, deve ser informado que ele receber o parmetro 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. Observe que, deve-se utilizar "::" para alimentarmos a propriedade da classe atual. Linha 11 - O mtodo GetServerTime finalizado nesta linha, retornando .T. (verdadeiro), indicando que o servio foi executado com sucesso. Aps compilado o servio, deve-se acessar novamente a pgina de ndice de servios (wsindex.apw) e verificar se o novo servio compilado encontra-se l. Se voc seguiu as configuraes desse documento, ento voc consegue acessa a pgina de ndices pelo endereo http://localhost/wsindex.apw . Isso significa que o servio em questo est sendo executado em ambiente local.

Testando o servio Ao acessar a pgina de ndice, e constatar a existncia do servio, deve-se 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 TOTVS | Development Studio para gerar o cdigo-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 Server, podemos gerar um cdigo-fonte client desta classe e compil-lo no mesmo repositrio do ambiente utilizado pelo Web Service 'Server', que a prpria interface de ndice de servios permitir o teste do mesmo. O processo de gerao do client ser apresentado no Tpico Aplicaes Client, onde ser possvel implementar o consumo desse servio configurado. Mas j que estamos falando de Aplicaes Web Service - Server, vamos concluir todos os conceitos referentes ao mesmo para depois darmos sequncia as configuraes.

10. Falha de carga dos servios

Neste tpico, abordaremos 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 Web Services como um todo, e ocorrncias que podem invalidar apenas um servio em caso de inconsistncia da declarao do mesmo. XXX : Erro de Estrutura : ARRAY OF em parmetro de entrada direto no suportado Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando um parmetro [XXX] foi utilizado como parmetro de entrada direto de um Web Services. Porm, o mesmo foi declarado com tratamento de "Array Of". Observao: No suportado receber diretamente um array como parmetro de um mtodo de Web Services 'Server'. Soluo Verifique e corrija o cdigo-fonte. Crie uma estrutura intermediria para encapsular o parmetro que deve ter tratamento de array.

Erro de Estrutura: Estrutura Indefinida Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando uma propriedade da classe server foi especificada como sendo uma estrutura, do tipo no bsico, porm a declarao da estrutura no foi localizada. Soluo Verifique e corrija o cdigo-fonte para proceder com a declarao da referida estrutura.

[XXX] Erro de Estrutura : Nome de Estrutura Invlido - Tipo bsico conflitante Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando o nome de uma determinada estrutura [XXX] foi especificada com um nome igual a um tipo bsico de informao. Observao: Esta ocorrncia invalida apenas o servio que utiliza a determinada estrutura. Soluo Verifique e corrija, no cdigo-fonte, a declarao do tipo da estrutura.

[XXX] : [YYY] : Erro de Mtodo : Estrutura de Entrada no encontrada Durante a etapa de validao dos servios, na carga dos Web Services, 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 cdigo-fonte construtor do servio. Soluo Verifique e corrija o cdigo-fonte para declarar o parmetro YYY como uma propriedade da classe XXX.

[XXX] : [YYY] : Erro de Mtodo : Estrutura de Retorno no encontrada Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi especificado com uma estrutura [YYY], cuja declarao no foi encontrada como uma propriedade no cdigo-fonte construtor do servio. Soluo Verifique e corrija o cdigo-fonte para declarar a propriedade YYY como uma propriedade da classe XXX.

[XXX] : [YYY] : Erro de Mtodo : Estrutura de Retorno no pode ser recebida como parmetro Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando um determinado mtodo [XXX] foi declarado para receber uma estrutura [YYY] e retornar a mesma estrutura [YYY]. Isto no no suportado pelos Web Services do sistema Microsiga Protheus. Soluo Verifique e corrija o cdigo-fonte.

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

Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando um determinado mtodo [XXX], referente ao servio [YYY], foi codificado, porm no foi declarado no construtor do Web Service. Esta ocorrncia invalida apenas o servio que utiliza a determinada estrutura. Soluo Verifique e corrija o cdigo-fonte para proceder com a declarao do mtodo no construtor do servio.

[XXX] Erro de Mtodo : Nome de Mtodo Invlido - Tipo bsico conflitante Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando o nome de um determinado 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. Soluo Verifique e corrija, no cdigo-fonte, a declarao do nome do mtodo.

Redundncia de Estruturas Durante a etapa de validao dos servios, na carga dos Web Services, esta ocorrncia reproduzida quando temos uma cadeia de estruturas, compostas por tipos bsicos e outras estruturas, e a declarao das estruturas entre 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 do tipo <B>, e <B> por sua vez tem uma propriedade do tipo <A>. Soluo Verifique e corrija, no cdigo-fonte, a declarao das estruturas envolvidas.

WSDL Server ONLOAD ERROR - Falha Interna na Carga do Web Service Esta ocorrncia apresentada na tela de ndice dos Web Services (wsindex.apw), quando algum erro fatal ocorre na carga dos Web Services. Os detalhes sobre a ocorrncia fatal so exibidas no console, do TOTVS | Application Server, e gravados no arquivo error.log, do ambiente em uso.

11. Ocorrncias de erro fatal e tratamento de erro

Neste tpico, abordaremos as mensagens de ocorrncias relacionadas erro fatal.As ocorrncias de erro fatal, refere-se falhas de carga do engine de Web Services como um todo e ocorrncias de falha de processamento quando da chamada para execuo dos servios.Para isso, em cada mensagens discriminaremos um resumo da ocorrncia, sua possvel causa e possveis solues.

AUTOMATIC URLLOCATION FAILED Ao configurar um Web Service 'Server', deve-se especificar, atravs da chave URLLOCATION, a URL especfica para o acesso aos servios.

Quando no definimos esta URL, a LIB de Web Services identifica automaticamente sob qual host o servio foi acessado. Esta operao no possvel quando o header HTTP do pacote permite informar uma operao diferente de 'Get' ou 'POST', ou o servidor do sistema esta executando tambm em uma 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 Web Service no processado, e o processamento abortado com a ocorrncia de erro acima.

BUILD [XXX] USING WEBSERVICES HTTPS NOT SUPPORTED Quando da carga inicial dos Web Services 'Server', a configurao da chave URLLocation criticada pela LIB. Caso, seja especificado que o acesso ser realizado via HTTPS e a build atual do TOTVS | Application Server utilizado ainda no suporta a utilizao do Web Service sob o protocolo HTTPS.

INVALID URLLOCATION [XXX] ON [YYY] Quando da configurao do TOTVS | Application Server para Web Services, caso especificada a configurao da chave URLLOCATION, na seo Environment, do arquivo de configurao do TOTVS | Application Server, porm a mesma no seja especificada com uma sintaxe vlida, o processamento abortado ao subir as 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 TOTVS | Application Server. Uma URL considerada invlida caso a mesma no seja iniciada com 'http://', 'https://', seja finalizada com um caractere no alfanumrico, diferente de '/', possua caracteres acentuados ou espaos. Desta forma, so considerados vlidos apenas os caracteres alfanumricos e caracteres ':' (dois pontos), '.' (ponto), '/' (barra) e '-' (hfen). Observao: Esta validao foi implementada na infraestrutura de Web Services, a partir da verso de infraestrutura 'ADVPL WSDL Server 1.031209'.

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 Web Service, na camada da LIB, quando da gerao do pacote 'SOAP' de retorno ao 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 arrray no continha nenhum elemento. Soluo Verifique o mtodo solicitado e certifique-se que a propriedade de retorno esteja sendo alimentada.

REQUIRED Return property [X] Type [Y] Unexpected Valtype [Z] Esta ocorrncia de erro reproduzida quando do trmino do processamento de um mtodo de um Web Services, na camada da LIB, quando da gerao do pacote 'SOAP' de retorno ao 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, a mesma continha um valor do tipo AdvPL [Z]. Soluo

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.

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 Web Services, na camada da LIB, quando da gerao do pacote SOAP de retorno ao client solicitante do servio. Quando da identificao da propriedade [X] de retorno do mtodo, a mesma deveria ser um array AdvPL, contendo elementos do tipo [Y]; porm, ao invs da propriedade ser um do tipo A (array), a mesma continha um valor do tipo AdvPL [Z]. Soluo Verifique o mtodo solicitado e certifique-se que a propriedade de retorno esteja alimentada com um array.

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 Web Service, na camada da LIB, quando da gerao do pacote 'SOAP' de retorno ao 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 tipo [Y]; porm, a propriedade de retorno continha um valor do tipo AdvPL [Z]. Soluo Verifique o mtodo solicitado e certifique-se que a propriedade de retorno seja alimentada com a respectiva estrutura, em conformidade com a declarao da propriedade da classe de servio.

Return property [X] Type [Y] Unexpected Valtype [Z] Esta ocorrncia de erro reproduzida quando do trmino do processamento de um mtodo de um Web Service, na camada da LIB, quando da gerao do pacote 'SOAP' de retorno ao 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, a mesma continha um valor do tipo AdvPL [Z]. Soluo 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.

UNKNOW ERROR : EMPTY HTTP RETURN Quando do processamento de uma requisio de um mtodo de Web Services 'Server', so executadas consistncias de pr 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 (SOAP Fault), 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. No entanto, at o momento, esta ocorrncia no foi reproduzida sob nenhuma condio.

[SVC] : [METHOD] as [X] : Tipo Inesperado de Retorno do Mtodo Esta ocorrncia de erro reproduzida, quando do trmino da execuo de um mtodo de uma classe 'Server' de Web Services. 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 [METHOD] e o tipo de retorno efetivo retornando em [X]. Soluo Verifique o cdigo-fonte do mtodo do servio e certifique-se que o retorno efetivo do mtodo seja sempre .T. (verdadeiro) ou .F. (falso).

Exemplos AdvPL
A seguir so apresentados diversos cdigos-fonte que exemplificam o uso das funes: GetWSCError GetWSCVer GetWSSVer SetSoapFault.

Exemplo de uso da funo GetWSCError

Neste exemplo, ser ilustrado o tratamento de erro sugerido para uma chamada de um mtodo atravs de um programa 'Client', desenvolvido em AdvPL. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 #include 'Protheus.ch' #include 'ApWebSrv.ch' User Function TstService Local oService , cSvcError , cSoapFCode ,cSoapFDescr ClienteoService := WSTeste():New() // Cria uma instncia do servio If oService:Hello() // Realiza a chamada do mtodo Hello() do servio. MsgStop('Execuo OK') // Mtodo executado com sucesso. 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

16 17 18 19 EndifoService := NIL 20 21 Return

Exemplo de uso da funo GetWSCVer

Neste exemplo, obtemos a verso da Lib 'Cliente' de Web Services compilada no repositrio atual. 1 User Function ShowVersions() 2 Local cCliVers := GetWSCVer() 3 MsgStop(cCliVers) 4 Return

Exemplo de uso da funo GetWSSVer

Neste exemplo, obtemos a verso da Lib 'Server' de Web Services compilada no repositrio atual. 1 User Function ShowVersions() 2 Local cSrvVers := GetWSSVer() 3 MsgStop(cSrvVers) 4 Return

Exemplo de uso da funo SetSoapFault

Neste exemplo de uso da funo, apresentamos dois exemplos de cdigo-fonte para demonstrar sua utilizao. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 // ********* 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 //(...)

Observaes: No exemplo 01, partindo de um mtodo de um Web Services '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 ao ambiente do servidor. Por padro, o Fault-Code de um Soap-Fault 'SOAPFAULT_SENDER', o que indica que o servio no foi processado por alguma razo ligada ao pacote de dados enviados; e indica ao client que o pacote deve ser remontado para que o servio seja executado.

Web Services 'Client'

Aplicaes Protheus 'Client' de Web Services
Definio de client Quando um Web Service 'Server' criado e disponibilizado, junto disponibilizada a definio do servio, argumentos, estruturas e retornos (WSDL). Para utilizar 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 excees. Embora existam Web Services que podem ser acessados via HTTP direto, apenas passando parmetros via URL, o client do Web Services do TOTVS | Application Server 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 (a verso 1.1 da especificao SOAP foi utilizada como base para implementao do toolkit de Web Services do Microsiga Protheus). O TOTVS | Application Server possui ferramentas e infraestrutura incorporadas que permitem esta integrao. Gerao do client em AdvPL No TOTVS | Development Studio, encontra-se disponvel, no menu Ferramentas, a opo para que, atravs de um link para a obteno do documento WSDL de um servio, o TOTVS | Application Server gere automaticamente, em AdvPL, uma classe client para a comunicao e utilizao do mesmo. Para isso, necessrio obter o endereo internet (URL) do WSDL desejado, criar um novo cdigo-fonte e acessar no menu Ferramentas + Gerar Cliente WebServices.... No entanto, para cada servio que se tenha necessidade de gerar um cdigo-fonte client, recomenda-se que cada cdigo-fonte client seja gerado em um arquivo independente e exclusivo para este fim, e que de forma alguma este cdigo-fonte gerado, pelo assistente, seja alterado. Como a especificao SOAP 1.1 foi utilizada como base para a implementao da interface Client de Web Services, usar um WSDL fornecido com verso a partir de 1.2 pode no ser suportado na ntegra, gerando ocorrncias desde falha na gerao do fonte client em AdvPL, at a gerao ou funcionamento incompletos. Em casos especiais, pode ser necessria alguma alterao no cdigo-fonte client gerado, caso necessrio atender alguma necessidade especfica da aplicao Server de Web Services no contemplada de modo nativo pela implementao de Web Services do TOTVS | Application Server. Neste caso, deve-se tomar muita ateno e documentar o cdigo-fonte, pois caso este fonte tenha que ser gerado novamente por qualquer razo, a alterao realizada perdida e, se ainda necessria, dever ser realizado novamente no cdigo regerado manualmente. Requisitos bsicos para gerao do client em AdvPL O processo de gerao do cdigo-fonte disparado atravs do TOTVS | Development Studio, porm, o servidor TOTVS | Application Server que buscar o documento WSDL solicitado. De modo que, a estao servidora utilizada no ambiente deve ter acesso ao endereo solicitado. importante salientar que, o processo de busca da URL informada disparado pelo TOTVS | Development Studio, mas a operao realizada atravs do TOTVS | Application Server. Logo, a mquina onde o servio do TOTVS | Application Server est sendo executado deve ter acesso URL informada. Gerao de fonte client para WSDLs disponibilizados em arquivo Existem fornecedores de servios para Web Services que fornecem os arquivos contendo as definies (WSDL) para a gerao dos clients. O TOTVS | Development Studio suporta a gerao de fonte client em arquivo. Para tal, deve-se disponibilizar o arquivo em uma pasta a partir do RootPath do ambiente (environment) configurado no TOTVS |

Development Studio, e informar na caixa de dilogo da URL para a gerao do cdigo-fonte, o path do arquivo, sempre iniciado com "\" (barra inversa) , seguido do path e nome do arquivo no servidor a ser utilizado para a gerao. Por exemplo, caso o arquivo contendo o WSDL chama-se "meuservico.txt", e ele seja copiado para uma pasta chamada "WSDL", que fica a partir do RootPath do ambiente em uso no TOTVS | Development Studio, a URL informada no TOTVS | Development Studio para gerar o cdigo-fonte client deve ser "\wsdl\meuservico.txt" . O TOTVS | Development Studio no vai criticar a extenso do arquivo, mas sim o contedo do mesmo. Ele deve conter um arquivo XML no formato WSDL. Gerao de fonte client para WSDLs publicados com autenticao e/ou conexo segura ( HTTPS ) A engine de conexo client HTTP do TOTVS | Application Server suporta conexo com URLs com HTTPS, inclusive para a gerao de fonte client de Web Services. Existem apenas restries quando a URL dos Web Services exigir autenticao (usurio e senha) para baixar o WSDL, e/ou seja uma conexo HTTPS que exija um uso de certificado client especfico. No caso da autenticao, possvel acessar a URL onde o WSDL est publicado atravs de um Web Browser (Navegador da Web), fazer a autenticao atravs do Browser, e ao acessar o WSDL, salv-lo em arquivo, copiar para uma pasta a partir do RootPath do TOTVS | Application Server, e fazer a gerao do client pelo TOTVS | Development Studio informando o arquivo em disco. Este mesmo procedimento tambm pode ser aplicado quando o WSDL est publicado em um endereo HTTPS que requer uso de certificado client. Basta conseguir acessar o contedo do WSDL no Web Browser, acess-lo em disco, e fazer a gerao a partir do arquivo em disco. Caso o Web Service possua dependncias (imports) que estejam publicados, a gerao um pouco mais complicada, pois existe a necessidade de fazer download de todos os imports necessrios, e compilar um e apenas um arquivo contendo o WSDL principal com todos os imports para a gerao do fonte client ser feita com sucesso. Ainda quanto gerao de clients onde o WSDL est publicado com conexo segura (HTTPS) que exija o uso de um certificado client especifico, possvel gerar pelo TOTVS | Development Studio, desde que o TOTVS | Application Server seja configurado para uso do certificado, como se o certificado fosse utilizado para conexo entre remote e server ( vide configurao da seo [SSLCONFIGURE] do TOTVS | Application Server). Basta configurar o certificado no TOTVS | Application Server, subir o servio, e proceder com a gerao do fonte client pelo TOTVS | Development Studio, informando a URL.

Gerao de client em AdvPL - 1 Passo

1 Passo - Determinar como obter o WSDL do servio desejado. A maioria das definies WSDL, dos servios disponveis 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 poder 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, aps um cadastro no site e autorizao da empresa para uso do servio por ele provido. Exemplo Neste exemplo, a definio obtida diretamente via HTTP, atravs do link http://localhost/SERVERTIME.apw?WSDL. Mas, caso este link seja acessado atravs de um Web Browser (exemplo: Internet Explorer), ser apresentado no browse um documento XML correspondente a definio do servio.

Gerao de client em AdvPL - 2 Passo

2 Passo - Gerar o cdigo-fonte AdvPL, do client, usando o assistente do TOTVS Development Studio. Ao ser gerado um cdigo-fonte client para um Web Service, este cdigo-fonte conter as definies dos mtodos do servio, a(s) estrutura (s) utilizada (s) 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 cdigo-fonte gerado atravs do assistente de criao de fonte deve preferencialmente ser gerado e compilado em um arquivo exclusivo, destinado nico 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 cdigo-fonte seja gerado novamente.

Procedimento Para gerao do cdigo-fonte client, em AdvPL, para utilizar este servio, necessrio criar um novo arquivo .PRX, no TOTVS | Development Studio, especificamente para conter as classes deste servio. Para isso, acesso o menu Ferramentas + Gerar Cliente WebService. Ao clicar nesta opo, ser apresentada uma tela (tipo pop-up).

No campo URL do WebService, informe a URL de onde o servidor ir obter a definio do Web Service. No nosso exemplo, http//localhost/SERVERTIME.apw?WSDL. Aps a confirmao, caso o procedimento ocorra com sucesso, na janela de mensagens do TOTVS | Development Studio, ser apresentado 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 apresentado abaixo: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 #INCLUDE 'PROTHEUS.CH' #INCLUDE 'APWEBSRV.CH' /*============================================================================== 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 Alteraes neste arquivo podem causar funcionamento incorreto e sero perdidas caso o cdigo-fonte seja gerado novamente. ============================================================================= */ /*-----------------------------------------------------------------------------WSDL Service WSSERVERTIME ----------------------------------------------------------------------------- */ WSCLIENT WSSERVERTIME WSMETHOD NEW WSMETHOD GETSERVERTIME WSDATA _URL AS String WSDATA cGETSERVERTIMERESULT AS string ENDWSCLIENT 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 mtodo, contendo os encapsulamentos necessrios para tratamento de excees. 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 cdigo-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 observar que, as linhas em negrito no cdigo-fonte acima, no foram inseridas pelo assistente do TOTVS | Development Studio, mas acrescentadas a este documento para fins didticos.

O cabealho do cdigo-fonte contm informaes sobre a localizao do WSDL utilizado para a gerao do cdigofonte, 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.

Gerao de client em AdvPL - 3 Passo

3 Passo - Criar um cdigo-fonte que utilize a classe para utilizao do Web Service.

Neste passo, necessrio criar um novo cdigo-fonte, no TOTVS | Development Studio, e montar uma funo para utilizar a classe de Web Service client e obter o horrio no servidor. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 #INCLUDE TOTVS.CH User Function TestClient() Local oSvc := NIL oSvc := WSSERVERTIME():New() If oSvc:GETSERVERTIME() alert('Horrio no Servidor : ' + oSvc:cGETSERVERTIMERESULT) Else alert('Erro de Execuo : ' + GetWSCError()) Endif Return

Linha 1 - Declarao da include TOTVS.CH que contm as definies dos comandos AdvPL e demais constantes. Linha 3 - Inicia-se a definio da User Function para utilizar o Web Service. Linha 4 - Declarao de uma varivel local para conter o objeto do Web Service client. Linha 6 - Utilizando-se do servio, a varivel oSvc alimentada com um nova instncia do Web Service client, obtida atravs da sintaxe <NOME_DO_SERVIO>():New(). Linha 8 - O mtodo GetServerTime executado a partir do objeto do servio oSrv, sem passar qualquer parmetro. O retorno de um mtodo do client pode ser verdadeiro (.T.), se for executado com sucesso, ou falso (.F.), em caso de falha de execuo. Linha 9 - Caso o servio tenha sido executado com sucesso, o retorno esperado alimentado na propriedade cGetServerTimeResult do objeto do servio. Linha 11 - Caso contrrio (retorno falso (.F.)), ocorreu alguma falha na chamada do servio, como, por exemplo, o servidor no estava no ar, demorou muito para responder (time-out), entre outras. Para recuperar os detalhes da ocorrncia de erro, utilize a funo GetWSCError() para retornar uma string com o resumo da ocorrncia. Linha 14 - O programa de teste finalizado com um Return.

Gerao de client em AdvPL - 4 Passo

4 Passo - Executar o programa de teste.

Abra uma nova instncia do TOTVS | SmartClient e execute a funo U_TestClient. Caso o Web Service esteja no ar, funcionando e o cdigo-fonte client devidamente compilado e sem erros, o resultado esperado uma janela com o horrio do servidor. Exemplo

No ambiente montado para teste, o servidor de Web Service e o client esto no sistema, compilados no mesmo Repositrio de Objetos. Para fins didticos, possvel simular uma ocorrncia de falha no client ao desabilitar o servidor HTTP do TOTVS | Application Server (configurar a chave Enable=0, na seo [HTTP], do arquivo de configurao do TOTVS | Application Server), e reiniciar o TOTVS | Application Server e executar o programa client novamente. Com isso, o sistema apresentar uma tela semelhante ao exemplo abaixo:

Gerao de client em AdvPL - 5 Passo

5 Passo - Obtendo informaes de debug. At o 4 passo, vimos um exemplo completo de um client funcionando perfeitamente. Agora, possvel verificarmos 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 isso, foi criada a funo WSDLDbgLevel() que permite definir em tempo de execuo, um nvel de detalhamento de informaes adicionais relacionadas ao Web Service; informaes que so apresentadas no console do TOTVS | Application Server (caso habilitado). Essa funo recebe um nmero como parmetro, sendo:

Valor 0 (padro) 1 2

Descrio Sem informaes adicionais. Apenas strings SOAP de retorno do TOTVS | Application Server. String SOAP de envio e retorno.

Alm disso, observe na linha 7, do cdigo-fonte do 3 Passo, que a instruo WSDLDbgLevel(2) acrescentada para ativar o nvel mais complexo de informaes adicionais e possvel observar no console, do TOTVS | Application Server, as mensagens apresentadas durante a execuo do cdigo-fonte de testes do ?client?. Deve ser obtido um echo no console do TOTVS | Application Server semelhante ao exemplo abaixo:

Iniciando Thread (siga0984, AUTOMAN)...

1 Exemplo ------------------------------------------------------------------------------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)

2 Exemplo ---------------------------------- 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> -------------------------------------------------------------------------------

3 Exemplo --------------------------------- 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><GETSERVERTIMERESPONSE xmlns='http://automan:8000/webservice/'><GETSERVERTIMERESULT>10:37:10</GETSERVE RTIMERESULT></GETSERVERTIMERESPONSE></soap:Body></soap:Envelope> -------------------------------------------------------------------------------

Fim Thread (siga0984, AUTOMAN)

BytesIn 73 BytesOut 75

No primeiro exemplo so as mensagens informativas a respeito da chamada do Web Service, informando a URL chamada, o estilo SOAP de troca de dados (document), o NameSpace e o SoapAction utilizados. No segundo exemplo (SOAPSEND) informa o contedo do pacote Soap que foi enviado (postado) ao Servidor, e no terceiro exemplo (POST RETURN) informa o contedo do pacote Soap devolvido pelo Server referente a esta solicitao. Quando ocorre um erro qualquer, relacionado execuo do ?client? Web Services, o mtodo chamado retorna .F., e o erro pode ser recuperado atravs da funo GetWSCerror(), vista anteriormente . Para cada exceo prevista no ?client?, existe um cdigo de erro correspondente, todos eles prefixados com WSCERR . A maioria das ocorrncias est relacionada gerao do Cdigo-fonte do ?client? AdvPL utilizado-se o TOTVS | Development Studio. Todas as ocorrncias de exceo tratadas peo Web Services ?client? AdvPL esto relacionadas no Tpico Web Services ?client? ? Cdigos de Erro.

Ocorrncias de erro
[WSDL no suportado. Existe mais de um servio declarado.] Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 cdigo-fonte, o processo abortado, o WSDL considerado invlido, e o cdigo-fonte client no gerado.

WSCERR001 / No h SOAP:BINDINGS para a gerao do Servio. Durante a gerao do cdigo-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 Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 parmetros 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 <XXX> e <YYY>, correspondendo ao nome do parmetro e tipo utilizado, respectivamente.

WSCERR004 / NO IMPLEMENTADO ( 001<X> / <N> / WSDLTYPE_NAME ) Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebService 'Client', utilizando o TOTVS | Development Studio. 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 outra estrutura, e esta no seja encontrada no WSDL ( ocorrncia <X> = A ), ou seja encontrada - porm registrada no como uma estrutura (complextype)- ( ocorrncia <X> = B ), o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a estrutura pendente em <WSDLTYPE_NAME>.

WSCERR006 / WSDL invlido ou no suportado. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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, 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. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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, 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. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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, 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) 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 sada. 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 incompleto Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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, 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 subestrutura do servio , e a primeira (008) refere-se um parmetro/estrutura de primeiro nvel do servio.

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 sada. 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, porm esta indica uma falha em outro ponto da rotina interna de anlise.

WSCERR013 / [SOAP_TYPE] UNEXPECTED TYPE. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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, um parmetro de tipo bsico no se encontre entre os tipos bsicos suportados pelo engine 'Client' de WebServices do ERP, a gerao do cdigo-fonte abortada com esta ocorrncia, indicando em SOAP_TYPE o tipo no suportado.

WSCERR014 / INVALID NULLPARAM INIT Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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, para cada propriedade da estrutura do servio so montadas as rotinas de inicializao de cada uma delas. Caso a rotina de gerao de cdigo-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 Response not found. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-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 cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR016 / Requisio HTTPS no suportada neste Build. [XXX] Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando informada uma URL para buscar a definio do servio (WSDL), utilizando o protocolo HTTPS; porm a build do ERP atual no suporta o tratamento de Web Services 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, a build do ERP deve ser atualizado.

WSCERR017 / HTTP[S] Requisio retornou [NIL] Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando informada uma URL para buscar a definio do servio (WSDL), utilizando o protocolo HTTP ou HTTPS; e no foi possvel buscar o link solicitado, o processamento abortado com a ocorrncia acima. Dentre as possveis causas para esta ocorrncia, podemos considerar: Sintaxe da URL invlida Servidor invlido, inexistente, ou DNF no disponvel Servidor fora do ar Verifique a URL digitada, e realize a requisio da mesma atravs de um Web Browser, para certificar-se que a mesma vlida e que a definio WSDL est realmente publicada e acessvel sob o link informado.

WSCERR018 / HTTP[S] Requisio retornou [EMPTY] Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando informada uma URL para buscar a definio do servio (WSDL), utilizando o protocolo HTTP ou HTTPS; e no foi possvel buscar o link solicitado, o processamento abortado com a ocorrncia acima.

Diferentemente da ocorrncia WSCERR017, esta ocorrncia foi reproduzida quando o servidor de WebServices que fornece o documento WSDL foi localizado, a requisio foi feita com sucesso, porm o servidor recebeu como retorno um pacote HTTP incompleto ou invlido. Verifique a URL digitada, e realize a requisio da mesma atravs de um Web Browser, para certificar-se que a mesma vlida e que a definio WSDL est realmente publicada e acessvel sob o link informado.

WSCERR019 / (XXX) Arquivo no encontrado. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando informada uma URL para buscar a definio do servio (WSDL), apontando para um arquivo no disco, porm o arquivo no foi encontrado, o processamento abortado com a ocorrncia acima. Dentre as possveis causas para esta ocorrncia, podemos considerar: Diretrio no existente ou invlido. Arquivo no existente ou invlido. Falta de permisso de acesso ao arquivo solicitado.

WSCERR020 / ( XXX / FERROR YYY ) Falha de Abertura. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando informada uma URL para buscar a definio do servio (WSDL), apontando para um arquivo no disco; porm houve uma impossibilidade de acesso ao arquivo. Dentre as possveis causas para esta ocorrncia, podemos considerar: Arquivo aberto em modo exclusivo por outra estao. Falha de permisso/direito de abertura do arquivo. Verifique as propriedades e direitos do arquivo solicitado e repita a operao.

WSCERR021 / [INFO] WSDL Parsing [PARSER_WARNING] Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando informada uma URL para buscar a definio do servio (WSDL), aps o documento WSDL ser recuperado, caso seja detectada alguma inconsistncia, considerada pelo parser interno de xml do sistema como uma advertncia (warning), no documento XML, o WSDL considerado invlido e a gerao do fonte cancelada, com esta ocorrncia. Em PARSER_WARNING discriminada a mensagem de advertncia do parser interno; e em [INFO] especificado o documento/operao que apresentou a inconsistncia.

WSCERR022 / [INFO] WSDL Parsing [PARSER_ERROR] Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando informada uma URL para buscar a definio do servio (WSDL), aps o documento WSDL ser recuperado, caso seja detectada alguma inconsistncia, considerada pelo parser interno de xml do sistema como erro no documento XML, o WSDL considerado invlido e a gerao do fonte cancelada, com esta ocorrncia. Em [PARSER_ERROR] discriminada a ocorrncia de erro do parser interno; e em [INFO] especificado o documento/operao que apresentou a inconsistncia.

WSCERR023 / [xxx] FALHA INESPERADA AO IMPORTAR WSDL Esta ocorrncia reproduzida, ao gerar um cdigo-fonte de Web Services Client, utilizando o TOTVS | Development Studio. Ao informar uma URL para buscar a definio do servio (WSDL), aps o documento WSDL ser recuperado, caso tenha passado pela etapa de validao XML, onde o documento retornado constitui um XML sintaticamente vlido, o parser no identifica nenhuma estrutura referente a um documento WSDL. Desta forma, o documento considerado invlido e a gerao do cdigo-fonte cancelada com esta ocorrncia. No cabealho da mensagem [xxx], possvel verificar a especificao do documento/operao que apresentou a inconsistncia.

WSCERR024 / [MSG_INFO] MESSAGE no encontrada. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 seo de mensagens (message) seja especificado para uma operao, porm no seja encontrado no WSDL, o mesmo considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a mensagem no encontrada em [MSG_INFO]. Caso a informao [MSG_INFO] estiver vazia, o documento WSDL no especificou alguma mensagem de parmetro ou retorno na seo <portType> da lista de mtodos do WSDL.

WSCERR025 / [BIND_INFO] Binding no Encontrado. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 seo de amarrao (binding) no seja localizado para uma operao especificada no WSDL, e a mesma no seja encontrada no WSDL, o mesmo considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a mensagem no encontrada em [BIND_INFO].

WSCERR026 / TARGETNAMESPACE no definido no WSDL. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 iniciado este processamento, verificado se o documento WSDL contm a definio do NameSpace de destino (TargetNameSpace) utilizado. Caso este no seja localizado, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima.

WSCERR027 / [OPER_INFO] BIND:OPERATION no encontrado. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 operao/mtodo do WebService no seja encontrada na seo de amarrao (binding), o documento WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a operao no encontrada em [OPER_INFO].

WSCERR028 / [PORT_INFO] PortType no Encontrado em aPort. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 operao/mtodo do WebService no seja encontrada na seo de portas do WSDL ( PortType ), o documento WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a porta no encontrada em [PORT_INFO].

WSCERR029 / [PORT_INFO] PortType no contm operaes. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 operao/mtodo do WebService no contenha a definio das operaes na seo de portas do servio (PortType), o documento WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a porta sem definio em [PORT_INFO].

WSCERR031 / [SCTUCT_NAME] Tipo sem NAMESPACE. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 determinada estrutura seja identificada como sendo externa ao WSDL atual, referenciada por um IMPORT ou REF; se a estrutura estiver declarada no WSDL sem o referido namespace, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a estrutura incompleta em [STRUCT_NAME].

WSCERR032 / [SHORT_NS] NAMESPACE no encontrado. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 do processamento de estruturas pendentes, identificadas como sendo externas ao WSDL atual, especificadas por um IMPORT ou REF, o namespace da mesma deve estar declarado no header do WSDL. Caso ele no seja encontrado, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando o namespace no encontrado em [SHORT_NS].

WSCERR033 / [LONG_NS] NameSpace sem Import declarado Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. No processo de gerao, so analisados todos os parmetros e estruturas utilizadas pelos mtodos do servio, at que todas as estruturas utilizadas sejam processadas. Complementar ao erro WSCERR032, este reproduzido quando o namespace identificado para o parmetro seja externo ao WSDL, porm a URL para processamento do mesmo no seja especificada atravs de um Import no WSDL . Neste caso, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando o namespace no encontrado em [LONG_NAMESPACE] .

WSCERR034 / [INFO_NS] NAMESPACE sem LOCATION informado. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. No processo de gerao, so analisados todos os parmetros e estruturas utilizadas pelos mtodos do servio, at que todas as estruturas utilizadas sejam processadas. Complementar ao erro WSCERR033, este reproduzido quando a declarao da URL/Location do NameSpace externo no esteja declarado no <IMPORT...> do WSDL. Neste caso, o documento considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando o namespace incompleto em [INFO_NS].

WSCERR035 / [TYPE] Tipo indefinido. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 do processamento de estruturas pendentes, identificadas como sendo externas ao WSDL atual, especificadas por um IMPORT ou REF, o namespace da mesma identificado e importado, e todo o WSDL reprocessado. No reprocessamento, caso o parmetro/estrutura pendente no seja encontrado, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a estrutura pendente em [TYPE].

WSCERR036 / Definio no suportada. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 da validao de estruturas complexas, caso a mesma no possua tipo definido, e no seja uma referncia externa ao WSDL, ela deve ser uma referncia ao prprio SCHEMA. Caso seja especificado qualquer outro tipo de referncia, o WSDL no suportado, e o processo de gerao abortado com a mensagem acima.

WSCERR037 / [TYPE] Estrutura Interna Inesperada. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 da validao de estruturas complexas, caso a mesma tenha passado por todas as interpretaes cabveis a uma estrutura, e mesmo assim no foi possvel identific-la, o

WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando a estrutura em [TYPE].

WSCERR038 / [PARAM] WSDL invlido ou no suportado. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. 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 da validao de estruturas complexas, caso uma estrutura e/ou parmetro/retorno tenha passado por todas as interpretaes cabveis de uma estrutura, porm no foi possvel localizar ou identificar adequadamente a estrutura, o WSDL considerado invlido, e o processo de gerao abortado com a mensagem acima, identificando o parmetro de origem da mesma em [PARAM]. Em termos prticos, este erro significa que : OU o WSDL fornecido no vlido, OU a engine de parser WSDL do Protheus no reconheceu a estrutura como vlida, isto , no soube lidar com ela para gerar um fonte client AdvPL.

WSCERR039 / Unexpected DumpType [X] Quando da utilizao da funo XMLDataSet, para a interpretao de um objeto de retorno XML em formato DataSet, caso no seja passado um objeto AdvPL de tipo vlido (Objeto XML ou Array), o processamento abortado, mostrando a mensagem acima, identificando o tipo de parmetro recebido em [X]. Verifique o cdigo-fonte da aplicao e certifique-se de sempre passar um Objeto XML ou Array para a funo XMLDataSet().

WSCERR040 / Unexpected SCHEMA Type [X] Quando da utilizao da funo XMLDataSchema, para determinar os dados recebidos por um retorno de um Web Service que retorna uma referncia ao Schema, e no seja passado a funo um Objeto AdvPL de Tipo Vlido (Objeto Xml ou Array), o processamento abortado, mostrando a mensagem acima, identificando o tipo de parmetro recebido em [X]. Verifique o cdigo-fonte da aplicao e certifique-se de sempre passar um Objeto XML ou Array para a funo XMLDataSchema().

WSCERR041 / [NOTNIL_MESSAGE] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, no momento que o client est desmontando o pacote SOAP retornado pelo servio. Durante a desmontagem do pacote de retorno de um Web Service, caso algum parmetro obrigatrio do servio no esteja presente no pacote de retorno, o processamento abortado com a mensagem acima, identificando em [NOTNIL_MESSAGE] o parmetro/propriedade que no veio preenchida. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR042 / URL LOCATION no especificada. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, antes do envio do pacote SOAP com o(s) parmetro(s) d ao/mtodo solicitado. No momento de postar o pacote SOAP de parmetros para um Web Service, verificada a propriedade reservada _URL do objeto do Servio, que contm a URL para postagem do pacote ao servidor. Caso a mesma esteja vazia, o processamento abortado com a mensagem acima, antes da postagem dos dados. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError(). Verifique o cdigo-fonte, e certifique-se que, caso a propriedade _URL esteja sendo redefinida, a mesma no esteja vazia. Esta propriedade j alimentada automaticamente pelo engine client de webservices, de acordo com as informaes para postagens obtidas no WSDL utilizado para a gerao do cdigo-fonte client.

WSCERR043 / [SOAP_STYLE] SOAPSTYLE Desconhecido. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, antes do envio do pacote SOAP com o(s) parmetro(s) da ao/mtodo solicitado. No momento de postar o pacote SOAP de parmetros para um Web Service, verificado o formato do pacote SOAP a ser enviado ao client. Esta propriedade definida em fonte, no momento da gerao do fonte client, e no deve ser alterada. Caso a mesma seja alterada manualmente, e no esteja num formato vlido, o processamento abortado com a mensagem acima, antes da postagem dos dados, indicando em [SOAP_STYLE] o soap style invlido informado. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError(). Verifique o cdigo-fonte, e certifique-se que o mesmo no foi alterado automaticamente pelo engine client de webservices, de acordo com as informaes para postagem obtidas no WSDL utilizado para a gerao do fonte client.

WSCERR044 / No foi possvel POST : URL [URP_POST] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao enviar o pacote SOAP com o(s) parmetro(s) da ao/mtodo solicitado. Aps montado o pacote de envio para a solicitao de processamento do servio, o pacote postado no servidor indicado na URL especificada no servio. Caso o servidor de destino do pacote no seja localizado no DNS, ou no esteja no ar, o processamento abortado com a mensagem acima, e a URL de destino especificada em [URL_POST]. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR045 / Retorno VAZIO de POST : URL <URL> [HEADER_RET] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao enviar o pacote SOAP com o(s) parmetro(s) d ao/mtodo solicitado. Aps montado o pacote de envio para a solicitao de processamento do servio, o pacote enviado a URL discriminada no servio.

Diferentemente da ocorrncia WSCERR014, esta ocorrncia pode ser reproduzida quando o servidor de WebServices que atendeu requisio foi localizado, a requisio foi feita com sucesso, porm o servidor do sistema recebeu como retorno um pacote HTTP incompleto ou invlido, ou ocorreu um erro interno no servidor, referenciado no header do pacote HTTP; nestes casos o processamento abortado com a ocorrncia acima, informando em <URL> o endereo do servidor onde o dado foi postado, e, se disponvel, em HEADER_RET informado o contedo do Header de Retorno do HTTP. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR046 / XML Warning [XML_WARNING] ( POST em <URL> ) Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Aps montado e enviado o pacote de envio para a solicitao de processamento do servio, o pacote SOAP retornado pelo servio analisado para a alimentao dos parmetros AdvPL. Caso seja detectada alguma inconsistncia, considerada pelo parser interno de xml do sistema como uma advertncia (warning), no documento XML, o pacote SOAP de retorno considerado invlido, e o processamento abortado com esta ocorrncia, informando em XML_WARNING a mensagem de advertncia do parser interno; e em <URL> o servidor de WebServices que retornou o pacote. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR047 / XML Error [XML_ERROR] ( POST em <URL> ) Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Aps montado e enviado o pacote de envio para a solicitao de processamento do servio, o pacote SOAP retornado pelo servio analisado para a alimentao dos parmetros AdvPL. Caso seja detectada alguma inconsistncia, considerada pelo parser interno de xml do sistema, como um erro de sintaxe no XML, o pacote SOAP de retorno considerado invlido, e o processamento abortado com esta ocorrncia, informando em XML_ERROR a mensagem de erro do parser interno; e em <URL> o servidor de WebServices que retornou o pacote. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError(). Veja mais detalhes na funo GetWSCError(), pois ela oferece a possibilidade de recuperar os elementos principais de retorno de um pacote SOAP_FAULT isoladamente.

WSCERR048 / SOAP FAULT [FAULT_CODE] ( POST em <URL> ) : [FAULT_STRING] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, para a alimentao dos parmetros AdvPL, caso o pacote de retorno contenha uma exceo do tipo SOAP FAULT, isto indica que houve uma falha de processamento do servio no servidor. O processamento abortado com esta ocorrncia, informando em [FAULT_CODE] o cdigo da exceo SOAP, em <URL> o servidor de WebService que retornou o pacote, e em FAULT_STRING mais detalhes sobre a ocorrncia. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

Alternativas para soluo do erro WSCERR048 Ocorrncias de erro e a soluo possvel para elas: Erro: WSCERR048 / SOAP FAULT soap:Client ( POST em http://localhost/webservice/NomeDoServicoWS) : [Unmarshalling Error: unexpected element (uri:"http://localhost/", local:"NomeDaTag"). Expected elements are <{}NomeDaTag> ] Explicao: O Servidor espera que a tag "NomeDaTag" contenha o atributo "xmlns", ainda que vazio: <NomeDaTag xmlns=""> ... Soluo Altere a chamada da funo "WSSoapValue" no client gerado pelo IDE de modo que o ltimo parmetro da funo seja .T.: cSoap += WSSoapValue("NomeDaTag", ...... demais parmetros ......., .T.)

WSCERR049 / SOAP RESPONSE (RPC) NOT FOUND. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, para a alimentao dos parmetros AdvPL, caso o servio utilize um soapStyle = RPC, e o node de resposta no seja encontrado no pacote, o pacote de resposta considerado invlido, e o processamento abortado com a mensagem acima. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR050 / SOAP RESPONSE REF <NODE_REF> (RPC) NOT FOUND. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, para a alimentao dos parmetros AdvPL, caso o servio utilize um SoapStyle = RPC, e o node de resposta aponte para um outro node via referncia, e este novo node no seja encontrado no pacote, o pacote considerado invlido e o processamento abortado com a mensagem acima, mostrando o identificador de referncia no encontrado em <NODE_REF>. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR051 / SOAP RESPONSE RETURN (RPC) NOT FOUND. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, para a alimentao dos parmetros AdvPL, caso o servio utilize um soapStyle = RPC, e o node de retorno no aponte para nenhuma referncia, o retorno deve estar dentro do XML, no

nvel do node de resposta . Caso o node de retorno no seja encontrado neste nvel, o pacote de retorno considerado invlido, e o processamento abortado com a mensagem acima. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR052 / Enumeration FAILED on [STRUCT_TYPE] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, antes do envio do pacote SOAP com o(s) parmetro(s) da ao/mtodo solicitado. Antes da montagem do pacote SOAP, os parmetros do mtodo/ao solicitada do servio so analisados e validados. Caso um parmetro contiver uma definio de enumeration, obtida no WSDL, e for alimentado pelo cdigo-fonte client com um valor que no conste na lista de parmetros vlidos, o processamento abortado com a mensagem acima, identificando o parmetro envolvido em [STRUCT_TYPE]. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError(). Verifique o cdigo-fonte client gerado em AdvPL, para obter a lista de parmetros vlido; e certifique-se que o parmetro especificado est alimentado de forma correta.

WSCERR053 / WSRPCGetNode (Object) not found. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, para a alimentao dos parmetros AdvPL, caso o servio utilize um soapStyle = RPC, no momento de anlise de um retorno de uma estrutura complexa, caso o node correspondente a estrutura no seja localizado no pacote de retorno, o mesmo considerado invlido, e o processamento abortado com a mensagem acima. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR054 / Binding SOAP no localizado no WSDL. Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Durante a gerao do cdigo-fonte, uma vez identificado o servio, o gerador de cdigo procura a declarao das amarraes do servio (BINDINGS) no WSDL. Dentre as amarraes encontradas, apenas so processadas aquelas que especificam o transporte de dados para o servio no formato SOAP. Caso no exista nenhuma amarrao no servio, que especifique a utilizao do SOAP, o processo de gerao do cdigofonte client abortado, retornando esta ocorrncia. A infraestrutura Client de WebServices do sistema no suporta a gerao de fontes-client de servios que no utilizem pacotes XML - SOAP para a troca de informaes.

WSCERR055 / Invalid Property Type (X) for [PARAM] (Y) Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, antes do envio do pacote SOAP com o(s) parmetro(s) da ao/mtodo solicitado. Antes da montagem do pacote SOAP, os parmetros do mtodo/ao solicitada do servio so analisados e validados. As propriedades da classe, utilizadas como parmetros, devem ser alimentadas com os tipos AdvPL apropriados, de acordo com sua definio. Caso uma determinada propriedade [PARAM] do objeto 'Client' do servio esteja alimentada com um tipo de dado Advpl [X], porm o tipo esperado era [Y], o processamento abortado com a ocorrncia de erro acima. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError(). Verifique o cdigo-fonte client gerado em AdvPL, e certifique-se que o parmetro especificado est sendo alimentado de forma correta, com o tipo apropriado.

WSCERR056 / Invalid XML-Soap Server Response : soap-envelope not found. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar o processamento do pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, caso o mesmo no contenha um envelope (soap-Envelope) de resposta, o retorno considerado invlido, e o processamento abortado com a mensagem acima. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR057 / Invalid XML-Soap Server Response : soap-envelope empty. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar o processamento do pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, caso no seja possvel determinar o prefixo do SOAP Envelope utilizado, o retorno considerado invlido, e o processamento abortado com a mensagem acima. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR058 / Invalid XML-Soap Server Response : Invalid soap-envelope [SOAP_ENV] object as valtype [X] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar o processamento do pacote SOAP recebido como retorno da ao/mtodo solicitado. Ao analisar o pacote SOAP retornado pelo servio, caso o soap-envelope determinado [SOAP_ENV], esperado como um Objeto, foi recebido com um tipo AdvPL [X]. Isto invalida o pacote soap recebido, sendo o processamento abortado com a ocorrncia acima. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR059 / Invalid XML-Soap Server Response : soap-body not found. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar o processamento do pacote SOAP recebido como retorno da ao/mtodo solicitado. Semelhante ocorrncia WSCERR056, esta ocorrncia indica que no foi possvel determinar o corpo (soap-body) do pacote SOAP retornado pelo servio; o que invalida o pacote de retorno, sendo o processamento abortado com esta ocorrncia de erro. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR060 / Invalid XML-Soap Server Response : soap-body envelope empty. Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar o processamento do pacote SOAP recebido como retorno da ao/mtodo solicitado. Semelhante ocorrncia WSCERR057, esta ocorrncia indica que pacote SOAP retornado, no foi possvel determinar o prefixo do corpo (soap-body) utilizado; o que invalida o pacote de retorno, sendo o processamento abortado com esta ocorrncia de erro. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR061 / Invalid XML-Soap Server Response : Invalid soap-body [BODY] object as valtype [TYPE] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar o processamento do pacote SOAP recebido como retorno da ao/mtodo solicitado. Semelhante ocorrncia WSCERR058, esta ocorrncia indica que no SOAP retornado, o corpo (soap-body) determinado [BODY], esperado como um Objeto, foi recebido como um tipo AdvPL [TYPE], ; o que invalida o pacote de retorno, sendo o processamento abortado com esta ocorrncia de erro. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR062 / Invalid XML-Soap Server Response : Unable to determine Soap Prefix of Envelope [SOAP_ENV] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar o processamento do pacote SOAP recebido como retorno da ao/mtodo solicitado. Esta ocorrncia indica que, no SOAP retornado, o envelope (soap-envelope) determinado [SOAP_ENV], no est em um formato que seja possvel determinar o nome do envelope; o que invalida o pacote de retorno, sendo o processamento abortado com esta ocorrncia de erro. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR063 / Argument error : Missing field [NODE] as [TYPE] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao iniciar a montagem do pacote SOAP com os parmetros para a chamada do servio. Esta ocorrncia indica que, o parmetro obrigatrio determinado em [NODE], com o tipo [TYPE], no foi alimentado para a chamada da funo client. Esta ocorrncia invalida a montagem do pacote de envio, abortando o processamento antes do envio do pacote, com esta ocorrncia. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR064 / Invalid Content-Type return (HTTP_HEAD) from <URL> Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Aps montado e enviado o pacote de envio para a solicitao de processamento do servio, o pacote SOAP retornado pelo servio analisado para a alimentao dos parmetros AdvPL. Esta ocorrncia indica que, o header HTTP de retorno do servio, postado em <URL>, veio com o contedo do header HTTP retornado pelo servidor, indica o uso de content-type diferente de XML, o que invalida o processamento do retorno. Um Web Service client sempre espera por um pacote de retorno com um 'Content-type: text/xml' de um Web Services SERVER. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError(). Esta ocorrncia normalmente reproduzida, quando um determinado WebService no est mais publicado no endereo especificado, porm a URL ainda vlida. De modo que, ao receber a requisio, o servidor devolve uma pgina HTML, com uma mensagem do tipo 'Page not Found'.

WSCERR065 / EMPTY Content-Type return (HEADER) from <URL> Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de WebServices, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. Semelhante ocorrncia WSCERR064, esta ocorrncia indica que, aps a postagem de um pacote SOAP ao servidor de destino do WebService, em <URL>, o contedo do header HTTP retornado (HEADER) retornado pelo servidor, no possua a identificao do Content-Type, o que invalida o processamento de retorno. O client AdvPL sempre espera por um pacote de resposta com um content-type: text/xml como retorno. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError().

WSCERR066 / Invalid INVALID WSDL Content-Type (HTTP_HEAD) from <URL> Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Esta ocorrncia indica que, o header HTTP de retorno da requisio do WSDL, solicitado no endereo <URL>, veio identificando um tipo de documento (content-type) diferente de textp/plain ou text/xml, o que invalida o processamento do retorno. Um Web Service client sempre espera por um pacote de retorno com um 'Content-type: text/xml' ou 'text/plain', de um Web Services SERVER.

Esta ocorrncia normalmente reproduzida, quando um determinado WebService no est mais publicado no endereo especificado, porm o servio de HTTP ainda est ativo no servidor solicitado. De modo que, ao receber a requisio, o servidor devolve uma pgina HTML, com uma mensagem do tipo 'Page not Found'. Alternativa para gerao do client Caso o WSDL possa ser aberto atravs de um navegador de internet (Internet Explorer, Mozilla Firefox, etc), proceda da seguinte forma: 1. Abra a URL do WSDL no navegador de internet. 2. Salve o documento em um diretrio do RootPath do TOTVS | Application Server. 3. Gere o client novamente a partir do TOTVS | Development Studio, desta vez colocando no campo "URL do WebService" o caminho em que o arquivo se encontra no RootPath. Exemplo: "\arquivo.wsdl".

WSCERR067 / EMPTY WSDL Content-Type (HTTP_HEAD) from <URL> Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Esta ocorrncia indica que, o header HTTP de retorno do WSDL, solicitado atravs do link <URL>, veio com o contedo do header HTTP sem a informao do tipo de contedo do documento (content-type). Um documento WSDL deve ser retornado pelo servidor de WebServices, informando no header HTTP um tipo de documento (content-type) definido como text/plain ou text/xml.

WSCERR068 / NOT XML SOURCE from <URL> Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Esta ocorrncia indica que, o documento retornado pelo servidor de Web Services no se trata de um XML vlido para ser analisado. O documento WSDL deve sempre iniciar com o node da declarao do XML ( <?XML ...) . Caso no possua esta informao, o primeiro node deve obrigatoriamente ser a definio do servio ( <DEFINITIONS ). Se o documento WSDL retornado no atender a estes requisitos, o processamento abortado com a mensagem acima.

WSCERR069 / BYREF [PARAM] WITH NO INPUT ARGUMENT : UNSUPPORTED WEBSERVICE Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando da gerao do cdigo-fonte, caso o WSDL retornado informe um mtodo de Web Services, que possua mais de um parmetro de retorno, isto caracteriza um mtodo que trabalha com parmetros por referncia (BYREF). Neste caso, aps o cruzamento dos retornos do mtodo com os parmetros, deve restar no mximo um retorno. Caso mesmo assim, reste mais de um retorno, o WSDL considerado invlido, sendo o processo de gerao abortado com a mensagem de erro acima, informando em [PARAM] o retorno excedente, que deveria ser localizado nos parmetros.

WSCERR070 / Requisio HTTPS no suportada neste BUILD [PROTHEUS_BUILD] Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de Web Services, antes do envio do pacote SOAP com o(s) parmetro(s) da ao/mtodo solicitado.

No momento de postar o pacote SOAP de parmetros para um Web Service, verificado se o protocolo em uso o HTTPS; e se o mesmo j suportado pela Build atual do servidor TOTVS | Application Server em uso. Esta ocorrncia capturada pelo prprio cdigo-fonte do mtodo, sendo que o mtodo 'Client' chamado retornar .F. (falso), e a descrio da ocorrncia deve ser recuperada atravs da funo GetWSCError(). Verifique o cdigo-fonte, e certifique-se que, caso a propriedade _URL esteja sendo redefinida, a mesma no esteja sendo redefinida para um endereo utilizando HTTPS. Caso a propriedade _URL no esteja sendo redefinida, e o servio solicitado exija o envio dos dados atravs de HTTPS, a build do servidor TOTVS | Application Server deve ser atualizado.

WSCERR071 / INVALID HTTP HEADER (HTTPHEAD) from <URL> Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de WebServices 'Client', utilizando o TOTVS | Development Studio. Quando da gerao de cdigos-fonte AdvPL, caso o servidor informado, acessado via URL, retorne um pacote HTTP, com um header de retorno que no seja identificado como HTTP, o processo de gerao abortado com a ocorrncia acima, informando em <httphead> o header informado, e em <url> o endereo informado para a solicitao do WSDL. Dentre as possveis causas, podemos considerar que a URL informada no corresponde a um servidor HTTP ou de WEB SERVICES. Para certificar-se da ocorrncia, abra a URL especificada utilizando um Web Browser.

WSCERR072 / HTTP REQUEST ERROR (HEADER) from <URL> Esta ocorrncia de erro reproduzida, quando da gerao de um cdigo-fonte de Web Services 'Client', utilizando o TOTVS | Development Studio. Quando da gerao de cdigos-fonte AdvPL, caso o servidor informado, acessado via URL, retorne um pacote HTTP, com um header de retorno HTTP, porm com um status diferente de 200 (OK) , o processo de gerao abortado com a ocorrncia acima, informando em <HEADER> a primeira linha do cabealho HTTP retornado, e em <url> o endereo informado para a solicitao do WSDL. Dentre as provveis causas, podemos considerar os status de retorno '403 Forbidden', retornados por proxys que requerem autenticao ou no permitem o acesso URL especificada, o '500 Internal Server Error', que indica uma ocorrncia interna de erro no servidor, que impossibilitou o retorno do WSDL.

WSCERR073 / Build (BUILD) XML Internal Error Esta ocorrncia reproduzida, quando da utilizao de um cdigo-fonte Client de Web Services, ao processar o pacote SOAP recebido como retorno da ao/mtodo solicitado. O pacote SOAP retornado pelo servio analisado para a alimentao dos parmetros AdvPL. Em primeiro momento, so realizadas as consistncias de cabealho de protocolo (header), e em seguida o pacote SOAP desmontado por um parser interno do TOTVS | Application Server, onde verificada a sintaxe do documento XML ( Veja ocorrncias WSCERR046 e WSCERR047 ), e a resultante deste processo ser um objeto intermedirio. Se e somente se, o contedo SOAP retornado pelo servio, contenha um erro estrutural ou sinttico, que no seja detectado pelo parser interno como um erro ou advertncia, este objeto intermedirio no gerado, o que impossibilita a rotina de prosseguir o processamento. Esta ocorrncia j foi reproduzida anteriormente, em builds do TOTVS | Application Server anteriores Dezembro/2003. Em releases posteriores a este, o tratamento dos pacotes de retorno do servio foi revisado; desde ento esta ocorrncia no mais foi reproduzida.

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

WSCERRINT ERROR_DESCRIPTION Quando executado um mtodo 'client' de Web Service, as ocorrncias de falha dentro destas rotinas so protegidas por um tratamento de erro exclusivo, que informa detalhes da ocorrncia. Se, e somente se, o tratamento de erro for acionado por uma ocorrncia inesperada, em algum ponto do processamento do mtodo da classe client, a descrio da ocorrncia de erro capturada, e mostrada em , e a ocorrncia prefixada com o cdigo WSCERRINT (Web Service Client Internal Error). Caso seja reproduzida esta ocorrncia, verifique os parmetros informados ao mtodo chamado, e certifique-se que o cdigo-fonte da classe 'client' em AdvPL no sofreu nenhuma alterao manual, aps a gerao do prprio.

ERROR_DESCRIPTION Invalid Method registrada a ocorrncia WSCERRINT / invalid method no envio de um pacote SOAP cujo parmetro da ao/mtodo solicitado provm de um schema.
------------------------------------------------------------------------------WSCERRINT / invalid method APXMLDOC45682:SOAPSEND ADVPL WSDL Client 1.090116 / TOTVS Manufatura Everymoment on 20100521 16:04:52 -------------- CallStack -------------Called from WSSOAPVALUE (4438) Called from MARCARNOVOSRECLAMANT ( 115) Called from EXEMPLO ( 9) -------------------------------------------------------------------------------

Ocorrncia

Altere o cdigo-fonte do 'client' Web Service e onde temos:

cSoap += WSSoapValue("reclamanteTable", ::oWSreclamanteTable, oWSreclamanteTable , "SCHEMA", .F. , .F., 0 , NIL, .F.)

Soluo

Monte e substitua pelo xml no formato requerido:

cSoap += "<reclamanteTable></reclamanteTable>"

Tipos de dados suportados - Client

possvel gerar cdigo-fonte AdvPL, para Web Service client, utilizando o tipos bsicos de dados reservados para aplicaes client. Para permitir a manipulao de cada tipo de dado, utilizando variveis AdvPL, so utilizados os tipos bsicos da linguagem AdvPL que tratam simultaneamente mais de um tipo de dado dos pacotes SOAP dos Web Services. A seguir, observe os tipos de dados disponibilizados, em AdvPL, atravs de uma varivel dos seguintes tipos:

Varivel do tipo 'N' Numrica INT INTEGER BYTE FLOAT DOUBLE UNSIGNEDLONG UNSIGNEDINT DECIMAL LONG

Varivel do tipo 'D' Data DATE

Varivel do tipo 'C' Character STRING DATETIME CHAR (Corresponde a uma string que contm o nmero do caractere correspondente tabela ASCII.) BASE64BINARY

Varivel do tipo 'L' Lgica BOOLEAN

Glossrio - Web Services

Glossrio de termos e expresses de Web Services. 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. Fonte Client: Cdigo-fonte AdvPL, gerado pela ferramenta do TOTVS | Development Studio 'Gerar Cliente WebServices...', a partir de uma definio WSDL publicada em um servidor HTTP ou disponibilizada em um arquivo .WSDL. SOAP - 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. Tipo bsico: So chamados de tipos bsicos, uma lista de tipos de informaes 'nativa' ,implementada na definio dos WebServices. 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 ERP 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. XML - 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 - 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.

Observao: No deixe de visitar o Totvs Developer Network atravs do link http://tdn.totvs.com para incrementar e atualizar os seus conhecimentos.