Objects Erase statement - MapBasic - 2023

Purpose

Erases any portions of the target object(s) that overlap the selection; corresponds to choosing the Erase command on the SPATIAL tab. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Objects Erase Into Target
	[ Concurrency { All | Aggressive | Intermediate | Moderate | None } ]
	[ Data column_name = expression [ , column_name = expression ... ]
	[ DropIndex ( Auto | On | Off ) ]

column_name is a string representing the name of a column in the table being modified.

expression is an expression used to determine what is erased from the column_name columns.

Description

The Objects Erase statement erases part of (or all of) the objects that are currently designated as the editing target. Using the Objects Erase statement is equivalent to choosing MapInfo Pro's Erase command on the SPATIAL tab. For an introduction to using the Erase command, see the MapInfo Pro User Guide.

Objects Erase erases any parts of the target objects that overlap the currently selected objects. To erase only the parts of the target objects that do not overlap the selection, use the Objects Intersect statement.

Before you call Objects Erase, one or more closed objects (regions, rectangles, rounded rectangles, or ellipses) must be selected, and an editing target must exist. The editing target may have been set by the user choosing Set Target command on the SPATIAL tab, or it may have been set by the MapBasic Set Target statement.

For each Target object, one object will be produced for that portion of the target that lies outside all cutter objects. If the Target lies inside cutter objects, then no object is produced for output.

In addition to the five possible concurrency values, you can also specify the number of cores to use, such as eight (8). If your computer has less than the specified number of cores, MapBasic defaults to using all available cores on that machine. Specifying zero (0), a negative number, or invalid text that is different from the five possible concurrency values causes an error.

The optional Data clause controls what values are stored in the columns of the target objects. The Data clause can contain a comma-separated list of column assignments.

Each column assignment can take one of the forms listed in the following table:

col_name = col_name

col_name = value

col_name = Proportion( col_name )

The Data clause can contain an assignment for every column in the table. If the Data clause only specifies assignments for some of the columns, MapBasic assigns blank values to those columns that are not listed in the Data clause. If you omit the Data clause entirely, MapBasic blanks out all columns of the target object, storing zero values in numeric columns and blank values in character columns.

Specifying that the DropIndex clause is On suspends updating transaction indexes while executing the operation and recreates them when the operation is complete. In some cases this significantly improves performance, but not always. For the best performance, we recommend setting this clause to Auto, so that MapInfo Pro decides whether or not to suspend and recreate indexes. MapInfo Pro will suspend and recreate indexes later if the operation is deleting or updating the rows and the table contains more than 1000 rows and more than 0.1% of the total rows are getting updated. When the DropIndex clause is Off the operation executes without suspending and recreating the transaction indexes.

Example

In the following example, the Objects Erase statement does not include a Data clause. As a result, MapBasic stores blank values in the columns of the target object(s). This example assumes that one or more target objects have been designated, and one or more objects have been selected.

Objects Erase Into Target

In the next example, the Objects Erase statement includes a Data clause, which specifies expressions for three columns (State_Name, Pop_1990, and Med_Inc_80). This operation assigns the string "area remaining" to the State_Name column and specifies that the Pop_1990 column should be reduced in proportion to the amount of the object that is erased. The Med_Inc_80 column retains the value it had before the Objects Erase statement. The target objects' other columns are blanked out.

Objects Erase Into Target 
	Data 
		State_Name = "area remaining", 
		Pop_1990 = Proportion( Pop_1990 ), 
		Med_Inc_80 = Med_Inc_80

Using the Concurrency clause:

Objects Erase Into Target 
	Concurrency All Data...

See Also:

Erase() function, Objects Intersect statement Objects Split statement