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