READ-JSON( ) method

Reads a JSON string into a 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", "JsonArray", "JsonObject", "HANDLE", and "LONGCHAR".

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 JsonArray reference that is the root of a tree of JsonArrays and JsonObjects. This tree must fit one of the valid patterns for a ProDataSet or Temp-table object. If any part of the tree does not fit one of the accepted patterns or if it fits the pattern, but not match the existing temp-table schema, the mismatched part of the tree is ignored.

JsonObject

A JsonObject reference that is the root of a tree of JsonArrays and JsonObjects. This tree must fit one of the valid patterns for a ProDataSet or Temp-table object. If any part of the tree does not fit one of the accepted patterns or if it fits a pattern, but does not match the existing temp-table schema, the mismatched part of the tree is ignored.

read-mode

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

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

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.

If a JSON string contains ProDataSet before-image data, the READ-JSON( ) method populates the after-table and before-table data for the ProDataSet.

You cannot read a JSON string into a database buffer.

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, WEB-CONTEXT system handle, WRITE-JSON( ) method , SERIALIZE-ROW( ) method