COBOL - Comando XML GENERATE - www.cadcobol.com.br
A instrução XML GENERATE converte dados para o formato XML.
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:
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.
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:
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:
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:
Os seguintes itens de dados não podem ser especificados como identifier-2:
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.
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.
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.
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.
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-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.
Se o identifier-8 for especificado, as seguintes regras se aplicarão a ele:
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 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.
O escopo de uma instrução XML GENERATE ou XML PARSE condicional pode ser encerrado por:
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.