Find statement - MapBasic - 2023

Purpose

Finds a location in a mappable table. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Find address [ , region ] [ Interactive ]

address is a string expression representing the name of a map object to find; to find the intersection of two streets, use the syntax: streetname && streetname.

region is the name of a region object which refines the search.

Description

The Find statement searches a mappable table for a named location (represented by the address parameter). MapBasic stores the search results in system variables, which a program can then access through the CommandInfo() function. If the Find statement includes the optional Interactive keyword, and if MapBasic is unable to locate the specified address, a dialog box displays a list of "near matches."

The Find statement can only search a mappable table (for example, a table which has graphic objects attached). The table must already be open. The Find statement operates on whichever column is currently chosen for searching. A MapBasic program can issue a Find Using statement to identify a specific table column to search. If the Find statement is not preceded by a Find Using statement, MapBasic searches whichever table was specified the last time the user chose MapInfo Pro's Find command.

The Find statement can optionally refine a search by specifying a region name in addition to the address parameter. In other words, you could simply try to find a city name (for example, "Albany") by searching a table of cities; or you could refine the search by specifying both a city name and a region name (for example, "Albany", "CA"). The Find statement does not automatically add a symbol to the map to mark where the address was found. To create such a symbol, call the CreatePoint() function or the Create Point statement; see example below.

Determining Whether the Address Was Found

Following a Find statement, a MapBasic program can issue the function call CommandInfo(CMD_INFO_FIND_RC) to determine if the search was successful. If the search was successful, call CommandInfo(CMD_INFO_X) to determine the x-coordinate of the queried location, and call CommandInfo(CMD_INFO_Y) to determine the y-coordinate. To determine the row number that corresponds to the "found" address, call CommandInfo(CMD_INFO_FIND_ROWID).

The Find statement may result in an exact match, an approximate match, or a failure to match. If the Find statement results in an exact match, the function call CommandInfo(CMD_INFO_FIND_RC) returns a value of one (1). If the Find statement results in an approximate match, the function call returns a value greater than one (1). If the Find statement fails to match the address, the function call returns a negative value.

The table below summarizes the Find-related information represented by the CommandInfo(CMD_INFO_FIND_RC) return value. The return value has up to three digits, and that each of the three digits indicates the relative success or failure of a different part of the search.

xx1

xx2

xx3 ( - )

xx4 ( - )

xx5 ( + )

x1x

x2x ( + / - )

x3x ( + / - )

x4x ( + / - )

x5x ( - )

x6x ( - )

x7x ( + )

1xx ( + / - )

2xx ( - )

3xx ( + / - )

4xx ( - )

5xx ( + )

6xx ( + )

The Mod operator is useful when examining individual digits from the Find result. For example, to determine the last digit of a number, use the expression number Mod 10. To determine the last two digits of a number, use the expression number Mod 100; etc.

The distinction between exact and approximate matches is best illustrated by example. If a table of cities contains one entry for "Albany", and the Find Using statement attempts to locate a city name without a refining region name, and the Find statement specifies an address parameter value of "Albany", the search results in an exact match. Following such a Find statement, the function call CommandInfo(CMD_INFO_FIND_RC) would return a value of 1 (one), indicating that an exact match was found.

Now suppose that the Find operation has been set up to refine the search with an optional region name; in other words, the Find statement expects a city name followed by a state name (for example, "Albany", "NY"). If a MapBasic program then issues a Find statement with "Albany" as the address and a null string as the state name, that is technically not an exact match, because MapBasic expects the city name to be followed by a state name. Nevertheless, if there is only one "Albany" record in the table, MapBasic will be able to locate that record. Following such a Find operation, the function call CommandInfo(CMD_INFO_FIND_RC) would return a value of 301. The 1 digit signifies that the city name matched exactly, while the 3 digit indicates that MapBasic was only partly successful in locating a correct refining region.

If a table of streets contains "Main St", and a Find statement attempts to locate "Main Street", MapBasic considers the result to be an approximate match (assuming that abbreviation file processing has been enabled; see Find Using statement). Strictly speaking, the string "Main Street" does not match the string "Main St". However MapBasic is able to match the two strings after substituting possible abbreviations from the MapInfo Pro abbreviations file (MAPINFOW.ABB). Following the Find statement, the CommandInfo(CMD_INFO_FIND_RC) function call returns a value of 2.

If the Find operation presents the user with a dialog box, and the user enters text in the dialog box in order to complete the find, then the return code will have a 1 (one) in the millions place.

Example

Include "mapbasic.def"
Dim x, y As Float, win_id As Integer
Open Table "states" Interactive
Map From States
win_id = FrontWindow()
Find Using states(state) 
Find "NY"
If CommandInfo(CMD_INFO_FIND_RC) >= 1 Then
	x = CommandInfo(CMD_INFO_X)
	y = CommandInfo(CMD_INFO_Y)
	Set Map
		Window win_id 
		Center (x, y)
	' Now create a symbol at the location we found. 
	' Create the object in the Cosmetic layer. 
	Insert Into 
		WindowInfo( win_id, WIN_INFO_TABLE) (Object) 
		Values ( CreatePoint(x, y) ) 
Else
	Note "Location not found." 
End If 

See Also:

CommandInfo() function, Find Using statement, OverlayNodes() function