Locate Function

Format

b = locate(dictionary_name, relational_operator, key_prefix);

Description

The locate function finds, but does not load, a case in a data file that matches a specified condition. The function searches the index of a file and finds the first case that matches the specified condition. The case pointer is positioned to the case's location, but the case is not loaded into memory. To load the case into memory, use the retrieve function or the loadcase function without arguments.

The dictionary_name refers to either an external dictionary or the main input file of a batch application.

The relational_operator is one of the following: =, <, <=, >, >=, or startswith.

The string expression key_prefix specifies the condition to use when searching for cases. Cases with a key that begins with or equals the key_prefix are considered eligible cases. If the relational operators are < or <=, then the file is positioned at the case with the largest key which satisfies the condition. If the relational operators are > or >=, then the file is positioned at the case with the smallest key which satisfies the condition. If startswith is used, the file is positioned at the first case whose key starts with the key_prefix.

An additional option, using uuid instead of a relational operator, determines the existence of a case based on the case's UUID, not the case's key. This may be useful when looking up duplicate or deleted cases.

Return Value

The function returns a logical value of 1 (true) if a case is found and 0 (false) otherwise.

Example

if locate(SURVEY_DICT, >=, "55") then

do while loadcase(SURVEY_DICT) and PROVINCE = 55
// process all cases in province 55
enddo;

endif;