SelectByVicinity()

Summary

Selects map features located in or near features in another layer or selection set.

 

Changes

Optional options array introduced in Version 5.0.

 

Syntax

n_selected = SelectByVicinity (string set_name, string operation, string search_layer_set, real buffer_size [, array options])

 

Argument	Contents
set_name	The name of the selection set
operation	The operation to perform, as indicated below
search_layer_set	The name of the search layer and selection set around which to search, in the form "layer_name|set_name"
buffer	The buffer distance around the features in the search layer and selection set in which to search, or zero for no buffer distance

 

Operation	Meaning
several	Replaces the contents of the selection set
less	Removes features from the selection set
more	Adds features to the selection set
subset	Selects a subset of the selection set

 

Option	Type	Contents
Inclusion	String	"Enclosed" or "Intersecting", overriding the current setting; for more information, seeSetSelectInclusion()
Max	Integer	Maximum number of records to select
Display	Boolean	"True" or "False" overriding the current setting; for more information, seeSetSelectDisplay()
Auto Redraw	Boolean	"True" or "False" overriding the current setting; for more information, seeSetSelectAutoRedraw()
Source And	String	A selection set on the current layer that records must be in to be selected
Source Not	String	A selection set on the current layer that records must not be in to be selected

 

Returns

An integer indicating the number of records in the selection set.

 

Notes

• The options array is an optional argument.

• All selection commands operate on the current layer.

• SelectByVicinity() supports the Dataview-Select By Location command.

• Use SetSelectInclusion() to control whether features are selected only when fully enclosed by the search area, or when they merely intersect the search area.

• The definition of the search area depends on the type of search layer. If the search layer is a point layer, SelectByVicinity() requires a non-zero buffer distance to create a search area. If the search layer is a line layer and SetSelectInclusion() is set to enclosed, SelectByVicinity() also requires a non-zero buffer distance to create a search area.

• The buffer distance is not used in other cases, and no buffer layer is created. To use an actual buffer, create a buffer layer with CreateBuffers() and use that as the search layer.

• The following tables show what it takes for a feature in the selection set on the current layer to be selected based on the search area created from the selection set on the search layer. This table is for SetSelectInclusion() set to enclosed:

Search Area	Selecting Points	Selecting Lines	Selecting Areas
Point-based	Inside buffer	Inside buffer	Inside buffer
Line-based	Inside buffer	Inside buffer	Inside buffer
Area-based	Inside area	Inside area	Inside area

 

This table is for SetSelectInclusion() set to intersecting:

 

Search Area	Selecting Points	Selecting Lines	Selecting Areas
Point-based	Inside buffer	Touching buffer	Touching buffer
Line-based	On line	Touching line	Touching line
Area-based	Inside area	Touching area	Touching area

• All selection commands operate on the current layer. The current layer can also be used as the search layer.

• If the set does not already exist, SelectByVicinity() creates it.

• The current layer needs to be in a map, not just in the workspace, for SelectbyVicinity() to work. For example, adding the layer with AddLayertoWorkspace() is not appropriate.

• The Max option returns the first n records found that are within the buffer distance, rather than the closest n records.

Example

// Find the high income counties...

SetLayer("Counties")

SelectByQuery("High Income", "Several", "Select where Income > 75000")

 

// Find customers living in these counties...

SetLayer("Customers")

n_cust = SelectByVicinity("Selection", "Several", "Counties|High Income", 0.0)

 

// Select stores within 5 miles of these customers...

SetLayer("Stores")

n_stores = SelectByVicinity("Selection", "Several", "Customers|Selection", 5.0)

 

Error Codes

Error Type	Meaning
Error	The set name, operation type, or search layer or selection set is invalid
NotFound	No features fall within the specified region
Cancel	User clicked cancel

 

See Also

Function	Summary
GetSelectInclusion()	Indicates the inclusion status for a spatial selection
SelectNearestFeatures()	Selects a feature in the current layer nearest to each feature in another layer or selection set
SetSelectInclusion()	Sets the inclusion status for spatial selection