The QMLocate() function searches a dynamic array for a field, value or subvalue matching a given string. It is analogous to the LOCATE statement.
The function arguments are:
If omitted or a null string, no sort order is applied.
The QMLocate() function searches a dynamic array at one of three levels:
•If Vno is less than 1, the function searches the dynamic array for a field matching Item, starting at the field position given by Fno.
•If Vno is given but Svno is less than 1, the function searches field Fno of the dynamic array for a value matching Item, starting at the value position given by Vno.
•If Vno and Svno are given, the function searches field Fno, value Vno of the dynamic array for a subvalue matching Item, starting at the value position given by Svno.
The Order argument determines the sorting system to be applied during the search:
•If Order is a null string, no sort rules are applied. The function scans all applicable dynamic array elements for a match against Item. The Pos variable will be returned as the position at which the item was found. If the item is not found, Pos will be returned as the position at which a new element could be appended.
•If the first character of Order is A, an ascending sort is applied. If the first character of Order is D, a descending sort is applied. In either case, the search terminates if an entry is found that would be beyond the correct position for Item. In this case, if the item is not found, Pos will be returned as the position at which to insert Item to maintain the correct sort order.
•If the second character of Order is L, a left aligned comparison is performed. Each entry of the dynamic array is compared with Item character by character from the left until a difference is found.
•If the second character of Order is R, a right aligned comparison is performed. If the two items being compared are of different lengths, spaces are added to the front of the shorter item before comparison.
The returned positional information indicates where the item was found or, if not found, where it should be inserted.
This function is evaluated on the client system and does not require a server connection to be open.
The examples below search field 4 of record stored as variable OrderRec for a value that contains the same data as the PartNo variable. If found, the value position is returned in variable Pos and Found is set to true. If not found, Pos will indicate the position at which the item could be inserted to maintain correct sorted order as implied by the AL sort code and Found will be set to False. Note that the QMLocate() function follows the default "Information style" syntax of QM where the field, value and subvalue positions indicate the point at which the search is to start. Thus, these examples specify a value position of 1 to search the entire field.