COBOL - Comando XML GENERATE - www.cadcobol.com.br



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

COBOL - Comando XML GENERATE
Enterprise COBOL for z/OS, V6.3.0, Language Reference

A instrução XML GENERATE converte dados para o formato XML.



identifier-1
A área de recebimento para um documento XML gerado.
O identifier-1 deve fazer referência a um dos seguintes itens:
  • Um item de dados elementar da categoria alfanumérica
  • Um item de grupo alfanumérico
  • Um item de dados elementar da categoria nacional
  • Um item de grupo nacional

Quando o identifier-1 faz referência a um item do grupo nacional, o identifier-1 é processado como um item de dados elementar da categoria nacional.
Quando o identifier-1 faz referência a um item de grupo alfanumérico, o identifier-1 é tratado como se fosse um item de dados elementar da categoria alfanumérica.

O identifier-1 não deve ser descrito com a cláusula JUSTIFIED e não pode ser um identificador de função.
O identifier-1 pode ser subscrito ou modificado por referência.

o identifier-1 não deve se sobrepor ao identifier-2, identifier-3, página de código (se for um identificador), identifier-4 ou identifier-5.

O identifier-1 não deve ser um item de grupo de comprimento dinâmico ou um item elementar de comprimento dinâmico.

A saída XML gerada é codificada conforme descrito na documentação da frase ENCODING.

o identifier-1 deve fazer referência a um item de dados da categoria nacional ou a frase ENCODING deve especificar 1208, se alguma das seguintes afirmações for verdadeira:

  • A opção do compilador CODEPAGE especifica uma página de código EBCDIC DBCS.
  • identifier-4 ou identifier-5 referencia um item de dados da categoria nacional.
  • literal-4, literal-5 ou literal-6 é da categoria national.
  • O XML gerado inclui dados do identificador-2 para:
    • Qualquer item de dados da classe nacional ou da classe DBCS
    • Qualquer item de dados com um nome DBCS (ou seja, um item de dados cujo nome consiste em caracteres DBCS)
    • Qualquer item de dados da classe alfanumérica que contém caracteres DBCS

O identifier-1 deve ser grande o suficiente para conter o documento XML gerado.
Normalmente, ele deve ter de 5 a 10 vezes o tamanho do identifier-2, dependendo do comprimento do nome ou nome dos dados no identifier-2.
Se o identifier-1 não for grande o suficiente, existe uma condição de erro no final da instrução XML GENERATE.

identifier-2
vO grupo ou item de dados elementar a ser convertido para o formato XML.

Se o identifier-2 referenciar um item de grupo nacional, o identifier-2 será processado como um item de grupo.
Quando o identifier-2 inclui um item de grupo nacional subordinado, esse item subordinado é processado como um item de grupo.

O identifier-2 não pode ser um identificador de função ou ser modificado por referência, mas pode ser subscrito.

o identifier-2 não deve se sobrepor ao identifier-1 ou ao identifier-3.

O identifier-2 pode não ser um item de grupo de comprimento dinâmico ou um item elementar de comprimento dinâmico.

A entrada de descrição de dados para o identifier-2 não deve conter uma cláusula RENAMES.

Os seguintes itens de dados especificados pelo identifier-2 são ignorados pela instrução XML GENERATE:

  • Quaisquer itens de dados elementares não nomeados subordinados ou itens de dados FILLER elementares
  • Quaisquer bytes slack (de folga) inseridos para itens SYNCHRONIZED
  • Qualquer item de dados subordinado ao identifier-2 descrito com a cláusula REDEFINES ou subordinado a esse item redefinidor
  • Qualquer item de dados subordinado ao identifier-2 descrito com a cláusula RENAMES
  • Qualquer item de dados do grupo cujos itens de dados subordinados são ignorados

Todos os itens de dados especificados pelo identifier-2 que não são ignorados de acordo com as regras anteriores devem atender às seguintes condições:

  • Cada item de dados elementar deve ter classe alfabética, alfanumérica, numérica ou nacional ou ser um item de dados de índice.
    (Ou seja, nenhum item de dados elementar pode ser descrito com a frase USAGE POINTER, USAGE FUNCTION POINTER, USAGE PROCEDURE POINTER ou USAGE OBJECT REFERENCE.)
  • Deve haver pelo menos um desses itens de dados elementares.
  • Cada nome de dados que não seja do FILLER deve ser exclusivo em qualquer item de dados do grupo imediatamente subordinado.
  • Quaisquer nomes de dados DBCS, quando convertidos em Unicode, devem ser legais como nomes na especificação XML, versão 1.0.
    Para detalhes sobre a especificação XML, consulte XML specification.

Por exemplo, considere a seguinte declaração de dados:

       01  STRUCT.
           02 STAT                                PIC X(004).
           02 IN-AREA                             PIC X(100).
           02 OK-AREA    REDEFINES IN-AREA.
              03 FLAGS                            PIC X(001).
              03                                  PIC X(003).
              03 COUNTER USAGE COMP-5             PIC S9(09).
              03 ASFNPTR REDEFINES COUNTER USAGE FUNCTION-POINTER.
              03 UNREFERENCED                     PIC X(092).
           02 NG-AREA1   REDEFINES IN-AREA.
              03 FLAGS                            PIC X(001).
              03                                  PIC X(003).
              03 PTR USAGE POINTER.
              03 ASNUM   REDEFINES PTR USAGE COMP-5 PIC S9(09).
              03                                  PIC X(092).
           02 NG-AREA2   REDEFINES IN-AREA.
              03 FN-CODE                          PIC X(001).
              03 UNREFERENCED                     PIC X(003).
              03 QTYONHAND USAGE BINARY           PIC 9(005).
              03 DESC USAGE NATIONAL              PIC N(040).
              03 UNREFERENCED                     PIC X(012).

Os seguintes itens de dados do exemplo anterior podem ser especificados como identifier-2:

  • STRUCT, cujos itens de dados subordinados STAT e IN-AREA seriam convertidos para o formato XML.
    (OK-AREA, NG-AREA1 e NG-AREA2 são ignorados porque especificam a cláusula REDEFINES.)
  • OK-AREA, dos quais os itens de dados subordinados FLAGS, COUNTER e UNREFERENCED seriam convertidos.
    (O item cuja entrada de descrição de dados especifica 03 PIC X(003) é ignorado porque é um item de dados FILLER elementar.
    ASFNPTR é ignorado porque especifica a cláusula REDEFINES.)
  • Qualquer um dos itens de dados elementares subordinados a STRUCT, exceto:
    • ASFNPTR ou PTR (uso não permitido)
    • UNREFERENCED OF NG-AREA2 (nomes não exclusivos para itens de dados que são elegíveis de outra forma)
    • Qualquer item de dados do FILLER

Os seguintes itens de dados não podem ser especificados como identifier-2:

  • NG-AREA1, porque o item de dados subordinado PTR especifica USAGE POINTER, mas não especifica a cláusula REDEFINES.
    (PTR seria ignorado se especificasse a cláusula REDEFINES.)
  • NG-AREA2, porque itens de dados elementares subordinados têm o nome não exclusivo UNREFERENCED.
COUNT IN phrase
Se a frase COUNT IN for especificada, o identifier-3 conterá (após a execução da instrução XML GENERATE) a contagem de unidades de codificação de caracteres XML geradas.
Se o identifier-1 (o receptor) 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.
identifier-3
O campo de contagem de dados.
Deve ser um item de dados inteiro definido sem o símbolo P na sequência das PICTURE.

o identifier-3 não deve se sobrepor ao identifier-1, identifier-2, página de código (se for um identificador), identifier-4 ou identifier-5.

ENCODING phrase
A frase ENCODING, se especificada, determina a codificação do documento XML gerado.
codepage
Deve ser um item de dados inteiro não assinado ou um literal inteiro não assinado e deve representar um identificador de conjunto de caracteres codificado válido (CCSID).
É necessário identificar uma das páginas de código suportadas para o processamento de XML COBOL, conforme descrito em The encoding of XML documents in the Enterprise COBOL Programming Guide.

Se o identifier-1 referenciar um item de dados da categoria nacional, a página de código deverá especificar 1200, o CCSID para Unicode UTF-16.

Se o identificador-1 referenciar um item de dados da categoria alfanumérica, a página de código deverá especificar 1208 ou o CCSID de uma página de código EBCDIC suportada, conforme listado em The encoding of XML documents no Enterprise COBOL Programming Guide.

Se a página de códigos for um identificador, não deverá se sobrepor ao identifier-1 ou ao identifier-3.

Se a frase ENCODING for omitida e o identifier-1 for da categoria nacional, a codificação do documento será Unicode UTF-16, CCSID 1200.

Se a frase ENCODING for omitida e o identifier-1 for da categoria alfanumérica, o documento XML será codificado usando a página de códigos especificada pela opção do compilador CODEPAGE em vigor quando o código fonte foi compilado.

Se a frase ENCODING for omitida e o identifier-1 for da categoria alfanumérica, o documento XML será codificado usando a página de códigos especificada pela variável de ambiente EBCDIC_CODEPAGE em vigor quando o código fonte foi compilado.

XML-DECLARATION phrase
Se a frase XML-DECLARATION for especificada, o documento XML gerado começará com uma declaração XML que inclui as informações da versão XML e uma declaração de codificação.

Se o identifier-1 for da categoria nacional, a declaração de codificação terá o valor UTF-16 (codificação = "UTF-16").

Se o identifier-1 for da categoria alfanumérica, a declaração de codificação será 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.
Veja a descrição da frase ENCODING para mais detalhes.

Para obter um exemplo do efeito da codificação da frase XML-DECLARATION, consulte Generating XML output no Enterprise COBOL Programming Guide.

Se a frase XML-DECLARATION for omitida, o documento XML gerado não incluirá uma declaração XML.

ATTRIBUTES phrase
Se a frase ATTRIBUTES for especificada, cada item elegível incluído no documento XML gerado será expresso como um atributo do elemento XML que corresponde ao item de dados imediatamente subordinado a esse item elegível, e não como um elemento filho do elemento XML.
Para ser elegível, um item de dados deve ser elementar, deve ter um nome diferente de FILLER e não deve especificar uma cláusula OCCURS em sua entrada de descrição de dados.

Se a frase TYPE for especificada para identificadores específicos, a frase TYPE terá precedência para esses identificadores sobre a frase WITH ATTRIBUTES.

Para um exemplo do efeito da frase ATTRIBUTES, consulte Generating XML output no Enterprise COBOL Programming Guide.

NAMESPACE and NAMESPACE-PREFIX phrases
Use a frase NAMESPACE para identificar um espaço para nome para o documento XML gerado.
Se a frase NAMESPACE não for especificada ou se o identifier-4 tiver comprimento zero ou contiver todos os espaços, os nomes dos elementos dos documentos XML produzidos pela instrução XML GENERATE não estarão em nenhum espaço de nomes.

Use a frase NAMESPACE-PREFIX para qualificar a tag inicial e final de cada elemento no documento XML gerado com um prefixo.

Se a frase NAMESPACE-PREFIX não for especificada ou se o identifier-5 tiver comprimento zero ou contiver todos os espaços, o espaço para nome especificado pela frase NAMESPACE especificará o espaço para nome padrão do documento.
Nesse caso, o espaço para nome declarado no elemento raiz se aplica por padrão a cada nome de elemento no documento, incluindo o nome do elemento raiz. (As declarações de espaço para nome padrão não se aplicam diretamente aos nomes dos atributos.)

Se a frase NAMESPACE-PREFIX for especificada e o identifier-5 não tiver comprimento zero e não contiver todos os espaços, a tag de início e fim de cada elemento no documento gerado será qualificada com o prefixo especificado.
O prefixo deve, portanto, preferencialmente ser curto.
Quando a instrução XML GENERATE é executada, o prefixo deve ser um nome XML válido, mas sem os dois pontos (:), conforme definido em Namespaces in XML 1.0.
O prefixo pode ter espaços à direita, que são removidos antes do uso.

identifier-4, literal-4; identifier-5, literal-5
identifier-4, literal-4: o identificador do namespace, que deve ser um URI (Uniform Resource Identifier) válido, conforme definido em Uniform Resource Identifier (URI): Generic Syntax.

identifier-5, literal-5: o prefixo do espaço para nome, que serve como um alias para o identificador do espaço para nome.

identifier-4 e identifier-5 devem fazer referência a itens de dados da categoria alfanumérica ou nacional.

o identifier-4 e o identifier-5 não devem se sobrepor ao identifier-1 ou ao identifier-3.

literal-4 e literal-5 devem ser da categoria alfanuméricos ou nacionais e não devem ser constantes figurativas.

Para obter detalhes completos sobre espaços para nome, consulte Namespaces in XML 1.0.

Para exemplos que mostram o uso das frases NAMESPACE e NAMESPACE-PREFIX, consulte Generating XML output no Enterprise COBOL Programming Guide.

NAME phrase
Permite que você forneça nomes de elemento e atributo.

identifier-6 deve fazer referência ao identifier-2 ou a um de seus itens de dados subordinados.
Não pode ser um identificador de função e não pode ser referência modificada ou subscrita.
Ele não deve especificar nenhum item de dados que seja ignorado pela instrução XML GENERATE.
Para obter mais informações sobre o identificador-2, consulte a descrição do identifier-2.
Se o identifier-6 for especificado mais de uma vez na frase NAME, a última especificação será usada.

literal-6 deve ser um literal alfanumérico ou nacional que contenha o nome do atributo ou do elemento a ser gerado no documento XML correspondente ao identifier-6.
Deve ser um nome local XML válido.
Se o literal-6 for um literal nacional, o identifier-1 deve fazer referência a um item de dados da categoria nacional ou a frase de codificação deve especificar 1208.

TYPE phrase
Permite controlar a geração de atributos e elementos.

identifier-7deve fazer referência a um item de dados elementar subordinado ao identifier-2.
Não pode ser um identificador de função e não pode ser referência modificada ou subscrita.
Ele não deve especificar nenhum item de dados que seja ignorado pela instrução XML GENERATE.
Para obter mais informações sobre o identifier-2, consulte a of identifier-2.
Se o identifier-7 for especificado mais de uma vez na frase TYPE, a última especificação será usada.
  • Se a instrução XML GENERATE também incluir uma frase WITH ATTRIBUTES, a frase TYPE terá precedência para o identifier-7.
  • Quando ATTRIBUTE é especificado, o identifier-7 deve ser elegível para ser um atributo XML. identifier
    O identifier-7 é expresso no XML gerado como um atributo do elemento XML imediatamente superordenado ao identifier-7, e não como um elemento filho.
  • Quando ELEMENT é especificado, o identifier-7 é expresso no XML gerado como um elemento.
    O nome do elemento XML é derivado do identifier-7 e o conteúdo do caractere do elemento é derivado do conteúdo convertido do identifier-7, conforme descrito em Operation of XML GENERATE.
  • Quando CONTENT é especificado, o identifier-7 é expresso no XML gerado como conteúdo de caractere do elemento XML que corresponde ao item de dados imediatamente subordinado ao identifier-7.
    O valor do conteúdo do caractere do elemento é derivado do conteúdo convertido do identificador-7, conforme descrito em Operation of XML GENERATE.
    Quando CONTENT é especificado para vários identificadores, todos correspondentes ao mesmo identificador super ordenado, as múltiplas contribuições ao conteúdo do caractere do elemento são concatenadas
SUPPRESS phrase
Permite identificar e suprimir incondicionalmente itens subordinados ao identifier-2 e gerar seletivamente saída para a instrução XML GENERATE.
Se a frase SUPPRESS for especificada, o identifier-1 deverá ser grande o suficiente para conter o documento XML gerado antes de qualquer supressão.

Com a frase de supressão genérica, os itens elementares subordinados ao identifier-2 que não são ignorados pelas operações XML GENERATE são identificados genericamente para possível supressão.
Itens da classe numérica, se a palavra-chave NUMERIC for especificada, ou itens que não sejam da classe numérica, se a palavra-chave NONNUMERIC for especificada, ou ambos, poderão ser suprimidos.
Se a palavra-chave ATTRIBUTE for especificada, apenas itens que seriam expressos no documento XML gerado como um atributo XML serão identificados para possível supressão.
Se a palavra-chave ELEMENT for especificada, apenas itens que seriam expressos no documento XML gerado como um elemento XML serão identificados para possível supressão.
Se a palavra-chave CONTENT for especificada, apenas os itens que seriam expressos no documento XML gerado como conteúdo de caractere do elemento XML correspondente ao item de dados superordenado ao item de dados CONTENT serão identificados para possível supressão.

Se várias frases de supressão genérica forem especificadas, o efeito será cumulativo.

identifier-8identifica explicitamente itens para possível supressão.
Se a frase WHEN for especificada, o identifier-8 deverá fazer referência a um item de dados elementar subordinado ao identifier-2 e que não será ignorado pelas operações XML GENERATE.
O identificador-8 não pode ser um identificador de função e não pode ser modificado ou subscrito por referência. Esse item de dados do grupo e todos os itens de dados subordinados ao item do grupo são suprimidos.
Se o identificador-8 for especificado mais de uma vez na frase SUPPRESS, a última especificação será usada.
A especificação de supressão explícita para o identificador-8 substitui a especificação de supressão implícita em qualquer frase de supressão genérica, se o identifier-8 também for um dos identificadores identificados genericamente.

Se o identifier-8 for especificado, as seguintes regras se aplicarão a ele:

  • Se ZERO, ZEROES ou ZEROS for especificado na frase WHEN, o identifier-8 não deverá ser USAGE DISPLAY-1.
  • Se SPACE ou SPACES for especificado na frase WHEN, o identifier-8 deverá ser USAGE DISPLAY, DISPLAY-1 ou NATIONAL.
    Se o identifier-8 for um item decimal nacional ou em zonas, ele deverá ser um número inteiro.
  • Se LOW-VALUE, LOW-VALUES, HIGH VALUE ou HIGH VALUES for especificado na frase WHEN, o identifier-8 deverá ser USAGE DISPLAY ou NATIONAL.
    Se o identifier-8 for um item decimal nacional ou em zonas, ele deverá ser um número inteiro.

Se a frase de supressão genérica for especificada, os itens de dados serão selecionados para supressão em potencial de acordo com as seguintes regras:

  • Se ZERO, ZEROES ou ZEROS for especificado na frase WHEN, todos os itens de dados, exceto aqueles definidos com USAGE DISPLAY-1, serão selecionados.
  • Se SPACE ou SPACES for especificado na frase WHEN, os itens de dados de USAGE DISPLAY, DISPLAY-1 ou NATIONAL serão selecionados.
    Para itens decimais zoneados ou nacionais, apenas números inteiros são selecionados.
  • Se LOW-VALUE, LOW-VALUES, HIGH VALUE ou HIGH VALUES for especificado na frase WHEN, os itens de dados de USAGE DISPLAY ou NATIONAL serão selecionados.
    Para itens decimais zoneados ou nacionais, apenas números inteiros são selecionados.
A operação de comparação que determina se um item será suprimido é uma condição de relação, conforme mostrado na tabela Comparisons involving figurative constants.
Ou seja, a comparação é uma comparação numérica se o valor especificado for ZERO, ZEROS ou ZEROES e o item for da classe numérica. Para todos os outros casos, a operação de comparação é uma comparação alfanumérica, DBCS ou nacional, dependendo se o item é de uso DISPLAY, DISPLAY-1 ou NATIONAL, respectivamente.

Quando a frase SUPPRESS é especificada, um item de grupo subordinado ao identifier-2 é suprimido no documento XML gerado se todos os itens elegíveis subordinados ao item de grupo forem suprimidos ou se, após suprimir quaisquer itens subordinados, o XML correspondente ao item de grupo seria um elemento vazio sem atributos.
O elemento raiz é sempre gerado, mesmo que todos os itens subordinados ao identifier-2 sejam suprimidos.

ON EXCEPTION phrase
Uma condição de exceção existe quando ocorre um erro durante a geração do documento XML, por exemplo, se o identifier-1 não for grande o suficiente para conter o documento XML gerado.
Nesse caso, a geração de XML é interrompida e o conteúdo do receptor, identifier-1, é indefinido.
Se a frase COUNT IN for especificada, o identificador-3 conterá o número de posições de caracteres que foram geradas, que podem variar de 0 ao comprimento do identifier-1.

Se a frase ON EXCEPTION for especificada, o controle será transferido para imperative-statement-1.
Se a frase ON EXCEPTION não for especificada, a frase NOT ON EXCEPTION, se houver, será ignorada e o controle será transferido para o final da instrução XML GENERATE.
O registro especial XML-CODE contém um código de exceção, conforme detalhado no Handling XML GENERATE exceptions Enterprise COBOL Programming Guide.

NOT ON EXCEPTION phrase
Se uma condição de exceção não ocorrer durante a geração do documento XML, o controle será passado para imperative-statement-2, se especificado, caso contrário, ao final da instrução XML GENERATE.
A frase ON EXCEPTION, se especificada, é ignorada.
O registro especial XML-CODE contém zero após a execução da instrução XML GENERATE.

END-XML phrase
Esse terminador de escopo explícito delimita o escopo das instruções XML GENERATE ou XML PARSE.
END-XML permite que uma instrução XML GENERATE ou XML PARSE condicional (ou seja, uma instrução XML GENERATE ou XML PARSE que especifique a frase ON EXCEPTION ou NOT ON EXCEPTION) seja aninhada em outra instrução condicional.

O escopo de uma instrução XML GENERATE ou XML PARSE condicional pode ser encerrado por:

  • Uma frase END-XML no mesmo nível de aninhamento
  • Um período separador

END-XML também pode ser usado com uma instrução XML GENERATE ou XML PARSE que não especifica a frase ON EXCEPTION ou NOT ON EXCEPTION.

Para obter mais informações sobre terminadores de escopo explícitos, consulte Delimited scope statements.



© Copyright IBM Corp.