Request of sorts: creating a help page on community to work with lists/arrays/multidimensional properties/etc

Primary tabs


I am still a beginner with COS and am struggling with these concepts. While digging through the official documentation will eventually tell you everything you need to know, getting started is nevertheless not an easy feat...

Is it possible to create a "lists/array/multidimensional 101" page for beginners? And, for instance, its interaction with $data, what it means to use "as list of something" or "as array of something", how to walk lists, how to add/remove elements, how to extract sublists etc?

At this moment, for me, this is all very confusing, and I think such a page would help me greatly in just, well, getting work done.

Coming from the Java world, I can now just tell that lists are not "objects", you don't really have, say, List<SomeClass> in COS but you can declare #dim x as list of SomeClass... You have functions such as $listfind, $list, $listbuild... I can manage some working code but that's about it :/



This should be in InterSystem's official documentation...

Note, that $list and, for example, %ListOfDataTypes are different concepts.  The first one is a datatype and a second one is an object.

$list and %ListOfDataTypes are different concepts: agreed.  but why does (%Library.ListOfDataTypes).BuildValueArray use $listnext then (and not work)?? LogicalToDisplay() also does not work -- for me.  When I use it on a LostOfDataTypes object.


What am I doing wrong?



Both BuildValueArray and LogicalToDisplay work with serialized form of %ListOfDataTypes object - $list string:

do ##class(%ListOfDataTypes).BuildValueArray($lb("a","b","c"), .out)
zw out



To sum up:

  • %ListOfDataTypes - object
  • serialized %ListOfDataTypes  - $list
  • $list - a string (with special properties, but not an object)
  • %List - $list

Thank you Eduard.  Looks like a serialized ListOfDataTypes is a $list, not a %ListOfDataTypes. 

This would not work (and is not):


TEST>s user=##class(Security.Users).%OpenId("testuser"))

TEST>w user.Roles
TEST>do ##class(%ListOfDataTypes).BuildValueArray(user.Roles,.array)


It does not work because the user.Roles is a %ListOfDataTypes, and not a $list.  Is there anything in the %ListOfDataTypes class that I can use to convert this object's Roles property to a nice looking string or array? Or must I first convert it to a $list?  Why isn't there a function to do that for me?


Thank you,


The  easy way to display list object:

for i=1:1:user.Roles.Count() w user.Roles.GetAt(i),!

You can also serialize list object to $list and display it:

zw user.Roles.Serialize()

Also note that lists of datatypes defined as class properties are of %Collection.ListOfDT class (which is somewhat similar but not identical to %ListOfDataTypes class).

You can also get all information on %ListOfDataTypes objects with zw command:

s b=##class(%ListOfDataTypes).%New()
do b.Insert(1)
do b.Insert(2)
do b.Insert(3)
zw b

Ah, that was the step that was missing -- I had to Serilaize my ListOfDataType object first.  Thank you.

Sorry -- I'm not clear on the difference between %Collection.ListOfDT and %Library.ListOfDataTypes, but seeing as ##class(%Library.ListOfDataTypes).LogicalToDisplay(roles.Serialize(),"|") works... I'm happy.  is it because both objects support it?

Thank you,


Hi Francis

One place to start might be the introduction to Cache ObjectScript and introduction to Cache Objects online courses.  Both take about 45min to an hour to complete.

You can access these with registration here:


Well, I am on it right now but it does not quite answer my question...

Still, it is a useful resource, so I take as many lessons as I deem are useful to me...