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

identifier-1

A área de recebimento para o texto JSON 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 national
• Um item de grupo national

Quando o identifier-1 faz referência a um item do grupo national, 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 definido 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 ou ao identifier-3.

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

O texto JSON gerado é codificado em UTF-8 (CCSID 1208), a menos que o identifier-1 seja da categoria nacional; nesse caso, ele é codificado em UTF-16 big-Endian (CCSID 1200).
A conversão dos valores dos dados e literais da frase NAME é feita de acordo com a opção CODEPAGE do compilador em vigor para a compilação.
A conversão de nomes de dados originais é sempre feita usando o CCSID 1140.

O identifier-1 deve ser grande o suficiente para conter o texto JSON gerado.
Normalmente, ele deve ter de 2 a 3 vezes o tamanho do identifier-2, dependendo dos comprimentos dos nomes de dados no identifier-2.
Se o identifier-1 não for grande o suficiente, existe uma condição de exceção no final da instrução JSON GENERATE.
Se a frase COUNT for especificada, o identifier-3 conterá o número de unidades de codificação de caracteres que foram realmente geradas.

identifier-2

O grupo ou item de dados elementar a ser convertido para o formato JSON.

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 JSON GENERATE:

• Quaisquer itens de dados elementares não nomeados subordinados ou itens de dados FILLER elementares
• Quaisquer bytes de slack (folga) inseridos para itens SYNCHRONIZED
• Qualquer item de dados subordinado ao identifier-2 definido com a cláusula REDEFINES ou subordinado a esse item redefinidor
• Qualquer item de dados subordinado ao identifier-2 definido com a cláusula RENAMES
• Qualquer item de dados do grupo cujos itens de dados subordinados são todos 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 um USAGE diferente de POINTER, FUNCTION-POINTER, PROCEDURE-POINTER ou OBJECT REFERENCE.
• Deve haver pelo menos um desses itens de dados elementares.
• Cada nome de dados que não seja do FILLER deve ter um identifier exclusivo no identifier-2.

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(9). 
              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 podem ser especificados como identifier-2:

• STRUCT, dos quais os itens de dados subordinados STAT e IN-AREA seriam convertidos para o formato JSON.
  (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 (3) é 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.
  (O PTR seria ignorado se for definido com a cláusula REDEFINES.)
• NG-AREA2, porque itens de dados elementares subordinados têm o nome não exclusivo UNREFERENCED.

COUNT phrase

Se a frase COUNT for especificada, o identifier-3 conterá (após a execução bem-sucedida da instrução JSON GENERATE) a contagem de unidades de codificação de caracteres JSON geradas.
Se o identifier-1 (o receptor) for da categoria nacional, a contagem será em bytes duplos.
Caso contrário, 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 de imagens.

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

NAME phrase

Permite substituir os nomes JSON padrão derivados do identifier-2 ou seus itens de dados subordinados.

identifier-4
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 JSON GENERATE.
Para obter mais informações sobre o identifier-2, consulte a descrição do identifier-2 . Se o identifier-4 for especificado mais de uma vez na frase NAME, a última especificação será usada.

literal-1
Deve ser um literal alfanumérico ou nacional contendo o nome a ser gerado no texto JSON correspondente ao identifier-4.
Com o PTF para APAR PH18641 instalado, como alternativa, é possível especificar OMITTED para gerar um objeto JSON anônimo, cujo nome-pai de nível superior não é gerado.
Quando você especifica OMITTED, o identifier-4 deve fazer referência ao identifier-2.

SUPPRESS phrase

Permite identificar e excluir incondicionalmente itens subordinados ao identifier-2 e, assim, gerar seletivamente saída para a instrução JSON GENERATE.
Se a frase SUPPRESS for especificada, o identifier-1 deverá ser grande o suficiente para conter o documento JSON gerado antes de qualquer supressão.

identifier-5
Deve fazer referência a um item de dados subordinado ao identifier-2 e que não seja ignorado pela operação da instrução JSON GENERATE.
identifier-5 não pode ser um identificador de função e não pode ser modificado ou subscrito por referência.
Se o identifier-5 especificar um item de dados do grupo, esse item e todos os itens subordinados ao item do grupo serão excluídos.
Especificações duplicadas do identifier-5 são permitidas.

Quando a frase SUPPRESS é especificada, um item de grupo subordinado ao identifier-2 é excluído do texto JSON gerado se todos os itens elegíveis subordinados ao item de grupo forem excluídos.
O objeto mais externo que corresponde ao próprio identifier-2 é sempre gerado, mesmo se todos os itens subordinados ao identifier-2 forem excluídos.
Nesse caso, o valor gerado para o identifier-2 é um objeto vazio, da seguinte maneira:

           {"identifier-2":{}}

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

           02 B.
              03 C OCCURS 0 TO 2 DEPENDING J.
                 04 D PIC X.
           02 E PIC X. 

Se o objeto ODO j contiver o valor 2 e o grupo a for preenchido com todos os '_', a instrução JSON GENERATE x FROM a (sem a frase SUPPRESS) produzirá o seguinte texto JSON:

           {"a":{"b":{"c":[{"d":"_"},{"d":"_"}]},"e":"_"}}

O item de grupo b é eliminado da saída se uma frase SUPPRESS especificar qualquer um dos itens de dados b, c ou d, resultando no seguinte texto JSON:

           {"a":{"e":"_"}}

Como um exemplo de supressão recursiva completa, a instrução JSON GENERATE x FROM a SUPPRESS b e produz:

           {"a":{}}

JSON tem uma representação explícita de uma tabela sem elementos:

           {"table-name":[]}

que é, portanto, retido no texto JSON gerado, a menos que seja explicitamente suprimido.

Por exemplo, se o objeto ODO j contiver o valor 0 e, portanto, a tabela d não tiver ocorrências, e o grupo a for preenchido com todos os '_', a instrução JSON GENERATE x FROM a produzirá o seguinte texto JSON:

           {"a":{"b":{"c":[]},"e":"_"}}

Os componentes de uma tabela de grupo de ocorrência zero não contribuem com nenhum texto JSON para a saída.
Como resultado, uma frase SUPPRESS que especificou apenas d não teria efeito sobre essa saída gerada.

Suprimir os itens de dados b ou c, e e, que contribuem com texto JSON, tem o mesmo resultado que para ocorrências diferentes de zero da tabela c, ilustradas acima.

ON EXCEPTION phrase

Existe uma condição de exceção quando ocorre um erro durante a geração do documento JSON, por exemplo, se o identifier-1 não for grande o suficiente para conter o documento JSON gerado.
Nesse caso, a geração JSON para e o conteúdo do receptor, identifier-1, é indefinido.
Se a frase COUNT for especificada, o identifier-3 conterá o número de posições de caracteres que foram realmente geradas.

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 JSON GENERATE.
O registro especial JSON-CODE contém um código de exceção, conforme detalhado em exceções JSON GENERATE no Enterprise COBOL Programming Guide.

NOT ON EXCEPTION phrase

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

END-JSON phrase

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

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

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

END-JSON também pode ser usado com uma instrução JSON GENERATE ou JSON 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 - Instruções de escopo delimitadas.