LOCATE Statement

The LOCATE statement may be used to find the occurrence of an attribute, value, or subvalue within a specified dynamic array, or if not found, find the proper position at which the string should be inserted.

Format

LOCATE(string , array, [attr# [,val#]] ; var [;seq]) THEN | ELSE statements

END

LOCATE string IN array [<attr# [,val#] >] [,start]

[BY seq] SETTING var THEN | ELSE statements

END

Parameter(s)

string	An expression evaluating to the string to be searched for in the dynamic array.
array	An expression evaluating to the dynamic array to be searched.
attr#	An expression evaluating to the attribute number to be searched. The value number matching the string is placed in var. If attr# is omitted or equal to 0, the entire dynamic array is searched and the attribute number which matches the string is placed in var.
val#	An expression evaluating to the value number to be searched within the specified attribute. The subvalue number matching the string is placed in var. If val# is omitted or equal to 0, the entire attribute is searched and the value number which matches the string is placed in var.
var#	Variable to be assigned.
start	Position to start searching with (default is 1). If string is in the first start-1 positions, it is not found; however, if string is found, var will still be assigned a value as if it had started searching with 1.
seq	An expression evaluating to the sequence in which elements are sorted. Possible values are:
	A	Ascending order.
	D	Descending order.
	AL	Ascending order, left justified.
	DL	Descending order, left justified.
	AR	Ascending order, right justified.
	DR	Descending order, right justified.
THEN statements	If found, execute the specified statements.
ELSE statements	If not found, execute the specified statements.

There are two forms to the LOCATE statement listed above, both using the LOCATE keyword. The second form allows the programmer to specify where in the dynamic array to start searching, and uses the angle bracket syntax similar to that of the EXTRACT function.

Description

The LOCATE statement searches a dynamic array for an attribute, value, or subvalue, and places an integer in var depending on whether it was found. If it was found, the integer indicates the position where the expression was found; if it was not found, the integer indicates where it should be inserted.

The LOCATE statement is meant for use with the INSERT statement. If the string is not found, the number placed in var may be used with a subsequent INSERT statement to place the string in the proper sequence.

Unless the BY clause is used, the sequence is assumed to be random: if the string is not found, var is assigned the number of the last position plus 1. Thus a subsequent INSERT statement places the string at the end of the sequence. However, if the elements to be searched are already sorted into an ascending or descending ASCII sequence, the BY clause can be used to specify the order to be maintained. If the string is not found and the BY clause is used, var is therefore assigned the position which would maintain the order, and a subsequent INSERT statement places the string in its proper place. However, if the BY clause is used and the elements are not in the expected sequence, an element which is out of order will not be found.

Either the THEN or ELSE clause must be used with the LOCATE statement. A common use of the ELSE clause is to insert the string into the proper position, using the position returned in var.

Example

In this application the user creates an alphabetical list of each item-ID in the file CUSTOMERS. The file is selected, and each item-ID is read with READNEXT. The LOCATE statement does not actually find the ID in the list, but returns into the variable POSITION the position where it should have been found. (If the ID is found in the list, the program aborts since it would imply duplicate item-IDs.) The INS statement is then used to insert the current ID in the proper position.

EQUATE TRUE TO 1, FALSE TO 0

OPEN "CUSTOMERS" TO CUSTFILE ELSE

ABORT 201, "CUSTOMERS"

END

SELECT CUSTFILE TO LIST

ALPH.LIST = ""

END.OF.LIST = FALSE

LOOP

READNEXT ID FROM LIST ELSE

END.OF.LIST = TRUE

END

UNTIL END.OF.LIST DO

LOCATE ID IN ALPH.LIST BY "AL" SETTING POSITION THEN

PRINT ID : " DUPLICATE ENTRY! POSSIBLE FILE CORRUPTION"

ABORT

END ELSE

INS ID BEFORE ALPH.LIST<POSITION>

END

REPEAT

The LOCATE statement in this example might also have read:

LOCATE( ID, ALPH.LIST ; POSITION ; " AL ") THEN...