For information on converting to InterSystems IRIS, see the
InterSystems IRIS Adoption Guide
and the InterSystems IRIS In-Place Conversion Guide,
both available on the WRC Distributions page (login required).
The SelectList class is for internal use in the InterSystems Cache MultiValue
product. The internals of this class can be changed by InterSystems
without prior notice. Application code should not inherit this class nor
should application code manipulate the properties and methods in this class.
The class may be examined for the purpose of debugging MultiValue applications.
The SelectList class represents an MVBASIC Select variable in various states such as:
1) Traversing through values supplied via a dynamic array SELECT var TO list
2) Traversing through the item IDs represented in a Global or a directory
3) Traversing through values taken from a different list SELECT list TO list
4) Traversing through values in an index
Because there are various states associated with each type of list, a class with
appropriate properties to track these states is required.
property %Count as %Integer [ InitialExpression = 0 ];
This value is an integer count of the number of elements that the list contains. We
don't always know this value (for instance if this is traversing the items in Global
representing an MV file we don't want to $order() the lot just to find out we have
6,000,000 elements we can read. However after CMQL statements or if we have done a writelist
or readlist or something similar we can count the elements as we go without much of a
penalty and can store the value here. If we know we have elements in the list but not how
many then we store -1 in this value, otherwise it is 0 when we create an object.
property %InReverse as %Integer [ InitialExpression = 0 ];
A select list can be read forwards or backwards and my change direction
at any time. In this case, we have a boundary condition when the first
READPREV or READFORWARD is called and when we change direction on some
types of selectlist. To cater for this we always return the key that
is currently being flagged as the LASTID, if this flag is set to 1 and the
operation is a READPREV. The list is so arranged that READNEXT does not need
to worry about this as the last ID will always be the one that WAS last
returned to a READNEXT.
property %IndexColl as %Integer [ InitialExpression = 0 ];
A select list can represent an index. An index stores the actual keys
as oppposed to the key values returned by READNEXT in collated encoding
sequence such as MV R or SPACE (equivalant to MV L) etc.
This property defines the collation in use for the index.
property %IndexFlags as %Integer [ InitialExpression = 0 ];
When the select list is of Type = 2, then we need to know the type
of the index that is being traversed. At the moment, we only allow standard
indexes to be traversed (not bitmap and bitslice), but I have specified these
types here for future examination. If it were not for the fact that we must
be able to traverse the index backwards, we would use SQL cursors to traverse
indexes, however, MVBASIC expects to be efficient and so we traverse the structure
directly in the associated globals as this is readonly access.
Future enhancements should include returning the associated data stored with
the index - IE the data that is stored with the index key that does not form
the actual key.
1 - Single valued index, no multivalues
2 - Multivalued index, no key (MV position stored)
4 - Multivalued index, includes key (MV position)
8 - This is an index variable generated by SELECTINDEX
Holds the value of the last element read from the list.
This is used only by those types of lists that are traversing indexes or files, where
the last key used allows us to pick up the next key efficiently
property %NextOffset as %Integer [ InitialExpression = 0 ];
The last offset is the offset within the Values property that should be used
to pick up the next ID. This allows us to optimize the list traversal so that we do
not scan from the start of the value list each time we need the next element
within it. In order to avoid copying the values in the Values property, we
store the values in an mvv variable when first accessed or when another list
reference knocks it out of the Last Used SelectList positions.
This value is a string containing all the values contained in a list that was initialized
from an expression or other dynamic array. It is not normally traversed directly from
the object as we would have to keep copying the value onto the stack before
looking to the next element in the list. We do not use a Cache $list for this
property as it offers little advantage in terms of traversing large lists in sequence.