Objects Split statement - MapBasic - 2023

Purpose

Splits target objects, using the currently-selected objects as a "cookie cutter"; corresponds to choosing the Split command on the SPATIAL tab. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Objects Split 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 the column where the new values are stored.

expression is an expression which is used to assign values to column_name.

concurrency lets you utilize multiple cores to split targeted objects on a map. Using multi cores can be achieved using the concurrency token. If the concurrency token is used, it needs to be followed by one the following values: aggressive, intermediate, moderate, none, or a number to specify number of cores to use. As with the usage in Create Object As Buffer statement, if a zero or a negative value is specified after concurrency, you will see an error message.

Description

Use the Objects Split statement to split each of the target objects into multiple objects. Using Objects Split is equivalent to choosing MapInfo Pro's Split command on the SPATIAL tab. For more information on split operations, see the MapInfo Pro Reference.

Before you call Objects Split, 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 on the SPATIAL tab, or it may have been set by the MapBasic Set Target statement.

For each target object, a new object is created for each area that intersects a cutter object. For example, if a target object is intersected by three cutter objects, then three new objects will be created. In addition, a single object will be created for all parts of the target object that lie outside all cutter objects. This is equivalent to performing both an Objects Erase statement and an Objects Intersect statement (Erase Outside command on the SPATIAL tab).

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 objects, 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 Split statement does not include a Data clause. As a result, MapBasic stores blank values in the columns of the target object(s).

Objects Split Into Target 

In the next example, the statement includes a Data clause, which specifies expressions for three columns (State_Name, Pop_1990, and Med_Inc_80). This first part of the Data clause assigns the string "sub-division" to the State_Name column; as a result, "sub-division" will be stored in the State_Name column of each object produced by the split. The next part of the Data clause specifies that the target object's original Pop_1990 value should be divided among the objects produced by the split. The third part of the Data clause specifies that each of the new objects should retain the original value from the Med_Inc_80 column.

Objects Split Into Target 
	Data 
		State_Name = "sub-division", 
		Pop_1990 = Proportion( Pop_1990 ), 
		Med_Inc_80 = Med_Inc_80

Using the concurrency token:

Objects Split Into Target 
	concurrency all Data...

See Also:

Alter Object statement Create Object As Buffer statement