MapBasic

Version 15.2

Reference
Notices
 Copyright

Information in this document is subject to change without notice and does not represent a commitment
on the part of the vendor or its representatives. No part of this document may be reproduced or
transmitted in any form or by any means, electronic or mechanical, including photocopying, without
the written permission of Pitney Bowes Software Inc., One Global View, Troy, New York 12180-8399.
© 2015 Pitney Bowes Software Inc. All rights reserved. Pitney Bowes Software Inc. is a wholly owned
subsidiary of Pitney Bowes Inc. Pitney Bowes, the Corporate logo, MapInfo, Group 1 Software, and
MapBasic are trademarks of Pitney Bowes Software Inc. All other marks and trademarks are property
of their respective holders.
Contact information for all Pitney Bowes Software Inc. offices is located at:
http://www.pitneybowes.com/us/contact-us.html.
© 2015 Adobe Systems Incorporated. All rights reserved. Adobe, the Adobe logo, Acrobat and the
Adobe PDF logo are either registered trademarks or trademarks of Adobe Systems Incorporated in
the United States and/or other countries.
© 2015 OpenStreetMap contributors, CC-BY-SA; see OpenStreetMap
http://www.openstreetmap.org (license available at www.opendatacommons.org/licenses/odbl)
and CC-BY-SA http://creativecommons.org/licenses/by-sa/2.0
libtiff © 1988-1997 Sam Leffler, © 2015 Silicon Graphics Inc. All Rights Reserved.
libgeotiff © 2015 Niles D. Ritter.
Amigo, Portions © 1999 Three D Graphics, Inc. All Rights Reserved.
Halo Image Library © 1993 Media Cybernetics Inc. All Rights Reserved.
Portions thereof LEAD Technologies, Inc. © 1991-2015. All Rights Reserved.
Portions © 1993-2015 Ken Martin, Will Schroeder, Bill Lorensen. All Rights Reserved.
ECW by ERDAS © 1993-2015 Intergraph Corporation, part of Hexagon Group and/or its suppliers.
All rights reserved.
Portions © 2015 Intergraph Corporation, part of Hexagon Group All Rights Reserved.
MrSID, MrSID Decompressor and the MrSID logo are trademarks of LizardTech, A Celartem
Company. used under license. Portions of this computer program are copyright © 1995-1998
LizardTech, A Celartem Company, and/or the university of California or are protected by US patent
no. 5,710,835 and are used under license. All rights reserved. MrSID is protected under US and
international patent & copyright treaties and foreign patent applications are pending. Unauthorized
use or duplication prohibited.
Contains FME® Objects © 2005-2015 Safe Software Inc., All Rights Reserved.
Amyuni PDF Converter © 2000-2015, AMYUNI Consultants – AMYUNI Technologies. All rights
reserved.
Civic England - Public Sector Symbols Copyright © 2015 West London Alliance. The symbols may
be used free of charge. For more information on these symbols, including how to obtain them for
use in other applications, please visit the West London Alliance Web site at
http://www.westlondonalliance.org

MapBasic 15.2 Reference 3

 Copyright

© 2006-2015 TomTom International BV. All Rights Reserved. This material is proprietary and the
subject of copyright protection and other intellectual property rights owned or licensed to TomTom.
The use of this material is subject to the terms of a license agreement. You will be held liable for
any unauthorized copying or disclosure of this material.
Microsoft Bing: All contents of the Bing service are Copyright © 2015 Microsoft Corporation and/or
its suppliers, One Microsoft Way, Redmond, WA 98052, USA. All rights reserved. Microsoft or its
suppliers own the title, copyright, and other intellectual property rights in the Bing service and content.
Microsoft, Windows, Windows Live, Windows logo, MSN, MSN logo (butterfly), Bing, and other
Microsoft products and services may also be either trademarks or registered trademarks of Microsoft
in the United States and/or other countries.
This product contains 7-Zip, which is licensed under GNU Lesser General Public License, Version
3, 29 June 2007 with the unRAR restriction. The license can be downloaded from
http://www.7-zip.org/license.txt. The GNU License may be downloaded from
http://www.gnu.org/licenses/lgpl.html. The source code is available from http://www.7-zip.org.
Products named herein may be trademarks of their respective manufacturers and are hereby
recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with
no intent to infringe on the trademark.

MapBasic 15.2 Reference 4

Table of Contents
MICloseFtpConnection() procedure 936
MICloseFtpFileFind() procedure 936
1 - Introduction to MapBasic MICloseHttpConnection() procedure 937
MICloseHttpFile() procedure 937
Type Conventions 8 MICloseSession() procedure 938
Language Overview 9 MICreateSession() function 938
MapBasic Fundamentals 9 MICreateSessionFull() function 939
MapBasic IDE Features 11 MIErrorDlg() function 941
Functions 13 MIFindFtpFile() function 942
Working With Tables 16 MIFindNextFtpFile() function 943
Working With Files (Other Than Tables) 19 MIGetContent() function 944
Working With Maps and Graphical Objects 20 MIGetContentBuffer() function 944
Creating the User Interface 25 MIGetContentLen() function 945
Communicating With Other Applications 28 MIGetContentString() function 946
Special Statements and Functions 29 MIGetContentToFile() function 946
Getting Technical Support 30 MIGetContentType() function 947
Copyright 32 MIGetCurrentFtpDirectory() function 948
OpenSource Attribution Notices 33 MIGetErrorCode() function 948
MIGetErrorMessage() function 949
MIGetFileURL() function 950
2 - New and Enhanced
MIGetFtpConnection() function 950
MapBasic Statements and MIGetFtpFile() function 951
MIGetFtpFileFind() function 953
Functions
MIGetFtpFileName() procedure 954
MIGetHttpConnection() function 954
New MapBasic Functions and Statements 35
MIIsFtpDirectory() function 955
Updates to Existing Functions and Statements 35
MIIsFtpDots() function 956
MIOpenRequest() function 956
3 - A to Z MapBasic Language MIOpenRequestFull() function 957
MIParseURL() function 959
Reference MIPutFtpFile() function 961
MIQueryInfo() function 962
Function and Statement Conventions 44 MIQueryInfoStatusCode() function 962
Function and Statement Descriptions 44 MISaveContent() function 964
Appendix A: HTTP and FTP Libraries MISendRequest() function 965
MISendSimpleRequest() function 965
About the HTTP and FTP Libraries 935 MISetCurrentFtpDirectory() function 966
MICloseContent() procedure 935 MISetSessionTimeout() function 967
Appendix B: XML Library
Searching for a Topic in the Help System 1039
About the XML Library 969 Using the Help System 1039
MIXmlAttributeListDestroy() procedure 969 About the Help Viewer 1039
MIXmlDocumentCreate() function 970 Viewing Help on Another Computer 1040
MIXmlDocumentDestroy() procedure 970
MIXmlDocumentGetNamespaces() function 971
MIXmlDocumentGetRootNode() function 971
MIXmlDocumentLoad() function 972
MIXmlDocumentLoadXML() function 973
MIXmlDocumentLoadXMLString() function 974
MIXmlDocumentSetProperty() function 975
MIXmlGetAttributeList() function 976
MIXmlGetChildList() function 977
MIXmlGetNextAttribute() function 977
MIXmlGetNextNode() function 978
MIXmlNodeDestroy() procedure 979
MIXmlNodeGetAttributeValue() function 979
MIXmlNodeGetFirstChild() function 980
MIXmlNodeGetName() function 981
MIXmlNodeGetParent() function 981
MIXmlNodeGetText() function 982
MIXmlNodeGetValue() function 983
MIXmlNodeListDestroy() procedure 984
MIXmlSCDestroy() procedure 984
MIXmlSCGetLength() function 985
MIXmlSCGetNamespace() function 985
MIXmlSelectNodes() function 986
MIXmlSelectSingleNode() function 987
Appendix C: Character Code Table

Character Code Table Definitions 990

Appendix D: Summary of Operators

Numeric Operators 992

Comparison Operators 993
Logical Operators 994
Geographical Operators 995
Automatic Type Conversions 997
Wildcards 999
Appendix E: MapBasic Definitions File

The MAPBASIC.DEF File 1001

Appendix F: Introduction to MapBasic Help

MapBasic 15.2 Reference 6

1 - Introduction to
MapBasic
Welcome to the MapBasic Development Environment, the powerful, yet
easy-to-use programming language that lets you customize and automate
MapInfo® Pro.
This manual describes every statement and function in the MapBasic
Development Environment programming language. To learn about the
concepts behind MapBasic programming, or to learn about using the
MapBasic development environment, see the MapBasic User Guide.
Note: This version of MapBasic is compatible with both 32-bit and 64-bit
versions of MapInfo® Pro.

In this section
Type Conventions 8
Language Overview 9
MapBasic Fundamentals 9
MapBasic IDE Features 11
Functions 13
Working With Tables 16
Working With Files (Other Than Tables) 19
Working With Maps and Graphical Objects 20
Creating the User Interface 25
Communicating With Other Applications 28
Special Statements and Functions 29
Getting Technical Support 30
Copyright 32
OpenSource Attribution Notices 33
 Introduction to MapBasic

Type Conventions

This manual uses the following conventions to designate specific items in the text:

Convention Meaning

If, Call, Map, Browse, Area

Bold words with the first letter capitalized are MapBasic
keywords.
Within this manual, the first letter of each keyword is
capitalized; however, when you write MapBasic programs,
you may enter keywords in upper-, lower-, or mixed-case.

Main, Pen, Object Non-bold words with the first letter capitalized are usually
special procedure names or variable types.

table, handler, window_id Italicized words represent parameters to MapBasic

statements. When you construct a MapBasic statement,
you must supply an appropriate expression for each
parameter.

[ window_id ], [ Interactive ] Keywords or parameters which appear inside square

brackets are optional.

{ On | Off } When a syntax expression appears inside braces, the braces

contain a list of keywords or parameters, separated by the
vertical bar character ( | ). You must choose one of the
options listed. For example, in the sample shown on the left
({ On | Off }), you should choose either On or Off.

Actual program samples are shown in Courier font.

"Note "Hello,world!"

MapBasic 15.2 Reference 8

 Introduction to MapBasic

Language Overview

The following pages provide an overview of the MapBasic language. Task descriptions appear on
the left; corresponding statement names and function names appear on the right, in bold. Function
names are followed by parentheses ().

MapBasic Fundamentals

Variables

Declare local or global variables: Dim,Global

Resize array variables: ReDim, UBound(), UnDim

Declare custom data structure: Type

Large Integer Variables

MapBasic uses the integer types SmallInt, Integer, and LargeInt. LargeInt is a type for storing 64-bit
(8 byte) integers; use the Dim statement to create a LargeInt variable.

SmallInt Whole numbers from -32768 to 32767 (inclusive); stored in

2 bytes.

Integer Whole numbers from -2,147,483,648 to +2,147,483,647

(inclusive); stored in 4 bytes.

LargeInt Whole numbers from –9,223,372,036,854,775,808 to

+9,223,372,036,854,775,807 (inclusive); stored in 8 bytes.

LargeInt variables are supported in MapBasic, but they are not a fully supported type in a table,
because some operations may not work correctly for large values (such as thematic maps). Some
mathematic calculations or functions generate a LargeInt value. If the value is outside the range for

MapBasic 15.2 Reference 9

 Introduction to MapBasic

an Integer variable and your application tries to store the result in an Integer, you will get an overflow
error.
The following functions return a LargeInt value:
• Seek statement on page 654Seek statement
• LOF() function on page 476LOF() function
• Server_GetODBCHConn() function on page 695Server_GetODBCHConn() function
• Server_GetODBCHStmt() function on page 696Server_GetODBCHStmt() function
The following statements accept a LargeInt value for the file position:
• Seek statement
• Get statement
The following function return a IntPtr value when the specified attributes are requested.
• SystemInfo() function attributes SYS_INFO_APPLICATIONWND, SYS_INFO_MAPINFOWND,
SYS_INFO_MDICLIENTWND, and SYS_INFO_APPIDISPATCH.
• WindowInfo() function attribute WIN_INFO_WND.
IntPtr is a platform specific type that is used to represent a pointer or a handle. This helps to write
applications that will work with both the 32-bit and 64-bit versions of MapInfo Pro. The 64-bit version
of MapInfo Pro treats this like a LargeInt, and the 32-bit version of MapInfo Pro treats this like an
Integer.

Looping and Branching

Looping: For...Next, Exit For, Do...Loop, Exit Do, While...Wend

Branching: If...Then, Do Case, GoTo

Other flow control: End Program, Terminate Application, End MapInfo

Output and Printing

Print a window's contents: PrintWin

Print text to message window: Print

Set up a Layout window: Layout, Create Frame, Set Window

MapBasic 15.2 Reference 10

 Introduction to MapBasic

Export a window to a file: Save Window

Controlling the Printer: Set Window, Window Info()

Procedures (Main and Subs)

Define a procedure: Declare Sub, Sub...End Sub

Call a procedure: Call

Exit a procedure: Exit Sub

Main procedure: Main

Error Handling

Set up an error handler: OnError

Return current error information: Err(), Error$()

Return from error handler: Resume

Simulate an error: Error

MapBasic IDE Features

Setting Search Paths for MapBasic Include and Module Files

To make it easier to develop MapBasic libraries of definitions and modules, you can set environment
variables for search paths for Include (.def) files when compiling and Module (.mbo) files when
linking. By default, MapBasic will search for these files first in the path specified in your MapBasic
code and then under the folder where MapBasic is installed. By setting these environment variables
you can specify additional folders to search after the path specified in your code but before the

MapBasic 15.2 Reference 11

 Introduction to MapBasic

MapBasic folder. The environment variables are called MBINCLUDE and MBMODULE for Include
and Module files, respectively, and their values should be set to a semi-colon delimited list of folders
to search. MapBasic will search the folders specified and all sub-folders beneath them.
You can set environment variables via the Advanced System Settings on your system. The
variables must be set before you run MapBasic for them to be effective.
To set additional search folders for Include files, set the environment variable MBINCLUDE. For
example, if you have libraries of .def files in or beneath the folders C:\My MapBasic Library
and C:\Work, set the MBINCLUDE environment variable as follows:

Do not use quotes around the folder names even if the path contains spaces.
To set additional search folders for Module files, similarly set the environment variable MBMODULE.
For example, if you have libraries of .mbo files in or beneath the folder C:\My MapBasic Library,
set the MBMODULE environment variable as follows:

Here is an example of section of MapBasic code:

Include “mapbasic.def”
Include “utilities.def”
Include “myapplication.def”

Assuming you set your environment variables as above, when compiling MapBasic will search for
these .def files first in the folder where the file your are compiling is located, then under C:\My
MapBasic Library and its subfolders, next under C:\Work and its subfolders, and last under
the folder where MapBasic was installed. If the file utilities.def, for example, is used by multiple
applications you’ve written you can put it somewhere under C:\My MapBasic Library or C:\Work
and MapBasic can find it without you having to specify the path in the code.

MapBasic 15.2 Reference 12

 Introduction to MapBasic

Similarly your project (.mbp) file could look as follows:

[Link]Application=myapplication.mbx
Module=myapplication.mbo
Module=library.mbo

If the file library.mbo, for example, is used by multiple applications you’ve written you can put it
somewhere under C:\My MapBasic Library and MapBasic can find it without you having to
specify the path in the project file.

Functions

Custom Functions

Define a custom function: Declare Function, Function...End Function

Exit a function: Exit Function

Data-Conversion Functions

Convert strings to codes: Asc()

Convert codes to strings: Chr$()

Convert strings to numbers: Val()

Convert numbers to strings: Str$(), Format$()

Convert a number or a string to a date: NumberToDate(), StringToDate()

Converting to a 2-Digit Year: Set Date Window, DateWindow()

Convert object types: ConvertToRegion(), ConvertToPline()

Convert labels to text: LabelInfo()

MapBasic 15.2 Reference 13

 Introduction to MapBasic

Convert a point object to a MGRS coordinate: PointToMGRS$()

Convert a MGRS coordinate to a point object: MGRSToPoint()

Convert a point object to a USNG coordinate: PointToUSNG$(obj, datumid)

Convert a USNG coordinate to a point object: USNGToPoint(string)

Date and Time Functions

Obtain the current date CurDate()

Extract parts of a date value: Day(), Month(), Weekday(), Year()

Obtains the current time as a formatted string: Time()

Creates a date from a number or a string: NumberToDate(), StringToDate()

Obtain the current Time or DateTime: CurTime(), CurDateTime()

Obtain the Date or Time from a DateTime value: GetDate(), GetTime()

Create a DateTime or Time value from a number: NumberToDateTime(), NumberToTime()

Create a DateTime value from two individual Date and Time MakeDateTime()
values:

Create a DateTime or Time value from a string: StringToDateTime(), StringToTime()

Creates a string representation of a Date or Time value: FormatDate$(), FormatTime$()

Extract parts of a Time value: Hour(), Minute(), Second()

Sets and gets the rule for two-digit year input: Set Date Window(), DateWindow()

MapBasic 15.2 Reference 14

 Introduction to MapBasic

Math Functions

Trigonometric functions: Cos(), Sin(), Tan(), Acos(), Asin(), Atn()

Geographic functions: Area(), Perimeter(), Distance(), ObjectLen(),

CartesianArea(), CartesianPerimeter(),
CartesianDistance(), CartesianObjectLen(),
SphericalArea(), SphericalPerimeter(),
SphericalDistance(), SphericalObjectLen()

Random numbers: Randomize, Rnd()

Sign-related functions: Abs(), Sgn()

Truncating fractions: Fix(), Int(), Round()

Other math functions: Exp(), Log(), Minimum(), Maximum(), Sqr()

String Functions

Upper / lower case: UCase$(), LCase$(), Proper$()

Find a sub-string: InStr()

Extract part of a string: Left$(), Right$(), Mid$(), MidByte$()

Trim blanks from a string: LTrim$(), RTrim$()

Format numbers as strings: Format$(), Str$(), Set Format, FormatNumber$(),

DeformatNumber$()

Determine string length: Len()

Convert character codes: Chr$(), Asc()

Compare strings: Like(), StringCompare(), StringCompareIntl()

Repeat a string sequence: Space$(), String$()

MapBasic 15.2 Reference 15

 Introduction to MapBasic

Return unit name: UnitAbbr$(), UnitName$()

Convert a point object to a MGRS coordinate: PointToMGRS$()

Convert a MGRS coordinate to a point object: MGRSToPoint()

Convert an EPSG string to a CoordSys clause: EPSGToCoordSysString$()

Convert a point object to a USNG coordinate: PointToUSNG$(obj, datumid)

Convert a USNG coordinate to a point object: USNGToPoint(string)

Working With Tables

Creating and Modifying Tables

Open an existing table: Open Table

Close one or more tables: Close Table, Close All

Create a new, empty table: Create Table

Turn a file into a table: Register Table

Import/export tables/files: Import, Export

Modify a table's structure: Alter Table, Add Column, Create Index, Drop Index,
Create Map, Drop Map

Create a Crystal Reports file: Create Report From Table

Load a Crystal Report: Open Report

Add, edit, delete rows: Insert, Update, Delete

MapBasic 15.2 Reference 16

 Introduction to MapBasic

Pack a table: Pack Table

Control table settings: Set Table

Save recent edits: Commit Table

Discard recent edits: Rollback

Rename a table: Rename Table

Delete a table: Drop Table

Querying Tables

Position the row cursor: Fetch, EOT()

Select data, work with Selection: Select, SelectionInfo()

Find map objects by address: Find, Find Using, CommandInfo()

Find map objects at location: SearchPoint(), SearchRect(), SearchInfo()

Obtain table information: NumTables(), TableInfo()

Obtain column information: NumCols(), ColumnInfo()

Create a query table from Browser window: Create Query

Query a table's metadata: GetMetadata$(), Metadata

Query seamless tables: TableInfo(), GetSeamlessSheet()

Query raster or grid tables: RasterTableInfo() function, GridTableInfo(),

GetGridCellValue() function, IsGridCellNull() function,
getcurrentpathfunction() function

MapBasic 15.2 Reference 17

 Introduction to MapBasic

Working With Remote Data

Create a new table: Server Create Table

Communicate with data server: Server_Connect(), Server_ConnectInfo()

Begin work with remote server: Server Begin Transaction

Assign local storage: Server Bind Column

Obtain column information: Server_ColumnInfo(), Server_NumCols()

Send an SQL statement: Server_Execute()

Position the row cursor: Server Fetch, Server_EOT()

Save changes: Server

Discard changes: Server Rollback

Free remote resources: Server Close

Make remote data mappable: Server Create Map

Change object styles: Server Set Map

Synchronize a linked table: Server Refresh

Create a linked table: Server Link Table

Unlink a linked table: Unlink

Disconnect from server: Server Disconnect

Retrieve driver information: Server_DriverInfo(), Server_NumDrivers()

Get ODBC connection handle: Server_GetODBCHConn()

Get ODBC statement handle: Server_GetODBCHStmt()

MapBasic 15.2 Reference 18

 Introduction to MapBasic

Set Object styles: Server Create Style

Working With Files (Other Than Tables)

File Input/Output

Open or create a file: Open File

Close a file: Close File

Delete a file: Kill

Rename a file: Rename File

Copy a file: Save File

Read from a file: Get, Seek, Input #, Line Input

Write to a file: Put, Print #, Write #

Determine file's status: EOF(), LOF(), Seek(), FileAttr(), FileExists()

Turn a file into a table: Register Table

Retry on sharing error: Set File Timeout

File and Directory Names

Return system directories: ProgramDirectory$(), HomeDirectory$(),

ApplicationDirectory$()

Extract part of a filename: PathToTableName$(), PathToDirectory$(),

PathToFileName$()

MapBasic 15.2 Reference 19

 Introduction to MapBasic

Return a full filename: TrueFileName$()

Let user choose a file: FileOpenDlg(), FileSaveAsDlg()

Return temporary filename: TempFileName$()

Locate files: LocateFile$(), GetFolderPath$()

Working With Maps and Graphical Objects

Creating Map Objects

Creation statements: Create Arc, Create Ellipse, Create Frame, Create Line,
Create Object, Create PLine, Create Point, Create Rect,
Create Region, Create RoundRect, Create Text,
AutoLabel, Create Multipoint, Create Collection

Creation functions: CreateCircle(), CreateLine(), CreatePoint(), CreateText()

Advanced operations: Create Object, Buffer(), CartesianBuffer(),

CartesianOffset(), CartesianOffsetXY(), ConvexHull(),
Offset(), OffsetXY(), SphericalOffset(),
SphericalOffsetXY()

Store object in table: Insert, Update

Create regions: Objects Enclose

Modifying Map Objects

Modify object attribute: Alter Object

Change object type: ConvertToRegion(), ConvertToPLine()

MapBasic 15.2 Reference 20

 Introduction to MapBasic

Offset objects: Objects Offset, Objects Move

Set the editing target: Set Target

Erase part of an object: CreateCutter, Objects Erase, Erase(), Objects Intersect,

Overlap()

Merge objects: Objects Combine, Combine(), Create Object

Rotate objects: Rotate(), RotateAtPoint()

Split objects: Objects Pline, Objects Split

Add nodes at intersections: Objects Overlay, OverlayNodes()

Control object resolution: Set Resolution

Store an object in a table: Insert, Update

Check Objects for bad data: Objects Check

Object processing: Objects Disaggregate, Objects Snap, Objects Clean

Querying Map Objects

Return calculated values: Area(), Perimeter(), Distance(), ObjectLen(), Overlap(),

AreaOverlap(), ProportionOverlap()

Return coordinate values: ObjectGeography(), MBR(), ObjectNodeX(),

ObjectNodeY(), ObjectNodeZ(), Centroid(), CentroidX(),
CentroidY(), ExtractNodes(), IntersectNodes()

Return settings for coordinates, distance, area and paper SessionInfo()

units:

Configure units of measure: Set Area Units, Set Distance Units, Set Paper Units,
UnitAbbr$(), UnitName$()

Configure coordinate system: Set CoordSys

MapBasic 15.2 Reference 21

 Introduction to MapBasic

Return style settings: ObjectInfo()

Query a map layer's labels: LabelFindByID(), LabelFindFirst(), LabelFindNext(),

Labelinfo()

Processing Objects

Use concurrency when processing these objects: Create Object as Buffer, Objects Erase, Objects
Intersect, Objects Overlay

Working With Object Styles

Return current styles: CurrentPen(), CurrentBorderPen(), CurrentBrush(),

CurrentFont(), CurrentLinePen(), CurrentSymbol(), Set
Style, TextSize()

Return part of a style: LayerStyleInfo() function, StyleAttr()

Create style values: MakePen(), MakeBrush(), MakeFont(), MakeSymbol(),

MakeCustomSymbol(), MakeFontSymbol(), Set Style,
RGB()

Query object's style: ObjectInfo()

Modify object's style: Alter Object

Reload symbol styles: Reload Symbols

Style clauses: Pen clause, Brush clause, Symbol clause, Font clause

Working With Windows

Find the number of windows: NumWindows(), NumAllWindows()

Bring window to front: FrontWindow()

MapBasic 15.2 Reference 22

 Introduction to MapBasic

Close or hide a window: Close Window

Close all: Close All

Procedures: WinClosedHandler, WinFocusChangedHandler

Working With Map Windows

Open a map window: Map

Create/edit 3DMaps: Create Map3D, Set Map3D, Map3DInfo(), Create

PrismMap, Set PrismMap, PrismMapInfo()

Add a layer to a map: Add Map

Remove a map layer: Remove Map

Label objects in a layer: AutoLabel

Show all selected objects in a layer: Changing the Current View of the Map

Query a map's settings: MapperInfo(), LabelOverrideInfo(), LayerInfo(),

StyleOverrideInfo()

Change a map's settings: Set Map

Create or modify thematic layers: Shade, Set Shade, Create Ranges, Create Styles, Create
Grid, Relief Shade

Query a map layer's labels: LabelFindByID(), LabelFindFirst(), LabelFindNext(),

Labelinfo(), LabelOverrideInfo()

Working with Classic Layout Windows

MapInfo Pro lets you continue working with the classic Layout window to work with your older map
layouts for print or export. There is no new work or updates made to classic Layout window.

MapBasic 15.2 Reference 23

 Introduction to MapBasic

Create a Layout window: Layout

Create a frame in a layout: Create Frame

Modify a layout: Set Layout

Query a Layout window: WindowInfo

Print a layout: PrintWin

Set the focus to a Layout window or bring it to the front: Set Window, Run Menu Command

Working with Layout Windows

Create a Layout window: Layout

Create a frame in a layout: Create Frame

Add a map, a table (Browser), a map legend, an image, and Map, Browse, Create Designer Legend, Add Image
text to the layout: Frame, Create Text

Add a shape to the layout: Create Line, Create Ellipse, Create Rect, Create
RoundRect

Modify a layout or bring a frame to the front: Set Layout, Run Menu Command

Query map or browser frames in a layout: WindowInfo

Get information about a layout or layout frame: LayoutInfo(), LayoutItemInfo()

Print a layout: PrintWin

Set the focus to a Layout window or bring it to the front: Set Window, Run Menu Command

MapBasic 15.2 Reference 24

 Introduction to MapBasic

Working With Legend Windows

Create map legend: Create Designer Legend

Refresh and set orientation of window: Set Designer Legend

Create, modify, and remove a legend frame: Add Designer Frame, Alter Designer Frame, Remove
Designer Frame

Working With Cartographic Legend Windows

The Cartographic Legend window predates the Legend window, which was introduced in version
11.5. The Cartographic Legend window is for users who have created maps and legends in
pre-version 11.5 MapInfo Pro and who want to maintain the look and feel of those legends. For new
projects, we strongly recommend using the Legend window to ensure that your map legends are
forwards compatible with future releases of MapInfo Pro.

Create map legend and thematic map legend: Create Cartographic Legend, Create Legend

Refresh and set properties of window: Set Cartographic Legend

Create, modify, and remove a legend frame: Add Cartographic Frame, Alter Cartographic Frame,
Remove Cartographic Frame

Creating the User Interface

This version of MapBasic is compatible with both 32-bit and 64-bit versions of MapInfo® Pro. All
user interface modification MapBasic commands work the same way as before with the 32-bit version
of MapInfo Pro.
For MapInfo Pro 64-bit, as it uses the new Ribbon Interface instead of menus, MapBasic commands
related to ButtonPads and Menus create a new tab called LEGACY in the MapInfo Pro ribbon and
any modifications using these commands are visible only on this tab.

MapBasic 15.2 Reference 25

 Introduction to MapBasic

ButtonPads (ToolBars)
The 64-bit version of MapInfo Pro supports all the listed ButtonPads related MapBasic commands
except ButtonPadInfo().

Create a new ButtonPad: Create ButtonPad

Modify a ButtonPad: Alter ButtonPad

Modify a button: Alter Button

Query the status of a pad: ButtonPadInfo()

Respond to button use: CommandInfo()

Restore standard pads: Create ButtonPad As Default, Create ButtonPads As

Default

Menus
In the 64-bit version of MapInfo Pro, the MenuItemInfoByHandler() and MenuItemInfoByID()
commands listed below are only supported for addin controls, not for MapInfo Pro default controls.

Define a new menu: Create Menu

Redefine the menu bar: Create Menu Bar

Modify a menu: Alter Menu, Alter Menu Item

Modify the menu bar: Alter Menu Bar, Menu Bar

Invoke a menu command: Run Menu Command

Query a menu item's status: MenuItemInfoByHandler(), MenuItemInfoByID()

MapBasic 15.2 Reference 26

 Introduction to MapBasic

Dialog Boxes

Display a standard dialog box: Ask(), Note, ProgressBar, FileOpenDlg(),

FileSaveAsDlg(), GetSeamlessSheet()

Display a custom dialog box: Dialog

Dialog handler operations: Alter Control, TriggerControl(), ReadControlValue(),

Dialog Preserve, Dialog Remove

Determine whether user clicked OK: CommandInfo(CMD_INFO_DLG_OK)

Disable progress bars: Set ProgressBars

Modify a standard MapInfo Pro dialog box: Alter MapInfoDialog

Windows

Show or hide a window: Open Window, Close Window, Set Window

Open a new window: Map, Browse, Graph, Layout, Create Redistricter, Create
Legend, Create Cartographic Legend, LegendFrameInfo

Determine a window's ID: FrontWindow(), WindowID()

Modify an existing window: Set Map, Shade, Add Map, Remove Map, Set Browse,
Set Graph, Set Layout, Create Frame, Set Legend, Set
Cartographic Legend, Set Redistricter, StatusBar, Alter
Cartographic Frame, Add Cartographic Frame, Remove
Cartographic Frame

Return a window's settings: WindowInfo(), MapperInfo(), LayerInfo()

Print a window: PrintWin

Control window redrawing: Set Event Processing, Update Window, Control

DocumentWindow clause

MapBasic 15.2 Reference 27

 Introduction to MapBasic

Count number of windows: NumWindows(), NumAllWindows()

System Event Handlers

React to selection: SelChangedHandler

React to window closing: WinClosedHandler

React to map changes: WinChangedHandler

React to window focus: WinFocusChangedHandler

React to DDE request: RemoteMsgHandler, RemoteQueryHandler()

React to OLE Automation method: RemoteMapGenHandler

Provide custom tool: ToolHandler

React to termination of application: EndHandler

React to MapInfo Pro getting or losing focus: ForegroundTaskSwitchHandler

Disable event handlers: Set Handler

Communicating With Other Applications

DDE (Dynamic Data Exchange; Windows Only)

Start a DDE conversation: DDEInitiate()

Send a DDE command: DDEExecute

MapBasic 15.2 Reference 28

 Introduction to MapBasic

Send a value via DDE: DDEPoke

Retrieve a value via DDE: DDERequest$()

Close a DDE conversation: DDETerminate, DDETerminateAll

Respond to a request: RemoteMsgHandler, RemoteQueryHandler(),

CommandInfo(CMD_INFO_MSG)

Integrated Mapping

Set MapInfo Pro 's parent window: Set Application Window

Set a Map window's parent: Set Next Document

Create a Legend window: Create Legend

Create a Layout window: Layout

Special Statements and Functions

Defines the name and argument list of a method/function Declare Method()

in a .Net assembly

Launch another program: Run Program

Return information about the system: SystemInfo()

Run a string as an interpreted command: Run Command

Save a workspace file: Save Workspace

Load a workspace file or an MBX: Run Application

MapBasic 15.2 Reference 29

 Introduction to MapBasic

Configure a digitizing tablet: Set Digitizer

Send a sound to the speaker: Beep

Set data to be read by CommandInfo: Set Command Info

Set duration of the drag-object delay: Set Drag Threshold

Switch between 1-bit per pixel cursors and 32-bit per pixel Set Cursor
cursors:

Getting Technical Support

Pitney Bowes Inc. offers a free support period on all new software purchases and upgrades, so you
can be productive from the start. Once the free period ends, Pitney Bowes Inc. offers a broad
selection of extended support services for individual, business, and corporate users.
Technical Support is here to help you, and your call is important. This section lists the information
you need to provide when you call your local support center. It also explains some of the technical
support procedures so that you will know what to expect about the handling and resolution of your
particular issue.
Please remember to include your serial number, partner number or contract number when contacting
Technical Support.

Contacting Technical Support

To use Technical Support, you must register your product. This can be done very easily during
installation or anytime during normal business hours by contacting Customer Service directly.
Full technical support for MapBasic is provided for the currently shipping version plus the two previous
versions.

Technical Support Contact Information

Extended support options are available at each of our technical support centers in the Americas,
Europe/Middle East/Africa, and Asia-Pacific regions. To contact the office nearest you, refer to the
Contact Support section on our website:
www.mapinfo.com/support

MapBasic 15.2 Reference 30

 Introduction to MapBasic

Technical Support Online Case Management System

The Technical Support Online Case Management system is another way to log and manage cases
with our Technical Support center. You must register yourself the first time you access this site if
you do not already have a user ID.
http://go.pbinsight.com/online-case-management

Before You Call

Please have the following information ready when contacting us for assistance.
1. Serial Number. You must have a registered serial number to receive Technical Support.
2. Your name and organization. The person calling must be the contact person listed on the support
agreement.
3. Version of the product you are calling about.
4. The operating system name and version.
5. A brief explanation of the problem. Some details that can be helpful in this context are:
• Error messages
• Context in which the problem occurs
• Consistency - is the problem reoccurring or occurring erratically?

Expected Response Time

Most issues can be resolved during your initial call. If this is not possible, Technical Support will
issue a response before the end of the business day. A representative will provide a status each
business day until the issue is resolved.
Support requests submitted by e-mail or through the online tracking system are handled using the
same guidelines as telephone support requests; however, there is an unavoidable delay of up to
several hours for message transmission and recognition.

Software Defects
If the issue is deemed to be a bug in the software, the representative will log the issue in Pitney
Bowes Inc. bug database and provide you with an incident number that you can use to track the
bug. Future upgrades and patches have fixes for many of the bugs logged against the product.

Other Resources
MapInfo-L Archive Database
Pitney Bowes Inc. Corporation, in conjunction with Bill Thoen, provides a web-based, searchable
archive database of MapInfo-L postings. The postings are currently organized by Discussion Threads
and Postings by Date.

MapBasic 15.2 Reference 31

 Introduction to MapBasic

Disclaimer: While Pitney Bowes Inc. Corporation provides this database as a service to its user
community, administration of the MapInfo-L mailing list is still provided by Bill Thoen. More information
on MapInfo-L can be obtained at the MapInfo-L web page located at
http://groups.google.com/group/mapinfo-l?hl=en.

Copyright

Information in this document is subject to change without notice and does not represent a commitment
on the part of the vendor or its representatives. No part of this document may be reproduced or
transmitted in any form or by any means, electronic or mechanical, including photocopying, without
the written permission of Pitney Bowes Software Inc., One Global View, Troy, New York 12180-8399.
© 2015 Pitney Bowes Software Inc. All rights reserved. Pitney Bowes Software Inc. is a wholly owned
subsidiary of Pitney Bowes Inc. Pitney Bowes, the Corporate logo, MapInfo, Group 1 Software, and
MapBasic are trademarks of Pitney Bowes Software Inc. All other marks and trademarks are property
of their respective holders.
Contact information for all Pitney Bowes Software Inc. offices is located at:
http://www.pitneybowes.com/us/contact-us.html.
© 2015 Adobe Systems Incorporated. All rights reserved. Adobe, the Adobe logo, Acrobat and the
Adobe PDF logo are either registered trademarks or trademarks of Adobe Systems Incorporated in
the United States and/or other countries.
© 2015 OpenStreetMap contributors, CC-BY-SA; see OpenStreetMap
http://www.openstreetmap.org (license available at www.opendatacommons.org/licenses/odbl)
and CC-BY-SA http://creativecommons.org/licenses/by-sa/2.0
libtiff © 1988-1997 Sam Leffler, © 2015 Silicon Graphics Inc. All Rights Reserved.
libgeotiff © 2015 Niles D. Ritter.
Amigo, Portions © 1999 Three D Graphics, Inc. All Rights Reserved.
Halo Image Library © 1993 Media Cybernetics Inc. All Rights Reserved.
Portions thereof LEAD Technologies, Inc. © 1991-2015. All Rights Reserved.
Portions © 1993-2015 Ken Martin, Will Schroeder, Bill Lorensen. All Rights Reserved.
ECW by ERDAS © 1993-2015 Intergraph Corporation, part of Hexagon Group and/or its suppliers.
All rights reserved.
Portions © 2015 Intergraph Corporation, part of Hexagon Group All Rights Reserved.
MrSID, MrSID Decompressor and the MrSID logo are trademarks of LizardTech, A Celartem
Company. used under license. Portions of this computer program are copyright © 1995-1998
LizardTech, A Celartem Company, and/or the university of California or are protected by US patent
no. 5,710,835 and are used under license. All rights reserved. MrSID is protected under US and

MapBasic 15.2 Reference 32

 Introduction to MapBasic

international patent & copyright treaties and foreign patent applications are pending. Unauthorized
use or duplication prohibited.
Contains FME® Objects © 2005-2015 Safe Software Inc., All Rights Reserved.
Amyuni PDF Converter © 2000-2015, AMYUNI Consultants – AMYUNI Technologies. All rights
reserved.
Civic England - Public Sector Symbols Copyright © 2015 West London Alliance. The symbols may
be used free of charge. For more information on these symbols, including how to obtain them for
use in other applications, please visit the West London Alliance Web site at
http://www.westlondonalliance.org
© 2006-2015 TomTom International BV. All Rights Reserved. This material is proprietary and the
subject of copyright protection and other intellectual property rights owned or licensed to TomTom.
The use of this material is subject to the terms of a license agreement. You will be held liable for
any unauthorized copying or disclosure of this material.
Microsoft Bing: All contents of the Bing service are Copyright © 2015 Microsoft Corporation and/or
its suppliers, One Microsoft Way, Redmond, WA 98052, USA. All rights reserved. Microsoft or its
suppliers own the title, copyright, and other intellectual property rights in the Bing service and content.
Microsoft, Windows, Windows Live, Windows logo, MSN, MSN logo (butterfly), Bing, and other
Microsoft products and services may also be either trademarks or registered trademarks of Microsoft
in the United States and/or other countries.
This product contains 7-Zip, which is licensed under GNU Lesser General Public License, Version
3, 29 June 2007 with the unRAR restriction. The license can be downloaded from
http://www.7-zip.org/license.txt. The GNU License may be downloaded from
http://www.gnu.org/licenses/lgpl.html. The source code is available from http://www.7-zip.org.
Products named herein may be trademarks of their respective manufacturers and are hereby
recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with
no intent to infringe on the trademark.

OpenSource Attribution Notices

QT Assistant 5.2.0
This product contains QT Assistant, version 5.2.0, which is licensed under GNU Lesser General
Public License, Version 2.1, February 1999. The license can be downloaded from:
http://www.gnu.org/licenses/lgpl-2.1.txt. The source code for this software is available from
http://qt-project.org/downloads.

MapBasic 15.2 Reference 33

2 - New and Enhanced
MapBasic Statements
and Functions

In this section
New MapBasic Functions and Statements 35
Updates to Existing Functions and Statements 35
 New and Enhanced MapBasic Statements and Functions

New MapBasic Functions and Statements

The following is a list of new functions and statements in this release:

• Add Custom Frame statement - Adds a custom frame to a Layout window.
• Add Designer Page statement - Adds one page to the Layout window.
• CharVal() function - Returns the character code for the first character in a string expression. This
function is the Unicode corollary of the Asc() function, so that the return value maps to the Unicode
character set encoding of the string expression (string_expr), rather than the system character
set mapping.
• ChrU$() function - Returns a one-character string corresponding to a specified character code.
This function is the Unicode corollary of the Chr$() function, so that the num_expr encoding maps
to the Unicode character codes rather than the system environment character codes.
• GetLicenseKind() function - Returns a value representing the kind of license MapInfo Pro is
using.
• GetPreference() function - Returns the value of the specified preference.
• LayoutPageItemInfo() function - Returns information about a frame on a specific page within a
Layout window.
• Remove Designer Page statement - Removes a page from the Layout window.
• Set FastPointRendering statement - Allows MapBasic developers to enable or disable Fast
Point Rendering. This command overrides the Fast Symbol Rendering preference set in MapInfo
Pro.
• Set Workspace Warning statement - Turns the save workspace message prompt on or off, that
appears when attempting to close MapInfo Pro.

Updates to Existing Functions and Statements

Dim statement - Now declares three more variables: IntPtr to represent a pointer or a handle,
and This and RefPtr to reference a .NET object.
FileOpenDlg() function - Added the following to the list of file types that will appear in the File
Open dialog box:

filetype parameter Type of files that appear

"XLS", "XLSX" Excel spreadsheet files

MapBasic 15.2 Reference 35

 New and Enhanced MapBasic Statements and Functions

filetype parameter Type of files that appear

"MDB", "ACCDB" Microsoft Access Database files

Run Menu Command statement - Added a section about accessing the Layout Window menu
options.
Set Table statement - A new InUse clause specifies what sort of access (ReadAccess or
WriteAccess) is available to a table when it is in use.
TableInfo() function - This function has new attributes. For information on how to set a table as in
use, see the Set Table statement.

attribute code ID TableInfo() returns

TAB_INFO_INUSE 46 Logical result: TRUE when a table is in use, and FALSE

when it is not in use.

TAB_INFO_DATA_FORMAT 47 SmallInt result: indicates the data format of the base table
(which is not a WMF, WFS, raster, FME, or query). The
return values are:

• TAB_DATA_FORMAT_NONE (0): not a base table

• TAB_DATA_FORMAT_DBASE (1): dBase DBF
• TAB_DATA_FORMAT_LOTUS (2): Lotus 1-2-3
• TAB_DATA_FORMAT_ASCII (3): Delimited ASCII
• TAB_DATA_FORMAT_EXCEL (4): Microsoft Excel
• TAB_DATA_FORMAT_NATIVE (5): MapInfo TAB
• TAB_DATA_FORMAT_DAO (8): Microsoft Access
• TAB_DATA_FORMAT_ODBC (10): ODBC
• TAB_DATA_FORMAT_NATIVEX (14): MapInfo
Extended TAB
• TAB_DATA_FORMAT_GPKG (15): GeoPackage

TAB_INFO_CHARSET 48 String value: the name of the table character set.

TAB_INFO_MAP_BLOCKSIZE 49 SmallInt result: the block size of the map file. If table is
not mappable, returns -1. (A table without a .map file
returns -1.)

TAB_INFO_READVERSION 50 Integer result: earliest version that can read the table.

TAB_INFO_EDITVERSION 51 Integer result: earliest version that can edit the table.

MapBasic 15.2 Reference 36

 New and Enhanced MapBasic Statements and Functions

attribute code ID TableInfo() returns

TAB_INFO_READALLVERSION 52 Integer result: earliest version that can read the entire
table.

The following statements now include a Priority clause to assign the Z-Order of the newly created
object frame on the Layout window, and a Name clause to assign a name to the frame:
• Create Ellipse statement
• Create Line statement
• Create Pline statement
• Create Point statement
• Create Rect statement
• Create Region statement
• Create RoundRect statement
Open Connection statement - New subclause, Servicename added to support new geocoding
services.
Geocode statement - New clause, PassThrough added that represents a set of name/value pairs
that are sent to the geocoder.
New Layout Window Enhancements
Create Text statement - Now supports the Angle clause for Layout windows.
LayerInfo() function - Has new attributes:

Attribute Code ID LayerInfo() Return Value

LAYER_INFO_GRIDLINE_COORDSYS 65 String value, containing the coordinate system used to

create the Gridline. Empty when layer is not a Gridline.

LAYER_INFO_GRIDLINE_SPACE_HORIZONTAL 66 Smallint value, representing the horizontal map spacing

of the Gridline. If using automatic spacing, this is the
horizontal spacing. Otherwise, this is the horizontal
spacing as requested by the user. If lines are closer than
the minimum horizontal paper spacing, this returns the
horizontal spacing displayed on the map (which should
be a larger value than requested). Returns 0.0 when layer
is not a Gridline.

LAYER_INFO_GRIDLINE_SPACE_VERTICAL 67 Smallint value, representing the vertical map spacing of

the Gridline. If using automatic spacing, this is the vertical
spacing. Otherwise, this is the vertical spacing as
requested by the user. If lines are closer than the
minimum vertical paper spacing, this returns the vertical
spacing displayed on the map (which should be a larger

MapBasic 15.2 Reference 37

 New and Enhanced MapBasic Statements and Functions

Attribute Code ID LayerInfo() Return Value

value than requested). Returns 0.0 when layer is not a

Gridline.

LAYER_INFO_GRIDLINE_AUTO 68 Logical value, indicates TRUE if the layer is a Gridline

that is using automatic spacing.

LAYER_INFO_GRIDLINE_MIN_HORIZONTAL 69 Smallint value, representing minimum paper spacing

allowed between horizontal Gridlines when using
automatic spacing. The value is in the current paper unit
(see Set Paper Units statement). Returns 0 when layer
is not a Gridline.

LAYER_INFO_GRIDLINE_MIN_VERTICAL 70 Smallint value, representing minimum paper spacing

allowed between vertical Gridlines when using automatic
spacing. The value is in the current paper unit (see Set
Paper Units statement).

LAYER_INFO_GRIDLINE_PAPER_HORIZONTAL 71 Smallint value, representing the current paper distance

of the horizontal gridlines. The value is in the current
paper unit (see Set Paper Units statement). Returns 0
when layer is not a Gridline.

LAYER_INFO_GRIDLINE_PAPER_VERTICAL 72 Smallint value, representing the current paper distance

of the vertical gridlines. The value is in the current paper
unit (see Set Paper Units statement). Returns 0 when
layer is not a Gridline.

LAYER_INFO_GRIDLINE_OFFSET 73 Smallint value, representing the current paper unit

distance of gridline labels from the edge of the map
(inwards). The value is in the current paper unit (see Set
Paper Units statement). Returns -1 when layer is not a
Gridline.

LAYER_INFO_LABEL_POS_RETRY 74 Logical value, TRUE if the label property for Try other
positions is set and FALSE otherwise.

LayoutInfo() function - New attributes have been added to this function:

Attribute Parameter ID Return Value

LAYOUT_INFO_NUM_PAGES 11 Integer value: The number of pages in the layout.

LAYOUT_INFO_CUR_PAGE 12 Integer value: The page number of the visible, or current,

page.

MapBasic 15.2 Reference 38

 New and Enhanced MapBasic Statements and Functions

LayoutItemInfo() function - New attributes have been added to this function:

Attribute Parameter ID LayoutItemInfo() Return Value

LAYOUT_ITEM_INFO_ANGLE 18 Float value: Returns the angle of rotation for a text frame
(in degrees)

LAYOUT_ITEM_INFO_ADDIN_FILE_NAME 19 String: Name of the custom frame add-in .mbx file.

LAYOUT_ITEM_INFO_SERIALIZED_NAME 20 String: Name of the custom frame serialized file.

LAYOUT_ITEM_INFO_XPS_VIEW_NAME 21 String: Name of the custom frame XPS view file.

LAYOUT_ITEM_INFO_NUM_ITEMS_ON_PAGE 22 Integer: Number of frames on this layout page. Frame

ID is ignored.

The following is a new frame type returned using LAYOUT_ITEM_INFO_TYPE.

Frame Type ID Frame Description

LAYOUT_ITEM_TYPE_CUSTOM 7 A custom frame.

Set Layout statement - Now includes a Page clause to set the current page in a multi-page Layout
window.
Set Map statement - Has a new section, Set Map Layer Gridline, that describes how to work with
gridlines.
Support For Working in Multiple Languages
Asc() function and Chr$ function - In Unicode versions of MapInfo Pro, these functions operate
in the system character set in a compatible manner with the non-Unicode versions of MapInfo Pro.
CharSet clause - Now supports "Utf-8" for a workspace character set or Native Extended format
table character set and to allow characters from any language to be represented. It can also be
used when importing, opening or registering a non-native table. This clause also supports "UTF-16"
for a Native Extended format table character set.
MidByte$() function - On systems with single-byte character sets, or in Unicode versions of MapInfo
Pro, the results returned by the MidByte$() function are identical to the results returned by the
Mid$() function.
Register Table statement - Now supports Unicode character sets for XLS, ODBC, Raster, and
Shape files. Also, the persistent cache type for shape files and cache for ODBC files can be set to
MapInfo (Native) or MapInfo Extended (NativeX) Tab file formats.

MapBasic 15.2 Reference 39

 New and Enhanced MapBasic Statements and Functions

Save Workspace statement - Includes the new CharSet clause to specify a character set. It's
char_set parameter should be a string constant, such as "WindowsLatin1". If no CharSet clause is
specified, MapBasic uses the system character set that is in use at runtime. Specifying "UTF-8" as
the workspace character set allows characters from any language to be represented.
SystemInfo() function - Has new attributes.

attribute code ID SystemInfo() Return Value

SYS_INFO_UNICODE 22 Logical: TRUE when MapInfoPro (64-bit version) is

running as Unicode, and FALSE when running a
multi-byte character set.

SYS_INFO_CULTURE 23 String: returns a two-letter code from the operating

system culture ("en" = English, "fr" = France, "de" =
German, "ja" = Japanese).

Support For Large Data Tables

The following statements let you specify whether to save in MapInfo (NATIVE) or MapInfo Extended
(NATIVEX) format. The new NATIVEX format supports data files that are greater than 2GB in size
and character sets UTF-8 and UTF-16:
• Commit Table statement - A Charset clause saves to a specific character set and a Locale
clause lets you set a string that specifies the local of the index to create, such as "en-US".
• Create Table statement - A Charset clause saves to a specific character set and a Locale clause
lets you set a string that specifies the local of the index to create, such as "en-US".
• Server Link Table statement - A Charset clause saves to a specific character set.
• Import statement - For details, see Importing MIF/MID, PICT, or MapInfo for DOS Files.
To support file sizes greater than 2GB, MapBasic functions and statements that return or use file
offsets and file sizes now return or use 64-bit integers.
• LOF function returns the size of a file as a LargeInt value.
• Seek function returns the current position in an open file as a LargeInt value.
• FileAttr function returns the size of a file when the FILE_ATTR_FILESIZE attribute is passed as
a LargeInt value.
• Get statement and Seek statement take a LargeInt value for the file position.
In MapBasic, a 64-bit integer is stored in a LargeInt variable. Existing applications are likely using
Integer values rather than LargeInt. If the file size is less than 2GB then everything should work as
before. If the application is used for file sizes greater than 2GB and the return values for LOF, Seek,
and FileAttr are put into Integer variables, then a MapBasic Overflow error could occur.
The following statements have been enhanced with an optional DropIndex clause that suspends
updating transaction indexes while executing an operation and recreates them when the operation
is complete:

MapBasic 15.2 Reference 40

 New and Enhanced MapBasic Statements and Functions

• Insert statement (when set to Off or Auto, behavior varies slightly from other statements)
• Delete statement
• Update statement
• Objects Combine statement
• Objects Disaggregate statement
• Objects Erase statement
• Objects Intersect statement
• Objects Split statement
The following statements include a new BlockSize clause to specify the block size of a MapInfo
Native or NativeX (MapInfo Extended) files. Generally, the larger the block size, the faster the data
transfer rate.
• Commit Table statement
• Create Map statement
To support working with large values, MapBasic now uses the LargeInt variable for some functions
and statements, see Large Integer Variables. Also, the following functions have attributes that now
return a IntPtr value.
• SystemInfo() function return values SYS_INFO_APPLICATIONWND, SYS_INFO_MAPINFOWND,
SYS_INFO_MDICLIENTWND, and SYS_INFO_APPIDISPATCH.
• WindowInfo() function return value WIN_INFO_WND.
Additions from MapInfo Pro 15.0
The following additions were made in MapInfo Pro 15.0 (32-bit) and are included in this 64-bit release:
Alter Designer Frame statement - Lets you set the width and height of layout frames using the
new Height and Width clauses. Lets you set the name of an existing layout frame using the new
Name clause.
Create Frame statement - Create empty frames for the Layout window to add template functionality
for layouts and to create place-holders at any position of any valid frame size. For details, see Create
Empty Frames.
LayerInfo() function - Has a new attribute:

Attribute Code ID LayerInfo() Return Value

LAYER_INFO_FRIENDLYNAME 64 String value, the friendly name assigned to a layer.

LayoutItemID() function - A new function returns a frame ID within a Layout window.

LayoutItemInfo() function - The values of some of the existing layout frame attributes are now
accessible with this funtion:

MapBasic 15.2 Reference 41

 New and Enhanced MapBasic Statements and Functions

Attribute Parameter ID LayoutItemInfo() Return Value

LAYOUT_ITEM_INFO_NAME 14 String value: Returns the name of the layout frame.

LAYOUT_ITEM_INFO_PEN 15 Pen value. Returns the pen of a shape or a frame.

LAYOUT_ITEM_INFO_FILL_BRUSH 16 Brush value. Returns the brush style of a shape or a

frame. This is not valid for a frame containing a line
shape.

LAYOUT_ITEM_INFO_Z_ORDER 17 Integer. Returns the z-order of the item. The z-order is

taken from the normalized set of frame priorities where
each element is unique.

Map statement and Browse statement - Use the ID clause to insert open tables into the empty
layout frame. The frame properties already set for the empty frame are retained (pen, brush, position,
size, name, and z-order).
Set Designer Frame statement - A new funtion that converts a normal layout frame into an empty
frame, or converts an empty frame into a map frame or browser frame, by cloning an existing Map
or Browser window. Use the Clear attribute to turn a layout frame into an empty frame.
Set Layout statement - The new Selection clause changes the selection of frames in a Layout
window.
Set Map statement - A new FriendlyName clause sets a pretty (friendly) name for a layer, which
persists in the workspace. For details, see Managing Individual Layer Properties and Appearance.
Set Table statement - Use the Description clause to write a default pretty (friendly) name for a
layer to the TAB file’s Description field.

MapBasic 15.2 Reference 42

3 - A to Z MapBasic
Language Reference
This section describes the MapBasic language in detail. You will find both
statements and function descriptions arranged alphabetically.

In this section
Function and Statement Conventions 44
Function and Statement Descriptions 44
 A to Z MapBasic Language Reference

Function and Statement Conventions

Each function and statement is described in the following format:

Purpose
Brief description of the function, clause, or statement.
Restrictions
Information about limitations (for example, "The DDEInitiate function is only available under Microsoft
Windows," "You cannot issue a For…Next statement through the MapBasic window").
Syntax
The format in which you should use the function or statement and explanation of argument(s).
Return Value
The type of value returned by the function.
Description
Thorough explanation of the function or statement's role and any other pertinent information.
Example
A brief example.
A description ends with a list of links to related functions and statements.
Most MapBasic statements can be typed directly into MapInfo Pro through the MapBasic window.
If a statement may not be entered through the MapBasic window, then the Restrictions section
identifies the limitation. Generally, flow-control statements (such as looping and branching statements)
cannot be entered through the MapBasic window.

Function and Statement Descriptions

The following topics describe functions, statements, and clauses. Some topics provide more details
on how to apply a function or statement.

MapBasic 15.2 Reference 44

 A to Z MapBasic Language Reference

Abs() function
Purpose
Returns the absolute value of a number. You can call this function from the MapBasic window in
MapInfo Pro.

Syntax

Abs ( num_expr )

num_expr is a numeric expression.

Return Value
Float

Description
The Abs() function returns the absolute value of the expression specified by num_expr.
If num_expr has a value greater than or equal to zero, Abs() returns a value equal to num_expr. If
num_expr has a negative value, Abs() returns a value equal to the value of num_expr multiplied by
negative one (-1).

Example

Dim f_x, f_y As Float

f_x = -2.5
f_y = Abs(f_x)

' f_y now equals 2.5

See Also:
Sgn() function

Acos() function
Purpose
Returns the arc-cosine value of a number. You can call this function from the MapBasic window in
MapInfo Pro.

Syntax

Acos ( num_expr )

MapBasic 15.2 Reference 45

 A to Z MapBasic Language Reference

num_expr is a numeric expression between one and negative one, inclusive.

Return Value
Float

Description
The Acos() function returns the arc-cosine of the numeric num_expr value. In other words, Acos()
returns the angle whose cosine is equal to num_expr.
The result returned from Acos() represents an angle, expressed in radians. This angle will be
somewhere between zero and Pi radians (given that Pi is equal to approximately 3.141593, and
given that Pi/2 radians represents 90 degrees).
To convert a degree value to radians, multiply that value by DEG_2_RAD. To convert a radian value
into degrees, multiply that value by RAD_2_DEG. Your program must Include MAPBASIC.DEF in
order to reference DEG_2_RAD or RAD_2_DEG.
Since cosine values range between one and negative one, the expression num_expr should represent
a value no larger than one and no smaller than negative one.

Example

Include "MAPBASIC.DEF"
Dim x, y As Float
x = 0.5
y = Acos(x) * RAD_2_DEG
' y will now be equal to 60,
' since the cosine of 60 degrees is 0.5

See Also:
Asin() function, Atn() function, Cos() function, Sin() function, Tan() function

ActiveWindow() function
Purpose
Returns current active window. You can call this function from the MapBasic window in MapInfo
Pro.
returns current docking manager active window in MapInfo Pro 64-bit.

Syntax

ActiveWindow ( )

MapBasic 15.2 Reference 46

 A to Z MapBasic Language Reference

Return Value
Integer

Add Cartographic Frame statement

Purpose
The Add Cartographic Frame statement adds cartographic frames to an existing cartographic
legend created with the Create Cartographic Legend statement. You can issue this statement
from the MapBasic window in MapInfo Pro.

Syntax

Add Cartographic Frame

[ Window legend_window_id ]
[ Custom ]
[ Default Frame Title { def_frame_title } [ Font... ] ]
[ Default Frame Subtitle { def_frame_subtitle } [ Font... ] ]
[ Default Frame Style { def_frame_style } [ Font... ] ]
[ Default Frame Border Pen... pen_expr ]
Frame From Layer { map_layer_id | map_layer_name }
[ Position ( x , y ) [ Units paper_units ] ]
[ Using
[ Column { column | object [ FromMapCatalog { On | Off }]} ]
[ Label { expression | default } ]
[ Title [ frame_title ] [ Font... ] ]
[ SubTitle [ frame_subtitle ] [ Font... ] ]
[ Border Pen... ]
[ Style [Font...] [ NoRefresh ]
[ Text { style_name } { Line Pen...
| Region Pen... Brush...
| Symbol Symbol... } ]
[ , ... ]
]
[ , ... ]

legend_window_id is an integer window identifier that you can obtain by calling the FrontWindow()
function and WindowID() function.
def_frame_title is a string which defines a default frame title. It can include the special character "#"
which will be replaced by the current layer name.
def_frame_subtitle is a string which defines a default frame subtitle. It can include the special
character "#" which will be replaced by the current layer name.
def_frame_style is a string that displays next to each symbol in each frame. The "#" character will
be replaced with the layer name. The "%" character will be replaced by the text "Line", "Point,
"Region", as appropriate for the symbol. For example, "% of #" will expand to "Region of States" for
the STATES.TAB layer.

MapBasic 15.2 Reference 47

 A to Z MapBasic Language Reference

pen_expr is a Pen expression, for example, MakePen( width, pattern, color ). If a default border pen
is defined, then it will be become the default for the frame. If a border pen clause exists at the frame
level, then it is used instead of the default.
map_layer_id or map_layer_name identifies a map layer; can be a SmallInt (e.g., use 1 to specify
the top map layer other than Cosmetic) or a string representing the name of a table displayed in the
map. For a theme layer you must specify the map_layer_id.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in
(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
frame_title is a string which defines a frame title. If a Title clause is defined here for a frame, then
it will be used instead of the def_frame_title.
frame_subtitle is a string which defines a frame subtitle. If a SubTitle clause is defined here for a
frame, then it will be used instead of the def_frame_subtitle.
column is an attribute column name from the frame layer's table, or the object column (meaning
that legend styles are based on the unique styles in the mapfile). The default is 'object'.
style_name is a string which displays next to a symbol, line, or region in a custom frame.

Description
If the Custom keyword is included, then each frame section must include a Position clause. If
Custom is omitted and the legend is laid out in portrait or landscape, then the frames will be added
to the end.
The Position clause controls the frame's position on the legend window. The upper left corner of
the legend window has the position 0, 0. Position values use paper unit settings, such as "in"
(inches) or "cm" (centimeters) (see Set Paper Units statement). MapBasic has a current paper
units setting, which defaults to inches; a MapBasic program can change this setting through the Set
Paper Units statement.You can override the current paper units by including the optional Units
subclause within the Position clause.
The defaults in this statement apply only to the frames being created in this statement. They have
no affect on existing frames. Frame defaults used in the Create Cartographic Legend statement
have no affect on frames created in this statement.
When you save to a workspace, the FromMapCatalog OFF clause is written to the workspace
when specified. This requires the workspace version increasing to 800. If the FromMapCatalog
ON clause is specified, we do not write it to the workspace since it is default behavior. This lets us
avoid increasing the workspace version.

MapBasic 15.2 Reference 48

 A to Z MapBasic Language Reference

FromMapCatalog ON retrieves styles from the MapCatalog for a live access table. If the table is
not a live access table, MapBasic reverts to the default behavior for a non-live access table instead
of throwing an error. The default behavior for a non-access table is FromMapCatalog Off (for
example, map styles).
FromMapCatalog OFF retrieves the unique map styles for the live table from the server. This table
must be a live access table that supports per record styles for this to occur. If the live table does
not support per record styles than the behavior is to revert to the default behavior for live tables,
which is to get the default styles from the MapCatalog (FromMapCatalog ON).
Label is a valid expression or default (meaning that the default frame style pattern is used when
creating each style's text, unless the style clause contains text). The default is default.
The Style clause and the NoRefresh keyword allow you to create a custom frame that will not be
overwritten when the legend is refreshed. If the NoRefresh keyword is used in the Style clause,
then the table is not scanned for styles. Instead, the Style clause must contain your custom list of
definitions for the styles displayed in the frame. This is done with the Text and appropriate Line,
Region, or Symbol clause.
See Also:
Create Cartographic Legend statement, Set Cartographic Legend statement, Alter Cartographic
Frame statement, Remove Cartographic Frame statement

Add Column statement

Purpose
Adds a new, temporary column to an open table, or updates an existing column with data from
another table. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Add Column table ( column [ datatype ] )

{ Values const [ , const ... ] |
From source_table
Set To expression
[ Where { dest_column = source_column |
Within | Contains | Intersects } ]
[ Dynamic ] }

table is the name of the table to which a column will be added.

column is the name of a new column to add to that table.
datatype is the data type of the column, defined as Char(width), Float, Integer, SmallInt,
Decimal(width, decimal_places), Date or Logical, DateTime; if not specified, type defaults to Float.
A DateTime is an integer value stored in nine bytes: 4 bytes for date, 5 bytes for time. Five bytes
for time include: 2 for millisec, 1 for sec, 1 for min, 1 for hour.

MapBasic 15.2 Reference 49

 A to Z MapBasic Language Reference

source_table is the name of a second open table.

expression is the expression used to calculate values to store in the new column; this expression
usually extracts data from the source_table, and it can include aggregate functions.
dest_column is the name of a column from the destination table (table).
source_column is the name of a column from the source_table.
Dynamic specifies a dynamic (hot) computed column that can be automatically update: if you include
this keyword, then subsequent changes made to the source table are automatically applied to the
destination table.

Description
The Add Column statement creates a temporary new column for an existing MapInfo Pro table.
The new column will not be permanently saved to disk. However, if the temporary column is based
on base tables, and if you save a workspace while the temporary column is in use, the workspace
will include information about the temporary column, so that the temporary column will be rebuilt if
the workspace is reloaded. To add a permanent column to a table, use the Alter Table statement
and Update statement.
See Also:
Alter Table statement, Update statement

Filling the New Column with Explicit Values

Using the Values clause, you can specify a comma-separated list of explicit values to store in the
new column.
The following example adds a temporary column to a table of "ward" regions. The values for the
new column are explicitly specified, through the Value clause.

Open Table "wards"

Add Column wards(percent_dem)
Values 31,17,22,24,47,41,66,35,32,88

Filling the New Column with Values from Another Table

If you specify a From clause instead of a Values clause, MapBasic derives the values for the new
column from a separate table (source_table). Both tables must already be open.
When you use a From clause, MapInfo Pro joins the two tables. To specify how the two tables are
joined, include the optional Where clause. If you omit the Where clause, MapInfo Pro automatically
tries to join the two tables using the most suitable method.
A Where clause of the form Where column = column joins the two tables by matching column values
from the two tables. This method is appropriate if a column from one of your tables has values
matching a column from the other table (e.g., you are adding a column to the States table, and your
other table also has a column containing state names).

MapBasic 15.2 Reference 50

 A to Z MapBasic Language Reference

If both tables contain map objects, the Where clause can specify a geographic join. For example,
if you specify the clause Where Contains, MapInfo Pro constructs a join by testing whether objects
from the source_table contain objects from the table that is being modified.
The following example adds a "County" column to a "Stores" table. The new column will contain
county names, which are extracted from a separate table of county regions:

Add Column
stores(county char(20) 'add "county" column
From counties 'derive data from counties table...
Set to cname 'using the counties table's "cname" column
Where Contains 'join: where a county contains a store site

The Where Contains method is appropriate when you add a column to a table of point objects, and
the secondary table represents objects that contain the points.
The following example adds a temporary column to the States table. The new column values are
derived from a second table (City_1K, a table of major U.S. cities). After the completion of the Add
Column statement, each row in the States table will contain a count of how many major cities are
in that state.

Open Table "states" Interactive

Open Table "city_1k" Interactive

Add Column states(num_cities)

From city_1k 'derive values from other table
Set To Count(*) 'count cities in each state
Where Within 'join: where cities fall within state

The Set To clause in this example specifies an aggregate function, Count(*). Aggregate functions
are described below.

Filling an Existing Column with Values from Another Table

To update an existing column instead of adding a new column, omit the datatype parameter and
specify a From clause instead of a Values clause. When updating an existing column, MapBasic
ignores the Dynamic clause.

Filling the New Column with Aggregate Data

If you specify a From clause, you can calculate values for the new column by aggregating data from
the second table. To perform data aggregation, specify a Set To clause that includes an aggregate
function.
The following table lists the available aggregate functions.

MapBasic 15.2 Reference 51

 A to Z MapBasic Language Reference

Function Value Stored In The New Column

Avg( col ) Average of values from rows in the source table.

Count( * ) Number of rows in the source table that correspond to the

row in the table being updated.

Max( col ) Largest of the values from rows in the source table.

Min( col ) Smallest of the values from rows in the source table.

Sum( col ) Sum of the values from rows in the source table.

WtAvg( col, weight_col ) Weighted average of the values from the source table; the
averaging is weighted so that rows having a large weight_col
value have more of an impact than rows having a small
weight_col value.

Proportion Avg( col ) Average calculation that makes adjustments based on how
much of an object is within another object.

Proportion Sum( col ) Sum calculation that makes adjustments based on how
much of an object is within another object.

Proportion WtAvg( col , weight_col ) Weighted average calculation that makes adjustments based
on how much of an object is within another object.

Note: Count returns an integer value. All other functions return a float value. (No MapBasic function,
aggregate or otherwise, returns a decimal value. A decimal field is only a way of storing the
data. The arithmetic is done with floating point numbers.)

Most of the aggregate functions operate on data values only. The last three functions (Proportion
Sum, Proportion Avg, Proportion WtAvg) perform calculations that take geographic relationships
into account. This is best illustrated by example.
Suppose you have a Counties table, containing county boundary regions and demographic information
(such as population) about each county. You also have a Risk table, which contains a region object.
The object in the Risk table represents some sort of area that is at risk; perhaps the region object
represents an area in danger of flooding due to proximity to a river.

MapBasic 15.2 Reference 52

 A to Z MapBasic Language Reference

1 County Boundaries 2 Risk Buffer Region

Given these two tables, you might want to calculate the population that lives within the risk region.
If half of a county's area falls within the risk region, you will consider half of that county's population
to be at risk; if a third of a county's area falls within the risk region, you will consider a third of that
county's population to be at risk; etc.
The following example calculates the population at risk by using the Proportion Sum aggregate
function, then stores the calculation in a new column (population_at_risk):

Add Column Risk(population_at_risk Integer)

From counties
Set To Proportion Sum(county_pop)
Where Intersects

For each county that is at least partly within the risk region, MapInfo Pro adds some or all of the
counties county_pop value to a running total.
The Proportion Sum function produces results based on an assumption―the assumption that the
number being totalled is distributed evenly throughout the region. If you use Proportion Sum to
process population statistics, and half of a region falls within another region, MapInfo Pro adds half
of the region's population to the total. In reality, however, an area representing half of a region does
not necessarily contain half of the region's population. For example, the population of New York
State is not evenly distributed, because a large percentage of the population lives in New York City.
If you use Proportion Sum in cases where the data values are not evenly distributed, the results
may not be realistic. To ensure accurate results, work with smaller region objects (for example,
operate on county regions instead of state regions).

MapBasic 15.2 Reference 53

 A to Z MapBasic Language Reference

The Proportion Avg aggregate function performs an average calculation which takes into account
the percentage of an object that is covered by another object. Continuing the previous example,
suppose the County table contains a column, median_age, that indicates the median age in each
county.
The following statement calculates the median age within the risk zone:

Add Column Risk(age Float)

From Counties
Set To Proportion Avg(median_age)
Where Intersects

For each row in the County table, MapInfo Pro calculates the percentage of the risk region that is
covered by the county; that calculation produces a number between zero and one, inclusive. MapInfo
Pro multiplies that number by the county's median_age value, and adds the result to a running total.
Thus, if a county has a median_age value of 50, and if the county region covers 10% of the risk
region, MapInfo Pro adds 5 (five) to the running total, because 10% of 50 is 5.
Both Proportion Sum and Proportion Avg keep running totals. For example:
If half the county falls in the risk area, then you take half the value and add it to the running total. If
it is 10%, then you add 10% of the value to the running total. However, Proportion Avg should be
an average, so if 4 counties intersect the risk area, then you take the running total and divide by 4.
If county1 intersects the risk region, and 50% of county1 intersects the risk region, and the population
of county1 is 66, then you add 33 to the running total.
If 30% of county2's area intersects the risk area and the population is 100, then add 30 to the running
total.
If county3 has 20% overlap with the risk area and has a population of 50, then add 10 to the running
total.
If county4 has 10% overlap with the risk area and has a population of 60, then add 6 to the running
total.
Then the Proportion Sum is 33+30+10+6 = 82
Then the Proportion Avg is (33+30+10+6)/4 = 20 (or 21 depending on round off, but I think 20).
Proportion WtAvg is similar to Proportion Avg, but it also lets you specify a data column for
weighting the average calculation; the weighting is also proportionate. For example:
Weighted Average should take a weighted value from another column; for the previous example
there is another column called RuralPercent in the County table. If the risk is for flood and the rural
areas are where it floods, then for risk you only want the population from the rural area.
If county1 has 50% overlap with the risk region, a population of 66, and a RuralPercent of 0.8, then
add (0.5 * 66 * 0.8) = 26.
If county3, 4, and 5 are all 50% rural, then:
county3 0.3 * 100 * 0.5 = 15

MapBasic 15.2 Reference 54

 A to Z MapBasic Language Reference

county4 0.2 * 50 * 0.5 = 5

county5 0.1 * 60 * 0.5 = 3
Then the proportion weighted Avg is: (26 + 15 + 5 + 3)/2.3 = 21.3043

Using Proportion... Functions with Non-Region Objects

When you use Proportion functions and the source table contains region objects, MapInfo Pro
calculates percentages based on the overlap of regions. However, when the source table contains
non-region objects, MapInfo Pro treats each object as if it were completely inside or completely
outside of the destination region (depending on whether the non-region object's centroid is inside
or outside of the destination region).

Dynamic Columns
If you include the optional Dynamic keyword, the new column becomes a dynamic computed column,
meaning that subsequent changes made to the source table are automatically applied to the
destination table.
If you create a dynamic column, and then close the source table used to calculate the dynamic
column, the column values are frozen (the column is no longer updated dynamically).
Similarly, if a geographic join is used in the creation of a dynamic column, and you close either of
the maps used for the geographic join, the column values are frozen.

Add Custom Frame statement

Purpose
Adds a custom frame to a Layout window.

Syntax

Add Custom Frame [ Window window_id ]

[ Position ( x, y ) [ Units paper_units ] ]
[ Width frame_width [ Units paper_units ] ]
[ Height frame_height [ Units paper_units ] ]
[ Pen ... ] [ Brush ... ] [ Priority n ]
[ Name frame_name ]
From { File addin_mbx_file_name.mbx }
Using serialized_custom_frame_file_name.mlcf
View xps_custom_frame_file_name.xps

window_id is a Layout window's integer window identifier.

x, y specifies the position of the upper left corner of the image frame, in paper_units, in the Layout
window.

MapBasic 15.2 Reference 55

 A to Z MapBasic Language Reference

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in

(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
frame_width and frame_height specify the width and height of the frame in the Layout window.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window. When
creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of frames to
a unique set of values beginning with 1.
frame_name is a string representing the frame name.
addin_mbx_file_name.mbx is a string representing the name of the addin mbx that create the
contents of the custom frame and manage its behavior. The file name is short file name or a relative
path name if the .mbx is stored within the MapInfo Pro Tools folder.
serialized_custom_frame_file_name.mlcf is a string representing the name of the serialized custom
frame. This file is created by the add-in and can be in any format the Add-in developer choose to
use as long as this file can be used to re-create the custom frame through the mapbasic command.
This file has .mlcf as an extension.
xps_custom_frame_file_name.xps is a string representing the name of the xps file generated when
the custom frame was saved into a workspace. This file has .xps as its extension. This file is needed
in case when re-running the mapbasic command an error occurred during the loading of the add-in
MBX or/and the use of the serialized custom frame file name in ordered to deserialize the custom
frame. In such case the .xps file will be used as alternative to display the custom frame as it was
when it was saved.

Description
The Add Custom Frame statement is only for .wor persistence and .wor loading. Executing this
statement outside of loading a workspace (.wor), such as from a MapBasic window or MapBasic
tool, displays an error stating that the executed command is not supported from within the MapBasic
window or tool.
Custom frames cannot be cloned. Cloning a Layout window that has a custom frame in it causes
MapInfo Pro to clone all of the frames in the Layout window except for the custom frame.
Note: The Layout window scale bar is an example of a custom frame.

MapBasic 15.2 Reference 56

 A to Z MapBasic Language Reference

Add Designer Frame statement

TheAdd Designer Frame statement adds legend frames to an existing Legend window created
with the Create Designer Legend statement. You can issue this statement from the MapBasic
window in MapInfo Pro.

Syntax

Add Designer Frame

[ Window legend_window_id ]
[ Custom ]
Frame From Layer { map_layer_id | map_layer_name }
[ Position ( x , y ) [ Units paper_units ] ]
[ Using
[ Column { column | object [ FromMapCatalog { On | Off } ] } ]
[ Label { expression | default } ]
[ Title [ frame_title ] ]
[ SubTitle [ frame_subtitle ] ]
[ Columns number_of_columns ] |
[ Height frame_height [ Units paper_units ] ]
[ Style [ NoRefresh ]
[ Text { style_name } { Line Pen...
| Region Pen... Brush...
| Symbol Symbol... } ]
[ , ... ] ] ]

legend_window_id is an integer window identifier that you can obtain by calling the FrontWindow(
) function and WindowID( ) function.
map_layer_id or map_layer_name identifies a map layer; can be a SmallInt (e.g., use 1 to specify
the top map layer other than Cosmetic) or a string representing the name of a table displayed in the
map. For a theme layer you must specify the map_layer_id.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in
(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
win_height is a string specifying the legned frame height in paper units. For details about paper
units, see Set Paper Units statement.
frame_title is a string which defines a frame title. If a Title clause is defined here for a frame, then
it will be used instead of the def_frame_title.
frame_subtitle is a string which defines a frame subtitle. If a SubTitle clause is defined here for a
frame, then it will be used instead of the def_frame_subtitle.

MapBasic 15.2 Reference 57

 A to Z MapBasic Language Reference

column is an attribute column name from the frame layer's table, or the object column (meaning
that legend styles are based on the unique styles in the mapfile). The default is 'object'.
number_of_columns is the number of columns to show in a frame.
frame_height this is used in place of the column clause when the user resizes a legend frame. The
height of the frame in paper units. Written to the WOR when the frame has been manually resized.
style_name is a string which displays next to a symbol, line, or region in a custom frame.

Description
The default properties set in the Create Designer Legend statement are used when adding new
frames. You override these default properties when you explicitly set properties for the frames that
you are adding. Unlike the Add Cartographic Frame statement, the Add Designer Frame statement
supports a Columns clause that lets you specify how many columns to use in a legend frame.
If the Custom keyword is included, then each frame section must include a Position clause. If
Custom is omitted and the legend is laid out in portrait or landscape, then the frames will be added
to the end.
The Frame From Layer may be a (SmallInt) value, such as 1 to specify the top map layer other
than the Cosmetic layer, or a string representing the layer name in an existing map. For a theme
layer you must specify the map_layer_id.
The Position clause controls the frame's position on the Legend window. The upper left corner of
the Legend window has the position 0, 0. Position values use paper units settings, such as "in"
(inches) or "cm" (centimeters). MapBasic has a current paper units setting, which defaults to inches;
a MapBasic program can change this setting through the Set Paper Units statement.You can
override the current paper units by including the optional Units subclause within the Position clause.
The defaults in this statement apply only to the frames being created in this statement. They have
no affect on existing frames. Frame defaults used in the Create Cartographic Legend statement
have no affect on frames created in this statement.
The Column clause is an attribute column name from the frame layer's table, or the object column
(legend styles are based on the unique styles in the .map file). The default is object.
When you save to a workspace, the FromMapCatalog OFF clause is written to the workspace
when specified. This requires the workspace to bumped up to 800. If the FromMapCatalog ON
clause is specified, we do not write it to the workspace since it is default behavior. This lets us avoid
bumping up the workspace version in this case.
FromMapCatalog ON retrieves styles from the MapCatalog for a live access table. If the table is
not a live access table, MapBasic reverts to the default behavior for a non-live access table instead
of throwing an error. The default behavior for a non-access table is FromMapCatalog Off (for
example, map styles).
FromMapCatalog OFF retrieves the unique map styles for the live table from the server. This table
must be a live access table that supports per record styles for this to occur. If the live table does
not support per record styles than the behavior is to revert to the default behavior for live tables,
which is to get the default styles from the MapCatalog (FromMapCatalog ON).

MapBasic 15.2 Reference 58

 A to Z MapBasic Language Reference

Label is a valid expression or default (the default frame style pattern is used when creating each
style's text, unless the style clause contains text). The default is default.
The Title clause is a string that defines a frame title. If a Title clause is defined for a frame, then it
will be used instead of def_frame_title.
The SubTitle clause is a string that defines a frame subtitle. If a SubTitle clause is defined for a
frame, then it will be used instead of def_frame_subtitle.
The Columns clause is the number of columns to show within a frame.
paper_units is a string representing a paper unit name. For details about paper units, see Set Paper
Units statement.
The Style clause and the NoRefresh keyword allow you to create a custom frame that will not be
overwritten when the legend is refreshed. If the NoRefresh keyword is used in the Style clause,
then the table is not scanned for styles. Instead, the Style clause must contain your custom list of
definitions for the styles displayed in the frame. This is done with the Text and appropriate Line,
Region, or Symbol clause.
Take note of the following:
• When adding legend frames from MapInfo Pro, new frames are selected.
• when adding legend frames from MapBasic, new frames are not selected and the previous selection
remains unchanged.
• The LayoutInfo( ) function includes theme legends in its frame count.

Examples
You can get an count of open document windows using NumAllWindows( ) function, then loop
through them using WindowID( ) function or WindowInfo( ) function to find the legend window
by type and its window ID to use with the Add Legend Designer statement.

Dim i, wndLegend as integer

for i = 1 to NumWindows()
If WindowInfo(WindowID(i), WIN_INFO_TYPE) = WIN_LEGEND_DESIGNER then
wndLegend = WindowInfo(WindowID(i), WIN_INFO_WINDOWID)
end if
next

This example adds frames.

Add Designer Frame Window wndLegend Frame From Layer 2 Columns 2

To get the window identifier use the following where window_id is an integer window identifier for
a Layout window and frame_id is a number that specifies which frame within the Layout window
you want to query.

LayoutItemInfo(window_id, frame_id, 10)

MapBasic 15.2 Reference 59

 A to Z MapBasic Language Reference

For example, if a layout has one map frame and one or more legends, then the map frame is
frame_id 1 and the first legend is 2. The following will return window identifier for the Legend
window where 2 is a legend frame:

Dim LD_window as Integer

LD_window = LayoutItemInfo(window_id, 2, 10)

You can use the results of the above in a statement to add legends:

Add Designer Frame Window window_id Frame From Layer . . .

See Also:
Create Designer Legend statement, Set Designer Legend statement, Add Designer Frame
statement, Add Designer Text statement, Add Image Frame statement, Add Image Page
statement, Alter Designer Frame statement, Remove Designer Frame statement

Add Designer Page statement

This statement adds one page to the Layout window. You can issue this statement from the
MapBasic window in MapInfo Pro.

Syntax

Add Designer Page

[ Window layout_win ]

layout_win is the window ID of a Layout window.

Description
The Add Designer Page statement adds one page to the Layout window. The page is added at
the end of the collection of pages (at the end of the thumbnails). There is no limit to the number of
pages you can add, it only depends on available memory.
See Also:
Create Designer Legend statement, Add Designer Frame statement, Add Designer Text
statement, Add Image Frame statement, Remove Designer Page statement

Add Designer Text statement

This statement adds text frames to an existing Legend window created with the Create Designer
Legend statement. You can issue this statement from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 60

 A to Z MapBasic Language Reference

Syntax

Add Designer Text

[ Window legend_window_id ]
Legend Text Frame
Text { frame_text [ Font... ] }
[ Position ( x, y ) [ Units paper_units ] ]

legend_window_id is an integer window identifier that you can obtain by calling the FrontWindow()
function and WindowID() function.
frame_text is text for a legend title, subtitle, or descriptive text (such as copyright information for
example).
x states the desired distance from the top of the workspace to the top edge of the window.
y states the desired distance from the left of the workspace to the left edge of the window.
Note: Here workspace means the client area (which excludes the title bar, tool bar, and the status
bar).

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in

(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points

Description
Legend Text Frame creates a text frame in the Legend window.
If Text does not specify the Font clause, then the default font is used.
The Position clause controls the frame's position on the Legend window. The upper left corner of
the Legend window has the position 0, 0. Position values use paper units settings, such as "in"
(inches) or "cm" (centimeters) (see Set Paper Units statement). MapBasic has a current paper
units setting, which defaults to inches; a MapBasic program can change this setting through the Set
Paper Units statement. You can override the current paper units by including the optional Units
subclause within the Position clause.

Example

Add Designer Text Window frontwindow()

Legend Text Frame
Text "This is My title" Font("Batang", 3, 12, 16711680)

See Also:

MapBasic 15.2 Reference 61

 A to Z MapBasic Language Reference

Create Designer Legend statement, Add Designer Frame statement, Add Designer Text
statement, Add Image Frame statement, Add Image Page statement, Alter Designer Text
statement, Remove Designer Text statement

Add Image Frame statement

Purpose
Adds an image frame to a Layout window. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

Add Image Frame [ Window window_id ]

[ Position ( x, y ) [ Units paper_units ] ]
[ Width frame_width [ Units paper_units ] ]
[ Height frame_height [ Units paper_units ] ]
[ Pen .... ] [ Brush ... ] [ Priority n ] [ Name frame_name ]
From { File image_file_name }

window_id is a Layout window's integer window identifier.

x, y specifies the position of the upper left corner of the image frame, in paper_units, in the Layout
window.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in
(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
frame_width and frame_height specify the width and height of the frame in the Layout window. The
Layout window maintains the aspect ratio of the image (the ratio between the height and the width),
so when specifying both width and height values it applies only the last dimension and uses it to
calculate the other dimension.
image_file_name is a string representing the name of the image file you are adding. Supported
formats are jpg, png, bmp, gif, tif, and ico.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window. When
creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of frames to
a unique set of values beginning with 1.
frame_name is a string representing the name for this image frame in a layout designer. If a name
is assigned to a frame in the Layout window, it will be written to the WOR. When the Name clause
is written to the WOR, the workspace version is updated to version 1500.

MapBasic 15.2 Reference 62

 A to Z MapBasic Language Reference

Description
The window_id parameter specifies which window to query. To obtain a window identifier, call the
FrontWindow() function immediately after opening a window, or call the WindowID() function at
any time after the window's creation.
An optional Position clause lets you place the image frame within the Layout window. If it is omitted,
then the image is centered in the visible area of the layout.
The optional Width and Height clauses specify the size of the image frame, in paper units. If no
Width and Height clauses are provided, then the image dimensions are used. If only one value is
specified, then it is used to calculate the missing value and still maintain the aspect ration of the
image.
Brush is a valid Brush clause. Only Solid brushes are allowed. While values other than solid are
allowed as input without error, the type is always forced to solid. This clause is used only to provide
the background color for the frame.
Pen is a valid Pen clause. This clause is designed to turn on (solid) or off (hollow) and set the color
of the border of the frame.
See Also:
Add Designer Frame statement, Add Designer Text statement, Add Image Frame statement,
Add Image Page statement, FrontWindow() function, Set Paper Units statement, WindowID()
function

Add Map statement

Purpose
Adds one or more graphic layers, or a group layer, to a Map window. You can also select a destination
group layer and/or position to insert the new layers.

Syntax 1

Add Map
[ Window window_id ] [ Auto ]
Layer table [ , table [ Animate ] ... ]
[ [ DestGroupLayer group_id ] Position position ]

window_id is the window identifier of a Map window.

table is the name of a mappable open table to add to a Map window.
group_id is the identification for a group layer, either as a integer value (the group number) or as a
string value (the group name).
position is the 1-based index within the destination group where to insert the new list of layers.

MapBasic 15.2 Reference 63

 A to Z MapBasic Language Reference

Syntax 2

Add Map
[ Window window_id ] [ Auto ]
GroupLayer ( "friendly_name" [ , item ... ] )
[ [ DestGroupLayer group_id ] Position position ]

where:

item = table | [ GroupLayer ( "friendly_name" [ , item ... ])

Description
The Add Map statement adds one or more open tables, or a group layer, to a Map window, but not
both within the same statement. The group layer may contain any number of nested group layers.
MapInfo Pro then automatically redraws the Map window, unless you have suppressed redraws
through a Set Event Processing statement Off statement or Set Map statement Redraw Off
statement.
The window_id parameter is an integer window identifier representing an open Map window; you
can obtain a window identifier by calling the FrontWindow() function and WindowID() function.
If the Add Map statement does not specify a window_id value, the statement affects the topmost
Map window.
If you include the optional Auto keyword, MapInfo Pro tries to automatically position the map layer,
or group layers at an appropriate place in the set of layers. A raster table or a map of region objects
would be placed closer to the bottom of the map, while a map of point objects would be placed on
top.
If you omit the Auto keyword, the specified table becomes the topmost layer in the window; in other
words, when the map is redrawn, the new layer, or group layers will be drawn last. You can then
use the Set Map statement to alter the order of layers in the Map window.
If a DestGroupLayer is specified the Auto keyword will be ignored and the list of layers, or the group
layer will be inserted into the layer list, in the group specified, at the position specified. A group id
of 0 is the top level list. If the DestGroupLayer is omitted the group ID defaults to 0.
The position is the 1-based index within the destination group of where to insert the new list of layers.
If the position is omitted it is assumed to be the first position in the group (position = 1). If the position
given exceeds the number of items in the destination group, the new layers and/or groups will be
inserted at the end of the destination group.
Layer and group IDs may be the numeric ID or name. Group IDs range from 0 to the total number
of groups in the list.
Note: You cannot insert into the middle of a set of thematic layers. Thematic layers are inserted
in a certain order as they are created and this order is maintained. If the destination position
would cause the new layers to be inserted within a set of thematic layers, the final position
will be adjusted to avoid that.

MapBasic 15.2 Reference 64

 A to Z MapBasic Language Reference

Adding Layers of Different Projections

If the layer added is a raster table, and the map does not already contain any raster map layers,
the map adopts the coordinate system and projection of the raster image. If a Map window contains
two or more raster layers, the window dynamically changes its projection, depending on which image
occupies more of the window at the time.
If raster re-projection is turned on, then MapInfo Pro retains the coordinate system of the map even
if you add a raster table to the map.
If the layer added is not a raster table, MapInfo Pro continues to display the Map window using
whatever coordinate system and projection were used before the Add Map statement, even if the
table specified is stored with a different native projection or coordinate system. When a table's native
projection differs from the projection of the Map window, MapInfo Pro converts the table coordinates
"on the fly" so that the entire Map window appears in the same projection.
Note: When MapInfo Pro converts map layers in this fashion, map redraws take longer, since
MapInfo Pro must perform mathematical transformations while drawing the map.

Using Animation Layers to Speed Up Map Redraws

If the Add Map statement includes the Animate keyword, the added layer becomes a special layer
known as the animation layer. When an object in the animation layer is moved, the Map window
redraws very quickly, because MapInfo Pro only redraws the one animation layer.
For an example of animation layers, see the sample program ANIMATOR.MB.
The animation layer is useful in real-time applications, where map features are updated frequently.
For example, you can develop a fleet-management application that represents each vehicle as a
point object. You can receive current vehicle coordinates by using GPS (Global Positioning Satellite)
technology, and then update the point objects to show the current vehicle locations on the map. In
this type of application, where map objects are constantly changing, the map redraws much more
quickly if the objects being updated are stored in the animation layer instead of a conventional layer.
The following example opens a table (Vehicles) and makes the table an animation layer:

Open Table "vehicles" Interactive

Add Map Layer vehicles Animate

In general, the last table to be followed by the Animate keyword will be the animation layer. Only
one layer at a time can be the Animation layer.
To terminate the animation layer processing, issue a Remove Map statement Layer Animate
statement.
Animation layers have special restrictions. For example, users cannot use the Info tool to click on
objects in an animation layer. Also, each Map window can have only one animation layer. For more
information about animation layers, see the MapBasic User's Guide.

MapBasic 15.2 Reference 65

 A to Z MapBasic Language Reference

Example

Open Table "world"

Map From world
Open Table "cust1992" As customers
Open Table "lead1992" As leads
Add Map Auto Layer customers, leads

Add a group layer example:

Open Table world

Open Table worldcap
Add Map Auto GroupLayer("new group", worldcap, world)
Open Table ocean
Add Map Layer ocean DestGrouplayer "new group" position 3

See Also:
Map statement, Remove Map statement, Set Map statement

AdornmentInfo() function
Purpose
Returns information about adornments like scale bars. You can call this function from the MapBasic
window in MapInfo Pro.

Syntax

AdornmentInfo( window_id, attribute )

window_id is an integer window identifier. The window needs to be an adornment.

attribute is an integer code indicating what type of information to return. For values, see the table
below:

Return Value
Float, smallint, integer, logical, pen, brush, font, or string, depending on the attribute parameter.

Description
There are several attributes that AdornmentInfo() can return. Codes are defined in MAPBASIC.DEF.

Attribute setting ID AdornmentInfo() Return Value

ADORNMENT_INFO_TYPE 1 Integer. Type of adornment: 0 (zero) for scale bar.

MapBasic 15.2 Reference 66

 A to Z MapBasic Language Reference

Attribute setting ID AdornmentInfo() Return Value

ADORNMENT_INFO_MAP_WINDOWID 2 Integer. WindowID of the parent map window.

ADORNMENT_INFO_IS_FIXED_POS 3 Logical. True for fixed position, false for docked position.

ADORNMENT_INFO_FIXED_POS_X 4 Float. X value of the fixed position.

ADORNMENT_INFO_FIXED_POS_Y 5 Float. Y value of the fixed position.

ADORNMENT_INFO_FIXED_POS_UNITS 6 Char. Units of the X and Y offsets for the docked position.

ADORNMENT_INFO_DOCKED_POS 7 SmallInt. Returns the docked position.

ADORNMENT_INFO_DOCKED_OFFSET_X 8 Float. X value of the offset relative to the docked position.

ADORNMENT_INFO_DOCKED_OFFSET_Y 9 Float. Y value of the offset relative to the docked position.

ADORNMENT_INFO_DOCKED_UNITS 10 Char. Units of the X and Y offsets for the docked position.

ADORNMENT_INFO_BACKGROUND_PEN 11 Pen. The style of the adornment background border pen.

ADORNMENT_INFO_BACKGROUND_BRUSH 12 Brush. The style of the adornment background fill brush.

ADORNMENT_INFO_SB_TYPE 20 SmallInt. Type of scale bar.

ADORNMENT_INFO_SB_MAP_UNITS 21 Char. Units of the map distance on the scale bar.

ADORNMENT_INFO_SB_PAPER_UNITS 22 Char. Paper units in the scale bar. For details about paper units,
see Set Paper Units statement.

ADORNMENT_INFO_SB_BAR_LENGTH 23 Float. Original size of the scale bar.

ADORNMENT_INFO_SB_BAR_DRAW_LEN 24 Float. Size the scale bar is drawn at.

ADORNMENT_INFO_SB_BAR_HEIGHT 25 Float. Height of the scale bar.

ADORNMENT_INFO_SB_AUTO_SCALING 26 Logical. To mark auto scaling on or off.

ADORNMENT_INFO_SB_CARTO_SCALE 27 Logical. To display the cartographic scale in the toolbar.

MapBasic 15.2 Reference 67

 A to Z MapBasic Language Reference

Attribute setting ID AdornmentInfo() Return Value

ADORNMENT_INFO_SB_BAR_PEN 28 Pen. The pen style used to draw the scale bar.

ADORNMENT_INFO_SB_BAR_BRUSH 29 Brush. The brush, fill style used to draw the scale bar.

ADORNMENT_INFO_SB_BAR_FONT 30 Font. The font used to render text in the scale bar.

ADORNMENT_INFO_SB_DISPLAY_SCALE 31 Float. The numeric value of the scale that will be shown in the scale
bar.

ADORNMENT_INFO_SB_AUTOOFF_SCALE 32 Float. The unrounded scale value that is used if auto scaling is off.

ADORNMENT_INFO_SB_AUTOON_SCALE 33 Float. The rounded scale value that is used if auto scaling is on.

ADORNMENT_INFO_SB_SCALE_STRING 34 Char. The scale value that is being displayed but as a formatted
string (such as decimal points, thousands separators).

ADORNMENT_INFO_SB_CARTO_VALUE 35 Float. The cartographics scale value as a numeric value, without

any rounding.

ADORNMENT_INFO_SB_CARTO_STRING 36 Char. The cartographic scale as a formatted string.

Example

print AdornmentInfo(MapperInfo(FrontWindow(), 201), 1)

Alter Button statement

Purpose
Enables, disables, selects, or deselects a button from a ButtonPad (toolbar) or a ribbon group.

Syntax

Alter Button { handler | ID button_id }

[ { Enable | Disable } ]
[ { Check | Uncheck } ]

handler is the handler that is already assigned to an existing button. The handler can be the name
of a MapBasic procedure, or a standard command code (e.g., M_TOOLS_RULER or
M_WINDOW_LEGEND) from MENU.DEF.

MapBasic 15.2 Reference 68

 A to Z MapBasic Language Reference

button_id is a unique integer button identification number.

Description
If the Alter Button statement specifies a handler (e.g., a procedure name), MapInfo Pro modifies
all buttons that call that handler. If the statement specifies a button_id number, MapInfo Pro modifies
only the button that has that ID.
The Disable keyword changes the button to a grayed-out state, so that the user cannot select the
button.
The Enable keyword enables a button that was previously disabled.
The Check and Uncheck keywords select and deselect ToggleButton type buttons, such as the
Show Statistics Window button. The Check keyword has the effect of "pushing in" a ToggleButton
control, and the Uncheck keyword has the effect of releasing the button. For example, the following
statement selects the Show Statistics Window button:

Alter Button M_WINDOW_STATISTICS Check

Note: Checking or unchecking a standard MapInfo Pro button does not automatically invoke that
button's action; thus, checking the Show/Hide Statistics button does not actually show the
Statistics window-it only affects the appearance of the button. To invoke an action as if the
user had checked or unchecked the button, issue the appropriate statement; in this example,
the appropriate statement is the Open Window statement Statistics.

Similarly, you can use the Check keyword to change the appearance of a ToolButton. However,
checking a ToolButton does not actually select that tool, it only changes the appearance of the
button. To make a standard tool the active tool, issue a Run Menu Command statement, such as
the following:

Run Menu Command M_TOOLS_RULER

To make a custom tool the active tool, use the syntax Run Menu Command ID IDnum.
Things to remember when using this command with the MapInfo Pro 64-bit:
1. This command allows you to enable\disable or select\unselect a control added to ButtonPad
group.
2. If you check/uncheck using a mapinfo run menu command then controls which have an ischecked
property bind are affected.
See Also:
Alter ButtonPad statement, Create ButtonPad statement, Run Menu Command statement

MapBasic 15.2 Reference 69

 A to Z MapBasic Language Reference

Alter ButtonPad statement

Purpose
Displays / hides a ButtonPad (toolbar), or adds / removes buttons. In the 64-bit version, does the
same with ribbon groups.

Syntax

Alter ButtonPad { current_title | ID pad_num }

[ Add button_definition [ button_definition ... ] ]
[ Remove { handler_num | ID button_id } [ , ... ] ]
[ Title new_title ]
[ Width width ]
[ Position ( x, y ) [ Units unit_name ] ]
[ ToolbarPosition ( row, column ) ]
[ { Show | Hide } ]
[ { Fixed | Float | Top | Left | Right | Bottom } ]
[ Destroy ]

current_title is the toolbar's title string (e.g., "Main").

pad_num is the ID number for a standard toolbar:
• 1 for Main
• 2 for Drawing
• 3 for Tools
• 4 for Standard
• 5 for Database Management System (DBMS)
• 6 Web Services
• 7 Reserved
handler_num is an integer handler code, such as M_TOOLS_RULER (1710), from MENU.DEF.
button_id is a custom button's unique identification number.
new_title is a string that becomes the toolbar's new title; visible when toolbar is floating. In MapInfo
Pro 64-bit, this is the caption of the ribbon group.
width is the pad width, in terms of the number of buttons across. Not suppported in the 64-bit version
of MapInfo Pro.
x, y specify the toolbar's position when floating; specified in paper units. For details about paper
units, see Set Paper Units statement. Not suppported in the 64-bit version of MapInfo Pro.
unit_name is a string paper unit name (e.g., "in" for inches, "cm" for centimeters). Not suppported
in the 64-bit version of MapInfo Pro.

MapBasic 15.2 Reference 70

 A to Z MapBasic Language Reference

row, column specify the toolbar's position when docked (e.g., 0, 0 places the pad at the left edge of
the top row of toolbars, and 0, 1 represents the second toolbar on the top row). Not suppported in
the 64-bit version of MapInfo Pro.
• row position starts at the top and increases in value going to the bottom. It is a relative value to
the rows existing in the same position (top or bottom). When there is a menu bar in the same
position, then the numbers become relative to the menu bar. When a toolbar is just below the
menu bar, its row value is 0. If it is directly above the menu bar, then its row value is -1.
• column position starts at the left and increases in value going to the right. It is a relative value to
the columns existing in the same position (left or right). For example, if a toolbar is docked to the
left and the menu bar is docked to the left position, then the column number for the column left of
the menu bar is -1. The column number for the column to the right of the menu bar is 0.
Each button_definition clause can consist of the keyword Separator, or it can have the following
syntax:

{ PushButton | ToggleButton | ToolButton }

Calling { procedure | menu_code | OLE methodname | DDE server, topic
}
[ ID button_id ]
[ Icon icon_code [ File file_spec ] ]
[ Cursor cursor_code [ File file_spec ] ]
[ DrawMode dm_code ]
[ HelpMsg msg ]
[ ModifierKeys { On | Off } ]
[ { Enable | Disable } ]
[ { Check | Uncheck } ]

procedure is the handler procedure to call when a button is used.

menu_code is a standard MapInfo Pro menu code from MENU.DEF, such as M_FILE_OPEN (102);
MapInfo Pro runs the menu command when the user uses the button.
methodname is a string specifying an OLE method name. For details on the Calling OLE clause
syntax, see Create ButtonPad statement.
server and topic are strings specifying a DDE server and topic name. For details on the Calling
DDE clause syntax, see Create ButtonPad statement.
button_id specifies the unique button number. This number can be used: as a tag in help; as a
parameter to allow the handler to determine which button is in use (in situations where different
buttons call the same handler); or as a parameter to be used with the Alter Button statement.
Icon icon_code specifies the icon to appear on the button; icon_code can be one of the standard
MapInfo icon codes listed in ICONS.DEF, such as MI_ICON_RULER (11). If the File sub-clause
specifies the name of a file containing icon resources, icon_code is an integer resource ID identifying
a resource in the file. The size of the button can be defined with resource file id of icon_code for
small and icon_code+1 for large sized buttons, with resource file ids of icon_code and icon_code+1
respectively.

MapBasic 15.2 Reference 71

 A to Z MapBasic Language Reference

Cursor cursor_code specifies the shape the mouse cursor should adopt whenever the user chooses
a ToolButton tool; cursor_code is a code, such as MI_CURSOR_ARROW (0), from ICONS.DEF.
This clause applies only to ToolButtons. If the File sub-clause specifies the name of a file containing
icon resources, cursor_code is an integer resource ID identifying a resource in the file.
The 64-bit version of MapInfo Pro supports cursors in three ways:
1. As a string from Icons.def: SetRbnToolBtnCtrlCursor(MyToolButton, "138")
2. As a string with keyword FILE and name of DLL with custom cursors:
SetRbnToolBtnCtrlCursor(MyToolButton, "136 FILE gcsres32.dll")
3. As an integer id such as a MapInfo Cursor define from Icons.def:
SetRbnToolBtnCtrlCursorId(MyToolButton, MI_CURSOR_FINGER_LEFT)
dm_code specifies whether the user can click and drag, or only click with the tool; dm_code is a
code, such as DM_CUSTOM_LINE (33), from ICONS.DEF. Applies only to ToolButtons.
msg is a string that specifies the button's status bar help and, optionally, ToolTip help. The first part
of msg is the status bar help message. If the msg string includes the letters \n then the text following
the \n is used as the button's ToolTip help.
The ModifierKeys clause applies only to ToolButtons; it controls whether the Shift and control
(Ctrl) keys affect "rubber-band" drawing if the user drags the mouse while using a ToolButton.
Default is Off (modifier keys have no effect).

Description
Use the Alter ButtonPad statement to show, hide, modify, or destroy an existing ButtonPad. For
an introduction to ButtonPads, see the MapBasic User Guide.
To show or hide a ButtonPad, include the Show or Hide keyword; see example below.
To set whether the pad is fixed to the top of the screen ("docked") or floating like a window, include
the Fixed or the Float keyword. The user can also control whether the pad is docked or not by
dragging the pad to or from the top of the screen. For more control over the location on the screen
that the pad is docked to, use the Top (which is the same as using Fixed), Left, Right, or Bottom
keywords.
When a pad is floating, its position is controlled by the Position clause; when a pad is docked, its
position is controlled by the ToolbarPosition clause.
To destroy a ButtonPad, include the Destroy keyword. Once a ButtonPad is destroyed, it no longer
appears in the Toolbars dialog box.
The Alter ButtonPad statement can add buttons to existing ButtonPads, such as Main and Drawing.
There are three types of button controls you can add: PushButton controls (which the user can click
and release-for example, to display a dialog box); ToggleButton controls (which the user can select
by clicking, then deselect by clicking again); and ToolButton controls (which the user can select,
and then use for clicking on a Map window or layout).
If you include the optional Disable keyword when adding a button, the button is disabled (grayed
out) when it appears. Subsequent Alter Button statements can enable the button. However, if the

MapBasic 15.2 Reference 72

 A to Z MapBasic Language Reference

button's handler is a standard MapInfo Pro command, MapInfo Pro automatically enables or disables
the button depending on whether the command is currently enabled.
If you include the optional Check keyword when adding a ToggleButton or a ToolButton, the button
is automatically selected ("checked") when it first appears.
If the user clicks while using a custom ToolButton tool, MapInfo Pro automatically calls the tool's
handler, unless the user cancels (e.g., by pressing the Esc key while dragging the mouse). A handler
procedure can call CommandInfo() to determine where the user clicked. If two or more tools call
the same handler procedure, the procedure can call CommandInfo() to determine the ID of the
button currently in use.

Custom Icons and Cursors

The Icon clause specifies the icon that appears on the button. If you omit the File clause, then the
parameter n must refer to one of the icon codes listed in ICONS.DEF, such as MI_ICON_RULER
(11).
Note: MapInfo Pro has many built-in icons that are not part of the normal user interface. To see a
demonstration of these icons, run the sample program ICONDEMO.MBX. This sample program
displays icons, and also lets you copy any icon's define code to the clipboard (so that you
can then paste the code into your program).

The File file_spec sub-clause refers to a DLL file that contains bitmap resources; the n parameter
refers to the ID of a bitmap resource. For more information on creating Windows icons, see the
MapBasic User Guide.
A ToolButton definition also can include a Cursor clause, which controls the appearance of the
mouse cursor while the user is using the custom tool. Available cursor codes are listed in ICONS.DEF,
such as MI_CURSOR_CROSSHAIR (138) or MI_CURSOR_ARROW (0). The procedure for specifying
a custom cursor is similar to the procedure for specifying a custom icon.
For custom icon size requirements for different MapInfo Pro versions, see Create ButtonPad
statement About Icon Size.

Custom Drawing Modes

A ToolButton definition can include a DrawMode clause, which controls whether the user can drag
with the tool (e.g., to draw a line) or only click (e.g., to draw a point). The following table lists the
available drawing modes. Codes in the left column are defined in ICONS.DEF.

DrawMode parameter ID Description

DM_CUSTOM_POINT 34 The user cannot drag while using the custom tool.

DM_CUSTOM_LINE 33 As the user drags, a line connects the cursor with the location where
the user clicked.

MapBasic 15.2 Reference 73

 A to Z MapBasic Language Reference

DrawMode parameter ID Description

DM_CUSTOM_RECT 32 As the user drags, a rectangular marquee appears.

DM_CUSTOM_CIRCLE 30 As the user drags, a circular marquee appears.

DM_CUSTOM_ELLIPSE 31 As the user drags, an elliptical marquee appears; if you include the
ModifierKeys clause, the user can force the marquee to a circular
shape by holding down the Shift key.

DM_CUSTOM_POLYGON 35 The user may draw a polygon. To retrieve the object drawn by the
user, use the function call: CommandInfo() function
(CMD_INFO_CUSTOM_OBJ).

DM_CUSTOM_POLYLINE 36 The user may draw a polyline. To retrieve the object drawn by the
user, use the function call: CommandInfo() function
(CMD_INFO_CUSTOM_OBJ).

All of the draw modes except for DM_CUSTOM_POINT (34) support the Autoscroll feature, which
allows the user to scroll a Map or layout by clicking and dragging to the edge of the window. To
disable autoscroll, see Set Window statement.
Note: MapBasic supports an additional draw mode that is not available to MapInfo Pro users. If a
custom ToolButton has the following Calling clause Calling M_TOOLS_SEARCH_POLYGON
(1733) then the tool allows the user to draw a polygon. When the user double-clicks to close
the polygon, MapInfo Pro selects all objects (from selectable map layers) within the polygon.
The polygon is not saved.

Examples
The following example shows the Main ButtonPad and hides the Drawing ButtonPad:

Alter ButtonPad "Main" Show

Alter ButtonPad "Drawing" Hide

The next example docks the Main ButtonPad and sets its docked position to 0,0 (upper left):

Alter ButtonPad "Main" Fixed ToolbarPosition(0,0)

The next example moves the Main ButtonPad so that it is floating instead of docked, and sets its
floating position to half an inch inside the upper-left corner of the screen.

Alter ButtonPad "Main" Float Position(0.5,0.5) Units "in"

MapBasic 15.2 Reference 74

 A to Z MapBasic Language Reference

The sample program, ScaleBar, contains the following Alter ButtonPad statement, which adds a
custom ToolButton to the Tools ButtonPad. (Note that "ID 3" identifies the Tools ButtonPad.)

Alter ButtonPad ID 3
Add
Separator
ToolButton
Icon MI_ICON_CROSSHAIR
HelpMsg "Draw a distance scale on a map\nScale Bar"
Cursor MI_CURSOR_CROSSHAIR
DrawMode DM_CUSTOM_POINT
Calling custom_tool_routine
Show

Note: The Separator keyword inserts space between the last button on the Tools ButtonPad and
the new MI_CURSOR_CROSSHAIR (138) button.

See Also:
Alter Button statement, ButtonPadInfo() function, Create ButtonPad statement, Set Window
statement

Alter Cartographic Frame statement

Purpose
The Alter Cartographic Frame statement changes a frame(s) position, title, subtitle, border and
style of an existing cartographic legend created with the Create Cartographic Legend statement.
(To change the size, position or title of the legend window, use the Set Window statement.) You
can issue this statement from the MapBasic window in MapInfo Pro.
This statement cannot alter the Title, Subtitle, or Fonts for a thematic frame in the Legend window.
To make these changes, use the Set Legend statement.

Syntax

Alter Cartographic Frame

[ Window legend_window_id ]
Id { frame_id }
[ Position ( x, y ) [ Units paper_units ] ]
[ Title [ frame_title ] [ Font... ] ]
[ SubTitle [ frame_subtitle ] [ Font... ] ]
[ Border Pen... ]
[ Style [ Font... ]
[ ID { id } Text { style_name } ]
[Line Pen... | Region Pen... Brush... | Symbol Symbol... ] ]
[ , ... ]

MapBasic 15.2 Reference 75

 A to Z MapBasic Language Reference

legend_window_id is an integer window identifier that you can obtain by calling the FrontWindow()
function and WindowID() function.
frame_id is the ID of the frame on the legend. You cannot use a layer name. For example, three
frames on a legend would have the successive ID's 1, 2, and 3.
x, y specifies the position of the upper left corner of the legend frame, in paper_units, in the Layout
window.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in
(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
frame_title is a string which defines a frame title.
frame_subtitle is a string which defines a frame subtitle.
id is the position within the style list for that frame. To get information about the number of styles in
a frame, use the LegendFrameInfo() function with attribute FRAME_NUM_STYLES (13).
style_name is a string that displays next to each symbol for the frame specified in ID. The "#"
character will be replaced with the layer name. The "%" character will be replaced by the text "Line",
"Point, "Region", as appropriate for the symbol. For example, "% of #" will expand to "Region of
States" for the frame corresponding to the STATES.TAB layer.

Description
If a Window clause is not specified MapInfo Pro will use the topmost legend window.
The Position clause controls the frame's position on the legend window. The upper left corner of
the legend window has the position 0, 0. Position values use paper units settings, such as "in"
(inches) or "cm" (centimeters) (see Set Paper Units statement). MapBasic has a current paper
units setting, which defaults to inches; a MapBasic program can change this setting through the Set
Paper Units statement. An Alter Cartographic Frame statement can override the current paper
units by including the optional Units subclause within the Position clause.
The Title and SubTitle clauses accept new text, new font or both.
The Style clause must contain a list of definitions for the styles displayed in frame. You can only
update the Style type for a custom style. You can update the Text of any style. There is no way to
add or remove styles from any type of frame.
See Also:
Create Cartographic Legend statement, Set Cartographic Legend statement, Add Cartographic
Frame statement, Remove Cartographic Frame statement

MapBasic 15.2 Reference 76

 A to Z MapBasic Language Reference

Alter Control statement

Purpose
Changes the status of a control in the active custom dialog box.

Syntax

Alter Control id_num

[ Title { title | From Variable array_name } ]
[ Value value ]
[ { Enable | Disable } ]
[ { Show | Hide } ]
[ Active ]

id_num is an integer identifying one of the controls in the active dialog box.
title is a string representing the new title to assign to the control.
array_name is the name of an array variable; used to reset the contents of ListBox, MultiListBox,
and PopupMenu controls.
value is the new value to associate with the specified control.

Restrictions
You cannot issue this statement through the MapBasic window.

Description
The Alter Control statement modifies one or more attributes of a control in the active dialog box;
accordingly, the Alter Control statement should only be issued while a dialog box is active (for
example, from within a handler procedure that is called by one of the dialog box controls). If there
are two or more nested dialog boxes on the screen, the Alter Control statement only affects controls
within the topmost dialog box.
The id_num specifies which dialog box control should be modified; this corresponds to the id_num
parameter specified within the ID clause of the Dialog statement.
Each of the optional clauses (Title, Value, Enable/Disable, Hide/Show, Active) modifies a different
attribute of a dialog box control. Note that all of these clauses can be included in a single statement;
thus, a single Alter Control statement could change the name, the value, and the enabled/disabled
status of a dialog box control.
Some attributes do not apply to all types of controls. For example, a Button control may be enabled
or disabled, but has no value attribute.
The Title clause resets the text that appears on most controls (except for Picker controls and EditText
controls; to reset the contents of an EditText control, set its Value). If the control is a ListBox,
MultiListBox, or PopupMenu control, the Title clause can read the control's new contents from an
array of string variables, by specifying a From Variable clause.

MapBasic 15.2 Reference 77

 A to Z MapBasic Language Reference

The Active keyword applies only to EditText controls. An Alter Control...Active statement puts the
keyboard focus on the specified EditText control.
Use the Hide and Show keywords to make controls disappear or reappear.
To de-select all items in a MultiListBox control, use a value setting of zero. To add a list item to the
set of selected MultiListBox items, issue an Alter Control statement with a positive integer value
corresponding to the number of the list item.
Note: In this case, do not issue the Alter Control statement from within the MultiListBox control's
handler.

You can use an Alter Control statement to modify the text that appears in a StaticText control.
However, MapInfo Pro cannot increase the size of the StaticText control after it is created. Therefore,
if you plan to alter the length of a StaticText control, you may want to pad it with spaces when you
first define it. For example, your Dialog statement could include the following clause:

Control StaticText ID 1 Title "Message goes here" + Space$(30)

Example
The following example creates a dialog box containing two check boxes, an OK button, and a Cancel
button. Initially, the OK button is disabled (grayed out). The OK button is only enabled if the user
selects one or both of the check boxes.

Include "mapbasic.def"
Declare Sub Main
Declare Sub checker
Sub Main
Dim browse_it, map_it As Logical
Dialog
Title "Display a file"
Control CheckBox
Title "Display in a Browse window"
Value 0
Calling checker
ID 1
Into browse_it
Control CheckBox
Title "Display in a Map window"
Value 0
Calling checker
ID 2
Into map_it
Control CancelButton
Control OKButton
ID 3
Disable
If CommandInfo(CMD_INFO_DLG_OK) Then
' ... then the user clicked OK...
End If

MapBasic 15.2 Reference 78

 A to Z MapBasic Language Reference

End Sub
Sub checker
' If either check box is checked,
' enable the OK button; otherwise, Disable it.
If ReadControlValue(1) Or ReadControlValue(2) Then
Alter Control 3 Enable
Else
Alter Control 3 Disable
End If
End Sub

Alter Designer Frame statement

Purpose
The Alter Designer Frame statement changes a Map frame's position, title, subtitle, and style for
an existing legend created with the Create Designer Legend statement. (To change the size,
position or title of the Legend window, use the Set Window statement.) This statement does not
work with Thematic Map frames.You can issue this statement from the MapBasic window in MapInfo
Pro.
Now you can also alter position, title, subtitle, and style of frames from a Layout window using this
statement.
This statement cannot alter the Title, Subtitle, or Fonts for a thematic frame in the Legend window.
To make these changes, use the Set Legend statement.

Syntax

Alter Designer Frame

[ Window legend_or_layout_window_id ]
Id { frame_id }
[ Position ( x, y ) [ Units paper_units ] ]
[ Title [ frame_title ] [ Font... ] ]
[ SubTitle [ frame_subtitle ] [ Font... ] ]
[ Columns number_of_columns ] |
[ Height frame_height [ Units paper_units ] ]
[ Width frame_width [ Units paper_units ] ]
[ Name frame_name ]
[ Region [ Height region_height [ Units paper_units ] ] ]
[ Region [ Width region_width [ Units paper_units ] ] ]
[ Line [ Width line_width [ Units paper_units ] ] ]
[ Auto Font Size { On | Off } ]
[ Order { Default | Ascending | Descending |
{ Custom id | id : id [ , id | id : id ... ] ... } } ]
[ Style [ Font... ]
[ ID { id } Text { style_name } ]
[Line Pen... | Region Pen... Brush... | Symbol Symbol... ] ]

MapBasic 15.2 Reference 79

 A to Z MapBasic Language Reference

[ , ... ]
[ Angle frame_angle ]

legend_or_layout_window_id is an integer window identifier for the Legend or Layout window that
you can obtain by calling the FrontWindow() function and WindowID() function.
frame_id is the ID of the frame. You cannot use a layer name. For example, three frames would
have the successive ID's 1, 2, and 3.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in
(inches), pt (points), and pica. For details about paper units, see Set Paper Units statement.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
frame_title is a string which defines a frame title.
frame_subtitle is a string which defines a frame subtitle.
number_of_columns is the number of columns to show in a frame.
frame_height this is used in place of the column clause when the user resizes a legend or layout
frame. The height of the frame in paper units. Written to the WOR when the frame has been manually
resized.
frame_width is width of the frame in paper units. Written to the WOR when the frame has been
manually resized. The width cannot be specified for a Legend frame.
frame_name is a string representing the name for a frame in a Layout window. The frame_name
cannot be specified for a Legend frame. If a name is assigned to a frame in the Layout window, it
is written to the workspace (WOR file) and the workspace version is updated to 1500.
region_height is a value representing the new height of a swatch in the map frame of the Lengend
or Layout window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2 inches,
0.282222 to 5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the default value
of 32 points is used (which can be set as a preference).
region_width is a value representing the new width of a swatch in the map frame of the Legend or
Layout window window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2
inches, 0.282222 to 5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the
default value of 32 points is used (which can be set as a preference).
line_width is a value representing the new width of a line segment in the map frame of a Legend
or Layout window. You can specify 12 to 144 points, 1 to 12 picas, 0.666667 to 2 inches, 4.23333
to 50.8 millimeters, or 4.23333 to 50.8 centimeters. If not specified, then the default value of 36
points is used (which can be set as a preference).
id is the position within the style list for that frame. To get information about the number of styles in
a frame, use the LegendFrameInfo() function with attribute FRAME_NUM_STYLES (13).

MapBasic 15.2 Reference 80

 A to Z MapBasic Language Reference

style_name is a string that displays next to each symbol for the frame specified in ID. The "#"
character will be replaced with the layer name. The "%" character will be replaced by the text "Line",
"Point, "Region", as appropriate for the symbol. For example, "% of #" will expand to "Region of
States" for the frame corresponding to the STATES.TAB layer.
frame_angle is a float value indicating the angle of rotation for a text frame only (in degrees).

Description
If you omit the Window clause, the statement operates on the frontmost window, or the frontmost
Legend or Layout window as the case may be.
The Position clause controls the frame's position on the Legend or Layout window. The upper left
corner of the window has the position 0, 0. Position values use paper units settings, such as "in"
(inches) or "cm" (centimeters). MapBasic has a current paper units setting, which defaults to inches;
a MapBasic program can change this setting through the Set Paper Units statement. An Alter
Designer Frame statement can override the current paper units by including the optional Units
subclause within the Position clause.
The Title and SubTitle clauses accept new text, new font clause or both.
The Columns clause is the number of columns to show within a frame.
All frame types have a minimum and maximum Height and Width. If you set an out of range
frame_width or frame_height, an error message appears showing the allowed range.
• In case of an image frame, the aspect ratio is always maintained. For example, for an image having
aspect ratio 0.5

Alter Designer Frame FrontWindow() ID 1 Width 100 'Height will be set

to 50

Alter Designer Frame FrontWIndow() ID 1 Height 100 'Width will be set

to 200

If both Width and Height are specified within the same statement, the last clause takes precedence.
In the following case, the height will be set to 100 and width to 200 to preserve the aspect ratio.

Alter Designer Frame FrontWindow() ID 1 Width 50 Height 100

• In case of a frame containing a line shape, if Width is set to zero then the line will be vertical. Set
Height to zero for a horizontal line. If both the width and height are set to zero, an error message
appears.
The Region Height clause specifies a specific height for a swatch in the legend frame of the Legend
window.
The Region Width clause specifies a specific width for a swatch in the legend frame of the Legend
window.

MapBasic 15.2 Reference 81

 A to Z MapBasic Language Reference

The Line Width clause specifies a specific width for a line sample in the legend frame of the Legend
window.
Auto Font Size enables or disables resizing the legend swatch based on the font size setting.
The Order clause adds the ability to sort or customize the order of rows in map legends. You can
sort map legends by style label or by defining your own order. The sort order options are Default,
Ascending, Descending, or Custom. The Order clause is only written to a workspace if the map
legend is sorted ascending, descending, or custom.
A Default sort order is the order the Create Legend wizard creates the legend rows. If you create
a legend based on unique styles, this will be the order of those styles, which then display as rows
in the map legend.
If specifying Custom sort order, the id values are row ids starting with 1, moving from top to bottom.
When looking at the list of rows in the Legend Frame Properties dialog box, the first row in the list
has id equal to 1 and so on down the list. For more details, see Custom Order Options for more
details.
The Display clause controls the display of each row. Each row in MapBasic starts with the Style
clause. At the end of each Style clause is the optional Display clause. Display On makes the row
visible. Display Off makes the row invisible. If the Display clause is absent, then the row displays.
The Display clause is only written to a workspace file for styles that are not visible in a frame.
Note: The Columns or Height clauses apply to map and thematic legends. However, all other
thematic legend properties must be specified using the Set Legend statement.

The paper Units are cm (centimeters), mm (millimeters), in (inches), pt (points), and pica. Conversions
between these units are:
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
The Style clause must contain a list of definitions for the styles displayed in frame. You can only
update the Style type for a legend frame created with the NoRefresh keyword. You can update the
Text of any style. There is no way to add or remove styles from any type of frame.
Only the following clauses will be applied to thematic legends. Those are:

[ Position ( x, y ) [ Units paper_units ] ]

[ Columns number_of_columns ] |
[ Height frame_height [ Units paper_units ] ]

MapBasic 15.2 Reference 82

 A to Z MapBasic Language Reference

Example
The following example alters Frame 1 style sample 1 from a Cities points layer. It updates the title,
subtitle, and text shown next to its symbols.

Alter Designer Frame

Window FrontWindow()
ID 1
Position (1, .5) Units "in"
Title "Big Cities"
Subtitle "125 Biggest Cities"
Style Font ("Arial",2,12,255)
ID 1 Text "City Points"

See Also:
Add Designer Frame statement, Create Designer Legend statement, Remove Designer Frame
statement, Set Designer Legend statement

Custom Order Options

Both the Create Designer Legend statement and the Alter Designer Frame statement include
an Order clause with the option of specifying a Custom sort order.

Custom id | id : id [ , id | id : id ... ]

Where the following specifies a range of row ids in increasing order (Id2 > Id1):

Id1 : Id2

Reordering a List
The syntax for custom order of legend rows is similar to the Order clause (to reorder layers) in the
Set Map statement. It is fairly easy to use when you want to reorder near the beginning of a list,
but not so easy when you want to reorder near the end. For instance, if you want to reverse the
order of the first three rows you only have to use:

Order Custom 3, 2, 1

You can leave out the rest of the rows. If you have 10 rows and want to switch the last two, you
have to list all the ids like this:

Order Custom 1, 2, 3, 4, 5, 6, 7, 8, 10, 9

To make this more compact, use the following syntax:

Order Custom 1:8, 10, 9

MapBasic 15.2 Reference 83

 A to Z MapBasic Language Reference

Indicating a Range of Values

Use a colon ( : ) to indicate a range of values, such as:

Long form:
Order Custom 2, 5, 6, 7, 8, 9, 10, 1, 3, 4

Short form:
Order Custom 2, 5:10, 1, 3, 4
Order Custom 2, 5:10, 1, 3:4 (same as above but also valid)
Order Custom 2, 5:10, 1 (same as above but also valid)

Long form:
Order Custom 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 18,
19, 20, 11

Short form:
Order Custom 1:10, 12:20, 11

The list of values cannot have duplicates that will cause an error. The following causes an error:

Order Custom 1:5, 8, 4:7

This is because row ids 4 and 5 are duplicates. To see this, expand the syntax as follows (which
causes an error):

Order Custom 1, 2, 3, 4, 5, 8, 4, 5, 6, 7

The alternate syntax can be used when creating or altering a legend in the Legend window. For
workspaces, the short syntax is used when legends in the Legend window have more than 50 rows
with a custom order.

Alter Designer Text statement

TheAlter Designer Text statement changes the text string, font style, or text frame position in a
Legend window or a Layout window. You can issue this statement from the MapBasic window in
MapInfo Pro.

Syntax

Alter Designer Text

[ Window legend_or_layout_window_id ]
[ ID textframe_id [ Text { frame_text [ Font... ] }
[ Position ( x, y ) [ Units paper_units ] ] ] ]

legend_or_layout_window_id is an integer window identifier for the Legend window or Layout

window that you can obtain by calling the FrontWindow() function and WindowID() function.
textframe_id is the unique identifier for a text frame (not a legend frame) in the Legend window.

MapBasic 15.2 Reference 84

 A to Z MapBasic Language Reference

frame_text is text for a legend title, subtitle, or descriptive text (such as copyright information for
example).
x states the desired distance from the top of the workspace to the top edge of the window.
y states the desired distance from the left of the workspace to the left edge of the window.
Note: Here workspace means the client area (which excludes the title bar, tool bar, and the status
bar).

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in

(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points

Description
If Text does not specify the Font clause, then the default font is used.
The Position clause controls the frame's position on the Legend window or the Layout window.
The upper left corner of the window has the position 0, 0. Position values use paper units settings,
such as "in" (inches) or "cm" (centimeters) (see Set Paper Units statement). MapBasic has a
current paper units setting, which defaults to inches; a MapBasic program can change this setting
through the Set Paper Units statement. You can override the current paper units by including the
optional Units subclause within the Position clause.
If you omit the Window clause, the statement operates on the frontmost open window, or the
frontmost Legend window, or the frontmost Layout window.

Example

Alter Designer Text Window frontwindow()

ID 1
Text "Title Changed" Font("Arial Greek", 0, 14, 14680064)

See Also:
Create Designer Legend statement, Add Designer Text statement, Remove Designer Text
statement

Alter MapInfoDialog statement

Purpose
Disables, hides, or assigns new values to controls in MapInfo Pro's standard dialog boxes.

MapBasic 15.2 Reference 85

 A to Z MapBasic Language Reference

Restrictions
Caution: The Alter MapInfoDialog statement may not be supported in future versions of MapInfo
Pro. As a result, MapBasic programs that use this statement may not work correctly when
run using future versions of MapInfo Pro. Use this statement with caution.

Syntax 1 (assigning non-default settings)

Alter MapInfoDialog dialog_ID

Control control_ID
{ Disable | Hide | Value new_value } [ , { Disable... } ]
[ Control... ]

Syntax 2 (restoring default settings)

Alter MapInfoDialog dialog_ID Default

dialog_ID is an integer ID number, indicating which MapInfo Pro dialog box to alter.
control_ID is an integer ID number, 1 or larger, indicating which control to modify.
new_value is a new value assigned to the dialog box control.

Description
Use this statement if you need to disable, hide, or assign new values to controls―buttons, check
boxes, etc.―in MapInfo Pro's standard dialog boxes.
Note: Use this statement to modify only MapInfo Pro's standard dialog boxes. To modify custom
dialog boxes that you create using the Dialog statement, use the Alter Control statement.

Determining ID Numbers
To determine a dialog box's ID number, run MapInfo Pro with this command line:
mapinfopro.exe -helpdiag
After you run MapInfo Pro with the -helpdiag argument, display a MapInfo Pro dialog box and click
the Help button. Ordinarily, the Help button launches Help, but because you used the -helpdiag
argument, MapInfo Pro displays the ID number of the current dialog box.
Note: There are different "common dialog boxes" (such as the Open and Save dialog boxes) for
different versions of Windows. If you want to modify a common dialog box, and if your
application will be used under different versions of Windows, you may need to issue two
Alter MapInfoDialog statements, ne for each version of the common dialog box.

Each individual control has an ID number. For example, most OK buttons have an ID number of 1,
and most Cancel buttons have an ID number of 2. To determine the ID number for a specific control,
you must use a third-party developer's utility, such as the Spy++ utility that Microsoft provides with
its C compiler. The MapBasic software does not provide a Spy++ utility.

MapBasic 15.2 Reference 86

 A to Z MapBasic Language Reference

Although the Alter MapInfoDialog statement changes the initial appearance of a dialog box, the
changes do not have any effect unless the user clicks OK. For example, you can use Alter
MapInfoDialog to store an address in the Find dialog box; however, MapInfo Pro will not perform
the Find operation unless you display the dialog box and the user clicks OK.

Types of Changes Allowed

Use the Disable keyword to disable (gray out) the control.
Use the Hide keyword to make the control disappear.
Use the Value clause to change the setting of the control.
When you alter common dialog boxes (e.g., the Open dialog box), you may reset the item selected
in a combo box control, or you may assign new text to static text, button, and edit box controls.
You can change the orientation control in the Page Setup dialog box. The Portrait and Landscape
buttons are 1056 and 1057, respectively.
When you alter other MapInfo Pro dialog boxes, the following list summarizes the types of changes
you may make.
• Button, static text, edit box, editable combo box: You may assign new text by using a text
string in the new_value parameter.
• List box, combo box: You may set which item is selected by using a numeric new_value.
• Checkbox: You may set the checkbox (specify a value of 1) or clear it (value of zero).
• Radio button: Setting a button's value to 1 selects that button from the radio group.
• Symbol style button: You may assign a new symbol style (e.g., use the return value from the
MakeSymbol() function).
• Pen style button: You may assign a new Pen value.
• Brush style button: You may assign a new Brush value.
• Font style button: You may assign a new Font value.
• Combined Pen/Brush style button: Specify a Pen value to reset the Pen style, or specify a Brush
value to reset the Brush style. (For an example of this type of control, see MapInfo Pro's Region
Style dialog box, which appears when you double-click an editable region.)

Example
The following example alters MapInfo Pro's Find dialog box by storing a text string ("23 Main St.")
in the first edit box and hiding the Respecify button.

If SystemInfo(SYS_INFO_MIVERSION) = 400 Then

Alter MapInfoDialog 2202
Control 5 Value "23 Main St."
Control 12 Hide
End If
Run Menu Command M_ANALYZE_FIND

The ID number 2202 refers to the Find dialog box. Control 5 is the edit box where the user types
an address. Control 12 is the Respecify button, which this example hides. All ID numbers are subject

MapBasic 15.2 Reference 87

 A to Z MapBasic Language Reference

to change in future versions of MapInfo Pro; therefore, this example calls the SystemInfo() function
to determine the MapInfo Pro version number.
See Also:
Alter Control statement, SystemInfo() function

Alter Menu statement

Purpose
Adds or removes items from an existing menu.

Syntax 1

Alter Menu { menuname | ID menu_id }

Add menudef [ , menudef... ]

Where each menudef defines a menu item, according to the syntax:

newmenuitem
[ ID menu_item_id ]
[ HelpMsg help ]
[ { Calling handler | As menuname } ]

menuname is the name of an existing menu (for example, "File").

menu_id is a standard integer menu ID from 1 to 64; 1 represents the File menu.
newmenuitem is a string, the name of an item to add to the specified menu.
menu_item_id is a custom integer menu item identifier, which can be used in subsequent Alter
Menu Item statements.
help is a string that will appear on the status bar while the menu item is highlighted.
handler is the name of a procedure, or a code for a standard menu command (e.g., M_FILE_NEW),
or a special syntax for handling the menu event by calling OLE or DDE. If you specify a command
code for a standard MapInfo Pro Show/Hide command (such as M_WINDOW_STATISTICS), the
newmenuitem string must start with an exclamation point and include a caret (^), to preserve the
item's Show/Hide behavior. For more details on the different types of handler syntax, see the Create
Menu statement.

Syntax 2

Alter Menu { menuname | ID menu_id }

Remove { handler | submenuname | ID menu_item_id }
[ , { handler | submenuname | ID menu_item_id } ... ]

menuname is the name of an existing menu.

MapBasic 15.2 Reference 88

 A to Z MapBasic Language Reference

menu_id is an integer menu ID from 1 to 64; 1 represents the File menu.

handler is either the name of a sub procedure or the code for a standard MapInfo Pro command.
submenuname is the name of a hierarchical submenu to remove from the specified menu.
menu_item_id is a custom integer menu item identifier.
Things to remember when using this command with MapInfo Pro 64-bit:
1. If the same menu is added at two different places, then only the last one added can be modified
using this command.
2. If any of MapInfo Pro's predefined menus are added to a drop down, this command would only
modify the one in menu group.

Description
The Alter Menu statement adds menu items to an existing menu or removes menu items from an
existing menu.
The statement can identify the menu to be modified by specifying the name of the menu (e.g., "File")
through the menuname parameter.
If the menu to be modified is one of the standard MapInfo Pro menus, the Alter Menu statement
can identify which menu to alter by using the ID clause. The ID clause identifies the menu by a
number from 1 to 64. The following table lists the names and ID numbers of all standard MapInfo
Pro menus.

Table 1: ID Numbers for Menus

Menu Name Define ID Description

File M_FILE 1 File menu.

Edit M_EDIT 2 Edit menu.

Search M_SEARCH 3 Search menu.

Query M_QUERY 3 Query menu.

Programs M_PGM 4 Programs menu.

Tools M_TOOLS 4 Tools menu.

Options M_OPTIONS 5 Options menu.

Window M_WINDOW 6 Window menu.

MapBasic 15.2 Reference 89

 A to Z MapBasic Language Reference

Menu Name Define ID Description

Help M_HELP 7 Help menu.

Browse M_BROWSE 8 Browse menu. Ordinarily, this only appears when a Browser window
is the active window.

Map M_MAP 9 Map menu. Ordinarily, this menu is only available when a Map
window is active.

Layout M_LAYOUT 10 Layout menu. Available when a Layout window is active.

Graph M_GRAPH 11 Graph menu. Available when a Graph window is active.

MapBasic M_MAPBASIC 12 MapBasic menu. Available when the MapBasic window is active.

Redistrict M_REDISTRICT 13 Redistrict menu. Available when a Districts Browser is active.

Objects M_OBJECTS 14 Objects menu.

Table M_TABLE 15 Table menu.

Open Web Service M_OPEN_WEBSERVICE 39 Open Web Service submenu on the File menu.

Find Selection M_FIND_SELECTION 40 Find Selection submenu on the Query menu.

Oracle Workspace M_ORACLE_TOOLS 41 Oracle Workspace Tools submenu on the Table menu.
Tools

Maintenance M_TAB_MAINTENANCE 42 Maintenance submenu on the Table menu.

Raster M_TAB_RASTER 43 Raster submenu on the Table menu.

Licensing M_LICENSING 44 Licensing submenu on the Help menu.

Tile Server Maps M_TILESERVER 45 Tile Server submenu on the File menu.

Legend Designer M_LEGEND_DESIGNER 49 Legend menu.

Layout Designer M_LAYOUT_DESIGNER 51 Layout menu.

MapBasic 15.2 Reference 90

 A to Z MapBasic Language Reference

The following are shortcut menus, which appear when the user clicks with the right mouse button.

Table 2: ID Numbers for Shortcut Menus

Menu Name Define ID Description

DefaultShortcut M_SHORTCUT_DFLT 16 The default shortcut menu. This menu

appears if the user right-clicks on a window
that does not have its own shortcut menu
defined.

MapperShortcut M_SHORTCUT_MAPPER 17 The Map window shortcut menu.

BrowserShortcut M_SHORTCUT_BROWSER 18 The Browse window shortcut menu.

LayoutShortcut M_SHORTCUT_LAYOUT 19 The Layout window shortcut menu.

GrapherShortcut M_SHORTCUT_GRAPHER 20 The Graph window shortcut menu. This

menu contains options for creating graphs.

CmdShortcut M_SHORTCUT_CMD 21 The MapBasic window shortcut menu.

RedistrictShortcut M_SHORTCUT_REDISTRICTER 22 The Redistricting shortcut menu; available

when the Districts Browser is active.

LegendShortcut M_SHORTCUT_LEGEND 23 The Legend window shortcut menu.

GrapherShortcut M_SHORTCUT_GRAPHTDG 24 The Graph window shortcut menu. This

menu contains options for formatting
graphs already created.

3DMapShortcut M_SHORTCUT_3DMAP 25 The 3D Map window shortcut menu.

MessageWinShortcut M_SHORTCUT_MSG_WIN 26 The Message window shortcut menu.

StatisticsWinShortcut M_SHORTCUT_STAT_WIN 27 The Statistics window shortcut menu.

AdornmentShortcut M_SHORTCUT_ADORNMENT 32 The Adornment window shortcut.

LcLayersShortcut M_SHORTCUT_LC_LAYERS 33 The Layer Control window shortcut that

displays when right-clicking a regular layer
in the layer list.

MapBasic 15.2 Reference 91

 A to Z MapBasic Language Reference

Menu Name Define ID Description

LcMapsShortcut M_SHORTCUT_LC_MAPS 34 The Layer Control window shortcut that

displays when right-clicking a Map node
in the layer list.

LcGroupsShortcut M_SHORTCUT_LC_GROUPS 35 The Layer Control window shortcut that

displays when right-clicking a Group Layer
in the layer list.

TableAdornmentShortcut M_SHORTCUT_TABLEADORNMENT 36 Reserved for future use.

TableListWindowShortcut M_SHORTCUT_TLV_TABLES 37 The Table List window shortcut that

displays when right-clicking a table name.

OverridesShortcut M_SHORTCUT_LC_OVERRIDES 38 The Layer Control window shortcut that

displays when right-clicking a Label
Override or a Display Override.

BrowserFilterShortcut M_SHORTCUT_BROWSER_SORTFILTER 47 The Browser window shortcut that displays

when clicking the Sort/Filter button.

BrowserSelectShortcut M_SHORTCUT_BROWSER_SELECT 48 The Browser window shortcut that displays

when clicking the Selection button.

LegendDesignerShortcut M_SHORTCUT_LEGEND_DESIGNER 50 The Legend Designer window shortcut.

Table 3: ID Numbers for Non-Shortcut Menus

Menu Name Define ID Description

3DWindow M_3DMAP 28 3D Map window.

Graph M_GRAPHTDG 29 Graph menu.

Legend M_LEGEND 31 Legend menu.

When altering a Custom menu (even if you create it with an Custom ID, such as 999), you are
required to use the Custom menuname, not the Custom ID, to alter it.

MapBasic 15.2 Reference 92

 A to Z MapBasic Language Reference

Examples
The following statement adds an item to the File menu.

Alter Menu "File" Add

"Special" Calling sub_procedure_name

In the following example, the menu to be modified is identified by its number.

Alter Menu ID 1 Add

"Special" Calling sub_procedure_name

In the following example, the menu item that is added contains an ID clause. The ID number (300)
can be used in subsequent Alter Menu Item statements.

Alter Menu ID 1 Add

"Special" ID 300 Calling sub_procedure_name

The following example removes the custom item from the File menu.

Alter Menu ID 1 Remove sub_procedure_name

The sample program, TextBox, uses a Create Menu statement to create a menu called "TextBox,"
and then issues the following Alter Menu statement to add the TextBox menu as a hierarchical
menu located on the Tools menu:

Alter Menu "Tools" Add

"(-",
"TextBox" As "TextBox"

The following example adds a custom command to the Map window's shortcut menu (the menu that
appears when an MapInfo Pro user right-clicks on a Map window).

Alter Menu ID 17 Add

"Find Nearest Site" Calling sub_procedure_name

See Also:
Alter Menu Bar statement, Alter Menu Item statement, Create Menu statement, Create Menu
Bar statement

Alter Menu Bar statement

Purpose
Adds or removes menus from the menu bar.

MapBasic 15.2 Reference 93

 A to Z MapBasic Language Reference

Syntax

Alter Menu Bar { Add | Remove }

{ menuname | ID menu_id }
[ , { menuname | ID menu_id } ... ]

menuname is the name of an available menu (e.g., "File")

menu_id is a standard menu ID from one to fifteen; one represents the File menu.
Things to remember when using this command with MapInfo Pro 64-bit:
1. In MapInfo Pro 64-bit, this command adds or removes a menu from the menu group on the
LEGACY tab.
2. The following sub-menus would also be treated as individual dropdown in a menu group:
a. Open Web Service
b. Find Selection
c. Oracle Workspace Tools
d. Maintenance
e. Raster
f. Licensing
g. Tile Serve Maps

Description
The Alter Menu Bar statement adds or removes one or more menus from the current menu bar.
The menuname parameter is a string representing the name of a menu, such as "File" or "Edit".
The menuname parameter may also refer to the name of a custom menu created by a Create Menu
statement (see example below)
Note: If the application is running on a non-English language version of MapInfo, and if the menu
names have been translated, the Alter Menu Bar statement must specify the translated
version of the menu name. However, each of MapInfo Pro's standard menus (File, Edit, etc.)
also has a menu ID, which you can use regardless of whether the menu names have been
translated. For example, specifying ID 2 always refers to the Edit menu, regardless of whether
the menu has been translated.

For a list of MapInfo Pro's standard menu names and their corresponding ID numbers, see Alter
Menu statement.

Adding Menus to the Menu Bar

An Alter Menu Bar Add statement adds a menu to the right end of the menu bar. If you need to
insert a menu at another position on the menu bar, use the Create Menu Bar statement to redefine
the entire menu bar.
If you add enough menus to the menu bar, the menu bar wraps down onto a second line of menu
names.

MapBasic 15.2 Reference 94

 A to Z MapBasic Language Reference

Removing Menus from the Menu Bar

An Alter Menu Bar Remove... statement removes a menu from the menu bar. However, the menu
remains part of the "pool" of available menus. Thus, the following pair of statements would first
remove the Query menu from the menu bar, and then add the Query menu back onto the menu bar
(at the right end of the bar).

Alter Menu Bar Remove "Query"

Alter Menu Bar Add "Query"

After an Alter Menu Bar Remove... statement removes a menu, MapInfo Pro ignores any hotkey
sequences corresponding to items that were on the removed menu. For example, a MapInfo Pro
user might ordinarily press Ctrl+O to bring up the File menu's Open dialog box; however, if an Alter
Menu Bar Remove statement removed the File menu, MapInfo Pro would ignore any Ctrl+O
key-presses.

Example
The following example creates a custom menu, called DataEntry, then uses an Alter Menu Bar
Add statement to add the DataEntry menu to MapInfo Pro's menu bar.

Declare Sub addsub

Declare Sub editsub
Declare Sub delsub
Create Menu "DataEntry" As
"Add" Calling addsub,
"Edit" Calling editsub,
"Delete" Calling delsub
'Remove the Window menu and Help menu
Alter Menu Bar Remove ID 6, ID 7
'Add the custom menu, then the Window & Help menus
Alter Menu Bar Add "DataEntry", ID 6, ID 7

Before adding the custom menu to the menu bar, this program removes the Help menu (menu ID
7) and the Window menu (ID 6) from the menu bar. The program then adds the custom menu, the
Window menu, and the Help menu to the menu bar. This technique guarantees that the last two
menus will always be Window and Help.
See Also:
Alter Menu statement, Alter Menu Item statement, Create Menu statement, Create Menu Bar
statement, Menu Bar statement

Alter Menu Item statement

Purpose
Alters the status of a specific menu item.

MapBasic 15.2 Reference 95

 A to Z MapBasic Language Reference

Syntax

Alter Menu Item { handler | ID menu_item_id }

{ [ Check | Uncheck ] |
[ Enable | Disable ] |
[ Text itemname ] |
[ Calling handler | As menuname ] }

handler is either the name of a Sub procedure or the code for a standard MapInfo Pro command.
menu_item_id is an integer that identifies a menu item; this corresponds to the menu_item_id
parameter specified in the statement that created the menu item (Create Menu statement or Alter
Menu statement).
itemname is the new text for the menu item (may contain embedded codes).
menuname is the name of an existing menu.
Things to remember when using this command with MapInfo Pro 64-bit:
1. In MapInfo Pro 64-bit, this command is only supported for user created controls.
2. Modifying text with new shortcut would only take effect if it is not being used by any other control
in application.
3. Calling As Clause is not supported.

Description
The Alter Menu Item statement alters one or more of the items that make up the available menus.
For example, you could use the Alter Menu Item statement to check or disable (gray out) a menu
item.
The statement must either specify a handler (e.g., the name of a procedure in the same program),
or an ID clause to indicate which menu item(s) to modify. Note that it is possible for multiple, separate
menu items to call the same handler procedure. If the Alter Menu Item statement includes the name
of a handler procedure, MapInfo Pro alters all menu items that call that handler. If the statement
includes an ID clause, MapInfo Pro alters only the menu item that was defined with that ID.
The Alter Menu Item statement can only refer to a menu item ID if the statement which defined the
menu item included an ID clause. A MapBasic application cannot refer to menu item IDs created
by other MapBasic applications.
The Check clause and the Uncheck clause affect whether the item appears with a checkmark on
the menu. Note that a menu item may only be checked if it was defined as "checkable" (for example,
if the Create Map statement included a "!" as the first character of the menu item name).
The Disable clause and the Enable clause control whether the item is disabled (grayed out) or
enabled. Note that MapInfo Pro automatically enables and disables various menu items based on
the current circumstances. For example, the Close command is disabled whenever there are no
tables open. Therefore, MapBasic applications should not attempt to enable or disable standard
MapInfo Pro menu items. Similarly, although you can treat specific tools as menu items (by referencing

MapBasic 15.2 Reference 96

 A to Z MapBasic Language Reference

defines from MENU.DEF, such as M_TOOLS_RULER), you should not attempt to enable or disable
tools through the Alter Menu Item statement.
The Text clause allows you to rename a menu item.
The Calling clause specifies a handler for the menu item. If the user chooses the menu item, MapInfo
Pro calls the item's handler.

Examples
The following example creates a custom "DataEntry" menu.

Declare Sub addsub

Declare Sub editsub
Declare Sub delsub
Create Menu "DataEntry" As
"Add" Calling addsub,
"Edit" Calling editsub,
"Delete" ID 100 Calling delsub,
"Delete All" ID 101 Calling delsub
'Remove the Help menu
Alter Menu Bar Remove ID 7
'Add both the new menu and the Help menu
Alter Menu Bar Add "DataEntry" , ID 7

The following Alter Menu Item statement renames the "Edit" item to read "Edit..."

Alter Menu Item editsub Text "Edit..."

The following statement disables the "Delete All" menu item.

Alter Menu Item ID 101 Disable

The following statement disables both the "Delete" and the "Delete All" items, because it identifies
the handler procedure delsub, which is the handler for both menu items.

Alter Menu Item delsub Disable

See Also:
Alter Menu statement, Alter Menu Bar statement, Create Menu statement

Alter Object statement

Purpose
Modifies the shape, position, or graphical style of an object. You can issue this statement from the
MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 97

 A to Z MapBasic Language Reference

Syntax

Alter Object obj

{ Info object_info_code, new_info_value |
Geography object_geo_code , new_geo_value |
Node {
Add [ Position polygon_num, node_num ] ( x, y ) |
Set Position polygon_num, node_num ( x , y ) |
Remove Position polygon_num, node_num } }

obj is an object variable.

object_info_code is an integer code relating to the ObjectInfo() function (e.g., OBJ_INFO_PEN).
new_info_value specifies the new object_info_code attribute to apply (e.g., a new Pen style).
object_geo_code is an integer code relating to the ObjectGeography() function (e.g.,
OBJ_GEO_POINTX).
new_geo_value specifies the new object_geo_code value to apply (e.g., the new x-coordinate).
polygon_num is a integer value (one or larger), identifying one polygon from a region object or one
section from a polyline object.
node_num is a integer value (one or larger), identifying one node from a polyline or polygon.
x, y are x- and y-coordinates of a node.

Description
The Alter Object statement alters the shape, position, or graphical style of an object.
The effect of an Alter Object statement depends on whether the statement includes an Info clause,
a Node clause, or a Geography clause. If the statement includes an Info clause, MapBasic alters
the object's graphical style (e.g., the object's Pen and Brush styles). If the statement includes a
Node clause, MapBasic adds, removes, or repositions a node (this applies only to polyline or region
objects). If the statement includes a Geography clause, MapBasic alters a geographical attribute
for objects other than polylines and regions (e.g., the x- or y-coordinate of a point object).

Info clause
By issuing an Alter Object statement with an Info clause, you can reset an object's style (e.g., the
Pen or Brush). The Info clause lets you modify the same style attributes that you can query through
the ObjectInfo() function.
For example, you can determine an object's current Brush style by calling the ObjectInfo() function:

Dim b_fillstyle As Brush

b_fillstyle = ObjectInfo(Selection.obj, OBJ_INFO_BRUSH)

MapBasic 15.2 Reference 98

 A to Z MapBasic Language Reference

Conversely, the following Alter Object statement allows you to reset the Brush style:

Alter Object obj_variable_name

Info OBJ_INFO_BRUSH, b_fillstyle

Note that you use the same code (e.g., OBJ_INFO_BRUSH) in both the ObjectInfo() function and
the Alter Object statement.
The table below summarizes the values you can specify in the Info clause to perform various types
of style alterations. Note that the obj_info_code values are defined in the standard MapBasic
definitions file, MAPBASIC.DEF. Accordingly, your program should Include "MAPBASIC.DEF" if you
intend to use the Alter Object...Info statement.

obj_info_code Value ID Result of Alter Object

OBJ_INFO_PEN 2 Resets object's Pen style; new_info_value must be a Pen

expression.

OBJ_INFO_SYMBOL 2 Resets a Point object's Symbol style; new_info_value must be a

Symbol expression.

OBJ_INFO_BRUSH 3 Resets object's Brush style; new_info_value must be a Brush

expression.

OBJ_INFO_SMOOTH 4 Resets a Polyline object's smoothed/unsmoothed setting;

new_info_value must be a logical expression.

OBJ_INFO_FRAMEWIN 4 Changes which window is displayed in a layout frame;

new_info_value must be an integer window ID.

OBJ_INFO_FRAMETITLE 6 Changes the title of a Frame object; new_info_value must be a

string.

OBJ_INFO_TEXTFONT 2 Resets a Text object's Font style; new_info_value must be a Font

expression.

OBJ_INFO_TEXTSTRING 3 Changes the text string that comprises a Text object; new_info_value
must be a string expression.

OBJ_INFO_TEXTSPACING 4 Changes a Text object's line spacing; new_info_value must be a

float value of 1, 1.5, or 2.

OBJ_INFO_TEXTJUSTIFY 5 Changes a Text object's alignment; new_info_value must be 0 for

left-justified, 1 for center-justified, or 2 for right-justified.

MapBasic 15.2 Reference 99

 A to Z MapBasic Language Reference

obj_info_code Value ID Result of Alter Object

OBJ_INFO_TEXTARROW 6 Changes a Text object's label line setting; new_info_value must be

0 for no line, 1 for simple line, or 2 for a line with an arrow.

Geography clause
By issuing an Alter Object statement with a Geography clause, you can alter an object's
geographical coordinates. The Geography clause applies to all object types except for polylines
and regions. To alter the coordinates of a polyline or region object, use the Node clause (described
below) instead of the Geography clause.
The Geography clause lets you modify the same attributes that you can query through the
ObjectGeography() function. For example, you can obtain a line object's end coordinates by calling
the ObjectGeography() function:

Dim o_cable As Object

Dim x, y As Float
x = ObjectGeography(o_cable, OBJ_GEO_LINEENDX)
y = ObjectGeography(o_cable, OBJ_GEO_LINEENDY)

Conversely, the following Alter Object statements let you alter the line object's end coordinates:

Alter Object o_cable

Geography OBJ_GEO_LINEENDX, x
Alter Object o_cable
Geography OBJ_GEO_LINEENDY, y

Note: You use the same codes (e.g., OBJ_GEO_LINEENDX) in both the ObjectGeography()
function and the Alter Object statement.

The table below summarizes the values you can specify in the Geography clause in order to perform
various types of geographic alterations. Note that the obj_geo_code values are defined in the
standard MapBasic definitions file, MAPBASIC.DEF. Your program should Include "MAPBASIC.DEF"
if you intend to use the Alter Object...Geography statement.

obj_geo_code Value ID Result of Alter Object

OBJ_GEO_MINX 1 Alters object's minimum bounding rectangle.

OBJ_GEO_MINY 2 Alters object's MBR.

OBJ_GEO_MAXX 3 Alters object's MBR; does not apply to Point objects.

OBJ_GEO_MAXY 4 Alters object's MBR; does not apply to Point objects.

MapBasic 15.2 Reference 100

 A to Z MapBasic Language Reference

obj_geo_code Value ID Result of Alter Object

OBJ_GEO_ARCBEGANGLE 5 Alters beginning angle of an Arc object.

OBJ_GEO_ARCENDANGLE 6 Alters ending angle of an Arc object.

OBJ_GEO_LINEBEGX 1 Alters a Line object's starting node.

OBJ_GEO_LINEBEGY 2 Alters a Line object's starting node.

OBJ_GEO_LINEENDX 3 Alters a Line object's ending node.

OBJ_GEO_LINEENDY 4 Alters a Line object's ending node.

OBJ_GEO_POINTX 1 Alters a Point object's x coordinate.

OBJ_GEO_POINTY 2 Alters a Point object's y coordinate.

OBJ_GEO_ROUNDRADIUS 5 Alters the diameter of the circle that defines the rounded corner of
a Rounded Rectangle object.

OBJ_GEO_TEXTLINEX 5 Alters x coordinate of the end of a Text object's label line.

OBJ_GEO_TEXTLINEY 6 Alters y coordinate of the end of a Text object's label line.

OBJ_GEO_TEXTANGLE 7 Alters rotation angle of a Text object.

Node clause
By issuing an Alter Object statement with a Node clause, you can add, remove, or reposition nodes
in a polyline or region object.
If the Node clause includes an Add sub-clause, the Alter Object statement adds a node to the
object. If the Node clause includes a Remove sub-clause, the statement removes a node. If the
Node clause includes a Set Position sub-clause, the statement repositions a node.
The Alter Object statement's Node clause is often used in conjunction with the Create Pline
statement and the Create Region statement. Create statements allow you to create new polyline
and region objects. However, Create statements are somewhat restrictive, because they force you
to state at compile time the number of nodes that will comprise the object. In some situations, you
may not know how many nodes should go into an object until run-time.
If your program will not know until run-time how many nodes should comprise an object, you can
issue a Create Pline statement or a Create Region statement which creates an "empty" object

MapBasic 15.2 Reference 101

 A to Z MapBasic Language Reference

(an object with zero nodes). Your program can then issue an appropriate number of Alter
Object...Node Add statements, to add nodes as needed.
Within the Node clause, the Position sub-clause includes two parameters, polygon_num and
node_num, that let you specify exactly which node you want to reposition or remove. The Position
sub-clause is optional when you are adding a node. The polygon_num and node_num parameters
should always be 1 (one) or greater.
The polygon_num parameter specifies which polygon in a multiple-polygon region (or which section
in a multiple-section polyline) should be modified.

Region Centroids
The Centroid of a Region can be set by using the Alter Object command with the syntax noted
below:

Alter Object Obj Geography OBJ_GEO_CENTROID, PointObj

Note that PointObj is a point object. This differs from other values input by Alter Object Geography,
which are all scalars. A point is needed in this instance because we need two values which define
a point. The Point that is input is checked to make sure it is a valid Centroid (for example, it is inside
the region). If the Obj is not a region, or if PointObj is not a point object, or if the point is not a valid
centroid, then an error is returned.
An easy way to center an X and Y value for a centroid is as follows:

Alter Object Obj Geography OBJ_GEO_CENTROID, CreatePoint(X, Y)

The user can also query the centroid by using the ObjectGeography() function as follows:

PointObj = ObjectGeography(Obj, OBJ_GEO_CENTROID)

There are other ways to get the Centroid, including the Centroid() function, CentroidX() function,
and CentroidY() function.
OBJ_GEO_CENTROID is defined in MAPBASIC.DEF.

Multipoint Objects and Collections

The Alter Object statement supports the following object types.
• Multipoint: sets a Multipoint symbol as shown in the following:

Alter Object obj_variable_mpoint

Info OBJ_INFO_SYMBOL, NewSymbol

• Collection: By issuing an Alter Object statement with an Info clause, you can reset collection
parts (Region, Polyline or Multipoint) inside the collection object. The Info clause allows you to

MapBasic 15.2 Reference 102

 A to Z MapBasic Language Reference

modify the same attributes that you can query through the ObjectInfo() function. For example,
you can determine a collection object's region part by calling the ObjectInfo() function:

Dim ObjRegion As Object

ObjRegion = ObjectInfo(Selection.obj, OBJ_INFO_REGION)

Also, the following Alter Object statement allows you to reset the region part of a collection object:

Alter Object obj_variable_name

Info OBJ_INFO_REGION, ObjRegion

Note: You use the same code (e.g., OBJ_INFO_REGION) in both the ObjectInfo() function and
the Alter Object statement.

The Alter Object statement inserts and deletes nodes to/from Multipoint objects.

Alter Object obj Node statement

To insert nodes within a Multipoint object:

Dim mpoint_obj as object

Create Multipoint Into Variable mpoint_obj 0
Alter Object mpoint_obj Node Add (0,1)
Alter Object mpoint_obj Node Add (2,1)

Note: Nodes for Multipoint are always added at the end.

To delete nodes from a Multipoint object:

Alter Object mpoint_obj Node Remove Position polygon_num, node_num

mpoint_obj is a Multipoint object variable.

polygon_num is ignored for Multipoint, it is advisable to set it to 1.
node_num is the number of a node to be removed.
To set nodes inside a Multipoint object:

Alter Object mpoint_obj Node Set Position polygon_num, node_num (x,y)

mpoint_obj is a Multipoint object variable.

polygon_num is ignored for Multipoint, it is advisable to set it to 1.
node_num is the number of a node to be changed.
x and y are the new coordinates of the node node_num.

MapBasic 15.2 Reference 103

 A to Z MapBasic Language Reference

Example

Dim myobj As Object, i As Integer

Create Region Into Variable myobj 0
For i = 1 to 10
Alter Object myobj
Node Add (Rnd(1) * 100, Rnd(1) * 100)
Next

Note: After using the Alter Object statement to modify an object, use an Insert statement or an
Update statement to store the object in a table.

See Also:
Create Pline statement, Create Region statement, Insert statement, ObjectGeography()
function, ObjectInfo() function, Update statement

Alter Table statement

Purpose
Alters the structure of a table. Cannot be used on linked tables. You can issue this statement from
the MapBasic window in MapInfo Pro.

Syntax

Alter Table table (

[ Add columnname columntype [ , ...] ]
[ Modify columnname columntype [ , ...] ]
[ Drop columnname [ , ...] ]
[ Rename oldcolumnname newcolumnname [ , ...] ]
[ Order columnname, columnname [ ,...] ] )
[ Interactive ]

table is the name of an open table.

columnname is the name of a column; column names can be up to 31 characters long, and can
contain letters, numbers, and the underscore character, and column names cannot begin with
numbers.
columntype indicates the datatype of a table column (including the field width if necessary).
oldcolumnname represents the previous name of a column to be renamed.
newcolumnname represents the intended new name of a column to be renamed.

MapBasic 15.2 Reference 104

 A to Z MapBasic Language Reference

Description
The Alter Table statement lets you modify the structure of an open table, allowing you to add
columns, change column widths or datatypes, drop (delete) columns, rename columns, and change
column ordering.
Note: If you have edited a table, you must save or discard your edits before you can use the Alter
Table statement.

Each columntype should be one of the following: integer, SmallInt, float, decimal( size, decplaces
), char(size), date, or logical, DateTime. DateTime is an integer value stored in nine bytes: 4 bytes
for date, 5 bytes for time. Five bytes for time include: 2 for millisec, 1 for sec, 1 for min, 1 for hour.
By including an Add clause in an Alter Table statement, you can add new columns to your table.
By including a Modify clause, you can change the datatypes of existing columns. A Drop clause
lets you delete columns, while a Rename clause lets you change the names of existing columns.
The Order clause lets you specify the order of the columns. Altogether, an Alter Table statement
can have up to five clauses. Note that each of these five clauses can operate on a list of columns;
thus, with a single Alter Table statement, you can make all of the structural changes that you need
to make (see example below).
The Order clause affects the order of the columns, not the order of rows in the table. Column order
dictates the relative positions of the columns when you browse the table; the first column appears
at the left edge of a Browser window, and the last column appears at the right edge. Similarly, a
table's first column appears at the top of an Info Tool window.
If a MapBasic application issues an Alter Table statement affecting a table which has memo fields,
the memo fields will be lost. No warning will be displayed.
An Alter Table statement may cause map layers to be removed from a Map window, possibly
causing the loss of themes or cosmetic objects. If you include the Interactive keyword, MapInfo
Pro prompts the user to save themes and/or cosmetic objects (if themes or cosmetic objects are
about to be lost).

Example
In the following example, we have a hypothetical table, "gcpop.tab" which contains the following
columns: pop_88, metsize, fipscode, and utmcode. The Alter Table statement below makes several
changes to the gcpop table. First, a Rename clause changes the name of the pop_88 column to
population. Then the Drop clause deletes the metsize, fipscode, and utmcode columns. An Add
clause creates two new columns: a small (2-byte) integer column called schoolcode, and a floating
point column called federalaid. Finally, an Order clause specifies the order for the new set of columns:
the schoolcode column comes first, followed by the population column, etc.

Open Table "gcpop"

Alter Table gcpop
(Rename pop_88 population
Drop metsize, fipscode, utmcode
Add schoolcode SmallInt, federalaid Float
Order schoolcode, population, federalaid)

MapBasic 15.2 Reference 105

 A to Z MapBasic Language Reference

See Also:
Add Column statement, Create Index statement, Create Map statement, Create Table statement

ApplicationDirectory$() function
Purpose
Returns a string containing the path from which the current MapBasic application is executing. You
can call this function from the MapBasic window in MapInfo Pro.

Syntax

ApplicationDirectory$()

Return Value
String expression, representing a directory path.

Description
By calling the ApplicationDirectory$() function from within a compiled MapBasic application, you
can determine the directory or folder from which the application is running. If no application is running
(e.g., if you call the function by typing into the MapBasic window), ApplicationDirectory$() returns
a null string.
To determine the directory or folder where the MapInfo Pro software is installed, call the
ProgramDirectory$() function.

Example

Dim sAppPath As String

sAppPath = ApplicationDirectory$()
' At this point, sAppPath might look like this:
'
' "C:\MAPBASIC\CODE\"

See Also:
ProgramDirectory$() function, ApplicationName$() function

ApplicationName$() function
Purpose
Returns a string containing the name of the current MapBasic application that is running. You can
call this function from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 106

 A to Z MapBasic Language Reference

Syntax

ApplicationName$()

Return Value
String expression representing the name of the MapBasic program.

Description
By calling the ApplicationName$() function from within a compiled MapBasic application, you can
determine the name of the running application. If no application is running (if you call the function
by typing into the MapBasic window), then ApplicationName$() returns an empty string.
To determine the path from which the current MapBasic application is executing call the
ApplicationDirectory$() function.

Example

Dim sAppName As String

sAppName = ApplicationName$()
' At this point, sAppName might look like this:
'
' "Test.MBX"

See Also:
ApplicationDirectory$() function

Area() function
Purpose
Returns the geographical area of an Object. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

Area( obj_expr, unit_name )

obj_expr is an object expression.

unit_name is a string representing the name of an area unit (e.g., "sq km").

Return Value
Float

MapBasic 15.2 Reference 107

 A to Z MapBasic Language Reference

Description
The Area() function returns the area of the geographical object specified by obj_expr.
The function returns the area measurement in the units specified by the unit_name parameter; for
example, to obtain an area in acres, specify "acre" as the unit_name parameter. See Set Area Units
statement for the list of available unit names.
Only regions, ellipses, rectangles, and rounded rectangles have any area. By definition, the area
of a point, arc, text, line, or polyline object is zero. The Area() function returns approximate results
when used on rounded rectangles. MapBasic calculates the area of a rounded rectangle as if the
object were a conventional rectangle.
For the most part, MapInfo Pro performs a Cartesian or Spherical operation. Generally, a spherical
operation is performed unless the coordinate system is NonEarth, in which case, a Cartesian
operation is performed.

Examples
The following example shows how the Area() function can calculate the area of a single geographic
object. Note that the expression tablename.obj (as in states.obj) represents the geographical object
of the current row in the specified table.

Dim f_sq_miles As Float

Open Table "states"
Fetch First From states
f_sq_miles = Area(states.obj, "sq mi")

You can also use the Area() function within the SQL Select statement, as shown in the following
example.

Select state, Area(obj, "sq km")

From states Into results

See Also:
ObjectLen() function, Perimeter() function, CartesianArea() function, SphericalArea() function,
Set Area Units statement

AreaOverlap() function
Purpose
Returns the area resulting from the overlap of two closed objects. You can call this function from
the MapBasic window in MapInfo Pro.

Syntax

AreaOverlap( object1, object2 )

MapBasic 15.2 Reference 108

 A to Z MapBasic Language Reference

object1 and object2 are closed objects.

Return Value
A float value representing the area (in MapBasic's current area units) of the overlap of the two
objects.

Restrictions
AreaOverlap() only works on closed objects. If both objects are not closed (such as points and lines),
then you may see an error message. Closed objects are objects that can produce an area, such as
regions (polygons).
See Also:
IntersectNodes() function, Overlap() function, ProportionOverlap() function, Set Area Units
statement

Asc() function
Purpose
Returns the character code for the first character in a string expression. You can call this function
from the MapBasic window in MapInfo Pro.

Syntax

Asc( string_expr )

string_expr is a string expression.

Return Value
Integer

Description
The Asc() function returns the character code representing the first character in the string specified
by string_expr.
If string_expr is a null string, the Asc() function returns a value of zero.
Note: All MapInfo Pro environments have common character codes within the range of 32 (space)
to 126 (tilde).

On a system that supports double-byte character sets (e.g., Windows Japanese): if the first character
of string_expr is a single-byte character, Asc() returns a number in the range 0 - 255; if the first
character of string_expr is a double-byte character, Asc() returns a value in the range 256 - 65,535.

MapBasic 15.2 Reference 109

 A to Z MapBasic Language Reference

On systems that do not support double-byte character sets, Asc() returns a number in the range 0
- 255.
In Unicode versions of MapInfo Pro, this function operates in the system character set in a compatible
manner with the non-Unicode versions of MapInfo Pro.

Example

Dim code As SmallInt

code = Asc("Afghanistan")
' code will now be equal to 65,
' since 65 is the code for the letter A

See Also:
CharVal() function, Chr$() function, Character Code Table Definitions

Asin() function
Purpose
Returns the arc-sine value of a number. You can call this function from the MapBasic window in
MapInfo Pro.

Syntax

Asin( num_expr )

num_expr is a numeric expression from one to negative one, inclusive.

Return Value
Float

Description
The Asin() function returns the arc-sine of the numeric num_expr value. In other words, Asin()
returns the angle whose sine is equal to num_expr.
The result returned from Asin() represents an angle, expressed in radians. This angle will be
somewhere between -Pi/2 and Pi/2 radians (given that Pi is approximately equal to 3.141593, and
given that Pi/2 radians represents 90 degrees).
To convert a degree value to radians, multiply that value by DEG_2_RAD. To convert a radian value
into degrees, multiply that value by RAD_2_DEG. (Note that your program will need to Include
"MAPBASIC.DEF" in order to reference DEG_2_RAD or RAD_2_DEG).
Since sine values range between one and negative one, the expression num_expr should represent
a value no larger than one (1) and no smaller than negative one (-1).

MapBasic 15.2 Reference 110

 A to Z MapBasic Language Reference

Example

Include "MAPBASIC.DEF"
Dim x, y As Float
x = 0.5
y = Asin(x) * RAD_2_DEG

' y will now be equal to 30,

' since the sine of 30 degrees is 0.5

See Also:
Acos() function, Atn() function, Cos() function, Sin() function, Tan() function

Ask() function
Purpose
Displays a dialog box, asking the user a yes or no (OK or Cancel) question. You can call this function
from the MapBasic window in MapInfo Pro.

Syntax

Ask( prompt, ok_text, cancel_text )

prompt is a string to appear as a prompt in the dialog box.

ok_text is a string (e.g., "OK") that appears on the confirmation button.
cancel_text is a string (e.g., "Cancel") that appears on the cancel button.

Return Value
Logical

Description
The Ask() function displays a dialog box, asking the user a yes-or-no question. The prompt parameter
specifies a message, such as "File already exists; do you want to continue?" While the length of
the prompt string passed to the Ask function can be approximately 2000 characters long,only the
first 299 will display in the dialog.
The dialog box contains two buttons; the user can click one button to give a Yes answer to the
prompt, or click the other button to give a No answer. The ok_text parameter specifies the name of
the Yes-answer button (e.g., "OK" or "Continue"), and the cancel_text parameter specifies the name
of the No-answer button (e.g., "Cancel" or "Stop").
If the user selects the ok_text button, the Ask() function returns TRUE. If the user clicks the
cancel_text button or otherwise cancels the dialog box (e.g., by pressing the Esc key), the Ask()
function returns FALSE. Since the buttons are limited in size, the ok_text and cancel_text strings

MapBasic 15.2 Reference 111

 A to Z MapBasic Language Reference

should be brief. If you need to display phrases that are too long to fit in small dialog box buttons,
you can use the Dialog statement instead of calling the Ask() function. The ok_text button is the
default button (the button which will be selected if the user presses Enter instead of clicking with
the mouse).

Example

Dim more As Logical

more = Ask("Do you want to continue?", "OK", "Stop")

See Also:
Dialog statement, Note statement, Print statement

Atn() function
Purpose
Returns the arc-tangent value of a number. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

Atn( num_expr )

num_expr is a numeric expression.

Return Value
Float

Description
The Atn() function returns the arc-tangent of the numeric num_expr value. In other words, Atn()
returns the angle whose tangent is equal to num_expr. The num_expr expression can have any
numeric value.
The result returned from Atn() represents an angle, expressed in radians, in the range -Pi/2 radians
to Pi/2 radians.
To convert a degree value to radians, multiply that value by DEG_2_RAD. To convert a radian value
into degrees, multiply that value by RAD_2_DEG. (Note that your program will need to Include
"MAPBASIC.DEF" in order to reference DEG_2_RAD or RAD_2_DEG).

Example

Include "MAPBASIC.DEF"
Dim val As Float

MapBasic 15.2 Reference 112

 A to Z MapBasic Language Reference

val = Atn(1) * RAD_2_DEG

'val is now 45, since the
'Arc tangent of 1 is 45 degrees

See Also:
Acos() function, Asin() function, Cos() function, Sin() function, Tan() function

AutoLabel statement
Purpose
Draws labels in a Map window, and stores the labels in the Cosmetic layer. You can issue this
statement from the MapBasic window in MapInfo Pro.

Syntax

AutoLabel
[ Window window_id ]
[ { Selection | Layer layer_id } ]
[ Overlap [ { On | Off } ] ]
[ Duplicates [ { On | Off } ] ]

window_id is an integer window identifier for a Map window.

layer_id is a table name (e.g., World) or a SmallInt layer number (e.g., 1 to draw labels for the top
layer).

Description
The AutoLabel statement draws labels (text objects) in a Map window. Only objects that are currently
visible in the Map window are labeled. The Window clause controls which Map window is labeled.
If you omit the Window clause, MapInfo Pro draws labels in the front-most Map window. If you
specify Selection, only selected objects are labeled. If you omit both the Selection and the Layer
clause, all layers are labeled.
The Overlap clause controls whether MapInfo Pro draws labels that overlap other labels. This setting
defaults to Off (MapInfo Pro will not draw overlapping labels). To force MapInfo Pro to draw a label
for every map object, regardless of whether the labels overlap, specify Overlap On. The Duplicates
clause controls whether MapInfo Pro draws a new label for an object that has already been labeled.
This setting defaults to Off (duplicates not allowed). The AutoLabel statement uses whatever font
and position settings are in effect. Set label options by choosing the Layers command (on the HOME
tab in the Document Windows group). To control font and position settings through MapBasic,
issue a Set Map statement.

MapBasic 15.2 Reference 113

 A to Z MapBasic Language Reference

Example

Open Table "world" Interactive

Open Table "worldcap" Interactive
Map From world, worldcap
AutoLabel
Window FrontWindow( )
Layer world

See Also:
Set Map statement

Beep statement
Purpose
Makes a beeping sound. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Beep

Description
The Beep statement sends a sound to the speaker.

Browse statement
Purpose
Opens a new Browser window. You can issue this statement from the MapBasic window in MapInfo
Pro.

Syntax

Browse expression_list From table

[ Position ( x, y ) [ Units paper_units ] ]
[ Width window_width [ Units paper_units ] ]
[ Height window_height [ Units paper_units ] ]
[ Row n ]
[ Column n ]
[ Min | Max | Floating | Docked | Tabbed | AutoHidden]
[ Pen .... ] [ Priority n ] [ Name framename ]
[ Into { Window layout_win_id } { ID empty_frame_id } ]

expression_list is either an asterisk or a comma-separated list of column expressions.

MapBasic 15.2 Reference 114

 A to Z MapBasic Language Reference

table is a string representing the name of an open table.

x, y specifies the position of the upper left corner of the Browser, in paper_units. With the Into
Window clause, the position is relative to the upper left corner of the Layout window.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in
(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
Floating docking state makes the window floating.
Docked docking state docks the window to the default position.
Tabbed docking stae makes the window tabbed, in this state it is also callled as a document.
AutoHidden docking state auto hides the window.
Note: All four docking states above are specific only to the 64-bit version of MapInfo Pro.

window_width and window_height specify the size of the Browser, in paper_units. With the Into
Window clause, this represents the width and height of the frame in the Layout window. If a valid
width or height is not specified, then a value is generated for the frame.
n is a positive integer value of 1 or higher.
framename is a string representing the name for this browser embedded in a layout frame. If a name
is assigned to a frame in the Layout window, it will be written to the WOR. When the Name clause
is written to the WOR, the workspace version is updated to version 1500.
layout_win_id is a Layout window's integer window identifier.
empty_frame_id is an emptly Layout window's integer window identifier.

Description
The Browse statement opens a Browse window to display a table. You can also use it to insert a
Browser window into a Layout window when preparing a layout. This description will use the name
Browser to mean either a Browser window in MapInfo Pro or a browser frame in a Layout window.
If the expression_list is simply an asterisk (*), the new Browser includes all fields in the table.
Alternately, the expression_list clause can consist of a comma-separated list of expressions, each
of which defines one column that is to appear in the Browser. Expressions in the list can contain
column names, operators, functions, and variables. Each column's name is derived from the
expression that defines the column. Thus, if a column is defined by the expression population /
area(obj, "acre"), that expression will appear on the top row of the Browser, as the column name.
To assign an alias to an expression, follow the expression with a string; see the example below.

MapBasic 15.2 Reference 115

 A to Z MapBasic Language Reference

An optional Position clause lets you specify where on the screen or in a layout to display the
Browser. The x coordinate specifies the distance (in paper units) from the left edge of the MapInfo
Pro application window to the left edge of the Browser window, or from the left edge of the Layout
window to the left edge of a browser frame. For details about paper units, see Set Paper Units
statement. The y coordinate specifies the distance from the top of the window down to the top of
the Browser.
The optional Width and Height clauses specify the size of the Browser window, in paper units. If
no Width and Height clauses are provided, MapInfo Pro assigns the Browser a default size that
depends on the table in question. For a Browser window, its height will be one quarter of the screen
height, unless the table does not have enough rows to fill a Browser window that large; and the
Browser width will depend on the widths of the fields in the table.
The optional Width and Height clauses specify the size of the Browser, in paper units. If no Width
and Height clauses are provided, MapInfo Pro assigns the Browser a default size that depends on
the table in question. For a Browser window, its height will be one quarter of the screen height,
unless the table does not have enough rows to fill a Browser window that large; and the Browser
window's width will depend on the widths of the fields in the table.
If the Browse statement includes the optional Max keyword, then the resulting Browser is maximized,
taking up all of the screen space available to MapInfo Pro or the entire canvas in a Layout Desinger
window. Conversely, if the Browse statement includes the Min keyword, the Browser is minimized
immediately.
The Row clause dictates which row of the table should appear at the top of the Browser. If the
Browse statement does not include a Row clause, the first row of the table will be the top row in
the Browser.
Similarly, the Column clause dictates which of the table's columns should appear at the left edge
of the Browser. If the Browse statement does not include a Column clause, the table's first column
will appear at the left edge of the Browser.
Pen is a valid Pen clause. This clause is designed to turn on (solid) or off (hollow) and set the color
of the border of the frame.
Priority is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of
frames to a unique set of values beginning with 1.
The Into Window clause creates a new frame within an existing Layout window.
Use the ID clause to insert open tables into an empty layout frame. The frame properties already
set for the empty frame are retained (pen, brush, position, size, name, and z-order). An error results
when the:
• From Window ID is not a map or browser: 1696 "Error: Expecting Map or Browser Window."
• Frame ID is not empty: 1698 "Layout frame ^0 must be empty."
• From Window does not close: 1697 "Unable to clone Window into empty frame."
• Map legends does not clone: 1708 "Unable to clone Legends for Map frame."

MapBasic 15.2 Reference 116

 A to Z MapBasic Language Reference

The following example creates a browser for the open table called World and inserts it into the empty
frame in the Layout window.

Browser World Into Window layout_win_id ID empty_frame_id

To reuse a frame after it has been filled with content it needs to be emptied, see the Set Designer
Frame statement. This leaves behind an empty frame of the same size and position as the content
it just contained, and retains the name currently assigned to it.

Example
The following example opens the World table and displays all columns from the table in a Browser
window.

Open Table "world"

Browse * From world

The next example specifies exactly which column expressions from the World table should be
displayed in the Browser.

Open Table "world"

Browse
country,
population,
population/area(obj, "sq km") "Density"
From world

The resultant Browser has three columns. The first two columns represent data as it is stored in the
World table, while the third column is derived. Through the third expression, MapBasic divides the
population of each country record with the geographic area of the region associated with that record.
The derived column expression has an alias ("Density") which appears on the top row of the Browse
window.
See Also:
FrontWindow() function, Set Browse statement, Set Designer Frame statement, Set Paper
Units statement, Set Window statement, WindowID() function

BrowserInfo() function
Purpose
Returns information about a Browser window, such as: the total number of rows or columns in the
Browser window; or the row number, column number, or value contained in the current cell. You
can call this function from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 117

 A to Z MapBasic Language Reference

Syntax

BrowserInfo( window_id, attribute )

window_id is an integer window identifier.

attribute is an integer code indicating what type of information to return. For values, see the table
later in this description.

Return Value
Float, logical, or string depending on the attribute parameter.

Description
The BrowserInfo() function returns information about a Browser window. The function does not apply
to the Redistricter window.
The window_id parameter specifies which Browser window to query. To obtain a window identifier,
call the FrontWindow() function immediately after opening a window, or call the WindowID()
function at any time after the window's creation.
There are several attributes that BrowserInfo() returns about any given Browser window. The attribute
parameter tells the BrowserInfo () function what Browser window statistic to return. The attribute
parameter should be one of the codes from the following table; codes are defined in MAPBASIC.DEF.

Attribute Parameter ID Return Value

BROWSER_INFO_NROWS 1 The total number of rows in the Browser window.

BROWSER_INFO_NCOLS 2 The total number of columns in the Browser window.

BROWSER_INFO_CURRENT_ROW 3 The row number of the current cell in the Browser window. Row
numbers start at one (1).

BROWSER_INFO_CURRENT_COLUMN 4 The column number of the current cell in the Browser window.
Column numbers start at zero (0).

BROWSER_INFO_CURRENT_CELL_VALUE 5 The value contained in the current cell in the Browser window.

Error Conditions
ERR_BAD_WINDOW (590) error generated if parameter is not a valid window number.
ERR_FCN_ARG_RANGE (644) error generated if an argument is outside of the valid range.
ERR_WANT_BROWSER_WIN (312) error generated if window id is not a Browser window.
See Also:

MapBasic 15.2 Reference 118

 A to Z MapBasic Language Reference

FrontWindow() function, WindowID() function

Brush clause
Purpose
Specifies a fill style for graphic objects. You can use this clause in the MapBasic window in MapInfo
Pro.

Syntax

Brush brush_expr

brush_expr is a Brush expression, such as MakeBrush( pattern, fgcolor, bgcolor ). (See MakeBrush(
) function for more information.) or a Brush variable.

Description
The Brush clause specifies a brush style―in other words, a set of color and pattern settings that
dictate the appearance of a filled object, such as a circle or rectangle. Brush is a clause, not a
complete MapBasic statement. Various object-related statements, such as Create Ellipse statement,
allow you to specify a brush value. The keyword Brush may be followed by an expression which
evaluates to a Brush value. This expression can be a Brush variable:

Brush br_var

or a call to a function which returns a Brush value:

Brush MakeBrush(64, CYAN, BLUE)

With some MapBasic statements (e.g., Set Map statement), the keyword Brush can be followed
immediately by the three parameters that define a Brush style (pattern, foreground color, and
background color) within parentheses:

Brush(64, CYAN, BLUE)

Some MapBasic statements take a Brush expression as a parameter (e.g., the name of a Brush
variable), rather than a full Brush clause (the keyword Brush followed by the name of a Brush
variable). The Alter Object statement is one example.
The following table summarizes the three components (pattern, foreground color, background color)
that define a Brush:

Component Description

pattern Integer value from 1 to 8 or from 12 to 186; see table below.

MapBasic 15.2 Reference 119

 A to Z MapBasic Language Reference

Component Description

foreground color Integer RGB color value; see RGB( ) function. The definitions file,
MAPBASIC.DEF, includes Define statements for BLACK, WHITE,
RED, GREEN, BLUE, CYAN, MAGENTA, and YELLOW.

background color Integer RGB color value.

To specify a transparent background, use pattern 3 or larger, and omit the background color from
the Brush clause. For example, specify Brush(5, BLUE) to see thin blue stripes with no background
fill color. Omitting the background parameter is like clearing the Background check box in MapInfo
Pro's Region Style dialog box.
To specify a transparent background when calling the MakeBrush( ) function specify -1 as the
background color.
The available patterns appear as follows. Pattern 2 produces a solid fill; pattern 1 produces no fill.

MapBasic 15.2 Reference 120

 A to Z MapBasic Language Reference

For a comprehensive list of fill patterns, see the MapInfo Pro Help―launch MapInfo Pro and open
the Help System and search for MapInfo Pro Fill Pattern Table.
See Also:
CurrentBrush( ) function, MakeBrush( ) function, Pen clause, Font clause, Symbol clause

Buffer() function
Purpose
Returns a region object that represents a buffer region (the area within a specified buffer distance
of an existing object). You can call this function from the MapBasic window in MapInfo Pro.

Syntax

Buffer( inputobject, resolution, width, unit_name )

inputobject is an object expression.

resolution is a SmallInt value representing the number of nodes per circle at each corner.
width is a float value representing the radius of the buffer; if width is negative, and if inputobject is
a closed object, the object returned represents an object smaller than the original object. If the width
is negative, and the object is a linear object (line, polyline, arc) or a point, then the absolute value
of width is used to produce a positive buffer.
unit_name is the name of the distance unit (e.g., "mi" for miles, "km" for kilometers) used by width.

Return Value
Returns a region object.

Description
The Buffer() function returns a region representing a buffer.
The Buffer() function operates on one single object at a time. To create a buffer around a set of
objects, use the Create Object statement As Buffer. The object will be created using the current
MapBasic coordinate system. The method used to calculate the buffer depends on the coordinate
system. If it is NonEarth, then a Cartesian method will be used. Otherwise, a spherical method will
be used.

MapBasic 15.2 Reference 121

 A to Z MapBasic Language Reference

Example
The following program creates a line object, then creates a buffer region surrounding the line. The
buffer region extends ten miles in all directions from the line.

Dim o_line, o_region As Object

o_line = CreateLine(-73.5, 42.5, -73.6, 42.8)
o_region = Buffer( o_line, 20, 10, "mi")

See Also:
Create Object statement, Set Buffer Version statement

ButtonPadInfo() function
Purpose
Returns information about a ButtonPad. You can call this function from the MapBasic window in
MapInfo Pro.

Syntax

ButtonPadInfo( pad_name, attribute )

pad_name is a string representing the name of an existing ButtonPad; use "Main", "Drawing", "Tools"
or "Standard" to query the standard pads, or specify the name of a custom pad.
attribute is a code indicating which information to return; see table below.

Return Value
Depends on the attribute parameter specified.

Description
The attribute parameter specifies what to return. Codes are defined in MAPBASIC.DEF

attribute code ID ButtonPadInfo() returns:

BTNPAD_INFO_FLOATING 1 Logical. TRUE means the pad is floating, FALSE means the pad is
docked.

BTNPAD_INFO_WIDTH 2 SmallInt: The width of the pad, expressed as a number of buttons

(not including separators).

BTNPAD_INFO_NBTNS 3 SmallInt. The number of buttons on the pad.

MapBasic 15.2 Reference 122

 A to Z MapBasic Language Reference

attribute code ID ButtonPadInfo() returns:

BTNPAD_INFO_X 4 A number indicating the x-position of the upper-left corner of the

pad. If the pad is docked, this is an integer. The value is negative
when a toolbar is docked to the left of the menu bar. If the pad is
floating, this is a float value, in paper units such as inches. For details
about paper units, see Set Paper Units statement.

BTNPAD_INFO_Y 5 A number indicating the y-position of the upper-left corner of the

pad. This value is negative when a toolbar is docked above the
menu bar.

BTNPAD_INFO_WINID 6 Integer. The window ID of the specified pad.

BTNPAD_INFO_DOCK_POSITION 7 Returns the position of the button pad as Floating, Left, Top, Right
or Bottom. Use for floating toolbars as an alternative to
BTNPAD_INFO_FLOATING. Returns:

• BTNPAD_INFO_DOCK_NONE (0)
• BTNPAD_INFO_DOCK_LEFT (1)
• BTNPAD_INFO_DOCK_TOP (2)
• BTNPAD_INFO_DOCK_RIGHT (3)
• BTNPAD_INFO_DOCK_BOTTOM (4)

Example

Include "mapbasic.def"
If ButtonPadInfo("Main", BTNPAD_INFO_FLOATING) Then
'...then the Main pad is floating; now let's dock it.
Alter ButtonPad "Main" ToolbarPosition(0,0) Fixed
End If

See Also:
Alter ButtonPad statement

Call statement
Purpose
Calls a sub procedure or an external routine (DLL, XCMD).

Restrictions
You cannot issue a Call statement through the MapBasic window.

MapBasic 15.2 Reference 123

 A to Z MapBasic Language Reference

Syntax

Call subproc [ ( [ parameter ] [ , ... ] ) ]

subproc is the name of a sub procedure.

parameter is a parameter expression to pass to the sub procedure.

Description
The Call statement calls a procedure. The procedure is usually a conventional MapBasic sub
procedure (defined through the Sub...End Sub statement). Alternately, a program running under
MapInfo Pro can call a Windows Dynamic Link Library (DLL) routine through the Call statement.
When a Call statement calls a conventional MapBasic procedure, MapBasic begins executing the
statements in the specified sub procedure, and continues until encountering an End Sub or an Exit
Sub statement. At that time, MapBasic returns from the sub procedure, then executes the statements
following the Call statement. The Call statement can only access sub procedures which are part of
the same application.
A MapBasic program must issue a Declare Sub statement to define the name and parameter list
of any procedure which is to be called. This requirement is independent of whether the procedure
is a conventional MapBasic Sub procedure, a DLL procedure or an XCMD.

Parameter Passing
Sub procedures may be defined with no parameters. If a particular sub procedure has no parameters,
then calls to that sub procedure may appear in either of the following forms:

Call subroutine

or

Call subroutine()

By default, each sub procedure parameter is defined "by reference." When a sub procedure has a
by-reference parameter, the caller must specify the name of a variable to pass as the parameter.
If the procedure then alters the contents of the by-reference parameter, the caller's variable is
automatically updated to reflect the change. This allows the caller to examine the results returned
by the sub procedure.
Alternately, any or all sub procedure parameters may be passed "by value" if the keyword ByVal
appears before the parameter name in the Sub and Declare Sub declarations. When a parameter
is passed by value, the sub procedure receives a copy of the value of the parameter expression;
thus, the caller can pass any expression, rather than having to pass the name of a variable.
A sub procedure can take an entire array as a single parameter. When a sub procedure expects
an array as a parameter, the caller should specify the name of an array variable, without parentheses.

MapBasic 15.2 Reference 124

 A to Z MapBasic Language Reference

Calling External Routines

When a Call statement calls a DLL routine, MapBasic executes the routine until the routine returns.
The specified DLL routine is actually located in a separate file (e.g., KERNEL.EXE). The specified
DLL file must be present at run-time for MapBasic to complete a DLL Call.
Similarly, if a Call statement calls an XCMD, the file containing the XCMD must be present at
run-time. When calling XCMDs, you cannot specify array variables or variables of custom data
Types as parameters.

Example
In the following example, the sub procedure Cube cubes a number (raises the number to the power
of three), and returns the result. The sub procedure takes two parameters; the first parameter
contains the number to be cubed, and the second parameter passes the results back to the caller.

Declare Sub Cube(ByVal original As Float, cubed As Float)

Dim x, result As Float
Call Cube( 2, result)
' result now contains the value: 8 (2 x 2 x 2)
x = 1
Call Cube( x + 2, result)
' result now contains the value: 27 (3 x 3 x 3)
End Program
Sub Cube (ByVal original As Float, cubed As Float)
' Cube the "original" parameter, and store
' the result in the "cubed" parameter.
cubed = original ^ 3
End Sub

See Also:
Declare Sub statement, Exit Sub statement, Global statement, Sub...End Sub statement

CartesianArea() function
Purpose
Returns the area as calculated in a flat, projected coordinate system using a Cartesian algorithm.
You can call this function from the MapBasic window in MapInfo Pro.

Syntax

CartesianArea( obj_expr, unit_name )

obj_expr is an object expression.

unit_name is a string representing the name of an area unit (e.g., "sq km").

MapBasic 15.2 Reference 125

 A to Z MapBasic Language Reference

Return Value
Float

Description
The CartesianArea() function returns the Cartesian area of the geographical object specified by
obj_expr.
The function returns the area measurement in the units specified by the unit_name parameter; for
example, to obtain an area in acres, specify "acre" as the unit_name parameter. See the Set Area
Units statement for the list of available unit names.
The CartesianArea() function will always return the area using a cartesian algorithm. A value of -1
will be returned for data that is in a Latitude/Longitude since the data is not projected.
Only regions, ellipses, rectangles, and rounded rectangles have any area. By definition, the
CartesianArea() of a point, arc, text, line, or polyline object is zero. The CartesianArea() function
returns approximate results when used on rounded rectangles. MapBasic calculates the area of a
rounded rectangle as if the object were a conventional rectangle.

Examples
The following example shows how the CartesianArea() function can calculate the area of a single
geographic object. Note that the expression tablename.obj (as in states.obj) represents the
geographical object of the current row in the specified table.

Dim f_sq_miles As Float

Open Table "counties"
Fetch First From counties
f_sq_miles = CartesianArea(counties.obj, "sq mi")

You can also use the CartesianArea() function within the Select statement, as shown in the
following example.

Select lakes, CartesianArea(obj, "sq km")

From lakes Into results

See Also:
Area() function, SphericalArea() function

CartesianBuffer() function
Purpose
Returns a region object that represents a buffer region (the area within a specified buffer distance
of an existing object). You can call this function from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 126

 A to Z MapBasic Language Reference

Syntax

CartesianBuffer( inputobject, resolution, width, unit_name )

inputobject is an object expression.

resolution is a SmallInt value representing the number of nodes per circle at each corner.
width is a float value representing the radius of the buffer; if width is negative, and if inputobject is
a closed object, the object returned represents an object smaller than the original object.
unit_name is the name of the distance unit (e.g., "mi" for miles, "km" for kilometers) used by width.

Return Value
Region Object

Description
The CartesianBuffer() function returns a region representing a buffer and operates on one single
object at a time.
To create a buffer around a set of objects, use the Create Object statement As Buffer. If width is
negative, and the object is a linear object (line, polyline, arc) or a point, then the absolute value of
width is used to produce a positive buffer.
The CartesianBuffer() function calculates the buffer by assuming the object is in a flat projection
and using the width to calculate a cartesian distance calculated buffer around the object.
If the inputobject is in a Latitude/Longitude Projection, then Spherical calculations will be used
regardless of the Buffer function used.

Example
The following program creates a line object, then creates a buffer region that extends 10 miles
surrounding the line.

Dim o_line, o_region As Object

o_line = CreateLine(-73.5, 42.5, -73.6, 42.8)
o_region = CartesianBuffer( o_line, 20, 10, "mi")

See Also:
Buffer() function, Creating Map Objects, Set Buffer Version statement

CartesianConnectObjects() function
Purpose
Returns an object representing the shortest or longest distance between two objects. You can call
this function from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 127

 A to Z MapBasic Language Reference

Syntax

CartesianConnectObjects( object1, object2, min )

object1 and object2 are object expressions.

min is a logical expression where TRUE calculates the minimum distance between the objects, and
FALSE calculates the maximum distance between objects.

Return Value
This statement returns a single section, two-point Polyline object representing either the closest
distance (min == TRUE) or farthest distance (min == FALSE) between object1 and object2.

Description
One point of the resulting Polyline object is on object1 and the other point is on object2. Note that
the distance between the two input objects can be calculated using the ObjectLen() function. If
there are multiple instances where the minimum or maximum distance exists (e.g., the two points
returned are not uniquely the shortest distance and there are other points representing "ties") then
these functions return one of the instances. There is no way to determine if the object returned is
uniquely the shortest distance.
CartesianConnectObjects() returns a Polyline object connecting object1 and object2 in the shortest
(min == TRUE) or longest (min == FALSE) way using a cartesian calculation method. If the calculation
cannot be done using a cartesian distance method (e.g., if the MapBasic Coordinate System is
Lat/Long), then this function will produce an error.

CartesianDistance() function
Purpose
Returns the distance between two locations. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

CartesianDistance( x1, y1, x2, y2, unit_name )

x1 and x2 are x-coordinates.

y1 and y2 are y-coordinates.
unit_name is a string representing the name of a distance unit (e.g., "km").

Return Value
Float

MapBasic 15.2 Reference 128

 A to Z MapBasic Language Reference

Description
The CartesianDistance() function calculates the Cartesian distance between two locations. It returns
the distance measurement in the units specified by the unit_name parameter; for example, to obtain
a distance in miles, specify "mi" as the unit_name parameter. See Set Distance Units statement
for the list of available unit names.
The CartesianDistance() function always returns a value using a cartesian algorithm. A value of
-1 is returned for data that is in a Latitude/Longitude coordinate system, since Latitude/Longitude
data is not projected and not cartesian.
The x- and y-coordinate parameters must use MapBasic's current coordinate system. By default,
MapInfo Pro expects coordinates to use a Latitude/Longitude coordinate system. You can reset
MapBasic's coordinate system through the Set CoordSys statement.

Example

Dim dist, start_x, start_y, end_x, end_y As Float

Open Table "cities"
Fetch First From cities
start_x = CentroidX(cities.obj)
start_y = CentroidY(cities.obj)
Fetch Next From cities
end_x = CentroidX(cities.obj)
end_y = CentroidY(cities.obj)
dist = CartesianDistance(start_x,start_y,end_x,end_y,"mi")

See Also:
Math Functions, CartesianDistance() function, Distance() function

CartesianObjectDistance() function
Purpose
Returns the distance between two objects. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

CartesianObjectDistance( object1, object2, unit_name )

object1 and object2 are object expressions.

unit_name is a string representing the name of a distance unit.

Return Value
Float

MapBasic 15.2 Reference 129

 A to Z MapBasic Language Reference

Description
CartesianObjectDistance() returns the minimum distance between object1 and object2 using a
cartesian calculation method with the return value in unit_name. If the calculation cannot be done
using a cartesian distance method (e.g., if the MapBasic Coordinate System is Lat/Long), then this
function will produce an error.

CartesianObjectLen() function
Purpose
Returns the geographic length of a line or polyline object. You can call this function from the
MapBasic window in MapInfo Pro.

Syntax

CartesianObjectLen( obj_expr, unit_name )

obj_expr is an object expression.

unit_name is a string representing the name of a distance unit (e.g., "km").

Return Value
Float

Description
The CartesianObjectLen() function returns the length of an object expression. Note that only line
and polyline objects have length values greater than zero; to measure the circumference of a
rectangle, ellipse, or region, use the Perimeter() function.
The CartesianObjectLen() function will always return a value using a cartesian algorithm. A value
of -1 will be returned for data that is in a Latitude/Longitude coordinate system, since
Latitude/Longitude data is not projected and not cartesian.
The CartesianObjectLen() function returns a length measurement in the units specified by the
unit_name parameter; for example, to obtain a length in miles, specify "mi" as the unit_name
parameter. See the Set Distance Units statement for the list of valid unit names.

Example

Dim geogr_length As Float

Open Table "streets"
Fetch First From streets
geogr_length = CartesianObjectLen(streets.obj, "mi")
' geogr_length now represents the length of the
' street segment, in miles

See Also:

MapBasic 15.2 Reference 130

 A to Z MapBasic Language Reference

SphericalObjectLen() function, CartesianObjectLen() function, ObjectLen() function

CartesianOffset() function
Purpose
Returns a copy of the input object offset by the specified distance and angle using a Cartesian
DistanceType. You can call this function from the MapBasic window in MapInfo Pro.

Syntax

CartesianOffset( object, angle, distance, units )

object is the object being offset.

angle is the angle to offset the object.
distance is the distance to offset the object.
units is a string representing the unit in which to measure distance.

Return Value
Object

Description
This function produces a new object that is a copy of the input object offset by distance along angle
(in degrees with horizontal in the positive X-axis being 0 and positive being counterclockwise). The
unit string, similar to that used for ObjectLen() function or Perimeter() function, is the unit for the
distance value. The DistanceType used is Cartesian. If the coordinate system of the input object is
Lat/Long, an error will occur, since Cartesian DistanceTypes are not valid for Lat/Long. This is
signified by returning a NULL object. The coordinate system used is the coordinate system of the
input object.
There are some considerations for Spherical measurements that do not hold for Cartesian
measurements. If you move an object that is in Lat/Long, the shape of the object remains the same,
but the area of the object will change. This is because you are picking one offset delta in degrees,
and the actual measured distance for a degree is different at different locations.
For the Offset functions, the actual offset delta is calculated at some fixed point on the object (e.g.,
the center of the bounding box), and then that value is converted from the input units into the
coordinate system's units. If the coordinate system is Lat/Long, the conversion to degrees uses the
fixed point. The actual converted distance measurement could vary at different locations on the
object. The distance from the input object and the new offset object is only guaranteed to be exact
at the single fixed point used.

MapBasic 15.2 Reference 131

 A to Z MapBasic Language Reference

Example

CartesianOffset(Rect, 45, 100, "mi")

See Also:
CartesianOffsetXY() function

CartesianOffsetXY() function
Purpose
Returns a copy of the input object offset by the specified X and Y offset values using a cartesian
DistanceType. You can call this function from the MapBasic window in MapInfo Pro.

Syntax

CartesianOffsetXY( object, xoffset, yoffset, units )

object is the object being offset.

xoffset and yoffset are the distance along the x and y axes to offset the object.
units is a string representing the unit in which to measure distance.

Return Value
Object

Description
This function produces a new object that is a copy of the input object offset by xoffset along the
X-axis and yoffset along the Y-axis. The unit string, similar to that used for ObjectLen() function
or Perimeter() function, is the unit for the distance values. The DistanceType used is Cartesian.
If the coordinate system of the input object is Lat/Long, an error will occur, since Cartesian
DistanceTypes are not valid for Lat/Long. This is signified by returning a NULL object. The coordinate
system used is the coordinate system of the input object.
There are some considerations for Spherical measurements that do not hold for Cartesian
measurements. If you move an object that is in Lat/Long, the shape of the object remains the same,
but the area of the object will change. This is because you are picking one offset delta in degrees,
and the actual measured distance for a degree is different at different locations.
For the Offset functions, the actual offset delta is calculated at some fixed point on the object (e.g.,
the center of the bounding box), and then that value is converted from the input units into the
coordinate system's units. If the coordinate system is Lat/Long, the conversion to degrees uses the
fixed point. The actual converted distance measurement could vary at different locations on the
object. The distance from the input object and the new offset object is only guaranteed to be exact
at the single fixed point used.

MapBasic 15.2 Reference 132

 A to Z MapBasic Language Reference

Example

CartesianOffset(Rect, 45, 100, "mi")

See Also:
CartesianOffset() function

CartesianPerimeter() function
Purpose
Returns the perimeter of a graphical object. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

CartesianPerimeter( obj_expr , unit_name )

obj_expr is an object expression.

unit_name is a string representing the name of a distance unit (e.g., "km").

Return Value
Float

Description
The CartesianPerimeter() function calculates the perimeter of the obj_expr object. The Perimeter()
function is defined for the following object types: ellipses, rectangles, rounded rectangles, and
polygons. Other types of objects have perimeter measurements of zero.
The CartesianPerimeter() function will always return a value using a Cartesian algorithm. A value
of -1 will be returned for data that is in a Latitude/Longitude coordinate system, since
Latitude/Longitude data is not projected and not Cartesian.
The CartesianPerimeter() function returns a length measurement in the units specified by the
unit_name parameter; for example, to obtain a length in miles, specify "mi" as the unit_name
parameter. See the Set Distance Units statement for the list of valid unit names.
CartesianPerimeter() returns approximate results when used on rounded rectangles. MapBasic
calculates the perimeter of a rounded rectangle as if the object were a conventional rectangle.

MapBasic 15.2 Reference 133

 A to Z MapBasic Language Reference

Example
The following example shows how you can use the CartesianPerimeter() function to determine the
perimeter of a particular geographic object.

Dim perim As Float

Open Table "world"
Fetch First From world
perim = CartesianPerimeter(world.obj, "km")
' The variable perim now contains
' the perimeter of the polygon that's attached to
' the first record in the World table.

You can also use the CartesianPerimeter() function within the Select statement. The following
Select statement extracts information from the States table, and stores the results in a temporary
table called Results. Because the Select statement includes the CartesianPerimeter() function,
the Results table will include a column showing each state's perimeter.

Open Table "states"

Select state, CartesianPerimeter(obj, "mi")
From states
Into results

See Also:
CartesianPerimeter() function, SphericalPerimeter() function, Perimeter() function

Centroid() function
Purpose
Returns the centroid (center point) of an object. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

Centroid( obj_expr )

obj_expr is an object expression.

Return Value
Point object

Description
The Centroid() function returns a point object, which is located at the centroid of the specified
obj_expr object. A region's centroid does not represent its center of mass. Instead, it represents the
location used for automatic labeling, geocoding, and placement of thematic pie and bar charts. If
you edit a map in reshape mode, you can reposition region centroids by dragging them.

MapBasic 15.2 Reference 134

 A to Z MapBasic Language Reference

If the obj_expr parameter represents a point object, the Centroid() function returns the position of
the point. If the obj_expr parameter represents a line object, the Centroid() function returns the
point midway between the ends of the line.
If the obj_expr parameter represents a polyline object, the Centroid() function returns a point located
at the mid point of the middle segment of the polyline.
If the obj_expr parameter represents any other type of object, the Centroid() function returns a point
located at the true centroid of the original object. For rectangle, arc, text, and ellipse objects, the
centroid position is halfway between the upper and lower extents of the object, and halfway between
the left and right extents. For region objects, however, the centroid position is always on the object
in question, and therefore may not be located halfway between the object's extents.

Example

Dim pos As Object

Open Table "world"
Fetch First From world
pos = Centroid(world.obj)

See Also:
Alter Object statement, CentroidX() function, CentroidY() function

CentroidX() function
Purpose
Returns the x-coordinate of the centroid of an object. You can call this function from the MapBasic
window in MapInfo Pro.

Syntax

CentroidX( obj_expr )

obj_expr is an object expression

Return Value
Float

Description
The CentroidX() function returns the X coordinate (e.g., Longitude) component of the centroid of
the specified object. See the Centroid() function for a discussion of what the concept of a centroid
position means with respect to different types of graphical objects (lines vs. regions, etc.).

MapBasic 15.2 Reference 135

 A to Z MapBasic Language Reference

The coordinate information is returned in MapBasic's current coordinate system; by default, MapBasic
uses a Longitude/Latitude coordinate system. The Set CoordSys statement allows you to change
the coordinate system used.

Examples
The following example shows how the CentroidX() function can calculate the longitude of a single
geographic object.

Dim x As Float
Open Table "world"
Fetch First From world
x = CentroidX(world.obj)

You can also use the CentroidX() function within the Select statement. The following Select
statement extracts information from the World table, and stores the results in a temporary table
called Results. Because the Select statement includes the CentroidX() function and the CentroidY()
function, the Results table will include columns which display the longitude and latitude of the
centroid of each country.

Open Table "world"

Select country, CentroidX(obj), CentroidY(obj)
From world Into results

See Also:
Centroid() function, CentroidY() function, Set CoordSys statement

CentroidY() function
Purpose
Returns the y-coordinate of the centroid of an object. You can call this function from the MapBasic
window in MapInfo Pro.

Syntax

CentroidY( obj_expr )

obj_expr is an object expression.

Return Value
Float

MapBasic 15.2 Reference 136

 A to Z MapBasic Language Reference

Description
The CentroidY() function returns the Y-coordinate (e.g., latitude) component of the centroid of the
specified object. See the Centroid() function for a discussion of what the concept of a centroid
position means, with respect to different types of graphical objects (lines vs. regions, etc.).
The coordinate information is returned in MapBasic's current coordinate system; by default, MapBasic
uses a Longitude/Latitude coordinate system. The Set CoordSys statement allows you to change
the coordinate system used.

Example

Dim y As Float
Open Table "world"
Fetch First From world
y = CentroidY(world.obj)

See Also:
Centroid() function, CentroidX() function, Set CoordSys statement

CharSet clause
Purpose
Specifies which character set MapBasic uses for interpreting character codes.
Note: See the MapInfo Pro User Guide for changes affecting this clause.

Syntax

CharSet char_set

char_set is a string that identifies the name of a character set; see table below.

Description
The CharSet clause specifies which character set MapBasic should use when reading or writing
files or tables. Note that CharSet is a clause, not a complete statement. Various file-related
statements, such as the Open File statement, can incorporate optional CharSet clauses.

What Is A Character Set?

Every character on a computer keyboard corresponds to a numeric code. For example, the letter
"A" corresponds to the character code 65. A character set is a set of characters that appear on a
computer, and a set of numeric codes that correspond to those characters.
Different character sets are used in different countries. For example, in the version of Windows for
North America and Western Europe, character code 176 corresponds to a degrees symbol; however,

MapBasic 15.2 Reference 137

 A to Z MapBasic Language Reference

if Windows is configured to use a different character set, character code 176 may represent a
different character.
Call SystemInfo(SYS_INFO_CHARSET) to determine the character set in use at run-time.

How Do Character Sets Affect MapBasic Programs?

If your files use only standard ASCII characters in the range of 32 (space) to 126 (tilde), you do not
need to worry about character set conflicts, and you do not need to use the CharSet clause.
Even if your files include "special" characters (for example, characters outside the range 32 to 126),
if you do all of your work within one environment (e.g., Windows) using only one character set, you
do not need to use the CharSet clause.
If your program needs to read an existing file that contains "special" characters, and if the file was
created in a character set that does not match the character set in use when you run your program,
your program should use the CharSet clause. The CharSet clause should indicate what character
set was in use when the file was created.
The CharSet clause takes one parameter: a string expression which identifies the name of the
character set to use. The following table lists all character sets available.

Character Set Comments

"Neutral" No character conversions performed.

"ISO8859_1" ISO 8859-1 (UNIX)

"ISO8859_2" ISO 8859-2 (UNIX)

"ISO8859_3" ISO 8859-3 (UNIX)

"ISO8859_4" ISO 8859-4 (UNIX)

"ISO8859_5" ISO 8859-5 (UNIX)

"ISO8859_6" ISO 8859-6 (UNIX)

"ISO8859_7" ISO 8859-7 (UNIX)

"ISO8859_8" ISO 8859-8 (UNIX)

"ISO8859_9" ISO 8859-9 (UNIX)

"PackedEUCJapanese" UNIX, standard Japanese implementation.

MapBasic 15.2 Reference 138

 A to Z MapBasic Language Reference

Character Set Comments

Windows Eastern Europe

"WindowsLatin2"
"WindowsArabic"
"WindowsCyrillic"
"WindowsGreek"
"WindowsHebrew"
"WindowsTurkish"

"WindowsTradChinese" Windows Traditional Chinese

"WindowsSimpChinese" Windows Simplified Chinese

"WindowsJapanese"

"WindowsKorean"

"CodePage437" DOS Code Page 437 = IBM Extended ASCII

"CodePage850" DOS Code Page 850 = Multilingual

"CodePage852" DOS Code Page 852 = Eastern Europe

"CodePage855" DOS Code Page 855 = Cyrillic

"CodePage857"

"CodePage860" DOS Code Page 860 = Portuguese

"CodePage861" DOS Code Page 861 = Icelandic

"CodePage863" DOS Code Page 863 = French Canadian

"CodePage864" DOS Code Page 864 = Arabic

"CodePage865" DOS Code Page 865 = Nordic

"CodePage869" DOS Code Page 869 = Modern Greek

MapBasic 15.2 Reference 139

 A to Z MapBasic Language Reference

Character Set Comments

"LICS" Lotus worksheet release 1,2 character set

"LMBCS" Lotus worksheet release 3,4 character set

"Utf-8" Workspace, Native Extended, and Non-Native character set

"Utf-16" Native Extended format character set

Note: You never need to specify a CharSet clause in an Open Table statement. Each table's
.TAB file contains information about the character set used by the table. When opening a
table, MapInfo Pro reads the character set information directly from the .TAB file, then
automatically performs any necessary character translations.

Specify "Utf-8" for a workspace character set or Native Extended (NativeX) format table character
set to allow characters from any language to be represented. It can also be used when importing,
opening or registering a non-native table.
To force MapInfo Pro to save a table in a specific character set, include a CharSet clause in the
Commit Table statement.
See Also:
Commit Table statement, Create Table statement, Export statement, Open File statement,
Register Table statement, Character Code Table Definitions

ChooseProjection$() function
Purpose
Displays the Choose Projection dialog box and returns the coordinate system selected by the user.
You can call this function from the MapBasic window in MapInfo Pro.

Syntax

ChooseProjection$( initial_coordsys, get_bounds )

initial_coordsys is a string value in the form of a CoordSys clause. It is used to set which coordinate
system is selected when the dialog box is first displayed. If initial_coordsys is empty or an invalid
CoordSys clause, then the default Longitude/Latitude coordinate system is used as the initial
selection.
get_bounds is a logical value that determines whether the users is prompted for boundary values
when a non-earth projection is selected. If get_bounds is true then the boundary dialog box is
displayed. If false, then the dialog box is not displayed and the default boundary is used.

MapBasic 15.2 Reference 140

 A to Z MapBasic Language Reference

Description
This function displays the Choose Projection dialog box and returns the selected coordinate system
as a string. The returned string is in the same format as the CoordSys clause. Use this function if
you wish to allow the user to set a projection within your application.

Example

Dim strNewCoordSys As String

strNewCoordSys = ChooseProjection$( "", True)
strNewCoordSys = "Set " + strNewCoordSys
Run Command strNewCoordSys

See Also:
MapperInfo() function

CharVal() function
Purpose
Returns the character code for the first character in a string expression. This function is the Unicode
corollary of the Asc() function, so that the return value maps to the Unicode character set encoding
of the string expression (string_expr), rather than the system character set mapping. You can call
this function from the MapBasic window in MapInfo Pro.

Syntax

CharVal( string_expr )

string_expr is a string expression.

Return Value
Integer

Description
The CharVal() function returns the character code representing the first character in the string
specified by the string expression, string_expr. If string_expr is a null string, then CharVal() returns
a value of zero.
Note: Except for the character encoding mapping, the usage and behavior of CharVal() is the
same as Asc() function.

CharVal() is only applicable for Unicode versions of MapInfoPro and returns a value of zero for
non-Unicode versions of MapInfo Pro.

MapBasic 15.2 Reference 141

 A to Z MapBasic Language Reference

Example
The following example displays the corresponding Unicode encoding for the character, which will
be 8364, 1587, and 24330:

Dim code As SmallInt

code = CharVal("€")
code = CharVal("‫)"س‬
code = CharVal(" ")

See Also:
Asc() function, ChrU$() function, Character Code Table Definitions

Chr$() function
Purpose
Returns a one-character string corresponding to a specified character code. You can call this function
from the MapBasic window in MapInfo Pro.

Syntax

Chr$( num_expr )

num_expr is an integer value from 0 to 255 (or, if a double-byte character set is in use, from 0 to
65,535), inclusive.

Return Value
String

Description
The Chr$() function returns a string, one character long, based on the character code specified in
the num_expr parameter. On most systems, num_expr should be a positive integer value between
0 and 255. On systems that support double-byte character sets (e.g., Windows Japanese), num_expr
can have a value from 0 to 65,535.
Note: All MapInfo Pro environments have common character codes within the range of 32 (space)
to 126 (tilde).

If the num_expr parameter is fractional, MapBasic rounds to the nearest integer.

Character 12 is the form-feed character. Thus, you can use the statement Print Chr$(12) to clear
the Message window. Character 10 is the line-feed character; see example below.
Character 34 is the double-quotation mark ("). If a string expression includes the function call
Chr$(34), MapBasic embeds a double-quote character in the string.

MapBasic 15.2 Reference 142

 A to Z MapBasic Language Reference

In Unicode versions of MapInfo Pro, this function operates in the system character set in a compatible
manner with the non-Unicode versions of MapInfo Pro.

Error Conditions
ERR_FCN_ARG_RANGE (644) error is generated if an argument is outside of the valid range.

Example

Dim s_letter As String * 1

s_letter = Chr$(65)
Note s_letter ' This displays the letter "A"
Note "This message spans" + Chr$(10) + "two lines."

See Also:
Asc() function, ChrU$() function, Character Code Table Definitions

ChrU$() function
Purpose
Returns a one-character string corresponding to a specified character code. This function is the
Unicode corollary of the Chr$() function, so that the num_expr encoding maps to the Unicode
character codes rather than the system environment character codes. You can call this function
from the MapBasic window in MapInfo Pro.

Syntax

ChrU$( num_expr )

num_expr is an integer value from 0 to 65,535, inclusive.

Return Value
String

Description
The ChrU$() function returns a string, one character long, based on the character code specified
in the num_expr parameter.
Note: Except for the character encoding mapping, the usage and behavior of ChrU$() is the same
as Chr$(). ChrU$() is only applicable for Unicode version of MapInfo Pro and returns a
[space] character in non-Unicode MapInfo Pro.

MapBasic 15.2 Reference 143

 A to Z MapBasic Language Reference

Example
The following example displays the Unicode character "€", the Unicode Arabic character "‫"س‬, and
the Unicode Traditional Chinese character " ":

Note ChrU$(8364)
Note ChrU$(1587)
Note ChrU$(24330)

See Also:
CharVal() function, Chr$() function, Character Code Table Definitions

Close All statement

Purpose
Closes all open tables. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Close All [ Interactive ]

Description
If a MapBasic application issues a Close All statement, and the affected table has edits pending
(the table has been modified but the modifications have not yet been saved to disk), the edits will
be discarded before the table is closed. No warning will be displayed. If you do not want to discard
pending edits, use the optional Interactive clause to prompt the user to save or discard changes.
See Also:
Close Table statement

Close Connection statement

Purpose
Closes a connection opened with the Open Connection statement. You can issue this statement
from the MapBasic window in MapInfo Pro.

Syntax

Close Connection connection_handle

connection_handle is an integer expression representing the value returned from the Open
Connection statement.

MapBasic 15.2 Reference 144

 A to Z MapBasic Language Reference

Description
The Close Connection statement closes the specified connection using the connection handle that
is returned from an Open Connection statement. Any service specific properties associated with
the connection are lost.
See Also:
Open Connection statement

Close File statement

Purpose
Closes an open file.

Syntax

Close File [ # ] filenum

filenum is an integer number identifying which file to close.

Description
The Close File statement closes a file which was opened through the Open File statement.
Note: The Open File statement and Close File statement operate on files in general, not on
MapInfo Pro tables. MapBasic provides a separate set of statements (e.g., Open Table
statement) for manipulating MapInfo tables.

Example

Open File "cxdata.txt" For INPUT As #1

'
' read from the file... then, when done:
'
Close File #1

See Also:
Open File statement

Close Table statement

Purpose
Closes an open table. You can issue this statement from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 145

 A to Z MapBasic Language Reference

Syntax

Close Table table [ Interactive ]

table is the name of a table that is open

Description
The Close Table statement closes an open table. To close all tables, use the Close All statement.
If a table is displayed in one or more Grapher or Browser windows, those windows disappear
automatically when the table is closed. If the Close Table statement closes the only table in a Map
window, the window closes. If you use the Close Table statement to close a linked table that has
edits pending, MapInfo Pro keeps the edits pending until a later session.

Saving Edits
If you omit the optional Interactive keyword, MapBasic closes the table regardless of whether the
table has unsaved edits; any unsaved edits are discarded. If you include the Interactive keyword,
and if the table has unsaved edits, MapBasic displays a dialog box allowing the user to save or
discard the edits or cancel the close operation.
To guarantee that pending edits are discarded, omit the Interactive keyword or issue a Rollback
statement before calling Close Table. To guarantee that pending edits are saved, issue a Commit
Table statement before the Close Table statement. To determine whether a table has unsaved
edits, call the TableInfo() function( table, TAB_INFO_EDITED) function.

Saving Themes and Cosmetic Objects

When you close the last table in a Map window, the window closes. However, the user may want
to save thematic layers or cosmetic objects before closing the window. To prompt the user to save
themes or cosmetic objects, include the Interactive keyword.
If you omit the Interactive keyword, the Close Table statement will not prompt the user to save
themes or cosmetic objects. If you include the Interactive keyword, dialog boxes will prompt the
user to save themes and/or cosmetic objects, if such prompts are appropriate. (The user is not
prompted if the window has no themes or cosmetic objects.)

Examples

Open Table "world"

' ... when done using the WORLD table,
' close it by saying:
Close Table world

To deselect the selected rows, close the Selection table.

Close Table Selection

See Also:

MapBasic 15.2 Reference 146

 A to Z MapBasic Language Reference

Close All statement, Commit Table statement, Open Table statement, Rollback statement,
TableInfo() function

Close Window statement

Purpose
Closes or hides a window. You can issue this statement from the MapBasic window in MapInfo
Pro.

Syntax

Close Window window_spec [ Interactive ]

window_spec is a window name (e.g., Ruler), a window code (e.g., WIN_RULER), or an integer
window identifier.

Description
The Close Window statement closes or hides a MapInfo Pro window.
To close a document window (Map, Browser, Layout, Graph), specify an integer window identifier
as the window_spec parameter. You can obtain integer window identifiers through the FrontWindow()
function and the WindowID() function.
To close a special MapInfo Pro window, specify one of the window names from the table below as
the window_spec parameter. You can identify a special window by name (e.g., Ruler) or by code
(e.g., WIN_RULER).
To close an adornment window, specify the window ID of the adornment as determined by the
MapperInfo() function.
The following table lists the available window_spec values:

value Window Description

Help The Help window (WIN_HELP).

Info The Info Tool window (WIN_INFO).

LayerControl The Layer Control window (WIN_LAYER_CONTROL). In an integrated mapping

application, this refers to the modal version.

Legend The Theme Legend window (WIN_LEGEND).

MapBasic The MapBasic window (WIN_MAPBASIC).

MapBasic 15.2 Reference 147

 A to Z MapBasic Language Reference

value Window Description

Message The Message window used by the Print statement (WIN_MESSAGE).

MoveMapTo The Move Map To window (WIN_MOVE_MAP_TO).

Ruler The Ruler tool window (WIN_RULER).

Statistics The Statistics window (WIN_STATISTICS).

TableList The Table List window (WIN_TABLE_LIST). In an integrated mapping application, this
refers to the modal version.

Note: The window IDs for Table List, Layer Control, and Move Map To windows are ignored by
the Set Window statement, WindowInfo() function, and WindowID() function.

Saving Themes and Cosmetic Objects

The user may want to save thematic layers or cosmetic objects before closing the window. To prompt
the user to save themes or cosmetic objects, include the Interactive keyword.
If you omit the Interactive keyword, the Close Window statement will not prompt the user to save
themes or cosmetic objects. If you include the Interactive keyword, dialog boxes will prompt the
user to save themes and/or cosmetic objects, if such prompts are appropriate. (The user will not be
prompted if the window has no themes or cosmetic objects.)

Example

Close Window Legend

See Also:
Open Window statement, Print statement, Set Window statement

ColumnInfo() function
Purpose
Returns information about a column in an open table. You can call this function from the MapBasic
window in MapInfo Pro.

Syntax

ColumnInfo( { tablename | tablenum } ,

{ columnname | "COLn" } , attribute )

MapBasic 15.2 Reference 148

 A to Z MapBasic Language Reference

tablename is a string representing the name of an open table.

tablenum is an integer representing the number of an open table.
columnname is the name of a column in that table.
n is the number of a column in the table.
attribute is a code indicating which aspect of the column to read.

Return Value
Depends on the attribute parameter specified.

Description
The ColumnInfo() function returns information about one column in an open table.
The function's first parameter specifies either the name or the number of an open table. The second
parameter specifies which column to query. The attribute parameter dictates which of the column's
attributes the function should return. The attribute parameter can be any value from this table.

attribute setting ID ColumnInfo() returns:

COL_INFO_NAME 1 String identifying the column name.

COL_INFO_NUM 2 SmallInt indicating the number of the column.

COL_INFO_TYPE 3 SmallInt indicating the column type (see table below).

COL_INFO_WIDTH 4 SmallInt indicating the column width; applies to Character or Decimal

columns only.

COL_INFO_DECPLACES 5 SmallInt indicating the number of decimal places in a Decimal

column.

COL_INFO_INDEXED 6 Logical value indicating if column is indexed.

COL_INFO_EDITABLE 7 Logical value indicating if column is editable.

If the ColumnInfo() function call specifies COL_INFO_TYPE as its attribute parameter, MapBasic
returns one of the values from the table below:

MapBasic 15.2 Reference 149

 A to Z MapBasic Language Reference

ColumnInfo() returns: ID Type of column indicated:

COL_TYPE_CHAR 1 Character.

COL_TYPE_DECIMAL 2 Fixed-point decimal.

COL_TYPE_INTEGER 3 Integer (4-byte).

COL_TYPE_SMALLINT 4 Small integer (2-byte).

COL_TYPE_DATE 5 Date.

COL_TYPE_LOGICAL 6 Logical (TRUE or FALSE).

COL_TYPE_GRAPHIC 7 special column type Obj; this represents the graphical objects
attached to the table.

COL_TYPE_FLOAT 8 Floating-point decimal.

COL_TYPE_TIME 37 Time.

COL_TYPE_DATETIME 38 DateTime.

The codes listed in both of the above tables are defined in the standard MapBasic definitions file,
MAPBASIC.DEF. Your program must include "MAPBASIC.DEF" if you intend to reference these
codes.

Error Conditions
ERR_TABLE_NOT_FOUND (405) error generated if the specified table is not available.
ERR_FCN_ARG_RANGE (644) error generated if an argument is outside of the valid range.

Example

Include "MAPBASIC.DEF"
Dim s_col_name As String, i_col_type As SmallInt
Open Table "world"
s_col_name = ColumnInfo("world","col1",COL_INFO_NAME)
i_col_type = ColumnInfo("world","col1",COL_INFO_TYPE)

See Also:
NumCols() function, TableInfo() function

MapBasic 15.2 Reference 150

 A to Z MapBasic Language Reference

Combine() function
Purpose
Returns a region or polyline representing the union of two objects. The objects cannot be Text
objects. You can call this function from the MapBasic window in MapInfo Pro.

Syntax

Combine( object1, object2 )

object1, object2 are two object expressions; both objects can be closed (e.g., a region and a circle),
or both objects can be linear (e.g., a line and a polyline)

Return Value
An object that is the union of object1 and object2.

Description
The Combine() function returns an object representing the geographical union of two object
expressions. The union of two objects represents the entire area that is covered by either object.
The Combine() function has been updated to allow heterogeneous combines, and to allow Points,
MultiPoints, and Collections as input objects. Previously, both objects had to be either linear objects
(Lines, Polylines, or Arcs) and produce Polylines as output; or both input objects had to be closed
(Regions, Rectangles, Rounded Rectangles, or Ellipses) and produce Regions as output.
Heterogeneous combines are not allowed, as are combines containing Point, MultiPoint and Collection
objects. Text objects are still not allowed as input to Combine().
MultiPoint and Collection objects, introduced in MapInfo Pro 6.5, extend the Combine operation.
The following table details the possible combine options available and the output results:

Input Object Type Input Object Type OutputObject Type

Point or MultiPoint Point or MultiPoint MultiPoint

Linear (Line, Polyline, Arc) Linear Polyline

Closed (Region, Rectangle, Rounded Closed Region

Rectangle, Ellipse)

Point, MultiPoint, Linear, Closed, Point, MultiPoint, Linear, Closed, Collection

Collection Collection

MapBasic 15.2 Reference 151

 A to Z MapBasic Language Reference

The results returned by Combine() are similar to the results obtained by choosing MapInfo Pro's
Combine command (on the SPATIAL tab), except that the Combine command modifies the original
objects; the Combine() function does not alter the object1 or object2 expressions. Also, the
Combine() function does not perform data aggregation.
The object returned by the Combine() function retains the styles (e.g., color) of the object1 parameter
when possible. Collection objects produced as output will get those portions of style that are possible
from object1, and the remaining portions of style from objects2. For example, if object1 is a Region
and object2 is a Polyline, then the output collection will use the brush and border pen of object1 for
the Region style contained in the collection, and the pen from object2 for the Polyline style in the
collection.
See Also:
Brush clause, Objects Combine statement, Pen clause, Set Combine Version statement

CommandInfo() function
Purpose
Returns information about recent events. You can call this function from the MapBasic window in
MapInfo Pro.

Syntax

CommandInfo( attribute )

attribute is an integer code indicating what type of information to return.

Return Value
Logical, float, integer, or string, depending on circumstances.

Description
The CommandInfo() function returns information about recent events that affect MapInfo Pro―for
example, whether the "Selection" table has changed, where the user clicked with the mouse, or
whether it was a simple click or a Shift+click.

After Displaying a Dialog Box

When you call CommandInfo() after displaying a custom dialog box, the attribute parameter can
be one of these codes:

MapBasic 15.2 Reference 152

 A to Z MapBasic Language Reference

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_DLG_OK 1 Logical value: TRUE if the user dismissed a custom dialog box by
clicking OK; FALSE if user canceled by clicking Cancel, pressing
Esc. (This call is only valid following a Dialog statement.)

CMD_INFO_STATUS 1 Logical value: TRUE if the user allowed a progress-bar operation

to complete, or FALSE if the user pressed the Cancel button to halt.

Within a Custom Menu or Dialog Handler

When you call CommandInfo() from within the handler procedure for a custom menu command or
a custom dialog box, the attribute parameter can be one of these codes:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_DLG_DBL 1 Logical value: TRUE if the user double-clicked on a ListBox or

MultiListBox control within a custom dialog box. This call is only
valid within the handler procedure of a custom dialog box.

CMD_INFO_MENUITEM 8 Integer value, representing the ID of the menu item the user chose.
This call is only valid within the handler procedure of a custom menu
item.

Within a Standard Handler Procedure

When you call CommandInfo() from within a standard system handler procedure (such as
SelChangedHandler), the attribute parameter can be any of the codes from the following table. For
details, see the separate discussions of SelChangedHandler, RemoteMsgHandler procedure,
WinChangedHandler and WinClosedHandler. From within SelChangedHandler:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_SELTYPE 1
1 if one row was added to the selection;
2 if one row was removed from the selection;
3 if multiple rows were added to the selection;
4 if multiple rows were de-selected.

CMD_INFO_ROWID 2 Integer value: The number of the row that was selected or
de-selected (only applies if a single row was selected or
de-selected).

MapBasic 15.2 Reference 153

 A to Z MapBasic Language Reference

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_INTERRUPT 3 Logical value: TRUE if the user interrupted a selection by pressing

Esc, FALSE otherwise.

From within the RemoteMsgHandler procedure, the RemoteQueryHandler() function, or the

RemoteMapGenHandler procedure:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_MSG 1000 String value, representing the execute string or the item name sent
to MapInfo Pro by a client program. For details, see
RemoteMsgHandler procedure, RemoteQueryHandler() function,
or RemoteMapGenHandler procedure.

From within WinChangedHandler procedure or WinClosedHandler procedure:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_WIN 1 Integer value, representing the ID of the window that changed or

the window that closed. For details, see WinChangedHandler
procedure or WinClosedHandler procedure.

From within ForegroundTaskSwitchHandler procedure:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_TASK_SWITCH 1 Integer value, indicating whether MapInfo Pro just became the active
application or just stopped being the active application. The return
value matches one of these codes: SWITCHING_INTO_MI Pro (If
MapInfo Pro received the focus) SWITCHING_OUT_OF_MapInfo
Pro (If MapInfo Pro lost the focus).

After a Find Operation

Following a Find statement, the attribute parameter can be one of these codes:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_X or CMD_INFO_Y 1, 2 Floating-point number, indicating x- or y-coordinates of the location

that was found.

MapBasic 15.2 Reference 154

 A to Z MapBasic Language Reference

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_FIND_RC 3 Integer value, indicating whether the Find statement found a match.

CMD_INFO_FIND_ROWID 4 Integer value, indicating the Row ID number of the row that was
found.

Within a Custom ToolButton's Handler Procedure

Within a custom ToolHandler procedure, you can specify any of these codes:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_CUSTOM_OBJ 1 Object value: a polyline or polygon drawn by the user. Applies to

drawing modes DM_CUSTOM_POLYLINE or
DM_CUSTOM_POLYGON.

CMD_INFO_X 1 x coordinate of the spot where the user clicked:

• If the user clicked on a Map, the return value represents a map

coordinate (e.g., longitude), in the current coordinate system unit.
• If the user clicked on a Browser, the value represents the number
of a column in the Browser (e.g., one for the left most column, or
zero for the select-box column).*
• If the user clicked in a Layout, the value represents the distance
from the left edge of the Layout (e.g., zero represents the left
edge), in MapBasic's current paper units. For details about paper
units, see Set Paper Units statement.

CMD_INFO_Y 2 y-coordinate of the spot where the user clicked:

• If the user clicked on a map, the value represents a map

coordinate (e.g., Latitude).
• If the user clicked on a Browser, the value represents a row
number; a value of one represents the top row, and a value of
zero represents the row of column headers at the top of the
window.*
• If the user clicked on a Layout, the value represents the distance
from the top edge of the Layout.

CMD_INFO_SHIFT 3 Logical value: TRUE if the user held down the Shift key while
clicking.

CMD_INFO_CTRL 4 Logical value: TRUE if the user held down the Ctrl key while clicking.

MapBasic 15.2 Reference 155

 A to Z MapBasic Language Reference

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_X2 5 x-coordinate of the spot where the user released the mouse button.
This only applies if the toolbutton was defined with a draw mode
that allows dragging, e.g., DM_CUSTOM_LINE.

CMD_INFO_Y2 6 y-coordinate of the spot where the user released the mouse button.

CMD_INFO_TOOLBTN 7 Integer value, representing the ID of the button the user clicked

* The CommandInfo() function ignores any clicks made in the top-left corner of a Browser
window―above the select column and to the left of the column headers. It also ignores clicks made
beyond the last column or row.

Hotlink Support
MapBasic applications launched via the Hotlink Tool can use the CommandInfo() function to obtain
information about the object that was activated. The following is a table of the attributes that can be
queried:

attribute code ID CommandInfo( attribute ) returns:

CMD_INFO_HL_WINDOW_ID 17 ID of map or browser window.

CMD_INFO_HL_TABLE_NAME 18 Name of table associated with the map layer or browser.

CMD_INFO_HL_ROWID 19 ID of the table row corresponding to the map object or browser row.

CMD_INFO_HL_LAYER_ID 20 Layer ID, if the program was launched from a map window.

CMD_INFO_HL_FILE_NAME 21 Name of file launched.

See Also:
FrontWindow() function, SelectionInfo() function, Set Command Info statement, WindowInfo()
function

Commit Table statement

Purpose
Saves recent edits to disk, or saves a copy of a table. In the past, you were unable to save queries
that contained indeterminate types, such as often occurred in ObjectInfo queries. We have added

MapBasic 15.2 Reference 156

 A to Z MapBasic Language Reference

an Interactive parameter to allow you to specify indeterminate types in such a query. If you do not
use the interactive parameter, the system uses a default type instead. You can issue this statement
from the MapBasic window in MapInfo Pro.

Syntax

Commit Table table

[ As filespec
[ Type { NATIVE [ Charset char_set ] |
NATIVEX [ Charset char_set ] [ Locale locale ] |
DBF [ Charset char_set ] |
Access Database database_filespec Version version Table tablename
[ Password pwd ] [ Charset char_set ] |
QUERY |
ODBC Connection ConnectionNumber Table tablename
[ Type SQLServerSpatial { Geometry | Geography } ]
[ ConvertDateTime { ON | OFF | INTERACTIVE } ] |
GPKG [ Database database_filespec ] [ Table tablename ] [ Charset
char_set ] } ]

[ CoordSys... ]
[ Version version_pro ] ]
[ Interactive ]
[ BlockSize block_size ]
[ { Interactive | Automatic commit_keyword } ]
[ ConvertObjects { ON | OFF | INTERACTIVE } ]

tablename is the name of the table as you want it to appear in database. The name can include a
schema name, which specifies the schema that the table belongs to. If no schema name is provided,
the table belongs to the default schema. The user is responsible for providing an eligible schema
name and must know if the login user has the proper permissions on the given schema. This
extension is for SQL Server 2005 only. When used with the GPKG clause, it is the name of the table
as you want it to appear in GeoPackage.
filespec is a file specification (optionally including directory path). This is where the MapInfo .TAB
file is saved.
char_set is the name of a character set; see CharSet clause.
locale is a string that specifies the locale of the index to create, such as "en-US". If not set, then the
default system locale is used.
version is an expression that specifies the version of the Microsoft Jet database format to be used
by the new database. Acceptable values are 4.0 (for Access 2000), 3.0 (for Access '95/'97), 12.0
(for Access 2007). If omitted, the default version is 12.0. If the database in which the table is being
created already exists, the specified database version is ignored.
database_filespec a string that identifies the name and path of a valid:
• Access database when used with Access. If the specified database does not exist, MapInfo Pro
creates a new Access (.MDB or .ACCDB) file.

MapBasic 15.2 Reference 157

 A to Z MapBasic Language Reference

• GeoPackage file when used with GPKG.

pwd is the database-level password for the database, to be specified when database security is
turned on.
ConnectionNumber is an integer value that identifies the specific connection to a database.
version_pro is 100 (to create a table that can be read by versions of MapInfo Pro) or 300 (MapInfo
Pro 3.0 format) for non-Access tables. For Access tables, version is 410.
block_size is a value of between 0 to 32768. If not specified, the default value is 16384. If the value
is less than 512, it rounds up to 512.
commit_keyword is one of the following keywords: NoCollision, ApplyUpdates, DiscardUpdates

Description
If no As clause is specified, the Commit Table statement saves any pending edits to the table. This
is analogous to the user choosing the Save command in MapInfo Pro.
A Commit Table statement that includes an As clause has the same effect as a user choosing the
Save Copy As command. The As clause can be used to save the table with a different name,
directory, file type, or projection.
To save the table under a new name, specify the new name in the filespec string. To save the table
in a new directory path, specify the directory path at the start of the filespec string.
The optional Type clause indicates the format of the local cache table, as either MapInfo (NATIVE)
or MapInfo Extended (NATIVEX). Use a Type clause within the As clause. The NATIVEX format
supports table caches larger than 2GB in size and character sets UTF-8 and UTF-16. When the
The Type clause is not specified, then the table type defaults to NATIVE.
The optional Charset clause is set with the Type clause and saves to a specific character set. The
char_set parameter should be a string constant, such as "WindowsLatin1". See CharSet clause
for more information.
• If not provided with the Type clause, the character set of the source table is assumed. Using an
incompatible character set may cause the character data in the destination table to convert into
underscores (such as WindowsCyrillic to WindowsLatin1). The preference is to convert to or from
UTF-8 or UTF-16 character sets.
• If not provided with the DBF and Table clauses, MapBasic uses the default character set for the
hardware platform that is in use at runtime. Note, the Commit Table statement does not support
UTF-8 or UTF-16 for DBF.
The Locale clause is set with the NATIVEX clause to specify the locale of the index to create, which
will affect the sorting behavior of the table. It takes a string value, such as "en-US". If not specified,
default system locale is used. This clause only applies to NativeX tables with a character set (charset)
of UTF-8 or UTF-16.
To save the table using a different coordinate system or projection, include a CoordSys clause
within the As clause. Note that only a mappable table may have a coordinate system or a projection.

MapBasic 15.2 Reference 158

 A to Z MapBasic Language Reference

To save a Query use the QUERY type for the table. Only queries made from the user interface and
queries created from Run Command statements in MapBasic can be saved. The Commit Table
statement creates a .TAB file and a .QRY file.
The Version clause controls the table's format. If you specify Version 100, MapInfo Pro stores the
table in a format readable by versions of MapInfo Pro. If you specify Version 300, MapInfo Pro stores
the table in MapInfo Pro 3.0 format. Note that region and polyline objects having more than 8,000
nodes and multiple-segment polyline objects require version 300. If you omit the Version clause,
the table is saved in the version 300 format.
Note: If a MapBasic application issues a Commit Table...As statement affecting a table which
has memo fields, the memo fields will not be retained in the new table. No warning will be
displayed. If the table is saved to a new table through MapInfo Pro's user interface (by
choosing Save Copy As), MapInfo Pro warns the user about the loss of the memo fields.
However, when the table is saved to a new table name through a MapBasic program, no
warning appears.

The ODBC clause indicates a copy of the Table will be saved on the DBMS specified by
ConnectionNumber.
Setting the SQLServerSpatial clause supports spatial data with GEOGRAPHY and GEOMETRY
data types.
The ConvertDateTime If the source table contains Time or Date type columns, these columns will
be converted to DATETIME or TIMESTAMP depending on whether the server supports the data
types. However, you can control this behavior using the clause ConvertDateTime. If the source table
does not contain a Time or Date type, this clause is a non-operational. If ConvertDateTime is set
to ON (which is the default setting), Time or Date type columns will be converted to DATETIME or
TIMESTAMP. If ConvertDateTime is set to OFF, the conversion is not done and the operation will
be canceled if necessary. If ConvertDateTime is set to INTERACTIVE a dialog box will pop up to
prompt the user and the operation will depend on the user's choice. If the user chooses to convert,
then the operation will convert and continue; if the user chooses to cancel, the operation will be
canceled.
The Time type requires conversion for all supported servers (Oracle, PostGIS, SQL Server Spatial,
MS SQL Server and Access) and the Date type requires conversion for MS SQL Server and Access
database servers.
Note: For MS SQL Server and Access database servers, this restriction could be a backward
compatibility issue. We suggest you use the DATETIME data type instead of TIMESTAMP
data type. If you still use the DATETIME data type, the conversion operation will fail.

CoordSys is a coordinate system clause; see CoordSys clause.

The BlockSize clause have a value of zero (0) to 32768. If not specified, the default is 16384. If the
value is less than 512, it rounds up to 512. Generally, the larger the block size, the faster the data
transfer rate. When converting from NativeX (MapInfo Extended) format to Native (MapInfo) format,
the original block size of the NativeX file is preserved. Users can specify a new block size when
committing from NativeX to Native format.

MapBasic 15.2 Reference 159

 A to Z MapBasic Language Reference

Setting the ConvertObjects clause to ONautomatically converts any unsupported objects

encountered in supported objects. Setting it to OFF does not convert unsupported objects. If they
are encountered, an error message displays saying the table cannot be saved. Setting to Interactive
asks the user what they want to do when unsupported objects are encountered in a table.

ConvertDateTime Examples

Commit Table DATETIME90 As "D:\MapInfo\Data\Remote\DATETIME90CPY.TAB"

Type ODBC Connection 1 Table """EAZYLOADER"".""DATETIME90CPY"""
ConvertDateTime Interactive

Server 1 Create Table """EAZYLOADER"".""CITY_125AA""" (Field1

Char(10),Field2 Char(10),Field3 Char(10),MI_STYLE Char(254)) KeyColumn

SW_MEMBER ObjectColumn SW_GEOMETRY

or
Server 1 Create Table "EAZYLOADER.CITY_125AA" (Field1 Char(10),Field2
Char(10),Field3 Char(10),MI_STYLE Char(254)) KeyColumn SW_MEMBER
ObjectColumn SW_GEOMETRY
Commit Table City_125aa As
"C:\Projects\Data\TestScripts\English\remote\City_125aacpy.tab" Type
ODBC
Connection 1 Table """EAZYLOADER"".""CITY_125AACPY"""
or
Commit Table City_125aa As
"C:\Projects\Data\TestScripts\English\remote\City_125aacpy.tab" Type
ODBC
Connection 1 Table "EAZYLOADER.CITY_125AACPY"

Saving Linked Tables

Saving a linked table can generate a conflict, when another user may have edits the same data in
the same table MapInfo Pro will detect if there were any conflicts and allows the user to resolve
them. The following clauses let you control what happens when there is a conflict. (These clauses
have no effect on saving a conventional MapInfo table.)
Interactive
In the event of a conflict, MapInfo Pro displays the Conflict Resolution dialog box. After a successful
Commit Table Interactive statement, MapInfo Pro displays a dialog box allowing the user to refresh.
Interactive when invoked for Commit Table As, handles the case when a user is saving a query with
one or more columns which are of indeterminate type. Using the Interactive parameter presents the
user with a message indicating which column(s) contain the indeterminate type and allows the user
to select new types and/or widths for these columns. If the Interactive parameter is not used, the
system assigns a Char(254) type to the indeterminate type column(s) by default.
Example

MapBasic 15.2 Reference 160

 A to Z MapBasic Language Reference

Issue the following query in the SQL Select dialog box and click OK or type this query in the
MapBasic window:

Select Highway, objectinfo(obj, 20) from US_HIWAY into Selection

When you select select the current query and then click the Save Copy As button, the following
error message displays:

Typically this dialog box contains a list of all columns that contain indeterminate types. In this query,
there is only one.
Click OK to display the Set Field Properties dialog box.

Use this dialog box to select the type information for this column. If there is more than one
indeterminate type, you can set each of these types one at a time. If there are columns whose type
is already defined, you will not be able to edit that information.
Click OK to save your query.

MapBasic 15.2 Reference 161

 A to Z MapBasic Language Reference

Automatic NoCollision
In the event of a conflict, MapInfo Pro does not perform the save. (This is the default behavior if the
statement does not include an Interactive clause or an Automatic clause.)
Automatic ApplyUpdates
In the event of a conflict, MapInfo Pro saves the local updates. (This is analogous to ignoring conflicts
entirely.)
Automatic DiscardUpdates
In the event of a conflict, MapInfo Pro saves the local updates already in the RDBMS (discards your
local updates). You can copy a linked table by using the As clause; however, the new copy is not
a linked table and no changes are updated to the server.

ODBC Connection
The length of tablename varies with databases. We recommend 14 or fewer characters for a table
name in order to work correctly for all databases. The statement limits the length of the tablename
to a maximum of 31 characters.
If the As clause is used and ODBC is the Type, a copy of the table will be saved on the database
specified by ConnectionNumber and named as tablename. If the source table is mappable, three
more columns, Key column, Object column, and Style column, may be added to the destination
database table, tablename, whether or not the source table has those columns. If the source table
is not mappable, one more column, Key column, may be added to the database table, tablename,
even if the source table does not have a Key column. The Key column will be used to create a
unique index.
A spatial index will be created on the Object column if one is present. The supported databases
include Oracle, SQL Server, IIS (SQL Server Spatial, Universal Server), and Microsoft Access.
However, to save a table with a spatial geometry/object, (including saving a point-only table)
SpatialWare is required for SQL Server, in addition to the spatial option for Oracle. The XY schema
is not supported in this statement.

Example
The following example opens the table STATES, then uses the Commit Table statement to make
a copy of the states table under a new name (ALBERS). The optional CoordSys clause causes
the ALBERS table to be saved using the Albers equal-area projection.

Open Table "STATES"

Commit Table STATES
As "ALBERS"
CoordSys Earth
Projection 9,7, "m", -96.0, 23.0, 20.0, 60.0, 0.0, 0.0

MapBasic 15.2 Reference 162

 A to Z MapBasic Language Reference

The following example illustrates an ODBC connection:

dim hodbc as integer

hodbc = server_connect("ODBC", "dlg=1")
Open table "C:\MapInfo\USA"
Commit Table USA
as "c:\temp\as\USA"
Type ODBC Connection hodbc Table "USA"

See Also:
Rollback statement

ConnectObjects() function
Purpose
Returns an object representing the shortest or longest distance between two objects. You can call
this function from the MapBasic window in MapInfo Pro.

Syntax

ConnectObjects( object1, object2, min )

object1 and object2 are object expressions.

min is a logical expression where TRUE calculates the minimum distance between the objects, and
FALSE calculates the maximum distance between objects.

Return Value
This statement returns a single section, two-point Polyline object representing either the closest
distance (min == TRUE) or farthest distance (min == FALSE) between object1 and object2.

Description
One point of the resulting Polyline object is on object1 and the other point is on object2. Note that
the distance between the two input objects can be calculated using the ObjectLen() function. If
there are multiple instances where the minimum or maximum distance exists (e.g., the two points
returned are not uniquely the shortest distance and there are other points representing "ties") then
these functions return one of the instances. There is no way to determine if the object returned is
uniquely the shortest distance.
ConnectObjects() returns a Polyline object connecting object1 and object2 in the shortest (min ==
TRUE) or longest (min == FALSE) way using a spherical calculation method. If the calculation cannot
be done using a spherical distance method (e.g., if the MapBasic coordinate system is NonEarth),
then a Cartesian method will be used.

MapBasic 15.2 Reference 163

 A to Z MapBasic Language Reference

Continue statement
Purpose
Resumes the execution of a MapBasic program (following a Stop statement). You can issue this
statement from the MapBasic window in MapInfo Pro.

Syntax

Continue

Restrictions
The Continue statement may only be issued from the MapBasic window; it may not be included
as part of a compiled program.

Description
The Continue statement resumes the execution of a MapBasic application which was suspended
because of a Stop statement.
You can include Stop statements in a program for debugging purposes. When a MapBasic program
encounters a Stop statement, the program is suspended, and the File menu automatically changes
to include a Continue Program option instead of a Run option. You can resume the suspended
application by choosing File > Continue Program. Typing the Continue statement into the MapBasic
window has the same effect as choosing Continue Program.

Control Button / OKButton / CancelButton clause

Purpose
Part of a Dialog statement; adds a push-button control to a dialog box.

Syntax

Control { Button | OKButton | CancelButton }

[ Position x, y ] [ Width w ] [ Height h ]
[ ID control_ID ]
[ Calling handler ]
[ Title title_string ]
[ Disable ] [ Hide ]

x, y specifies the button's position in dialog box units.

w specifies the width of the button in dialog box units; default width is 40.
h specifies the height of the button in dialog box units; default height is 18.

MapBasic 15.2 Reference 164

 A to Z MapBasic Language Reference

control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
handler is the name of a procedure to call if the user clicks on the button.
title_string is a text string to appear on the button.

Description
If a Dialog statement includes a Control Button clause, the dialog box includes a push-button
control. If the OKButton keyword appears in place of the Button keyword, the control is a special
type of button; the user chooses an OKButton control to "choose OK" and dismiss the dialog box.
Similarly, the user chooses a CancelButton control to "choose Cancel" and dismiss the dialog box.
Each dialog box should have no more than one OKButton control, and have no more than one
CancelButton control. Disable makes the control disabled (grayed out) initially. Hide makes the
control hidden initially.
Use the Alter Control statement to change a control's status (e.g., whether the control is enabled
or hidden).

Example

Control Button
Title "&Reset"
Calling reset_sub
Position 10, 190

See Also:
Alter Control statement, Dialog statement

Control CheckBox clause

Purpose
Part of a Dialog statement; adds a check box control to a dialog box

Syntax

Control CheckBox
[ Position x, y ] [ Width w ]
[ ID control_ID ]
[ Calling handler ]
[ Title title_string ]
[ Value log_value ]
[ Into log_variable ]
[ Disable ] [ Hide ]

x, y specifies the control's position in dialog box units.

w specifies the width of the control in dialog box units.

MapBasic 15.2 Reference 165

 A to Z MapBasic Language Reference

control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
handler is the name of a procedure to call if the user clicks on the control.
title_string is a text string to appear in the label to the right of the check-box.
log_value is a logical value: FALSE sets the control to appear un-checked initially.
log_variable is the name of a logical variable.

Description
If a Dialog statement includes a Control CheckBox clause, the dialog box includes a check box
control.
The Value clause controls the initial appearance. If the Value clause is omitted, or if it specifies a
value of TRUE, the check box is checked initially. If the Value clause specifies a FALSE value,
check-box is clear initially. Disable makes the control disabled (grayed out) initially. Hide makes
the control hidden initially.

Example

Control CheckBox
Title "Include &Legend"
Into showlegend
ID 6
Position 115, 155

See Also:
Alter Control statement, Dialog statement, ReadControlValue() function

Control DocumentWindow clause

Purpose
Part of a Dialog statement; adds a document window control to a dialog box which can be
re-parented for integrated mapping.

Syntax

Control DocumentWindow
[ Position x, y ]
[ Width w ] [ Height h ]
[ ID control_ID ]
[ Disable ] [ Hide ]

x, y specifies the control's position in dialog box units.

w specifies the width of the control in dialog units; default width is 100.

MapBasic 15.2 Reference 166

 A to Z MapBasic Language Reference

h specifies the height of the control in dialog units; default height is 100.
control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
Disable grays out the control initially.
Hide initially hides the control.

Description
If a Dialog statement includes a Control DocumentWindow clause, the dialog box includes a
document window control that can be re-parented using the Set Next Document statement.

Example
The following example draws a legend in a dialog box:

Control DocumentWindow
ID ID_LEGENDWINDOW
Position 160, 20
Width 120 Height 150

The dialog box handler will need to re-parent the window as in the following example:

Sub DialogHandler
OnError Goto HandleError
Dim iHwnd As Integer
Alter Control ID_LEGENDWINDOW Enable Show
' draw the legend
iHwnd = ReadControlValue(ID_LEGENDWINDOW)
Set Next Document Parent iHwnd Style WIN_STYLE_CHILD
Create Legend
Exit Sub
HandleError:
Note "DialogHandler: " + Error$()
End Sub

See Also:
Dialog statement

Control EditText clause

Purpose
Part of a Dialog statement; adds an EditText control box (input text) to a dialog box.

Syntax

Control EditText
[ Position x, y ] [ Width w ] [ Height h ]

MapBasic 15.2 Reference 167

 A to Z MapBasic Language Reference

[ ID control_ID ]
[ Value initial_value ]
[ Into variable ]
[ Disable ] [ Hide ] [ Password ]

x, y specifies the control's position in dialog box units.

w specifies the width of the control in dialog box units.
h specifies the height of the control in dialog box units; if the height is greater than 20, the control
becomes a multiple-line control, and text wraps down onto successive lines.
control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
initial_value is a string or a numeric expression that initially appears in the dialog box.
variable is the name of a string variable or a numeric variable; MapInfo Pro stores the final value of
the field in the variable if the user clicks OK.
The Disable keyword makes the control disabled (grayed out) initially.
The Hide keyword makes the control hidden initially.
The Password keyword creates a password field, which displays asterisks as the user types.

Description
If the user types more text than can fit in the box at one time, MapInfo Pro automatically scrolls the
text to make room. An EditText control can hold up to 32,767 characters.
If the height is large enough to fit two or more lines of text (for example, if the height is larger than
20), MapInfo Pro automatically wraps text down to successive lines as the user types. If the user
enters a line-feed into the EditText box (for example, on Windows, if the user presses Ctrl+Enter
while in the EditText box), the string associated with the EditText control will contain a Chr$(10)
value at the location of each line-feed. If the initial_value expression contains embedded Chr$(10)
values, the text appears formatted when the dialog box appears.
To make an EditText control the active control, use an Alter Control...Active statement.

Example

Control EditText
Value "Franchise Locations"
Position 65, 8 Width 90
ID 1
Into s_map_title

See Also:
Alter Control statement, Dialog statement, ReadControlValue() function

MapBasic 15.2 Reference 168

 A to Z MapBasic Language Reference

Control GroupBox clause

Purpose
Part of a Dialog statement; adds a rectangle with a label to a dialog box.

Syntax

Control GroupBox
[ Position x, y ] [ Width w ] [ Height h ]
[ ID control_ID ]
[ Title title_string ]
[ Hide ]

x, y specifies the control's position in dialog box units.

w specifies the width of the control in dialog box units.
h specifies the height of the control in dialog box units.
control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
title_string is a text string to appear at the upper-left corner of the box
The Hide keyword makes the control hidden initially.

Example

Control GroupBox
Title "Level of Detail"
Position 5, 30
Height 40 Width 70

See Also:
Alter Control statement, Dialog statement

Control ListBox / MultiListBox clause

Purpose
Part of a Dialog statement; adds a list to a dialog box

Syntax

Control { ListBox | MultiListBox }

[ Position x, y ] [ Width w ] [ Height h ]
[ ID control_ID ]
[ Calling handler ]

MapBasic 15.2 Reference 169

 A to Z MapBasic Language Reference

[ Title { str_expr | From Variable str_array_var } ]

[ Value i_selected ]
[ Into i_variable ]
[ Disable ] [ Hide ]

x, y specifies the control's position in dialog box units.

w specifies the width of the control in dialog box units; default width is 80.
h specifies the height of the control in dialog box units; default height is 70.
control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
handler is the name of a procedure to call if the user clicks or double-clicks on the list.
str_expr is a string expression, containing a semicolon-delimited list of items to appear in the control.
str_array_var is the name of an array of string variables.
i_selected is a SmallInt value indicating which list item should appear selected when the dialog box
first appears: a value of one selects the first list item; if the clause is omitted, no items are selected
initially.
i_variable is the name of a SmallInt variable which stores the user's final selection.
The Disable keyword makes the control disabled (grayed out) initially.
The Hide keyword makes the control hidden initially.

Description
If a Dialog statement includes a Control ListBox clause, the dialog box includes a listbox control.
If the list contains more items than can be shown in the control at one time, MapBasic automatically
adds a scroll-bar at the right side of the control.
A MultiListBox control is identical to a ListBox control, except that the user can Shift+Click to select
multiple items from a MultiListBox control.
The Title clause specifies the contents of the list. If the Title clause specifies a string expression
containing a semicolon-delimited list of items, each item appears as one item in the list. The following
sample Title clause demonstrates this syntax:

Title "1st Quarter;2nd Quarter;3rd Quarter;4th Quarter"

Alternately, if the Title clause specifies an array of string variables, each entry in the array appears
as one item in the list. The following sample Title clause demonstrates this syntax:

Title From Variable s_optionlist

Processing a MultiListBox control

To read what items the user selected from a MultiListBox control, assign a handler procedure that
is called when the user dismisses the dialog box (for example, assign a handler to the OKButton

MapBasic 15.2 Reference 170

 A to Z MapBasic Language Reference

control). Within the handler procedure, set up a loop to call the ReadControlValue() function
repeatedly.
The first call to the ReadControlValue() function returns the number of the first selected item; the
second call to the ReadControlValue() function returns the number of the second selected item;
etc. When the ReadControlValue() function returns zero, you have exhausted the list of selected
items. If the first call to the ReadControlValue() function returns zero, there are no list items
selected.

Processing Double-click events

If you assign a handler procedure to a list control, MapBasic calls the procedure every time the user
clicks or double-clicks an item in the list. In some cases, you may want to provide special handling
for double-click events. For example, when the user double-clicks a list item, you may want to dismiss
the dialog box as if the user had clicked on a list item and then clicked OK.
To see an example, refer to the sample application NVIEWS.MB in <Your MapBasic
Installation Directory>\SAMPLES\MAPBASIC\SNIPPETS.
To determine whether the user clicked or double-clicked, call the CommandInfo() function within
the list control's handler procedure, as shown in the following sample handler procedure:

Sub lb_handler
Dim i As SmallInt
If CommandInfo(CMD_INFO_DLG_DBL) Then
' ... then the user double-clicked.
i = ReadControlValue( TriggerControl() )
Dialog Remove
' at this point, the variable i represents
' the selected list item...
End If
End Sub

Example

Control ListBox
Title "1st Quarter;2nd Quarter;3rd Quarter;4th Quarter"
ID 3
Value 1
Into i_quarter
Position 10, 92 Height 40

The NVIEWS.MB sample program demonstrates how to create a dialog box which provides special
handling for when the user double-clicks. The NVIEWS program displays a dialog box with a ListBox
control. To complete the dialog box, the user can click on a list item and then choose OK, or the
user can double-click an item in the list.

MapBasic 15.2 Reference 171

 A to Z MapBasic Language Reference

The following Control ListBox clause adds a list to the Named Views dialog box. Note that the
ListBox control has a handler routine, "listbox_handler."

Control ListBox
Title desc_list
ID 1
Position 10, 20 Width 245 Height 64
Calling listbox_handler

If the user clicks or double-clicks on the ListBox control, MapBasic calls the sub procedure
"listbox_handler." The procedure calls the CommandInfo() function to determine whether the user
clicked or double-clicked. If the user double-clicked, the procedure issues a Dialog Remove
statement to dismiss the dialog box. If not for the Dialog Remove statement, the dialog box would
remain on the screen until the user clicked OK or Cancel.

Sub listbox_handler
Dim i As SmallInt
' First, since user clicked on the name of a view,
' we can enable the OK button and the Delete button.
Alter Control 2 Enable
Alter Control 3 Enable
If CommandInfo(CMD_INFO_DLG_DBL) = TRUE Then
' ...then the user DOUBLE-clicked.
' see which list item the user clicked on.
i = ReadControlValue(1) ' read user's choice.
Dialog Remove
Call go_to_view(i) ' act on user's choice.
End If
End Sub

MapBasic calls the handler procedure whether the user clicks or double-clicks. The handler procedure
must check to determine whether the event was a single- or double-click.
See Also:
Alter Control statement, Dialog statement, ReadControlValue() function, CommandInfo()
function

Control PenPicker/BrushPicker/SymbolPicker/FontPicker clause

Purpose
Part of a Dialog statement; adds a button showing a pen (line), brush (fill), symbol (point), or font
(text) style.

Syntax

Control { PenPicker | BrushPicker | SymbolPicker | FontPicker }

[ Position x, y ] [ Width w ] [ Height h ]

MapBasic 15.2 Reference 172

 A to Z MapBasic Language Reference

[ ID control_ID ]
[ Calling handler ]
[ Value style_expr ]
[ Into style_var ]
[ Disable ] [ Hide ]

x, y specifies the control's position, in dialog box units.

w specifies the control's width, in dialog box units; default width is 20.
h specifies the control's height, in dialog box units; default height is 20.
control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
handler is the name of a handler procedure; if the user clicks on the Picker control, and then clicks
OK on the style dialog box which appears, MapBasic calls the handler procedure.
style_expr is a Pen, Brush, Symbol, or Font expression, specifying what style will appear initially in
the control; this expression type must match the type of control (for example, must be a Pen
expression if the control is a PenPicker).
style_var is the name of a Pen, Brush, Symbol, or Font variable; this variable type must match the
type of control (for example, must be a Pen variable if the control is a PenPicker control).
The Disable keyword makes the control disabled (grayed out) initially.
The Hide keyword makes the control hidden initially.

Description
A Picker control (PenPicker, BrushPicker, SymbolPicker, or FontPicker) is a button showing a pen,
brush, symbol, or font style. If the user clicks on the button, a dialog box appears to allow the user
to change the style.

Example

Control SymbolPicker
Position 140,42
Into sym_storemarker

See Also:
Alter Control statement, Dialog statement, ReadControlValue() function

ControlPointInfo() function
Purpose:
Returns raster and geographic control point coordinates for an image table. The geographic
coordinates will be in the current MapBasic coordinate system.

MapBasic 15.2 Reference 173

 A to Z MapBasic Language Reference

Syntax:

ControlPointInfo( table_id, attribute, controlpoint_num )

table_id is a string representing a table name, a positive integer table number, or 0 (zero). The table
must be a raster, grid or WMS table.
attribute is an integer code indicating which aspect of the control point to return.
controlpoint_num is the integer number of which control point to return. Control point numbers start
at 1. The maximum control point number can be found by calling

RasterTableInfo(table_id, RASTER_TAB_INFO_NUM_CONTROL_POINTS)

Return Value
The X or Y raster coordinate is returned as an Integer. The X or Y geographic coordinate is returned
as a Float. The return type depends upon the attribute flag, for the control point specified by
controlpoint_num.
The attribute parameter can be any value from the table below. Codes in the left column (for example,
RASTER_CONTROL_POINT_X) are defined in MAPBASIC.DEF.

attribute code ID ControlPointInfo() returns:

RASTER_CONTROL_POINT_X 1 Integer result, representing the X coordinate of the control point

number specified by controlpoint_num

RASTER_CONTROL_POINT_Y 2 Integer result, representing the Y coordinate of the control point

number specified by controlpoint_num

GEO_CONTROL_POINT_X 3 Float result, representing the X coordinate of the control point

number specified by controlpoint_num

GEO_CONTROL_POINT_Y 4 Float result, representing the Y coordinate of the control point

number specified by controlpoint_num

TAB_GEO_CONTROL_POINT_X 5 Float result, representing the X coordinate of the control point

number specified by controlpoint_num stored in the raster image
TAB file

TAB_GEO_CONTROL_POINT_Y 6 Float result, representing the Y coordinate of the control point

number specified by controlpoint_num stored in the raster image
TAB file

MapBasic 15.2 Reference 174

 A to Z MapBasic Language Reference

Control PopupMenu clause

Purpose
Part of a Dialog statement; adds a popup menu control to the dialog box.

Syntax

Control PopupMenu
[ Position x, y ]
[ Width w ]
[ ID control_ID ]
[ Calling handler ]
[ Title { str_expr | From Variable str_array_var } ]
[ Value i_selected ]
[ Into i_variable ]
[ Disable ]

x, y specifies the control's position in dialog box units.

w specifies the control's width, in dialog box units; default width is 80.
control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
handler is the name of a procedure to call when the user chooses an item from the menu.
str_expr is a string expression, containing a semicolon-delimited list of items to appear in the control.
str_array_var is the name of an array of string variables.
i_selected is a SmallInt value indicating which item should appear selected when the dialog box
first appears: a value of one selects the first item; if the clause is omitted, the first item appears
selected.
i_variable is the name of a SmallInt variable which stores the user's final selection (one, if the first
item selected, etc.).
The Disable keyword makes the control disabled (grayed out) initially.

Description
If a Dialog statement includes a Control PopupMenu clause, the dialog box includes a pop-up
menu. A pop-up menu is a list of items, one of which is selected at one time. Initially, only the selected
item appears on the dialog box.
If the user clicks on the control, the entire menu appears, and the user can choose a different item
from the menu.

MapBasic 15.2 Reference 175

 A to Z MapBasic Language Reference

The Title clause specifies the list of items that appear in the menu. If the Title clause specifies a
string expression containing a semicolon-delimited list of items, each item appears as one item in
the menu. The following sample Title clause demonstrates this syntax:

Title "Town;County;Territory;Region;Entire state"

Alternately, the Title clause can specify an array of string variables, in which case each entry in the
array appears as one item in the popup menu.
The following sample Title clause demonstrates this syntax:

Title From Variable s_optionlist

Example

Control PopupMenu
Title "Town;County;Territory;Region;Entire state"
Value 2
ID 5
Into i_map_scope
Position 10, 150

See Also:
Alter Control statement, Dialog statement, ReadControlValue() function

Control RadioGroup clause

Purpose
Part of a Dialog statement; adds a list of radio buttons to the dialog box.

Syntax

Control RadioGroup
[ Position x, y ]
[ ID control_ID ]
[ Calling handler ]
[ Title { str_expr | From Variable str_array_var } ]
[ Value i_selected ]
[ Into i_variable ]
[ Disable ] [ Hide ]

x, y specifies the control's position in dialog box units.

control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
handler is the name of a procedure to call if the user clicks or double-clicks on any of the radio
buttons.

MapBasic 15.2 Reference 176

 A to Z MapBasic Language Reference

str_expr is a string expression, containing a semicolon-delimited list of items to appear in the control.
str_array_var is the name of an array of string variables.
i_selected is a SmallInt value indicating which item should appear selected when the dialog box
first appears: a value of one selects the first item; if the clause is omitted, the first item appears
selected.
i_variable is the name of a SmallInt variable which stores the user's final selection (one, if the first
item selected, etc.).
The Disable keyword makes the control disabled (grayed out) initially.
The Hide keyword makes the control hidden initially.

Description
If a Dialog statement includes a Control RadioGroup clause, the dialog box includes a group of
radio buttons. Each radio button is a label to the right of a hollow or filled circle. The currently-selected
item is indicated by a filled circle. Only one of the radio buttons may be selected at one time.
The Title clause specifies the list of labels that appear in the dialog box. If the Title clause specifies
a string expression containing a semicolon-delimited list of items, each item appears as one item
in the list.
The following sample Title clause demonstrates this syntax:

Title "&Full Details;&Partial Details"

Alternately, the Title clause can specify an array of string variables, in which case each entry in the
array appears as one item in the list. The following sample Title clause demonstrates this syntax:

Title From Variable s_optionlist

Example

Control RadioGroup
Title "&Full Details;&Partial Details"
Value 2
ID 2
Into i_details
Calling rg_handler
Position 15, 42

See Also:
Alter Control statement, Dialog statement, ReadControlValue() function

MapBasic 15.2 Reference 177

 A to Z MapBasic Language Reference

Control StaticText clause

Purpose
Part of a Dialog statement; adds a label to a dialog box.

Syntax

Control StaticText
[ Position x, y ]
[ Width w ] [ Height h ]
[ ID control_ID ]
[ Title title_string ]
[ Hide ]

x, y specifies the control's position, in dialog box units.

w specifies the control's width, in dialog box units.
h specifies the control's height, in dialog box units.
control_ID is an integer; cannot be the same as the ID of another control in the dialog box.
title_string is a text string to appear in the dialog box as a label.
The Hide keyword makes the control hidden initially.

Description
If you want the text string to wrap down onto multiple lines, include the optional Width and Height
clauses. If you omit the Width and Height clauses, the static text control shows only one line of
text.

Example

Control StaticText
Title "Enter map title:"
Position 5, 10

See Also:
Alter Control statement, Dialog statement

ConvertToPline() function
Purpose
Returns a polyline object that approximates the shape of another object. You can call this function
from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 178

 A to Z MapBasic Language Reference

Syntax

ConvertToPline( object )

object is the object to convert; may not be a point object or a text object.

Return Value
A polyline object

Description
The ConvertToPline() function returns a polyline object which approximates the object parameter.
Thus, if the object parameter represents a region object, ConvertToPline() returns a polyline that
has the same shape and same number of nodes as the region.
The results obtained by calling ConvertToPline() are similar to the results obtained by choosing
MapInfo Pro's Convert To Polylines command. However, the function ConvertToPline() does not
alter the original object.
See Also:
Objects Enclose statement

ConvertToRegion() function
Purpose
Returns a region object that approximates the shape of another object. You can call this function
from the MapBasic window in MapInfo Pro.

Syntax

ConvertToRegion( object )

object is the object to convert; may not be a point, line, or text object.

Return Value
A region object

Description
Retains most style attributes. Other attributes are determined by the current pens or brushes. A
polyline whose first and last nodes are identical will not have the last node duplicated. Otherwise,
MapInfo Pro adds a last node whose vertices are the same as the first node.
The ConvertToRegion() function returns a region object which approximates the object parameter.
Thus, if the object parameter represents a rectangle, ConvertToRegion() returns a region that looks
like a rectangle.

MapBasic 15.2 Reference 179

 A to Z MapBasic Language Reference

The results obtained by calling ConvertToRegion() are similar to the results obtained by choosing
MapInfo Pro's Convert To Regions command on the SPATIAL tab. However, the
ConvertToRegion() function does not alter the original object.
See Also:
Objects Enclose statement

ConvexHull() function
Purpose
Returns a region object that represents the convex hull polygon based on the nodes from the input
object. The convex hull polygon can be thought of as an operator that places a rubber band around
all of the points. It will consist of the minimal set of points such that all other points lie on or inside
the polygon. The polygon will be convex―no interior angle can be greater than 180 degrees. You
can call this function from the MapBasic window in MapInfo Pro.

Syntax

ConvexHull( inputobject )

inputobject is an object expression.

Return Value
Returns a region object.

Description
The ConvexHull() function returns a region representing the convex hull of the set of points
comprising the input object. The ConvexHull() function operates on one single object at a time. To
create a convex hull around a set of objects, use the Create Object As ConvexHull statement.

Example
The following program selects New York from the States file, then creates a ConvexHull surrounding
the selection.

Dim Resulting_object as object

select * from States
where State_Name = "New York"
Resulting_object = ConvexHull(selection.obj)
Insert Into States(obj) Values (Resulting_object)

See Also:
Create Object statement

MapBasic 15.2 Reference 180

 A to Z MapBasic Language Reference

CoordSys clause
Purpose
Specifies a coordinate system. You can use this clause in the MapBasic window in MapInfo Pro
(see CoordSys Earth and NonEarth Projection, CoordSys Layout Units, CoordSys Table, and
CoordSys Window).

CoordSys Earth and NonEarth Projection

Syntax 1 (Earth Projection)

CoordSys Earth
[ Projection type, datum, unitname
[ , origin_longitude ] [ , origin_latitude ]
[ , standard_parallel_1 [ , standard_parallel_2 ] ]
[ , azimuth ] [ , scale_factor ]
[ , false_easting ] [ , false_northing ]
[ , range ] ]
[ Affine Units unitname, A, B, C, D, E, F ]
[ Bounds ( minx, miny ) ( maxx, maxy ) ]

Syntax 2 (NonEarth Projection)

CoordSys Nonearth
[ Affine Units unitname, A, B, C, D, E, F ]
Units unitname
[ Bounds ( minx, miny ) ( maxx, maxy ) ]

type is a positive integer value representing which coordinate system to use.

datum is a positive integer value identifying which datum to reference.
unitname is a string representing a distance unit of measure (for example, "m" for meters); for a list
of unit names, see Set Distance Units statement.
origin_longitude is a float longitude value, in degrees.
origin_latitude is a float latitude value, in degrees.
standard_parallel_1 and standard_parallel_2 are float latitude values, in degrees.
azimuth is a float angle measurement, in degrees.
scale_factor is a float scale factor.
range is a float value from 1 to 180, dictating how much of the Earth will be seen.
minx is a float specifying the minimum x value.
miny is a float specifying the minimum y value.

MapBasic 15.2 Reference 181

 A to Z MapBasic Language Reference

maxx is a float specifying the maximum x value.

maxy is a float specifying the maximum y value.
A performs scaling or stretching along the X axis.
B performs rotation or skewing along the X axis.
C performs shifting along the X axis.
D performs scaling or stretching along the Y axis.
E performs rotation or skewing along the Y axis.
F performs shifting along the Y axis.

Description
The CoordSys clause specifies a coordinate system, and, optionally, specifies a map projection to
use in conjunction with the coordinate system. Note that CoordSys is a clause, not a complete
MapBasic statement. Various statements may include the CoordSys clause; for example, a Set
Map statement can include a CoordSys clause, in which case the Set Map statement will reset
the map projection used by the corresponding Map window.
Use CoordSys Earth (syntax 1) to explicitly define a coordinate system for an Earth map (a map
having coordinates which are specified with respect to a location on the surface of the Earth). The
optional Projection parameters dictate what map projection, if any, should be used in conjunction
with the coordinate system. If the Projection clause is omitted, MapBasic uses datum 0. The Affine
clause describes the affine transformation for producing the derived coordinate system. If the
Projection clause is omitted, the base coordinate system is Longitude/Latitude. Since the derived
coordinates may be in different units than the base coordinates, the Affine clause requires you to
specify the derived coordinate units.
Use CoordSys Nonearth (syntax 2) to explicitly define a non-Earth coordinate system, such as the
coordinate system used in a floor plan or other CAD drawing. In the CoordSys Non-Earth case,
the base coordinate system is an arbitrary Cartesian grid. The Units clause specifies the base
coordinate units, and the Affine clause specifies the derived coordinate units.
When a CoordSys clause appears as part of a Set Map statement or Set Digitizer statement,
the Bounds subclause is ignored. The Bounds subclause is required for non-Earth maps when
the CoordSys clause appears in any other statement, but only for non-Earth maps.
The Bounds clause defines the map's limits; objects may not be created outside of those limits.
When specifying an Earth coordinate system, you may omit the Bounds clause, in which case
MapInfo Pro uses default bounds that encompass the entire Earth.
Note: In a Create Map statement, you can increase the precision of the coordinates in the map
by specifying narrower Bounds.

Every map projection is defined as an equation; and since the different projection equations have
different sets of parameters, different CoordSys clauses may have varying numbers of parameters
in the optional Projection clause. For example, the formula for a Robinson projection uses the

MapBasic 15.2 Reference 182

 A to Z MapBasic Language Reference

datum, unitname, and origin_latitude parameters, while the formula for a Transverse Mercator
projection uses the datum, unitname, origin_longitude, origin_latitude, scale_factor, false_easting,
and false_northing parameters.
For more information on projections and coordinate systems, see the MapInfo Pro documentation.
Each MapBasic application has its own CoordSys setting that specifies the coordinate system used
by the application. If a MapBasic application issues a Set CoordSys statement, other MapBasic
applications which are also in use will not be affected.

Examples
The Set Map statement controls the settings of an existing Map window. The Set Map statement
below tells MapInfo Pro to display the Map window using the Robinson projection:

Set Map CoordSys Earth Projection 12, 12, "m", 0.

The first 12 specifies the Robinson projection; the second 12 specifies the Sphere datum; the "m"
specifies that the coordinate system should use meters; and the final zero specifies that the origin
of the map should be at zero degrees longitude.
The following statement tells MapInfo Pro to display the Map window without any projection.

Set Map CoordSys Earth

The following example opens the table World, then uses a Commit Table statement to save a copy
of World under the name RWorld. The new RWorld table will be saved with the Robinson projection.

Open Table "world" As World

Table world As "RWORLD.TAB"
CoordSys Earth Projection 12, 12, "m", 0.

The following example defines a coordinate system called DCS that is derived from UTM Zone 10
coordinate system using the affine transformation.

x1 = 1.57x - 0.21y + 84120.5

y1 = 0.19x + 2.81y - 20318.0

In this transformation, (x1, y1) represents the DCS derived coordinates, and (x, y) represents the
UTM Zone 10 base coordinates. If the DCS coordinates are measured in feet, the CoordSys clause
for DCS would be as follows:

CoordSys Earth
Projection 8, 74, "m", -123, 0, 0.9996, 500000, 0
Affine Units "ft", 1.57, -0.21, 84120.5, 0.19, 2.81, -20318.0

MapBasic 15.2 Reference 183

 A to Z MapBasic Language Reference

CoordSys Layout Units

Syntax

CoordSys Layout Units paperunitname

paperunitname is a string representing a paper unit of measure (for example, "in" for inches); for a
list of unit names, see Set Paper Units statement.

Description
Use CoordSys Layout to define a coordinate system which represents a MapInfo Pro Layout
window. A MapBasic program must issue a Set CoordSys Layout statement before querying,
creating or otherwise manipulating Layout objects. The unitname parameter is the name of a paper
unit, such as "in" for inches or "cm" for centimeters.

Examples
The following Set CoordSys statement assigns a Layout window's coordinate system, using inches
as the unit of measure:

Set CoordSys Layout Units "in"

CoordSys Table

Syntax

CoordSys Table tablename

tablename is the name of an open table.

Description
Use CoordSys Table to refer to the coordinate system in which a table has been saved.

CoordSys Window

Syntax

CoordSys Window window_id

window_id is an integer window identifier corresponding to a Map or Layout window.

Description
Use CoordSys Window to refer to the coordinate system already in use in a window.

MapBasic 15.2 Reference 184

 A to Z MapBasic Language Reference

Examples
The following example sets one Map window's projection to match the projection of another Map
window. This example assumes that two integer variables (first_map_id and second_map_id) already
contain the window IDs of the two Map windows.

Set Map
Window second_map_winid
CoordSys Window first_map_winid

See Also:
Commit Table statement, Set CoordSys statement, Set Map statement

CoordSysName$() function
Purpose
Returns coordinate system name string from MapBasic Coordinate system clause. You can call this
function from the MapBasic window in MapInfo Pro.

Syntax

CoordSysName$ ( string )

Return Value
String

Example

Note CoordSysName$("Coordsys Earth Projection 1, 62")

Returns this string in the MapInfo dialog box:

Longitude / Latitude (NAD 27 for Continental US)

Note: If a coordinate system name does not exist in the MapInfow.prj file, such as when the map
is in NonEarth system in Survey Feet, then function will return an empty string.

Note CoordSysName$("CoordSys NonEarth Units " + """survey ft""" +

"Bounds (0, 0) (10, 10)")

If an invalid CoordSys clause is passed such as this (using invalid units):

Note CoordSysName$("CoordSys Earth Projection 3, 74, " + """foo""" +

"-90, 42, 42.7333333333, 44.0666666667, 1968500, 0")

MapBasic 15.2 Reference 185

 A to Z MapBasic Language Reference

Then an Error regarding the Invalid Coordinate System should be returned (Error #727).

Invalid Coordinate System: CoordSys Earth Projection <content>

CoordSysStringToEPSG() function
Purpose
Converts a MapBasic Coordinate System clause into an EPSG integer value for use with any
MapBasic function or statement. You can call this function from the MapBasic window in MapInfo
Pro.

Syntax

CoordSysStringToEPSG ( coordsys_string )

coordsys_string is a MapBasic CoordSys clause. EPSG (European Petroleum Survey Group) value
is an integer value; for example, CoordSys Clause of "Earth Projection 1, 104" will return an EPSG
code of 4326. For a complete list of EPSG codes used with MapInfo Pro see the MAPINFOW.PRJ
file in your MapInfo Pro installation. The EPSG codes are identified by a "\p" followed by a number.

Return Value
Integer. If no EPSG value is found, it returns -1.

Description
The CoordSysStringToEPSG() function is used to convert a MapBasic CoordSys clause into an
integer EPSG value.

Example
The following example displays EPSG code Earth Projection 1, 104 Coordinate System.

print CoordSysStringToEPSG("Earth Projection 1, 104"))

See Also:
CoordSys clause

CoordSysStringToPRJ$() function
Purpose
Converts MapBasic Coordinate System clause into an PRJ string. PRJ string format is used to
describe MapInfo Coordinate Systems in mapinfow.prj file. You can call this function from the
MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 186

 A to Z MapBasic Language Reference

Syntax

CoordSysStringToPRJ$( coordsys_string )

coordsys_string is a MapBasic CoordSys clause. PRJ string is an alternative definition of Coordinate

System used in the mapinfow.prj file; for example, CoordSys Clause of "Earth Projection 1, 104"
will return a PRJ string of "1,104".

Return Value
string

Description
The CoordSysStringToPRJ$() function is used to convert a MapBasic CoordSys clause into an
integer EPSG value.

Example
The following example displays PRJ string for Earth Projection 1, 104 Coordinate System.

print CoordSysStringToPRJ$("Earth Projection 1, 104")

See Also:
CoordSys clause

CoordSysStringToWKT$() function
Purpose
Converts a CoordSys clause into an WKT (Well-Known Text) string value. You can call this function
from the MapBasic window in MapInfo Pro.

Syntax

CoordSysStringToWKT$( coordsys_string )

coordsys_string is a CoordSys clause.

Return Value
WKT string. If no WKT string value is found, returns an empty string.

MapBasic 15.2 Reference 187

 A to Z MapBasic Language Reference

Example
The following example:

Print coordsysstringtowkt$("CoordSys Earth Projection 8, 74, " + """m"""

+
", -123, 0, 0.9996, 500000, 0 Affine Units " + """ft""" + ", 1.57, -0.21,

84120.5, 0.19, 2.81, -20318.0")

produces the following WKT string:

PROJCS["_MI_0",GEOGCS[
,DATUM["North_American_Datum_1983",SPHEROID["Geodet
ic Reference System of
1980",6378137,298.2572221009113],AUTHORITY["EPSG","6269"]],PRIMEM["Greenw

ich",0],UNIT["degree",0.0174532925199433]],PROJECTION["Transverse_Mercato

r"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-
123],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],P

ARAMETER["false_northing",0],UNIT["METER",1]]

See Also:
CoordSys clause

Cos() function
Purpose
Returns the cosine of a number. You can call this function from the MapBasic window in MapInfo
Pro.

Syntax

Cos( num_expr )

num_expr is a numeric expression representing an angle in radians.

Return Value
Float

Description
The Cos() function returns the cosine of the numeric num_expr value, which represents an angle
in radians. The result returned from Cos() is between one (1) and negative one (-1).

MapBasic 15.2 Reference 188

 A to Z MapBasic Language Reference

To convert a degree value to radians, multiply that value by DEG_2_RAD. To convert a radian value
into degrees, multiply that value by RAD_2_DEG.
Note: Your program must Include "MAPBASIC.DEF" to reference DEG_2_RAD or RAD_2_DEG.

Example

Include "MAPBASIC.DEF"
Dim x, y As Float
x = 60 * DEG_2_RAD
y = Cos(x)

' y will now be equal to 0.5

' since the cosine of 60 degrees is 0.5

See Also:
Acos() function, Asin() function, Atn() function, Sin() function, Tan() function

Create Adornment statement

Purpose
Creates and displays Adornments, such as a scale bar, on mapper window. You can issue this
statement from the MapBasic window in MapInfo Pro.

Syntax

Create Adornment
From Window map_window_id
Type adornment_type
[ Position {
[ Fixed [ ( x, y ) [ Units paper_units ] ] ] |
[ win_position [ Offset (x, y) ] [Units paper_units ] ]
} ]
[ Layout Fixed Position { Frame | Geographic } ]
[ Size [ Width win_width ] [ Height win_height ] [ Units paper_units
] ]
[ Background [ Brush ... ] [ Pen ... ] ]
[ < SCALEBAR CLAUSE > ]

Where SCALEBAR CLAUSE is:

[ BarType type ]
[ Ground Units distance_units ]
[ Display Units paper_units ]
[ BarLength paper_length ]
[ BarHeight paper_height ]
[ BarStyle [ Pen .... ] [ Brush ... ] [ Font ... ] ]

MapBasic 15.2 Reference 189

 A to Z MapBasic Language Reference

[ Scale [ { On | Off } ] ]
[ Auto [ { On | Off } ] ]

adornment_type can be scalebar.

(x, y) in the Fixed clause is position measured from the upper left of the mapper window, which is
(0, 0). Using this version of adornment placement, the adornment will be at that position in the
mapper as the mapper resizes. For example, a position of (3, 3) inches would be toward the bottom
right of a small sized mapper but in the middle of a large sized mapper. As the mapper changes
size, the adornment will try to remain completely within the displayed mapper.
paper_units defaults to the MapBasic Paper Unit. For details about paper units, see Set Paper
Units statement.
win_position specify one of the following codes; codes are defined in the MAPBASIC.DEF file.

ADORNMENT_INFO_MAP_POS_TL (0)
ADORNMENT_INFO_MAP_POS_TC (1)
ADORNMENT_INFO_MAP_POS_TR (2)
ADORNMENT_INFO_MAP_POS_CL (3)
ADORNMENT_INFO_MAP_POS_CC (4)
ADORNMENT_INFO_MAP_POS_CR (5)
ADORNMENT_INFO_MAP_POS_BL (6)
ADORNMENT_INFO_MAP_POS_BC (7)
ADORNMENT_INFO_MAP_POS_BR (8)

(x, y) in the Offset clause is measured from the anchor position. For example, if the win_position
is ADORNMENT_INFO_MAP_POS_TL (top left), then the x is to the right and the y is down. If the
win_position is ADORNMENT_INFO_MAP_POS_BR, then the x position is left and the y position
is up. In the center left (ADORNMENT_INFO_MAP_POS_CL) and center right
(ADORNMENT_INFO_MAP_POS_CR), the y offset is ignored. In the center position
(ADORNMENT_INFO_MAP_POS_CC), the offset is ignored completely (both x and y). In the top
center (ADORNMENT_INFO_MAP_POS_TC) and bottom center
(ADORNMENT_INFO_MAP_POS_BC) positions, the x offset is ignored. For
ADORNMENT_INFO_MAP_POS_ defines, see win_position.
win_width and win_height define the size of the adornment. MapInfo Pro ignores these parameters
if this is a scale bar adornment, because scale bar adornment size is determined by scale bar specific
items, such as BarLength.
type specify one of the following codes; codes are defined in the MAPBASIC.DEF file.

SCALEBAR_INFO_BARTYPE_CHECKEDBAR (0)
SCALEBAR_INFO_BARTYPE_SOLIDBAR (1)
SCALEBAR_INFO_BARTYPE_LINEBAR (2)
SCALEBAR_INFO_BARTYPE_TICKBAR (3)

MapBasic 15.2 Reference 190

 A to Z MapBasic Language Reference

0 Check Bar, 1 Solid Bar, 2 Line Bar, or 3 Tick Bar

distance_units a unit of measure that the scale bar is to represent:

distance value Unit Represented

"ch" chains

"cm" centimeters

"ft" feet (also called International Feet; one International Foot equals exactly 30.48 cm)

"in" inches

"km" kilometers

"li" links

"m" meters

"mi" miles

"mm" millimeters

"nmi" nautical miles (1 nautical mile represents 1852 meters)

"rd" rods

"survey ft" U.S. survey feet (used for 1927 State Plane coordinates; one U.S. Survey Foot equals exactly
12/39.37 meters, or approximately 30.48006 cm)

"yd" yards

paper_length a value in paper_units to specify how long the scale bar will be displayed. Specify the
length of the scale bar to a maximum of 34 inches or 86.3 cm on the printed map.

MapBasic 15.2 Reference 191

 A to Z MapBasic Language Reference

paper_height a value in paper_units to specify how tall the scale bar will be displayed. Specify height
of the adornment to a maximum of 44 inches or 111.76cm on the printed map.
paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in
(inches), pt (points), and pica.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points

Description
The scale bar displays as a paper_length bar in the paper_units.
Position can be Fixed relative to the mapper upper left regardless of the size of the mapper, or
relative to some anchor point on the mapper specified by win_position.
Offset is the amount the adornment will be offset from the mapper when using one of the docked
win_position.
Layout Fixed Position determines how an adornment is positioned in a layout when the adornment
is using Fixed positioning. If this is set to Geographic, then the adornment is placed on the same
geographic place on the map frame in the layout as it is in the mapper. If the layout frame changes
size, then the adornment will move relative to the frame to match the geographic position. If this is
set to Frame, then the adornment will remain at a fixed position relative to the frame, as designated
in the Position clause. If the Position clause positions the adornment at (1.0, 1.0) inches, then the
adornment will be placed 1 inch to the left and one inch down from the upper left corner of the frame.
Changing the size of the frame will not change the position of the adornment. The default is
Geographic.
Offset is the amount the adornment will be offset from the mapper when using one of the docked
win_positions.
The Background clause when used with Brush denotes the fill pattern to be used in the background
while creating or modifying a scale bar. When used with the Pen clause, this denotes the border to
be used in the background while creating or modifying a scale bar.
Brush is a valid Brush clause. Only Solid brushes are allowed. While values other than solid are
allowed as input without error, the type is always forced to solid. This clause is used only to provide
the background color for the adornment.
Pen is a valid Pen clause. Due to window clipping (the adornment is a window within the mapper),
Pen widths other than 1 may not display correctly. Also, Pen styles other than solid may not display
correctly. This clause is designed to turn on (solid) or off (hollow) and set the color of the border of
the adornment.
Font is a valid Font clause.

MapBasic 15.2 Reference 192

 A to Z MapBasic Language Reference

The Auto clause set to On shows values that have been automatically rounded in the scale bar. If
the clause is set to Off, the values will not be rounded and will be shown like they had been in earlier
versions. The default is Auto Off, if not already specified.
Use Scale set to On to include a representative fraction (RF) with the scale bar. (In MapInfo Pro, a
map scale that does not include distance units, such as 1:63,360 or 1:1,000,000, is called a
cartographic scale.)

Example
If the paper_length is 1 and the paper_unit is inches, then the scale bar displays as 1 inch. It is
labeled in the distance_unit for the current amount that paper_unit spans, and it dynamically updates
as the map changes (e.g., zoom and pan). The default distance_unit is the current distance unit in
the mapper. The paper_height determines how tall the scale bar displays. The Pen and Brush
define the style to draw the scale bar with and Font defines the text style for scale bar labeling and
annotation. The Scale parameter displays a cartographic scale.
The following example shows default settings:

create adornment
from window 261763624
type scalebar
position 6 offset (0.000000, 0.000000) units "in"
background Brush (2,16777215,16777215) Pen (1,2,0)
bartype 0 ground units "mi" display units "in"
barlength 1.574803 barheight 0.078740
barstyle Pen (1,2,0) Brush (2,0,16777215) Font ("Arial",0,8,0)
scale on

See Also:
Set Adornment statement

Create Arc statement

Purpose
Creates an arc object. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Arc
[ Into { Window window_id | Variable var_name } ]
( x1, y1 ) ( x2, y2 )
start_angle end_angle
[ Pen... ]

window_id is a window identifier.

var_name is the name of an existing object variable.

MapBasic 15.2 Reference 193

 A to Z MapBasic Language Reference

x1, y1 specifies one corner of the minimum bounding rectangle (MBR) of an ellipse; the arc produced
will be a section of this ellipse.
x2, y2 specifies the opposite corner of the ellipse's MBR.
start_angle specifies the arc's starting angle, in degrees.
end_angle specifies the arc's ending angle, in degrees.
The Pen clause specifies a line style.

Description
The Create Arc statement creates an arc object.
If the statement includes the optional Into Variable clause, the object will be stored in the specified
object variable. If the Into clause specifies a window identifier, the object will be stored in the
appropriate place in the window (for example, in the editable layer of a Map window). If the Into
clause is not provided, MapBasic will attempt to store the object in the topmost window; if objects
may not be stored in the topmost window (for example, if the topmost window is a grapher) no object
will be created.
The x and y parameters use whatever coordinate system MapBasic is currently using. By default,
MapBasic uses a Longitude/Latitude coordinate system, although the Set CoordSys statement
can re-configure MapBasic to use a different coordinate system. Note that MapBasic's coordinate
system is independent of the coordinate system of any Map window. Objects created on a Layout
window, however, are specified in paper units: each x-coordinate represents a distance from the
left edge of the page, while each y-coordinate represents the distance from the top edge of the
page. For details about paper units, see Set Paper Units statement. By default, MapBasic uses
inches as the default paper unit. To use a different paper unit, use the Set Paper Units statement.
Before creating objects on a Layout window, you must issue a Set CoordSys Layout statement.
The optional Pen clause specifies a line style. If no Pen clause is specified, the Create Arc statement
uses the current MapInfo Pro line style (the style which appears in the Line Style dialog box).
See Also:
Insert statement, Pen clause, Update statement, Set CoordSys statement

Create ButtonPad statement

Purpose
Creates a ButtonPad (toolbar) in MapInfo Pro 32-bit version. In the 64-bit version, this command
creates a new group in the LEGACY tab. You can issue this statement from the MapBasic window
in MapInfo Pro.

MapBasic 15.2 Reference 194

 A to Z MapBasic Language Reference

Syntax

Create ButtonPad { title_string | ID pad_num } As

button_definition [ button_definition ... ]
[ Title title_string ]
[ Width width ]
[ Position ( x, y ) [ Units unit_name ] ]
[ ToolbarPosition ( row, column ) ]
[ { Show | Hide } ]
[ { Fixed | Float | Top | Left | Right | Bottom } ]

title_string is the ButtonPad title (for example, "Drawing"). Any whitespaces in the title would be
stripped and any special characters masked.
pad_num is the ID number for the standard toolbar you want to re-define:
• 1 for Main
• 2 for Drawing
• 3 for Tools
• 4 for Standard
• 5 for Database Management System (DBMS)
• 6 Web Services
• 7 Reserved
width is the pad width, in terms of the number of buttons across. Not suppported in the 64-bit version
of MapInfo Pro.
x, y specify the pad's position when it is floating; specified in paper units . For details about paper
units, see Set Paper Units statement. Not suppported in the 64-bit version of MapInfo Pro.
unit_name is a string representing paper units name (for example, "in" for inches, "cm" for
centimeters). Not suppported in the 64-bit version of MapInfo Pro.
row, column specify the pad's position when it is docked as a toolbar (for example, 0, 0 places the
pad at the left edge of the top row of toolbars, and 0, 1 represents the second pad on the top row).
Not suppported in the 64-bit version of MapInfo Pro.
• row position starts at the top and increases in value going to the bottom. It is a relative value to
the rows existing in the same position (top or bottom). When there is a menu bar in the same
position, then the numbers become relative to the menu bar. When a toolbar is just below the
menu bar, its row value is 0. If it is directly above the menu bar, then its row value is -1.
• column position starts at the left and increases in value going to the right. It is a relative value to
the columns existing in the same position (left or right). For example, if a toolbar is docked to the
left and the menu bar is docked to the left position, then the column number for the column left of
the menu bar is -1. The column number for the column to the right of the menu bar is 0.

MapBasic 15.2 Reference 195

 A to Z MapBasic Language Reference

Each button_definition clause can consist of the keyword Separator, or it can have the following
syntax:

{ PushButton | ToggleButton | ToolButton }

Calling { procedure | menu_code | OLE methodname | DDE server, topic
}
[ ID button_id ]
[ Icon icon_code [ File file_spec ] ]
[ Cursor cursor_code [ File file_spec ] ]
[ DrawMode dm_code ]
[ HelpMsg msg ]
[ ModifierKeys { On | Off } ]
[ { Enable | Disable } ]
[ { Check | Uncheck } ]

procedure is the handler procedure to call when a button is used.

menu_code is a standard MapInfo Pro menu code from MENU.DEF (for example, M_FILE_OPEN);
MapInfo Pro runs the menu command when the user uses the button.
methodname is a string specifying an OLE method name.
server, topic are strings specifying a DDE server and topic name.
ID button_id specifies a unique button number. This number can be used as a parameter to allow
a handler to determine which button is in use (in situations where different buttons call the same
handler) or as a parameter to be used with the Alter Button statement.
Icon icon_code specifies the icon to appear on the button; icon_code can be one of the standard
MapInfo icon codes listed in ICONS.DEF, such as MI_ICON_RULER (11). If the File sub-clause
specifies the name of a file containing icon resources, icon_code is an integer resource ID identifying
a resource in the file. The size of the button can be defined with resource file id of icon_code for
small and icon_code+1 for large sized buttons, with resource file ids of icon_code and icon_code+1
respectively.
Cursor cursor_code specifies the shape the mouse cursor should adopt whenever the user chooses
a ToolButton tool; cursor_code is a code, such as MI_CURSOR_ARROW (0), from ICONS.DEF.
This clause applies only to ToolButtons. If the File sub-clause specifies the name of a file containing
icon resources, cursor_code is an integer resource ID identifying a resource in the file.
The 64-bit version of MapInfo Pro supports cursors in three ways:
1. As a string from Icons.def: SetRbnToolBtnCtrlCursor(MyToolButton, "138")
2. As a string with keyword FILE and name of DLL with custom cursors:
SetRbnToolBtnCtrlCursor(MyToolButton, "136 FILE gcsres32.dll")
3. As an integer id such as a MapInfo Cursor define from Icons.def:
SetRbnToolBtnCtrlCursorId(MyToolButton, MI_CURSOR_FINGER_LEFT)
DrawMode dm_code specifies whether the user can click and drag, or only click with the tool;
dm_code is a code (for example, DM_CUSTOM_LINE) from ICONS.DEF. The DrawMode clause
applies only to ToolButtons.

MapBasic 15.2 Reference 196

 A to Z MapBasic Language Reference

HelpMsg msg specifies the button's status bar help and, optionally, ToolTip help. The first part of
the msg string is the status bar help message. If the msg string includes the letters \n then the text
following the \n is used as the button's ToolTip help.
ModifierKeys clause controls whether the Shift and control (Ctrl) keys affect "rubber-band" drawing
if the user drags the mouse while using a ToolButton. Default is Off, meaning that the Shift and
control (Ctrl) keys have no effect.

Description
Use the Create ButtonPad statement to create a custom ButtonPad. Once you have created a
custom ButtonPad, you can modify it using Alter Button statement and Alter ButtonPad statement.
Each toolbar can be hidden. To create a toolbar in the hidden state, include the Hide keyword.
To set whether the pad is fixed to the top of the screen ("docked") or floating like a window, include
the Fixed or the Float keyword. The user can also control whether the pad is docked or not by
dragging the pad to or from the top of the screen. For more control over the location on the screen
that the pad is docked to, use the Top (which is the same as using Fixed), Left, Right, or Bottom
keywords.
When a toolbar is floating, its position is controlled by the Position clause; when it is docked, its
position is controlled by the ToolbarPosition clause.
For more information on ButtonPads, see the MapBasic User Guide. For additional information
about the capabilities of ToolButtons, see Alter ButtonPad statement.

About Icon Size

Before MapInfo Pro 10.0, custom icons were rectangular in size: 18x16 for small icons and 26x24
for large icons. Toolbar and menu features introduced in MapInfo Pro 10.0 require square icons:
16x16 for small icons and 24x24 for large icons. MapInfo Pro 10.0 and later display custom icons
in the square size distorting how they display. To correct the distortion MapInfo Pro removes the
first and last column of pixels to not display them (cropping the image). As a result, there may be
some loss of information in the icon image.
For best results, create your icons to 16x16 for small icons and 24x24 for large icons. Icons at these
sizes are not compatible with versions before 10.0.1 and generate an error message in these
versions.
For compatibility with versions before 10.0.1, use 18x16 for small icons and 26x24 for large icons.
These icons appear distorted in version 10.0 and appear cropped in versions after 10.0.
About Icons for Menu Items
The following describe how MapInfo Pro 10.0 handles icons for menu items:
• Icons for menu items are dynamic based on icons in toolbars.
• If a toolbar button has an icon it may be used for a menu item if it meets one of the following
requirements:
• Toolbar button and menu item must be within the same MBX file.

MapBasic 15.2 Reference 197

 A to Z MapBasic Language Reference

• The same handler/userId combination; any menu item that calls the same handler/userid from
the same MBX file is assigned that icon).
• The same userId calling different handlers.
• The same handler, no userID.
• ID must be <= 32767.

• For built in handlers, priority is given to find an icon from a built in toolbar. If none is found, then
there is a search through the toolbar icons from the MBX files for a match.
• Small icons are shown next to menu items.
• When an MBX unloads, any of its associated icons are unloaded and are no longer in use for
menu items.
The following describe how MapInfo Pro handles icons for menu items:
• Menu items can show an icon if a MapBasic application creates a toolbar button and menu item
that meet the previously listed requirements for menu item icons.

Calling Clause Options

The Calling clause specifies what should happen when the user acts on the custom button. The
following table describes the available syntax.

Calling clause example Description

If Calling is followed by a numeric code from MENU.DEF, the event

Calling M_FILE_NEW runs a standard MapInfo Pro menu command (the File > New command,
in this example).

If you specify a procedure name, the event calls the procedure. The
Calling my_procedure procedure must be part of the same MapBasic program.

Makes a method call to the OLE Automation object set by MapInfo Pro's
Calling OLE "methodname" SetCallback method. See the MapBasic User Guide.

Connects through DDE to "server|topic" and sending an Execute

Calling DDE message to the DDE server.
"server","topic"

In the last two cases, the string sent to OLE or DDE starts with the three letters "MI:" so that the
server can detect that the message came from MapInfo. The remainder of the string contains a
comma-separated list of the values returned from the function calls CommandInfo(1) through
CommandInfo(8). For complete details on the string syntax, see the MapBasic User Guide.

MapBasic 15.2 Reference 198

 A to Z MapBasic Language Reference

Examples
Create a button pad of utilities:

Create ButtonPad "Utils" As

PushButton
HelpMsg "Choose this button to display query dialog"
Calling button_sub_proc
Icon MI_ICON_ZOOM_QUESTION
ToolButton
HelpMsg "Use this tool to draw a new route"
Calling tool_sub_proc
Icon MI_ICON_CROSSHAIR
DrawMode DM_CUSTOM_LINE
ToggleButton
HelpMsg "Turn proximity checking on/off"
Calling toggle_prox_check
Icon MI_ICON_RULER
Check
Title "Utilities"
Width 3
Show

Create a toolbar button that launches the Browser Preferences dialog, which has a menu command
ID of 222:

Create ButtonPad "Prefs" As

PushButton
HelpMsg "Browser Preferences.\nBrowser Prefs"
Calling 222
Icon 99

See Also:
Alter Button statement, Alter ButtonPad statement, ButtonPadInfo() function

Create ButtonPad As Default statement

Purpose
Restores one standard ButtonPad (for example, the Main ButtonPad) to its default state. You can
issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create ButtonPad { title_string | ID pad_num } As Default

title_string is the ButtonPad title (for example, "Main", "Standard", or "Custom Tools").
pad_num is the ID number for the standard ButtonPad (toolbar) you want to re-define:

MapBasic 15.2 Reference 199

 A to Z MapBasic Language Reference

• 1 for Main
• 2 for Drawing
• 3 for Tools
• 4 for Standard
• 5 for Database Management System (DBMS)
• 6 Web Services
• 7 Reserved
Custom ButtonPads use only the title_string.

Description
This statement restores MapInfo Pro's standard ButtonPads (such as Main, Drawing, and Tools) to
their default states. Custom ButtonPads will be destroyed.
See Also:
Alter Button statement,Alter ButtonPad statement, Create ButtonPad statement, Create
ButtonPads As Default statement

Create ButtonPads As Default statement

Purpose
Restores all standard ButtonPads (for example, the Main ButtonPad) to their default state. You can
issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create ButtonPads As Default

Description
This statement restores MapInfo Pro's standard ButtonPads (such as Main, Drawing, and Tools) to
their default states. Custom ButtonPads will be destroyed.
Use this statement with caution. The Create ButtonPads As Default statement destroys all custom
buttons, even buttons defined by other MapBasic applications.
See Also:
Alter Button statement,Alter ButtonPad statement, Create ButtonPad statement, Create
ButtonPad As Default statement

MapBasic 15.2 Reference 200

 A to Z MapBasic Language Reference

Create Cartographic Legend statement

Purpose
Creates and displays cartographic style legends as well as theme legends for an active map window.
You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Cartographic Legend

[ From Window map_window_id ]
[ Behind ]
[ Position ( x, y ) [ Units paper_units ] ]
[ Width win_width [ Units paper_units ] ]
[ Height win_height [ Units paper_units ] ]
[ Window Title { legend_window_title }
[ ScrollBars { On | Off } ]
[ Portrait | Landscape | Custom ]
[ Style Size { Small | Large }
[ Default Frame Title { def_frame_title } [ Font... ] } ]
[ Default Frame Subtitle { def_frame_subtitle } [ Font... ] } ]
[ Default Frame Style { def_frame_style } [ Font... ] } ]
[ Default Frame Border Pen [ [ pen_expr ]
Frame From Layer { map_layer_id | map_layer_name
[ Using
[ Column { column | Object } [ FromMapCatalog { On | Off }]]
[ Label { expression | Default } ]
[ Position ( x, y ) [ Units paper_units ] ]
[ Title { frame_title [ Font... ] }
[ SubTitle { frame_subtitle [ Font... ] } ]
[ Border Pen pen_expr ]
[ Style [ Font...] [ Norefresh ] [ Text { style_name }
{ Line Pen... | Region Pen... Brush...| Symbol Symbol... } |
Collection [ Symbol ... ]
[ Line Pen... ] [ Region Pen... Brush ...] } ]
[ , ... ]

map_window_id is an integer window identifier which you can obtain by calling the FrontWindow()
function and WindowID() function.
x states the desired distance from the top of the workspace to the top edge of the window.
y states the desired distance from the left of the workspace to the left edge of the window.
Note: Here workspace means the client area (which excludes the title bar, tool bar, and the status
bar).

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in

(inches), pt (points), and pica.

MapBasic 15.2 Reference 201

 A to Z MapBasic Language Reference

• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points

• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
win_width is the desired width of the window.
win_height is the desired height of the window.
legend_window_title is a string expression representing a title for the window, defaults to "Legend
of xxx" where xxx is the map window title.
def_frame_title is a string which defines a default frame title. It can include the special character "#"
which will be replaced by the current layer name.
def_frame_subtitle is a string which defines a default frame subtitle. It can include the special
character "#" which will be replaced by the current layer name.
def_frame_style is a string that displays next to each symbol in each frame. The "#" character will
be replaced with the layer name. The % character will be replaced by the text "Line", "Point, "Region",
as appropriate for the symbol. For example, "% of #" will expand to "Region of States" for the
STATES.TAB layer.
pen_expr is a Pen expression, for example, MakePen( width, pattern, color ). If a default border pen
is defined, then it will be become the default for the frame. If a border pen clause exists at the frame
level, then it is used instead of the default.
map_layer_id or map_layer_name identifies a map layer; can be a SmallInt (for example, use 1 to
specify the top map layer other than Cosmetic) or a string representing the name of a table displayed
in the map. For a theme layer you must specify the map_layer_id.
frame_title is a string which defines a frame title. If a Title clause is defined here for a frame, then
it will be used instead of the def_frame_title.
frame_subtitle is a string which defines a frame subtitle. If a Subtitle clause is defined here for a
frame, then it will be used instead of the def_frame_subtitle.
column is an attribute column name from the frame layer's table.
style_name is a string which displays next to a symbol, line, or region in a custom frame.

Description
The Create Cartographic Legend statement allows you to create and display cartographic style
legends as well as theme legends for an active map window. Each cartographic and thematic styles
legend will be connected to one, and only one, Map window so that there can be more than one
Legend window open at a time.
You can create a frame for each cartographic or thematic map layer you want to include on the
legend. The cartographic and thematic frames will include a legend title and subtitle. Cartographic
frames display a map layer's styles; legend frames display the colors, symbols, and sizes represented

MapBasic 15.2 Reference 202

 A to Z MapBasic Language Reference

by the theme. You can create frames that have styles based on the Map window's style or you can
create your own custom frames.
At least one Frame clause is required.
All clauses pertaining to the entire legend (scrollbars, width, etc.) must proceed the first Frame
clause.
The From Layer clause must be the first clause after the Frame clause.
The optional Behind clause places the legend behind the Thematic Map window.
The optional Position clause controls the window's position on MapInfo Pro's workspace. The upper
left corner of MapInfo Pro's workspace has the position 0, 0. The optional Width and Height clauses
control the window's size. Window position and size values use paper units settings, such as "in"
(inches) or "cm" (centimeters). For details about paper units, see Set Paper Units statement.
MapBasic has a current paper units setting, which defaults to inches; a MapBasic program can
change this setting through the Set Paper Units statement. A Create Cartographic Legend
statement can override the current paper units by including the optional Units subclause within the
Position, Width, and/or Height clauses.
Use the ScrollBars clause to show or hide scroll-bars on a Map window.
Portrait or Landscape describes the orientation of the legend frames in the window. Portrait results
in an orientation that is down and across. Landscape results in an orientation that is across and
down.
If Custom is specified, you can specify a custom Position clause for a frame.
The Position clause at the frame level specifies the position of a frame if Custom is specified.The
x coordinate measures from the left of the legend window, and the y coordinate measures from the
bottom of the legend window (the origin (0,0) is in the bottom-left of the legend window).
The optional Style Size clause controls the size of the samples that appear in legend windows. If
you specify Style Size Small, small-sized legend samples are used in Legend windows. If you
specify Style Size Large, larger-sized legend samples are used.
The Position, Title, SubTitle, Border Pen, and Style clauses at the frame level are used only for
map layers. They are not used for thematic layers. For a thematic layer, this information is gotten
automatically from the theme.
The Font clause specifies a text style. If a default frame title, subtitle, or style name font is defined,
then it will become the default for the frame. If a frame level Title, Subtitle, or Style clause exists
and includes a Font clause, then the frame level font is used. If no font is specified at any level,
then the current text style is used and the point sizes are 10, 9, and 8 for title, subtitle and style
name.
The Style clause and the NoRefresh keyword allow you to create custom frames that are not
overwritten when the legend is refreshed. If the NoRefresh keyword is used in the Style clause,
then the table is not scanned for styles. Instead, the Style clause must contain your custom list of
definitions for the styles displayed in the frame. This is done with the Text clause and appropriate
Line, Region, or Symbol clause. Multipoint objects are treated as Point objects.

MapBasic 15.2 Reference 203

 A to Z MapBasic Language Reference

Collection objects are treated separately. When MapInfo Pro creates a Legend based on object
types, it draws Point symbols first, then Lines, then Regions. Collection objects are drawn last. Inside
collection objects the order of drawing is point, line, and then region samples.
If Column is defined, column is the name of an attribute column in the frame layer's table, or Object
denotes the object column (meaning that legend styles are based on the unique styles in the map
file). The default is Object.
FromMapCatalog ON retrieves styles from the MapCatalog for a live access table. If the table is
not a live access table, MapBasic reverts to the default behavior for a non-live access table instead
of throwing an error. The default behavior for a non-access table is FromMapCatalog Off (for
example, map styles).
FromMapCatalog OFF retrieves the unique map styles for the live table from the server. This table
must be a live access table that supports per record styles for this to occur. If the live table does
not support per record styles than the behavior is to revert to the default behavior for live tables,
which is to get the default styles from the MapCatalog (FromMapCatalog ON).
If a Label is defined, specify expression as a valid expression, or Default (meaning that the default
frame style pattern is used when creating each style's text, unless the style clause contains text).
The default is Default.
Initially, each frame layer's TAB file is searched for metadata values for the title, subtitle, column
and label. If no metadata value exists for the column, the default is Object. If no metadata value
exists for Label, the default is the default frame style pattern. If legend metadata keys exist and you
want to override them, you must use the corresponding MapBasic syntax.

Example
The following example shows how to create a frame for a Map window's cartographic legend. Legend
windows are a special case: To create a frame for a Legend window, you must use the Title clause
instead of the From Window clause.

Dim i_layout_id, i_map_id As Integer

Dim s_title As String
' here, you would store the Map window's ID in i_map_id,
' and store the Layout window's ID in i_layout_id.
' To obtain an ID, call FrontWindow() or WindowID().
s_title = "Legend of " + WindowInfo(i_map_id, WIN_INFO_NAME)
Set CoordSys Layout Units "in"
Create Frame
Into Window i_layout_id
(1,2) (4, 5)
Title s_title

This creates a frame for a Cartographic Legend window. To create a frame for a Thematic Legend
window, change the title to the following.

S_title="Theme Legend of " + WindowInfo (I_map_id, WW_INFO_NAME)

See Also:

MapBasic 15.2 Reference 204

 A to Z MapBasic Language Reference

Set Cartographic Legend statement, Alter Cartographic Frame statement, Add Cartographic
Frame statement, Remove Cartographic Frame statement, Create Legend statement, Set
Window statement, WindowInfo() function

CreateCircle() function
Purpose
Returns an Object value representing a circle. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

CreateCircle( x, y, radius )

x is a float value, indicating the x-position (for example, Longitude) of the circle's center.
y is a float value, indicating the y-position (for example, Latitude) of the circle's center.
radius is a float value, indicating the circle radius.

Return Value
Object

Description
The CreateCircle() function returns an Object value representing a circle.
The x and y parameters use whatever coordinate system MapBasic is currently using. By default,
MapBasic uses a Longitude/Latitude coordinate system, although the Set CoordSys statement
can re-configure MapBasic to use a different coordinate system.
Note: MapBasic's coordinate system is independent of the coordinate system of any Map window.

The radius parameter specifies the circle radius, in whatever distance unit MapBasic is currently
using. By default, MapBasic uses miles as the distance unit, although the Set Distance Units
statement can re-configure MapBasic to use a different distance unit.
The circle uses whatever Brush style is currently selected. To create a circle object with a specific
Brush, you can issue a Set Style statement before calling CreateCircle(). Alternately, instead of
calling CreateCircle(), you can issue a Create Ellipse statement, which has optional Pen clause
and Brush clause.
The circle object created through the CreateCircle() function could be assigned to an Object variable,
stored in an existing row of a table (through the Update statement), or inserted into a new row of
a table (using an Insert statement).
Note: Before creating objects on a Layout window, you must issue a Set CoordSys Layout
statement.

MapBasic 15.2 Reference 205

 A to Z MapBasic Language Reference

Error Conditions
ERR_FCN_ARG_RANGE (644) is generated if an argument is outside of the valid range.

Examples
The following example uses the Insert statement to insert a new row into the table Sites. The
CreateCircle() function is used within the body of the Insert statement to specify the graphic object
that is attached to the new row.

Open Table "sites"

Insert Into sites (obj)
Values ( CreateCircle(-72.5, 42.4, 20) )

The following example assumes that the table Towers has three columns: Xcoord, Ycoord, and
Radius. The Xcoord column contains longitude values, the Ycoord column contains latitude values,
and the Radius column contains radius values. Each row in the table describes a radio broadcast
tower, and the Radius column indicates each tower's broadcast area.
The Update statement uses the CreateCircle() function to build a circle object for each row in the
table. Following this Update statement, each row in the Towers table will have a circle object attached.
Each circle object will have a radius derived from the Radius column, and each circle will be centered
at the position indicated by the Xcoord and Ycoord columns.

Open Table "towers"

Update towers
Set obj = CreateCircle(xcoord, ycoord, radius)

See Also:
Create Ellipse statement, Insert statement, Update statement

Create Collection statement

Purpose
Combines points, linear objects, and closed objects into a single object. The collection object displays
in the Browser as a single record. You can issue this statement from the MapBasic window in
MapInfo Pro.

Syntax

Create Collection [ num_parts ]

[ Into { Window window_id | Variable var_name } ]
Multipoint
[ num_points ]
( x1, y1 ) ( x2, y2 ) [ ... ]
[ Symbol... ]
Region

MapBasic 15.2 Reference 206

 A to Z MapBasic Language Reference

num_polygons
[ num_points1 ( x1, y1 ) ( x2, y2 ) [ ... ] ]
[ num_points2 ( x1, y1 ) ( x2, y2 ) [ ... ] ... ]
[ Pen... ]
[ Brush... ]
[ Center ( center_x, center_y ) ]
Pline
[ Multiple num_sections ]
num_points
( x1, y1 ) ( x2, y2 ) [ ... ]
[ Pen... ]
[ Smooth... ]

num_parts is the number of non-empty parts inside a collection. This number is from 0 to 3 and is
optional for MapBasic code (it is mandatory for MIF files).
num_polygons is the number of polygons inside the Collection object.
num_sections specifies how many sections the multi-section polyline will contain.
Pen is a valid Pen clause to specify a line style.
Brush is a valid Brush clause to specify fill style.

Example

create collection multipoint 2 (0,0) (1,1) region 3 3 (1,1) (2,2) (3,4)

4
(11,11) (12,12) (13,14) (19,20) 3 (21,21) (22,22) (23,24) pline 3 (-1,1)

(3,-2) (4,3)
dim a as object
create collection into variable a multipoint 2 (0,0) (1,1) region 1 3
(1,1) (2,2) (3,4) pline 3 (-1,1) (3,-2) (4,3)
insert into test (obj) values (a)
create collection region 2 4 (-5,-5) (5,-5) (5,5) (-5,5) 4 (-3,-3) (3,-3)

(3,3) (-3,3) pline multiple 2 2 (-6,-6) (6,6) 2 (-6,6) (6,-6) multipoint

6
(2,2) (-2,-2) (2,-2) (-2,2) (4,1) (-1,-4)

See Also:
Create MultiPoint statement, Set Combine Version statement

Create Cutter statement

Purpose
Produces a Region object that can be used as a cutter for an Object Split operation, as well as a
new set of Target objects which may be a subset of the original set of Target objects. You need to

MapBasic 15.2 Reference 207

 A to Z MapBasic Language Reference

provide a set of Target objects, and a set of polylines as a selection object. You can issue this
statement from the MapBasic window in MapInfo Pro.

Syntax

Create Cutter Into Target

Description
Before using Create Cutter, one or more Polyline objects must be selected, and an editable target
must exist. This is set by choosing the Set Target command, or using the Set Target statement.
The Polyline objects contained in the selection must represent a single, contiguous section. The
Polyline selection must contain no breaks or self intersections.
The Polyline must intersect the Minimum Bounding Rectangle (MBR) of the Target in order for the
Target to be a valid object to split. The Polyline, however, does not have to intersect the Target
object itself. For example, the Target object could be a series of islands (for example, Hawaii), and
the Polyline could be used to divide the islands into two sets without actually intersecting any of the
islands. If the MBR of a Target does not intersect the Polyline, then that Target will be removed from
the Target list.
Given this revised set of Target objects, a cumulative MBR of all of these objects is calculated and
represents the overall space to be split. The polyline is then extended, if necessary, so that it covers
the MBR. This is done by taking the direction of the last two points on each end of the polyline and
extending the polyline in that Cartesian direction until it intersects with the MBR. The extended
Polyline should divide the Target space into two portions. One Region object will be created and
returned which represents one of these two portions.
This statement returns the revised set of Target objects (still set as the Target), as well as this new
Region cutter object. This Region object will be inserted into the Target table (which must be an
editable table). The original Polyline object(s) will remain, but will no longer be selected. The new
Region object will now be the selected object. If the resulting Region object is suitable, then this
operation can be immediately followed by an Object Split operation, as appropriate Target objects
are set, and a suitable Region cutter object is selected.
Note: The cutter object still remains in the target layer. You will have to delete the cutter object
manually from your editable layer.

Example

Open Table "C:\MapInfo_data\TUT_USA\USA\STATES.TAB"

Open Table "C:\MapInfo_data\TUT_USA\USA\US_HIWAY.TAB"
Map from States, Us_hiway
select * from States where state = "NY"
Set target On
select * from Us_hiway where highway = "I 90"
Create Cutter Into Target
Objects Split Into Target

MapBasic 15.2 Reference 208

 A to Z MapBasic Language Reference

See Also:
OverlayNodes() function, Set Target statement

Create Designer Legend statement

Purpose
Creates a new Legend window to display cartographic style frames for map layers and theme legend
frames for thematic map layers for an active Map window. You can issue this statement from the
MapBasic window in MapInfo Pro.

Syntax

Create Designer Legend

[ From Window map_window_id ]
[ Behind ]
[ Position ( x, y ) [ Units paper_units ] ]
[ Width win_width [ Units paper_units ] ]
[ Height win_height [ Units paper_units ] ]
[ Min | Max | Restore | Floating | Docked | Tabbed | AutoHidden ]
[ Window Title { legend_window_title }
[ Portrait | Landscape | Custom ]
[ Default Frame Title { def_frame_title } [ Font... ] } ]
[ Default Frame Subtitle { def_frame_subtitle } [ Font... ] } ]
[ Default Frame Style { def_frame_style } [ Font... ] } ]
[ Default Frame Line Width width [ Units paper_units ] ]
[ Default Frame Region Width width [ Units paper_units ] ]
[ Default Frame Region Height height [ Units paper_units ] ]
[ Default Frame Auto Font Size { On | Off } ]
[ Legend Text Frame [ Text { frame_text [ Font... ] }
[ Position ( x, y ) [ Units paper_units ] ] ] ]
Frame From Layer { map_layer_id | map_layer_name
[ Using
[ Column { column | Object } [ FromMapCatalog { On | Off }]]
[ Label { expression | Default } ]
[ Position ( x, y ) [ Units paper_units ] ]
[ Border Pen .... ] [ Brush ... ] [ Priority n ] [ Name framename ]
[ Region [ Height region_height [ Units paper_units ] ] ]
[ Region [ Width region_width [ Units paper_units ] ] ]
[ Line [ Width line_width [ Units paper_units ] ] ]
[ Auto Font Size { On | Off } ]
[ Title { frame_title [ Font... ] }
[ SubTitle { frame_subtitle [ Font... ] } ]
[ Columns number_of_columns ] |
[ Height frame_height [ Units paper_units ] ]
[ Order { Default | Ascending | Descending |
{ Custom id | id : id [ , id | id : id ... ] ... } } ]
[ Style [ Font...] [ Norefresh ] [ Text { style_name }

MapBasic 15.2 Reference 209

 A to Z MapBasic Language Reference

{ Line Pen... | Region Pen... Brush...| Symbol Symbol... } |

Collection [ Symbol... ]
[ Line Pen... ] [ Region Pen... Brush...] } ]
[ , ... ]

map_window_id is an integer window identifier which you can obtain by calling the FrontWindow()
function and WindowID() function. If this identifier is for a map within a Layout window, then the
legends are created in the window.
x states the desired distance from the top of the workspace to the top edge of the window.
y states the desired distance from the left of the workspace to the left edge of the window.
Note: Workspace means the client area, which excludes the title bar, tool bar, and the status bar.

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in

(inches), pt (points), and pica. For a list of paper unit names, see Set Paper Units statement.
• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points
win_width is the desired width of the window.
win_height is the desired height of the window.
Floating docking state makes the window floating.
Docked docking state docks the window to the default position.
Tabbed docking stae makes the window tabbed, in this state it is also callled as a document.
AutoHidden docking state auto hides the window.
Note: All four docking states above are specific only to the 64-bit version of MapInfo Pro.

legend_window_title is a string expression representing a title for the window, defaults to "Legend
of xxx" where xxx is the map window title.
def_frame_title is a string which defines a default frame title. It can include the special character "#"
which will be replaced by the current layer name.
def_frame_subtitle is a string which defines a default frame subtitle. It can include the special
character "#" which will be replaced by the current layer name.
def_frame_style is a string that displays next to each symbol in each frame. The "#" character will
be replaced with the layer name. The % character will be replaced by the text "Line", "Point, "Region",
as appropriate for the symbol. For example, "% of #" will expand to "Region of States" for the
STATES.TAB layer.

MapBasic 15.2 Reference 210

 A to Z MapBasic Language Reference

width value, in paper units (see paper_units), is the desired width used to display region sample
swatches within the window.
height value, in paper units (see paper_units), is the desired height used to display region sample
swatches within the window.
frame_text is text for a legend title, subtitle, or descriptive text (such as copyright information for
example).
map_layer_id or map_layer_name identifies a map layer; can be a SmallInt (for example, use 1 to
specify the top map layer other than Cosmetic) or a string representing the name of a table displayed
in the map. For a theme layer you must specify the map_layer_id.
frame_title is a string which defines a frame title. If a Title clause is defined here for a frame, then
it will be used instead of the def_frame_title.
frame_subtitle is a string which defines a frame subtitle. If a Subtitle clause is defined here for a
frame, then it will be used instead of the def_frame_subtitle.
number_of_columns is the number of columns to show in a frame (this is different from the number
of columns in a portrait layout).
frame_height this is used in place of the column clause when the user resizes a legend frame. The
height of the frame in paper units. Written to the WOR when the frame has been manually resized.
column is an attribute column name from the frame layer's table.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window. When
creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of frames to
a unique set of values beginning with 1.
framename is a string representing the name for this legend frame embedded in a Layout window.
If a name is assigned to a frame in the Layout, it will be written to the WOR. When the Name clause
is written to the WOR, the workspace version is updated to version 1500.
region_height is a value representing the new height of a swatch in the map frame of the Legend
window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2 inches, 0.282222 to
5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the default value of 32 points
is used (which can be set as a preference).
region_width is a value representing the new width of a swatch in the map frame of the Legend
window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2 inches, 0.282222 to
5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the default value of 32 points
is used (which can be set as a preference).
line_width is a value representing the new width of a line segment in the map frame of a Legend
window. You can specify 12 to 144 points, 1 to 12 picas, 0.666667 to 2 inches, 4.23333 to 50.8
millimeters, or 4.23333 to 50.8 centimeters. If not specified, then the default value of 36 points is
used (which can be set as a preference).
style_name is a string which displays next to a symbol, line, or region in a custom frame.

MapBasic 15.2 Reference 211

 A to Z MapBasic Language Reference

Description
The Create Designer Legend statement allows you to create and displays cartographic legends
as well as theme legends for an active map window. Each cartographic and thematic styles legend
will be connected to one, and only one, Map window so that there can be more than one Legend
window open at a time.
You can create a legend frame for each cartographic or thematic map layer you want to include on
the Legend window. Legends can include a legend title and subtitle. They can display a map layer's
styles, or the colors, symbols, and sizes represented by a theme. You can also create legends that
define your own custom styles using the Create Designer Legend statement.
At least one Frame clause is required. Each Frame clause represents one legend that will be created
in the Legend window.
All clauses pertaining to the entire Legend window (width, etc.) must proceed the first Frame clause.
The From Layer clause must be the first clause after the Frame clause.
The optional Behind clause places the legend behind the Map window.
The optional Position clause controls the window's position on MapInfo Pro's workspace. The upper
left corner of MapInfo Pro's workspace has the position 0, 0. The optional Width and Height clauses
control the window's size. Window position and size values use paper units settings, such as "in"
(inches) or "cm" (centimeters). MapBasic has a current paper units setting, which defaults to inches;
a MapBasic program can change this setting through the Set Paper Units statement. A Create
Designer Legend statement can override the current paper units by including the optional Units
subclause within the Position, Width, and/or Height clauses.
Brush is a valid Brush clause. Only Solid brushes are allowed. While values other than solid are
allowed as input without error, the type is always forced to solid. This clause is used only to provide
the background color for the frame.
Border Pen is a valid Pen clause. This clause is designed to turn on (solid) or off (hollow) and set
the color of the border of the frame.
The Region Height clause specifies a specific height for a swatch in the legend frame of the Legend
window.
The Region Width clause specifies a specific width for a swatch in the legend frame of the Legend
window.
The Line Width clause specifies a specific width for a line sample in the legend frame of the Legend
window.
Auto Font Size enables or disables resizing the legend swatch based on the font size setting.
Portrait or Landscape describes the orientation or automatic arrangement of the legend frames in
the window. Portrait results in an orientation that is down and across. Landscape results in an
orientation that is across and down.
If Custom is specified, you can specify a custom Position clause for each frame.

MapBasic 15.2 Reference 212

 A to Z MapBasic Language Reference

The Position clause at the frame level specifies the position of a frame if Custom is specified.The
x coordinate measures from the left of the Legend window, and the y coordinate measures from
the bottom of the Legend window (the origin (0,0) is in the bottom-left of the Legend window).
The Position, Default Frame Title, Default Frame SubTitle, and Default Frame Style clauses at
the frame level are used only for map layer legends. They are not used for thematic layer legends.
For a thematic legend, this information is obtained automatically from the theme.
The default frame settings are optional. If not specified, then the default is used from the application
preferences (minimum and maximum limits will exist). The new swatch settings will override the
default frame settings.
• The Default Frame Line Width is width in paper units for line style samples.
• The Default Frame Region Width is width in paper units for region style samples.
• The Default Frame Region Height is height in paper units for region style samples.
paper_units is a string representing a paper unit name. For details about paper units, see Set Paper
Units statement.
Legend Text Frame creates a text frame in the Legend window.
If Text does not specify the Font clause, then the default font is used.
If Column is defined, column is the name of an attribute column in the frame layer's table, or Object
denotes the object column (meaning that legend styles are based on the unique styles in the map
file). The default is Object.
FromMapCatalog ON retrieves styles from the MapCatalog for a live access table. If the table is
not a live access table, MapBasic reverts to the default behavior for a non-live access table instead
of throwing an error. The default behavior for a non-access table is FromMapCatalog Off (for
example, map styles).
FromMapCatalog OFF retrieves the unique map styles for the live table from the server. This table
must be a live access table that supports per record styles for this to occur. If the live table does
not support per record styles than the behavior is to revert to the default behavior for live tables,
which is to get the default styles from the MapCatalog (FromMapCatalog ON).
If a Label is defined, specify expression as a valid expression, or Default (meaning that the default
frame style pattern is used when creating each style's text, unless the style clause contains text).
The default is Default.
The Height clause is used in place of the Columns clause when the user resizes a frame. This
applies to both map legend frames and thematic legend frames, which are mutually exclusive. If
both are present, then the Columns clause is used.
The Order clause adds the ability to sort or customize the order of rows in map legends. You can
sort map legends by style label or by defining your own order. The sort order options are Default,
Ascending, Descending, or Custom. The Order clause is only written to a workspace if the map
legend is sorted ascending, descending, or custom.

MapBasic 15.2 Reference 213

 A to Z MapBasic Language Reference

A Default sort order is the order the Create Legend wizard creates the legend rows. If you create
a legend based on unique styles, this will be the order of those styles, which then display as rows
in the map legend.
If specifying Custom sort order, the id values are row ids starting with 1, moving from top to bottom.
When looking at the list of rows in the Legend Frame Properties dialog box, the first row in the list
has id equal to 1 and so on down the list. For more details, see Custom Order Options and the
Alter Designer Frame statement custom order Options.
The Display clause controls the display of each row. Each row in MapBasic starts with the Style
clause. At the end of each Style clause is the optional Display clause. Display On makes the row
visible. Display Off makes the row invisible. If the Display clause is absent, then the row displays.
The Display clause is only written to a workspace file for styles that are not visible in a legend frame.
Note: The Shade statement and Set Legend statement still create and modify thematic legends,
but only the Create Designer Legend statement adds thematic legends to a Legend window
(by specifying the theme layer ID using the Frame From Layer id clause).

Note: The Columns or Height clauses apply to map and thematic legends. However, all other
thematic legend properties must be specified using the Set Legend statement.

The Style clause and the NoRefresh keyword allow you to create custom frames that are not
overwritten when the legend is refreshed. If the NoRefresh keyword is used in the Style clause,
then the table is not scanned for styles. Instead, the Style clause must contain your custom list of
definitions for the styles displayed in the frame. This is done with the Text clause and appropriate
Line, Region, or Symbol clause. Multipoint objects are treated as Point objects.
Collection objects are treated separately. When MapInfo Pro creates a Legend based on object
types, it draws Point symbols first, then Lines, then Regions. Collection objects are drawn last. Inside
collection objects the order of drawing is point, line, and then region samples.
The Font clause specifies a text style. If a default frame title, subtitle, or style name font is defined,
then it will become the default for the frame. If a frame level Default Frame Title, Default Frame
Subtitle, or Default Frame Style clause exists and includes a Font clause, then the frame level
font is used. If no font is specified at any level, then the font styles in the Legend Window preferences
are used for title, subtitle, and style name.
Initially, each frame layer's TAB file is searched for metadata values for the title, subtitle, column
and label. If no metadata value exists for the column, the default is Object. If no metadata value
exists for Label, the default is the default frame style pattern. If legend metadata keys exist and you
want to override them, you must use the corresponding MapBasic syntax. See GetMetadata$()
function and Metadata statement.

Creating Legends in a Layout Window

When a map is embedded in a Layout window, any legends you create for the map are also placed
in the same Layout window. You can only create one full set of legends for a map. A full set includes
one legend for each layer in the map.

MapBasic 15.2 Reference 214

 A to Z MapBasic Language Reference

Some of the clauses in the Create Designer Legend statement syntax do not apply when creating
a legend frame for a map embedded within a Layout window. The Behind, Window Title, and
Legend Text Frame clauses are ignored.
If you use the Create Designer Legend statement again for the same map in a Layout window, you
will see a message stating that the map already contains one or more legends. Use the Add Designer
Frame statement instead.

Example

Open Table ApplicationDirectory$() + "MyTable.tab" As mytable

Open Table ApplicationDirectory$() + "States.tab" As states
Open Table ApplicationDirectory$() + "City_125.tab" As cities
Open Table ApplicationDirectory$() + "Us_hiway.tab" As hiway
Map From cities, hiway, states, mytable
Create Designer Legend From Window FrontWindow()
Position (8, 0) Units "in"
Width 3 Units "in"
Height 6 Units "in"
Window Title "Legend Designer Window Test"
Custom
Default Frame Title "# Legend" Font ("Calibri",1,12,16711680)
Default Frame Subtitle "#" Font ("Arial",2,10,255)
Default Frame Style "%" Font ("Lucida Calligraphy",0,8,16732240)
Frame From Layer Cities
Using column object
label default
Position (.5, 0) Units "in"
Subtitle "125 Largest Cities"
Frame From Layer hiway
Using column object
label default
Position (.5, .75) Units "in"
Title "US Highways"
Subtitle "Interstates"
Frame From Layer states
Using column object
label default
Position (.5, 1.5) Units "in"
Title "United States"
Subtitle "State Boundaries"
Frame From Layer mytable
Using column object
label default
Position (.5, 2.5) Units "in"
Title "MyTable Objects"
Subtitle "Special Objects"
Columns 4

See Also:
Alter Designer Frame statement, Add Designer Frame statement, Remove Designer Frame
statement, Set Designer Legend statement, Set Window statement, WindowInfo() function

MapBasic 15.2 Reference 215

 A to Z MapBasic Language Reference

Custom Order Options

Both the Create Designer Legend statement and the Alter Designer Frame statement include
an Order clause with the option of specifying a Custom sort order.

Custom id | id : id [ , id | id : id ... ]

Where the following specifies a range of row ids in increasing order (Id2 > Id1):

Id1 : Id2

Reordering a List
The syntax for custom order of legend rows is similar to the Order clause (to reorder layers) in the
Set Map statement. It is fairly easy to use when you want to reorder near the beginning of a list,
but not so easy when you want to reorder near the end. For instance, if you want to reverse the
order of the first three rows you only have to use:

Order Custom 3, 2, 1

You can leave out the rest of the rows. If you have 10 rows and want to switch the last two, you
have to list all the ids like this:

Order Custom 1, 2, 3, 4, 5, 6, 7, 8, 10, 9

To make this more compact, use the following syntax:

Order Custom 1:8, 10, 9

Indicating a Range of Values

Use a colon ( : ) to indicate a range of values, such as:

Long form:
Order Custom 2, 5, 6, 7, 8, 9, 10, 1, 3, 4

Short form:
Order Custom 2, 5:10, 1, 3, 4
Order Custom 2, 5:10, 1, 3:4 (same as above but also valid)
Order Custom 2, 5:10, 1 (same as above but also valid)

Long form:
Order Custom 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 18,
19, 20, 11

Short form:
Order Custom 1:10, 12:20, 11

MapBasic 15.2 Reference 216

 A to Z MapBasic Language Reference

The list of values cannot have duplicates that will cause an error. The following causes an error:

Order Custom 1:5, 8, 4:7

This is because row ids 4 and 5 are duplicates. To see this, expand the syntax as follows (which
causes an error):

Order Custom 1, 2, 3, 4, 5, 8, 4, 5, 6, 7

The alternate syntax can be used when creating or altering a legend in the Legend window. For
workspaces, the short syntax is used when legends in the Legend window have more than 50 rows
with a custom order.

Create Ellipse statement

Purpose
Creates an ellipse or circle object. You can issue this statement from the MapBasic window in
MapInfo Pro.

Syntax

Create Ellipse
[ Into { Window window_id | Variable var_name } ]
( x1, y1 ) ( x2, y2 )
[ Pen... ]
[ Brush... ] [ Priority n ] [ Name framename ]

window_id is a window identifier.

var_name is the name of an existing object variable.
x1, y1 specifies one corner of the rectangle which the ellipse will fill.
x2, y2 specifies the opposite corner of the rectangle.
Pen is a valid Pen clause to specify a line style.
Brush is a valid Brush clause to specify fill style.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
framename is a string representing the name for this item in a Layout window.

Description
The Create Ellipse statement creates an ellipse or circle object. If the object's Minimum Bounding
Rectangle (MBR) is defined in such a way that the x-radius equals the y-radius, the object will be a
circle; otherwise, the object will be an ellipse.

MapBasic 15.2 Reference 217

 A to Z MapBasic Language Reference

If the statement includes the optional Into Variable clause, the object will be stored in the specified
object variable. If the Into clause specifies a window identifier, the object will be stored in the
appropriate place in the window (for example, in the editable layer of a Map window). If the Into
clause is not provided, MapBasic attempts to store the object in the topmost window; if objects may
not be stored in the topmost window (for example, if the topmost window is a grapher) no object will
be created.
The x and y parameters use whatever coordinate system MapBasic is currently using. By default,
MapBasic uses a Latitude/Longitude coordinate system, although the Set CoordSys statement
can re-configure MapBasic to use a different coordinate system. Note that MapBasic's coordinate
system is independent of the coordinate system of any Map window. Objects created on a Layout
window, however, are specified in paper units: each x-coordinate represents a distance from the
left edge of the page, while each y-coordinate represents the distance from the top edge of the
page. For details about paper units, see Set Paper Units statement. By default, MapBasic uses
inches as the default paper unit. To use a different paper unit, use the Set Paper Units statement.
Before creating objects on a Layout window, you must issue a Set CoordSys Layout statement.
The optional Pen clause specifies a line style. If no Pen clause is specified, the Create Ellipse
statement uses the current MapInfo Pro line style (the style which appears in the Line Style dialog
box). Similarly, the optional Brush clause specifies a fill style.
When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of
frames to a unique set of values beginning with one (1). Use the Priority clause to assign the Z-Order
of the newly created object frame on the Layout window.
The Name clause assigns a name to a frame in the Layout window. If a name is assigned, it is
written to the workspace (WOR) file and the workspace version updates to 1500.
See Also:
Brush clause, CreateCircle() function, Insert statement, Pen clause, Update statement

Create Frame statement

Purpose
Creates a new frame in a layout. You can issue this statement from the MapBasic window in MapInfo
Pro.

Syntax

Create Frame
[ Into { Window window_id | Variable var_name } ]
( x1, y1 ) ( x2, y2 )
[ Pen... ]
[ Brush... ]
[ Priority n ]
[ Name framename ]
[ Title title ]

MapBasic 15.2 Reference 218

 A to Z MapBasic Language Reference

[ From Window contents_win_id ]

[ FillFrame { On | Off } ]

window_id is an integer window identifier.

var_name is the name of an Object variable.
x1, y1 specifies one corner of the new frame to create.
x2, y2 specifies the other corner.
Pen is a valid Pen clause to specify a line style.
Brush is a valid Brush clause to specify fill style.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window. When
creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of frames to
a unique set of values beginning with 1.
framename is a string representing the name for this image frame in a layout designer. If a name
is assigned to a frame in the Layout window, it will be written to the WOR. When the Name clause
is written to the WOR, the workspace version is updated to version 1500.
title is a string identifying the frame contents (for example, "WORLD Map"); not needed if the From
Window clause is used.
contents_win_id is an integer window identifier indicating which window will appear in the frame.

Description
The Create Frame statement creates a new frame within an existing layout window. This statement
works with both Layout windows and the older (classic) Layout windows. If no window_id is specified,
the new frame is added to the topmost layout window.
If you use non-Earth coordinate (X, Y) values to position the frame, an error displays. Before creating
objects on a layout, you must issue a Set CoordSys Layout statement.
The window_id parameter specifies which layout window to add a new frame to and the
contents_win_id parameter specifies which window will appear in the new frame. To obtain a window
identifier, call the FrontWindow() function immediately after opening a window, or call the
WindowID() function at any time after the window's creation.
Frames in a Layout window cannot be in a negative position past the top or past the left edge of
the layout. MapInfo Pro adjusts a negative X or Y value to make it zero (0) when placing the frame.
(The classic Layout window does allow negative position values.)
The Pen clause dictates what line style will be used to display the frame, and the Brush clause
dictates the fill style used to fill the frame window.
The Title clause provides an alternate syntax for specifying which window appears in the frame.
For example, to identify a Map window that displays the table WORLD, the Title clause should read
Title "WORLD Map". If the title string does not refer to an existing window, or if title is an empty

MapBasic 15.2 Reference 219

 A to Z MapBasic Language Reference

string (""), the frame will be empty. If you specify both the Title clause and the From Window
clause, the latter clause takes effect.
Use the From Window clause to specify which window should appear inside the frame. For example,
to make a Map window appear inside the frame, specify From Window id_map (where id_map is
an integer variable containing the Map window identifier). A window must already be open before
you can create a frame containing the window.
The FillFrame clause controls how the window fills the frame. If you specify FillFrame On, the
entire frame is filled with an image of the window. If you specify FillFrame Off (or if you omit the
FillFrame clause entirely), the aspect ratio of the window affects the appearance of the frame; in
other words, re-sizing a Map window to be tall and thin causes the frame to appear tall and thin.
Between sessions, MapInfo Pro preserves layout window settings by storing Create Frame
statements in the workspace file. To see an example of the Create Frame statement, create a
layout, save the workspace, and examine the workspace file in a text editor.
Note: When working with an existing layout, you can get the window ID of a map frame in the
layout by calling the LayoutItemInfo() function with the LAYOUT_ITEM_INFO_WIN attribute.

Example
The following examples show how to create a frame for a Map window's thematic legend, or
Cartographic Legend window.
Theme Legend windows are a special case. To create a frame for a Theme Legend window, you
must use the Title clause instead of the From Window clause.

Dim i_layout_id, i_map_id As Integer

Dim s_title As String

' here, you would store the Map window's ID in i_map_id,

' and store the Layout window's ID in i_layout_id.
' To obtain an ID, call FrontWindow() or WindowID().

s_title = "Theme Legend of " + WindowInfo(i_map_id, WIN_INFO_NAME)

Set CoordSys Layout Units "in"
Create Frame
Into Window i_layout_id
(1,2) (4, 5)
Title s_title

To create a frame for a Map window's cartographic legend, you should use the From Window
clause since there may be more than one cartographic legend window per map.

Dim i_cartlgnd_id As Integer

' here, you would store the Cartographic Legend window's ID

' in i_cartlgnd _id,
' To obtain an ID, call FrontWindow() or WindowID().

MapBasic 15.2 Reference 220

 A to Z MapBasic Language Reference

Create Frame
Into Window i_layout_id
(1,2) (4, 5)
From Window i_cartlgnd_id

See Also:
Brush clause, Insert statement, Layout statement, Pen clause, Set CoordSys statement, Set
Layout statement, Update statement

Create Empty Frames

The Create Frame statement can also be used to create empty frames for the Layout window.
Empty frames are used to add template functionality for Layouts and create place-holders at any
position, of any valid frame size.

Syntax

Create Frame
[ Into { Window window_id | Variable var_name } ]
( x1, y1 ) ( x2, y2 )
[ Pen... ]
[ Brush... ]
[ Priority n ]
[ Name framename ]

If window_id refers to a Layout window, a new empty frame will be created. If it refers to a classic
Layout window, the legacy empty frame will still be created.
If Name is omitted the default text will be "" (empty string). Names will be displayed in the center of
the frame. Long names (names wider than the current width of the empty frame) will wrap.
If Pen is omitted default pen will be a single pixel solid black line.
If Brush is omitted default brush will be a transparent brush (no fill).If Priority is omitted the frame
is added as the topmost.
The empty frame is counted as a frame like any other and added to the frame count returned by
LayoutInfo().The Pen, Brush, Name, and Priority properties can be modified after the frame is created
using Alter Designer Frame statement. Position and size can also be modified using Alter Designer
Frame or by clicking and dragging the frame in the GUI. The frame border and fill (pen and brush)
can be modified in the GUI using the Frame Properties dialog.

Adding Content to Empty Frames

Only maps and browsers can be inserted into empty frames. There are two ways of inserting a map
or browser window into an empty frame:

MapBasic 15.2 Reference 221

 A to Z MapBasic Language Reference

1. Using the Set Designer Frame statement

Set Designer Frame

[ Window layout_window_id ]
[ ID empty_frame_id ]
From { Window map_or_browser_window_id }

If ID is an empty frame, then when followed by From Window clause, the empty frame is populated
by a clone of the original map or browser.
2. Using the Map From and Browse From statements
Use these statements to insert currently open tables into the empty frame. For example,

Map From World, World_Cities Into Window layout_win_id Id empty_frame_id

This will create a map for the open tables called World and World_Cities and insert it into the
empty frame in the Layout Designer window. A default view of the map will be displayed. The
frame properties already set for the empty frame will also be retained (pen, brush, position, size,
name, and z-order).

Reusing the Empty Frame

To reuse a frame after it has been filled with content, it needs to be emptied.

Set Designer Frame [ Window layout_window_id ] Id { frame_id } Clear

This leaves an empty frame of the same size and position as the content it just contained, and
retains the name currently assigned to it. The content itself is destroyed; meaning, the map or
browser goes away. Other frame properties such as the border pen, fill brush, and z-order remain
unchanged.
Browsers, Maps, Legends, Shapes, Images, and Text can be removed using this command. The
command can also be used on an empty frame. If you clear a Map frame and it has legend frames
associated with it, the legend frames will be removed from the layout.

Create Grid statement

Purpose
Produces a raster grid file, which MapBasic displays as a raster table in a Map window. You can
issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Grid
From tablename
With expression [ Ignore value_to_ignore ]

MapBasic 15.2 Reference 222

 A to Z MapBasic Language Reference

Into filespec [ Type grid_type ]

[ Coordsys... ]
[ Clipping { Object obj } | { Table tablename } ]
Inflect num_inflections [ By Percent ] at
color : inflection_value [ color : inflection_value ...]
[ Round rounding_factor ]
{[ Cell Size cell_size [ Units distance_unit ]] | [ Cell Min n_cells
]}
[ Border numcells ]
Interpolate With interpolator_name Version version_string
Using num_parameters parameter_name : parameter_value
[ parameter_name : parameter_value ... ]

tablename is the "alias" name of an open table from which to get data points.
expression is the expression by which the table will be shaded, such as a column name.
value_to_ignore is a value to be ignored; this is usually zero. No grid theme will be created for a
row if the row's value matches the value to be ignored.
filespec specifies the fully qualified path and name of the new grid file. It will have a .MIG extension.
grid_type is a string expression that specifies the type of grid file to create. By default, .MIG format
files are created using "mig.ghl". If using a custom grid handler, then supply the name of that custom
grid handler, such as "dted.ghl".
Coordsys is an optional CoordSys clause which is the coordinate system that the grid will be created
in. If not provided, the grid will be created in the same coordinate system as the source table. Refer
to CoordSys clause for more information.
obj is an object to clip grid cells to. Only the portion of the grid theme within the object will display.
If a grid cell is not within the object, that cell value will not be written out and a null cell is written in
its place.
tablename is the name of a table of region objects which will be combined into a single region object
and then used for clipping grid cells.
num_inflections is a numeric expression, specifying the number of color:inflection_value pairs.
color is a color expression of, part of a color:value inflection pair.
inflection_value is a numeric expression, specifying the value of a color:inflection_value pair as a
number or a percentage.
rounding_factor is a numeric expression, specifying the rounding factor applied to the inflection
values.
cell_size is a numeric expression, specifying the size of a grid cell in distance units.
distance_unit is a string expression specifying the units for the preceding cell size. This is an optional
parameter. If not present, the distance units from the table's coordinate system are used.
n_cells is a numeric expression that specifies the height or width of the grid in cells only.

MapBasic 15.2 Reference 223

 A to Z MapBasic Language Reference

numcells defines the number of cells to be added around the edge of the original grid bounds.
numcells will be added to the left, right, top, and bottom of the original grid dimensions.
interpolator_name is a string expression specifying the name of the interpolator to use to create the
grid. MapInfo built-in interpolators are "IDW" or "TIN."
version_string is a string expression specifying the version of the interpolator that the parameters
are meant for. (Version 100 of the IDW interpolator shipped with MapInfo Pro 5.0 and Version 200
of the TIN and IDW interpolators shipped with MapInfo Pro 5.5 and later.)
num_parameters is a numeric expression, that specifies the number of parameter_name:
parameter_value pairs to use.
• parameter_name is a string expression, specifying the name part of this pair.
• parameter_value is a numeric expression, specifying the value part of this pair.

Description
A grid surface theme is a continuous raster grid produced by an interpolation of point data. The
Create Grid statement takes a data column from a table of points, and passes those points and
their data values to an interpolator. The interpolator produces a raster grid file, which MapBasic
displays as a raster table in a Map window.
The Create Grid statement reads (x, y, z) values from the table specified in the From clause. It gets
the z values by evaluating the expression specified in the With clause with respect to the table.
The dimensions of the grid can be specified in two ways. One is by specifying the size of a grid cell
in distance units, such as miles. The other is by specifying a minimum height or width of the grid in
terms of grid cells. For example, if you wanted the grid to be at least 200 cells wide by 200 cells
high, you would specify "cell min 200". Depending on the aspect ratio of the area covered by the
grid, the actual grid dimensions would not be 200 by 200, but it would be at least that wide and high.
By Percent at specifies that the subsequent color:Inflection_value pairs represent a color value
and Percentage value. If not used, then the Inflection_value represents a numeric value such as
elevation or temperature.
For more about grids, see Grid Description. For details about specific interpolators, see IDW
Interpolator, and TIN Interpolator.

Example

Open Table "C:\States.tab" Interactive

Map From States
Open Table "C:\Us_elev.tab" Interactive
Add Map Auto Layer Us_elev
set map redraw off
Set Map Layer 1 Display Off
set map redraw on

create grid
from Us_elev

MapBasic 15.2 Reference 224

 A to Z MapBasic Language Reference

with Elevation_FT
into "C:\Us_elev_grid"
clipping table States
inflect 5 at
RGB(0, 0, 255) : 13
RGB(0, 255, 255) : 3632.5
RGB(0, 255, 0) : 7252
RGB(255, 255, 0) : 10871.5
RGB(255, 0, 0) : 14491
cell min 200
interpolate
with "IDW" version "100"
using 4
"EXPONENT": "2"
"MAX POINTS": "25"
"MIN POINTS": "1"
"SEARCH RADIUS": "100"

See Also:
GetGridCellValue() function, GridTableInfo(), IsGridCellNull() function, OverlayNodes() function,
RasterTableInfo() function, Set Map statement

Grid Description
A grid surface theme is a continuous raster grid produced by an interpolation of point data. The
Create Grid statement takes a data column from a table of points and passes those points and their
data values to an interpolator. The interpolator produces a raster grid file, which MapBasic displays
as a raster table in a Map window. The Create Grid statement reads (x, y, z) values from the table
specified in the From tablename clause. It gets the z values by evaluating the expression specified
in the With clause (a column name) with respect to the table and computes a grid cell value using
the settings provided for the specific interpolator chosen with these points.
The dimensions of the grid can be specified in two ways. One is by specifying the size of a grid cell
in distance units, such as miles, meters, feet, and so on. The other is by specifying a minimum
height or width of the grid by number of grid cells. For example, if you wanted the grid to be at least
200 cells wide by 200 cells high, you would specify "cell min 200". Depending on the aspect ratio
of the area covered by the grid, the actual grid dimensions might not be exactly 200 by 200, but it
would be at least that wide and high.
Example IDW Interpolation with inflections set at certain elevation values:

Open Table "C:\MyData\States.tab" Interactive

Map From States
Open Table "C:\ MyData\Us_elev.tab" Interactive
Add Map Auto Layer Us_elev
Set map redraw off
Set Map Layer 1 Display Off
Set map redraw on
Create Grid

MapBasic 15.2 Reference 225

 A to Z MapBasic Language Reference

From Us_elev
with Elevation_FT
ignore 0
into "C:\ MapData\Us_elev_grid.mig"
Type "mig.ghl"
CoordSys Earth Projection 1, 74
clipping table States
Inflect 6 at
RGB(64, 0, 128) : -32808
RGB(0, 128, 192) : -16404
RGB(151, 255, 239) : -98
RGB(254, 248, 199) : 33
RGB(244, 171, 100) : 6566
RGB(235, 95, 1) : 32808
round 100
cell min 200
interpolate
with "IDW" version "100"
using 7
"AGGREGATION METHOD": "1"
"BORDER": "0"
"CELL SIZE": "8"
"EXPONENT": "2"
"MAX POINTS": "25"
"MIN POINTS": "1"
"SEARCH RADIUS": "800"

TIN Interpolator example with inflections set at percentage values:

inflect 5 by Percent at
RGB(0, 0, 255) : 0
RGB(0, 255, 255) : 25
RGB(0, 255, 0) : 50
RGB(255, 255, 0) : 75
RGB(255, 0, 0) : 100
Round 10
cell min 200
interpolate
with "TIN" version "100"
using 8
"BORDER": "0"
"CELL SIZE": "15"
"DISTANCE": "80"
"EXPONENT": "2"
"FEATURE ANGLE": "45"
"SEARCH RADIUS": "53"
"TOLERANCE": "0.01 "
"READ ONLY": "T"

MapBasic 15.2 Reference 226

 A to Z MapBasic Language Reference

Grid Appearance and Inflection Methods

Once the cell values are calculated, MapInfo Pro groups them into a color spectrum that is bounded
by the minimum and maximum values in the table defined by the number of inflection color and
value pairs defined.
You can control how the color is spread by specifying an inflection method and the number of
inflection points. The number of inflections must be between 2 and 255. You can also apply a
rounding factor to the inflection values. When interpolating via the user interface, you have four
choices of computing inflection values:
• Equal Cell Count - Sets the inflections so that approximately an equal number of grid cells fall
between each inflection value.
• Equal Value Ranges - Spreads the inflections evenly between the minimum and maximum values
of the data range.
• Custom Cell Count - Use this method to specify your own percentages.
• Custom Value Ranges - Use this method to specify your own values.
When using the Create Grid statement, you must compute inflection color and values manually
using your own methods to compute values from your input data.

Grid Templates
When creating a Grid thematic map in MapInfo Pro, the Grid default template assigns blue to the
minimum value and red to the maximum value. These minimum and maximum values are also
expressed as percentages of the range. These color settings/values are known as inflection points
and will display in the legend with a particular color, value and percentage. If a cell has the exact
value as the inflection point, it will display that color on the map. A cell value that falls between two
inflection points displays with the color that is in between the colors of those inflection points.
See Also:
IDW Interpolator, TIN Interpolator

IDW Interpolator
The IDW Interpolator is best suited for data values that produce arbitrary values over the grid, that
is, data that does not have any relationship or influence over neighboring data values, such as
population. This method of interpolation also works well for sparse data. The IDW Interpolator
calculates the value of grid cells that cover the mapping area. Each data point value from the source
table that is considered in the calculation for a cell value is weighted by its distance from the center
of the cell. Because the interpolation is an inverse distance weighting calculation, the farther the
point is from the cell, the less influence its value will have on the resulting cell value. MapInfo Pro's
grid mapping process begins by determining the minimum bounding rectangle (MBR) of the source
table. The grid is divided into equal sized square cells of some size. For example, using the Grid
default template, the States table in MapInfo Pro's sample data set creates a grid dimension of 200
cells by 303 cells. By calculating the number of cells in the grid and knowing the dimension of the
MBR, MapInfo Pro determines that each cell needs to be 18.1 by 18.1 miles square. (The cell size

MapBasic 15.2 Reference 227

 A to Z MapBasic Language Reference

will be in whatever distance units set for the Map window. To change the units, select Map >
Options > Map Units.)
The IDW Interpolator settings can be controlled via the Settings button in the Create Thematic
Map - Step 3 of 3 dialog when creating a grid thematic map. The cell size number in this interpolator
settings dialog represents both the height and width of the cell. Any change to the cell size will result
in an automatic update of the grid dimensions. With the cell size and the source points and values
known, MapInfo Pro calculates a value for each cell. This value is determined by calculating a
distance-weighted average of the points that lie within the specified search radius. Points are inversely
weighted by their distance from the center of the cell. In the IDW Interpolator, the exponent determines
how much influence each point will have on the result. The higher the exponent, the greater the
influence closer points will have on the cell value. Exponents can range from one to 10. You can
also choose an aggregation method for the z-values of coincident source data points (ones that fall
within area of same grid cell). Coincident data points can be aggregated by average, count, sum,
min, and max. Average method is aggregation default.

IDW Interpolator Settings for Create Grid Statement

For the MapInfo Pro IDW Interpolator, when specifying the following parameters in the Create Grid
Statement syntax:

Using num_parameters parameter_name : parameter_value

[ parameter_name : parameter_value ... ]

the following parameter_name : parameter_values may be used.

• "EXPONENT": "number" - Minimum value 1, maximum value 10, default exponent is 2. The higher
the number, the greater the influence closer points have on the cell value being computed.
• "SEARCH RADIUS": "number" - Must be greater than zero, default setting is 10 units.
• "MIN POINTS": "number" - Must be greater than zero, default setting is 1. The minimum points
required for calculating value of a grid cell.
• "MAX POINTS": "number" - Must be greater than zero, default setting is 25. The maximum points
used for calculating value of a grid cell.
• "GRID HEIGHT": "number" - Must be greater than zero, default setting is 100. The minimum height
of grid in cells. The result is affected by aspect ratio, but height in cells result should be a minimum
of this value.
• "GRID WIDTH": "number" - Must be greater than zero, default setting is 100. The minimum width
of grid in cells. The result is affected by aspect ratio, but width in cells result should be a minimum
of this value.
• "CELL SIZE": "number" - Size of grid cell in distance units. Must be greater than zero and default
size is 100, if not specified.
• "BORDER": "number" - Number of cells beyond the table's bounding rectangle by which to expand
the grid. This is useful if you are interpolating with data from a point table but are clipping to a
region table.
• "AGGREGATION METHOD": "number" - Aggregation method of coincident points located in same
cell. The default is aggregation method is Average or 0. Most of the parameters for the interpolator

MapBasic 15.2 Reference 228

 A to Z MapBasic Language Reference

correspond to controls in the interpolator settings dialog box. Instead of passing a string for
aggregation, however, a number will be used.

Average 0

Count 1

Minimum 2

Maximum 3

Sum 4

If parameter name : parameter is not provided, then a default value is used. If all default interpolator
settings are desired, then set Using num_parameters to 0.
See Also:
Create Grid statement, READ ONLY Parameter for TIN and IDW Interpolators

TIN Interpolator
The TIN Interpolator works best for terrain data and for data points that have a linear progression
or relationship to each other across the grid, such as elevation or temperature. The TIN Interpolator
produces triangles from a network of points that more closely reproduces the original map terrain
than the IDW Interpolator. It draws lines between points, dividing them into triangles and connecting
all the points that it can. It creates a mesh of connectivity so that the grid points can be interpolated.
The interpolation is not influenced by the neighboring original data values, so you do not get the
"false bumping" of data that you can get with the IDW Interpolator.
The TIN settings can be manipulated to give more or less detail to the map terrain. The Tolerance
setting controls whether closely spaced points are discarded. The tolerance is a fraction of the
diagonal length of the bounding box of the points. The Distance value controls the output. For
non-zero distance values, only edges or triangles contained within a sphere centered at mesh
vertices are output. This is useful to constrain the triangulated irregular network to a specified
distance; otherwise, the triangulation will cross concave regions. The Feature Angle setting controls
the angle (in degrees) that defines a sharp edge. This setting is used for smoothing the final grid.
If the difference in angle across neighboring polygons is greater than this value, the shared edge
is considered "sharp."
The TIN Interpolator settings can be controlled via the Settings button in the Create Thematic Map
- Step 3 of 3 dialog when creating a grid thematic map. The cell size number in this interpolator
settings dialog represents both the height and width of the cell like the IDW method. Any change to
the cell size will result in an automatic update of the grid dimensions.

MapBasic 15.2 Reference 229

 A to Z MapBasic Language Reference

TIN Interpolator Settings for Create Grid Statement

For the MapInfo Pro TIN Interpolator, when specifying the following parameters in the Grid Statement
syntax:

Using num_parameters parameter_name : parameter_value

[ parameter_name : parameter_value ... ]

the following parameter_name : parameter_values may be used:

• "TOLERANCE": "number" – Must be equal to or greater than .0001 and less than or equal to .01,
default setting is .005.
• "DISTANCE": "number" – Must be greater than zero and less than height and width of grid .
• "FEATURE ANGLE": "number" – Must be equal to or greater than zero and equal to or less than
180, default setting is 25 degrees.
• "MIN POINTS": "number" – Must be greater than zero, default setting is 1. The minimum points
required for calculating value of a grid cell.
• "MAX POINTS": "number" – Must be greater than zero, default setting is 25. The maximum points
used for calculating value of a grid cell.
• "GRID HEIGHT": "number" – Must be greater than zero, default setting is 100. The minimum height
of grid in cells. The result is affected by aspect ratio, but height in cells result should be a minimum
of this value.
• "GRID WIDTH": "number" – Must be greater than zero, default setting is 100. The minimum width
of grid in cells. The result is affected by aspect ratio, but width in cells result should be a minimum
of this value
• "CELL SIZE": "number" – Size of grid cell in distance units. Must be greater than zero and default
size is 100, if not specified.
Note: If parameter name : parameter is not provided, then a default value is used. If all default
interpolator settings are desired, then set Using num_parameters to 0.

See Also:
READ ONLY Parameter for TIN and IDW Interpolators

READ ONLY Parameter for TIN and IDW Interpolators

If you want to flag a grid as read-only, so that it cannot be altered or re-interpolated, specify "READ
ONLY": "T" for the parameter name : parameter value pair, which can be passed with either MapInfo
Pro TIN or IDW interpolators. If this parameter value is used, then the metadata tag:

"\Interpolator\Parameter\READ ONLY" = "0"

is written into the TAB file and the user will not be able to modify or re-interpolate the grid via the
user interface.

MapBasic 15.2 Reference 230

 A to Z MapBasic Language Reference

Create Index statement

Purpose
Creates an index for a column in an open table. You can issue this statement from the MapBasic
window in MapInfo Pro.

Syntax

Create Index On table ( column )

table is the name of an open table.

column is the name of a column in the open table.

Description
The Create Index statement creates an index on the specified column. MapInfo Pro uses Indexes
in operations such as Find. Indexes also improve the performance of queries in general.
Note: MapInfo Pro cannot create an index if the table has unsaved edits. Use the Commit Table
statement to save edits.

Example
The following example creates an index for the "Capital" field of the World table.

Open Table "world" Interactive

Create Index on World(Capital)

See Also:
Alter Table statement, Create Table statement, Drop Index statement, Commit Table statement

Create Legend statement

Purpose
Creates a new Theme Legend window tied to the specified Map window. You can issue this statement
from the MapBasic window in MapInfo Pro.
For MapInfo Pro versions 5.0 and later, the Create Cartographic Legend statement allows you to
create and display cartographic style legends. Refer to the Create Cartographic Legend statement
for more information.

MapBasic 15.2 Reference 231

 A to Z MapBasic Language Reference

Syntax

Create Legend
[ From Window window_ID ]
[ { Show | Hide } ]

window_ID is an integer, representing a MapInfo Pro window ID for a Map window.

Description
This statement creates a special floating, Thematic Legend window, in addition to the standard
MapInfo Pro Legend window. (To open MapInfo Pro's standard Legend window, use the Open
Window Legend statement.)
The Create Legend statement is useful if you want the Legend of a Map window to always be
visible, even when the Map window is not active. Also, this statement is useful in "Integrated Mapping"
applications, where MapInfo Pro windows are integrated into another application, such as a Visual
Basic application. For information about Integrated Mapping, see the MapBasic User Guide.
If you include the From Window clause, the new Theme Legend window is tied to the window that
you specify; otherwise, the new window is tied to the most recently used Map.
If you include the optional Hide keyword, the window is created in a hidden state. You can then
show the hidden window by using the Set Window...Show statement.
After you issue the Create Legend statement, determine the new window's integer ID by calling
WindowID( 0 ). Use that window ID in subsequent statements (such as the Set Window
statement).
The new Theme Legend window is created according to the parent and style settings that you specify
through the Set Next Document statement.
See Also:
Create Cartographic Legend statement, Open Window statement, Set Next Document
statement, Set Window statement

CreateLine() function
Purpose
Returns an Object value representing a line. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

CreateLine( x1, y1, x2, y2 )

x1 is a float value, indicating the x-position (for example,) of the line's starting point.
y1 is a float value, indicating the y-position (for example, Latitude) of the line's starting point.

MapBasic 15.2 Reference 232

 A to Z MapBasic Language Reference

x2 is a float value, indicating the x-position of the line's ending point.

y2 is a float value, indicating the y-position of the line's ending point.

Return Value
Object

Description
The CreateLine() function returns an Object value representing a line. The x and y parameters use
the current coordinate system. By default, MapBasic uses a Longitude/Latitude coordinate system.
Use the Set CoordSys statement to choose a new system.
The line object will use whatever Pen style is currently selected. To create a line object with a specific
Pen style, you could issue the Set Style statement before calling CreateLine() or you could issue
a Create Line statement, with an optional Pen clause.
The line object created through the CreateLine() function could be assigned to an Object variable,
stored in an existing row of a table (through the Update statement), or inserted into a new row of
a table (through an Insert statement). If you need to create objects on a Layout window, you must
first issue a Set CoordSys Layout statement.

Example
The following example uses the Insert statement to insert a new row into the table Routes. The
CreateLine() function is used within the body of the Insert statement.

Open Table "Routes"

Insert Into routes (obj)
Values (CreateLine(-72.55, 42.431, -72.568, 42.435))

See Also:
Create Line statement, Insert statement, Update statement

Create Line statement

Purpose
Creates a line object. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Line
[ Into { Window window_id | Variable var_name } ]
( x1, y1) ( x2, y2)
[ Pen... ] [ Priority n ] [ Name framename ]

window_id is a window identifier.

MapBasic 15.2 Reference 233

 A to Z MapBasic Language Reference

var_name is the name of an existing object variable.

x1, y1 specifies the starting point of a line.
x2, y2 specifies the ending point of the line.
The Pen clause specifies a line style.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
framename is a string representing the name for this item in a Layout window.

Description
The Create Line statement creates a line object.
If the statement includes the optional Into Variable clause, the object will be stored in the specified
object variable. If the Into clause specifies a window identifier, the object will be stored in the
appropriate place in the window (for example, in the editable layer of a Map window). If the Into
clause is not provided, MapBasic will attempt to store the object in the topmost window; if objects
may not be stored in the topmost window (for example, if the topmost window is a grapher) no object
will be created.
The x and y parameters use whatever coordinate system MapBasic is currently using. By default,
MapBasic uses a Longitude/Latitude coordinate system, although the Set CoordSys statement
can re-configure MapBasic to use a different coordinate system. Note that MapBasic's coordinate
system is independent of the coordinate system of any Map window. Objects created on a Layout
window, however, are specified in paper units: each x-coordinate represents a distance from the
left edge of the page, while each y-coordinate represents the distance from the top edge of the
page. For details about paper units, see Set Paper Units statement. By default, MapBasic uses
inches as the default paper unit. To use a different paper unit, use the Set Paper Units statement.
Note: If you need to create objects on a Layout window, you must first issue a Set CoordSys
Layout statement.

The optional Pen clause specifies a line style; see Pen clause for more details. If no Pen clause
is specified, the Create Line statement will use the current MapInfo Pro line style.
When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of
frames to a unique set of values beginning with one (1). Use the Priority clause to assign the Z-Order
of the newly created object frame on the Layout window.
The Name clause assigns a name to a frame in the Layout window. If a name is assigned, it is
written to the workspace (WOR) file and the workspace version updates to 1500.
See Also:
CreateLine() function, Insert statement, Pen clause, Update statement

MapBasic 15.2 Reference 234

 A to Z MapBasic Language Reference

Create Map statement

Purpose
Modifies the structure of a table, making the table mappable. You can issue this statement from the
MapBasic window in MapInfo Pro.

Syntax

Create Map
For table [ BlockSize block_size ]
[ CoordSys... ] Using from_table]

table is the name of an open table.

from_table is the name of an open table from where to copy a coordinate system.
block_size is a value of between 0 to 32768. If not specified, the default value is 16384. If the value
is less than 512, it rounds up to 512.

Description
The Create Map statement makes an open table mappable, so that it can be displayed in a Map
window. This statement does not open a new Map window. To open a new Map window, use the
Map statement.
You should not perform a Create Map statement on a table that is already mappable; doing so
will delete all map objects from the table. If a table already has a map attached, and you wish
to permanently change the projection of the map, use a Table As statement. Alternately, if you
wish to temporarily change the projection in which a map is displayed, issue a Set Map statement
with a CoordSys clause. The Create Map statement does not work on linked tables. To make a
linked table mappable, use the Server Create Map statement.
The BlockSize clause have a value of zero (0) to 32768. If not specified, the default is 16384. If the
value is less than 512, it rounds up to 512. Generally, the larger the block size, the faster the data
transfer rate. When converting from NativeX (MapInfo Extended) format to Native (MapInfo) format,
the original block size of the NativeX file is preserved. Users can specify a new block size when
committing from NativeX to Native format.
CoordSys is a coordinate system clause; see CoordSys clause and refer to the next section,
Specifying the Coordinate System.

Specifying the Coordinate System

Use one of the following two methods to specify a coordinate system:
• Provide the name of an already open mappable table as the from_table portion of the Using
clause. In this case, the coordinate system used will be identical to that used in the from_table.
The from_table must be a currently open table, and must be mappable or an error will occur.

MapBasic 15.2 Reference 235

 A to Z MapBasic Language Reference

• Explicitly supply the coordinate system information through a CoordSys clause (set in preferences).
If you omit both the CoordSys clause and the Using clause, the table will use the current MapBasic
coordinate system.
Note that the CoordSys clause affects the precision of the map. The CoordSys clause includes
a Bounds clause, which sets limits on the minimum and maximum coordinates that can be stored
in the map. If you omit the Bounds clause, MapInfo Pro uses default bounds that encompass the
entire Earth (in which case, coordinates are precise to one millionth of a degree, or approximately
4 inches). If you know in advance that the map you are creating is limited to a finite area (for example,
a specific metropolitan area), you can increase the precision of the map's coordinates by specifying
bounds that confine the map to that area. For a complete listing of the CoordSys syntax, see
CoordSys clause.
See Also:
Commit Table statement, CoordSys clause, Create Table statement, Drop Map statement,
Map statement, Server Create Map statement, Set Map statement

Create Map3D statement

Purpose
Creates a 3DMap with the desired parameters. You can issue this statement from the MapBasic
window in MapInfo Pro.

Syntax

Create Map3D
[ From Window window_id | MapString mapper_creation_string ]
[ Camera [ Pitch angle | Roll angle | Yaw angle | Elevation angle ] |
[ Position ( x, y, z ) | FocalPoint ( x, y, z ) ] |
[ Orientation ( vu_1, vu_2, vu_3, vpn_1, vpn_2, vpn_3,
clip_near, clip_far )]]
[ Light [ Position ( x, y, z ) | Color lightcolor ] ]
[ Resolution ( res_x, res_y ) ]
[ Scale grid_scale ]
[ Background backgroundcolor ]
[ Units unit_name ]

window_id is a window identifier a for a Map window which contains a Grid layer. An error message
is displayed if a Grid layer is not found.
mapper_creation_string specifies a command string that creates the mapper textured on the grid.
Camera specifies the camera position and orientation.
angle is an angle measurement in degrees. The horizontal angle in the dialog box ranges from
0-360 degrees and rotates the maps around the center point of the grid. The vertical angle in the
dialog box ranges from 0-90 and measures the rotation in elevation from the start point directly over
the map.

MapBasic 15.2 Reference 236

 A to Z MapBasic Language Reference

Pitch adjusts the camera's current rotation about the x axis centered at the camera's origin.
Roll adjusts the camera's current rotation about the z axis centered at the camera's origin.
Yaw adjusts the camera's current rotation about the y axis centered at the camera's origin.
Elevation adjusts the current camera's rotation about the x axis centered at the camera's focal
point.
Position indicates the camera/light position.
FocalPoint indicates the camera/light focal point.
Orientation specifies the cameras ViewUp (vu_1, vu_2, vu_3), ViewPlane Normal (vpn_1, vpn_2,
vpn_3), and Clipping Range (clip_near, clip_far) (used specifically for persistence of view).
Resolution is the number of samples to take in the x and y directions. These values can increase
to a maximum of the grid resolution. The resolution values can increase to a maximum of the grid
x, y dimension. If the grid is 200x200 then the resolution values will be clamped to a maximum of
200x200. You cannot increase the grid resolution, only specify a subsample value.
grid_scale is the amount to scale the grid in the z direction. A value >1 will exaggerate the topology
in the z direction, a value <1 will scale down the topological features in the z direction.
backgroundcolor is a color to be used to set the background and is specified using the RGB()
function.
unit_name specifies the units the grid values are in. Do not specify this for unit-less grids (for example,
grids generated using temperature or density). This option needs to be specified at creation time.
You cannot change them later with the Set Map3D statement or the Properties dialog box.

Description
Once it is created, the 3DMap window is a standalone window. Since it is based on the same tables
as the original Map window, if these tables are changed and the 3DMap window is manually
"refreshed" or re-created from a workspace, these changes are displayed on the grid. The creation
fails if the window_id is not a Map window or if the Map window does not contain a Grid layer. If
there are multiple grids in the Map window, each will be represented in the 3DMap window.
A 3DMap keeps a Mapper creation string as its texture generator. This string will also be prevalent
in the workspace when the 3DMap window is persisted. The initialization will read in the grid layer
to create 3D geometry and topology objects.

Example

Create Map3D Resolution(75,75)

Creates a 3DMap window of the most recent Map window. It will fail if the window does not contain
any Continuous Grid layers. Another example is:

Create Map3D From Window FrontWindow() Resolution(100,100) Scale 2

Background RGB(255,0,0) Units "ft".

MapBasic 15.2 Reference 237

 A to Z MapBasic Language Reference

Creates a 3DMap window with a Red background, the z units set to feet, a Z scale factor of 2, and
the grid resolution set to 100x100.
See Also:
Set Map3D statement

Create Menu statement

Purpose
Creates a new menu, or redefines an existing menu. In MapInfo Pro 64-bit, this command creates
a new menu in the Menu ribbbon group under the LEGACY tab. You can issue this statement from
the MapBasic window in MapInfo Pro.

Syntax 1

Create Menu newmenuname [ ID menu_id ] [ Context ] As

menuitem [ ID menu_item_id ] [ HelpMsg help ]
{ Calling handler | As menuname }
[ , menuitem ... ]

Syntax 2

Create Menu newmenuname As Default

Note: In MapInfo Pro 64-bit, Syntax 2 above would remove the menu from the menu group.

newmenuname is a string representing the name of the menu to define or redefine.

menuitem is a string representing the name of an item to include on the new menu.
Context is reserved for internal use only; not usable in MapBasic programs.
menu_id is a SmallInt ID number from one to fifteen, identifying a standard menu.
menu_item_id is an integer ID number that identifies a custom menu item.
help is a string that appears on the status bar whenever the menu item is highlighted.
handler is the name of a procedure, or a code for a standard menu command, or a special syntax
for handling the menu event by calling OLE or DDE; see Calling Clause Options. If you specify a
command code for a standard MapInfo Pro Show/Hide command (such as
M_WINDOW_STATISTICS), the menuitem string must start with an exclamation point and include
a caret (^), to preserve the item's Show/Hide behavior.
menuname is the name of an existing menu to include as a hierarchical submenu.

MapBasic 15.2 Reference 238

 A to Z MapBasic Language Reference

Description
If the newmenuname parameter matches the name of an existing MapInfo Pro menu (such as File),
the statement re-defines that menu. If the newmenuname parameter does not match the name of
an existing menu, the Create Menu statement defines an entirely new menu. For a list of the standard
MapInfo Pro menu names, see Alter Menu statement.
The Create Menu statement does not automatically display a newly-created menu; a new menu
will only display as a result of a subsequent Alter Menu Bar statement or Create Menu Bar
statement. However, if a Create Menu statement modifies an existing menu, and if that existing
menu is already part of the menu bar, the change will be visible immediately.
Note: MapInfo Pro can maintain no more than 96 menu definitions at one time, including the menus
defined automatically by MapInfo Pro (File, etc.). This limit is independent of the number of
menus displayed on the menu bar at one time.

The menuitem parameter identifies the name of the menu item. The item's name can contain special
control characters to define menu item attributes (for example, whether a menu item is checkable).
See tables below for details.
The following characters require special handling: slash (/), back slash(\), and less than (<). If you
want to display any of these special characters in the menu or the status bar help, you must include
an extra back slash in the menuitem string or the help string. For example, the following statement
creates a menu item that reads, "Client/Server."

Create Menu "Data" As

"Client\/Server" Calling cs_proc

If a menuitem parameter begins with the character @, the custom menu breaks into two columns.
The item whose name starts with @ is the first item in the second column.
Things to remember when using this command with the MapInfo Pro 64-bit:
1. If the menu with the id already exist in the Legacy tab then all the user addin controls from that
menu would we removed and the menu would be created with new structure.

Assigning Handlers to Custom Menu Items

Most menu items include the Calling handler clause; where handler is either the name of a MapBasic
procedure or a numeric code identifying an MapInfo Pro operation (such as M_FILE_SAVE to specify
the Save Table command). If the user chooses a menu item which has a handler, MapBasic
automatically calls the handler (whether the handler is a sub procedure or a command code). Your
program must Include the file MENU.DEF if you plan to refer to menu codes such as M_FILE_SAVE.
The optional ID clause lets you assign a unique integer ID to each custom menu item. Menu item
IDs are useful if you want to allow multiple menu items to call the same handler procedure. Within
the handler procedure, you can determine which menu item the user chose by calling
CommandInfo(CMD_INFO_MENUITEM). Menu item IDs can also be used by other statements,
such as the Alter Menu Item statement. If a menu item has neither a handler nor a menuname

MapBasic 15.2 Reference 239

 A to Z MapBasic Language Reference

associated with it, that menu item is inert. Inert menu items are used for cosmetic purposes, such
as displaying horizontal lines which break up a menu.

Creating Hierarchical Menus

To include a hierarchical menu on the new menu, use the As sub-clause instead of the Calling
sub-clause. The As sub-clause must specify the name of the existing menu which should be attached
to the new menu. The following example creates a custom menu containing one conventional menu
item and one hierarchical menu.

Create Menu "Special" As

"Configure" Calling config_sub_proc,
"Objects" As "Objects"

When you add a hierarchical menu to the menu, the name of the hierarchical menu appears on the
parent menu instead of the menuitem string.

Properties of a Menu Item

Menu items can be enabled or disabled; disabled items appear grayed out. Some menu items are
checkable, meaning that the menu can display a check mark next to the item. At any given time, a
checkable menu item is either checked or unchecked.
To set the properties of a menu item, include control codes (from the table below) at the start of the
menuitem parameter.

Control code Effect

The menu item is initially disabled. Example: (Close

(

The menu item is a horizontal separator line; such a menu item cannot have a handler. Example:
(- (-

This special code represents the File menu's most-recently-used (MRU) list. It may only appear
($ once in the menu system, and it may not be used on a shortcut menu. To eliminate the MRU

MapBasic 15.2 Reference 240

 A to Z MapBasic Language Reference

Control code Effect

list from the File menu, either delete this code from MAPINFOW.MNU or re-create the File
menu by issuing a Create Menu statement.

This special code represents the Window menu's list of open windows. It may only appear once
(> in the menu system.

Menu item is checkable, but it is initially unchecked.

!
Example: !Confirm Deletion

If a caret (^) appears within the text string of a checkable menu item, the item toggles between
! ... ^ ... alternate text (for example, Show... vs. Hide...) instead of toggling between checked
and unchecked. The text before the caret appears when the item is "checked." Example: !Hide
Status Bar^Show Status Bar

Menu item is checkable, and it is initially checked.

!+
Example: !+Confirm Deletions

Defining Keyboard Shortcuts

Menu items can have two different types of keyboard shortcuts, which let the user choose menu
items through the keyboard rather than by clicking with the mouse.
One type of keyboard shortcut lets the user drop down a menu or choose a menu item by pressing
keys. For example, on MapInfo Pro, the user can press Alt+W to show the Window menu, then
press M (or Alt-M) to choose New Map Window. To create this type of keyboard shortcut, include
the ampersand character (&) in the newmenuname or menuitem string (for example, specify "&Map"
as the menuitem parameter in the Create Menu statement). Place the ampersand immediately
before the character to be used as the shortcut.
The other type of keyboard shortcut allows the user to activate an option without going through the
menu at all. If a menu item has a shortcut key sequence of Alt+F5, the user can activate the menu
item by pressing Alt+F5. To create this type of shortcut, use the following key sequences.

MapBasic 15.2 Reference 241

 A to Z MapBasic Language Reference

Note: The codes in the following tables must appear at the end of a menu item name.

Windows Accelerator Code Effect

Defines a Windows shortcut key which can be activated by pressing the

/W {letter | %number} appropriate key.

Examples: Zap /WZ or Zap /W%120

Defines a Windows shortcut key which also requires the Shift key.
/W# {letter | %number}
Examples: Zap /W#Z or Zap /W#%120

Defines a Windows shortcut key which also requires the Alt key.
/W@ {letter | %number}
Examples: Zap /W@Z or Zap /W@%120

Defines a Windows shortcut key which also requires the Ctrl key.
/W^ {letter | %number}
Examples: Zap /W^Z or Zap /W^%120

To specify a function key as a Windows accelerator, the accelerator code must include a percent
sign (%) followed by a number. The number 112 corresponds to F1, 113 corresponds to F2, etc.
Note: The Create Menu Bar As Default statement removes and un-defines all custom menus
created through the Create Menu statement. Alternately, if you need to un-define one, but
not all, of the custom menus that your application has added, you can issue a statement of
the form Create Menu menuname As Default.

After altering a standard MapInfo Pro menu (for example, "File"), you can restore the menu to its
original state by issuing a Create Menu menuname As Default statement.

Calling Clause Options

The Calling clause specifies what should happen when the user chooses the custom menu command.
The following table describes the available syntax.

Calling clause example Description

If Calling is followed by a numeric code from MENU.DEF,

Calling M_FILE_NEW MapInfo Pro handles the event by running a standard

MapBasic 15.2 Reference 242

 A to Z MapBasic Language Reference

Calling clause example Description

MapInfo Pro menu command (the File > New command, in

this example).

If you specify a procedure name, MapInfo Pro handles the

Calling my_procedure event by calling the procedure.

MapInfo Pro handles the event by making a method call to

Calling OLE "methodname" the OLE Automation object set by the SetCallback
method.

Windows only. MapInfo Pro handles the event by connecting

Calling DDE "server","topic" through DDE to "server|topic" and sending an Execute
message to the DDE server.

In the last two cases, the string sent to OLE or DDE starts with the three letters "MI:" (so that the
server can detect that the message came from MapInfo Pro). The remainder of the string contains
a comma-separated list of the values returned from relevant CommandInfo() function calls. For
complete details on the string syntax, see the MapBasic User Guide.

Examples
The following example uses the Create Menu statement to create a custom menu, then adds the
custom menu to MapInfo Pro's menu bar. This example removes the Window menu (ID 6) and the
Help menu (ID 7), and then adds the custom menu, the Window menu, and the Help menu back to
the menu bar. This technique guarantees that the last two menus will always be Window, and Help.

Declare Sub Main

Declare Sub addsub
Declare Sub editsub
Declare Sub delsub
Sub Main
Create Menu "DataEntry" As
"Add" Calling addsub,
"Edit" Calling editsub,
"Delete" Calling delsub

Alter Menu Bar Remove ID 6, ID 7

Alter Menu Bar Add "DataEntry", ID 6, ID 7
End Sub

The following example creates an abbreviated version of the File menu. The "(" control character
specifies that the Close, Save, and Print options will be disabled initially. The Open and Save
options have Windows accelerator key sequences (Ctrl+O and Ctrl+S, respectively). Note that both

MapBasic 15.2 Reference 243

 A to Z MapBasic Language Reference

the Open and Save options use the Chr$(9) function to insert a Tab character into the menu item
name, so that the remaining text is shifted to the right.

Include "MENU.DEF"

Create Menu "File" As

"New" Calling M_FILE_NEW,
"Open" +Chr$(9)+"Ctrl+O/W^O" Calling M_FILE_OPEN,
"(-",
"(Close" Calling M_FILE_CLOSE,
"(Save" +Chr$(9)+"Ctrl+S /W^S" Calling M_FILE_SAVE,
"(-",
"(Print" Calling M_FILE_PRINT,
"(-",
"Exit" Calling M_FILE_EXIT

If you want to prevent the user from having access to MapInfo Pro's shortcut menus, use a Create
Menu statement to re-create the appropriate menu, and define the menu as just a separator control
code: "(-". The following example uses this technique to disable the Map window's shortcut menu.

Create Menu "MapperShortcut" As "(-"

See Also:
Alter Menu Item statement, Create Menu Bar statement

Create Menu Bar statement

Purpose
Rebuilds the entire menu bar, using the available menus. You can issue this statement from the
MapBasic window in MapInfo Pro.

Syntax 1

Create Menu Bar As

{ menu_name | ID menu_number }
[ , { menu_name | ID menu_number } ... ]

Note: In MapInfo Pro 64-bit, this command creates a new menu group on the LEGACY tab and
each menu is created as a dropdown. Also, if a menu with same name already exists in the
menu group, this command would replace it with the new one.

Syntax 2

Create Menu Bar As Default

Note: In MapInfo Pro 64-bit, Syntax 2 above would remove the whole menu group.

MapBasic 15.2 Reference 244

 A to Z MapBasic Language Reference

menu_name is the name of a standard MapInfo Pro menu, or the name of a custom menu created
through a Create Menu statement.
menu_number is the number associated with a standard MapInfo Pro menu (for example, 1 for the
File menu).

Description
A Create Menu Bar statement tells MapInfo Pro which menus should appear on the menu bar, and
in what order. If the statement omits one or more of the standard menu names, the resultant menu
may be shorter than the standard MapInfo Pro menu. Conversely, if the statement includes the
names of one or more custom menus (which were created through the Create Menu statement),
the Create Menu Bar statement can create a menu bar that is longer than the standard MapInfo
Pro menu.
Any menu can be identified by its name (for example, "File"), regardless of whether it is a standard
menu or a custom menu. Each of MapInfo Pro's standard menus can also be referred to by its menu
ID; for example, the File menu has an ID of 1.
See Alter Menu Item statement for a listing of the names and ID numbers of MapInfo Pro's menus.
After the menu bar has been customized, the following statement:

Create Menu Bar As Default

restores the standard MapInfo Pro menu bar. Note that the Create Menu Bar As Default statement
removes any custom menu items that may have been added by other MapBasic applications that
may be running at the same time. For the sake of not accidentally disabling other MapBasic
applications, you should exercise caution when using the Create Menu Bar As Default statement.

Examples
The following example shortens the menu bar so that it includes only the File, Edit, Query, and
window-specific (for example, Map, Browse, etc.) menus.

Create Menu Bar As

"File", "Edit", "Query", "WinSpecific"

Ordinarily, the MapInfo Pro menu bar only displays a Map menu when a Map window is the active
window. Similarly, MapInfo Pro only displays a Browse menu when a Browse window is the active
window. The following example redefines the menu bar so that it always includes both the Map and
Browse menus, even when no windows are on the screen. However, all items on the Map menu
will be disabled (grayed out) whenever the current window is not a Map window, and all items on
the Browse menu will be disabled whenever the current window is not a Browse window.

Create Menu Bar As

"File", "Edit", "Query", "Map", "Browse"

MapBasic 15.2 Reference 245

 A to Z MapBasic Language Reference

The following example creates a custom menu, called DataEntry, and then redefines the menu bar
so that it includes only the File, Edit, and DataEntry menus.

Declare Sub AddSub

Declare Sub EditSub
Declare Sub DelSub

Create Menu "DataEntry" As

"Add" calling AddSub,
"Edit" calling EditSub,
"Delete" calling DelSub

Create Menu Bar As

"File", "Edit", "DataEntry"

See Also:
Alter Menu Bar statement, Create Menu statement, Menu Bar statement

Create MultiPoint statement

Purpose
Combines a number of points into a single object. All points have the same symbol. The Multipoint
object displays in the Browser as a single record. You can issue this statement from the MapBasic
window in MapInfo Pro.

Syntax

Create Multipoint
[ Into { Window window_id | Variable var_name } ]
[ num_points ]
( x1, y1 ) ( x2, y2 ) [ ... ]
[ Symbol... ]

window_id is a window identifier.

var_name is the name of an existing object variable.
num_points is the number of points inside Multipoint object.
x y specifies the location of the point.
The Symbol clause specifies a symbol style.
Note: One symbol is used for all points contained in a Multipoint object.

Currently MapInfo Pro uses the following four different syntaxes to define a symbol used for points:

MapBasic 15.2 Reference 246

 A to Z MapBasic Language Reference

Syntax 2 (MapInfo Pro's 3.0 Symbol Syntax)

Symbol ( shape, color, size )

shape is an integer, 31 or larger, specifying which character to use from MapInfo Pro's standard
symbol set. MapInfo 3.0 symbols refers to the symbol set that was originally published with MapInfo
for Windows 3.0 and has been maintained in subsequent versions of MapInfo Pro. To create an
invisible symbol, use 31. The standard set of symbols includes symbols 31 through 67, but the user
can customize the symbol set by using the Symbol application.
color is an integer RGB color value; see RGB() function.
size is an integer point size, from 1 to 48.

Syntax 3 (TrueType Font Syntax)

Symbol ( shape, color, size, fontname, fontstyle, rotation )

shape is an integer, 31 or larger, specifying which character to use from a TrueType font. To create
an invisible symbol, use 31.
color is an integer RGB color value; see RGB() function.
size is an integer point size, from 1 to 48.
fontname is a string representing a TrueType font name (for example, "Wingdings").
fontstyle is an integer code controlling attributes such as bold.
rotation is a floating-point number representing a rotation angle, in degrees.

Syntax 4 (Custom Bitmap File Syntax)

Symbol ( filename, color, size, customstyle )

filename is a string up to 31 characters long, representing the name of a bitmap file. The file must
be in the CUSTSYMB directory (unless a Reload Symbols statement has been used to specify a
different directory).
color is an integer RGB color value; see RGB() function.
size is an integer point size, from 1 to 48.
customstyle is an integer code controlling color and background attributes. See table below.

Syntax 5

Symbol symbol_expr

symbol_expr is a Symbol expression, which can either be the name of a Symbol variable, or a
function call that returns a Symbol value, for example, the MakeSymbol() function.

MapBasic 15.2 Reference 247

 A to Z MapBasic Language Reference

Example

Create Multipoint 7 (0,0) (1,1) (2,2) (3,4) (-1,1) (3,-2) (4,3)

See Also:
Objects Combine statement, Set Combine Version statement

Create Object statement

Purpose
Creates one or more regions by performing a Buffer, Merge, Intersect, Union, Voronoi, or Isogram
operation. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Object As { Buffer | Isogram | Union | Intersect | Merge |

ConvexHull | Voronoi }
From fromtable
[ Into { Table intotable | Variable varname } ]
[ Data column = expression [ , column = expression... ] ]
[ Group By { column | RowID } ]

fromtable is the name of an open table, containing one or more graphic objects.
intotable is the name of an open table where the new object(s) will be stored.
varname is the name of an Object variable where a new object will be stored.
column is the name of a column in the table.
expression is an expression used to populate column.

Description
The Create Object statement creates one or more new region objects, by performing a geographic
operation (Buffer, Merge, Intersect, Union, ConvexHull, Voronoi, or Isogram) on one or more existing
objects.
The Into clause specifies where results are stored. To store the results in a table, specify Into Table.
To store the results in an Object variable, specify Into Variable. If you omit the Into clause, results
are stored in the source table.
Note: If you specify a Group By clause to perform data aggregation, you must store the results in
a table rather than a variable.

The keyword which follows the As keyword dictates what type of objects are created. Buffer and
Isogram are discussed in sections: Create Object As Buffer and Create Object As Isogram.
Union

MapBasic 15.2 Reference 248

 A to Z MapBasic Language Reference

Specify Union to perform a combine operation, which eliminates any areas of overlap. If you perform
the union operation on two overlapping regions (each of which contains one polygon), the end result
may be a region object that contains one polygon.
The union and merge operations are similar, but they behave very differently in cases where objects
are completely contained within other objects. In this case, the merge operation removes the area
of the smaller object from the larger object, leaving a hole where the smaller object was. The union
operation does not remove the area of the smaller object.
Create Objects As Union is similar to the Objects Combine statement. The Objects Combine
statement deletes the input and inserts a new combined object. Create Objects As Union only
inserts the new combined object, it does not delete the input objects. Combining using a Target and
potentially different tables is only available with the Objects Combine statement. The Combine
Objects using Column functionality is only available using Create Objects As Union using the
Group By clause.
If a Create Object As Union statement does not include a Group By clause, MapInfo Pro creates
one combined object for all objects in the table. If the statement includes a Group By clause, it must
name a column in the table to allow MapInfo Pro to group the source objects according to the
contents of the column and produce a combined object for each group of objects.
If you specify a Group By clause, MapInfo Pro groups all records sharing the same value, and
performs an operation (for example, Merge) on the group.
If you specify a Data clause, MapInfo Pro performs data aggregation. For example, if you perform
merge or union operations, you may want to use the Data clause to assign data values based on
the Sum() or Avg() aggregate functions.
Intersect
Specify Intersect to create an object representing the intersection of other objects (for example, if
two regions overlap, the intersection is the area covered by both objects).
Merge
Specify Merge to create an object representing the combined area of the source objects. The Merge
operation produces a results object that contains all of the polygons that belonged to the original
objects. If the original objects overlap, the merge operation does not eliminate the overlap. Thus, if
you merge two overlapping regions (each of which contains one polygon), the end result may be a
region object that contains two overlapping polygons. In general, Union should be used instead.
Convex Hull
The ConvexHull operator creates a polygon representing a convex hull around a set of points. The
convex hull polygon can be thought of as an operator that places a rubber band around all of the
points. It consists of the minimal set of points such that all other points lie on or inside the polygon.
The polygon is convex―no interior angle can be greater than 180 degrees.
The points used to construct the convex hull are any nodes from Regions, Polylines, or Points in
the fromtable. If a Create Object As ConvexHull statement does not include a Group By clause,
MapInfo Pro creates one convex hull polygon. If the statement includes a Group By clause that
names a column in the table, MapInfo Pro groups the source objects according to the contents of

MapBasic 15.2 Reference 249

 A to Z MapBasic Language Reference

the column, then creates one convex hull polygon for each group of objects. If the statement includes
a Group By RowID clause, MapInfo Pro creates one convex hull polygon for each object in the
source table.
Voronoi
Specify Voronoi to create regions that represent the Voronoi solutions of the input points. The data
values from the original input points can be assigned to the resultant polygon for that point by
specifying data clauses.

Example
The following example merges region objects from the Parcels table, and stores the resultant regions
in the table Zones. Since the Create Object statement includes a Group By clause, MapBasic
groups the Parcel regions, then performs one merge operation for each group. Thus, the Zones
table ends up with one region object for each group of objects in the Parcels table. Each group
consists of all parcels having the same value in the zone_id column.
Following the Create Object statement, the parcelcount column in the Zones table indicates how
many parcels were merged to produce that zone. The zonevalue column in the Zones table indicates
the sum of the values from the parcels that comprised that zone.

Open Table "PARCELS"

Open Table "ZONES"
Create Object As Merge
From PARCELS Into Table ZONES Data
parcelcount=Count(*),zonevalue=Sum(parcelvalue)
Group By zone_id

The next example shows a multi-object convex hull using the Create Object As statement.

Create Object As ConvexHull from state_caps into Table dump_table

See Also:
OverlayNodes() function, Set Buffer Version statement, Set Combine Version statement

Create Object As Buffer

Purpose
Creates a polygon boundary around points, lines, or other boundaries. You can issue this statement
from the MapBasic window in MapInfo Pro.

Syntax

Create Object As Buffer

From fromtable
[ Into { Table intotable | Variable varname } ]
[ Width bufferwidth [ Units unitname ]]]

MapBasic 15.2 Reference 250

 A to Z MapBasic Language Reference

[ Type { Spherical | Cartesian } ] ]

[ Resolution smoothness ]
[ Data column = expression [ , column = expression... ] ]
[ Group By { column | RowID } ]
[ Concurrency { All | Aggressive | Intermediate | Moderate | None } ]

bufferwidth is a number indicating the displacement used in a Buffer operation; if this number is
negative, and if the source object is a closed object, the resulting buffer is smaller than the source
object. If the width is negative, and the object is a linear object (line, polyline, arc) or a point, then
the absolute value of width is used to produce a positive buffer.
unitname
smoothness is an integer from 2 to 100, indicating the number of segments per circle in a Buffer
operation.

Description
If the Create Object statement performs a Buffer operation, the statement can include Width and
Resolution clauses. The Width clause specifies the width of the buffer. The optional Units sub-clause
lets you specify a distance unit name (such as "km" for kilometers) to apply to the Width clause. If
the Width clause does not include the Units sub-clause, the buffer width is interpreted in MapBasic's
current distance unit. By default, MapBasic uses miles as the distance unit; to change this unit, use
the Set Distance Units statement.
Type is the method used to calculate the buffer width around the object. It can either be Spherical
or Cartesian. Note that if the coordinate system of the intotable is NonEarth, then the calculations
are performed using Cartesian methods regardless of the option chosen, and if the coordinate
system of the intotable is Latitude/Longitude, then calculations are performed using Spherical
methods regardless of the option chosen.
The optional Type sub-clause lets you specify the type of distance calculation used to create the
buffer. If the Spherical type is used, then the calculation is done by mapping the data into a
Latitude/Longitude On Earth projection and using widths measured using Spherical distance
calculations. If the Cartesian type is used, then the calculation is done by considering the data to
be projected to a flat surface and widths are measured using Cartesian distance calculations. If the
Width clause does not include the Type sub-clause, then the default distance calculation type
Spherical is used. If the data is in a Latitude/Longitude projection, then Spherical calculations are
used regardless of the Type setting. If the data is in a NonEarth projection, the Cartesian calculations
are used regardless of the Type setting.
The Resolution keyword lets you specify the number of segments comprising each circle of the
buffer region. By default, a buffer object has a smoothness value of twelve (12), meaning that there
are twelve segments in a simple ring-shaped buffer region. By specifying a larger smoothness value,
you can produce smoother buffer regions. Note, however, that the larger the smoothness value, the
longer the Create Object statement takes, and the more disk space the resultant object occupies.
The optional Concurrency clause lets you distribute the processing to multiple cores to improves
performance. When Concurrency is set to none and the machine has more than one core, then

MapBasic 15.2 Reference 251

 A to Z MapBasic Language Reference

the other cores are left unused. This clause lets you specify the level of concurrency needed to
perform this operation on the map. Concurrency can have one of the following values:
• All: Full concurrency. All processors on your system perform the operation. This is the default
setting MapInfo Pro installs with.
• Aggressive: Aggressive concurrency, 75% of the processors on your system perform the operation.
• Intermediate: Intermediate concurrency, 50% of the processors on your system perform the
operation.
• Moderate: Moderate concurrency, 25% of the processors on your system perform the operation.
• None: No concurrency. A single processor performs the operation. This option provides the least
amount of processing speed.
For example:

Create Object As Buffer

From zipcodes
Width 1
Units "mi"
Type Spherical
Resolution 12
Into Table zipcodes
Group by Rowid
Concurrency Aggressive
Data...

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 following commands display an error message:

Create Object As Buffer

From zipcodes
Width 1
Units "mi"
Type Spherical
Resolution 12
Into Table zipcodes
Group by Rowid
Concurrency 0

Create Object As Buffer

From zipcodes
Width 1
Units "mi"
Type Spherical
Resolution 12
Into Table zipcodes

MapBasic 15.2 Reference 252

 A to Z MapBasic Language Reference

Group by Rowid
Concurrency -5

Note: You can only use concurrency if the One buffer for each object option is selected in the
Buffer Objects dialog box. If this option is not selected and you specify the Concurrency
clause, then it is ignored and there is no error message.

If a Create Object As Buffer statement does not include a Group By clause, MapInfo Pro creates
one buffer region. If the statement includes a Group By clause which names a column in the table,
MapInfo Pro groups the source objects according to the contents of the column, then creates one
buffer region for each group of objects. If the statement includes a Group By RowID clause, MapInfo
Pro creates one buffer region for each object in the source table.

Example
The next example creates a region object, representing a quarter-mile buffer around whatever
objects are currently selected. The buffer object is stored in the Object variable, corridor. A subsequent
Update statement or Insert statement could then copy the object to a table.

Dim corridor As Object

Create Object As Buffer
From Selection
Into Variable corridor
Width 0.25 Units "mi"
Resolution 60

See Also:
Set Buffer Version statement

Create Object As Isogram

Syntax

Create Object As Isogram

From fromtable
[ Into { Table intotable } ]
[ Data column = expression [ , column = expression... ] ]
Connection connection_handle
[ Distance dist1 [[ Brush ... ] [ Pen ... ]]
[ , dist2 [ Brush ... ] [ Pen ... ]]
[ , distN [ Brush ... ] [ Pen ... ] [ ,...]
Units dist_unit ]
[ Time time1 [[ Brush ... ] [ Pen ... ]]
[ , time2 [ Brush ... ] [ Pen ... ]]
[ , timeN [ Brush ... ] [ Pen ... ]] [ ,...]
Units time_unit ]

MapBasic 15.2 Reference 253

 A to Z MapBasic Language Reference

connection_handle is a number expression returned from the Open Connection statement

referencing the connection to be used.
dist1, dist2, distN are numeric expressions representing distances for the Isograms expressed in
dist_units.
Brush is a valid Brush clause to specify fill style.
Pen is a valid Pen clause to specify a line style.
dist_unit is a valid unit of distance (for example, "km" for kilometers). See Set Distance Units
statement for a complete list of possible values.
time1, time2, timeN are numeric values representing times for Isograms expressed in time_units.
time_unit is a string representing valid unit of time. Valid choices are: "hr", "min", or "sec".

Description
If the Create Object statement performs an Isogram operation, you must pass a connection_handle
that corresponds to an open connection created with an Open Connection statement. You must
specify a Distance clause or a Time clause to create the size of the Isogram desired. The Distance
clause can contain one or more distance expressions with an optional brush and/or pen for each
one. If you do not specify a Brush clause or Pen clause the current brush and pen is used. No
matter how many Distance instances you specify a single Units string must be provided to indicate
the units in which the distances are expressed.
By specifying a Time clause, you can create regions based on time, with each one having an optional
Brush clause and/or Pen clause. If you do not specify a Brush clause or Pen clause the current
brush and pen is used. No matter how many Time instances you specify a single Units string must
be provided to indicate the units in which the times are expressed. The maximum amount of values
allowed is 50. Each value creates a separate band that can be either specific times or specific
distances. Larger values take substantially longer to create. Many items factor into the equation,
but in general, using the Set Connection Isogram statement with MajorRoadsOnly specified,
results in a much quicker response compared to using the entire road network. MapBasic only allows
distances of 35 miles with MajorRoadsOnly Off and 280 miles with MajorRoadsOnly On. similarly,
the maximum time is 0.5 hours with MajorRoadsOnly Off and 4 hours with MajorRoadsOnly On.
See Also:
Buffer() function, ConvexHull() function, Objects Combine statement, Objects Erase statement,
Objects Intersect statement, Open Connection statement

Create Pline statement

Purpose
Creates a polyline object. You can issue this statement from the MapBasic window in MapInfo Pro.

MapBasic 15.2 Reference 254

 A to Z MapBasic Language Reference

Syntax

Create Pline
[ Into { Window window_id | Variable var_name } ]
[ Multiple num_sections ]
num_points ( x1, y1 ) ( x2, y2 ) [ ... ]
[ Pen... ]
[ Smooth ] [ Priority n ] [ Name framename ]

window_id is a window identifier.

var_name is the name of an existing object variable.
num_points specifies how many nodes the polyline will contain.
num_sections specifies how many sections the multi-section polyline will contain.
each x, y pair defines a node of the polyline.
The Pen clause specifies a line style.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
framename is a string representing the name for this item in a Layout window.

Description
The Create Pline statement creates a polyline object. If you need to create a polyline object, but
do not know until run-time how many nodes the object should contain, create the object in two steps:
First, use Create Pline to create an object with no nodes, and then use the Alter Object statement
to add detail to the polyline object.
If the statement includes the optional Into Variable clause, the object will be stored in the specified
object variable. If the Into clause specifies a Window identifier, the object will be stored in the
appropriate place in the window (for example, in the editable layer of a Map window). If you omit
the Into clause, MapInfo Pro attempts to store the object in the topmost window; if objects cannot
be stored in the topmost window; no object is created.
The x and y parameters use whatever coordinate system MapBasic is currently using
(Longitude/Latitude by default). Objects created on a Layout window, however, are specified in
paper units. For details about paper units, see Set Paper Units statement. By default, MapBasic
uses inches as the paper unit. To use a different paper unit, use the Set Layout statement. If you
need to create objects on a Layout window, you must first issue a Set CoordSys Layout statement.
The optional Pen clause specifies a line style. If no Pen clause is specified, the Create Pline
statement will use the current line style (the style which appears in the MapInfo Pro Line Style
dialog box). Smooth will smooth the line so that it appears to be one continuous line with curves
instead of angles.
When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of
frames to a unique set of values beginning with one (1). Use the Priority clause to assign the Z-Order
of the newly created object frame on the Layout window.

MapBasic 15.2 Reference 255

 A to Z MapBasic Language Reference

The Name clause assigns a name to a frame in the Layout window. If a name is assigned, it is
written to the workspace (WOR) file and the workspace version updates to 1500.
A single-section polyline can contain up to 134,217,724 nodes. The maximum number of segments
in a multi-segment polyline is 24,403,223.
See Also:
Alter Object statement, Insert statement, Pen clause, Set CoordSys statement, Update
statement

CreatePoint() function
Purpose
Returns an Object value representing a point. You can call this function from the MapBasic window
in MapInfo Pro.

Syntax

CreatePoint( x, y )

x is a float value, representing an x-position (for example, Longitude).

y is a float value, representing a y-position (for example, Latitude).

Return Value
Object

Description
The CreatePoint() function returns an Object value representing a point.
The x and y parameters should use whatever coordinate system MapBasic is currently using. By
default, MapBasic uses a Longitude/Latitude coordinate system, although the Set CoordSys
statement can re-configure MapBasic to use a different coordinate system. Note that MapBasic's
coordinate system is independent of the coordinate system of any Map window.
The point object will use whatever Symbol style is currently selected. To create a point object with
a specific Symbol style, you could issue the Set Style statement before calling CreatePoint().
Alternately, instead of calling CreatePoint(), you could issue a Create Point statement, which has
an optional Symbol clause.
The point object created through the CreatePoint() function could be assigned to an Object variable,
stored in an existing row of a table (through the Update statement), or inserted into a new row of
a table (through an Insert statement).
Note: If you need to create objects on a Layout window, you must first issue a Set CoordSys
statement.

MapBasic 15.2 Reference 256

 A to Z MapBasic Language Reference

Examples
The following example uses the Insert statement to insert a new row into the table Sites. The
CreatePoint() function is used within the body of the Insert statement to specify the graphic object
that will be attached to the new row.

Open Table "sites"

Insert Into sites (obj)
Values ( CreatePoint(-72.5, 42.4) )

The following example assumes that the table Sites has Xcoord and Ycoord columns, which indicate
the longitude and latitude positions of the data. The Update statement uses the CreatePoint()
function to build a point object for each row in the table. Following the Update operation, each row
in the Sites table will have a point object attached. Each point object will be located at the position
indicated by the Xcoord, Ycoord columns.

Open Table "sites"

Update sites
Set obj = CreatePoint(xcoord, ycoord)

The above example assumes that the Xcoord, Ycoord columns contain actual longitude and latitude
degree values.
See Also:
Create Point statement, Insert statement, Update statement

Create Point statement

Purpose
Creates a point object. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Point
[ Into { Window window_id | Variable var_name } ]
( x, y )
[ Symbol... ] [ Priority n ] [ Name framename ]

window_id is a window identifier.

var_name is the name of an existing object variable.
x, y specifies the location of the point.
The Symbol clause specifies a symbol style.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
framename is a string representing the name for this item in a Layout window.

MapBasic 15.2 Reference 257

 A to Z MapBasic Language Reference

Description
The Create Point statement creates a point object.
If the statement includes the optional Into Variable clause, the object will be stored in the specified
object variable. If the Into clause specifies a window identifier, the object will be stored in the
appropriate place in the window (for example, in the editable layer of a Map window). If the Into
clause is not provided, MapBasic will attempt to store the object in the topmost window; if objects
may not be stored in the topmost window (for example, if the topmost window is a grapher) no object
will be created.
The x and y parameters use whatever coordinate system MapBasic is currently using. By default,
MapBasic uses a longitude, latitude coordinate system, although the Set CoordSys statement can
re-configure MapBasic to use a different coordinate system. Note that MapBasic's coordinate system
is independent of the coordinate system of any Map window. Objects created on a Layout window,
however, are specified in paper units: each x-coordinate represents a distance from the left edge
of the page, while each y-coordinate represents the distance from the top edge of the page. For
details about paper units, see Set Paper Units statement. By default, MapBasic uses inches as
the default paper unit. To use a different paper unit, use the Set Paper Units statement.
Note: If you need to create objects on a Layout window, you must first issue a Set CoordSys
Layout statement.

The optional Symbol clause specifies a symbol style; see Symbol clause for more details. If no
Symbol clause is specified, the Create Point statement uses the current symbol style (the style
which appears in the Symbol Style dialog box).
When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of
frames to a unique set of values beginning with one (1). Use the Priority clause to assign the Z-Order
of the newly created object frame on the Layout window.
The Name clause assigns a name to a frame in the Layout window. If a name is assigned, it is
written to the workspace (WOR) file and the workspace version updates to 1500.
See Also:
CreatePoint() function, Insert statement, Symbol clause, Update statement

Create PrismMap statement

Purpose
Creates a Prism map. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create PrismMap
[ From Window window_ID | MapString mapper_creation_string ]
{ layer_id | layer_name }

MapBasic 15.2 Reference 258

 A to Z MapBasic Language Reference

With expr
[ Camera [Pitch angle | Roll angle | Yaw angle | Elevation angle] |
[ Position ( x, y, z ) | FocalPoint ( x, y, z ) ] |
[ Orientation(vu_1, vu_2, vu_3, vpn_1, vpn_2, vpn_3,
clip_near, clip_far) ]
]
[ Light Color lightcolor ]
[ Scale grid_scale ]
[ Background backgroundcolor ]

window_id is a window identifier a for a Map window which contains a region layer. An error message
is displayed if a layer with regions is not found.
mapper_creation_string specifies a command string that creates the mapper textured on the Prism
map.
layer_id is the layer identifier of a layer in the map (one or larger).
layer_name is the name of a layer in the map.
expr is an expression that is evaluated for each row in the table.
Camera specifies the camera position and orientation.
angle is an angle measurement in degrees. The horizontal angle in the dialog box ranges from
0-360 degrees and rotates the maps around the center point of the grid. The vertical angle in the
dialog box ranges from 0-90 and measures the rotation in elevation from the start point directly over
the map.
Pitch adjusts the camera's current rotation about the x-axis centered at the camera's origin.
Roll adjusts the camera's current rotation about the z-axis centered at the camera's origin.
Yaw adjusts the camera's current rotation about the y-axis centered at the camera's origin.
Elevation adjusts the current camera's rotation about the x-axis centered at the camera's focal
point.
Position indicates the camera and/or light position.
FocalPoint indicates the camera and/or light focal point.
Orientation specifies the camera's ViewUp (vu_1, vu_2, vu_3), ViewPlane Normal (vpn_1, vpn_2,
vpn_3) and Clipping Range (clip_near and clip_far), used specifically for persistence of view).
grid_scale is the amount to scale the grid in the z direction. A value >1 will exaggerate the topology
in the z direction, a value <1 will scale down the topological features in the z direction.
backgroundcolor is a color to be used to set the background and is specified using the RGB()
function.

Description
The Create PrismMap statement creates a Prism Map window. The Prism Map is a way to associate
multiple variables for a single object in one visual. For example, the color associated with a region

MapBasic 15.2 Reference 259

 A to Z MapBasic Language Reference

may be the result of thematic shading while the height the object is extruded through may represent
a different value. The Create PrismMap statement corresponds to MapInfo Pro's Prism Map
command.
Between sessions, MapInfo Pro preserves Prism Maps settings by storing a Create PrismMap
statement in the workspace file. Thus, to see an example of the Create PrismMap statement, you
could create a map, choose the Add Theme command on the MAP tab, save the workspace (for
example, PRISM.WOR), and examine the workspace in a MapBasic text edit window. You could
then copy the Create PrismMap statement in your MapBasic program. Similarly, you can see
examples of the Create PrismMap statement by opening the MapBasic window before you choose
Add Theme.
Each Create PrismMap statement must specify an expr expression clause. MapInfo Pro evaluates
this expression for each object in the layer; following the Create PrismMap statement, MapInfo Pro
chooses each object's display style based on that record's expr value. The expression typically
includes the names of one or more columns from the table being shaded.
The optional window_id clause identifies which map layer to use in the prism map; if no window_id
is provided, MapBasic uses the topmost Map window. The Create PrismMap statement must specify
which layer to use, even if the Map window has only one layer. The layer may be identified by
number (layer_id), where the topmost map layer has a layer_id value of one, the next layer has a
layer_id value of two, etc. Alternately, the Create PrismMap statement can identify the map layer
by name (for example, "world").

Example

Open Table "STATES.TAB" Interactive

Map From STATES
Create PrismMap From Window FrontWindow() STATES With Pop_1980 Background

RGB(192,192,192)

See Also:
Set PrismMap statement, PrismMapInfo() function

Create Query statement

Purpose
Generates a query table that represents the current contents of the specified Browser window. You
can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Query
From Window window_id
Into query_name

MapBasic 15.2 Reference 260

 A to Z MapBasic Language Reference

window_id is an Integer window ID number identifying a Browser window.

query_name is the name of the query table to generate.

Error Conditions
ERR_TABLE_ALREADY_OPEN error is generated if there is already a table open with the name
query_name and the table is not a query table.

Description
After you have applied sort and/or filter conditions to a Browser window, you might want to perform
other operations on the results of the filter. Use the Create Query statement to generate a query
table that represents the current contents of the Browser. The resulting query represents the set of
rows that satisfies the filter conditions. You can then use the query in other MapBasic statements,
such as the Update statement, Commit Table statement, and Map statement.

Example

Browse * From World

Set Browse Filter Where (Continent = "North America" Or Continent =
"South
America")
Create Query From Window Frontwindow() into Americas
Map From Americas

See Also:
Set Browse statement, Select statement

Create Ranges statement

Purpose
Calculates thematic ranges and stores the ranges in an array, which can then be used in a Shade
statement. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Ranges
From table
With expr
[ Use { "Equal Ranges" | "Equal Count" | "Natural Break" | "StdDev" }
]
[ Quantile Using q_expr ]
[ Number num_ranges ]
[ Round rounding_factor ]
Into Variable array_variable

table is the name of the table to be shaded thematically.

MapBasic 15.2 Reference 261

 A to Z MapBasic Language Reference

expr is an expression that is evaluated for each row in the table.

q_expr is the expression used to perform quantiling.
num_ranges specifies the number of ranges (default is 4).
rounding_factor is factor by which the range break numbers should be rounded (for example, 10 to
round off values to the nearest ten).
array_variable is the float array variable in which the range information will be stored.

Description
The Create Ranges statement calculates a set of range values which can then be used in a Shade
statement (which creates a thematic map layer). For an introduction to thematic maps, see the
MapInfo Pro documentation.
The optional Use clause specifies how to break the data into ranges. If you specify "Equal Ranges"
each range covers an equal portion of the spectrum of values (for example, 0-25, 25-50, 50-75,
75-100). If you specify "Equal Count" the ranges are constructed so that there are approximately
the same number of rows in each range. If you specify "Natural Break" the ranges are dictated by
natural breaks in the set of data values. If you specify "StdDev" the middle range breaks at the mean
of your data values, and the ranges above and below the middle range are one standard deviation
above or below the mean. MapInfo Pro uses the population standard deviation (N - 1).
The Into Variable clause specifies the name of the float array variable that will hold the range
information. You do not need to pre-size the array; MapInfo Pro automatically enlarges the array,
if necessary, to make room for the range information. The final size of the array is twice the number
of ranges, because MapInfo Pro calculates a high value and a low value for each range.
After calling Create Ranges, call the Shade statement to create the thematic map, and use the
Shade statement's optional From Variable clause to read the array of ranges. The Shade statement
usually specifies the same table name and column expression as the Create Ranges statement.

Quantiled Ranges
If the optional Quantile Using clause is present, the Use clause is ignored and range limits are
defined according to the q_expr.
Quantiled ranges are best illustrated by example. The following statement creates ranges of buying
power index (BPI) values, and uses state population statistics to perform quantiling to set the range
limits.

Create Ranges From states

With BPI_1990 Quantile Using Pop_1990
Number 5
Into Variable f_ranges

Because of the Number 5 clause, this example creates a set of five ranges.

MapBasic 15.2 Reference 262

 A to Z MapBasic Language Reference

Because of the With BPI_1990 clause, states with the highest BPI values will be placed in the
highest range (the deepest color), and states with the lowest BPI values will be placed in the lowest
range (the palest color).
Because of the Quantile Using Pop_1990 clause, the range limits for the intermediate ranges
are calculated by quantiling, using a method that takes state population (Pop_1990) into account.
Since the Quantile Using clause specifies the Pop_1990 column, MapInfo Pro calculates the total
1990 population for the table (which, for the United States, is roughly 250 million). MapInfo Pro
divides that total by the number of ranges (in this case, five ranges), producing a result of fifty million.
MapInfo Pro then tries to define the ranges in such a way that the total population for each range
approximates, but does not exceed, fifty million.
MapInfo Pro retrieves rows from the States table in order of BPI values, starting with the states
having low BPI values. MapInfo Pro assigns rows to the first range until adding another row would
cause the cumulative population to match or exceed fifty million. At that time, MapInfo Pro considers
the first range "full" and then assigns rows to the second range. MapInfo Pro places rows in the
second range until adding another row would cause the cumulative total to match or exceed 100
million; at that point, the second range is full, etc.

Example

Include "mapbasic.def"

Dim range_limits() As Float, brush_styles() As Brush

Dim col_name As Alias

Open Table "states" Interactive

Create Styles
From Brush(2, CYAN, 0) 'style for LOW range
To Brush (2, BLUE, 0) 'style for HIGH range
Vary Color By "RGB"
Number 5
Into Variable brush_styles
' Store a column name in the Alias variable:
col_name = "Pop_1990"

Create Ranges From states

With col_name
Use "Natural Break"
Number 5
Into Variable range_limits

Map From states

Shade states
With col_name
Ranges
From Variable range_limits
Style Variable brush_styles

MapBasic 15.2 Reference 263

 A to Z MapBasic Language Reference

' Show the theme legend window:

Open Window Legend

See Also:
Create Styles statement, Set Shade statement, Shade statement

Create Rect statement

Purpose
Creates a rectangle or square object. You can issue this statement from the MapBasic window in
MapInfo Pro.

Syntax

Create Rect
[ Into { Window window_id | Variable var_name } ]
( x1, y1 ) ( x2, y2 )
[ Pen ... ]
[ Brush ... ] [ Priority n ] [ Name framename ]

window_id is a window identifier.

var_name is the name of an existing object variable.
x1, y1 specifies the starting corner of the rectangle.
x2, y2 specifies the opposite corner of the rectangle.
Pen is a valid Pen clause to specify a line style.
Brush is a valid Brush clause to specify fill style.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
framename is a string representing the name for this item in a Layout window.

Description
If the Create Rect statement includes the optional Into Variable clause, the object will be stored in
the specified object variable. If the Into clause specifies a Window identifier, the object will be stored
in the appropriate place in the window (for example, in the editable layer of a Map window). If the
Into clause is not provided, MapBasic will attempt to store the object in the topmost window; if
objects may not be stored in the topmost window (for example, if the topmost window is a grapher)
no object will be created.
The x and y parameters use whatever coordinate system MapBasic is currently using. By default,
MapBasic uses a Longitude/Latitude coordinate system, although the Set CoordSys statement
can re-configure MapBasic to use a different coordinate system. Note that MapBasic's coordinate
system is independent of the coordinate system of any Map window. Objects created on a Layout

MapBasic 15.2 Reference 264

 A to Z MapBasic Language Reference

window, however, are specified in paper units: each x-coordinate represents a distance from the
left edge of the page, while each y-coordinate represents the distance from the top edge of the
page. For details about paper units, see Set Paper Units statement. By default, MapBasic uses
inches as the default paper unit. To use a different paper unit, call the Set Paper Units statement.
Note: If you need to create objects on a Layout window, you must first issue a Set CoordSys
Layout statement.

The optional Pen clause specifies a line style; see Pen clause for more details. If no Pen clause
is specified, the Create Rect statement uses the current line style (the style which appears in the
Line Style dialog box). Similarly, the optional Brush clause specifies a fill style; see Brush clause
for more details.
When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of
frames to a unique set of values beginning with one (1). Use the Priority clause to assign the Z-Order
of the newly created object frame on the Layout window.
The Name clause assigns a name to a frame in the Layout window. If a name is assigned, it is
written to the workspace (WOR) file and the workspace version updates to 1500.
See Also:
Brush clause, Create RoundRect statement, Insert statement, Pen clause, Update statement

Create Redistricter statement

Purpose
Begins a redistricting session. You can issue this statement from the MapBasic window in MapInfo
Pro.

Syntax

Create Redistricter source_table By district_column

With
[ Layer <layer_number> ]
[ Count ]
[ , Brush ] [ , Symbol ] [ , Pen ]
[ , { Sum | Percent } ( expr ) ] [ , { Sum | Percent } ( expr ) ... ]

[ Percentage From expr ]

[ Percentage from { column | row } ]
[ Order { "MRU" | "Alpha" | "Unordered" } ]

source_table is the name of the table containing objects to be grouped into districts.
district_column is the name of a column; the initial set of districts is built from the original contents
of this column, and as objects are assigned to different districts, MapInfo Pro stores the object's
new district name in this column.

MapBasic 15.2 Reference 265

 A to Z MapBasic Language Reference

layer_number is the number of a layer in the current Map window (for example, 1 for the top layer);
to determine the number of layers in a Map window, call the MapperInfo() function.
Count keyword specifies that the Districts Browser will show a count of the objects belonging to
each district.
Brush keyword specifies that the Districts Browser will show each district's fill style.
Symbol keyword specifies that the Districts Browser will show each district's symbol style.
Pen keyword specifies that the Districts Browser will show each district's line style.
expr is a numeric column expression.
Percentage From clause specifies in-row calculation.
Order clause specifies the order of rows in the Districts Browser (alphabetical, unsorted, or based
on most-recently-used); default is MRU.

Description
The Create Redistricter statement begins a redistricting session. This statement corresponds to
choosing MapInfo Pro's Redistricter command on the HOME tab. For an introduction to redistricting,
see the MapInfo Pro documentation.
To control the set of districts, use the Set Redistricter statement. To end the redistricting session,
use the Close Window statement to close the Districts Browser window.
If you include the Brush keyword, the Districts Browser includes a sample of each district's fill style.
Note that this is not a complete Brush clause; the keyword Brush appears by itself. Similarly, the
Symbol and Pen keywords are individual keywords, not a complete Symbol clause or Pen clause.
If the Districts Browser includes brush, symbol, and/or pen styles, the user can change a district's
style by clicking on the style sample that appears in the Districts Browser.
The Percentage From clause allows you to specify the in-row mode of percentage calculation. If
the Percentage From clause is not specified, the in-column method of calculation is used.
See Also:
Set Redistricter statement

Create Region statement

Purpose
Creates a region object. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Region
[ Into { Window window_id | Variable var_name } ]
num_polygons

MapBasic 15.2 Reference 266

 A to Z MapBasic Language Reference

[ num_points1 ( x1, y1 ) ( x2, y2 ) [ ... ] ]

[ num_points2 ( x1, y1 ) ( x2, y2 ) [ ... ] ... ]
[ Pen ... ]
[ Brush ... ]
[ Center ( center_x, center_y ) ]
[ Priority n ] [ Name framename ]

window_id is a window identifier.

var_name is the name of an existing object variable.
num_polygons specifies the number of polygons that will make up the region (zero or more).
num_points1 specifies the number of nodes in the region's first polygon.
num_points2 specifies the number of nodes in the region's second polygon, etc.
Each x, y pair specifies one node of a polygon.
Pen is a valid Pen clause to specify a line style.
Brush is a valid Brush clause to specify fill style.
center_x is the x-coordinate of the object centroid.
center_y is the y-coordinate of the object centroid.
n is an integer value indicating the Z-Order value of objects (frames) on the Layout window.
framename is a string representing the name for this item in a Layout window.

Description
The Create Region statement creates a region object.
The num_polygons parameter specifies the number of polygons which comprise the region object.
If you specify a num_polygons parameter with a value of zero, the object will be created as an empty
region (a region with no polygons). You can then use t