WRITE-JSON( ) method

Writes a specified JSON string, Progress.Json.ObjectModel.JsonArray object, or Progress.Json.ObjectModel.JsonObject object from a corresponding ProDataSet, temp-table, or temp-table buffer object. In the case of a temp-table buffer object, all the records of the temp-table associated with the buffer object are written to the JSON string or JsonArray object—not just the one record in the buffer.

Return type: LOGICAL

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

Syntax

WRITE-JSON ( target-type
  , { file | stream | stream-handle | memptr | longchar 
        | JsonArray | JsonObject }
  [ , formatted [ , encoding [ , omit-initial-values  
  [ , omit-outer-object [ , write-before-image ] ] ] ] ] )

target-type

A CHARACTER expression that specifies the target type for the JSON output. Valid values are "FILE", "STREAM", "STREAM-HANDLE", "MEMPTR", "LONGCHAR", "JsonArray", and "JsonObject".

All values except "JsonArray" and "JsonObject" specify a target for a JSON string.

"JsonArray" is only a valid target-type for invoking WRITE-JSON( ) on a temp-table or buffer object handle. If set to "JsonArray" for a ProDataSet object handle, the WRITE-JSON( ) method generates an error message and returns a value of FALSE.

file

A CHARACTER expression that specifies the name of a file to which the AVM writes the JSON string. You can specify an absolute pathname or a pathname relative to the current working directory. If a file with the specified name already exists, the AVM verifies that the file is writeable and overwrites the file.

stream

A CHARACTER expression that specifies the name of a stream. If you specify the empty string (""), the AVM writes the JSON string to the default unnamed output stream. For WebSpeed, write the JSON string to the WebSpeed-defined output stream (WEBSTREAM).

For more information about using ABL unnamed output streams, see the DEFINE STREAM statement reference entry and the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces. For more information about using WebSpeed-defined output streams, see OpenEdge Application Server: Developing WebSpeed Applications.

stream-handle

A HANDLE variable that specifies a stream object handle.

memptr

A MEMPTR variable to contain the JSON string in memory. If you do not specify the encoding parameter, the AVM encodes the text written to the MEMPTR as UTF-8. This method allocates the required amount of memory for the JSON string and sets the size of the variable. When you are finished using the MEMPTR, you must free the associated memory, by executing SET-SIZE(memptr) = 0 on the MEMPTR.

longchar

A LONGCHAR variable to contain the JSON string in memory.

The AVM saves the JSON string to the LONGCHAR variable in the code page that corresponds to the character encoding you specify in the encoding option. If you do not specify a character encoding for the JSON string, the AVM saves the LONGCHAR variable in UTF-8.

If the LONGCHAR variable's code page is fixed (that is, set using the FIX-CODEPAGE statement) and the fixed code page is not equivalent to the character encoding you specify in the encoding option, the WRITE-JSON( ) method generates an error message and returns FALSE. The JSON string is not saved to the LONGCHAR.

JsonArray

A reference to a Progress.Json.ObjectModel.JsonArray object to which the AVM writes the contents of the associated temp-table. Any prior contents of the specified JsonArray are removed.

The JsonArray must be a valid instance of type Progress.Json.ObjectModel.JsonArray. If not, the WRITE-JSON( ) method generates an error message and returns FALSE.

JsonObject

A reference to a Progress.Json.ObjectModel.JsonObject object to which the AVM writes the contents of the associated ProDataSet or temp-table. Any prior contents of the specified JsonObject are removed.

The JsonObject must be a valid instance of type Progress.Json.ObjectModel.JsonObject. If not, the WRITE-JSON( ) method generates an error message and returns FALSE.

formatted

An optional LOGICAL expression where TRUE directs the AVM to format the JSON string in a hierarchical manner using extra white space, carriage returns, and line feeds. The default value is FALSE.

If you specify the Unknown value (?), the method uses the default value of FALSE.

The formatted option is ignored for JsonArray and JsonObject targets.

encoding

An optional CHARACTER expression that specifies the name of the character encoding the AVM uses to write the JSON output. The default encoding is "UTF-8".

The encoding name must specify a Unicode transformation format. Valid values are "UTF-8", "UTF-16", "UTF-16BE", "UTF-16LE", "UTF-32", "UTF-32BE", and "UTF-32LE".

Note: If you specify the empty string ("") or the Unknown value (?), the AVM uses the default encoding of UTF-8.

omit-initial-values

An optional LOGICAL expression where TRUE directs the AVM to exclude temp-table fields containing their initial values from the JSON output, and FALSE directs the AVM to include all temp-table field data in the output. The default value is FALSE. If you specify the Unknown value (?), the method uses the default value of FALSE.

When working with large ProDataSets, omitting fields containing their initial values can yield smaller JSON values, more efficient network transfers, and performance gains with the READ-JSON( ) and WRITE-JSON( ) methods.

This behavior applies both to temp-table fields that have the default initial value for its data type, and for fields that have an initial value set with the ABL INITIAL option.

Although using the omit-initial-values option can give your application performance and resource use improvements, you must be sure that the consumers of the generated JSON output can correctly handle it. The ABL READ-JSON( ) method always populates created records with initial values from the temp-table or ProDataSet definition. Other applications might not do this.

omit-outer-object

An optional LOGICAL expression that indicates whether the outer-most object is included in the JSON output. TRUE directs the AVM to remove the outer-most object on output. FALSE directs the AVM to include the outer-most object in the output.

For a JSON string or JsonObject target, the default value is FALSE. If you specify the Unknown value (?), the method also uses the default value of FALSE. When writing a temp-table to a JsonObject target, omit-outer-object must be FALSE. If you specify TRUE, the WRITE-JSON( ) method generates an error message and returns FALSE.

For a JsonArray target, the default value for omit-outer-object is TRUE. If you specify the Unknown value (?), the method also uses the default value of TRUE. When writing a temp-table or temp-table buffer object to a JsonArray target, omit-outer-object must be TRUE. If you specify FALSE, the WRITE-JSON( ) method generates an error message and returns FALSE.

write-before-image

An optional LOGICAL expression where TRUE directs the AVM to include ProDataSet before-image data and error information in the JSON output. The default value is FALSE.

This element can only be set to TRUE for a ProDataSet. If its value is set to TRUE for a temp-table or buffer handle, the WRITE-JSON( ) method generates an error message and returns a value of FALSE.

Notes

• When writing data from a ProDataSet object that contains data-relations, you can nest child rows of a ProDataSet buffer within their parent rows in the resulting JSON output by:
  • Setting the NESTED attribute on the data-relation object handle to TRUE
  • Specifying the NESTED option for the data-relation on the DEFINE DATASET statement
  • Specifying the NESTED option in the ADD-RELATION( ) method
  • Specify a PARENT-ID-RELATION in the DEFINE DATASET statement
  • Using the ADD-PARENT-ID-RELATION( ) method on a dynamic ProDataSet object
• You cannot call WRITE-JSON( ) on a database buffer handle.
• WRITE-JSON( ) can serialize fields with data types based on class-based objects. The following restrictions apply to any class-based objects that are to be written to the JSON target:
  • The object's class and all of the classes in its hierarchy must be marked as SERIALIZABLE. See the CLASS statement entry for more information.
  • All of the object's data members that are themselves defined as class-based objects must be of class types that are also marked SERIALIZABLE. ABL enums are also allowed because they are implicitly serializable.
  • By default, all non-static, public data members and read-write properties are serialized. You can include protected and private data members, read-write properties, temp tables, and ProDataSets in serialization by defining them using the SERIALIZABLE option. See the DEFINE entry for each element for more details.
  • To be able to deserialize an object, the API for the object's class at the time of serialization must be compatible with the API for the class at the time of deserialization. At a minimum, the data members contained in the JSON target for that object should exist in the class, be serializable, and have compatible data types.
  • The content of static data members is not serialized, and the state of queries, buffers, open files, streams, and event subscriptions, for example, are not maintained.

Examples

The following code example defines a static ProDataSet object, attaches its data sources, fills the ProDataSet object, and writes the ProDataSet object to a JSON string in a nested manner:

DEFINE VARIABLE cTargetType AS CHARACTER NO-UNDO.
DEFINE VARIABLE cFile       AS CHARACTER NO-UNDO.
DEFINE VARIABLE lFormatted  AS LOGICAL   NO-UNDO.
DEFINE VARIABLE lRetOK      AS LOGICAL   NO-UNDO.

DEFINE TEMP-TABLE ttCustomer NO-UNDO LIKE Customer.
DEFINE TEMP-TABLE ttOrder    NO-UNDO LIKE Order.
DEFINE TEMP-TABLE ttInvoice  NO-UNDO LIKE Invoice.

DEFINE DATASET dsOrderLog FOR ttCustomer, ttOrder, ttInvoice
  DATA-RELATION CustOrd FOR ttCustomer,
    ttOrder RELATION-FIELDS(CustNum,CustNum) NESTED
  DATA-RELATION OrdInv FOR ttOrder,
    ttInvoice RELATION-FIELDS(OrderNum,OrderNum) NESTED.

DEFINE DATA-SOURCE dsCustomer FOR Customer.
DEFINE DATA-SOURCE dsOrder    FOR Order.
DEFINE DATA-SOURCE dsInvoice  FOR Invoice.

BUFFER ttCustomer:HANDLE:ATTACH-DATA-SOURCE(DATA-SOURCE dsCustomer:HANDLE).
BUFFER ttOrder:HANDLE:ATTACH-DATA-SOURCE(DATA-SOURCE dsOrder:HANDLE).
BUFFER ttInvoice:HANDLE:ATTACH-DATA-SOURCE(DATA-SOURCE dsInvoice:HANDLE).

DATA-SOURCE dsCustomer:FILL-WHERE-STRING = "WHERE Customer.CustNum = 2 ".
DATASET dsOrderLog:FILL().

ASSIGN
  cTargetType = "file"
  cFile       = "dset.json"
  lFormatted  = TRUE.
lRetOK = DATASET dsOrderLog:WRITE-JSON(cTargetType, cFile, lFormatted).

The following code example defines a static temp-table object, populates the temp-table object (code not shown), and writes the temp-table object to a JSON string:

DEFINE VARIABLE cTargetType AS CHARACTER NO-UNDO.
DEFINE VARIABLE cFile       AS CHARACTER NO-UNDO.
DEFINE VARIABLE lFormatted  AS LOGICAL   NO-UNDO.
DEFINE VARIABLE lRetOK      AS LOGICAL   NO-UNDO.

DEFINE TEMP-TABLE ttCust NO-UNDO LIKE Customer.

/* Code to populate the temp-table */  
ASSIGN  
  cTargetType = "file" 
  cFile       = "ttCust.json" 
  lFormatted  = TRUE. 
lRetOK = TEMP-TABLE ttCust:WRITE-JSON(cTargetType, cFile, lFormatted).

The following code example defines and populates a static temp-table object with different assigned, initial, and default value settings. It also defines and instantiates both a JsonArray and JsonObject object, then writes the JSON representation of the temp-table to both the JsonArray and the JsonObject. As it writes out the JSON, it generates MESSAGE statement output to a TtabWriteJsonArrObj.out file to show the results by returning and displaying both the written JSON array and object contents as a string.

USING Progress.Json.ObjectModel.*.

DEFINE VARIABLE jArr AS JsonArray.
DEFINE VARIABLE jObj AS JsonObject.
DEFINE VARIABLE htt AS HANDLE.

DEFINE TEMP-TABLE ttTest
    FIELD f1 AS CHARACTER INITIAL "InitVal"
    FIELD f2 AS INTEGER.

OUTPUT TO TtabWriteJsonArrObj.out.

CREATE ttTest.
ASSIGN 
    f1 = "AAA"
    f2 = 1.
    
CREATE ttTest.
ASSIGN 
    f2 = 2. 
    
CREATE ttTest.
ASSIGN 
    f1 = "BBB". 

htt = TEMP-TABLE ttTest:HANDLE.

jArr = NEW JsonArray().
jObj = NEW JsonObject().

MESSAGE "ttTest:WRITE-JSON to jArr". 

htt:WRITE-JSON("JsonArray", jArr).

MESSAGE "After calling WRITE-JSON() JsonArray contains:".

MESSAGE STRING(jArr:GetJsonText()).
MESSAGE "jArr:LENGTH =" jArr:LENGTH.

MESSAGE SKIP "ttTest:WRITE-JSON to jObj". 

htt:WRITE-JSON("JsonObject", jObj).

MESSAGE "After calling WRITE-JSON () JsonObject contains:" SKIP.
MESSAGE STRING(jObj:GetJsonText()).

OUTPUT CLOSE.

The following shows the MESSAGE statement output generated in TtabWriteJsonArrObj.out.

ttTest:WRITE-JSON to jArr
After calling WRITE-JSON() JsonArray contains:
[{"f1":"AAA","f2":1},{"f1":"InitVal","f2":2},{"f1":"BBB","f2":0}]

jArr:LENGTH = 3

ttTest:WRITE-JSON to jObj
After calling WRITE-JSON () JsonObject contains:
{"ttTest":[{"f1":"AAA","f2":1},{"f1":"InitVal","f2":2},{"f1":"BBB","f2":0}]}

See also

ENCODING attribute, FIX-CODEPAGE statement, FOREIGN-KEY-HIDDEN attribute, NESTED attribute, Progress.Json.ObjectModel.JsonArray class, Progress.Json.ObjectModel.JsonObject class, READ-JSON( ) method, SERIALIZE-ROW( ) method