LocateRecord()
Summary
Locates a record based on the value of a field.
Syntax
record_handle = LocateRecord(string view_set, string field_name, array value_array, array options)
| Argument | Contents |
|---|---|
| view_set | The view and set of records to consider |
| field_name | The name of a field in the view |
| value_array | A one-element array containing the value for which to search; should be compatible with the type of the field. |
| Option | Type | Contents |
|---|---|---|
| Exact | Boolean | Whether to search only for a record whose value for field_name matches exactly ("True"), or for a record with an inexact match ("False") |
Returns
A string indicating the record handle for the located record, or null if no record was found.
Notes
If there are multiple exact matches, the first record with an exact match is returned.
If there is no exact match and the exact option is "False" (the default), then LocateRecord() returns the first record with the next higher value (if there is one).
The returned record is also made the current record.
String comparisons are case-sensitive.
To search for a missing value, use a null value, i.e., the value_array is an array of one element, and that element is null. (The value_array must not be null itself.)
LocateRecord() returns null either if there is no exact match and the Exact option is "True", or if the Exact option is "False" and no record contains a higher value.
If the Exact option is "False" LocateRecord() does not indicate whether a returned non-null record is an exact match or not.
Example
// Find Hawaii in the State layer
rh1 = LocateRecord("U.S. States|", "Name", {"Hawaii"}, {{"Exact", "True"}})
// Find the first employee with a salary of $50,000 or more
rh2 = LocateRecord("Employees|Management", "Salary", {50000}, )Error Codes
| Error Type | Meaning |
|---|---|
| Error | Field_name or value_array is null, or the options array is non-null and invalid; or unable to perform necessary type-conversions on the input value |
| NotFound | The specified view or set or field does not exist |
See Also
| Function | Summary |
|---|---|
| GetFirstRecord() | Finds the first record in a view or selection set based on a sort order |
| GetRecord() | Returns the record handle of the current record of a view |
| SetRecord() | Sets the current record of a view |