SERIALIZE-ROW( ) method

A CHARACTER expression that specifies the format of the output. Valid values are "JSON" and "XML".

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

All values except "JsonObject" specify a target for a JSON or XML string.

When you specify "JsonObject", target-format must be "JSON". Otherwise, the SERIALIZE-ROW( ) method generates an error message and returns FALSE.

A CHARACTER expression that specifies the name of a file to which the AVM writes the buffer's current row. 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.

A CHARACTER expression that specifies the name of a stream. If you specify the empty string (""), the AVM writes the buffer's current row to the default unnamed output stream. For WebSpeed, write the buffer's current row 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.

A HANDLE variable that specifies a stream object handle.

A MEMPTR variable to contain the buffer's current row 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 MEMPTR 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.

A LONGCHAR variable to contain the buffer's current row in memory.

The AVM saves the buffer's current row 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 LONGCHAR, 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 SERIALIZE-ROW( ) method generates an error message and returns FALSE. The buffer's current row is not saved to the LONGCHAR.

A reference to a Progress.Json.ObjectModel.JsonObject object to which the AVM writes the buffer's current row. 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 SERIALIZE-ROW( ) method generates an error message and returns FALSE.

When you specify a JsonObject parameter, target-format must be "JSON". Otherwise, the SERIALIZE-ROW( ) method generates an error message and returns FALSE.

An optional LOGICAL expression where TRUE directs the AVM to format the output 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 JsonObject targets.

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

When target-format is "JSON", 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 target-format is "XML", the encoding name must be an Internet Assigned Numbers Authority (IANA) name supported by the ABL XML Parser. For a list of supported IANA encodings and their corresponding ABL code pages, see the following table in the ENCODING attribute reference entry.

An optional LOGICAL expression where TRUE directs the AVM to exclude temp-table fields containing their initial values from the 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 output size, more efficient network transfers, and performance gains with the READ-JSON( ) and SERIALIZE-ROW( ) 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( ) and READ-XML( ) methods always populate created records with initial values from the temp-table or ProDataSet definition. Other applications might not do this.

An optional LOGICAL expression that indicates whether the outer-most object in JSON output is included. 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. The default is FALSE.

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

The omit-outer-object option is only valid when target-format is "JSON". If omit-outer-object is TRUE when target-type is "XML", the SERIALIZE-JSON( ) method generates an error message and returns FALSE.