Home > Class Reference > %SYS namespace > %Library.DynamicObject

%Library.DynamicObject

donotuse class %Library.DynamicObject extends %Library.DynamicAbstractObject

Dynamic Object type class.

Method Inventory

Methods

method %Get(key, default, type) as %RawString [ Language = objectscript ]
Given the key name of a key/value pair in an object, return the actual value that corresponds to the key name. If the value is the JSON null value then an empty string "" is returned. By default an empty string "" is also returned if the value does not exist. You can differentiate between a null value or an unassigned value that returns a "" string or a real "" string value by using the %GetTypeOf()() method.

key The 'key' argument contains the key name value of the object element that you wish to retrieve.

default The 'default' argument is optional and if missing then it is assumed to contain the empty string. The 'default' value is returned when the selected object element is undefined.

type The 'type' argument is optional, and if missing then it is assumed contain the empty string.

If the 'type' argument is present then its value must be one of the following string values:

""          - %Get(key) without conversions
"string"       - Convert to text string
"string>base64"  - Convert to text string then encode into base64
"string<base64"  - Convert to text string then decode from base64
"stream"      - Place string conversion into %Stream
"stream>base64" - String encoded into base64 into %Stream
"stream<base64" - String decoded from base64 into %Stream
"json"        - Convert to JSON representation

Returns The value of the object data element as selected by the key name of the key argument.

If the 'type' argument is the empty string then the selected object element is converted to the corresponding ObjectScript value.

If the 'type' argument is the text value "string", then the value of the object element is converted to an ObjectScript string value. The JSON null value is converted to the empty string; the values dervied from JSON false, JSON true and a JSON format number will keep their JSON textual representation; an ObjectScript numeric value will use its ObjectScript canonical numeric representation (this includes the IEEE floating-point values for $DOUBLE("nan") and $DOUBLE("inf")); JSON array and JSON object values (represented by %DynamicArray and %DynamicObject oref values) and any other ObjectScript oref values are given their default ObjectScript conversion to string representation (e.g., "99@%Library.DynamicArray").

If the 'type' argument is "string>base64" then the value is first converted using the string type and then that result is encoded using Base64 encoding. The characters of the string value must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the string contains a character value greater-than %CHAR(255) then a <WIDE CHAR> error is signaled.

If the 'type' argument is "string<base64" then the string value of the element must contain a Base64 encoded string and the string characters are decoded into binary bytes. If a character not supported by the Base64 encoding is encountered then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.

If the 'type' argument is "stream" then the value of the object element is converted to a string value and then that string value is loaded into a newly created %Stream.DynamicCharacter object or a newly created %Stream.DynamicBinary object. The oref of the newly created %Stream becomes the return value of %Get(...). Unlike ObjectScript string values, converting a large object element into a %Stream.DynamicCharacter object or a %Stream.DynamicBinary object will never signal the <MAXSTRING> error (although it may signal <STORE> if the memory capacity of the process is exceeded.) The "stream" 'type' will convert object elements using the same conventions and conversions as the "string" 'type' value.

If the 'type' argument is "stream>base64" then the value of the object element is first converted to a string value. Then that string value is encoded using Base64 conventions and loaded into a newly created %Stream.DynamicBinary object whose oref will become the return value of %Get(...). Unlike ObjectScript string values, converting a large object element into a %Stream.DynamicBinary object will never signal the <MAXSTRING> error (although it may signal <STORE> if the memory capacity of the process is exceeded.) The "stream>base64" 'type' will convert object elements using the same conventions, conversions, restrictions and errors as the "string>base64" 'type' value.

If the 'type' argument is "stream<base64" then the value of the object element is first converted to a string value. Then that string value is decoded using Base64 conventions and loaded into a newly created %Stream.DynamicBinary object whose oref will become the return value of %Get(...). Unlike ObjectScript string values, converting a large object element into a %Stream.DynamicBinary object will never signal the <MAXSTRING> error (although it may signal <STORE> if the memory capacity of the process is exceeded.) The "stream<base64" 'type' will convert object elements using the same conventions, conversions, restrictions and errors as the "string<base64" 'type' value.

If the 'type' argument is "json" then the value of the selected object element is converted to the corresponding JSON value. Note that converting the following object element values to JSON will signal the <ILLEGAL VALUE> error: the $DOUBLE values for a NaN and an Infinity. Converting any oref value that does not refer to an object of the %DynamicObject class or the %DynamicArray class will signal some form of illegal value or not supported error.

There is a possible workaround for the case where dao.%Get(key,,"json") signals a not supported error when the dao element is an ObjectScript oref value. You can modify the class of that object to be "JSON enabled" by inheriting the %JSON.Adapter class. You will then be able to call the %JSONExportToString()(...) method to convert that class object to JSON text that can be imported back into an IRIS system.

  Set Result = dao.%Get(key,,"json")
  ;; could be replaced by
  Set Status=dao.%Get(key).%JSONExportToString(.Result)
  
method %GetIterator() as %Iterator.Object [ Language = objectscript ]
Inherited description:

Perform an iteration of all the values in a %DynamicAbstractObject subclass.

In the example below, we will output all values contained in a %DynamicArray or a %DynamicObject.

     set iter = AbstractObject.%GetIterator()
     while iter.%GetNext(.key , .value ) {
        write "key = "_key_" , value = "_value,!
     }
  
method %IsDefined(key) as %Boolean [ Language = objectscript ]
Tests if a key is defined within an object.

key The key name of the value you wish to test.

Returns A %Boolean value to show if a value is defined (1) or not (0).

method %Remove(key) as %DynamicAbstractObject [ Language = objectscript ]
Remove the element with the named key from the %DynamicObject. If the value of the element is an embedded %DynamicArray or %DynamicObject, remove all subordinate nodes as well.

key The key name of the %DynamicObject element you wish to remove.

Returns The value of the removed %DynamicObject element.

method %Set(key, value, type) as %DynamicAbstractObject [ Language = objectscript ]
Create a new value or update an existing value.

key The key name of the value you wish to create or update.

value The new value with which to update the previous value or create a new value.

type OPTIONAL, the 'type' of the value being assigned.

If the 'type' argument is present then its value must be one of the following string values:

""          - %Set(key,value) without conversions
"null"        - "" becomes null; else assign with no conversion
"boolean"      - 0/nonzero becomes JSON false/true
"number"      - Convert to numeric value
"string"       - Convert to text string
"string>base64"  - Convert to text string then encode into base64
"string<base64"  - Convert to text string then decode from base64
"stream"      - %Stream contents converted to text string
"stream>base64" - %Stream contents are encoded into base64 string
"stream<base64" - %Stream is decoded from base64 into byte string

Returns An OREF to the current modified object, allowing calls to %Set()() to be nested.

If the 'type' argument is the empty string then ObjectScript 'value' argument is stored in the object without conversion.

If the 'type' argument is "null" and the 'value' argument contains the empty string then the JSON value null is stored in the object element; all other ObjectScript values are stored without conversion.

If the 'type' argument is "boolean" then the 'value' argument is first converted to a number. If that value is zero then the JSON value false is stored; otherwise the JSON value true is stored.

If the 'type' argument is "number" then the 'value' argument is converted to an ObjectScript numeric representation before being stored.

If the 'type' argument is "string" then the 'value' argument is converted to string representation before being stored.

If the 'type' argument is "string>base64" then the 'value' argument is converted to string representation and then the Base64 encoding of that string is stored. The characters of the string value must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the string contains a character value greater-than %CHAR(255) then a <WIDE CHAR> error is signaled.

If the 'type' argument is "string<base64" then the 'value' argument is converted to string representation and then the Base64 decoding of that string is stored. If a character not supported by the Base64 encoding is encountered then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.

If the 'type' argument is "stream" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The entire contents of the %Stream are stored in the object element as a string value.

If the 'type' argument is "stream>base64" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The entire contents of the %Stream must consist of binary characters and the Base64 encoding of those characters are stored in the object element as a string value. The characters in the %Stream must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the %Stream contains a character value greater-than %CHAR(255) then a <WIDE CHAR> error is signaled.

If the 'type' argument is "stream<base64" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The contents of that %Stream are decoded using Base64 conventions and the result is stored in the object element as a string value. If a character not supported by the Base64 encoding is encountered in the %Stream then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.