LOCATE, LOCATE() |
![]() ![]() ![]() |
The LOCATE statement searches a dynamic array for a given field, value or subvalue. The LOCATE() function provides similar capabilities and is particularly suited to use in dictionary I-type items.
Format
LOCATE string IN dyn.array<field {,value {, subvalue}}> {BY order} SETTING var {THEN statement(s)} {ELSE statement(s)}
where
At least one of the THEN and ELSE clauses must be present.
The LOCATE statement searches for fields, values or subvalues. If only field is specified, LOCATE searches for a field that matches string. If only field and value are specified, LOCATE searches for a value within the specified field that matches string. If field, value and subvalue are specified, LOCATE searches for a subvalue within the specified field and value that matches string.
Searching commences at the starting position defined in the IN clause. If a match is found, var is set to its field, value or subvalue position as appropriate to the level of the search. If no match is found, var is set to the position at which a new item should be inserted. For an unordered LOCATE this will be such that it would be appended.
The optional BY clause allows selection of an ordering rule. The order must evaluate to a two character string, which is
The ordering string must be in upper case. Left aligned ordering is faster than right aligned and should be used for textual data. Right aligned ordering is useful for numeric data such as internal format dates where the left aligned ordering would lead to sequencing problems (for example, 17 May 1995 is day 9999, 18 May 1995 is day 10000. Use of a left aligned ordering would place these dates out of calendar order).
The THEN clause is executed if the string is found in dyn.array. The ELSE clause is found if the string is not found.
The LOCATE() function returns as its result the position at which the item was found, zero if it was not found. Although the order argument can be used to specify the expected ordering and has the impact described above for numeric data, this function does not provide a way to identify where an item should be inserted if it is not found. The LOCATE() function is particularly suited to use in dictionary I-type items.
The result of a LOCATE statement or LOCATE() function with a specific ordering when applied to a dynamic array which does not conform to that ordering is undefined and likely to lead to misbehaviour of the program at run time.
Use of the $NOCASE.STRINGS compiler directive makes the comparison case insensitive. When used with a BY clause, the sorting is effectively as though both string and dyn.array are in uppercase.
Examples
LOCATE PART.NO IN PARTS<1> BY "AL" SETTING I ELSE INS PART.NO BEFORE PARTS<I> END
This program fragment locates PART.NO in a sorted list PARTS and, if it is not already present, inserts it.
I = LOCATE(PART.NO, PARTS, 1; "AL")
This statement performs the same search as the previous example but can only be used to find the position of an existing item, not to determine where a new item should be inserted to maintain the correct sort order.
Alternative Formats
QM supports two alternative formats of LOCATE for compatibility with other database products.
The UniVerse database running in Ideal or Reality flavour uses the IN clause to identify the item to be searched, not the starting position. The starting position is assumed to be the first item in the data but may specified explicitly in the command.
LOCATE string IN dyn.array{<field {,value }>} {, start} {BY order} SETTING var {THEN statement(s)} {ELSE statement(s)}
This format of LOCATE can be selected by including a line $MODE UV.LOCATE in the program on a line preceding the LOCATE statement. This mode setting has no effect on the operation of the LOCATE() function.
The Pick database uses a very different syntax which does not permit the search to start part way through the region of the dynamic array being searched.
LOCATE(string, dyn.array{,field {,value }}; var {; order}) {THEN statement(s)} {ELSE statement(s)}
This format can be used in QM without any special mode settings. Note that despite the presence of brackets, this is a statement and should not be confused with the LOCATE() function described above.
See also: DEL, DELETE(), EXTRACT(), FIND, FINDSTR, INS, INSERT(), LISTINDEX(), REPLACE() |