Reading JSON into a temp-table, temp-table buffer, or ProDataSet
The READ-JSON( ) method loads data from a JSON string, Progress.Json.ObjectModel.JsonArray object, or Progress.Json.ObjectModel.JsonObject object into a corresponding static or dynamic temp-table, temp-table buffer, or ProDataSet object handle on which you call the method. If the ABL data object has a defined schema, the AVM assumes that the JSON values match up with the ABL fields' data types as shown in Table 4. READ-JSON( ) generates an error message and returns FALSE if the JSON value cannot be converted to the expected ABL data type.
Note that you cannot call READ-JSON( ) on a database buffer handle.
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 the Inferring ABL schemas from JSON data.
READ-JSON( ) accepts a JsonArray or JsonObject as a source as long as the source object conforms to an accepted pattern for the temp-table or ProDataSet into which you are loading the JSON data. Note, however, that you cannot read a JsonArray into a ProDataSet object. If you attempt to load data from a JsonArray into a ProDataSet object, READ-JSON( ) generates an error message and returns FALSE.
If a JSON string contains ProDataSet before-image data, the READ-JSON( ) method populates the after-table and before-table data for the ProDataSet.
Here is the syntax for READ-JSON( ). The method returns TRUE or FALSE to indicate if the operation was successful.
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.
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, which can contain additional JsonArrays and JsonObjects. This JsonArray must fit one of the valid patterns for a temp-table object. If any part of the JsonArray does not fit one of the accepted patterns, READ-JSON( ) generates an error message and returns FALSE. If the JsonArray 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, which can contain additional JsonArrays and JsonObjects. This JsonObject must fit one of the valid patterns for a ProDataSet or temp-table object. If any part of the JsonObject does not fit one of the accepted patterns, READ-JSON( ) generates an error message and returns FALSE. If the JsonObject 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 9. 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.
For a static ProDataSet or temp-table, the serialize name or object name must match the corresponding name found in the JSON source. 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 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.
Note: While reading JSON data into an ABL data object, the AVM does not respond to ProDataSet events. The AVM also does not track changes to the data in the ProDataSet or temp-table object, meaning that before-image tables are not updated.
