READ-JSON( ) method

Reads a JSON string into a ProDataSet, a temp-table, or a temp-table buffer object.

Syntax
READ-JSON ( `source-type`, { `file` \| `memptr` \| `handle` \| `longchar` } [, `read-mode`] )

A CHARACTER expression that specifies the source JSON string type. Valid values are “FILE”, “MEMPTR”, “HANDLE”, and “LONGCHAR”.

A CHARACTER expression that specifies the name of a file. You can specify an absolute pathname or one relative to the current working directory. The AVM verifies that the file exists and is accessible.

A MEMPTR variable that contains the JSON string in memory. The size of the MEMPTR variable must match the size of the JSON string.

A HANDLE variable that specifies the WEB-CONTEXT system handle.

This method reads a JSON string from the WebSpeed Transaction Server. The method verifies that the JSON string was posted to the WebSpeed Transaction Server by checking that the handle’s IS-JSON attribute is YES. The method also verifies that ABL is running in a WebSpeed environment.

A LONGCHAR variable that contains the JSON string in memory.

A CHARACTER expression that specifies the mode in which this method reads data from the JSON string into a temp-table or a ProDataSet member buffer. The expression must evaluate to “APPEND”, “EMPTY”, “MERGE”, or “REPLACE”. The default value is "MERGE".

Table 95 lists the READ-JSON( ) method modes for reading data.

Table 95: READ-JSON( ) method read modes
When the mode is . . .	The READ-JSON( ) method . . .
APPEND	Reads data from the JSON string into the ProDataSet or temp-table object by adding new records to the existing records, without performing any record comparisons. If a record from the JSON string exists in the object (that is, it results in a duplicate unique key conflict), the method generates an error message and returns FALSE.
EMPTY	Empties the contents of the ProDataSet or temp-table object before reading in data from the JSON string.
MERGE	Reads data from the JSON string into the ProDataSet or temp-table object by merging new records with existing records in the table. If a record from the JSON string exists in the object (that is, it results in a duplicate unique key conflict), the method does not replace the existing record. If the record from the JSON string does not exist in the object, the method creates a new record.
REPLACE	Reads data from the JSON string into the ProDataSet or temp-table object by merging new records with existing records in the table. If the record from the JSON string exists in the object (that is, it results in a duplicate unique key conflict), the method replaces the existing record with the new record. If the record from the JSON string does not exist in the object, the method creates a new record.

For a dynamic ProDataSet or temp-table that is in the CLEAR state, the AVM infers the object’s schema from the data in the JSON value. If a dynamic temp-table is not in the PREPARED or CLEAR state, the method generates an error and returns FALSE. For more information about inferring schema from a JSON string, see OpenEdge Development: Working with JSON.

For a static ProDataSet or temp-table, the serialize name or object name must match the name found in the JSON string. If the names do not match, the AVM generates an error message and the method returns FALSE. The AVM ignores any columns in the JSON string that do not map to temp-table columns. If you use the SERIALIZE-NAME option in the DEFINE DATASET or DEFINE TEMP-TABLE statement, the AVM uses that name for matching, rather than the ABL object name.

The following code example creates a dynamic ProDataSet object from an empty ProDataSet handle, creates the objects schema by inference from the specified JSON string, and populates the temp-tables with records from the specified JSON document:

DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. DEFINE VARIABLE cReadMode AS CHARACTER NO-UNDO. DEFINE VARIABLE cFile AS CHARACTER NO-UNDO. DEFINE VARIABLE lRetOK AS LOGICAL NO-UNDO. DEFINE VARIABLE hDSet AS HANDLE NO-UNDO. CREATE DATASET hDSet. ASSIGN cSourceType = "file" cFile = "dset.json" cReadMode = "empty" lRetOK = hDSet:READ-JSON(cSourceType, cFile, cReadMode).

DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. 
DEFINE VARIABLE cReadMode   AS CHARACTER NO-UNDO. 
DEFINE VARIABLE cFile       AS CHARACTER NO-UNDO. 
DEFINE VARIABLE lRetOK      AS LOGICAL   NO-UNDO. 
DEFINE VARIABLE hDSet       AS HANDLE    NO-UNDO. 
CREATE DATASET hDSet. 
ASSIGN 
  cSourceType = "file" 
  cFile       = "dset.json"  
  cReadMode   = "empty" 
lRetOK = hDSet:READ-JSON(cSourceType, cFile, cReadMode).

The following code example creates a dynamic temp-table object from an empty temp-table handle, creates the object's schema by inference from the specified JSON string, and populates the temp-table with records from the same string:

DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. DEFINE VARIABLE cReadMode AS CHARACTER NO-UNDO. DEFINE VARIABLE cFile AS CHARACTER NO-UNDO. DEFINE VARIABLE lRetOK AS LOGICAL NO-UNDO. DEFINE VARIABLE httCust AS HANDLE NO-UNDO. CREATE TEMP-TABLE httCust. ASSIGN cSourceType = "file" cFile = "ttcust.json" cReadMode = "empty" lRetOK = httCust:READ-JSON(cSourceType, cFile, cReadMode).

DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. 
DEFINE VARIABLE cReadMode   AS CHARACTER NO-UNDO. 
DEFINE VARIABLE cFile       AS CHARACTER NO-UNDO. 
DEFINE VARIABLE lRetOK      AS LOGICAL   NO-UNDO. 
DEFINE VARIABLE httCust     AS HANDLE    NO-UNDO. 
CREATE TEMP-TABLE httCust. 
ASSIGN 
  cSourceType = "file" 
  cFile       = "ttcust.json"  
  cReadMode   = "empty" 
lRetOK = httCust:READ-JSON(cSourceType, cFile, cReadMode).