LocateNearestRecords()
Summary
Finds the map features nearest a point location.
Changes
Optional options array with Target Layer option added in Version 6.0/2012.
Syntax
record_handles = LocateNearestRecords(coordinate location, real search_distance, array options)
| Argument | Contents |
|---|---|
| location | The point at which to search |
| search_distance | The maximum search distance from the point |
| Options | Type | Contents |
|---|---|---|
| Unique | String | A full field specification indicating a field for which each unique value yields only one record in the output list |
| Target Layer | String | The layer to search, if other than the current layer |
Returns
An array of strings indicating the record handles for all map features in the current layer that are within search_distance of the location, or null if there is no map feature within search_distance of the location.
Notes
-
The record handles are sorted in increasing distance from the input location.
-
LocateNearestRecords() works on the current layer or on the layer set by the Target Layer option.
-
If the Unique option is used, LocateNearestRecords() returns only the nearest record with a particular value for the chosen field.
-
If the Target Layer option is specified, the current layer is saved and restored.
Example
folder = RunMacro("G30 Tutorial Folder")
plclayer = AddLayerToWorkspace("Place",folder + "NES_PLC.CDF","Place",)
SetLayer(plclayer)
Boston = Coord(-71060500, 42358400)
record_handles = LocateNearestRecords(Boston, 25.0, )
SetRecord(plclayer, record_handles[1])
ShowMessage("The nearest place is " + plclayer.City)
ShowMessage("There are " + String(record_handles.length) + " places within 25 miles.")Error Codes
| Error Type | Meaning |
|---|---|
| Error | There is no current layer, or the current layer is not a point, line or area layer |
| NotFound | There is no geographic record within the search distance of the specified location |
| Locked | The required geographic databases are not available; most likely a time-out occurred |
See Also
| Function | Summary |
|---|---|
| LocateNearestRecord() | Finds the map feature nearest a point location |
| SelectNearestFeatures() | Selects a feature in the current layer nearest to each feature in another layer or selection set |
| TagLayer() | Fills a field in a layer with information about the nearest feature in another layer. |