Writing JSON from a temp-table, temp-table buffer, or a ProDataSet
The WRITE-JSON( ) method writes a JSON string, Progress.Json.ObjectModel.JsonArray object, or Progress.Json.ObjectModel.JsonObject object containing the data from a corresponding temp-table, temp-table buffer, or ProDataSet object handle on which you call the method. If you call the method on a temp-table buffer handle, it writes the entire contents of the associated temp-table, not just the contents of the buffer. When calling the method on a ProDataSet object handle, WRITE-JSON( ) writes the current version of data in each row of each table in the ProDataSet object. The AVM ignores any before-image data for a ProDataSet unless you specify an option to include it.
Note that you cannot call WRITE-JSON( ) on a database buffer handle.
Note also that you cannot write a JsonArray from a ProDataSet object. If you call the method on a ProDataSet object handle to write a JsonArray, WRITE-JSON( ) generates an error message and returns a value of FALSE.
For JSON string output only, WRITE-JSON( ) provides the option to format the JSON in a hierarchical manner using extra white space and line breaks.
WRITE-JSON( ) does not write the data object's schema to JSON, because JSON has no standardized support for schema. The lack of schema information means that the JSON string does not explicitly include indexes and data-relations.
The syntax for WRITE-JSON( ) is shown below. The method returns TRUE or FALSE to indicate whether the operation was successful.
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.
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).
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 setting the MEMTER to zero bytes with the SET-SIZE statement.
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 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.
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.
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 returns an error and a value of FALSE.
Note: The examples used in this chapter are found in the doc_samples\src\prodoc\json directory.
