IB Statements/first

From CometWiki

FIRST function

Syntax: FIRST(lun [,EXCP=statement-label])

Discussion: The FIRST function returns the value of the first key in the file that is open on the specified logical unit number. The first key is the lowest ASCII valued key contained in the file. Notes:

The FIRST function is valid only for keyed files.

If the FIRST function is attempted on an empty keyed file, an exception 2 (END OF FILE) will be reported.

The FIRST function does not move the record pointer. Other file-related functions: KEY, LAST, PREV.

Application note: Some applications employ the FIRST function as a way of moving the record pointer to the beginning of the file (i.e., use the FIRST function to determine the first key and then READ using that value). A more efficient way to accomplish this result is to use the FILE statement to position the record pointer to the beginning of the file. Example:

 OPEN (1) "SALES"
 FIRSTKEY$ = FIRST(1,EXCP=9999)

In the above example, the FIRST function is used to determine the value of the first key in the SALES file. If an exception occurs when this statement is executed, program control will transfer to exception-statement-label 9999.