A instrução JSON PARSE converte o texto JSON em formatos de dados COBOL.

Nota: Para usar a instrução JSON PARSE, a opção do compilador CODEPAGE deve especificar um EBCDIC CCSID de byte único.

identifier-1

O item de dados que contém o texto JSON.

Um item de dados elementar da categoria alfanumérica

Um item de grupo alfanumérico

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-21.

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 é assumido como codificado em UTF-8 (CCSID 1208).

Todas as seqüências de caracteres de escape definidas na especificação JSON são aceitas.
Também é aceita a sequência “\ x”, gerada por JSON GENERATE, e que representa o caractere de controle EBCDIC NL (nova linha) X'15 ', equivalente ao caractere de controle Unicode NEXT LINE, NX'0085'.

A conversão de Unicode dos nomes e valores JSON é feita de acordo com a opção CODEPAGE do compilador em vigor para a compilação.

identifier-2

O grupo ou item de dados elementar a ser preenchido a partir do texto 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.

O identifier-2 e seus itens de dados subordinados não devem conter a cláusula UNBOUNDED.

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 PARSE:

• 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 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 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 DISPLAY-1, FUNCTION-POINTER, INDEX, OBJECT REFERENCE, POINTER ou PROCEDURE-POINTER.
• Deve haver pelo menos um desses itens de dados elementares.
• Cada nome de dados que não seja do FILLER deve ter um identificador exclusivo no identifier-2.
• Se (a declaração de dados do) identifier-2 ou qualquer item de dados subordinado contiver a cláusula OCCURS DEPENDING ON, o (s) objeto (s) da (s) cláusula (s) OCCURS DEPENDING ON não deverá estar subordinado ao identifier-2.
  Portanto, quaisquer objetos das cláusulas OCCURS DEPENDING ON não serão atualizados pela instrução JSON PARSE.

WITH DETAIL phrase

A frase WITH DETAIL faz com que a instrução JSON PARSE emita mensagens de tempo de execução para quaisquer condições de exceção e exceção encontradas durante a análise.

NAME phrase

Com o objetivo de corresponder o nome de um JSON name/value pair, a frase NAME permite alterar efetivamente o nome de um item de dados para o literal especificado durante a execução da instrução JSON PARSE.

OMITTED pode ser especificado para analisar um objeto JSON anônimo, cujo nome pai principal não está especificado.

O identifier-3 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 PARSE.
Para obter mais informações sobre o identifier-2, consulte a descrição do identifier-2.
Se o identifier-3 for especificado mais de uma vez na frase NAME, a última especificação será usada.
Se OMITTED for especificado, o identifier-3 deverá se referir ao identifier-2.

O literal-1 deve ser um literal alfanumérico ou nacional contendo o nome JSON para ser associado ao identifier-3.

A frase NAME agregada não deve resultar em uma especificação de nome ambígua.
Por exemplo, dadas as seguintes declarações de dados e texto JSON:

       01  G.
           05 H.
              10 A   PIC X(010).
              10 3_  PIC 9(001.
              10 C-C PIC X(010).

           '{"g": {"H": {"A": "Eh?", "3_": 5, "C-C": "See"}}}'.

Em seguida, se permitido, especificando a frase NAME como:

           NAME OF A IS 'C-C'

resultaria em nenhum item de dados recebendo o valor "Eh?" e em uma ambiguidade sobre qual item de dados deveria receber o valor "See", definindo efetivamente a declaração do grupo G como:

        01  G.
            05 H.
               10 C-C PIC X(010).
               10 3_  PIC 9(001).
               10 C-C PIC X(010).

o que seria ilegal se referenciado como identifier-2 em uma instrução JSON PARSE.
Especificando a frase NAME como:

           NAME OF A IS 'C-C' C-C is 'A'

não é ambíguo e simplesmente trocaria as atribuições pelos itens de dados A e CC.

Dada a seguinte declaração de dados e texto JSON:

   01. top
   02. A pic x(20).
   03. B pic x(20).

   '{"A":"value1","B":"value2"}'

Este objeto JSON pode ser analisado usando OMITTED:

           NAME top IS OMITTED

If Se OMITTED não for especificado, o objeto JSON precisará conter um nome pai chamado "top":

           '{"top":{"A":"value1","B":"value2"}}'

SUPPRESS phrase

Permite identificar e excluir incondicionalmente itens subordinados ao identifier-2 da atribuição pela instrução JSON PARSE.

O identifier-4 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 PARSE.
O identifier-4 não pode ser um identificador de função e não pode ser modificado ou subscrito por referência.
O identifier-4 pode fazer referência a uma tabela inteira.

Se o identifier-4 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-4 são permitidas.

Um item de dados especificado na frase SUPPRESS é suprimido, mesmo que o mesmo item de dados também seja especificado na frase NAME.

ON EXCEPTION phrase

Existe uma condição de exceção quando ocorre um erro durante a análise do texto JSON, por exemplo, um valor JSON mal formado ou durante a designação de um valor para um item de dados COBOL.
Nesses casos, a análise JSON para e o receptor, identifier-2, pode ser parcialmente modificado.

O registro especial JSON-CODE contém um código de exceção, conforme detalhado nas condições JSON PARSE, códigos associados e mensagens de tempo de execução no Enterprise COBOL Programming Guide.
O registro especial JSON-STATUS também pode conter um valor de status diferente de zero, representando uma ou mais condições de não exceção que ocorreram antes da condição de exceção.
Para mais detalhes, consulte Operação do JSON PARSE.

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 PARSE.

NOT ON EXCEPTION phrase

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

Condições sem exceção que podem ocorrer durante a execução da instrução JSON PARSE podem resultar no registro especial JSON-STATUS sendo definido como um valor de status diferente de zero e no identificador identifier-2 sendo parcialmente modificado.

Para obter mais detalhes, consulte “Operação das condições JSON PARSE” e JSON PARSE e códigos e mensagens de tempo de execução associados no Enterprise COBOL Programming Guide.

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.