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