LIMIT.INDEX Statement

Specifies the end of a range of positions within an index.

Syntax

LIMIT.INDEX indexSelectVar location {SETTING settingVar} [THEN statement(s) | ELSE statement(s)]

Syntax Elements

indexSelectVar The name of a variable that identifies an index. A reference to an index must be obtained using the SELECT statement.

location Specifies the required position. One of the following:

= keyValueInclude keys that exactly match keyValue.

< keyValueDo not include keys that exactly match keyValue.

] keyValue Include keys that start with keyValue.

keyValue is a key value (of the form by which the index is sorted) to compare against the index's sort criteria. If the index definition includes multiple BY clauses, the key values for the different clauses must be separated with attribute marks (@AM).

END The end of the index. Removes any previous limit.

settingVar The name of a variable to which the error code is assigned when the ELSE clause is taken. The file I/O error codes are described in File I/O and IPC Error Codes.

If the THEN clause is taken, settingVar is returned set to zero.

statement(s) Either a THEN or an ELSE clause (or both). A statement must be included. The THEN clause is executed if the index is referenced successfully; otherwise the ELSE clause is executed.

Comments

Use the POSITION statement to specify the start of the range.

This statement will not work with any kind of list other than an index reference. Specifically, it will not work with a list returned by SELECT-INDEX or ISELECT, since those commands do not generate index references.

See also Using Indexes.

Case Sensitivity

The case of any key values specified in the location parameter is subject to the case-sensitivity settings that were current when the index was created (see CREATE-INDEX, Item Lists and Selection Criteria). If in doubt, ensure that the case of this parameter matches that of the index key values.

Output Conversions

For indexes that were created from dictionary definitions that include output conversions, LIMIT.INDEX applies those output conversions to the literal data specified as appropriate. This behaviour can be changed with the EXTERNAL.KEY environment option.

Examples

In the following examples, the file called NAMES contains the following :

IID

1

2

3

4

5

6

7

Attr 1

BILL

FRED

GEORGE

JOE

FREDA

FRED

JANE

and has an index called NAME containing all the items in the file, sorted by attribute 1:

:DEFINE-INDEX NAMES BY *A1

TO:NAME
[1281] Index definition 'NAME' created.
:CREATE-INDEX NAMES NAME
[1280] Index 'NAME' created.
:

Example 1

OPEN "NAMES" TO NAME.FILE ELSE STOP 201,"NAMES"
*
SELECT NAME.FILE,"NAME" TO NAME.IDX
* Position to first FRED
POSITION NAME.IDX ="FRED" ELSE STOP
* Limit to FRED only.
LIMIT.INDEX NAME.IDX ="FRED" ELSE STOP
*
LOOP WHILE READNEXT ID FROM NAME.IDX DO
   READ ITEM FROM NAME.FILE,ID ELSE NULL
   PRINT ID,ITEM
REPEAT

Displays:

2                 FRED
6                 FRED

This example selects the items referenced by the NAME index. It then positions the read pointer to the first item containing "FRED" and defines a range that ends with the last item containing "FRED". It then loop through this range, displaying the item id and item contents for each item in this range.

Example 2

OPEN "NAMES" TO NAME.FILE ELSE STOP 201,"NAMES"
*
SELECT NAME.FILE,"NAME" TO NAME.IDX
* Position to first FRED
POSITION NAME.IDX ="FRED" ELSE STOP
* Limit to "FRED]" only.
LIMIT.INDEX NAME.IDX ]"FRED" ELSE STOP
*
LOOP WHILE READNEXT ID FROM NAME.IDX DO
   READ ITEM FROM NAME.FILE,ID ELSE NULL
   PRINT ID,ITEM
REPEAT

Displays:

2                 FRED
6                 FRED
5                 FREDA

This example is similar to the previous one, but the end of the range is set to the last item that begins with "FRED". It therefore displays the items containing both "FRED" and "FREDA".