Quick Reference for Dynamic Entity Methods - Using JSON in Caché

This section provides an overview and references for each of the available dynamic entity methods. Dynamic entities are instances of %Library.DynamicObject or %Library.DynamicArray, both of which extend %Library.DynamicAbstractObject. Each listing in this chapter includes a link to the appropriate online class reference documentation.

Given a JSON source, parse the source and return an object of datatype %DynamicAbstractObject containing the parsed JSON. If an error occurs during parsing, an exception will be thrown. See “Converting Dynamic Entities to and from JSON” for details and examples.

   classmethod %FromJSON(str) as %DynamicAbstractObject

parameters:

str — The input can be from any one of the following sources:
- string value containing the source.
- stream object to read the source from.
- file URI where the source can be read. The file must be encoded as UTF-8.

class reference: %DynamicAbstractObject.%FromJSON()

Given a valid object key or array index, returns the value. If the value does not exist, a null string "" is returned. See “Using %Set(), %Get(), and %Remove()” for details and examples.

   method %Get(key) as %CacheString

parameters:

key — the object key or array index of the value to be retrieved. An array index must be passed as a canonical integer value. Array indexes begin at position 0.

see also: %IsDefined()

class reference: %DynamicAbstractObject.%GetTypeOf()

Tests if the item specified by key is defined within an object. Returns false if the item is unassigned or does not exist. See “Using %IsDefined() to Test for Valid Values” for details and examples.

   method %IsDefined(key) as %Boolean

parameters:

key — the object key or array index of the item to be tested. An array index must be passed as a canonical integer value. Array indexes begin at position 0.

class reference: %DynamicObject.%IsDefined() and %DynamicArray.%IsDefined()

Returns the value of the last member of the array. The value is then removed from the array. If the array is already empty, the method returns the empty string, "". See “Using %Push and %Pop with Dynamic Arrays” for details and examples.

   method %Pop() as %CacheString

class reference: %DynamicArray.%Pop()

Given a new value, append it to the end of the current array, increasing the length of the array. value Returns An oref referencing the current modified array, allowing calls to %Push() to be chained. See “Using %Push and %Pop with Dynamic Arrays” for details and examples.

   method %Push(value, type) as %DynamicAbstractObject

parameters:

value — The value to be assigned to the new array element.
type — optional string indicating the datatype of value. The following strings may be used:
- "null" — a JSON null. The value argument must be "" (empty string).
- "boolean" — a JSON false (value argument must be 0) or true (value argument must be 1).
- "false" — a JSON false (value argument must be 0).
- "true" — a JSON true (value argument must be 1).
- "number" — convert value to a canonical numeric value
- "string" — convert value to a text string

class reference: %DynamicArray.%Push()

Removes the specified element from a dynamic object or array, and returns the value of the removed element. If the value of the element is an embedded dynamic object or array, all subordinate nodes are removed as well. In a dynamic array, all elements following the removed element will have their subscript position decremented by 1. See “Using %Set(), %Get(), and %Remove()” for details and examples.

   method %Remove(key) as %DynamicAbstractObject

parameters:

key — the object key or array index of the element you wish to remove. An array index must be passed as a canonical integer value. Array indexes begin at position 0.