Selects items into a select list.
SELECT dynarray [TO listnum] [SETTING var] [ON ERROR statements]
SELECT [filevar] [TO listnum] [SETTING var] [ON ERROR statements]
SELECT dynarray TO listname [SETTING var] [ON ERROR statements]
SELECT [filevar] TO listname [SETTING var] [ON ERROR statements]
SELECTN dynarray [TO listnum] [ON ERROR statements]
SELECTN [filevar] [TO listnum] [ON ERROR statements]
SELECTV dynarray TO listname [ON ERROR statements]
SELECTV [filevar] TO listname [ON ERROR statements]
||Any valid dynamic array of Field Values.
||Optional A local variable used as the file identifier of an open MultiValue file. This variable is set by the OPEN statement. If omitted, the default file variable is used.
||Optional A numbered select list, specified as an integer from 0 through 10. You must specify a listnum from 1 through 10; listnum 0 is not valid for Caché MVBasic. If omitted, select list 0 is used.
||A named select list, specified as a local variable name. (See Emulation section below.)
||Optional When an error occurs, sets the local variable var to the operating system's error return code. Successful completion returns 0; error return codes are platform-specific. The SETTING clause is executed before the ON ERROR clause. Provided for jBASE compatibility.
statements select the field identifiers from a MultiValue file or a dynamic array and place them in a select list. You can then use READNEXT
to read this select list, one field identifier at a time. Selecting to a select list overwrites any previous values for that select list.
can select into a numbered select list or a named select list. (See Emulation section below.)
can only select into a numbered select list.
can only select into a named select list.
You can use SELECTE
to copy numbered Select List 0 to a named select list.
statements sort the contents of a select list or file into Caché storage order: first the empty string, then canonical numbers in ascending numeric order, then strings in string collation order. They then place the results in a select list. SELECT
does not sort the contents of a file system directory or the elements of a dynamic array. These are copied into a select list in the order listed. To sort dynamic array elements, first use SELECT
to copy the elements into a select list, then use SELECT
on that select list.
The optional ON ERROR clause specifies one or more MVBasic statements to execute if the SELECT
operation fails. For example, if you specify an invalid listnum
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.
For SELECT filevar
, you must specify a MultiValue file opened using the OPEN
statement. The SELECT
completes successfully even if filevar
is not defined, but a subsequent READNEXT
places a direct reference to filevar
in the newly created select list; the select list does not contain a copy of the file contents. Therefore, any subsequent change to the filevar
file will immediately change the contents of this previously selected select list. To avoid this, you can specify $OPTIONS FSELECT
before invoking SELECT filevar
. If the FSELECT flag option is activated, SELECT filevar
creates a select list containing a copy of the indices from the file referenced by filevar
; subsequent changes to the filevar
file will have no effect on the contents of this previously selected select list. The FSELECT option is off (inactive) by default. Using the FSELECT option makes the length of the select list immediately available after executing the SELECT filevar
statement. However, performing a SELECT filevar
with the FSELECT option enabled has poorer performance than a SELECT filevar
Selecting an Index
You can use SELECT
with a named select list to select an entire index. The index must have been opened using an OPENINDEX
statement. After selecting the index, you can read individual index items using the READNEXT KEY
SELECT and SSELECT
(sorted select) statements sort in ordinary string collation order. SSELECT filevar
always creates a select list containing a copy of the indices from the file referenced by filevar
, regardless of the $OPTIONS FSELECT
setting. The SELECT
statements are otherwise comparable to the corresponding SSELECT
By default, SELECT
can select to a numbered select list or to a named select list. Any TO clause variable that resolves to an integer from 0 through 10 is treated as a numbered select list; any other value is treated as a named select list. SELECT
uses select list 0 as the default select list for both internal and external use. These are the defaults for Caché, jBASE, and UniData emulation.
D3, IN2, MVBase, PICK, R83, POWER95, Reality, and Ultimate set $OPTIONS VAR.SELECT
. This requires that the select list specified in the TO clause must be a named select list; SELECT
behaves like SELECTV
. These emulations return an error when you specify a numeric value for the TO clause. Select List 0 is used as the default when you omit the TO clause.
INFORMATION, PIOpen, Prime, and UniVerse set $OPTIONS SELECT.ANY
This requires that the select list specified in the TO clause must be a numbered select list; SELECT
behaves like SELECTN
. These emulations return an error when you specify a non-numeric value for the TO clause.
D3, IN2, MVBase, R83, POWER95, and Reality set $OPTIONS PICK.SELECT
. This causes SELECT
to use two distinct default select lists, one internal and one external. The default external select list is 0, and the default internal select list is 10.
UniData sets $OPTIONS FSELECT
by default; for Caché and all other emulations FSELECT is inactive by default. This causes SELECT
to set both @SELECTED
when using Select List 0. For any other select list, only @SELECTED is set. All other emulations only set @SELECTED.
D3, IN2, jBASE, MVBase, PICK, R83, POWER95, and Ultimate set $OPTIONS NO.RESELECT
. This prevents the reselecting of a select list; a second SELECT
is ignored when referencing an active unused or partially used select list. For D3, jBASE, MVBase, R83, POWER95, and Ultimate, $OPTIONS ARRAY.RESELECT
is also set by default, overriding NO.RESELECT for a dynamic array.
The following example illustrates the use SELECT dynarray
copies all of the field mark identifiers into Select List 3. The @SELECTED
system variable contains the number of elements selected (in this case, 4). Each iteration of READNEXT
reads the next field mark identifier from Select List 3 into the area
SELECT regions TO 3 ON ERROR PRINT "Select failed"
FOR x=1 TO 5
READNEXT area FROM 3
The following example illustrates the use of the SELECTV
copies all of the field mark identifiers into a Select List named rfields
. Each iteration of READNEXT
reads the next field mark identifier from Select List rfields
into the area
SELECTV regions TO rfields ON ERROR PRINT "Select failed"
FOR x=1 TO 5
READNEXT area FROM rfields
© 1997-2019 InterSystems Corporation, Cambridge, MA