%Library.DynamicAbstractObject

Class %Library.DynamicAbstractObject Extends %Library.AbstractSet [ Abstract, ClassType = dynamic, System = 1 ]

For information on the API provided by this superclass, see Using Dynamic Entities.

Dynamic Entity base class.

Methods

clear

Method clear() [ CodeMode = call ]

remove all elements of the current set, throws an exception if this operation is not supported or the set cannot be cleared.

contains

Method contains(key As %DataType) As %Boolean [ CodeMode = expression ]

return true if the key is currently an element of the set, false otherwise.

containsAll

Method containsAll(array As %Library.DynamicArray) As %Boolean

return true if the set contains() all key[n] where 0≤n≤ size(array)

get

Method get(key As %DataType) As %Library.Any [ CodeMode = expression ]

get the element identified by key

iterator

Method iterator() As %Iterator [ CodeMode = call ]

return an iterator over the elements of this set

put

Method put(key As %DataType, value As %Library.Any, type As %Library.String) As %Library.DynamicAbstractObject [ CodeMode = call ]

put the value into the set with the element name (id) of key. If an element with this key is already present in the set then that element's value is replaced by value

parameters:

• key: key to put into the set
• value: value to put into the set
• type: type of the value, refer to %GetTypeOf for a list of supported types

returns:

• oref referencing the modified DAO, this may be different from the current oref

throws:

• exception

putAll

Method putAll(key As %Library.DynamicAbstractObject, value As %Library.DynamicArray) As %Library.DynamicAbstractObject

put all {keys[n], values[n]} elements where 0≤n≤ size(keys) into the DAO

parameters:

• keys: array of keys to put into the DAO
• values: array of values to put into the DAO

returns:

• oref referencing the modified DAO

throws:

• exception

putIfAbsent

Method putIfAbsent(key As %DataType, value As %Library.Any) As %Library.AbstractSet

put the {key, value} element into the set. If contains(key) is false or get(key) is null then put(key,value)

parameters:

• key: key to put into the set
• value: value to put into the set returns:
• oref referencing the modified set

throws:

• exception

putAllIfAbsent

Method putAllIfAbsent(key As %Library.DynamicAbstractObject, value As %Library.DynamicArray) As %Library.DynamicAbstractObject

put all {keys[n], values[n]} elements where 0≤n≤ size(keys) and keys[n] is not already associated with a value in the set.

parameters:

• keys: array of keys to be put into the set
• values: array of values to be put into the set

returns:

• oref referencing the modified set

throws:

• exception

remove

Method remove(key As %DataType) As %Library.Any [ CodeMode = expression ]

remove the element identified by key from the set

parameters:

• key: key of element to be removed from the set

returns:

• the removed element or null if that element doesn't exist

throws:

• exception

removeAll

Method removeAll(key As %Library.DynamicArray) As %Library.DynamicArray

remove all elements identified by keys[n] where 0≤n≤ size(keys) from the set

parameters:

• keys: array of keys to be removed from the set

returns:

• array of removed elements (null element if key doesn't exist)

throws:

• exception

removeIf

Method removeIf(expression As %RawString) As %Library.DynamicArray [ Abstract ]

remove all of the elements matching the expression

parameters:

• expression: elements matching expression are to be removed

returns:

• array of removed elements (null element if key doesn't exist)

throws:

• exception

rename

Method rename(currentkey As %DataType, newkey As %DataType) As %DataType

replace the key of the element identified by currentKey with newKey

parameters:

• currentkey - current key of the element to be renamed
• newkey - new key to assign to the element returns:
• the current key if the element exists, null otherwise

throws:

• exception

replace

Method replace(key As %DataType, value As %Library.Any) As %Library.Any

replace the value of the element identified by key with value

parameters:

• key - key of the element to be replaced
• value - new value of the element returns:
• return the previous value of the element

throws:

• exception

replaceAll

Method replaceAll(key As %Library.DynamicArray, value As %Library.DynamicArray) As %Library.DynamicArray

replace all {keys[n], values[n]} members, return an array containing the replaced values

parameters:

• keys: array of keys of the elements to be replaced
• values: array of values of the elements

returns:

• array of previous element values

throws:

• exception

size

Method size() As %Integer [ CodeMode = call ]

return the number of elements in the current set

toString

Method toString() As %String [ CodeMode = expression ]

The toString() method returns the contents of a set as a string.

%OnClose

Method %OnClose() As %Status

%GetTypeOf

Method %GetTypeOf(key As %DataType) As %String

Find out the type of value.

Returns One of the following strings are returned.
"null" - JSON null
"boolean" - Either "true" or "false"
"number" - Any numeric value
"oref" - An %ObjectHandle (an ObjectScript oref)
"object" - A nested object
"array" - A nested array
"string" - Normal text string
"unassigned" - The value is unassigned

%Size

Method %Size() As %Integer

Find the size of an %DynamicArray or a %DynamicObject.

Returns An integer showing the size of the array or object. In the case of an array, the size includes unassigned entries within the array. In the case of an object, the size only includes elements that have assigned values.

%FromJSON

ClassMethod %FromJSON(str As %RawString) As %DynamicAbstractObject

Given a JSON source, parse the source and return an object of type %DynamicAbstractObject. If an error occurs during parsing, an exception will be thrown.

str The input can be from a number of sources

(1) A string value containing the source.
(2) A stream object to read the source from.

Returns An object of type %DynamicAbstractObject containing the parsed JSON.

NOTE: RFC 7159 specifies that the default encoding for JSON values uses UTF-8. This implies that for streams not containing 16-bit Unicode it may be necessary to explicitly convert individual character values via a call to $ZCONVERT (e.g. $zcvt(value,"I","UTF8") ) or entire streams by setting the TranslateTable attribute of the stream to "UTF8". set filename = "c:/iscsrc/json/greg4.json" set stream = ##class(%Stream.FileCharacter).%New() set sc = stream.LinkToFile(filename) if ('sc) { w "Error on linking file "_filename,! q } try { set obj = ##class(%DynamicAbstractObject).%FromJSON(stream) } catch ex { w "Error. Unable to parse file "_filename,! w "Error type "_ex.Name,! w "Error code "_ex.Code,! w "Error location "_ex.Location,! set obj = "" } q obj

set src = "{""name"" : ""greg"", ""weight"" : 220 }" set obj = ##class(%DynamicAbstractObject).%FromJSON(src)

An alternative in the catch block, to see formatted exception information, is to do $SYSTEM.OBJ.DisplayError(%objlasterror).

%FromJSONFile

ClassMethod %FromJSONFile(filename As %RawString, TranslateTable As %String = "UTF8") As %DynamicAbstractObject

Given a filename, parse the contents and return an object of type %DynamicAbstractObject. If an error occurs during parsing, an exception will be thrown. See the example in %FromJSON for how to handle an exception.

filename A file URI where the JSON source can be read. By default, the file must be encoded as UTF8.

TranslateTable An optional parameter specifying the character encoding used in the JSON source file. If the parameter is missing, the file will use the "UTF8" encoding. See Translation Tables for other available Translation Tables.

Returns An object of type %DynamicAbstractObject containing the parsed JSON.

%FromJSONStats

ClassMethod %FromJSONStats(str As %RawString, stats As %RawString) As %DynamicAbstractObject [ Internal ]

INTERNAL ONLY!

The %FromJSONStats(...) method is for internal use only. The actions taken by this method may change in the future as additional capabilities are added to %DynamicAbstractObject class objects.

%ToJSON

Method %ToJSON(outstrm As %Stream.Object) As %String

Convert a %DynamicAbstractObject into a JSON string.

outstrm is optional. There are a number of possibilities:
(1) Parameter outstrm is not defined and the method is called via 'DO'. In this case the JSON string is written to the current output device.
(2) Parameter outstrm is not defined and the method is called as an expression. In this case the JSON string becomes the value of the expression.
(3) Parameter outstrm is defined. If it is %Stream object then the JSON string will be written to the stream. If outstrm is present but not an object then it is presumed to be a fully qualified file specification. In that case, a %Stream.FileCharacter stream is created, linked to that file and the JSON string is written to that stream. On completion, this stream is saved. The full path to the file must be defined. If outstrm is an object but is not an instance of %Stream.Object then an exception will be thrown.

NOTE: RFC 7159 specifies that the default encoding for JSON values uses UTF-8. When writing a stream containing 8-bit characters this implies that it may be necessary to explicitly convert individual values via a call to $ZCONVERT (e.g. $zcvt(value,"O","UTF8") ) or entire streams by setting the TranslateTable attribute of the stream to "UTF8" set obj = {"title" : "MR" , "lastname" : "JONES"} set obj.firstname = "JIMMY" do obj.%ToJSON() {"title":"MR","lastname":"JONES","firstname":"JIMMY"} set source = obj.%ToJSON() write source {"title":"MR","lastname":"JONES","firstname":"JIMMY"}

%FromPVA

ClassMethod %FromPVA(Global As %String) As %DynamicAbstractObject [ Internal ]

This method is for INTERNAL USE only. It's specifications will change in the future.

Convert the Packed Vector Array binary representation (PVA representation) stored in a global array into a tree of class objects defined the %DynamicAbstractObject subclasses. The subclass of objects from the $DynamicAbstractObject classes will be abbreviated as the %DAO objects. The PVA binary representation can be created by executing
DO DynObj.%ToPVA(Global)

The conversion can be done by evaluating:
SET dao=##class(%DynamicAbstractObject).%FromPFA(Global) which sets the local variable 'dao' to be a reference of the root of a tree of %DAOs described in the global array 'Global'.

Global is the $NAME representation of the root of a global subtree.

If you execute
SET dao=##class(%DynamicAbstractObject).%FromPVA("^Docs(""alpha"",""book1"")")
or execute
SET dao=##class(%DynamicAbstractObject).%FromPVA($NAME(^Docs("alpha","book1"))
then the binary PVA will be extracted from the data under the global ^Docs(alpha,book1).

In the future the %FromPVA(Stream,Global) will accept PVA binary data from a %Stream and will distribute it into the 'Global' array entry.

%ToPVA

Method %ToPVA(Global As %String) As %Status [ Internal ]

This method is for INTERNAL USE only. It's specifications will change in the future.

Convert an object of the %DynamicAbstractObject subclass into the binary Packed Vector Array representation which will be stored into global tree by executing DO DynObj.%ToPVA(Global).

Global is the $NAME representation of the root of a global subtree.

If you execute DO DynObj.%ToPVA("^Docs(""alpha"",""book1"")")
or execute DO DynObj.%ToPVA($NAME(^Docs("alpha","book1"))
then binary data will be created under ^Docs(alpha,book1).

The preexisting data at ^Docs(alpha,book1) will be KILL-ed.

The newly created data will look like: ^Docs(alpha,book1,0,0),...,^Docs(alpha,book1,0,N0-1) where the binary data is broken in 'N0' chunks of binary strings. The binary strings always contain 8-bit binary bytes, even on Unicode instances of IRIS. Complicated %DynamicAbstractObject objects may also generate additional subtrees of the form ^Docs(alpha,book1,1,0), ..., ^Docs(alpha,book1,1,N1-1) where additional binary data is broken into 'N1' chunks of binary strings. And %ToPVA may need to generate additional chunks, like ^Docs(alpha,book1,i,j), when the necessary. These additional chunks are created to simplify generation and retrieval of the binary Packed Vector Array data.

ConvertStreamToValue

Method ConvertStreamToValue(value) As %DynamicAbstractObject [ Internal, Private ]

The parameter 'value' must be a %Stream. The contents of 'value' will be placed in a %DynamicString, %DynamicBinary or %DynamicBase64 object.

Returns The generated %DynamicString, %DynamicBinary or %DynamicBase64 object.

%GetObjectType

Method %GetObjectType() As %Integer [ Internal ]

%GetIterator

Method %GetIterator() As %Iterator.AbstractIterator [ Abstract ]

Performs an iteration over all the values in a %DynamicAbstractObject subclass. Adding or removing an element of the %DynamicAbstractObject subclass will cause further calls on the %GetNext(.key,.value,.type) method to have undefined behavior.

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, .type ) { write "key = "_key_", value = "_value_", type = "_type,! } See the descriptions of the %GetNext in the %Iterator.Array and %Iterator.Object classes for more details.

ToZWrite

Method ToZWrite() As %String [ Internal ]

INTERNAL USE ONLY.

The ToZWrite() method is for internal use only. It provides output for the ZWRITE command. It returns the contents of a %DynamicAbstractObject as a %String using combined JSON/%String syntax.

set obj = {"NaNvalue" : ($DOUBLE("NAN")), "Infinity":($DOUBLE("Inf"))} write obj.ToZWrite()

%SetKeyMap

Method %SetKeyMap(keymap As %DynamicKeyMap, flags = 0) As %Integer [ Internal ]

INTERNAL ONLY!

The %SetKeyMap(keymap) method is for internal use only. The actions taken by this method may change in the future as additional capabilities are added to %DynamicAbstractObject class objects.

The statement SET count=dao.%SetKeyMap(dkm) will attach the %DynamicKeyMap dkm to the %DynamicAbstractObject dao, replacing the key map that was previously attached to dao. If dao is a %DynamicObject then its internal key index array will be modified to use the dkm %DynamicKeyMap. If necessary, additional key names will be added to the dkm key map. The count value returned by the %SetKeyMap(dkm) call is a count of the number of the key name strings added to the dkm key map. If the dkm key map is not modified by %SetKeyMap then the value zero is returned.

dkm is the %DynamicKeyMap to replace the key map currently used by the %DynamicAbstractObject.

flags is optional. When present it is a bit encoded integer of flag values. The 0x1 bit clears the key map value used by a %DynamicArray. The 0x2 bit clears the key map values used by a %DynamicObject BUT the key index arrays of the %DynamicObject are modified to conform to the new dkm key map ordering. Returns The count of the number of key name strings added to the dkm key map.

%SetKeyMapRecursive

Method %SetKeyMapRecursive(keymap As %DynamicKeyMap, flags = 0) As %Integer [ Internal ]

INTERNAL ONLY!

The %SetKeyMapRecursive(keymap) method is for internal use only. The actions taken by this method may change in the future as additional capabilities are added to %DynamicAbstractObject class objects.

The statement SET count=dao.%SetKeyMapRecursive(dkm) will attach the %DynamicKeyMap dkm to the %DynamicAbstractObject dao and to all decendant %DynamicAbstractObject-s in the tree rooted at dao. Every %DynamicObject in the tree rooted at dao will have its internal key index array modified to use the dkm %DynamicKeyMap. If necessary, additional key names will be added to the dkm key map. The count value returned by the %SetKeyMap(dkm) method call is a count of the number of the key name strings added to the dkm key map. If the dkm key map is not modified by %SetKeyMapRecursive then the value zero is returned.

dkm is the %DynamicKeyMap to replace the key maps currently used by the %DynamicAbstractObject-s in the tree rooted at dao.

flags is optional. When present it is a bit encoded integer of flag values. The 0x1 bit clears the key map value used by any %DynamicArray in the tree of %DynamicAbstractObject-s. The 0x2 bit clears the key map value used by any %DynamicObject in the tree of %DynamicAbstractObject-s, BUT the key index arrays of the %DynamicObject are modified to conform to the new dkm key map ordering.

Returns The count of the number of key name strings added to the dkm key map.

%GetKeyMap

Method %GetKeyMap() As %DynamicKeyMap [ Internal ]

INTERNAL ONLY!

The %GetKeyMap() method is for internal use only. It returns a reference to the %DynamicKeyMap associated with a %DynamicAbstractObject. The formats and semantics of a key map are known only to the routines and methods that implement the %DynamicAbstractObject class and its subclasses. These formats, semantics, routines and methods may change in the future as additional capabilities are added to %DynamicAbstractObject class objects.

The %GetKeyMap() method returns a reference to the %DynamicKeyMap used by the %DynamicArray or %DynamicObject. Adding additional key names to this key map will also affect the key map currently attached to the %DynamicAbstractObject, and vice versa. If a %DynamicArray or %DynamicObject has no associated key map then %GetKeyMap() returns the empty string.

Most %DynamicObject class objects have a KeyMap attached. When a %DynamicObject is created by the %FromJSON method, abd when there are other %DynamicObject-s created in the same %FromJSON call then all those %DynamicObject-s will share the same KeyMap. A %DynamicArray created by the %FromJSON method may also have a shared KeyMap attached if there was a %DynamicObject created in the same %FromJSON method call.

%GetSwizzleObject

Method %GetSwizzleObject(force As %Integer = 0, ByRef oid As %ObjectIdentity) As %Status [ ServerOnly = 1 ]

%GetSerial

Method %GetSerial(force As %Integer = 0) As %String [ CodeMode = expression, ServerOnly = 1 ]

%SetSerial

ClassMethod %SetSerial(val As %String) As %Status [ CodeMode = expression, ServerOnly = 1 ]

%SetDocumentMetadata

Method %SetDocumentMetadata(documentID As %RawString, documentVersion As %Integer, collectionName As %String(MAXLEN=""), localID As %Integer(MINVALUE=1) = "")

%GetDocumentCollection

Method %GetDocumentCollection() As %RawString

getDocumentCollection

Method getDocumentCollection() As %RawString [ CodeMode = call ]

getDocumentId

Method getDocumentId() As %RawString [ CodeMode = call ]

toJson

Method toJson(outstrm As %Stream.Object) As %RawString [ CodeMode = call ]

getDocumentVersion

Method getDocumentVersion() As %Integer [ CodeMode = call ]

%GetDocumentID

Method %GetDocumentID() As %RawString

%GetDocumentLID

Method %GetDocumentLID() As %RawString [ Internal ]

%GetDocumentVersion

Method %GetDocumentVersion() As %Integer

%GetDocumentMetadata

Method %GetDocumentMetadata(Output documentID As %RawString, Output documentVersion As %Integer, Output collectionName As %String(MAXLEN=""), Output localID As %Integer(MINVALUE=1) = "") [ Internal ]

%SetDocumentCollection

Method %SetDocumentCollection(collection As %RawString) [ Internal ]

%SetDocumentID

Method %SetDocumentID(documentID As %RawString) [ Internal ]

%SetDocumentLID

Method %SetDocumentLID(localID As %RawString) [ Internal ]

%SetDocumentVersion

Method %SetDocumentVersion(version As %Integer) [ Internal ]

%SetMetadata

Method %SetMetadata(key As %DataType, value As %RawString) [ Internal ]

%GetMetadata

Method %GetMetadata(key As %DataType) As %RawString [ Internal ]

toPVA

Method toPVA(gloref, options = 0) As %Integer [ Internal ]

INTERNAL ONLY!

$toPVA() serializes an AbstractObject instance into a packed vector array. The key names can be optionally included, excluded or only the key names included (no data). The form of the packed vector array is not public and the only way to access data serialized as PVA is to extract it from the PVA using $fromPVA.

This method accepts two arguments. The first is the name of the reference where the PVA will be placed. That reference can be a local variable expression or a global variable expression. Typically, this is produced using the $Name function.
USER>set obj = {"name":"test PVA","stuff":"misc"} USER>set id = 6 do obj.$toPVA($Name(mypva(id))) USER>zw mypva mypva(6,1)=

The above example is using a local variable but it could be a global reference, simply place the '^' in front of the variable name.

The encoding of the data is proprietary and direct access is not supported.

The second argument, options, is used to control whether or not the key names are included in the packed vector array.

0x00 - do not include the key names, only include data

0x01 - include the key names and the data

0x02 - means this is the key map being dumped.

If the key name map is not included in the packed vector array (options = 1) then the key names cannot be recovered when extracting the contents of the packed vector array. Normally the key name map would be supplied as a separate argument passed to $fromPVA() in that case.

This function returns the length of the packed vector.

fromPVA

ClassMethod fromPVA(gloref As %RawString, keymap = "") As %Library.DynamicAbstractObject [ Internal ]

INTERNAL ONLY!

fromPVA() extracts the contents of a packed vector array (PVA) into an instance AbstractObject. The form of the packed vector array is not public and the only way to construct a PVA is to invoke $toPVA. This method accepts two arguments. The first is the name of the variable where the PVA is located. That reference can be a local variable expression or a global variable expression. Typically, this is produced using the $Name function. The optional second argument is the key name map. If the packed vector array contained in the reference passed as the first argument includes the key name map then the key name map does not need to be passed as a separate argument. If the packed vector array does not contain the key name map then it must be supplied. The key name map is expected to be an instance of %Library.Array. The key name map can be extracted from a packed vector array or it can be retrieved by invoking $getKeyNameMap. To serialize the key name map as a packed vector array, refer to $toPVA.

USER>k USER>set obj = {"name":"test PVA","stuff":"misc"} USER>set id = 6 do obj.$toPVA($Name(mypva(id)),$zh("1")) USER>set obj2 = ##class(%Library.AbstractObject).$fromPVA($Name(mypva(id))) USER>write obj2.$toJSON() {"name":"test PVA","stuff":"misc"}

The encoding of the data is proprietary and direct access is not supported.

The above example is using a local variable but it could be a global reference, simply place the '^' in front of the variable name.

%Clear

Method %Clear() As %Library.DynamicAbstractObject

Remove all the data from the dynamic object, leaving a blank object intact. return $this to allow chaining.

%Clone

Method %Clone() As %DynamicAbstractObject [ Internal ]

%FromOref

ClassMethod %FromOref(source As %Library.AbstractSet) As %DynamicAbstractObject

%FromOref() will return an instance of %DynamicAbstractObject populated from the source object.

request object

Name	Description
source	Oref of the object to be cast as a DynamicAbstractObject.
returnValue	An oref referencing the DynamicAbstractObject.

set person = ##class(Sample.Person).%OpenId(50) set object = ##class(%DynamicObject).%FromOref(person)

%FromObject

ClassMethod %FromObject(source As %Any) As %DynamicAbstractObject

%FromObjectSwizzle

ClassMethod %FromObjectSwizzle(oref As %Any, property As %String) As %DynamicAbstractObject

%FromObjectMulti

ClassMethod %FromObjectMulti(oref As %Any, property As %String) As %DynamicAbstractObject

addList

ClassMethod addList(type, ByRef json, ByRef source)

"_isLabeled"

Method "_isLabeled"() As %Boolean [ CodeMode = expression ]

@Override