Writes a JSON string from a ProDataSet, a temp-table, or a temp-table buffer object. In the case of the temp-table buffer object, all the records of the temp-table associated with the buffer object are written to the JSON string—not just the one in the buffer.
Return type: LOGICAL
Applies to: Buffer object handle, ProDataSet object handle, Temp-table object handle
WRITE-JSON ( target-type
, { file | stream | stream-handle | memptr | longchar }
[ , formatted [ , encoding [ , omit-initial-values
[ , omit-outer-object [ , write-before-image ] ] ] ] ] )
|
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.
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 and returns FALSE. The JSON string is not saved to the LONGCHAR.
If you specify the Unknown value (?), the method uses the default value of FALSE.
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".
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 string will correctly handle the JSON. 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.
If you specify the the Unknown value (?), the method uses the default value of 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 raises an error and returns a value of FALSE.
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 string by:
You cannot write a JSON string from a database buffer.
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). |