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.
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.
For dynamic array type select lists, this is the current subscript under Values
This is 0 for normal select lists, 1 for exploded select lists, and 2 for subvalue exploded select lists
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.
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.
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.
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
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.
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
Tracks the last index key that was returned when traversing an index
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
For dynamic array type select lists, this is the maximum subscript under Values
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.
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.
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
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.