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.