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 locationLocateRecord()
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.