Reads a specified JSON string, Progress.Json.ObjectModel.JsonArray object, or Progress.Json.ObjectModel.JsonObject object into a corresponding ProDataSet, a temp-table, or a temp-table buffer object.

Return type: LOGICAL

Applies to: Buffer object handle, ProDataSet object handle, Temp-table object handle

Syntax

READ-JSON ( source-type 
  , { file | memptr | handle | longchar | JsonArray | JsonObject } 
  [ , read-mode ] )
source-type
A CHARACTER expression that specifies the source JSON string type. Valid values are "FILE", "MEMPTR", "HANDLE", "LONGCHAR", "JsonArray", and "JsonObject".
All values except "JsonArray" and "JsonObject" specify a source for a JSON string.
"JsonArray" is only a valid source-type for invoking READ-JSON( ) on a temp-table or buffer object handle. If set to "JsonArray" for a ProDataSet object handle, the READ-JSON( ) method generates an error message and returns a value of FALSE.
file
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.
memptr
A MEMPTR variable that contains the JSON string in memory. The size of the MEMPTR variable must match the size of the JSON string.
handle
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.

longchar
A LONGCHAR variable that contains the JSON string in memory.
JsonArray
A reference to a Progress.Json.ObjectModel.JsonArray object.
This JsonArray object must fit one of the valid patterns for a temp-table object. If any part of the JsonArray object does not fit one of the accepted patterns, the READ-JSON( ) method generates an error message and returns FALSE. If the JsonArray object fits an accepted pattern, but contains fields whose names do not match the existing temp-table schema, the mismatched fields are ignored.
JsonObject
A reference to a Progress.Json.ObjectModel.JsonObject object.
This JsonObject object must fit one of the valid patterns for a ProDataSet or temp-table object. If any part of the JsonObject object does not fit one of the accepted patterns, the READ-JSON( ) method generates an error message and returns FALSE. If the JsonObject object fits an accepted pattern, but contains tables whose names do not match the existing ProDataSet schema, or contains fields whose names do not match the existing temp-table schema, the mismatched tables or fields are ignored.
read-mode
An optional CHARACTER expression that specifies the mode in which this method reads data from the JSON source into a temp-table or a ProDataSet member buffer. The expression must evaluate to "APPEND", "EMPTY", "MERGE", or "REPLACE". The default value is "MERGE".

The following table lists the READ-JSON( ) method modes for reading data.

Table 1. READ-JSON( ) method read modes
When the mode is . . . The READ-JSON( ) method . . .
"APPEND" Reads data from the JSON source 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 source 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 source.
"MERGE" Reads data from the JSON source into the ProDataSet or temp-table object by merging new records with existing records in the table. If a record from the JSON source 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 source does not exist in the object, the method creates a new record.
"REPLACE" Reads data from the JSON source into the ProDataSet or temp-table object by merging new records with existing records in the table. If the record from the JSON source 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 source does not exist in the object, the method creates a new record.

Notes

  • 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 message and returns FALSE. For more information about inferring schema from a JSON source, see Use JSON with ABL Applications.
  • For a static ProDataSet or temp-table, the serialize name or object name must match the name found in the JSON source. If the names do not match, the method generates an error message and returns FALSE. The AVM ignores any columns in the JSON source 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.
  • If a JSON source contains ProDataSet before-image data, the READ-JSON( ) method populates the after-table and before-table data for the ProDataSet.
  • You cannot call READ-JSON( ) on a database buffer handle.
  • READ-JSON( ) can deserialize class-based objects from a JSON source. See WRITE-JSON( ) method for a detailed list of restrictions that apply to any class-based objects that are to be written to and from JSON.
  • When executing the method, there is no guarantee as to the contents of the buffers involved after the method finishes executing.
  • Binary types, including BLOB, RAW, and ROWID are base64-encoded/decoded. See Data type mapping in Use JSON with ABL Applications for more information.
  • JSON data can be in Scientific notation format for DECIMAL, INTEGER, and INT64 data types.

Examples

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

See also

IS-JSON attribute, Progress.Json.ObjectModel.JsonArray class, Progress.Json.ObjectModel.JsonObject class, WEB-CONTEXT system handle, WRITE-JSON( ) method , SERIALIZE-ROW( ) method