Support for the JSON format was added in the PowerBuilder 2017 R2 release and then enhanced in 2017 R3. PowerBuilder 2019 contains even more enhancements in this area, particularly with regard to:
- Enhanced JSONParser
- Enhanced JSONPackage
- DataWindows Row Level Import/Export
- New ModelStore JSON Format
Enhanced JSONParser
There are two new methods: ContainsKey and GetItemType. Both functions are important for allowing more dynamic parsing of data sets.
The ContainsKey method take a key name as a string returns a boolean indicating whether or not the key exists:
objectname.ContainsKey ( Key )
The GetItemType takes an item handle or a parent item handle and a key name and returns a JsonItemType indicating what type of value the item is.
objectname.GetItemType ( ItemHandle )
objectname.GetItemType ( ParentItemHandle, Key )
The JsonItemType is one of the following:
- JsonStringItem!
- JsonNumberItem!
- JsonBooleanItem!
- JsonNullItem!
- JsonObjectItem!
- JsonArrayItem!
There is also a new ReturnsNullWhenError property. A boolean value, by default is FALSE meaning that if your code attempts to access a key that doesn't exist in the JSON, an exception is thrown, which was also the behavior up through 2017 R3. If you set the value to TRUE, then an attempt to access a key that doesn't exist will just return a null value.
Enhanced JSONPackage
The original JSONPackage object only accepted and returned string values for the GetValue and SetValue methods. Starting with PowerBuilder 2019, there are separate methods for all of the various data types:
- GetValueBlob, GetValueBoolean, GetValueDate, GetValueDateTime, GetValueNumber, GetValueString, GetValueTime
- SetValueBlob, SetValueBoolean, SetValueDate, SetValueDateTime, SetValueNumber, SetValueString, SetValueTime
In addition, methods have been added to allow the direct transfer of data from a DataWindow, DataStore or DataWindowChild:
- objectname.GetValueToDataWindow (string key, dwcontrol DWControl {, boolean resetflag} {, string error} {, DWBuffer dwbuffer {, long startrow {, long endrow } } } )
- objectname.SetValueByDataWindow ( string Key, dwcontrol DWControl {, boolean format } )
- objectname.SetValueByDataWindow ( string Key, dwcontrol DWControl {, DWBuffer dwbuffer }, boolean changedonly, boolean format )
- objectname.SetValueByDataWindow ( string Key, dwcontrol DWControl, boolean primarydata, boolean filterdata, boolean deletedata, boolean dwcdata {, boolean format } )
- objectname.SetValueByDataWindow ( string Key, dwcontrol DWControl, DWBuffer dwbuffer {, long startrow {, long endrow {, long startcolumn {, long endcolumn } } } } {, boolean format } )
In addition, the JSONPackage has a new GetItemType method and a new ReturnNullWhenError property identical to those for the JSONParser discussed above.
DataWindow Row Level Import/Export
The DataWindow (and DataStore) have two new methods that allow JSON to be imported and exported at a row level.
- ImportRowFromJson( string json, long row, {,ref string error} {, DWBuffer dwbuffer})
- ExportRowAsJson (long row {, DWBuffer dwbuffer})
ModelStore JSON Format
PowerBuilder 2017 R2 and R3 export and import JSON in two different formats: Plain JSON and DataWindow JSON. Plain JSON is useful for interacting with non PowerBuilder based applications. DataWindow JSON is useful when interacting with another PowerBuilder based applications (e.g., SnapDevelop generated REST APIs). The DataWindow JSON format allows state information (row and column modified status, column original and modified values, etc.) which supports an optimistic concurrency approach to updates without requiring timestamp columns to be added to data models. It also contains meta data about the datawindow that was used to create it and has separate sections to represent the different datawindow buffers (including child datawindow buffers).
ModelStore JSON format is similar to the DataWindow JSON format in that it contains meta data about row/column modified status and original and modified column value. It isn't generated by the DataWindow though, it's an import only format. Since it isn't DataWindow generated, it doesn't contain DataWindow related meta data or store row information in separate DataWindow buffer sections.