JSON Format Manipulation Functions

Functions available from D2000 V12.2.

JSON format manipulation functions allow creating, reading, writing and deleting JSON objects. Function names are created by the prefix %JSON_.

When adding invalid value (e.g. %JSON_ObjectSetValue), value in JSON is stored as null. When reading null value from JSON (e.g. %JSON_ObjectGetValue), value is interpreted as invalid value.

Every handle to JSON object or array must be released by calling %JSON_FreeObjectHandle or %JSON_FreeArrayHandle.

Handle remain valid also after deleting of child object or array (e.g. %JSON_ArrayRemoveItem) pointed to by the handle. Similarly when removed parent object or array, handle pointed to child remains valid.

Example:

INT _obj
INT _clientInfo
TEXT _d2version
 
_obj := %JSON_ObjectFromString(ModuleInfo)
_clientInfo := %JSON_ObjectGetObject(_obj, "client_data")
 
%JSON_FreeObjectHandle(_obj) ; release handle to _obj, _clientInfo is still valid handle
 
_d2version := %JSON_ObjectGetValue(_clientInfo, "d2000_version")
 
LOG "D2000 version", _d2version PRIORITY _LOG_PRTY_INFO
 
%JSON_FreeObjectHandle(_clientInfo) ; finally release _clientInfo handle

There is created JSON object from ModuleInfo variable, then we get value from object and this value is written into monitoring database.

Sharing of arrays:

When an array is inserted into an object or another array (%JSON_ObjectSetArray, %JSON_ArraySetArray, %JSON_ArrayAppendArray), the array is not copied. The handle of the inserted array and the item in the parent object or array point to the same array. Similarly, when an array is obtained from an object or array (%JSON_ObjectGetArray, %JSON_ArrayGetArray), the function returns a handle to the same array that is stored in the parent object or array.

Functions %JSON_ArrayAppendValue, %JSON_ArrayAppendArray and %JSON_ArrayAppendObject modify the shared array, the change is visible also in the parent object or array.
Functions %JSON_ArraySetValue, %JSON_ArraySetArray, %JSON_ArraySetObject, %JSON_ArrayRemoveItem, %JSON_ArraySetLength and %JSON_ArrayClear (on a non-empty array) create a private copy of the array for the given handle. The parent object or array keeps the original array, and neither this change nor any later change made through the handle (including %JSON_ArrayAppend…) is visible in it.
Functions %JSON_ObjectSetValue, %JSON_ObjectSetArray, %JSON_ObjectSetObject, %JSON_ObjectRemoveField and %JSON_ObjectClear modify the object without copying, the change is visible through all handles pointing to the object.

INT _obj
  INT _arr

  _obj := %JSON_CreateObject()
  _arr := %JSON_CreateArray()

  %JSON_ArrayAppendValue(_arr, 1)
  %JSON_ObjectSetArray(_obj, "x", _arr)   ; _obj and _arr share the same array

  %JSON_ArrayAppendValue(_arr, 2)         ; _obj: {"x":[1,2]}  _arr: [1,2]
  %JSON_ArraySetValue(_arr, 1, 99)        ; _obj: {"x":[1,2]}  _arr: [99,2] - _arr has a private copy
  %JSON_ArrayAppendValue(_arr, 3)         ; _obj: {"x":[1,2]}  _arr: [99,2,3]

  %JSON_FreeArrayHandle(_arr)
  %JSON_FreeObjectHandle(_obj)

%JSON file manipulation functions:

Related pages:

ESL extended functions