SELECT, SELECTN, SELECTV
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]
|dynarray||Any valid dynamic array of Field Values.|
|filevar||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.|
|TO listnum||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.|
|TO listname||A named select list, specified as a local variable name. (See Emulation section below.)|
|SETTING var||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.|
The SELECT 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.
SELECT can select into a numbered select list or a named select list. (See “Emulation” section below.)
SELECTN can only select into a numbered select list.
SELECTV can only select into a named select list.
You can use SELECTE to copy numbered Select List 0 to a named select list.
Unless otherwise stated, all documented SELECT behavior also applies to SELECTN and SELECTV.
SELECT 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 or SSELECT 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.
SELECT and FORMLIST are functionally identical.
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 statement fails.
SELECT filevar 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 without FSELECT.
Use of FSELECT only applies to a SELECT filevar executed directly as an MVBasic statement. Indirect execution of SELECT filevar, such as EXECUTE 'SELECT filevar', does not apply the FSELECT setting. Executing SELECT filevar from the MultiValue Shell does not apply the FSELECT setting.
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 statement.
If you wish to select only part of an index, you can use the SELECT ATKEY or SELECTINDEX statement.
SELECT and SSELECT
The 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 statements.
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 and SYSTEM(11) 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. SELECT 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 variable:
regions="Northeast":@FM:"Southeast":@FM:"Northwest":@FM:"Southwest" SELECT regions TO 3 ON ERROR PRINT "Select failed" PRINT @SELECTED FOR x=1 TO 5 READNEXT area FROM 3 PRINT area NEXT
The following example illustrates the use of the SELECTV statement. 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 variable:
regions="Northeast":@FM:"Southeast":@FM:"Northwest":@FM:"Southwest" SELECTV regions TO rfields ON ERROR PRINT "Select failed" PRINT @SELECTED FOR x=1 TO 5 READNEXT area FROM rfields PRINT area NEXT