%MV.SelectList
class %MV.SelectList extends %Library.RegisteredObject
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 Inventory
- %Count
- %CurSub
- %ExplodeFlag
- %GlobalName
- %InReverse
- %IndexColl
- %IndexFlags
- %IndexName
- %LastReturnedId
- %LastReturnedKey
- %LastReturnedMVPos
- %MaxSub
- %Namespace
- %NextOffset
- %Type
- %Values
Method Inventory
Properties
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 methods: %CountDisplayToLogical(), %CountGet(), %CountIsValid(), %CountLogicalToDisplay(), %CountNormalize(), %CountSet()
property %CurSub as %Integer [ InitialExpression = 0 ];
For dynamic array type select lists, this is the current subscript
under Values
Property methods: %CurSubDisplayToLogical(), %CurSubGet(), %CurSubIsValid(), %CurSubLogicalToDisplay(), %CurSubNormalize(), %CurSubSet()
property %ExplodeFlag as %Integer [ InitialExpression = 0 ];
This is 0 for normal select lists, 1 for exploded select lists, and 2 for
subvalue exploded select lists
Property methods: %ExplodeFlagDisplayToLogical(), %ExplodeFlagGet(), %ExplodeFlagIsValid(), %ExplodeFlagLogicalToDisplay(), %ExplodeFlagNormalize(), %ExplodeFlagSet()
property %GlobalName as %String;
When the SelectList is traversing keys in a Global, we need to know
the name of the global we are traversing, and so we store it here.
Property methods: %GlobalNameDisplayToLogical(), %GlobalNameGet(), %GlobalNameIsValid(), %GlobalNameLogicalToDisplay(), %GlobalNameLogicalToOdbc(), %GlobalNameNormalize(), %GlobalNameSet()
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 methods: %InReverseDisplayToLogical(), %InReverseGet(), %InReverseIsValid(), %InReverseLogicalToDisplay(), %InReverseNormalize(), %InReverseSet()
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 methods: %IndexCollDisplayToLogical(), %IndexCollGet(), %IndexCollIsValid(), %IndexCollLogicalToDisplay(), %IndexCollNormalize(), %IndexCollSet()
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.
Types are:
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
Types are:
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
Property methods: %IndexFlagsDisplayToLogical(), %IndexFlagsGet(), %IndexFlagsIsValid(), %IndexFlagsLogicalToDisplay(), %IndexFlagsNormalize(), %IndexFlagsSet()
property %IndexName as %String;
When the select list is of Type = 2, then we need to know
which index we are traversing so we can construct the global reference.
The name of the index that is being traversed is stored here.
Property methods: %IndexNameDisplayToLogical(), %IndexNameGet(), %IndexNameIsValid(), %IndexNameLogicalToDisplay(), %IndexNameLogicalToOdbc(), %IndexNameNormalize(), %IndexNameSet()
property %LastReturnedId as %String;
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 methods: %LastReturnedIdDisplayToLogical(), %LastReturnedIdGet(), %LastReturnedIdIsValid(), %LastReturnedIdLogicalToDisplay(), %LastReturnedIdLogicalToOdbc(), %LastReturnedIdNormalize(), %LastReturnedIdSet()
property %LastReturnedKey as %String;
Tracks the last index key that was returned when traversing an index
Property methods: %LastReturnedKeyDisplayToLogical(), %LastReturnedKeyGet(), %LastReturnedKeyIsValid(), %LastReturnedKeyLogicalToDisplay(), %LastReturnedKeyLogicalToOdbc(), %LastReturnedKeyNormalize(), %LastReturnedKeySet()
property %LastReturnedMVPos as %Integer [ InitialExpression = 0 ];
Multivalue indices must track the last Key, ItemID and MVPOS while traversing
the index. Hence we need a property to hold the last MVPos that we returned
Property methods: %LastReturnedMVPosDisplayToLogical(), %LastReturnedMVPosGet(), %LastReturnedMVPosIsValid(), %LastReturnedMVPosLogicalToDisplay(), %LastReturnedMVPosNormalize(), %LastReturnedMVPosSet()
property %MaxSub as %Integer [ InitialExpression = 0 ];
For dynamic array type select lists, this is the maximum subscript
under Values
Property methods: %MaxSubDisplayToLogical(), %MaxSubGet(), %MaxSubIsValid(), %MaxSubLogicalToDisplay(), %MaxSubNormalize(), %MaxSubSet()
property %Namespace as %String;
When the selectlist is being used to traverse a global, we need to know the name
space that the global lives in. This property serves that function.
Property methods: %NamespaceDisplayToLogical(), %NamespaceGet(), %NamespaceIsValid(), %NamespaceLogicalToDisplay(), %NamespaceLogicalToOdbc(), %NamespaceNormalize(), %NamespaceSet()
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.
Property methods: %NextOffsetDisplayToLogical(), %NextOffsetGet(), %NextOffsetIsValid(), %NextOffsetLogicalToDisplay(), %NextOffsetNormalize(), %NextOffsetSet()
property %Type as %Integer [ InitialExpression = 0 ];
Indicates what type of select list the object instance is representing:
0 - Simple dynamic array of attributes, stored herein
1 - Item IDs returned from a global
2 - Elements, (keys, IDs and MV positions), returned from an index
0 - Simple dynamic array of attributes, stored herein
1 - Item IDs returned from a global
2 - Elements, (keys, IDs and MV positions), returned from an index
Property methods: %TypeDisplayToLogical(), %TypeGet(), %TypeIsValid(), %TypeLogicalToDisplay(), %TypeNormalize(), %TypeSet()
property %Values as %String [ MultiDimensional ];
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.
Property methods: %ValuesDisplayToLogical(), %ValuesGet(), %ValuesIsValid(), %ValuesLogicalToDisplay(), %ValuesLogicalToOdbc(), %ValuesNormalize(), %ValuesSet()
Methods
method Dump() as %Status
Inherited Members
Inherited Methods
- %AddToSaveSet()
- %ClassIsLatestVersion()
- %ClassName()
- %ConstructClone()
- %DispatchClassMethod()
- %DispatchGetModified()
- %DispatchGetProperty()
- %DispatchMethod()
- %DispatchSetModified()
- %DispatchSetMultidimProperty()
- %DispatchSetProperty()
- %Extends()
- %GetParameter()
- %IsA()
- %IsModified()
- %New()
- %NormalizeObject()
- %ObjectModified()
- %OriginalNamespace()
- %PackageName()
- %RemoveFromSaveSet()
- %SerializeObject()
- %SetModified()
- %ValidateObject()