COBOL - PROCEDURE DIVISION - Producing XML output - Generating XML output



Desenvolvido por DORNELLES Carlos Alberto - Analista de Sistemas - Brasília DF. - cad_cobol@hotmail.com

COBOL - PROCEDURE DIVISION - Producing XML output - Generating XML output
Enterprise COBOL for z/OS 6.3.0, Language Reference

Para transformar dados COBOL em XML, use a instrução XML GENERATE como no exemplo abaixo.

           XML GENERATE XML-OUTPUT FROM SOURCE-REC
               COUNT IN XML-CHAR-COUNT
               ON EXCEPTION
                  DISPLAY 'XML generation error ' XML-CODE
                  STOP RUN
           NOT ON EXCEPTION
                  DISPLAY 'XML document was successfully generated.'
           END-XML

Na instrução XML GENERATE, você primeiro identifica o item de dados (XML-OUTPUT no exemplo acima) que deve receber a saída XML.
Defina o item de dados como grande o suficiente para conter a saída XML gerada, geralmente de cinco a 10 vezes o tamanho dos dados de origem COBOL, dependendo do comprimento do nome ou nome dos dados.

Na DATA DIVISION, você pode definir o identificador de recebimento como alfanumérico (um item de grupo alfanumérico ou um item elementar da categoria alfanumérica) ou como nacional (um item de grupo nacional ou um item elementar da categoria nacional).

Em seguida, você identifica o item de dados de origem que deve ser transformado para o formato XML (SOURCE-REC no exemplo).
O item de dados de origem pode ser um item de grupo alfanumérico, item de grupo nacional ou item de dados elementar da classe alfanumérica ou nacional.

Alguns itens de dados COBOL não são transformados em XML, mas são ignorados.
Os itens de dados subordinados de um item de grupo alfanumérico ou nacional que você transforma em XML serão ignorados se:

  • Especifique a cláusula REDEFINES ou esteja subordinada a esse item redefinidor
  • Especifique a cláusula RENAMES

Esses itens no item de dados de origem também são ignorados quando você gera XML:

  • Itens de dados elementares do FILLER (ou sem nome)
  • Bytes Slack (fracos) inseridos para itens de dados SYNCHRONIZED

Nenhum espaço em branco extra (por exemplo, novas linhas ou recuo) é inserido para tornar o XML gerado mais legível.

Opcionalmente, você pode codificar a frase COUNT IN para obter o número de unidades de codificação de caracteres XML que são preenchidas durante a geração da saída XML.
Se o identificador de recebimento tiver categoria nacional, a contagem estará em unidades de codificação de caracteres UTF-16.
Para todas as outras codificações (incluindo UTF-8), a contagem é em bytes.

Você pode usar o campo de contagem como um comprimento de modificação de referência para obter apenas a parte do item de dados de recebimento que contém a saída XML gerada.
Por exemplo, XML-OUTPUT (1: XML-CHAR-COUNT) faz referência às primeiras posições de caracteres XML-CHAR-COUNT de XML-OUTPUT.

Considere o seguinte trecho do programa:

       01  doc       pic x(512).
       01  docSize   pic 9(9) binary.
       01  G. 
           05  A     pic x(3) value "aaa". 
           05  B. 
               10  C pic x(3) value "ccc". 
               10  D pic x(3) value "ddd". 
           05  E     pic x(3) value "eee".
           . . .
           XML Generate Doc from G

O código acima gera o seguinte documento XML, no qual A, B e E são expressos como elementos filho do elemento G e C e D se tornam elementos filho do elemento B:

<G><A>aaa</A><B><C>ccc</C><D>ddd</D></B><E>eee</E></G>

Como alternativa, você pode especificar a frase ATTRIBUTES da instrução XML GENERATE.
A frase ATTRIBUTES faz com que todos os itens de dados elegíveis incluídos no documento XML gerado sejam expressos como um atributo do elemento XML que contém, e não como um elemento filho do elemento XML que contém.
Para ser elegível, o item de dados deve ser elementar, deve ter um nome diferente de FILLER e não deve ter uma cláusula OCCURS em sua entrada de descrição de dados.
O elemento XML que contém corresponde ao item de dados do grupo que é imediatamente superordenado ao item de dados elementar.
Opcionalmente, você pode especificar um controle mais preciso de quais itens de dados devem ser expressos como atributos ou elementos usando a frase TYPE OF.

Por exemplo, suponha que a instrução XML GENERATE no trecho do programa acima tenha sido codificada da seguinte maneira:

XML Generate Doc from G with attributes

O código geraria o seguinte documento XML, no qual A e E são expressos como atributos do elemento G, e C e D se tornam atributos do elemento B:

<G A="aaa" E="eee"><B C="ccc" D="ddd"></B></G>

Opcionalmente, você pode codificar a frase ENCODING da instrução XML GENERATE para especificar o CCSID do documento XML gerado.
Se você não usar a frase ENCODING, a codificação do documento será determinada pela categoria do item de dados de recebimento e pela opção do compilador CODEPAGE.
Para obter detalhes adicionais, consulte a tarefa relacionada abaixo sobre como controlar a codificação da saída XML gerada.

Opcionalmente, você pode codificar a frase XML-DECLARATION para fazer com que o documento XML gerado tenha uma declaração XML que inclui informações de versão e uma declaração de codificação. Se o item de dados de recebimento for da categoria:

  • National: a declaração de codificação tem o valor UTF-16 (codificação = "UTF-16").
  • Alfanumérico: a declaração de codificação é derivada da frase ENCODING, se especificada, ou da opção do compilador CODEPAGE em vigor para o programa, se a frase ENCODING não for especificada.

Por exemplo, o trecho do programa abaixo especifica a frase XML-DECLARATION de XML GENERATE e especifica a codificação com CCSID 1208 (UTF-8):

           01  Greeting. 
               05 msg  pic x(80)  value 'Hello, world!'. 
           . . .
           XML Generate Doc from Greeting 
               with Encoding 1208 
               with XML-declaration 
           End-XML

O código acima gera o seguinte documento XML:

<?xml version="1.0" encoding="UTF-8"?><Greeting><msg>Hello, world!</msg></Greeting>

Se você não codificar a frase XML-DECLARATION, uma declaração XML não será gerada.

Opcionalmente, você pode codificar a frase NAMESPACE para especificar um espaço para nome para o documento XML gerado.
O valor do espaço para nome deve ser um URI (Uniform Resource Identifier) válido, por exemplo, uma URL (Uniform Resource Locator); para obter mais detalhes, consulte o conceito relacionado sobre a sintaxe do URI abaixo.

Especifique o espaço para nome em um identificador ou literal da categoria nacional ou alfanumérico.

Se você especificar um espaço para nome, mas não especificar um prefixo para o espaço para nome (descrito abaixo), o espaço para nome se tornará o espaço para nome padrão do documento.
Ou seja, o espaço para nome definido no elemento raiz se aplica por padrão a cada nome de elemento no documento, incluindo o elemento raiz.

Por exemplo, considere as seguintes definições de dados e a instrução XML GENERATE:

       01  Greeting. 
           05  msg  pic x(80)   value 'Hello, world!'. 
       01  NS       pic x(20)   value 'http://example'.
           . . .
           XML Generate Doc from Greeting
               namespace is NS

O documento XML resultante possui um espaço para nome padrão (http: // example), da seguinte maneira:

<Greeting xmlns="http://example"><msg>Hello, world!</msg></Greeting>

Se você não especificar um espaço para nome, os nomes dos elementos no documento XML gerado não estarão em nenhum espaço para nome.

Opcionalmente, você pode codificar a frase NAMESPACE-PREFIX para especificar um prefixo a ser aplicado à tag de início e fim de cada elemento no documento gerado.
Você pode especificar um prefixo apenas se tiver especificado um espaço para nome como descrito acima.

Quando a instrução XML GENERATE é executada, o valor do prefixo deve ser um nome XML válido, mas sem os dois pontos (:); consulte a referência relacionada abaixo sobre namespaces para obter detalhes.
O valor pode ter espaços à direita, que são removidos antes que o prefixo seja usado.

Especifique o prefixo do espaço para nome em um identificador ou literal da categoria nacional ou alfanumérico.

É recomendável que o prefixo seja curto, porque qualifica a tag de início e fim de cada elemento.

Por exemplo, considere as seguintes definições de dados e a instrução XML GENERATE:

       01  Greeting. 
           05  msg  pic x(80)   value 'Hello, world!'. 
       01  NS       pic x(20)   value 'http://example'. 
       01  NP       pic x(5)    value 'pre'. 
           . . .
           XML Generate Doc from Greeting
               namespace is NS
               namespace-prefix is NP

O documento XML resultante possui um espaço para nome explícito (http: // example) e o prefixo pré é aplicado à tag de início e fim dos elementos Greeting e msg, da seguinte maneira:

<pre:Greeting xmlns:pre="http://example"><pre:msg>Hello, world!</pre:msg></pre:Greeting>

Opcionalmente, você pode codificar a frase NAME para especificar nomes de atributos e elementos no documento XML gerado.
Os nomes de atributos e elementos devem ser literais alfanuméricos ou nacionais e devem ser nomes legais de acordo com o padrão XML 1.0.

Por exemplo, considere a seguinte estrutura de dados e a instrução XML GENERATE:

       01 Msg.
          02 Msg-Severity pic 9 value 1.
          02 Msg-Date     pic 9999/99/99 value "2012/04/12".
          02 Msg-Text     pic X(50) value "Sell everything!".
       01 Doc             pic X(500).
           XML Generate Doc from Msg
               With attributes
               Name of Msg          is  "Message" 
                       Msg-Severity is  "Severity"
                       Msg-Date     is  "Date"
                       Msg-Text     is  "Text"
           End-XML

O documento XML resultante é o seguinte:

<Message Severity="1" Date="2012/04/12" Text="Sell everything!"></Message>

Opcionalmente, você pode codificar a frase SUPPRESS para especificar se itens de dados individuais são gerados com base em se eles atendem ou não a determinados critérios.

Por exemplo, considere a seguinte estrutura de dados e a instrução XML GENERATE para suprimir espaços e zeros:

       01  G.
           02 SensitiveInfo.
              03 SSN         pic x(11) value '123-45-6789'.
              03 HomeAddress pic x(50) value '123 Main St, Anytown, USA'.   
           02 Aarray value spaces.
              03 A           pic AAA occurs 5.
           02 Barray value spaces.
              03 B           pic XXX occurs 5.
           02 Carray value zeros.
              03 C           pic 999 occurs 5.

           Move 'abc' to A(1)
           Move 123   to C(3)

           XML Generate Doc from G
               Suppress SensitiveInfo
                        every nonnumeric element when space
                        every numeric element when zero
           End-XML

O documento XML resultante é o seguinte:

<G>
   <Aarray><A>abc</A></Aarray>
   <Carray><C>123</C></Carray>
</G>

Opcionalmente, você pode usar a frase TYPE OF para especificar se itens de dados individuais serão expressos como atributos, elementos ou conteúdo.

Por exemplo, considere a seguinte estrutura de dados e a instrução XML GENERATE:

       01  Msg.
           02 Msg-Severity pic 9 value 1.
           02 Msg-Date     pic 9999/99/99 value "2012/04/12".
           02 Msg-Text     pic X(50) value "Sell everything!".
       01 Doc              pic X(500).

           XML Generate Doc from Msg
               With attributes
               Type of Msg-Severity is attribute
                       Msg-Date     is attribute
                       Msg-Text     is element
           End-XML

O documento XML resultante é o seguinte:

<Msg Msg-Severity="1" Msg-Date="2012/04/12"> 
       <Msg-Text>Sell everything!</Msg-Text></Msg>

Além disso, você pode especificar uma ou as seguintes frases para receber o controle após a geração do documento XML:

  • ON EXCEPTION, para receber o controle se ocorrer um erro durante a geração de XML
  • NOT ON EXCEPTION, para receber o controle se nenhum erro ocorrer

Você pode finalizar a instrução XML GENERATE com o terminador de escopo explícito END-XML.
Código END-XML para aninhar uma instrução XML GENERATE que possui a frase ON EXCEPTION ou NOT ON EXCEPTION em uma instrução condicional.

A geração de XML continua até que o registro de origem COBOL seja transformado em XML ou ocorra um erro.
Se ocorrer um erro, os resultados são os seguintes:

  • O registro especial XML-CODE contém um código de exceção diferente de zero.
  • O controle é passado para a frase ON EXCEPTION, se especificada, caso contrário, para o final da instrução XML GENERATE.

Se nenhum erro ocorrer durante a geração XML, o registro especial XML-CODE contém zero e o controle é passado para a frase NOT ON EXCEPTION, se especificado, ou para o final da instrução XML GENERATE, caso contrário.

Exemplo: Gerando XML


© Copyright IBM Corp.