Introduction

You can create dynamic entities and define an arbitrary schema for them at run time:

   set dynObject1 = ##class(%DynamicObject).%New()
   set dynObject1.SomeNumber = 42
   set dynObject1.SomeString = "a string"
   set dynObject1.SomeArray = ##class(%DynamicArray).%New()
   set dynObject1.SomeArray."0" = "an array element"
   set dynObject1.SomeArray."1" = 123

You can also create a dynamic entity by assigning a literal JSON string. Literal JSON constructors {} and [] are can be used in place of the %New() constructor. For example you can create a dynamic array with set x=[] rather than set x=##class(%DynamicArray).%New(). Unlike %New(), a literal JSON constructor can also take a JSON literal string that specifies properties or elements. This means you can create an object identical to dynObject1 in the previous example with these simple assignment statements:

   set dynObject2 = {"SomeNumber":42,"SomeString":"a string"}
   set dynObject2.SomeArray = ["an array element",123]

This example uses a statement for each constructor, but the array constructor could just as easily be nested inside the object constructor.

To demonstrate that dynObject1 and dynObject2 are identical, we can display them as serialized JSON strings returned by the %ToJSON() method:

   write "object 1: "_dynObject1.%ToJSON(),!,"object 2: "_dynObject2.%ToJSON()

object 1: {"SomeNumber":42,"SomeString":"a string","SomeArray":["an array element",123]}
object 2: {"SomeNumber":42,"SomeString":"a string","SomeArray":["an array element",123]}

The text enclosed in literal constructors {} and [] must use valid JSON syntax, with one exception. For the value of an element or property, you can use a Caché expression enclosed in parentheses rather than a JSON literal. This ObjectScript dynamic expression (equivalent to the right side of a set statement) will evaluated at runtime and converted to a valid JSON value. The dynamic expression in this example includes a call to the Caché $ZDATE function:

   set dynObj = { "Date":($ZD($H,3)) }

The evaluated dynamic expression value is displayed when we retrieve dynObject.Date:

   write "Value of dynamic expression is: "_dynObject.Date

Value of dynamic expression is: 2016-07-27

(See “Dynamic Expressions and Dot Syntax” for a detailed discussion of these topics).

Dynamic entities have serialization methods that allow them to be converted to and from JSON strings. In the following example, a literal constructor is used to create a dynamic object, and the object’s %ToJSON() method is called to serialize it to myJSONstring:

   set myJSONstring = {"aNumber":(21*2),"aDate":($ZD($H,3)),"anArray":["string",123]}.%ToJSON()

This serialized JSON object can be stored and retrieved like any other string. Class method %FromJSON() can take a valid JSON string from any source and convert it to a dynamic object. The following code deserializes myJSONstring to dynamic object myObject and uses %ToJSON() to display it:

   set myObject = ##class(%DynamicAbstractObject).%FromJSON(myJSONstring)
   write myObject.%ToJSON()

{"aNumber":42,"aDate":"2016-08-29","anArray":["string",123]}

(See “Converting Dynamic Entities to and from JSON” for more information on serialization).

Some dynamic entity methods can be chained. This example creates a dynamic array with two elements, and then chains the %Push() method to add three more elements to the end of the array. A final chained call to %ToJSON() displays the serialized string:

   set dynArray = ["a","b"]
   write dynArray.%Push(12).%Push({"a":1,"b":2}).%Push("final").%ToJSON()

["a","b",12,{"a":1,"b":2},"final"]

(See “Method Chaining” for more information on chainable methods).

Dynamic entity methods are also provided for purposes such as iteration and datatype discovery. This example creates two JSON strings, deserializes one of them to dynEntity (either one will work), and then gets an iterator for dynEntity :

   set arrayStr = [12,"some string",[1,2]].%ToJSON()
   set objectStr = {"a":12,"b":"some string","c":{"x":1,"y":2}}.%ToJSON()
   set dynEntity = {}.%FromJSON(objectStr)
   set itr = dynEntity.%GetIterator()

For each iteration of the while loop, %GetNext() will return the property name or array index in key and the member value in val. The return value of %GetTypeOf() is a string indicating the datatype of the value:

   while itr.%GetNext(.key,.val) {write !,key_": "_"/"_val_"/, type: "_dynEntity.%GetTypeOf(key)}

a: /12/, type: number
b: /some string/, type: string
c: /1@%Library.DynamicObject/, type: object

(See “Iteration and Sparse Arrays” and “Working with Datatypes” for more information on these and related methods).

%Set() can either change the value of an existing dynamic entity member (property or element), or create a new member and assign a value to it. %Remove() removes an existing member. %Get() retrieves the value of a member. See “Creating and Modifying Dynamic Entities” for details.

%GetIterator() returns an iterator containing pointers to each member of a dynamic entity. %GetNext() returns the key and value of a member identified by the iterator, and advances the cursor to the next member. %Size() returns the number of members (including unassigned elements in a sparse array). %IsDefined() tests whether a member has an assigned value. See “Iteration and Sparse Arrays” for details.

%Push() adds a new element to the end of a dynamic array. %Pop() removes the final element of the array and returns its value. These methods are not available for dynamic objects because object properties are not stored in a predictable sequence. See “Using %Push and %Pop with Dynamic Arrays” for details.

%FromJSON() converts a JSON string to a dynamic entity. %ToJSON() serializes a dynamic entity to a canonical JSON string. See “Converting Dynamic Entities to and from JSON” for details.

%GetTypeOf() returns a string indicating the datatype of a specified member value. %Set() and %Push() provide an optional third argument to explicitly specify the datatype of a value. See “Working with Datatypes” for details.