Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?


Selects a specified key type into a select list.


SELECT ivar [TO varname] ATKEY keytype[,recID[,vmcount]] [ON ERROR statements]


ivar A local variable used as the index identifier of an open MultiValue file. This variable is set by the OPENINDEX statement.
TO varname Optional — Either a named select list for an index, specified as a variable name, or a select list number. If omitted, select list 0 is used.
keytype The specified index key to select. You can specify the empty string (ATKEY '') if you wish MVBasic to ignore the ATKEY clause and take the recID and/or vmcount values.
recID Optional — A specified record within the index key value at which to start processing.
vmcount Optional — If the record specified in recID is a dynamic array, vmcount specifies which element to start from. Specified as an integer value, beginning with 1 (the default).


The SELECT ATKEY statement selects the index identifiers of the specified type from an index file and places them in a select list. You can then use READNEXT KEY to read this select list, one index identifier at a time. Selecting to a select list overwrites any previous values for that select list.

There are three ways to select an index

  • SELECT selects the entire index into a named select list. You then use READNEXT KEY to read individual index items.

  • SELECT ATKEY selects the specified index key into a named select list. You then use READNEXT KEY to read individual index items.

  • SELECTINDEX selects all the unique index keys into a named select list. You then use READNEXT to read individual index items.

For all three types of index SELECT, you must specify an index file opened using the OPENINDEX statement.

The optional ON ERROR clause specifies one or more MVBasic statements to execute if the SELECT ATKEY operation fails. For example, if you specify an invalid ivar the ON ERROR statements are executed. The statements argument can be the NULL placeholder keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line; there must be a line break between the ON ERROR keyword and the first line.

When you are finished using an assigned select list, you can use the CLEARSELECT statement to reset the select list.


The following example used OPENINDEX to open an index to VOC on the attribute F1. The SELECT ATKEY selects S-type keys from this index to a select list. The READNEXT KEY reads an item from the select list:


See Also