PARSE JSON

PARSE JSON operand1 [ENCODED[IN] CODEPAGE operand2]
   

INTO

Opening bracket

 PATH operand3 [WITH SEPARATOR operand4] [NAME operand5] [VALUE operand6]

Closing bracket

  NAME operand5 [VALUE operand6]    
  VALUE operand6      
    [ GIVING operand7 [SUBCODE operand8]]
       statement...
END-PARSE [(r)] (structured mode only)
LOOP [(r)] (reporting mode only)

Dieser Abschnitt behandelt folgende Themen:

Eine Erläuterung der in dem Syntax-Diagramm verwendeten Symbole entnehmen Sie dem Abschnitt Syntax-Symbole.

Verwandtes Statement: REQUEST DOCUMENT.

Gehört zur Funktionsgruppe: Internet und Parsing.

Funktion PARSE JSON

Das Statement PARSE JSON ermöglicht es Ihnen, XML-Dokumente aus einem Natural-Programm zu parsen. Siehe auch Statements für den Internet- und JSON-XML-Zugriff im Leitfaden zur Programmierung.

Es empfiehlt sich, dynamische Variablen zu benutzen, wenn Sie das Statement PARSE JSON verwenden. Der Grund dafür ist, dass es unmöglich ist, die Länge einer statischen Variablen zu ermitteln. Der Einsatz von statischen Variablen könnte zum Abschneiden des Wertes führen, der in die Variable geschrieben werden soll.

Informationen zur Unicode-Unterstützung siehe PARSE JSON in der Unicode- und Codepage-Unterstützung-Dokumentation.

Markup

Die folgenden Markierungen werden in Pfadzeichenketten verwendet, um die verschiedenen Datenstrukturen und ihre Zustände in einem JSON-Dokument darzustellen:

Markierung JSON-Daten Position in der Pfad-Zeichenkette
< Anfang eines Objekts Am Anfang, am Ende oder zwischen Feldnamen
> Ende eines Objekts Am Ende
( Anfang eines Arrays Am Anfang, am Ende oder zwischen Feldnamen.
) Ende eines Arrays Am Ende
/ Separator

Anmerkung
Die Trennmarkierung können Sie im operand2 anpassen.

 
$ Geparste Daten - Datenzeichenkette Am Ende

Durch die Verwendung dieses zusätzlichen Markups im Pfadstring können Sie die Elemente des JSON-Dokuments in der Ausgabe leichter unterscheiden.

Zugehörige Systemvariablen

Die folgenden Natural-Systemvariablen werden für jedes ausgeführte PARSE JSON-Statement automatisch erstellt:

Durch Angabe der Notation (r) hinter *PARSE-TYPE, *PARSE-LEVEL und *PARSE-INDEX können Sie das Statement-Label bzw. die Statement-Nummer des Statements angeben, in dem das PARSE-Statement abgesetzt wurde. Wenn (r) nicht angegeben wird, stellt die betreffende Systemvariable die Systemvariable der JSON-Daten dar, die gerade in der zurzeit aktiven PARSE-Verarbeitungsschleife abgearbeitet werden.

Weitere Informationen über diese Systemvariablen finden Sie in der Systemvariablen-Dokumentation.

Syntax-Beschreibung PARSE JSON

Operanden-Definitionstabelle:

Operand Mögliche Struktur Mögliche Formate Referenzierung erlaubt Dynam. Definition
operand1 C S       A U B                     ja nein
operand2 C S       A                         ja nein
operand3   S       A U B                     ja ja
operand4 C  S       A U B                     ja nein
operand5   S       A U B                     ja ja
operand6   S       A U B                     ja ja
operand7   S             I4                   ja ja
operand8   S             I4                   ja ja

Syntax-Element-Beschreibung:

Syntax-Element Beschreibung
operand1
JSON-Dokument:

operand1 stellt das zu parsende JSON-Dokument dar. Das JSON-Dokument kann nicht geändert werden, während es vom Parser abgearbeitet wird. Wenn Sie versuchen, während des Parse-Vorgangs das JSON-Dokument zu ändern, hat die Änderung keine Auswirkung auf den PARSE-Vorgang.

ENCODED [IN] CODEPAGE operand2
ENCODED [IN] CODEPAGE:

operand2 bezeichnet die Codepage des in operand1 dargestellten Dokuments.

PATH operand3
Pfad:

operand3 stellt den Pfad der Daten im JSON-Dokument dar.

Der Pfad (PATH) enthält den Namen (NAME) des identifizierten JSON-Teils, die Namen aller übergeordneten Elemente (Parents), sowie den Typ des XML-Teils. Jeder Name in PATH wird durch das in operand4 angegebene, "Separator" genannte Zeichen abgetrennt.

Anmerkung
Die mit PATH angegebenen Informationen erleichtern den Aufbau einer Baumstruktur.

Siehe auch Beispiel 1 - Benutzung der PATH-Option.

SEPARATOR operand4
Separator:

operand4 stellt das Trennzeichen (Separator) dar, das zur Trennung von NAME und Mark-Up im PATH (operand3) verwendet wird. Das im PATH (operand3) verwendete Standard-Trennzeichen ist ein Schrägstrich (/).

Siehe auch Beispiel 2 - Benutzung der PATH-Option mit SEPARATOR.

NAME operand5
Datenelementname:

operand5 stellt den Namen (NAME) eines Datenelements in dem JSON-Dokument dar.

Wenn NAME keinen Wert hat, dann wird die damit verbundene dynamische Variable auf *LENGTH()=0 gesetzt, welche eine mit einem Leerzeichen gefüllte statische Variable ist.

Siehe auch Beispiel 3 - Benutzung der NAME-Option.

VALUE operand6
Datenelementinhalt:

operand6 stellt den Inhalt (VALUE) eines Datenelements in dem JSON-Dokument dar.

Wenn kein Wert vorhanden ist, dann wird die damit verbundene dynamische Variable auf *LENGTH()=0 gesetzt, welche eine mit einem Leerzeichen gefüllte statische Variable ist.

Siehe auch Beispiel 4 - Benutzung der VALUE-Option.

GIVING operand7
GIVING-Parameter:

Wenn der PARSE-Prozess zur Laufzeit auf einen Fehler stößt, enthält operand7 die 4-stellige Natural-Fehlernummer.

operand7 wird am Ende jeder Iteration eines Parse-Prozesses aktualisiert.

Wenn der Parameter GIVING angegeben ist, gibt operand7 0 zurück, wenn kein Fehler vorliegt. Tritt jedoch ein PARSE-Fehler auf, gibt operand7 eine entsprechende Natural-Fehlernummer zurück.

Wenn ein Fehler auftritt und der GIVING-Parameter angegeben ist, wird die PARSE-Schleife beendet und die Kontrolle an das auf END-PARSE folgende Statement zurückgegeben.

Wenn GIVING nicht gesetzt ist und ein Fehler auftritt, wird eine Natural-Fehlermeldung zurückgegeben und die Programmausführung unterbrochen, sofern nicht der ON ERROR- Statement-Block verwendet wird.

Siehe auch Beispiel 5 - Benutzung der GIVING- und SUBCODE-Klauseln.

SUBCODE operand8
SUBCODE-Parameter:

Wenn der PARSE-Prozess zur Laufzeit auf einen Fehler stößt, enthält operand8 den dreistelligen Reason Code, der mit der Fehlernummer in operand7 korrespondiert.

operand8 wird am Ende jeder Iteration eines Parse-Prozesses aktualisiert.

Wenn der SUBCODE-Parameter angegeben ist, gibt operand8 0 zurück, wenn kein Fehler vorliegt. Wenn jedoch ein PARSE-Fehler auftritt, gibt operand8 einen entsprechenden Reason Code zurück.

SUBCODE betrifft nur Reason Codes für den Fehler NAT8331. Wenn der SUBCODE-Operand zusammen mit GIVING angegeben wird und ein Fehler auftritt, wird die PARSE-Schleife abgebrochen und die Kontrolle an das auf END-PARSE folgende Statement zurückgegeben.

Anmerkung
Eine Liste aller Reason Codes für den Natural-Fehler NAT8331 finden Sie im Kapitel JSON-Related Reason Codes for Error NAT8331 in der Messages and Codes-Dokumentation.

Siehe auch Beispiel 5 - Benutzung der GIVING- und SUBCODE-Klauseln.

END-PARSE (r)
Ende des PARSE JSON-Statements:

Im Structured Mode muss das für Natural reservierte Schlüsselwort END-PARSE zum Beenden des PARSE JSON-Statements benutzt werden.

Im Structured Mode können Sie bei END-PARSE Labels oder Zeilennummern angeben.

Im Reporting Mode wird das Natural-Statement LOOP zum Beenden des PARSE JSON-Statements benutzt.

Im Reporting Mode können Sie bei LOOP Labels oder Zeilennummern angeben.

LOOP (r)

Beispiele PARSE JSON

Beispiel 1 - Benutzung der PATH-Option

Der folgende Code

** Example 'PAJSNEX1': PARSE JSON (with PATH and CODEPAGE)
**                                                                      
** Note: Definition of variable MYJSON needs TQMARK set to OFF.         
************************************************************************
OPTIONS TQMARK=OFF          /* Translate quotation mark                 
*
DEFINE DATA LOCAL                                                       
1 MYJSON      (A) DYNAMIC
1 MYCODEPAGE  (A) DYNAMIC                                               
1 MYPATH      (A) DYNAMIC                                               
END-DEFINE                                                              
*                                                                       
COMPRESS '{'                                                          
         '  "employee": {'                                              
         '    "@personnel-id": "30016315",'                             
         '    "full-name": {'                                           
         '      "first-name": "RICHARD",'                               
         '      "name": "FORDHAM"'                                      
         '    }'                                                        
         '  }'                                                          
         '}'                                                           
INTO MYJSON LEAVING NO                                                  
*                                                                       
MYCODEPAGE := *CODEPAGE                                                 
*                                                                       
PARSE JSON MYJSON ENCODED IN CODEPAGE MYCODEPAGE                        
                  INTO PATH MYPATH                                      
   PRINT MYPATH                                                         
END-PARSE                                                               
END

erzeugt die folgende Ausgabe:

<                                            
</employee                                   
</employee/<                                 
</employee/</@personnel-id                   
</employee/</@personnel-id/$                 
</employee/</full-name                       
</employee/</full-name/<                     
</employee/</full-name/</first-name          
</employee/</full-name/</first-name/$        
</employee/</full-name/</name                
</employee/</full-name/</name/$              
</employee/</full-name/>                     
</employee/>                                 
>

Beispiel 2 - Benutzung der PATH-Option mit SEPARATOR

Der folgende Code

** Example 'PAJSNEX2': PARSE JSON (with PATH and SEPARATOR)
**                                                                      
** Note: Definition of variable MYJSON needs TQMARK set to OFF.         
************************************************************************
OPTIONS TQMARK=OFF          /* Translate quotation mark                 
*
DEFINE DATA LOCAL                                                       
1 MYJSON      (A) DYNAMIC
1 MYCODEPAGE  (A) DYNAMIC                                               
1 MYPATH      (A) DYNAMIC
1 MYSEPARATOR (A1)                                               
END-DEFINE                                                              
*                                                                       
COMPRESS '{'                                                          
         '  "employee": {'                                              
         '    "@personnel-id": "30016315",'                             
         '    "full-name": {'                                           
         '      "first-name": "RICHARD",'                               
         '      "name": "FORDHAM"'                                      
         '    }'                                                        
         '  }'                                                          
         '}'                                                           
INTO MYJSON LEAVING NO                                                  
*                                                                       
MYCODEPAGE := *CODEPAGE
MYSEPARATOR := '*'                                                  
*                                                                       
PARSE JSON MYJSON ENCODED IN CODEPAGE MYCODEPAGE                        
                  INTO PATH MYPATH WITH SEPARATOR MYSEPARATOR           
   PRINT MYPATH                                                         
END-PARSE                                                               
END

erzeugt die folgende Ausgabe:

<                                    
<*employee                           
<*employee*<                         
<*employee*<*@personnel-id           
<*employee*<*@personnel-id*$         
<*employee*<*full-name               
<*employee*<*full-name*<             
<*employee*<*full-name*<*first-name  
<*employee*<*full-name*<*first-name*$
<*employee*<*full-name*<*name        
<*employee*<*full-name*<*name*$      
<*employee*<*full-name*>             
<*employee*>                         
>

Beispiel 3 - Benutzung der NAME-Option

Der folgende Code

** Example 'PAJSNEX3': PARSE JSON (with PATH and NAME)
**                                                                      
** Note: Definition of variable MYJSON needs TQMARK set to OFF.         
************************************************************************
OPTIONS TQMARK=OFF          /* Translate quotation mark                 
*
DEFINE DATA LOCAL                                                       
1 MYJSON      (A) DYNAMIC
1 MYPATH      (A) DYNAMIC                                               
1 MYNAME      (A) DYNAMIC                                               
END-DEFINE                                                              
*                                                                       
COMPRESS '{'                                                          
         '  "employee": {'                                              
         '    "@personnel-id": "30016315",'                             
         '    "full-name": {'                                           
         '      "first-name": "RICHARD",'                               
         '      "name": "FORDHAM"'                                      
         '    }'                                                        
         '  }'                                                          
         '}'                                                           
INTO MYJSON LEAVING NO                                                  
*                                                                       
PARSE JSON MYJSON INTO PATH MYPATH NAME MYNAME                          
   DISPLAY (AL=39) MYPATH MYNAME                                        
END-PARSE                                                               
END

erzeugt die folgende Ausgabe:

               MYPATH                                MYNAME
----------------------------------    -----------------------------------

<                                                                              
</employee                              employee                               
</employee/<                            employee                               
</employee/</@personnel-id              @personnel-id                          
</employee/</@personnel-id/$                                                   
</employee/</full-name                  full-name                              
</employee/</full-name/<                full-name                              
</employee/</full-name/</first-name     first-name                             
</employee/</full-name/</first-name/$                                          
</employee/</full-name/</name           name                                   
</employee/</full-name/</name/$                                                
</employee/</full-name/>                                                       
</employee/>                                                                   
>

Beispiel 4 - Benutzung der VALUE-Option

Der folgende Code

** Example 'PAJSNEX4': PARSE JSON (with PATH and VALUE)
**                                                                      
** Note: Definition of variable MYJSON needs TQMARK set to OFF.         
************************************************************************
OPTIONS TQMARK=OFF          /* Translate quotation mark                 
*
DEFINE DATA LOCAL                                                       
1 MYJSON      (A) DYNAMIC
1 MYPATH      (A) DYNAMIC                                               
1 MYVALUE     (A) DYNAMIC                                               
END-DEFINE                                                              
*                                                                       
COMPRESS '{'                                                          
         '  "employee": {'                                              
         '    "@personnel-id": "30016315",'                             
         '    "full-name": {'                                           
         '      "first-name": "RICHARD",'                               
         '      "name": "FORDHAM"'                                      
         '    }'                                                        
         '  }'                                                          
         '}'                                                           
INTO MYJSON LEAVING NO                                                  
*                                                                       
PARSE JSON MYJSON INTO PATH MYPATH VALUE MYVALUE                        
   DISPLAY (AL=39) MYPATH MYVALUE                                       
END-PARSE                                                               
END

erzeugt die folgende Ausgabe:

                MYPATH                                  MYVALUE                 
--------------------------------------- ---------------------------------------
                                                                               
<                                                                              
</employee                                                                     
</employee/<                                                                   
</employee/</@personnel-id                                                     
</employee/</@personnel-id/$            30016315                               
</employee/</full-name                                                         
</employee/</full-name/<                                                       
</employee/</full-name/</first-name                                            
</employee/</full-name/</first-name/$   RICHARD                                
</employee/</full-name/</name                                                  
</employee/</full-name/</name/$         FORDHAM                                
</employee/</full-name/>                                                       
</employee/>                                                                   
>

Beispiel 5 - Benutzung der GIVING- und SUBCODE-Klauseln

Das folgende Programm erzeugt einen Laufzeitfehler:

** Example 'PAJSNEX5': PARSE JSON (with GIVING and SUBCODE)
**                                                                      
** Note: Definition of variable MYJSON needs TQMARK set to OFF.         
************************************************************************
OPTIONS TQMARK=OFF          /* Translate quotation mark                 
*
DEFINE DATA LOCAL                                                       
1 MYJSON      (A) DYNAMIC
1 MYPATH      (A) DYNAMIC 
1 MYNAME      (A) DYNAMIC
1 MYVALUE     (A) DYNAMIC
1 MYGIVING    (I4)      
1 MYSUBCODE   (I4)                                                      
END-DEFINE                                                              
*
* Produce Natural runtime error with incorrect JSON document
*                                                                       
COMPRESS '{'                                                          
         '  "employee": {'                                              
         '    "@personnel-id": "30016315",'                             
         '    "full-name": {'                                           
         '      "first-name": "RICHARD",'                               
         '      "FORDHAM"'     /* here the key 'name' is missing        
         '    }'                                                        
         '  }'                                                          
         '}'                                                           
INTO MYJSON LEAVING NO                                                  
*                                                                  
PARSE JSON MYJSON INTO PATH MYPATH NAME MYNAME VALUE MYVALUE
                  GIVING MYGIVING SUBCODE MYSUBCODE                     
   WRITE (AL=39) MYPATH
END-PARSE                                                               
*
IF MYGIVING NE 0                                        
  WRITE / 'Error Number:'  MYGIVING 'Subcode:' MYSUBCODE
END-IF                                                  
END

Ausgabe des obigen Programms:

<                                            
</employee                                   
</employee/<
</employee/</@personnel-id                   
</employee/</@personnel-id/$                 
</employee/</full-name                       
</employee/</full-name/<                     
</employee/</full-name/</first-name          
</employee/</full-name/</first-name/$
</employee/</full-name/</FORDHAM 
                                
Error Number:        8331 Subcode:           5

On this page