LocateNearestRecord()
Summary
Finds the map feature nearest a point location.
Changes
Optional options array with Target Layer option added in Version 6.0/2012.
Syntax
record_handle = LocateNearestRecord(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, in map units |
| Option | Type | Contents |
|---|---|---|
| Target Layer | String | The layer to search, if other than the current layer |
| Target Set | String | A selection set on the current or in the Target Layer that records must be in to be selected |
Returns
A string indicating the record handle for the nearest map feature in the current layer, or null if there is no map feature within search_distance of location.
Notes
The options array is an optional argument.
The returned record is also set as the current record.
LocateNearestRecord() works on the current layer or on the layer set by the Target Layer option.
The layer does not have to be in a map; LocateNearestRecord() can be used with a layer added with AddLayerToWorkspace().
The nearest map feature is determined as follows: for points, the nearest is the closest point feature to the search point; for lines, the nearest is the line feature whose shape brings it closest to the search point; for areas, the nearest is the area feature that the search point is within.
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)
rh = LocateNearestRecord(Boston, 25.0)
ShowMessage("The nearest place is " + plclayer.City)
DropLayerFromWorkspace(plclayer)Error Codes
| Error Type | Meaning |
|---|---|
| Error | There is no current layer, or the current layer is not a point, line or area layer |
| Locked | The required geographic databases are not available; most likely a time-out occurred |
See Also
| Function | Summary |
|---|---|
| LocateNearestRecords() | Finds the map features nearest a point location |
| LocateRecord() | Locates a record based on the value of a field |
| SelectByCircle() | Selects map features that are located within a circle |
| 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. |