Description
Inserts a data row from a JSON string into a DataWindow control, DataStore object, or DataWindowChild object. The status of the inserted data row is NotModified!.
The JSON string that can be imported by this function must be a one-level plain JSON string. For details, see Plain JSON: one-level structure in Application Techniques.
This function will fail to import data properly, if the DataWindow is in query mode.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, and DataStore object, except for those with the Composite, Crosstab, OLE 2.0, or RichText presentation styles. |
Syntax
PowerBuilder
long dwcontrol.ImportRowFromJson( string json, long row {, ref string error} {, DWBuffer dwbuffer})
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, DataStore, or DataWindowChild. |
|
json |
A string specifying the JSON data. The JSON string must be in the plain format which must have only one level (cannot be two or more) and must be an object (cannot be an array). |
|
row |
A long value identifying the row before which you want to insert a row. To insert a row at the end, specify 0, or a negative value, or a value greater than the row count in the DataWindow buffer. |
|
error (optional) |
A variable into which the returned warning or error message will be placed. When there are a large amount of error messages, the error information will only display the total number of errors, and the detailed message of the first 10 errors. The import warning caused by data type mismatch will not affect the return value of this function; although the data of the mismatched columns will not be imported, the rest columns (even only one column) that are matched will be imported successfully; and that row will be regarded as a successful import and counted into the return value. The import error caused by DW presentation style mismatch, invalid arguments etc. will be regarded as a failure, and represented by a negative return value of this function, instead of being placed into this variable. See the Return Value section for more. Most of the messages placed into this variable are warnings (such as data type mismatch) rather than errors. Developers can adjust the JSON data according to the message or simply ignore the message if the problematic column is not critical and the corresponding DataWindow column can be left blank. |
|
dwbuffer (optional) |
A value of the dwBuffer enumerated datatype identifying the DataWindow buffer from which you want to import the data. For a list of valid values, see DWBuffer. If not specified, imports the JSON data to the Primary! buffer. If specified, imports the JSON data to the specified buffer. |
Return value
Long. Returns 1 if the data row was added successfully and one of the following negative integers if an error occurs.
-1 -- General error.
-3 -- Invalid argument.
-4 -- Invalid JSON.
-5 -- JSON format error.
-6 -- Unsupported DataWindow presentation style for import.
-7 -- Error resolving DataWindow nesting.
The method returns null if any of the following:
-
any argument's value is null
-
the DataWindow object (dataobject) is invalid
Usage
There is no forced conversion between strings and numbers. For example, the number 123 in JSON string will not be imported into the DataWindow column of char(10) type. For such case, a data type mismatch warning will be recorded in the error argument.
A boolean value (true or false) will be converted to 0 or 1 when imported from the JSON string to the DataWindow; however, 0 or 1 will not be converted to a boolean value (true or false) when exported from the DataWindow to the JSON string.
If the string length in JSON is larger than the string length in DataWindow, the string will be truncated when imported into the DataWindow. For example, JSON string [{"name":"TestForTrancate"}] is imported as "Test" if the data type of DataWindow column "name" is char(4).
When the number value is imported from the JSON string to the DataWindow column of number data type (with uncertain precision), the value will have uncertain decimals, for example, 6.78 becomes 6.78000020980835 after imported from the JSON string to the DataWindow.
Example
The following example imports two rows, one before the first row and the other before the last row.
String ls_Json = '{"dept_id":1900,"dept_name":"Test send patch request42","dept_head_id":"test"}'
String ls_Error
Integer li_ImportJsonReturn
//Inserts a row before the first row
//Note that the column name and data type between JSON string and DataWindow must match
li_ImportJsonReturn = dw_Data.ImportRowFromJson( ls_Json, 1, ls_Error)
If Trim(ls_Error) <> "" Then
//Prints the value of ls_Error.
//The data type of the last column between JSON string and DataWindow does not match
//so there will be an error message here.
End If
ls_Json = '{"dept_id":1900,"dept_name":"Test send patch request42","dept_head_id":1}'
//Inserts a row before the last row
//Note that the column name and data type between JSON string and DataWindow must match
li_ImportJsonReturn = dw_Data.ImportRowFromJson( ls_Json, 0, ls_Error, Primary!)
If Trim(ls_Error) <> "" Then
//Prints the value of ls_Error
End If
See also
