POSITION Statement

Positions the read pointer of an index.

Syntax

POSITION 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:

BEG The start of the index.

END The end of the index.

= keyValue The position of the first entry that matches keyValue.

> keyValue The position after the first entry that matches keyValue.

In the latter two cases:

  • 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).

  • If there is no entry that matches keyValue, the read pointer is positioned where the entry would occur if it did exist.

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

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, POSITION applies those output conversions to the literal data specified as appropriate. This behaviour can be changed with the EXTERNAL.KEY environment option.

Examples

POSITION ACCPAYINDEX = MONTHCURR ELSE PRINT "NON-EXISTENT INDEX"; STOP

Sets the read pointer of the index specified in variable ACCPAYINDEX to the first entry that is equal to or greater than the value in MONTHCURR.

POSITION ACCPAYINDEX END ELSE PRINT "NON-EXISTENT INDEX"; STOP

Sets the pointer to the end of the index specified in variable ACCPAYINDEX.

EQU FNAME TO "SQLEMP"
EQU INAME TO "EMP.X2"
*
OPEN FNAME TO EMP ELSE STOP 201,FNAME
SELECT EMP,INAME TO XV
*
* Position to first SMITH in department 90020
*
DEPT = "90020"
NAME = "SMITH"
KEYVAL = DEPT:@AM:NAME
POSITION XV =KEYVAL ELSE STOP
* Limit to SMITH in this dept.
LIMIT.INDEX XV =KEYVAL ELSE STOP
*
* Print item-ids of all employees called SMITH in department 90020
*
LOOP WHILE READNEXT ID FROM XV DO
   PRINT ID
REPEAT
*
END

In the above example, the index EMP.X2 has been created on file SQLEMP with a definition such as:

:DEFINE-INDEX SQLEMP BY DEPTNO BY ENAME

TO:EMP.X2

so that it is sorted first by Department and secondly by Employee Name. The example prints the item-ids of all employees with the name SMITH in department number 90020.

See Also

SELECT statement, READNEXT statement, LIMIT.INDEX statement.