SpatialWare 4.9.2 for SQL Server User Guide - GIS...

SpatialWare®

Version 4.9.2 for Microsoft® SQL Server

USER GUIDE

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 MapInfo Corporation, One Global View, Troy, New York 12180-8399.© 2009 MapInfo Corporation. All rights reserved. Portions © 2004 Stopwatch Maps, Inc. All rights reserved. MapInfo, the MapInfo logo, MapInfo Professional, and SpatialWare are trademarks of MapInfo Corporation and/or its affiliates. MapInfo Corporate Headquarters:Voice: (518) 285-6000Fax: (518) 285-6070Sales Info Hotline: (800) 327-8627Government Sales Hotline: (800) 619-2333Technical Support Hotline: (518) 285-7283Technical Support Fax: (518) 285-6080Contact information for all MapInfo offices is located at: http://www.mapinfo.com/contactus.Adobe Acrobat® is a registered trademark of Adobe Systems Incorporated in the United States.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.April 2009

http://www.mapinfo.com/contactus

Table of Contents

Part 1: Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17Product Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19Background Information on Industry Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Chapter 2: Getting Started with SpatialWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Overview of the SpatialWare Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24Preparing to Work with SpatialWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Walking Through SpatialWare Funtionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

Chapter 3: Preparing Your Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39About Spatially Enabled Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Enabling Your Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Chapter 4: Defining Spatial Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43What is a Spatial Table? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Using Your Existing Tables with SpatialWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Creating a New Spatial Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45Creating an R-Tree Index for a Spatial Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Checking for a Spatial Table or R-Tree Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Despatializing and Dropping Spatial Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

Chapter 5: Adding Data to Spatial Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51What are Spatial Data? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Writing Spatial Data Using SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Performing Batch Imports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53Updating and Deleting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

User Guide 3

Chapter 6: Performing Queries on Spatial Data . . . . . . . . . . . . . . . . . . . . . . . . . . 55How SpatialWare Queries Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56Using the sp_spatial_query Stored Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Saving the Result of a Query into a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Using Global Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Performing Nearest Neighbor Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64

Chapter 7: Working with MapInfo Client Software . . . . . . . . . . . . . . . . . . . . . . . . 67Preparing to Work with a MapInfo Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68Supporting Case-Sensitive Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Working with Spatial Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Working with MapInfo Professional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71Working with MapInfo MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71

Part 2: Developer Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 8: Constructing Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75What is Geometry and How do I Construct It? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76An Overview of the Spatial Data Type Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Creating Geometry Using the ST_Spatial Function . . . . . . . . . . . . . . . . . . . . . . . . . . . .82ST_Spatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83Geometry String Formats Used with SpatialWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84HG_Box – Two Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85HG_Box – x, y Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86HG_Circle – Two Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86HG_Circle – Center Point and Radius . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87HG_Circle – x, y, and Radius Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88HG_Curve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89HG_Triangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90HG_Quad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90ST_CircularArc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91ST_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92ST_Point. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93ST_Polygon - Polygon with Exterior Boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94ST_Polygon – Polygon with Exterior Boundary and a Centroid. . . . . . . . . . . . . . . . . .94ST_Polygon – Polygon with Exterior Boundary and One or More Interior Boundaries .95ST_Polygon – Polygon with Exterior Boundary, One or More Interior Boundaries, and a Centroid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96ST_Polyline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

User Guide 4

Chapter 9: ST_Spatial Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Understanding ST_Spatial Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100Special Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Chapter 10: Understanding Geometry Collections . . . . . . . . . . . . . . . . . . . . . . 105Creating Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106Mapping Special Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

Chapter 11: Performing Coordinate System Transformations . . . . . . . . . . . . . 109Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110Performing Coordinate Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110

Part 3: Function Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 12: About Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117What are Spatial Functions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118Filter Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118Data Tolerance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119Data Dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119Spherical and Ordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

Chapter 13: Cast Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123HG_AsBinary 124HG_AsText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124 HG_GeometryFromBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125 HG_GeometryFromText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Chapter 14: Aggregate Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 HG_Aggspatial 128 HG_Aggunion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128 HG_Aggintersection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129 HG_Aggconvex_Hull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 HG_Bounding_Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

Chapter 15: Coordinate Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 HG_CSTransform 134

Chapter 16: General Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 HG_GetString 136 HG_Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Chapter 17: Measurement Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 HG_Azimuth 140

User Guide 5

HG_Azimuth_2pts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 HG_Distance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 HG_Height. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 HG_Separation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 HG_Slope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 HG_Slope_2pts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 HG_Slope_Avg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 HG_Slope_Max. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 HG_Slope_Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 HG_SphericalArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 HG_SphericalDist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 HG_SphericalDistance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 HG_SphericalLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 HG_SphericalPerimeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 HG_Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 ST_Area. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 ST_Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 ST_Length_3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 ST_Perimeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 ST_Perimeter_3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Chapter 18: Observer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 HG_Begin_Point 157 HG_Cen_X. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 HG_Cen_Y. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 HG_Cen_Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 HG_Center_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 HG_Corner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 HG_Curve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 HG_End_Arc_Rot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 HG_End_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 HG_End_Tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 HG_End_Tangent_P. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 HG_Expanded. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 HG_Exterior_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 HG_Extract_At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 HG_GeometryN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 HG_Interior_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 HG_Llb_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 HG_Llb_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 HG_Llb_Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 HG_Ncoords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

6 Spatialware 4.9.2 for Microsoft SQL Server

HG_Ncurves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168 HG_Nitems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168 HG_Npaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169 HG_Npoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169 HG_Npolygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170 HG_Nsubcurves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170 HG_Ori_Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 HG_Ori_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 HG_Ori_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 HG_Ori_Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 HG_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173 HG_Pointdyn_Ori_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173 HG_Pointdyn_Ori_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175 HG_Pointdyn_Rot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175 HG_Pointdyn_Xscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176 HG_Pointdyn_Yscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176 HG_PointN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177 HG_Radians . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177 HG_Start_Arc_Rot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178 HG_Start_Tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178 HG_Start_Tangent_P . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179 HG_Subcurve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179 HG_Urt_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180 HG_Urt_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181 HG_Urt_Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181 ST_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 ST_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 ST_Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Chapter 19: Spatial Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 HG_Affine 187 HG_Affine3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187 HG_As_Curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188 HG_As_Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189 HG_As_Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189 HG_Center_In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190 HG_Center_In_3D. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 HG_Centroid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192 HG_Clean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192 HG_Clean_I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193 HG_Clean_S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 HG_Combine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196

User Guide 7

HG_Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 HG_Convex_Hull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 HG_Difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 HG_End_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199 HG_Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 HG_Erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 HG_Erase_Outside. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 HG_Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 HG_Filter_Curves. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 HG_Filter_Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 HG_Filter_Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 HG_Filter_Polygons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 HG_Intersect_In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 HG_LL_Circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 HG_SphericalBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 HG_SphericalCircle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 HG_Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 HG_Start_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 HG_Sym_Difference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 HG_Union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 ST_Adjacent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 ST_Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 ST_Contain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 ST_Overlap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 ST_Transform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 ST_Transform3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Chapter 20: Spatial Predicate Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 HG_Above 223 HG_Assembled. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 HG_At_End_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 HG_At_Start_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 HG_Below . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 HG_Connected_To. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 HG_Identical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 HG_Is_Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 HG_Is_Circle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 HG_Is_CircularArc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 HG_Is_Closed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 HG_Is_Contiguous. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 HG_Is_Curve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 HG_Is_Empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231


HG_Is_Forward. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232 HG_Is_HG_Curve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232 HG_Is_Invalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233 HG_Is_Nulldir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233 HG_Is_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234 HG_Is_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234 HG_Is_Polygon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235 HG_Is_Polyline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235 HG_Is_Quad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 HG_Is_Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 HG_Is_Triangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 HG_Is_Valid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237 HG_Is_Znull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237 HG_Level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238 ST_Adjacent_To . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238 ST_Contained_By. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240 ST_Contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240 ST_Equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 ST_Meets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242 ST_Not_Equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243 ST_Outside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243 ST_Overlaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244 ST_Within . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245

Chapter 21: User Defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247UDF Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248Table-Valued UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250Primary Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251Secondary Filtering (Refinement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252Nearest Neighbor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252fn_sw_udfs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253Geometries as Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254XY Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259

Part 4: References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Chapter 22: Troubleshooting and Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263The Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264SQL Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265

User Guide 9

Chapter 23: Usage and Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Using Indexes in an sp_spatial_query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Uploading Transactional Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Using Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Using Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Using the sp_spatial_query Stored Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Using Aliases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Chapter 24: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Updating the ST_Spatial Column From Longitude Latitude Values . . . . . . . . . . . . . 276

Chapter 25: Importing Data with EasyLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . 277About EasyLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Running EasyLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Uploading MapInfo TAB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Using the EasyLoader Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Using the EasyLoader Commandline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281/A Append all Tables to One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282/D Server Create Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282/E Exclusive Use of Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282/F Log File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283/G Grant All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283/I DO NOT Create a Spatial Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283/K Create Automated Key Column for SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 283/L List of MapInfo Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284/M MICODE/XY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284/O Connection String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284/P ACR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284/Q Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284/R Replace the Server Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285/U DO NOT Create a Unique Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285/T MapInfo Table Name;Server Table Name;Range . . . . . . . . . . . . . . . . . . . . . . . . . . . 285/V Oracle Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285/X Commit Interval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285/Y Symbology Column Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Combining the Commandline with the Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Chapter 26: Conversion Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Conversion Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Chapter 27: Understanding Coordinate Systems and Projections . . . . . . . . . . 289Understanding Projection and Coordinate System Terminology . . . . . . . . . . . . . . . 290Choosing Projections for Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292


Using Earth and Non-Earth Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295Working with Coordinates in SpatialWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295

Chapter 28: Transformation Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Two Dimensional Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298Three Dimensional Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298

Chapter 29: Coordinate Transformation Reference Tables. . . . . . . . . . . . . . . . 301Projections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302Spheroids/Ellipsoids. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303Coordinate Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303Datums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304

Chapter 30: Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

User Guide 11

Part 1: Getting Started

Topics:

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Getting Started with SpatialWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Preparing Your Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Defining Spatial Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Adding Data to Spatial Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Performing Queries on Spatial Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Working with MapInfo Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

1
Introduction
Welcome to the SpatialWare User Guide. This guide introduces SQL application developers to SpatialWare's spatial functions for Microsoft SQL Server. This is a rich set of functions that will enhance your spatial analysis capabilities.

In this section:

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17Product Inventory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19Background Information on Industry Standards . . . . . . . . . . . . .21

Overview

OverviewSpatialWare allows you to store, access, manage, and manipulate spatial data as a standard part of your business data. Spatial data contains geographic information so that it may be represented on a map. Customer records with name, address and telephone numbers are only records in a database. Once the address can be tied to a geographic location on Earth, the record becomes spatial information. Display that record with other spatial information on a map and you can see the relationships among the records, allowing you to make more informed decisions about your business data.

With SpatialWare and SQL Server, spatial data may be a part of any SQL Server database insert, update, or delete. You can access both spatial and non-spatial data within a single SQL Server query. Spatial data used in conjunction with non-spatial data are being used by companies to find their next customer, increase the number of products and services that are offered to customers, and serve customers better. Spatial data can help answer key questions such as: Where can I buy or service products? Can you get a service truck out to me today? Do you offer cellular service in my area? What is the average home value within a 5 KM radius? All these answers depend on knowing accurate location information. SpatialWare lets you capitalize on this information. You already store key business information in your database; your spatial data should complement and extend the analysis opportunities available from the database.

Key FeaturesSpatialWare provides:

• A complete integration of spatial and attribute data.• Data security.• Scalability. The spatial data type enhancements are implemented entirely on the server side to

exploit the scalability offered by Microsoft SQL Server.• A rich set of spatial functions that follow the OGC naming and parameter specifications for

spatial functions in SQL.• Standards compliance.• Ease of use.• Programmatic interfaces. SpatialWare requires no middle tier to access the database, so you

can access SpatialWare functionality through standard programmatic interfaces, such as JDBC, ODBC, ADO, and .NET.


Chapter 1:

ArchitectureThe following illustrates SpatialWare's architecture.

SpatialWare is made up of three main components: the spatial data type, spatial indexing, and spatial functions.

Spatial Data Type

SpatialWare supports a spatial data type called ST_Spatial, which is a SQL Server user-defined datatype, to store geometry data within tables of a database. Database management systems such as SQL Server support data types such as integer, float, and character to support scalar data.

There is a need for a more complex data type designed to store spatial information. SpatialWare provides the storage mechanism and necessary functionality to store, retrieve, and analyze the contents of the data type. SpatialWare also allows this type to be "cast" to useful derivative types for use by client software (Cast Functions transform data from one format to another).

Spatial Indexing

Spatial Indexing is mandatory when spatial data are being searched. A sequential scan of spatial data is typically very expensive since the geometry information stored is normally quite complex, and tables can have large numbers of rows. SpatialWare implements a special indexing scheme based on R-Trees, that is specifically designed to index multidimensional (geometry) data. This indexing scheme is well suited to the distribution patterns typical for spatial data. The implementation is specially tuned so that no knowledge of that data (or likely future extent, volume, or distribution of the data) is required to achieve optimum performance. A spatial index is created on a column of type ST_Spatial using a SpatialWare stored procedure (Creating an R-Tree Index for a

User Guide 17

Product Inventory

Spatial Table on page 48). SpatialWare maintains the index through database triggers when the geometries in the indexed column change as a result of an INSERT, UPDATE, or DELETE operation.

Spatial Functions

SpatialWare contains over 150 spatial functions and predicates. These are extensions to the SQL language, to retrieve data from tables with the ability to compute new geometric values or qualify data based upon geometric relationships. A query, which uses Spatial functions and predicates, is presented to SQL Server via a SpatialWare stored procedure (Chapter 6: Performing Queries on Spatial Data). The query extensions can be logically grouped into the following categories:

As an alternative to performing a query it is possible to use User Defined Functions (UDF) that are available with SQL Server. SpatialWare creates UDFs for most function types given in the previous table. UDFs provide a powerful alternative to SpatialWare’s stored procedure.

Product InventoryYour copy of SpatialWare includes software, sample data, sample queries, and documentation.

Function Type Description

Aggregate Functions Work across rows in a group taking one or more spatial objects of type ST_Spatial as input. They return a single-row result of a spatial object.

Geometry Construction Create geometry from a string using the ST_Spatial function.

Coordinate Functions Transform geometries from one coordinate system to another. Coordinate systems may be geographic (longitude/latitude), or projected (e.g., Mercator, Robinson).

General Functions Perform operations, make queries, or change settings.

Measurement Functions Perform calculations on geometries to find a measurable char-acteristic, such as length, or area.

Observer Functions Return numbers, objects, or attributes from within a geometry. (e.g., X ordinate of a point, Nth Vertex of a polyline.)

Spatial Functions Perform operations on geometries to create new geometries. (e.g., create a buffer zone around a road (linear) geometry.)

Spatial Predicate Functions Analyze geometries or pairs of geometries to see if they meet specific conditions. These functions return TRUE or FALSE (1 or 0) values and are generally used within a WHERE clause. (e.g., find overlapping geometries.)


Chapter 1:

SoftwareSpatialWare software is provided to integrate with Microsoft SQL Server. Also provided are:

• The EasyLoader upload utility for bringing TAB files into SQL Server.• A MapBasic application called sw_spatialize_tab.mbx to assist with spatializing tables (preparing

tables for use with SpatialWare).

EasyLoader is provided as a download from the MapInfo website (www.mapinfo.com). sw_spatialize_tab.mbx is provided with MapInfo Professional.

Sample DataSpatialWare includes sample data for experimenting with data retrieval and analysis. The following sample data are installed with SpatialWare:

• Georgetown database – A sample database that many of the examples in the User Guide reference.

These sample data are automatically installed into the SQL Server instance specified during SpatialWare installation.

Sample QueriesSample queries on the Georgetown database are provided to show the advantages and implementations of using SQL Server and SpatialWare for spatial data management.

Sample queries are installed into SpatialWare’s demo/Query directory.

DocumentationSpatialWare documentation consists of the following:

• Release Notes – A PDF file available from the documentation area of the MapInfo Corporate Web site at www.mapinfo.com. (All SpatialWare documentation is available from this site.)

• Installation Guide – Provided as a PDF file on the software media.• User Guide – Installed with your software and accessible by pointing your Internet browser to the

index.htm page in SpatialWare’s doc directory. Also provided as a PDF file on the software media.

You can view online (HTML) documentation on a Windows, Macintosh, or UNIX computer running version 4 or later of Internet Explorer or Netscape, or running a current version of Mozilla or Safari.

About This GuidePlease read Concepts first before using this product. It contains information about the supported data formats.

User Guide 19

About This Guide

This guide is also available in HTML form for online use. Please view the online version in one of the recommended browsers, either Netscape 4.5 or higher, or Microsoft Internet Explorer 5.0 or higher.

Note For SpatialWare usage notes and caveats refer to Chapter 23: Usage and Caveats.

AssumptionsThis guide assumes that you have SQL Server installed and running, are familiar with SQL, and have read the Microsoft SQL Server Guide.

ConventionsExamples have been included wherever possible to clarify a concept or to illustrate usage. You can use either uppercase or mixed case when sending function calls to SQL Server, depending on how your database was defined. In this guide, function names are given in mixed case, HG_SphericalDist, to make them easier to read.

SQL Syntax

SQL Server queries are encased within an exec sp_spatial_query. For example:

exec sp_spatial_query 'select sw_member, sw_geometryfrom flood100 where ST_Overlaps(sw_geometry,

HG_Box(1756600,10703200, 1755500,10702500))'

Refer to Chapter 6: Performing Queries on Spatial Data for details. If an example is long, it may be wrapped across multiple lines for easier viewing.

If you are using a UDF you do not need to encase the SQL Syntax query with an exec sp_spatial_query. Note that it is not possible to use UDFs with all types of spatial functions. Refer to Chapter 21: User Defined Functions for details.

Icons

Icons are used with function descriptions to denote what is returned:

Signifies a function that returns a geometry.

Signifies a function that returns a number.

Signifies a function that returns a Boolean value (used in a WHERE clause).

Signifies a function that returns a string.


Chapter 1:

Examples

This guide refers to the sample data distributed with the product, the georgetown database. Please refer to the printed installation notes for instructions on how to install sample data.

Some examples refer to a sample table called geomtest. Refer to T-SQL Commands on page 45 in for details on how to create this table if you want to try these examples.

Terms

This guide uses the following terms. For a more complete list of terms used, refer to Chapter 30: Glossary.

For Data• Spatial Data – Data with information on location, position, size, and shape.• Spatial Object – Synonym for a geometry defined by SpatialWare’s ST_Spatial type. A spatial

object could be comprised of a single geometry or a geometry collection.

For Tables• Spatialize a Table – To spatially enable a table using the Spatialize Column procedure. This is

necessary to save spatial data to a table. Note that the table must first contain a column of type ST_Spatial.

• Spatial Table – A table is considered "spatializable" if it has a column of type ST_Spatial and an integer column which is unique and not null (preferably primary key). A table is considered “spatial” if it has been spatially enabled using the sp_sw_spatialize_column procedure.

• Spatial Indexing – A method of accessing geometric data. Spatial indexing avoids sequential searching by using the coordinates of a location as a key.

For Databases• Spatially Enabled Database – A database must be spatially enabled in order for SpatialWare to

use it. This involves running scripts on the database to install SpatialWare components, and create the spatial type necessary to work with SpatialWare.

Background Information on Industry StandardsOpenGIS Standards

SpatialWare for SQL Server follows the Open Geospatial Consortium, Inc. (OGC) Standards. It supports and properly defines geometry and its components.

The OGC defines itself as "a unique membership organization dedicated to the development of open system approaches to geoprocessing." They are developing the OpenGIS® Simple Features Specification For SQL Documentation, which is available at the Open Geospatial Consortium web site ((http://www.opengeospatial.org).

For a copy of the Simple Features Specification for SQL, refer to the OpenGIS Consortium web site.

User Guide 21

http://www.opengeospatial.org

Background Information on Industry Standards

ISO Standards

SpatialWare for SQL Server accepts and generates text geometries. These geometries are in the SQL/MM standard text format. For more information on this format, refer to the SQL Multimedia and Application Packages document at the ISO Standards web site.


2
Getting Started with SpatialWare
This section provides an overview of how to get started with SpatialWare for SQL Server.

Before you continue, you must first have installed SpatialWare by following the instructions provided in the Installation Guide (printed copy) distributed with this product. The install process sets up your master database for use with SpatialWare. To use SpatialWare with any other database, it should be spatially enabled as described in Chapter 3: Preparing Your Database.

In this section:

Overview of the SpatialWare Installation . . . . . . . . . . . . . . . . . . . .24Preparing to Work with SpatialWare . . . . . . . . . . . . . . . . . . . . . . .29Walking Through SpatialWare Funtionality . . . . . . . . . . . . . . . . . .30

Overview of the SpatialWare Installation

Overview of the SpatialWare InstallationWhen you install SpatialWare you are asked to choose the Microsoft SQL Server instance that you want to install to. You can spatially enable one or more databases in this instance to store and query spatial data. If you do not choose a named instance, then the default instance is modified. The install procedure enhances the instance with the following features:

• SpatialWare extended stored procedures and tables are added to the master database.• A login called MAPINFO is created.• The model database is spatially enabled.• Two sample spatially enabled databases, georgetown and World, are created for demonstration

purposes.

This instance is referred to as a SpatialWare instance.

A spatial database is any database defined in a SpatialWare Instance that is spatially enabled. A database is spatially enabled during the SpatialWare installation process (when you are asked to pick those databases that you want to use with SpatialWare), or afterwards by running a SpatialWare script on the database.

A spatially enabled database has the following features:

• A SpatialWare user defined data type called ST_Spatial.• SpatialWare stored procedures.• SpatialWare user defined functions.• A user called MAPINFO is associated with the MAPINFO login for the SpatialWare instance.• A metadata table, called MAPINFO.MAPINFO_MAPCATALOG, used by MapInfo clients such as

MapInfo Professional.

Note Refer to Chapter 3: Preparing Your Database for details on how to spatialize a database.


Chapter 2:

You can view the features that SpatialWare has installed to your database using the Enterprise Manager (in SQL Server 2000) or Management Studio (in SQL Server 2005 or 2008). The first thing you will notice in Enterprise Manager is the inclusion of the georgetown and World sample databases to your SQL Server instance.

Georgetown Database

The georgetown database is provided for learning purposes. This database is already spatially enabled – its tables have been spatialized, and R-tree indexes have been built for them.

Examples throughout this guide are based on georgetown data. The georgetown database represents a residential area. It contains data, such as roads, public and private buildings, flood zone, and lake. There are also sample queries that can be run on the georgetown database located in demo/Query subdirectory where SpatialWare is installed.

Note that the georgetown database is in the 'Texas 4203, Central Zone (1983, US Survey feet)' coordinate system.

World Database

SpatialWare installs sample World data including world boundaries, world capitals and major and minor cities, and ocean boundaries.

User Guide 25


Description of the World database:

Listing the ST_Spatial Data TypeA spatially enabled database, such as the georgetown database, contains the ST_Spatial data type. This type is a SQL Server user defined data type used to store geometry data within tables of a database.

Note A geometry may be up to 2 GB in size, not 16 bytes as suggested by this screen shot.

Geometry takes the form of objects, such as points, lines, and polygons. For a full description of geometry, refer to Chapter 8: Constructing Geometry.

Listing SpatialWare Stored ProceduresSpatialWare provides stored procedures, which are SQL code stored in the database to be available for Transact-SQL programming, for managing SpatialWare tasks.

Table Types Source

World capitals and point locations for major and minor cities

MapInfo from Digital Chart of the World

World Boundaries MapInfo Corporation from National Imag-ery and Mapping Agency (NIMA)


Chapter 2:

Stored procedures are provided to do things like spatialize table columns, create an R-tree index on a table, or drop an R-tree index. SpatialWare also provides a stored procedure, called sp_spatial_query, which provides a convenient way to do spatial queries.

Listing SpatialWare User Defined FunctionsSpatialWare User Defined Functions (UDFs) can be used as part of a select, insert, update, or delete statement. They are added to the database when SpatialWare is installed to provide a powerful alternative to sp_spatial_query in some cases.

User Guide 27


For a full description of UDFs, refer to Chapter 21: User Defined Functions.


Chapter 2:

Viewing Spatial Table PropertiesSpatial tables have key and spatial columns. A key column is used for maintaining spatialized columns, and for R-tree indexing. It is defined as unique and, preferrably, as primary. By convention it is called sw_member. A spatial column is where spatial geometry is stored. It is defined as type ST_Spatial, and by convention is called sw_geometry.

A spatial table has both key and spatial columns in addition to its other columns of data as shown in the previous illustration.

Refer to Chapter 4: Defining Spatial Tables for details on spatial tables.

Preparing to Work with SpatialWareIf this is the first time that you are using SpatialWare with SQL Server, you will have to do the following things:

1. Prepare your database for use with SpatialWare. Refer to Chapter 3: Preparing Your Database.

2. Create spatial tables or spatialize existing tables to work with SpatialWare. Refer to Creating a New Spatial Table on page 45.

For performance reasons, you may want to populate your spatial tables before you create spatial indexes on them (next step). The spatial indexes are maintained when you perform insert, update, or delete operations on the indexed geometry column, and this may cause performance degradation for loading large amounts of data.

User Guide 29

Walking Through SpatialWare Funtionality

3. Create R-tree indexes for your spatial tables. Refer to Creating an R-Tree Index for a Spatial Table on page 48.

An R-Tree index is a spatial index that is used to improve the performance of spatial queries issued against the geometries in particular spatial tables.

4. Populate your spatial tables. Refer to Chapter 5: Adding Data to Spatial Tables.

Populating Spatial Tables

Chapter 5: Adding Data to Spatial Tables provides examples of how to insert spatial data into a table, or how to view geometry. A constructor function, ST_Spatial, is provided to create geometry. Chapter 8: Constructing Geometry describes geometry construction, and geometry collections.

You could import MapInfo TAB files using MapInfo's EasyLoader. Refer to Chapter 25: Importing Data with EasyLoader for details.

Please take note of the data dimension and coordinate system information of your data when populating spatial tables. For details refer to Data Dimension in Chapter 12 on page 119 and to Chapter 11: Performing Coordinate System Transformations.

Performing Spatial Queries

Once you have a database that contains spatial data, you can use SpatialWare functions to:

• Perform operations, or make queries. (General Functions) • Perform calculations on geometries to find a measurable characteristic, such as length, or area.

(Measurement Functions) • Return numbers, objects, or conditions from within a geometry. (Observer Functions) • Perform operations on geometries to create new geometries. (Spatial Functions) • Analyze geometries to see if they meet specific conditions. These functions usually return TRUE

or FALSE (1 or 0) values and are generally used within a WHERE clause. (Spatial Predicate Functions)

Refer to Chapter 6: Performing Queries on Spatial Data for examples of how to perform spatial queries on your data.

Walking Through SpatialWare FuntionalityThis section walks you through a T-SQL script that creates a spatial table, populates the table with geometry (points and polygons), performs some queries, and then cleans up the table (despatializes and drops it). It is a very simplified example of some of the functionality that you would use when working with SpatialWare.


Chapter 2:

The script has been broken up with some text describing each section. The sections are:

1. Initial Settings2. Create Spatial Tables3. Insert Cities4. Insert Search Regions5. Perform Spatial Searches7. Cleanup and Drop Tables

If you have a MapInfo client to SpatialWare, such as MapInfo Professional, installed and running, then you can use the client software to view a map representation of the geometry in the table created by this script.

This example provides a basic overview of a workflow. Please refer to Preparing to Work with SpatialWare on page 29 for an overview with references to more detailed information on subjects such as preparing your database, populating spatial tables, and performing spatial queries.

1. Initial Settings

First, set nocount to on. This is done simply to reduce the number of T-SQL feedback messages returned when executing this script. Also, ensure that the script is executed on the World sample database, which is provided with your SpatialWare installation.

World is where you will create your spatial tables in the next step. It provides the country administrative boundary if displaying this example on a map. This example takes place in the continental United States.

set nocount onuse world

2. Create Spatial Tables

Create two tables, one for cities and one for search regions using CREATE TABLE statements. After a table is created it must be spatialized in order to store spatial data – spatializing a table creates an update and insert trigger on it. This means identifying a unique key column (sw_member), and a spatial type column (sw_geometry). The spatial type column has been defined using SpatialWare’s ST_Spatial type. This is the column where geometry data are stored.

Spatialize each table using SpatialWare’s sp_sw_spatialize_column procedure.

/*------------------------------------------------------------------- Create tables and then spatialize them.-----------------------------------------------------------------*/-- Cities in North Americacreate table na_cities (

sw_member integer identity primary key,city varchar(20),sw_geometry st_spatial

)exec sp_sw_spatialize_column 'dbo', 'na_cities',

'sw_geometry', 'sw_member'

-- Regions in North Americacreate table na_areas (

User Guide 31


sw_member integer identity primary key,area_name varchar(20),sw_geometry st_spatial

)exec sp_sw_spatialize_column 'dbo', 'na_areas',

'sw_geometry', 'sw_member'

3. Insert Cities

Cities are in the form of point geometry. INSERT statements are used to insert points into the na_cities table, which takes a city name and geometry as input.

Note that sw_member was created as an identity column in the na_cities table. This column’s value gets filled in automatically by SQL Server.

/*------------------------------------------------------------------- Insert some cities.-----------------------------------------------------------------*/

insert into na_cities values ('Albuquerque', 'ST_Point(-106.6246358400, 35.1172179900 )');insert into na_cities values ('Anaheim', 'ST_Point(-117.8723311200, 33.8389000200 )');insert into na_cities values ('Denver', 'ST_Point(-104.872655160, 39.7680350400 )');insert into na_cities values ('Greensboro', 'ST_Point(-79.8268881600, 36.0789000300 )');insert into na_cities values ('Houston', 'ST_Point(-95.3867278800, 29.7686999700 )');insert into na_cities values ('Irving', 'ST_Point(-96.9693379200, 32.8576850100 )');insert into na_cities values ('Las Vegas', 'ST_Point(-115.222799160, 36.2057499900 )');insert into na_cities values ('Lincoln', 'ST_Point(-96.6881710800, 40.8164000400 )');insert into na_cities values ('Los Angeles', 'ST_Point(-118.411201080, 34.1121009600 )');insert into na_cities values ('Lubbock', 'ST_Point(-101.875374000, 33.5758500000 )');insert into na_cities values ('Miami', 'ST_Point(-80.2108450800, 25.7756670000 )');insert into na_cities values ('Milwaukee', 'ST_Point(-87.9666231600, 43.0633500300 )');insert into na_cities values ('Minneapolis', 'ST_Point(-93.2668491600, 44.9618499900 )');insert into na_cities values ('New Orleans', 'ST_Point(-89.931354840, 30.0658460400 )');insert into na_cities values ('New York', 'ST_Point(-73.943849160, 40.6698000300 )');insert into na_cities values ('Norfolk', 'ST_Point(-76.244942880, 36.9232000200 )');insert into na_cities values ('Philadelphia', 'ST_Point(-75.134678040, 40.0068170100 )');


Chapter 2:

insert into na_cities values ('Phoenix', 'ST_Point(-112.07139912, 33.5425500000 )');insert into na_cities values ('Salt Lake City', 'ST_Point(-111.92992092, 40.7772669600 )');insert into na_cities values ('Tulsa', 'ST_Point(-95.916407040, 36.1277499600 )');

-- declare a variable to bind in some geometry values. This-- variable is reused in some of the following insert statements.declare @geom varbinary(4000)

You will see the following if using client software, such as MapInfo Professional, to view the na_cities table in the World database:

4. Insert Search Regions

Search regions are in the form of polygon geometry. INSERT statements are used to insert polygons into the na_areas table, which takes an area name and geometry as input. Polygons take the form of rectangles, circles, and an arbitrary shape (a polyline, which is essentially a series of connected points).

/*------------------------------------------------------------------- Insert some areas to represent search regions.-----------------------------------------------------------------*/

-- Insert a rectangle using SpatialWare’s HG_Box function.insert into na_areas

values ('Rect1', 'HG_Box(-121,35, -118,36)')

-- Insert a rectangle using SpatialWare’s HG_Box User Defined Function-- (UDF).select @geom = dbo.HG_Box(-91,29, -90,30)insert into na_areas

values ('Rect2', @geom)

User Guide 33


-- Insert a rectangle by invoking sp_spatial_query.insert into na_areas

exec sp_spatial_query 'select ''Rect3'', HG_Box(-84,42, -83,43) from master..hg_onerow

'

-- Insert a circular polygon using SpatialWare’s HG_SphericalCircle -- User Defined Function.select @geom = dbo.HG_SphericalCircle('ST_Point(-74,42.7)', 100, 'km')insert into na_areas

values ('Circ1', @geom)

-- Insert a circular polygon by invoking sp_spatial_query.insert into na_areas

exec sp_spatial_query 'select ''Circ2'', HG_SphericalCircle(ST_Point(-77,39),100,''km'') from master..hg_onerow

'

-- Insert an arbitrary polygon using SpatialWare’s ST_Spatial-- string representation.insert into na_areas

values ('Poly1', 'ST_Polygon(ST_Polyline(LIST{

ST_Point(-114,34),ST_Point(-114,32),ST_Point(-105,36),ST_Point(-114,34)

}))')

-- Insert a polygon using the OGC well-known text.insert into na_areas

exec sp_spatial_query 'select ''Poly2'',

HG_GeometryFromText(''POLYGON((-119 44,-119 38,-110 41,-119 44))'')

from master..hg_onerow'

The following sp_spatial_query displays the search regions that you’ve just created. The second sp_spatial_query displays the search regions using the OGC Text representation.

-- Let's view the areas just created.exec sp_spatial_query '

select area_name, HG_SphericalArea(sw_geometry, ''sq km'') as area,HG_GetString(sw_geometry) as geom


Chapter 2:

from na_areas'

-- let's view the areas just created using the OGC Text representation.exec sp_spatial_query '

select area_name, HG_SphericalArea(sw_geometry, ''sq km'') as area,HG_AsText(sw_geometry) as ogcgeom

from na_areas'

You will see the following if you display na_areas on your map. Note that not every search region includes a city.

The following uses SpatialWare’s sp_sw_create_rtree procedure to create R-trees for the cities and areas tables. R-trees improve spatial searches on the geometry in these tables.

-- Now, let’s create spatial indexes on the geometry to -- facilitate searching.exec sp_sw_create_rtree 'dbo', 'na_cities', 'sw_geometry', 'sw_member'

exec sp_sw_create_rtree 'dbo', 'na_areas', 'sw_geometry', 'sw_member'

5. Perform Spatial Searches

You’re now ready to perform searches on the tables that you’ve created.

/*------------------------------------------------------------------- Perform some spatial searches.-----------------------------------------------------------------*/-- Find all cities within a constant window using sp_spatial_query.

User Guide 35


exec sp_spatial_query 'select city from na_cities where ST_Contains(HG_Box(-100,29, -90,30), sw_geometry)

'

-- Find all cities within a constant window using UDFs.select a.cityfrom na_cities a, na_cities#s#sw_geometry#s#sw_member(

'HG_Box(-100,29, -90,30)','st_overlaps', 1

) bwhere a.sw_member = b.member

-- Find all cities within a specified distance of the city called New York.exec sp_spatial_query '

select a.city from na_cities a, na_cities b where ST_Contained_By(

a.sw_geometry, HG_SphericalCircle(b.sw_geometry, 300, ''km'')

)and b.city = ''New York''

'

-- Join all regions with all cities to determine all (area, city) -- overlap pairs.exec sp_spatial_query '

select a.area_name, b.city from na_areas a, na_cities bwhere ST_Overlaps(a.sw_geometry, b.sw_geometry)

'

7. Cleanup and Drop Tables

You are now ready to clean up the World database by removing the cities and areas tables that you created. This involves dropping the R-trees for the tables, despatializing the tables, and then dropping the tables. SpatialWare provides procedures to assist with this: sp_sw_drop_rtree and sp_sw_despatialize_column.

/*------------------------------------------------------------------- Clean up the tables.-----------------------------------------------------------------*/-- Drop R-trees and despatialize tables before dropping them.

exec sp_sw_drop_rtree 'dbo', 'na_cities','sw_geometry', 'sw_member'

exec sp_sw_despatialize_column 'dbo', 'na_cities','sw_geometry', 'sw_member'

drop table na_cities

exec sp_sw_drop_rtree 'dbo', 'areas','sw_geometry', 'sw_member'


Chapter 2:

exec sp_sw_despatialize_column 'dbo', 'na_areas','sw_geometry', 'sw_member'

drop table na_areas

User Guide 37

3
Preparing Your Database
To use a Microsoft SQL Server database with SpatialWare, it must first be spatially enabled. This involves making a few settings and running a script on the database to install SpatialWare components.

In this section:

About Spatially Enabled Databases . . . . . . . . . . . . . . . . . . . . . . . .40Enabling Your Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

About Spatially Enabled Databases

About Spatially Enabled DatabasesIn order to understand what a spatially enabled database is, you first need to know what a SpatialWare Instance is.

What is a SpatialWare Instance?

When you install SpatialWare you are asked to choose the Microsoft SQL Server instance that you want to install to. This instance is then modified to contain a spatially enabled database. If you do not choose a specific instance, then the default instance is modified. The install procedure enhances the instance with the following features:

• SpatialWare extended stored procedures are added to the master database.• A mapinfo login is created.• The model database is spatially enabled.• A sample spatially enabled database called georgetown is created for demonstration purposes.

This instance is referred to as a SpatialWare instance. Those databases that you want to use with SpatialWare must be defined in this instance.

What is a Spatial Database?

A spatial database is any database defined in a SpatialWare Instance that is spatially enabled. A database is spatially enabled during the SpatialWare installation process (when you are asked to pick those databases that you want to use with SpatialWare), or afterwards by running a SpatialWare script on the database.

A spatially enabled database has the following features:

• A SpatialWare data type called ST_Spatial.• SpatialWare stored procedures.• SpatialWare user defined functions.• A mapinfo user that is associated with the mapinfo login for the SpatialWare Instance.• A metadata table, called mapinfo.mapinfo_mapcatalog, used by MapInfo clients such as

MapInfo Professional.

Enabling Your DatabaseDuring the install procedure you are given the option of selecting those databases that you would like to use with SpatialWare. The install script then spatially enables them. If you did not spatially enable a database during the install procedure, or if you are creating a new database, then you must spatially enable it manually. This involves making necessary settings to the database and then running a SpatialWare script on the database.


Chapter 3:

1. Make necessary settings to the database.

To use a database with SpatialWare, it must have the following settings:

• The recursive triggers setting turned OFF. Trigger settings are managed through Enterprise Manager. (If you are using SQL Server 2005 or 2008, refer to the online help for Management Studio.) Highlight the server name, right click, and then choose Properties > Server Settings. Under Server Behavior, ensure that the nested triggers option is unchecked (this is the “Allow triggers to be fired which fire other triggers” option).

• The QUOTED_IDENTIFIER environment set to ON.The quoted identifier can be set for the entire server or for an individual database. Refer to Setting the QUOTED_IDENTIFIER for details.

2. Run the spatialize script on the database.

After applying these settings to a database, it must be spatially enabled. This is done using SQL Server 2000’s Query Analyzer or another type of connection (such as ODBC) and executing the following statement:

exec sp_spatialize_db

(If you are using SQL Server 2005 or 2008, refer to the online help for Management Studio.)

You are now ready to create spatial tables. Refer to Chapter 4: Defining Spatial Tables.

Setting the QUOTED_IDENTIFIERThe QUOTED_IDENTIFIER setting must be set to ON for a database to ensure that MapInfo clients work properly with it. There are two ways to set quoted identifiers in the Enterprise Manager: for the entire server or for an individual database. (If you are using SQL Server 2005 or 2008, refer to the online help for Management Studio.)

• Entire Server – To set for the entire server, highlight the server name in Enterprise Manager and right click, then choose Properties. The SQL Server Properties dialog displays. Select the Connections tab and select the Quoted Identifiers check box.

• Individual Database – To set for an individual database, highlight the database name and right click, then choose Properties. The database Properties dialog displays. Select the Connections tab and select the Quoted Identifiers check box.

SpatialWare does not attempt to determine the current QUOTED_IDENTIFIER environment. Its stored procedures are created with this setting ON. It also parses spatial queries as though this setting is ON. However, SQL Server executes spatial queries in the current QUOTED_IDENTIFIER environment, which could be set to OFF.

Problems may arise if the SQL Server QUOTED_IDENTIFIER setting is OFF and the client driver is ON. While SpatialWare stored procedures are created by default with QUOTED_IDENTIFIER set to ON, SQL Server executes the spatial queries in the current QUOTED_IDENTIFIER environment.

User Guide 41

Enabling Your Database

For example, if QUOTED_IDENTIFIER is ON at the server level, but SET QUOTED_IDENTIFIER OFF is executed in a Query Analyzer session, then the following

exec sp_spatial_query 'select "abc" from t'

treats "abc" as a column name, but

select "abc" from t

treats "abc" as a string.


4
Defining Spatial Tables
This section describes how to create and prepare spatial tables for use with SpatialWare. Before you continue, you must prepare your database for use with SpatialWare by spatially enabling it (refer to Chapter 3: Preparing Your Database).

After creating and preparing your tables, you will want to review the material in Chapter 5: Adding Data to Spatial Tables, which describes how to add data to spatial tables.

In this section:

What is a Spatial Table? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Using Your Existing Tables with SpatialWare . . . . . . . . . . . . . . . .44Creating a New Spatial Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45Creating an R-Tree Index for a Spatial Table. . . . . . . . . . . . . . . . .48Checking for a Spatial Table or R-Tree Index . . . . . . . . . . . . . . . .49Despatializing and Dropping Spatial Tables . . . . . . . . . . . . . . . . .50

What is a Spatial Table?

What is a Spatial Table?In order for SpatialWare to use a table in a spatially enabled database, the table must have a spatial and key columns added to it and an R-tree index created for it. This type of table is called a spatial table and it has the following features:

• Spatial Column – A spatial column is where spatial geometry is stored. It is defined as type ST_Spatial. By default, this column is called SW_GEOMETRY, but it can be any legal name. A table may have multiple spatial columns, but clients such as MapInfo Professional only support one column.

• Key Column – A key column is used for maintaining spatialized columns, and for R-tree indexing. This is preferably a primary key which has the IDENTITY property. It is defined as type integer, not null, and unique. By default, this column is called SW_MEMBER, but it can be any legal name.

• R-tree Index – The R-tree index is used to improve the speed of queries against a table. Several stored procedures are installed to your spatial database when it is spatially enabled that spatialize tables (adding a column of type ST_Spatial), and create R-tree indexes for them.

You can perform checks to see if a table contains a spatial column, or to check if a table has an R-tree index created for it. Refer to Checking for a Spatial Table or R-Tree Index on page 49 for details.

Tables created using MapInfo’s EasyLoader, or using any of the MapInfo Professional methods, are spatialized and all necessary columns and indexes are automatically created.

Using Your Existing Tables with SpatialWareTo prepare an existing table for use with SpatialWare, key, and geometry columns need to be added to it. You do not need to add a key column if your table already has one, but it must contain unique values and it must be defined as not null, and type integer. For tables of a non-trivial size, you should either designate the key column as the primary key, or create a unique index on the column to for performance reasons.

To spatialize an existing non-spatial table:

1. Alter the table to add a key column called SW_MEMBER and a column of type ST_Spatial, called SW_GEOMETRY. Set the key column to IDENTITY. alter table table1 add

sw_member integer not null IDENTITY Primary Key, sw_geometry st_spatial

The values of sw_member are set automatically for the existing records.2. You must now spatialize your table in order to use it. Refer to Spatialize a Table on page 45.

If necessary, create an R-tree index for the spatial table, and upload your data.


Chapter 4:

Creating a New Spatial TableThere are several ways to create a spatial table. In each method the necessary spatial columns and indexes are automatically created when using:

• T-SQL Commands – Lets you spatialize a table, or you can use other tools such as Enterprise Manager in SQL Server 2000. Refer to T-SQL Commands on page 45 for details.

• EasyLoader – Lets you upload TAB files to SQL Server. Refer to Chapter 25: Importing Data with EasyLoader.

• MapInfo Professional – Lets you save spatial tables by choosing File > Save Copy As or File > New Table from the main menu. Save Copy As this turns an existing table into a spatial table and store it in SQL Server. New Table creates a table from scratch, or patterns it after an existing table. Refer to MapInfo Professional on page 46 for details.

Although SQL Server allows table names of up to 128 characters, your spatial table names must be no more than 32 characters in length in order to use them with MapInfo client software, such as MapInfo Professional.

After creating a spatial table using one of these three methods, it is recommended that you create an R-tree index for it. Refer to Creating an R-Tree Index for a Spatial Table on page 48.

T-SQL CommandsYou do not need to spatialize a table if you uploaded it with EasyLoader or used MapInfo Professional’s New Table or Save Copy As features to create it. The spatialize procedures have already been performed.

To create tables using T-SQL commands for SpatialWare, do the following.

Create a New Table

The necessary columns are included when creating a new table. The following example creates a new table called geomtest with a key column called SW_MEMBER and a geometry column called SW_GEOMETRY. The key column is set to IDENTITY so sw_member is updated automatically, this helps in multi-user environments.

create table geomtest ( sw_member integer not null IDENTITY Primary Key, sw_geometry st_spatial

)

The key column (called sw_member in the previous example) should be the primary key whenever possible. If the application requires some other column for a primary key, you should create or designate a unique integer column, and create a unique index on it for increased performance.

Spatialize a Table

After preparing your table, spatialize it using one of the following methods:

• Spatialize Column procedure – A procedure called sp_sw_spatialize_column is provided to do four things: create an auxiliary table, create triggers on the base table, create the spatial index, and create spatial functions for the table. It is executed in the Query Analyzer (SQL Server 2000) or Management Studio (SQL Server 2005 or 2008) and has the following syntax:

User Guide 45

Creating a New Spatial Table

exec sp_sw_spatialize_column '<owner>','<table_name>', '<spatial_column>', '<key_column>'[, 'filegroup']

For example: exec sp_sw_spatialize_column 'dbo', 'geomtest','sw_geometry', 'sw_member'

If filegroup is not specified, then the default filegroup is used. To use the table with MapInfo clients, it must be made mappable using the 'Make Table Mappable’ tool.

Note SpatialWare uses a table's base name when creating auxiliary tables for it. For example, an auxiliary table for geomtest could be called geomtest#sw_geometry#t#sw_member.

• MapInfo Professional spatialize table tool – MapInfo Professional users can use the spatialize table tool, sw_spatialize_tab.mbx (refer to Spatializing Tables on page 69), which is installed with MapInfo Professional.

MapInfo ProfessionalWhen using MapInfo Professional as a client to SpatialWare, a new spatial table is created whenever you copy an existing spatial table or when you create a new table.

Copy a Table

To save a copy of your table using the MapInfo Professional client:

1. Choose File > Save Copy As. If the table is open, the Save Copy of Table As dialog displays. If more than one table is open, the Save Copy As dialog displays where you must select the appropriate table.

At least one table must be open for Save Copy As to be available. If necessary, establish a connection to the DBMS by clicking the Open DBMS Connection button in the upper right corner of the dialog.

2. Pick the name of the data source from the Save As Type drop-down list. 3. Specify a new table name for the copy. 4. Optionally set the projection by clicking on the Projection button. 5. Click Save. The Save As dialog displays.

Choose the location and/or filename for the local copy of the TAB file that is created during this operation.

6. Click Save.

Create a New Table

To save your table using the MapInfo Professional client, choose File > New Table, which starts a table creation wizard. The following instructions walk you through each dialog of the wizard.

A. New Table Dialog

1. Choose the view for the new table: Open New Browser and/or Open New Mapper or neither. 2. Set the initial table structure by choosing to Create New or Using Table and choosing a table as

the template. The table must be open for Using Table to be active. 3. Click Create. The New Table Structure dialog displays.


Chapter 4:

B. New Table Structure Dialog

1. Add field(s) and provide name, type and width as needed. Reorder as necessary. Set the projection by clicking the Projection button.

By default, the Table is Mappable checkbox is checked. All newly created tables are mappable, meaning that a spatial object column will be created and the table can be displayed in a Map window (even if the table contains no map objects). If you unchecked the Open New Mapper in step 2, then Table is Mappable is enabled. If you uncheck the Table is Mappable control, you will create a non-mappable table. For example, you may want to do this when you only want to upload data.

2. Click Create. The Create New Table dialog displays.

C. Create New Table Dialog

1. Choose the data source name from the Save as Type drop-down list or click the Open DBMS Connection button to establish a connection to a data source.

2. Give the new table a name and click Save. The New DBMS Table Options dialog displays.

D. New DBMS Table Options Dialog

1. From the General tab, set the filename and location of the local TAB file that will be created for the new DBMS table.

To have a key column created for the table, keep the Key column checkbox checked. Type in a name for the column or accept the default SW_MEMBER. Without a key column, the DBMS table will only be opened and read as a Linked table. It will not be editable.

2. Choose either Download Data (Linked Table) or Live Access. For Live Access, keep the Cache checkbox checked to keep the attributes and objects that have been read into memory accessible. Uncheck it if you want all the data to be fetched from the database each time you zoom or make other changes. You will get the most up to date data, but the process will be less efficient.

3. Choose the Spatial tab. Under the default Index Type tables is SpatialWare, provide a name for the Index Column or accept the default SW_GEOMETRY. This is where the spatial information about a record is stored.

4. Choose the Styles tab. Keep the Per Row Style checkbox checked if you wish to enable per row symbology whereby every object can have its own style. If unchecked the style of all objects is determined by the default object styles that are maintained in the MAPINFO_MAPCATALOG. Provide a name for the column which will be used to contain the style information, or accept the default name MI_STYLE. Set the Default Object Styles by clicking on the appropriate button for Symbol, Line and/or Region. These styles are used if the Per Row Style setting is not turned on for the table (unchecked) or the style information for a particular object does not exist (style column for that row is empty). The information set here is entered into the MAPINFO_MAPCATALOG.

5. Click OK to leave the New DBMS Table Options dialog. The new table is created and displayed according to the settings you chose in step 2.

An entry for the table is automatically added to the MAPCATALOG.

User Guide 47

Creating an R-Tree Index for a Spatial Table

Spatialize An Existing Non-Spatial Table

MapInfo Professional provides a spatialize table tool, called sw_spatialize_tab.mbx, that lets you spatialize an existing, non-spatial, table. This tool adds the a spatial column and a key column to a table, both of which are required for SpatialWare to access the table.

Creating an R-Tree Index for a Spatial TableWhat is an R-Tree Index?

An R-Tree index is a spatial index that is used to improve the speed of spatial queries issued against a spatial table. Once a spatial index is create, SpatialWare automatically maintains the index when you do transactional changes to the data via INSERT/UPDATE and DELETE statements from your application. It is recommended that your spatial tables have an R-tree index.

An R-tree index is used for indexing spatial data. For example, an R-tree index can more efficiently answers queries such as ‘select all points within a bounding rectangle’.

Generating the R-Tree Index

If a table contains a non-null and unique key column of type integer, a spatial (R-tree) index can be created on its spatial column. If you used the Spatialize Table MapBasic tool, described in Spatializing Tables on page 69, then an R-tree is created automatically. You do not need to perform this operation.

To generate an R-tree table for your spatial table, you must run a Create R-Tree procedure called sp_sw_create_rtree on the table. Its syntax is as follows:

exec sp_sw_create_rtree '<owner>', '<table_name>', '<spatial_column>', '<key_column>' [, '<filegroup>' [,'<prefetch_size>' [, '<cache_size>' ] ] ]

For example:

exec sp_sw_create_rtree 'dbo', 'geomtest', 'sw_geometry', 'sw_member', null, 200, 12000

The following parameters are optional:

• Filegroup – Filegroup can be explicitly specified to change storage behavior. By default, filegroup has a NULL value. This means that the DEFAULT filegroup is used for auxiliary table creation.

• Fetch size – Used to fine-tune processing time. Fetch size defines how many base table rows will be read at a time. By default, fetch size is ignored.

• Cache size – Used to fine-tune processing time. Cache size defines the size of an internal buffer in K bytes, which is used during the R-tree creation process. The default cache size value is 10,000.

Determining Cache Size

When creating an R-tree on a geometry column, you can tune the performance of the index creation process according to your system resources. For example, if your server machine has two Gigabytes of memory, then you would use a larger cache for R-tree creation.


Chapter 4:

A way to determine cache size is to use the minimum of the following two values for the cache size parameter:

• 10% of the physical RAM, expressed in kilobytes (an excessively large cache can result in performance degradation, due to cache traversal overheads).

• 0.07 * number of base table rows (an excessive value will effectively not be used in R-tree creation).

For example, if you are creating an index on a table with 6,000,000 rows on a server with 1GB of RAM, you would calculate:

• (0.10 * 1,000,000) = 100,000 and• (0.07 * 6,000,000) = 420,000

A good choice for cache size for this example is the minimum value of 100,000.

Background ReadingFor a more in-depth discussion of the R-tree methodology that SpatialWare uses, refer to the following publication:

Guttman, A., “R-trees: a Dynamic Index Structure for Spatial Searching”, Proc. ACM SIGMOD, p. 47-57, 1984.

Checking for a Spatial Table or R-Tree IndexProcedures are provided that help you check tables for spatial columns and for R-tree indexes.

Verifying Your Table has a Spatial Column

You can check if a table contains a spatialized column using the Column Is Spatialized procedure (sp_sw_column_is_spatialized). The syntax for this procedure is:

exec sp_sw_column_is_spatialized '<owner>', '<table_name>', '<spatial_column>', '<key_column>', @truth = <truth_parameter> output

Verifying Your Table has an R-Tree Index

You can check if a table has an R-tree index by using the R-Tree Is Created procedure (sp_sw_rtree_is_created). The syntax for this procedure is:

exec sp_sw_rtree_is_created '<owner>', '<table_name>', '<spatial_column>', '<key_column>', @truth = <truth_parameter> output

User Guide 49

Despatializing and Dropping Spatial Tables

Despatializing and Dropping Spatial TablesThere is a specific sequence of steps that you must follow to drop a spatial table, which is related to how the table was created. You drop the R-tree index first, despatialize the column, and then drop the table. Note that this is also how you would despatialize a table, but without dropping it. The complete sequence, from creating the table to dropping it, is as follows:

To drop a spatial table, do the following:

1. Drop the table’s R-tree index using the sp_sw_drop_rtree procedure. The syntax is: exec sp_sw_drop_rtree '<owner>', '<table_name>', '<spatial_column>', '<key_column>'

2. Despatialize the spatial column (the column of type ST_Spatial) by using the sp_sw_despatialize_column procedure. The syntax is: exec sp_sw_despatialize_column '<owner>', '<table_name>','<spatial_column>', '<key_column>'

3. Drop the table by typing the following:drop table <table_name>

Work Flow A Work Flow B


5
Adding Data to Spatial Tables
This section describes how to add spatial data to a table, and how to view geometry.

In this section:

What are Spatial Data? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Writing Spatial Data Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . .52Performing Batch Imports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53Updating and Deleting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

What are Spatial Data?

What are Spatial Data?SpatialWare allows you to store geometric objects that represent entities on the surface of the earth. Such entities may include:

• County boundaries, and drive time regions in the form of polygons.• Streets or rivers in the form of lines.• Customer locations or oil wells in the form of points.

These types of data, geometric objects, are referred to as spatial data.

Storing spatial data has some limitations, such as file size restrictions, lack of concurrency, and difficulty with backup and retrieval. SpatialWare resolves these issues. It lets you store, index, search, and retrieve spatial data in a sharable, scalable manner. It also lets you treat spatial data like numeric or attribute data, for storing, indexing, and querying.

Writing Spatial Data Using SQLBefore inserting spatial data into a table, ensure that it is spatially enabled (if necessary, check with the sp_sw_column_is_spatialized procedure). You can then add geometry to the SW_GEOMETRY column.

For example, the following uses the predefined string format for circle to insert a circle geometry into a table called geomtest:

insert into geomtest(sw_member, sw_geometry) values(1, 'ST_Spatial(

HG_Circle(ST_Point(11.11,22.22), ST_Point(55.55,44.44)))'

)

In this example, ST_Spatial( ) is part of the string inserted to the table geomtest. It is optional to include this, because the SpatialWare parser interprets the geometry string correctly with or without the ST_Spatial( ). The following would also work:

insert into geomtest(sw_member, sw_geometry) values(2, 'HG_Circle(ST_Point(11.11,22.22), ST_Point(55.55,44.44))'

)

Please refer toGeometry String Formats Used with SpatialWare on page 84 for a description of the string formats used with ST_Spatial. Refer also to Chapter 4: Defining Spatial Tables for a description of how to create a spatial table.

Checking Data was Correctly InsertedTo check that your geometry was inserted correctly, you can use HG_GetString. Type the following:

exec sp_spatial_query 'select HG_GetString(sw_geometry) from geomtest

'

This example returns:


Chapter 5:

ST_Spatial(HG_Circle(ST_Point(11.110000000000,22.220000000000),49.6854),ST_Point(60.795430460045,22.220000000000)

)

A geometry is always returned in the ST_Spatial(geometry) format. Refer to Chapter 6: Performing Queries on Spatial Data for more information on how to create spatial queries.

Note If the entire geometry string does not display, you may want to adjust your connection options. To do this in SQL Server 2000, choose Query > Current Connection Options > Advanced from the Query Analyzer. (If you are using SQL Server 2005 or 2008, refer to the online help for Management Studio.) Under the Advanced tab change your maximum character per column setting to 4000 (the default value will be 256, which may not be large enough to display geometry strings). The following statement finds the length of an ST_Spatial value:

select datalength(sw_geometry) from canada

Performing Batch ImportsThe MapInfo EasyLoader is provided to import data into SpatialWare. EasyLoader is a Windows-only utility available from MapInfo Corporation that allows you to upload MapInfo TAB files to a remote database, such as Microsoft SQL Server. The spatial information in the TAB files are maintained in the SQL Server database and are available for viewing and analyzing in MapInfo Professional.

For details on how to use EasyLoader, refer to Chapter 25: Importing Data with EasyLoader.

Determining When to Create a Spatial Index

There are performance costs associated with updating geometry columns that are indexed. If you have large volumes of data to load into a table, then it is recommended you create the spatial index after you load the data. Refer to Creating an R-Tree Index for a Spatial Table on page 48 for more information about R-tree indexes.

Updating and Deleting DataUpdating and deleting spatial data can be performed through the standard SQL statements, update and delete. For example:

update spotelev set sw_geometry='ST_Spatial(ST_Point(1755500,10702500))'where sw_member=1

delete from spotelev where sw_member>500

Database triggers are created when you spatialize a table. These triggers cast spatial data into the appropriate binary format and maintain the spatial indexes when you do insert, update, or delete operations on a table.

User Guide 53

Updating and Deleting Data

When you want to determine the rows to be updated or deleted using spatial criteria, you can do it in two steps: the first step performs the spatial query to determine the rows to be deleted/updated, the second step performs the actual delete or update statement. For example:

exec sp_spatial_query 'select sw_member into temp_table from flood100 where ST_Overlaps(sw_geometry,ST_Spatial(''HG_Box(1756600,10703200,1755500,10702500)''))

'delete from flood100 where sw_member=any(select * from temp_table)drop table temp_table


6
Performing Queries on Spatial Data
Data query refers to performing spatial SQL queries. These notes describe how to perform SQL queries on spatial data.

In this section:

How SpatialWare Queries Data . . . . . . . . . . . . . . . . . . . . . . . . . . . .56Using the sp_spatial_query Stored Procedure . . . . . . . . . . . . . . .57Saving the Result of a Query into a Table . . . . . . . . . . . . . . . . . . .62Using Global Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . .63Performing Nearest Neighbor Operations . . . . . . . . . . . . . . . . . . .64

How SpatialWare Queries Data

How SpatialWare Queries DataSpatialWare supports two ways for querying data: using a stored procedure called sp_spatial_query, and using a set of user-defined functions (UDF) that can be used as a part of SQL Server's SELECT, UPDATE, INSERT, or DELETE statement.

The Stored Procedure sp_spatial_queryThis is a stored procedure that accepts a SQL Statement as an argument and returns a result set. The SQL supported by this stored procedure is a significant subset of SQL. It aims to provide access to all the spatial functions in a clean and efficient way. This interface provides a workaround to SQL Server's programmability limitations with large binary/text columns (image and text datatypes). This interface also facilitates simple and transparent index access, and supports aggregate functions.

The following example finds the flood zones that overlap a given rectangular window:

exec sp_spatial_query 'select sw_member, sw_geometryfrom flood100 where ST_Overlaps(sw_geometry,

HG_Box(1756600,10703200, 1755500,10702500))'

This query returns a default result set (referred to in previous SQL Server releases as the firehose cursor).

Note the following:

• The query is actually passed as a string literal into the stored procedure.• The query is in the form of a string. Therefore, the string literals within the query are escaped

with two single quotes. For example:exec sp_spatial_query 'select sw_member, sw_geometryfrom flood100 where ST_Overlaps(sw_geometry,

ST_Spatial(''HG_Circle(ST_Point(1,2),ST_Point(4,6))'')'

Due to this reason, this form of querying does not support binding parameters.

Refer to Using the sp_spatial_query Stored Procedure on page 57 for details.

User Defined Functions (UDF)SpatialWare supports two categories of UDFs. Scalar UDFs that return a single value, and a table-valued UDF that returns a table of values (typically as a result of a spatial index search).

For example:

select dbo.hg_envelope(sw_geometry) from flood100 where flood100_cm = '44500002'

And:

select a.sw_member, a.sw_geometryfrom flood100 a, flood100#s#sw_geometry#s#sw_member(


Chapter 6:

'HG_Box(1756600,10703200, 1755500,10702500)', 'st_overlaps', 1) bwhere a.sw_member = b.member

Note the following:

• The invocation of the spatial index is explicit. The caller invokes a user-defined function to identify the rows that satisfy the spatial criteria (unlike with ST_Spatial).

• The UDF name is coined using a naming convention, out of the name of the table, spatial column and attribute column.

• There are two types of user-defined functions, as illustrated by the two examples. The functions in the first category are plain scalar functions, such as HG_Envelope, or ST_Area. Functions in the other category perform spatial index access.

• Currently, the SQL Server user-defined functions cannot return large datatypes (over 8K), such as ST_Spatial. Similarly, you cannot declare a variable of type text, image, or st_spatial in Transact SQL scripts. This limits the usefulness of UDF in a general case, as SpatialWare functions such as ST_Buffer cannot be supported as user-defined functions.

Refer to Chapter 21: User Defined Functions for details.

Guidelines for choosing between sp_spatial_query and UDFsYou can perform spatial analysis using SpatialWare in two ways, sp_spatial_query and user-defined function. In some cases, there is comparable functionality in the two forms. This section provides some guidelines on choosing between the two.

If you are accessing SpatialWare functionality from the expert dialog MapInfo Professional, or using a MapBasic program using commands like Server_execute, use sp_spatial_query. In a general case, we expect sp_spatial_query to be adequate to perform spatial queries.

For Transact-SQL developers who want to query simple properties of geometries like area, handling a result set returned by sp_spatial_query could be quite cumbersome. They may want to use the UDF interface in such cases.

In simple window queries that return selected rows from a table within a rectangular window, UDFs are both quicker and scalable.

Use sp_spatial_query for functions that return a geometry, because UDFs cannot return geometries.

When you want to address the results of spatial query within a larger query, use UDFs.

sp_spatial_query returns results in a default result set (also called Firehose cursor in the older SQL Server literature). Default result sets suffer from some limitations. They can only be used to send result sets back to a client application, or as a part of INSERT into ... EXEC sp_spatial_query.

Due to SQL Server limitations, sp_spatial_query may not be used within another UDF, or as a part of a larger SELECT statements. The UDFs provide a good alternative to work around these limitations.

Using the sp_spatial_query Stored ProcedureYou can do normal select statements that get processed by SQL Server, and in addition you can use the stored procedure sp_spatial_query to perform powerful spatial queries.

User Guide 57

Using the sp_spatial_query Stored Procedure

SQL queries are performed using the SQL Server 2000 isql utility or Query Analyzer, or th SQL Server 2005/2008 sqlcmd utility or Management Studio. Spatial queries are made using the sp_spatial_query stored procedure:

exec sp_spatial_query '<query>' [, <index_control>]

This procedure returns a result set. The data type of the columns in the result set are determined by the query.

Note For sp_spatial_query usage notes and caveats please refer to Chapter 23: Usage and Caveats.

ParametersYou can use sp_spatial_query to perform simple spatial queries described by the following grammar. SQL Server terminology is used here even though there may be limitations and extensions to these terms as they apply to SpatialWare.

<select statement> ::= <query specification><query specification> ::= SELECT <select_list> [INTO new_table] FROM {<table_source>} [,...10] [WHERE <search_condition>]<select_list> ::= * | { { <table_name> | view_name | table_alias }.* | { column_name | <spatial expression> } [AS column_alias] } [,...n]<spatial expression> ::= <spatial function keyword> ( {column | constant | <spatial expression>} [, ...n] )<spatial function keyword> ::= ST_Buffer | ......

Refer to the section on Chapter 19: Spatial Functions for spatial function descriptions (e.g., ST_Buffer).

<table_source> ::= <table_name> [table_alias] | view_name [table_alias]<table_name> ::= [[database.]owner.]table<search_condition> ::= <predicate> | <spatial_predicate> | (<search_condition>) [ {AND <search_condition>} [...n] ] <predicate> ::= { expression { = | <> | != | > | >= | < | <= | !< | >! } expression | string_expression [NOT] LIKE string_expression [ESCAPE 'escape_character'] | expression [NOT] BETWEEN expression AND expression | expression IS [NOT] NULL


Chapter 6:

}<spatial predicate> ::= [NOT] <spatial predicate keyword> ( {column | constant | <spatial expression>} [, ...n] )<spatial predicate keyword> ::= ST_Overlaps | ST_Contains |......

Refer to Chapter 20: Spatial Predicate Functions, for predicate function descriptions (e.g., ST_Overlaps and ST_Contains).

UsageThe <query> parameter is encased within single quotes. Strings, such as for ST_Spatial, are encased in two single quotes to escape the sp_spatial_query. For example (single quotes are in bold):

exec sp_spatial_query 'select HG_Azimuth_2pts(

spotelev.sw_geometry, ST_Spatial(''ST_Point(1753960.182000,10698421.103000,2784.945100)'')

from spotelev'

Caveats• If you use the "select ... into ..." construct in sp_spatial_query, and you have a literal in the select

list, it will fail.For example, the following statement:exec sp_spatial_query 'select 101 as m into tab2 from tab1'

will return the following error:Server: Msg 173, Level 11, State 1, Line 0The definition for column 'm' must include a data type.

• When a statement has no spatial component in it, and if the SpatialWare parser cannot parse a SQL syntax phrase for processing by SQL Server, the query gets "passed through" to SQL Server.

For example, the following query will work, even though the sp_spatial_query grammar does not support the TOP 10 clause.

exec sp_spatial_query 'select top 10 sw_member, sw_geometry from flood100

'The following will fail:

exec sp_spatial_query 'select top 10 sw_member, HG_GetString(sw_geometry) from flood100

'• If you add a spatial function (HG_GetString) to this example, the statement will fail. This is

because the query passes through to the SQL Server parser (because of the ORDER BY clause), which cannot parse the spatial function. Please note that this implies a general restriction on the use of aggregate functions or sub-select clauses together with spatial functions.exec sp_spatial_query 'select sw_member, HG_GetString(sw_geometry) from parcel order by

User Guide 59

Using the sp_spatial_query Stored Procedure

sw_member'Server: Msg 70802, Level 11, State 1, Line 0SPW_PARSER_INVALID_PARSETREE wherelist_verify

Controlling the Use of IndexesThe spatial query has an optional second parameter, that controls the use of spatial indexes (index_control).

exec sp_spatial_query '<query>' [, <index_control>]

The index control is a boolean parameter. If you supply FALSE for this argument, then the spatial query will not use an R-tree index. This is helpful if the SQL statement includes spatial predicates and any additional conditions. For example:

exec sp_spatial_query 'select sw_member from geomtestwhere st_overlaps(

sw_geometry, ST_Spatial(''ST_Point(-95, 55)''), 5.1)and sw_member <= 100

', false

If the programmer knows that the sw_member <=100 clause condition has much better selectivity than the ST_Overlaps predicate, he/she can disable the use of the spatial index to improve performance.

Order By and Group By SupportSpatialWare supports order by and group by clauses in sp_spatial_query.

Order By Clause

The syntax of the Order by clause is as follows:

ORDER BY {order_by_expression [ASC | DESC] } [,...n]

The order_by_expression specifies a column on which to sort. A sort column can be a column name or column alias. If you want to sort by the return value of a spatial function, specify it through an alias. The items included in the ORDER BY clause must appear in the select list if there are spatial function columns in the ORDER BY clause.

If there is an alias for a spatial function in the order by clause, then in the select list can not have items that include spatial functions and return a value of type ST_Spatial.

For example:

exec sp_spatial_query 'select pin, ST_Area(sw_geometry) as area from parcel order by area

'

The following will not work:


Chapter 6:

exec sp_spatial_query 'select pin, st_area(sw_geometry) from parcel order by st_area(sw_geometry)

'

Instead, rewrite it as:

exec sp_spatial_query 'select sw_member, st_buffer(sw_geometry, 20, null) as buf,

st_area(sw_geometry) as area from parcelorder by area

'

Group By Clause

The syntax of the Group by clause is as follows:

GROUP BY group_by_column [,...n]

If aggregate functions are included in the SELECT list, then the non-aggregate columns in the SELECT list must be included in the GROUP BY list. The select list item must be either an aggregate function or a column name. Expressions are not supported in the SELECT list.

The following numeric aggregate functions are supported with group by:

• SUM• COUNT• MIN• MAX• AVG

The following geometry aggregate functions are supported with group by:

• HG_Aggspatial• HG_Aggunion• HG_Aggintersection• HG_Aggconvex_Hull• HG_Bounding_Box

Examplesexec sp_spatial_query '

select state, avg(ST_X(sw_geometry)), avg(ST_Y(sw_geometry)) from uscty_8k group by state

'

Spatial aggregates in conjunction with group by:

exec sp_spatial_query 'select state, HG_AggSpatial(sw_geometry) from uscty_8k group by state

'

User Guide 61

Saving the Result of a Query into a Table

Limitations

Take note of the following limitations:

• You can only group by column names or aliases that are in the select list.• Group by and order by can not co-exist in a query.• The value returned by aggregate functions can not be passed as a parameter to another

function. For example, HG_Getstring(HG_AggUnion(sw_geometry)) will not work.

Examples for cases that are not supported:

• Order by and group by do not work together. The following will not work:exec sp_spatial_query '

select state, max(st_x(sw_geometry) from uscty_8k group by state order by state

'

• You can not embed aggregates and group by in functions. The following will not work:exec sp_spatial_query '

select state, HG_GetString(HG_AggSpatial(sw_geometry)) from uscty_8k group by state

'

• You need to include the column you group by in the select list. The following will not work. To make it work, simply add state to the select list. exec sp_spatial_query '

select count(*) from uscty_8k group by state'

Saving the Result of a Query into a Table

Creating an Output TableYou will need to create an output table if one does not already exist. This example performs a query to compute an area, then saves the results into a temporary table for further processing.

exec sp_spatial_query 'select a.sw_member as id, Province as province,

ST_Area(a.sw_geometry) as areainto output_tablefrom canada a

'select id, province, area from output_table order by area-- After performing such a query you will want to drop-- the temporary table.drop table output_table

Note This statement attempts to create the table output_table and therefore it must not already exist. Remember that the table name can not be a reserved word (such as temp), unless it is bracketed (i.e., [temp]), or QUOTED_IDENTIFIER is set to ON and double quoted (i.e., "temp"). You must use an alias for the result of a function. Note how the above example uses an alias for the result of a function (area is the alias for the result from ST_Area).


Chapter 6:

Outputting to an Existing TableYou can output the results into an existing table, provided it has the correct structure. Use the INSERT statement with the sp_spatial_query procedure to insert the results of a spatial query into an already existing table.

create table output_table (id integer, province varchar(40), area float)insert into output_table exec sp_spatial_query '

select a.sw_member as id, Province as province, ST_Area(a.sw_geometry)as area

from canada a'

Note that the such an insert statement can also be used with temporary tables.

create table #output_table (id integer, province varchar(40), area float)insert into #output_table

exec sp_spatial_query 'select a.sw_member as id, Province as province, ST_Area(a.sw_geometry)

as areafrom canada a'

Note As documented in the SQL Server INSERT (T-SQL) statement, for SQL Server version 7.0, the columns for this usage of the INSERT statement can not be of type St_Spatial, image or text.

Using Global Temporary TablesQueries you execute via sp_spatial_query can now reference a global temporary table. The advantage of using a global temporary table instead of a permanent table is that it automatically is removed when the connection that creates it is terminated.

A global temporary table is a table that is visible to all connections, but has a lifespan not exceeding that of the connection that creates it. Global temporary tables in SQL Server are named with ## as a prefix. They are stored in the tempdb database, regardless of what the current database in use is. Local temporary tables, by contrast, are just visible to the connection that creates them. They have a prefix of #. You cannot use local temporary tables with sp_spatial_query.

You can create spatial indexes on global temporary tables. The rules for the life of the index will be similar to the rules for the life of the base table. For example, they get cleaned up when the connection that created it terminates.

Please note that you cannot have triggers on a temporary table – global or otherwise. Therefore, you can not spatialize a temporary table and have the triggers rewrite the geometries from string format into binary format. All geometries inserted into a global temporary table need to be in the right binary format. For the same reason, you need to create R-trees on temporary tables after all the data is in place, as shown in the following example.

create table ##globalTemp (sw_member integer identity,

User Guide 63

Performing Nearest Neighbor Operations

pin varchar(12),sw_geometry st_spatial,

)

-- copy some records to this table based on some-- preprocessing criteriainsert into ##globalTemp (pin, sw_geometry)

select pin, sw_geometry from parcel where pin like '45600002%'

select count(*) from ##globalTemp

exec sp_sw_spatialize_column 'dbo', '##globalTemp', 'sw_geometry', 'sw_member'exec sp_sw_create_rtree 'dbo', '##globalTemp', 'sw_geometry', 'sw_member'

exec sp_spatial_query 'select a.pin from ##globalTemp a, privbldg bwhere st_overlaps(a.sw_geometry, b.sw_geometry)'

-- cleanupexec sp_sw_drop_rtree 'dbo', '##globalTemp', 'sw_geometry', 'sw_member'exec sp_sw_despatialize_column 'dbo', '##globalTemp', 'sw_geometry', 'sw_member'drop table ##globalTemp

As a tip, if you want to create global temporary tables with unique, coined names, then use the SQL Server function called NewId to create unique string identifiers.

declare @temp_tname varchar(50)declare @sqlStmt varchar (1000)select @temp_tname = newid()set @sqlStmt =

'create table [##'+ @temp_tname + '] (sw_member integer)'execute (@sqlStmt)

Performing Nearest Neighbor OperationsSpatialWare supports nearest neighbor operations using the sp_nearest stored procedure. The sp_nearest finds the geometries closest to a given geometry. The search can be refined using non-spatial criteria. The sp_nearest works from an R-tree, which must be created on a base table.

Parameters

The first four parameters are the same as for R-tree creation with sp_sw_create_rtree.

• @owner SYSNAME – Owner of the base table.• @table SYSNAME – Base table.• @spatialcolumn SYSNAME – Geometry column in base table.• @keycolumn SYSNAME – Integer not null primary key or unique column in base table.• @geo ST_Spatial – Target geometry (any geometry, not just points).


Chapter 6:

• @num INT – Maximum number of rows being requested in output result set (i.e., how many nearest, also satisfying other conditions given in @query); even in case of ties, this is not exceeded (i.e., if 10 geometries are equally close, and @num is 3, then some arbitrary three are returned).

• @max_dist – Maximum distance to search from target geometry, otherwise NULL.• @query – Simple query specifying everything except for the nearest condition. It can also be an

insert statement, which is useful for saving results to a table ([INSERT...]SELECT...FROM...[WHERE...] – only basic parsing is implemented in this release).

• @units – When the geometry data is in Longitude/Latitude, distances are calculated as spherical distances, and the units are as specified by this parameter, for example 'km'. When the geometry data is not in Longitude/Latitude, this parameter should be NULL. To see a list of valid spherical linear units, refer to Supported Units on page 120.

Returns

The result set is in the same table format as @query would return, but with an extra "distance" column (FLOAT) added. The rows are returned in ascending order of distance.

Examples

The following selects the nearest 10 public buildings from a given point, within a maximum distance of 10000 units.

sp_nearest'dbo','pubbldg','sw_geometry','sw_member','ST_Point(1754670.0, 10699431.0)',10,10000.0,'select sw_member, sw_geometry from pubbldg', null

The following returns rows for the five nearest public buildings to a given point, and no further than 10000.0 from that point.

sp_nearest'dbo','pubbldg','sw_geometry','sw_member','ST_Point(1754670.0, 10699431.0)',5,10000.0,'select sw_member, sw_geometry from pubbldg where bldg_type=1', null

The following finds the five nearest public buildings to a given point, that are no further than 10000.0 from the point, and stores the result in the table called ##pb.

create table ##pb (sw_member integer primary key, sw_geometry st_spatial, dist float)

sp_nearest'dbo','pubbldg','sw_geometry','sw_member','ST_Point(1754670.0, 10699431.0)',5,10000.0,'insert into ##pb select sw_member, sw_geometry from pubbldg

where bldg_type=1', null

Notes

HG_Distance, which calculates Cartesian distance, is used in the implementation when @units is NULL; otherwise HG_SphericalDistance is used.

User Guide 65

Performing Nearest Neighbor Operations


7
Working with MapInfo Client Software
This section discusses the use of clients with SpatialWare. It provides database set up information, hints, tips, and suggestions for working with MapInfo client.

In this section:

Preparing to Work with a MapInfo Client . . . . . . . . . . . . . . . . . . . .68Supporting Case-Sensitive Databases. . . . . . . . . . . . . . . . . . . . . .70Working with Spatial Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .70Working with MapInfo Professional . . . . . . . . . . . . . . . . . . . . . . . .71Working with MapInfo MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71

Preparing to Work with a MapInfo Client

Preparing to Work with a MapInfo Client

Creating a Data SourceBefore you can access any data in SQL Server from a client application, you must create a data source, known as a Data Source Name (DSN). To create a DSN you need an ODBC driver. SpatialWare is verified with the Microsoft SQL Server ODBC Driver.

MapInfo client products are verified with the MapInfo driver. Therefore, it is recommended that MapInfo client products use the MapInfo driver, which is installed automatically with MapInfo DBMS support from the MapInfo client installer.

DSNs are created using the OBDC Data Source Administrator, but if you are using MapInfo Professional as a client, data sources may also be created there.

Creating a Data Source from within MapInfo Professional

If you are using MapInfo Professional as a client, you can create a Data Source from within the application. This example illustrates how a DSN is created using the MapInfo SQL Server driver.

1. From MapInfo Professional, choose File > Open. At the Open dialog, click the DBMS Connection button on the upper right of the dialog. The Open DBMS Connection dialog appears.

2. Choose ODBC and click New. The Select Data Source dialog displays. 3. From the File Data Source or Machine Data Source tab, click the New button and proceed

through the wizard to choose the driver for the data source (MapInfo SQL Server Driver 4.00) and provide other connection information. On the Advanced tab, check the Enable Quoted Identifiers checkbox.

Creating a Data Source Using the ODBC Data Source Administrator

Follow these initial instructions, then continue for the SQL Server driver:

1. Open the ODBC Data Source Administrator. Select Settings > Control Panel from the Start menu.

2. Choose Administrative Tools > Data Sources (ODBC) to display the ODBC Data Source Administrator.

3. Ensure the User DSN tab is selected, then click the Add button to display the Create New Data Source dialog.

Continue with the following instructions.

Setup for the SQL Server Driver

To set up a DSN that makes use of the SQL Server driver, from the Create New Data Source do the following:

1. Choose SQL Server Driver from the Create New Data Source dialog.2. Double-click the driver to display the Create a New Data Source for SQL Server dialog.3. Enter the data source name, which is any name you wish to use to identify the data source you

are creating. Optionally enter a description for the data source, and choose a SQL Server to which the DSN will connect. Click Next.


Chapter 7:

4. Specify Windows or SQL Server authentication, then click Next.5. Select a database you wish to be the default database for the connection from the pull-down list,

and ensure the Quoted Identifiers box is checked. Click Next.6. Click Finish to complete the process.

Spatializing TablesA MapBasic tool called Spatialize Table (sw_spatialize_tab.mbx) is supplied with MapInfo Professional.

You must have ALTER privileges for the table you want to spatialize. The table must reside in a spatially enabled database. Check with your DBA to determine if the database has been prepared for spatial information. If you have admin privileges, you can spatialize the database. To run the Spatialize Table tool:

1. From the MapInfo Professional Tools menu, choose Run MapBasic Program and navigate to the Tools directory and run sw_spatialize_tab.mbx. You can also add the tool to Tool Manager and run it directly off the Tools menu.

2. Make a connection to the SQL Server database where the table you wish to spatialize is stored. At the Connection Manager dialog, select an existing connection or click New to create one. When you have a connection, the Spatializing the Table dialog displays.

3. Choose the Table from the Tables drop-down list. 4. To create the spatial column, click the Add Spatial Column button. A column of type

ST_SPATIAL is created and listed in the drop-down list. The default column name is SW_GEOMETRY.

5. To set the Key column, choose the appropriate column and click the Add Key Column button. The chosen column will be renamed with the default Key column name SW_MEMBER. The column will not be renamed if the existing column already has a Key defined for it. It must be of type integer and be unique, not null.

6. As a final step to spatialize the table, click the Spatialize button. The table has a spatial index created on the geometry column, and the spatialize operation is carried out. The table is now ready to accept spatial information. The table must now be made mappable so it can be viewed in MapInfo Professional. Refer to your MapInfo Professional documentation for more information.

Unique Identifier Column Requirement for Tables

SpatialWare tables must have a uniquely constrained column in order to be edited. This column clearly identifies the rows that have been edited and that need to be updated in the server database. Such tables are marked as non-editable within a client.

The name of the key column can be different from SW_MEMBER, but it must be integer, not null, and be unique (preferably the primary key). The geometry column can be any legal name. By default it is called SW_GEOMETRY.

User Guide 69

Supporting Case-Sensitive Databases

Supporting Case-Sensitive DatabasesSpatialWare supports case-sensitive SQL Server databases. However, some older releases of MapInfo client applications do not have the necessary syntax changes to remotely work with case-sensitive SQL Server databases. MapInfo Professional 7.0 does have these changes. If you are using a MapInfo client other than MapInfo Professional, please do not use it with a case-sensitive SQL Server database. If running spatial queries only from the server, then case-sensitive table access is supported as per the following notes.

Case sensitivity is determined in SQL Server by the choice of character set sort order at installation time. It is case-insensitive by default.

When executing sp_spatial_query, SpatialWare determines whether the server is case-insensitive or case-sensitive. It adopts the corresponding behavior for handling database, owner, table, and column names.

Many strings in queries are not manipulated directly by SpatialWare, but are passed through to SQL Server, which handles them according to its case sensitivity setting. For example, the following two statements are not the same if you are working with a case-sensitive database, because the city name is in mixed case (Troy) or in a single case (TROY):

exec sp_spatial_query 'select hg_getstring(sw_geometry) from t1 where city=''Troy''

'exec sp_spatial_query '

select hg_getstring(sw_geometry) from t1 where city=''TROY'''

However, there is an exception. Some spatial functions take string arguments. These strings are handled differently by SpatialWare; they are always treated as case-insensitive. These spatial functions are ST_Spatial, HG_GeometryFromText, HG_Clean_S and HG_CSTransform. For example, the following will both parse in SpatialWare regardless of the case sensitivity setting of the database:

hg_getstring(''ST_Spatial(ST_Point(1,1))'')hg_getstring(''ST_SPATIAL(ST_POINT(1,1))'')

Other stored procedures, such as sp_sw_create_rtree, are also under the control of the SQL Server case sensitivity environment.

Some MapInfo client application releases (i.e., MapInfo Professional 6.5 and earlier, and MapXtreme), do not interface with SQL Server case sensitive databases. Therefore, case insensitive databases should be used with these client applications.

Working with Spatial FunctionsWhen using MapInfo client applications with SpatialWare for SQL Server, the results of selects using spatial functions can be edited and saved back to the original table. For example, the results of the following statement, which will be a set of buffer areas around the lakes, could be edited and the modified results saved:


Chapter 7:

exec sp_spatial_query 'select ST_buffer(LAKE.SW_GEOMETRY, 66.0, 1.0)from LAKE

'

The edited buffer of a particular lake would then replace the original lake geometry. This behavior is different from SpatialWare implementations on other RDBMSs where buffer results cannot be edited and saved. This difference is noted here for clarity.

Working with MapInfo Professional

Remote ToolsSeveral tools are installed with the SpatialWare server software that can be copied to a client machine. They can be used on machines where MapInfo Professional is installed that are used to access the server database across a network. To use these tools you must first install them on the client machine. These tools are:

• EasyLoader – This is a flexible Data Loader Utility used to import MapInfo format TAB file into tables in a SpatialWare SQL Server database.

• Spatialize Table Tool – This is a MapBasic script (and associated files) which is used to prepare a SQL Server table to accept spatial information.

Spatial functionality can be accessed through most Microsoft SQL Server client side tools. Examples of useful tools in SQL Server 2000 include the Enterprise Manager (used for viewing and managing multiple SQL Server databases), and the Query Analyzer (used for submitting SQL queries, and examining database structures).


TipsThe following are a few tips to keep in mind when performing spatial database queries using either the expert dialog or a custom MapBasic program:

• The expert dialog adds the sp_spatial_query prefix and encloses the query in quotes, so you should not add the sp_spatial_query prefix.

• If you have strings within the query then you don't have to escape the string using two single quote ( ' ) characters instead of one. The expert dialog performs this automatically. For example: select sw_member from rdpaved where rdname like 'GLENN%'

Note The string in the where clause is 'GLENN%' and not ''GLENN%''.

Working with MapInfo MapXWhen you use MapX with SQL Server, the Quoted Identifier setting should be set to ON for all connections. This can be set at the time of configuring the client's DSN or can be specified in the Connection string passed to MapX by adding the "QuotedID=Yes" clause.

User Guide 71

Working with MapInfo MapX

Refer to Setting the QUOTED_IDENTIFIER on page 41 for more details.


Part 2: Developer Reference

Topics:

Constructing Geometry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75ST_Spatial Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Understanding Geometry Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Performing Coordinate System Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

8
Constructing Geometry
This chapter describes how to construct geometry using SpatialWare’s Constructor functions and predefined string formats. The resulting geometry is in the expected format used by SpatialWare’s functions.

In this section:

What is Geometry and How do I Construct It? . . . . . . . . . . . . . . .76An Overview of the Spatial Data Type Hierarchy . . . . . . . . . . . . .81Creating Geometry Using the ST_Spatial Function . . . . . . . . . . .82Geometry String Formats Used with SpatialWare . . . . . . . . . . . .84

What is Geometry and How do I Construct It?

What is Geometry and How do I Construct It?SpatialWare works with data in a predefined format. This format specifies types of geometry, such as points, boxes, and circles.

There are geometry-specific constructor functions such as HG_Circle that create basic geometries, and a more general constructor function, ST_Spatial, to create more complex geometries. All constructor functions return the ST_Spatial type.

How is Geometry Defined?Spatial data consists of geometries, such as points, lines, polygons, or collections of these in some combination. The SQL Server datatype called ST_Spatial stores geometries. Although the database stores geometries in a format that is not human-readable, you can create and query geometries using a general string representation.

The textual representation of geometry is useful for both reading and writing geometries. You can insert a geometry into a spatialized table by providing the textual description described below. When you do so, SpatialWare's internal triggers rewrite the string into the internal storage representation. You can also query a stored geometry in textual form by doing a query like:

exec sp_spatial_query 'select sw_member, HG_GetString(sw_geometry) from lake

'

The text string for a point contains the following information, where “ST_Point” specifies the geometry type as a point and the information within the brackets “(x,y)” defines it.

'ST_Point(1.0, 2.1)'

A circle (circular line) is defined by a centre point and a radius value.

The text string for this type of circle is:

'HG_Circle(ST_Point(11.11,22.22), 10)'

In some cases, a geometry can be described in the textual form in more than one way. This is true for the HG_Circle element in the text description, which may also be defined using two points: a centre point and a point on its diameter.


Chapter 8:

The text string for this type of circle is:

'HG_Circle(ST_Point(11.11,22.22),ST_Point(55.55,44.44))'

Another example is a polygon described by a polyline that forms the outer boundary:

'ST_Polygon(ST_Polyline(LIST{

ST_Point(11, 11), ST_Point(12,11), ST_Point(12,12), ST_Point(11,12), ST_Point(11,11)

}))'

As you can see, these strings can express a wider variety of geometries than the built-in functions like ST_Point( ) and HG_Box( ).

Geometry Standards

The spatial data types are in a defined format that follows industry standards, such as the OpenGIS standards. Refer to Background Information on Industry Standards on page 21 for information about standards.

Spatial data types that follow the standards are prefixed with ST_ (e.g., ST_Point). Geometry that extends the standards is prefixed by HG_ (e.g., HG_Circle).

How do I Construct Geometry?There are two ways to create geometry directly using SpatialWare for SQL Server: working with the geometry strings lets you create general or elaborate geometry, working with the Constructor functions lets you quickly create simple geometry.

Working with Geometry Strings

The geometry text string is the format used for input or output to a spatial table. The text string format makes it easier for you to work with geometry. When inserting geometry to a spatial table, SpatialWare triggers convert the geometry text string to a binary format. Triggers convert the binary format to a text string when geometry is output from a spatial query.

User Guide 77


For example, HG_Triangle geometry type is defined using a list of three points. It’s string format is as follows:

'HG_Triangle(LIST{ST_Point(1,3), ST_Point(5,7), ST_Point(9,11)})'

When adding geometry to a table, you can supply the geometry string format in the T-SQL command:

insert into geomtest(sw_member, sw_geometry) values(3, 'HG_Triangle(LIST{ST_Point(1,3), ST_Point(5,7), ST_Point(9,11)})'

)

SpatialWare triggers convert the HG_Triangle text string to binary format in the geomtest table. The triggers are activated when a text string is being inserted to a spatial table’s spatial column, which is sw_geometry in this example.

Refer to Chapter 4: Defining Spatial Tables for a full explanation of spatial tables. Also, refer to Creating a New Spatial Table on page 45 for how to create the geomtest table.

Working with Constructor Functions

SpatialWare provides some constructor functions that are a simple interface through which you can create basic geometry, such as a point, box, and circle.

These functions follow the model used to define geometry. For example, the function for creating a point is called HG_Point. This function constructs a geometry of type HG_Point.

The following functions construct basic geometry:

• ST_Point – Constructs an ST_Point geometry.• HG_Box – Constructs an HG_Box geometry using x,y values.• HG_Circle – Constructs an HG_Circle using centre point and radius.• HG_LL_Circle – Constructs an HG_Circle using Longitude/Latitude and radius values. Note that

this function is listed with the Spatial functions.• HG_SphericalCircle – Constructs an HG_Circle and lets you specify the distance units for the

radius value. Note that this function is listed with the Spatial functions.

In addition to these simple functions, SpatialWare provides the ST_Spatial constructor function. This function lets you generate all supported spatial data types, such as HG_Circle, ST_Polyline, and ST_Polygon. The syntax of ST_Spatial is described under Creating Geometry Using the ST_Spatial Function on page 82.

The ST_Spatial constructor function is the most general constructor. It allows you to specify multiple spatial data types in a single construction in order to create an arbitrary geometry. This gives you the flexibility to create geometry collections.


Chapter 8:

A geometry collection is a geometry comprised of multiple geometry string formats. For example, a land parcel that is subdivided by a roadway.

For a more complete discussion of geometry collections, refer to Chapter 10: Understanding Geometry Collections.

How Do I Perform Spatial Queries?Constructor functions are called within an sp_spatial_query, or as a User Defined Function (UDF). Note that usage varies by function as summarized under Summary of where to use Constructor Functions on page 80.

sp_spatial_query

The usage of sp_spatial_query is described in more detail in Chapter 6: Performing Queries on Spatial Data, but looks like this:

sp_spatial_query 'select sw_member from geomtestwhere ST_Overlaps(sw_geometry,

ST_Spatial(''HG_Box(11.22,33.44,55.66,77.88)''))

'

This example selects those geometries from the geomtest table that overlap with a box defined by lower x,y and upper x,y values. This HG_Box type is used as part of the string syntax of ST_Spatial.

The same statement can be made using the HG_Box Constructor function. This is because HG_Box, as defined by x,y values, is not just a data type.

sp_spatial_query 'select sw_member from geomtestwhere ST_Overlaps(sw_geometry,

HG_Box(11.22,33.44,55.66,77.88))

'

UDF

Within a UDF, the geometry string is available for query:

select sw_member from geomtest where dbo.ST_Overlaps(sw_geometry,

'HG_Box(11.22,33.44,55.66,77.88)')=1

This same statement can be made using the HG_Box constructor, which is available as a UDF:

select sw_member from geomtest

User Guide 79


where dbo.ST_Overlaps(sw_geometry,dbo.HG_Box(11.22,33.44,55.66,77.88)

)=1

Note that ST_Spatial is a data type and Constructor function, but is not available as a UDF. The following table summarizes where you can use Constructor functions.

Summary of where to use Constructor Functions

Geometry-specific functions, such as HG_Circle, are considered to be convenience constructor functions. They can be called either within sp_spatial_query or as a User Defined Function (UDF).

The following table summarizes SpatialWare’s geometry functions (Constructor functions) and where they can be used.

The reason some of the functions are available within sp_spatial_query, but not as a UDF is due to a SQL Server limitation. It is not possible in SQL Server 2000 to return a geometry that is greater than 8000 bytes in size

Note Information about working with UDFs is provided in Chapter 21: User Defined Functions.

Constructor Function

Part of ST_Spatial String Syntax

Available in sp_spatial_query

Available as UDF(syntax specific)

HG_Box yes yes yesHG_Box(x1,y1,x2,y2)

HG_Circle yes yes yesHG_Circle(x,y,radius)

HG_Curve yes no no

HG_Quad yes no no

HG_Triangle yes no no

ST_CircularArc yes no no

ST_Path yes no no

ST_Point yes yes yesST_Point(x,y)

ST_Polygon yes no no

ST_Polyline yes no no

ST_Spatial N/A yes no


Chapter 8:

An Overview of the Spatial Data Type HierarchyIn addition to being the name of a constructor function, “ST_Spatial” is also the parent of all SpatialWare data types. It is the name of the class of spatial objects, and an instantiated data type.

In the type structure, ST_Spatial is the parent type of ST_GeometricPrimitive from which all types are derived. ST_Spatial is also an instantiated type in SpatialWare, defined by zero to n ST_GeometricPrimatives.

Types of ST_GeometricPrimitives

ST_GeometricPrimitive is used to define the types ST_Point, ST_Line, and ST_Area. ST_GeometricPrimitive is not instantiated.

• ST_Point Type An ST_Point can be a two, or three dimensional point. A two dimensional point is defined by its x and y coordinates; a three dimensional point by its x, y, and z coordinates.

• ST_Line TypeST_Line is used to define a broad range of line types. The two main sub-types are ST_Curve and ST_Path. ST_Curve is not instantiated but defines the line types: ST_Polyline, ST_CircularArc, HG_Circle, or HG_Curve. An ST_Path is made up of a list of ST_Curves.

• ST_Area TypeThe ST_Area type is not instantiated, but is used to create the sub-type ST_Polygon. Basic polygons are defined by a boundary and zero to n interior boundaries. There are three sub-types of ST_Polygon: HG_Box, HG_Triangle, and HG_Quad.

User Guide 81

Creating Geometry Using the ST_Spatial Function

SpatialWare Type Hierarchy

The geometry string representations correspond to the following ST_Spatial type hierarchy.

Note In SpatialWare for SQL Server ST_Spatial is the data type of a column.

Some of these spatial data types are non-instantiable (abstract). This means that it is not possible to create an object of these types. Other types are instantiable and objects may be created of them.

Creating Geometry Using the ST_Spatial FunctionYou can create geometry via ST_Spatial. The ST_Spatial Constructor function creates geometry (SW_GEOMETRY) using geometry string formats. It is also a data type used to define the geometry column of a table.


Chapter 8:

SpatialWare functions work with predefined geometry string formats. The ST_Spatial function creates these formats (refer to Geometry String Formats Used with SpatialWare on page 84). ST_Spatial is very versatile because more than one string format can be used to create a multi-element geometry.

The ST_Spatial constructor takes the following form inside sp_spatial_query.

ST_Spatial('geometry_string')

For example:

sp_spatial_query 'select sw_geometry from geomtest where st_overlaps(sw_geometry,

ST_Spatial(''HG_Box(ST_Point(11.22, 33.44), ST_Point(55.66, 77.88))'')

)'

Note When defining a table for use with SpatialWare, a spatial column is created for the table. A spatial column is where spatial geometry is stored. Its defined as type ST_Spatial. By default, this column is called SW_GEOMETRY, but it can be any legal name. For information on how to create a spatial table (containing an ST_Spatial type column), refer to Chapter 4: Defining Spatial Tables.

ST_SpatialThe ST_Spatial function takes a textual description of the geometry and constructs a SW_GEOMETRY from it. The textual descriptions are in SpatialWare-SQL/MM format.

ST_Spatial generates geometry consisting of one or more elements in the form of character strings that represent geometry, such as HG_Box and HG_CircularArc.

Syntax

ST_Spatial(string)

where:

• string – A character string representing a geometry (refer to Geometry String Formats Used with SpatialWare on page 84).

Return Type

ST_Spatial returns SW_GEOMETRY.

Example

The following example calls HG_Center_In, which centers a geometry on another geometry. The ST_Spatial constructor is used to create a point geometry for input to the HG_Center_In function.

exec sp_spatial_query 'select HG_GetString(HG_Center_In(

flood100.sw_geometry, ST_Spatial(''ST_Point(1753960.182000, 10698421.103000)'')

User Guide 83

Geometry String Formats Used with SpatialWare

)) from flood100

'

Caveat

HG_GetString has been added to the example so that it will return geometry in text format.

The ST_Spatial string is set in double quotes when in an sp_spatial_query.

All ST_Spatial geometries (objects) have internal attributes, which communicate information about the ST_Spatial. Attributes may include whether the object is assembled, its orientation, its centroid, and its type (string format). Refer to Chapter 9: ST_Spatial Attributes for details.

Geometry String Formats Used with SpatialWareThe ST_Spatial Constructor Function creates geometry in the expected binary format. The following lists the predefined string formats used by the ST_Spatial constructor function to create geometry:

• HG_Box – Two Points• HG_Box – x, y Values• HG_Circle – Two Points• HG_Circle – Center Point and Radius• HG_Circle – x, y, and Radius Values• HG_Curve• HG_Triangle• HG_Quad• ST_CircularArc• ST_Path• ST_Point• ST_Polygon - Polygon with Exterior Boundary• ST_Polygon – Polygon with Exterior Boundary and a Centroid• ST_Polygon – Polygon with Exterior Boundary and One or More Interior Boundaries• ST_Polygon – Polygon with Exterior Boundary, One or More Interior Boundaries, and a

Centroid• ST_Polyline

For information on geometry collections, refer to Chapter 10: Understanding Geometry Collections.

The examples provided with the geometry string format descriptions refer to a table called geomtest. For information about how to create this spatial table, refer to Chapter 4: Defining Spatial Tables.

Creating 3D Geometry

Geometry is three-dimensional if it uses three-dimensional point construction, where points are defined with x, y, and z values.

The following example constructs a three-dimensional polyline.


Chapter 8:

ST_Spatial('ST_Polyline(LIST{ST_Point(1,3,5), ST_Point(10,6,9)

})')

SpatialWare functions generate geometry in two dimensions, but wherever possible three ordinates are retained. Refer to Data Dimension on page 119 for a list of SpatialWare functions that work with three-dimensional geometry.

HG_Box – Two PointsHG_Box generates a box given points for the lower left and upper right corners.

Syntax

The string format of an HG_Box is:

'HG_Box(point1, point2)'

where:

• point1 – An ST_Point. The lower left corner of the box.• point2 – An ST_Point. The upper right corner of the box.

Example

insert into geomtest(sw_member, sw_geometry) values(4, 'HG_Box(ST_Point(11.22, 33.44), ST_Point(55.66, 77.88))'

)

User Guide 85

HG_Box – x, y Values

HG_Box – x, y ValuesHG_Box creates a box generates a box given x and y values for the lower left and upper right corners.

Syntax

The string format of an HG_Box is:

'HG_Box(x1, y1, x2, y2)'

where:

• x1, y1 – Double precision values. The lower left corner of the box.• x2, y2 – Double precision values. The upper right corner of the box.

Examples

Constructor string:

insert into geomtest(sw_member, sw_geometry) values(5, 'HG_Box(11.22, 33.44, 55.66, 77.88)'

)

UDF:

select sw_member from geomtest where dbo.ST_Overlaps(

sw_geometry, dbo.HG_Box(11.22, 33.44, 55.66, 77.88))=1

HG_Circle – Two PointsHG_Circle generates a linear geometry – a circular path.


Chapter 8:

A two point HG_Circle is defined by a center point and a point that lies on the circle, in that order.

Note To generate a circular area, instead of a circular path, buffer around a point or create a polygon from a circle. Creating a polygon from a circle is the preferred method.

ST_Spatial('ST_Polygon(HG_Circle(x,y,r))')ST_Buffer(ST_Spatial('ST_Point(x,y)'), r)

String Format

The string format of an HG_Circle is:

'HG_Circle(point1, point2)'

where:

• point1 – The string format of an ST_Point.• point2 – The string format of an ST_Point.

Example

insert into geomtest(sw_member, sw_geometry) values(6, 'HG_Circle(ST_Point(11.11,22.22),ST_Point(55.55,44.44))'

)

HG_Circle – Center Point and RadiusHG_Circle generates a linear geometry – a circular path.

You can define an HG_Circle by specifying a center point and a radius value.

String Format


'HG_Circle(point, radius)'

User Guide 87

HG_Circle – x, y, and Radius Values

where:

• point1 – The string format of an ST_Point.• radius – A double precision value.

Constructor

The HG_Circle syntax of the ST_Spatial constructor is:

ST_Spatial('HG_Circle(point, radius)')

Example

Constructor string:

insert into geomtest(sw_member, sw_geometry) values(7, 'HG_Circle(ST_Point(2,2), 1)'

)

UDF:


sw_geometry, dbo.HG_Circle(ST_Point(2,2), 1))=1

HG_Circle – x, y, and Radius ValuesHG_Circle generates a linear geometry – a circular path. You can define an HG_Circle by specifying the x and y ordinates of the circle center point, and a radius value.

String Format


'HG_Circle(x, y, radius)'

where:

• x, y – Double precision values.• radius – A double precision value.

Example

insert into geomtest(sw_member, sw_geometry) values(8, 'HG_Circle(11.11, 22.22, 10)'


Chapter 8:

)

HG_CurveHG_Curve is the string format of a curve. It is a smoothly curving line defined by a list of points: a start point and an end point, with zero or more control points in between. Optional start-tangent and end-tangent parameters give more control over the shape of the line.

HG_Curve can be defined in four ways:

• A list of ST_Points. • A start-tangent and a list of ST_Points. • A list of ST_Points and an end-tangent. • A start-tangent, a list of ST_Points, and an end-tangent.

For brevity, only the fourth case will be detailed below. Just note that the start-tangent and end-tangent parameters are optional. Default values will be assigned if they are left out.

Note By setting the start and end tangents, you have more control over the shape of the curve as shown. Tangents are entered as double precision numbers representing a degree.

String Format

The string format of an HG_Curve is:

'HG_Curve(start_tan, LIST{point, point, point,...}, end_tan)'

where:

• start_tan – A double precision number representing degrees. (This parameter is optional.)• LIST – An internal list mechanism.• point – The string format of an ST_Point.• end_tan – A double precision number representing degrees. (This parameter is optional.)

User Guide 89

HG_Triangle

Example

insert into geomtest(sw_member, sw_geometry) values(9, 'HG_Curve(55.0, LIST{

ST_Point(11.11,22.22),ST_Point(33.33,44.44), ST_Point(55.55,66.66)

}, 40.0)')

HG_TriangleHG_Triangle is a triangular polygon, which is defined by three points.

String Format

The string format of an HG_Triangle is:

'HG_Triangle(LIST{point1, point2, point3})'

where:

• point – The string format of ST_Point.

Example

insert into geomtest(sw_member, sw_geometry) values(10, 'HG_Triangle(LIST{

ST_Point(11.22, 33.44), ST_Point(55.66, 77.88), ST_Point(99.1010, 1111.1212)

})')

HG_QuadHG_Quad is a four-sided polygon of any shape, size, or rotation, which is defined by four points. HG_Quad is a subset of ST_Polygon. See HG_Box for an alternative method of creating an axis-oriented quadrilateral.


Chapter 8:

String Format

The string format of an HG_Quad is:

'HG_Quad(LIST{point1, point2, point3, point4})'

where:


Constructor

The HG_Quad syntax of the ST_Spatial constructor is:

ST_Spatial('HG_Quad(LIST{point, point, point, point})')

Example

insert into geomtest(sw_member, sw_geometry) values(11, 'HG_Quad(LIST{

ST_Point(11.22, 33.44), ST_Point(55.66, 77.88), ST_Point(99.1010, 1111.1212), ST_Point(1313.1414, 1515.1616)

})')

ST_CircularArcST_CircularArc is the string format of a curved line defined by three points. The first and last points define the beginning and end, and the middle point determines the shape of the arc.

String Format

The string format of an ST_CircularArc is:

User Guide 91

ST_Path

'ST_CircularArc(LIST{point1, point2, point3})'

where:


Example

insert into geomtest(sw_member, sw_geometry) values(12, 'ST_CircularArc(LIST{

ST_Point(11.11,22.22), ST_Point(-36.33,44.44), ST_Point(55.55,36.66)

})')

ST_PathST_Path is the string format defining a compound line made up of one or more curves. In this case, a curve refers to a family of geometries: ST_Polyline, ST_CircularArc, HG_Circle, or HG_Curve.

String Format

The string format of an ST_Path is:

'ST_Path(LIST{object, object,...})'

where:

• LIST – An internal list mechanism.• object – The string format of any curve (ST_Polyline, ST_CircularArc, HG_Circle, or HG_Curve).

Example

insert into geomtest(sw_member, sw_geometry) values(13, 'ST_Path(LIST{

ST_Polyline(LIST{ST_Point(11.11,22.22),ST_Point(33.33,44.44)}),ST_CircularArc(LIST{

ST_Point(11.11,22.22),ST_Point(33.33,44.44),ST_Point(55.55,66.66)


Chapter 8:

})})'

)

ST_PointST_Point is the string format of a point defined by its x, y, and optional z coordinates. The optional z coordinate is used for points located in three-dimensional space. The coordinates are double precision values.

String Format

The string format of ST_Point in two dimensions is:'ST_Point(x, y)'

The string format of ST_Point in three dimensions is:'ST_Point(x, y, z)'

where:

• x – A double precision number representing the point's x coordinate.• y – A double precision number representing the point's y coordinate.• z – A double precision number representing the point's z coordinate.

Examples

Constructor string:

insert into geomtest(sw_member, sw_geometry) values(14, 'ST_Point(11.11,22.22)'

)

UDF:


sw_geometry, dbo.ST_Point(11.11,22.22))=1

Caveat

The following example uses a three-dimensional point.

insert into geomtest(sw_member, sw_geometry) values(15,

User Guide 93

ST_Polygon - Polygon with Exterior Boundary

'ST_Point(11.11,22.22,44.44)')

ST_Polygon - Polygon with Exterior BoundaryA polygon is the string format of a closed plane figure consisting of three or more straight sides that connect three or more points. None of the sides are intersecting.

This syntax defines a polygon with a path that creates an exterior boundary. The start and end points are the same.

String Format

The string format of an ST_Polygon with an exterior boundary is:

'ST_Polygon(path)'

where:

• path – The string format of ST_Path.

Example

insert into geomtest(sw_member, sw_geometry) values(16, 'ST_Polygon(

ST_Path(LIST{ST_Point(1.2,1.0),ST_Point(6.4,1.6),ST_Point(6.4,2.9),ST_Point(5.0,4.2),ST_Point(2.1,4.0),ST_Point(1.2,1.0)

})))'

)

ST_Polygon – Polygon with Exterior Boundary and a CentroidA polygon is the string format of a closed plane figure consisting of three or more straight sides that connect three or more points. None of the sides are intersecting.


Chapter 8:

This syntax defines a polygon with a path, and the centroid of the polygon.

String Format

The string format of an ST_Polygon with an exterior boundary and a centroid is:

'ST_Polygon(path, point)'

where:

• path – The string format of ST_Path.• point – The string format of ST_Point.

Example

The following statement uses an ST_Polygon with a centroid:



}),ST_Point(3.7,2.6)

)')

ST_Polygon – Polygon with Exterior Boundary and One or More Interior Boundaries

A polygon is the string format of a closed plane figure consisting of three or more straight sides that connect three or more points. None of the sides are intersecting.

User Guide 95

ST_Polygon – Polygon with Exterior Boundary, One or More Interior Boundaries, and a Centroid

This syntax defines a polygon with a path (exterior boundary) and a list of geometries (interior boundaries). The resulting geometry is what is shaded in the below example.

String Format

The string format of an ST_Polygon with an exterior boundary and one or more interior boundaries is:

'ST_Polygon(path,LIST{obj1,obj2,...})'

where:

• path – The string format of ST_Path.• obj1, obj2,... – Geometries defining interior boundaries.

Example

The following statement uses an ST_Polygon with an exterior boundary and two interior boundaries:



}),LIST{

HG_Circle(ST_Point(3.0,1.9),ST_Point(3.2,1.9)),HG_Circle(ST_Point(4.6,3.7),ST_Point(5.0,3.7))

}))'

)

ST_Polygon – Polygon with Exterior Boundary, One or More Interior Boundaries, and a Centroid

A polygon is the string format of a closed plane figure consisting of three or more straight sides that connect three or more points. None of the sides are intersecting.


Chapter 8:

This syntax defines an ST_Polygon that includes all possible elements: a path (exterior boundary), a LIST of interior boundaries, and a centroid.

String Format

The string format of an ST_Polygon with an exterior boundary, one or more interior boundaries, and a centroid is:

'ST_Polygon(path, LIST{obj1,obj2,...},point)'

where:

• path – The string format of ST_Path.• obj1, obj2,... – Geometries defining interior boundaries.• point – The string format of ST_Point.

Example

The following statement uses an ST_Polygon with an exterior boundary, two interior boundaries, and a centroid:



}),LIST{

HG_Circle(ST_Point(3.0,1.9),ST_Point(3.2,1.9)),HG_Circle(ST_Point(4.6,3.7),ST_Point(5.0,3.7))

}ST_Point(3.7,2.6)

)')

User Guide 97

ST_Polyline

ST_PolylineST_Polyline is the string format of defining one or more two-point line segments positioned end to end. The line can be of any shape.

String Format

The string format of an ST_Polyline is:

'ST_Polyline(LIST{point1, point2,...})'

where:

• point1,point2,... – String formats of ST_Point.

Example

insert into geomtest(sw_member, sw_geometry) values(20, 'ST_Polyline(LIST{

ST_Point(11.11,22.22), ST_Point(33.33,44.44)

})')


9
ST_Spatial Attributes
This section describes the internal attributes that communicate information about an ST_Spatial object. The ST_Line and ST_Point object types have some special attributes in addition to global attributes.

In this section:

Understanding ST_Spatial Attributes. . . . . . . . . . . . . . . . . . . . . .100Special Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Understanding ST_Spatial Attributes

Understanding ST_Spatial AttributesAll ST_Spatial objects share the following, global attributes:

• envelope – The smallest box containing the ST_Spatial.• assembled – Indicates if objects in the ST_Spatial are assembled.• orientation – An orientation point, which is reserved for internal use only.• centroid – A point on the object closest to the center of gravity.• number – The number of geometry elements in the object.• type – The type of object in the ST_Spatial.

In addition to these attributes, line and point types have type-specific attributes, which are described in Special Attributes on page 101.

EnvelopeAll ST_Spatials have an envelope attribute, which indicates the smallest, axis oriented, box that can contain the ST_Spatial.

AssembledAssembled is a Boolean attribute of all ST_Spatials. This attribute is provided for some external applications. The Assembled attribute is set to true by an application when an ST_Spatial is assembled.

For example, when an application creates an ST_Spatial it can set the assembled flag to TRUE. When the application manipulates the object at a later time, it can set assembled to FALSE to indicate that the shape has been modified and that a cleanup is necessary. The default value of assembled is NULL.

OrientationAll ST_Spatials allow for an orientation point, which is reserved for internal use. SpatialWare does not currently provide any method for users to set the orientation point. Please see instead Point Dynamic Orientation and Scale.


Chapter 9:

The placement of the orientation point can communicate angle and rotation.

CentroidThe centroid of an ST_Spatial is a point on the object chosen to be close to the center of gravity. It may optionally be a point on the object specified at the time of input.

The x, y, and z coordinates are accessible. A centroid is defined as an ST_Point.

NumberThe number attribute specifies how many geometry elements are in an ST_Spatial.

TypeAll ST_Spatial objects have a type attribute, which indicates the type of object in the ST_Spatial.

Special AttributesIn addition to global attributes, line and point types have the following type-specific attributes:

• line direction – The direction of the line.• point dynamic orientation – Specifies position for mapping purposes.• point dynamic scale – Specifies size for mapping purposes.

Line DirectionIn addition to the global attributes, ST_Polyline contains a direction attribute that specifies the directional property of the line. Line directions are FORWARD, REVERSE, or NULL.

The direction of a line determines which points are considered the beginning and end points. Line direction is relevant for many functions in SpatialWare, such as HG_Slope.

A line has 0 to n points.

User Guide 101

Special Attributes

When a line's direction is FORWARD or NULL, the beginning point is P0 and the end point is Pn. When a line is REVERSE, the beginning point is Pn and the end point is P0.

Point Dynamic Orientation and ScaleST_Points can store information about scale and orientation, commonly used for map attribute positioning and sizing. These attributes compose the point dynamic.

One element of the point dynamic is orientation. It is similar to the global ST_Spatial orientation, but it is an additional place to store orientation information. So, an ST_Point can have two levels of orientation: its orientation as an ST_Spatial and its orientation as an ST_Point.

The second element of the point dynamic is scale. Scale allows applications that do mapping or plotting to specify the size of an attribute associated with an ST_Point. Scaling can be done for both x and y axes.

The scale is based on one unit of plot.

Functions that access point dynamic information include:


Chapter 9:

• HG_Pointdyn_Xscale • HG_Pointdyn_Yscale • HG_Pointdyn_Ori_X • HG_Pointdyn_Ori_Y • HG_Pointdyn_Rot

User Guide 103

Special Attributes


10
Understanding Geometry Collections
An ST_Spatial contains a collection of 0 to n ST_GeometricPrimitives.

Some SpatialWare functions, such as ST_Overlap, take complex ST_Spatials (collections) as parameters. When functions deal with collections, the basic point-line-polygon relationships remain intact, but become more difficult to visualize. This section outlines a simple method to help you determine (map) the behavior of functions in special cases.

In this section:

Creating Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106Mapping Special Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

Creating Collections

Creating CollectionsThe following examples describe the process of constructing various types of two-dimensional geometry using the ST_Spatial constructor. You can also create three-dimensional geometry using ST_Spatial by adding a z ordinate to points.

The following are examples of single element geometries. For a full description of supported geometry string formats, refer to ST_Spatial Geometry String Formats.

• A three point polyline: insert into geomtest(sw_member, sw_geometry) values(21,

'ST_Spatial(ST_Polyline(LIST{ST_Point(1,1), ST_Point(2,0), ST_Point(3,3)}

))')

• A circular polygon: insert into geomtest(sw_member, sw_geometry) values(22,

'ST_Spatial(ST_Polygon(ST_Path(LIST{HG_Circle(ST_Point(1,1), 10.0)})

))')

• A circular arc: insert into geomtest(sw_member, sw_geometry) values(23,

'ST_Spatial(ST_CircularArc(LIST{ST_Point(1,1), ST_Point(2,2), ST_Point(3,1)}

))')

Geometry string formats can be combined into more complex geometries.

• Two overlapping objects: insert into geomtest(sw_member, sw_geometry) values(24,

'ST_Spatial(LIST{ HG_Box(0,0,4,4), HG_Box(6,3,9,5)})'

)• A geometry with a point and a polygon:

insert into geomtest(sw_member, sw_geometry) values (25,'ST_Spatial(LIST{

ST_Point(1,1), ST_Polygon(ST_Polyline(LIST{

ST_Point(1,1),ST_Point(1,2), ST_Point(2,2), ST_Point(1,1)

})) })'

)

• A geometry composed of a circular arc and polyline: insert into geomtest(sw_member, sw_geometry) values (26,

'ST_Spatial( ST_Path(LIST{


Chapter 10:

ST_Polyline(LIST{ST_Point(1,1), ST_Point(2,2)

}), ST_CircularArc(LIST{

ST_Point(2,2), ST_Point(3,2), ST_Point(3,3)

}) })

)')

Mapping Special CasesFunctions that take two objects as an argument have a set of valid geometry relationships. For example, with ST_Contain, a line can contain a point, but not the reverse. Diagrams of the valid shape relationships are included in the function descriptions. The diagrams only show the basic relationships between simple shapes. There are an infinite number of geometry combinations possible.

If you want to determine how a function will handle a special case, it is necessary to map out the simple relationships between each of the shapes and then combine the results. The union of all of the simple relationships is the return of the function.

Example

In the following example, two complex SpatialObjects are sent as parameters to ST_Overlap.

We want to determine what the return will be when the two objects are sent to ST_Overlap as parameters. When overlapped, they look like:

User Guide 107

Mapping Special Cases

SpatialObject A has three geometries, and SpatialObject B has two. This means that there are six simple relationships to map out: A1-B1, A1-B2, A2-B1, etc.... To find out what ST_Overlap will return if given SpatialObjects A and B, you must first determine the results from the six combinations, and then unite the results as a single object.

According to the definition of ST_Overlap, each combination produces a Geometry or NULL. By combining all of the results, you determine what the return object will be.


11
Performing Coordinate System Transformations
This section describes how to perform coordinate system transformations.

Refer to Appendix 28: Transformation Calculation for reference tables for Projections, Spheroids/Ellipsoids, Coordinate Units, and Datums.

In this section:

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110Performing Coordinate Transformations. . . . . . . . . . . . . . . . . . .110

Overview

OverviewThe coordinate system of a table is defined by the entry in the MAPINFO_MAPCATALOG. Data loaded using Easy Loader will create this entry automatically, otherwise use the Make Table Mappable function in MapInfo Professional to register MapInfo tables in the catalog table.

Spatial queries take spatial data as arguments in matching coordinate systems. For example to do an overlap or buffer, the data in both tables must be in the same coordinate system.

Results from queries are returned in the same coordinate system as the data used. If you need a result to be returned in another coordinate system, then use the HG_CSTransform function to transform the spatial data to another coordinate system.

Data extracted into MapInfo Professional is always connected into the coordinate system of the mapper window into which it is selected. The coordinate system of an MapInfo Professional mapper window is the coordinate system of the first table extracted into it.

For a description and background information on coordinate systems and projections, refer to Chapter 27: Understanding Coordinate Systems and Projections.

Note Another useful function is HG_CSTransform, which is a coordinate transformation function.

Performing Coordinate TransformationsSpatialWare for SQL Server provides an SQL function for coordinate transformation. Geometries can be transformed from one coordinate system to another using HG_CSTransform.

The HG_CSTransform function performs an explicit transformation. Applications must provide the geometry, the description of the coordinate system the geometry is in, and the description of the coordinate system to transform to. The description of the coordinate system is in the form of an OGC well-known text representation. Coordinate system descriptions are stored in a table called master..HG_SpatialRef.

For more information about the transformation function, refer to HG_CSTransform.

Note Geometries are not tagged with the coordinate system that they are in.

The HG_SpatialRef TableSpatialWare comes with a table of supported coordinate systems, master..HG_SpatialRef. This table contains the OGC well-known text strings. (These are the same as the coordinate systems defined in MapInfo Professional's MAPINFOW.PRJ.) The values in this table may be used in a join to perform coordinate system transformations.

Note MapInfo Professional users may notice that this table doesn't contain non-earth projections. This is because they are not defined in the OpenGIS Consortium's model. You can, however, implement transformation between non-earth systems using HG_Transform or HG_Affine.

The following generates a complete list of supported coordinate systems stored in the HG_SpatialRef table:

select cs_name from master..HG_SpatialRef order by cs_name


Chapter 11:

A coordinate system is identified by a string of not more than 67 characters. This identifier is unique across the database instance, and is shared by all schemas in the instance. The following are examples of valid identifiers:

• 'British National Grid' • 'Longitude / Latitude (NAD 83)' • 'UTM Zone 28 (ED 50)' • 'Vermont (1983)'

Note Since identifiers are strings, please take note of white spaces when using them.

You can find a coordinate system identifier by querying the HG_SpatialRef table. The following example shows how to find the definition of the Robinson coordinate system:

select srtext from master..HG_SpatialRef where cs_name = 'Robinson'

OGC Well-Known TextCoordinates are defined according to the standards outlined by the OpenGIS Consortium (OGC). Refer to Background Information on Industry Standards on page 21 for more information about standards.

Coordinate system definitions are stored in the HG_SpatialRef table in the Master database.

The SpatialWare supports projected coordinates (PROJCS) and geographic coordinates (GEOGCS). Geocentric coordinates (GEOCCS) are not supported.

Projected Coordinates

The following is the Extended Backus Naur Form (EBNF) definition of the string representation of a projected coordinate system:

<coordinate system> = <projected cs> | <geographic cs> | <geocentric cs><projected cs> = PROJCS['<name>', <geographic cs>, <projection>, {<parameter>,}* <linear unit>]<projection> = PROJECTION['<name>']<parameter> = PARAMETER['<name>', <value>]<value> = <number>

The projected coordinate system is defined with a name (‘<name>‘) followed by the geographic coordinate system, the map projection, zero (0) or more parameters, and the linear unit of measure.

An example of a projected coordinate system is British National Grid. Its string representation is:

PROJCS['British National Grid', GEOGCS['Ordnance Survey GreatBrit', DATUM['Ordnance Survey Great Brit', SPHEROID['Airy 1930',6377563.396000,299.324965]], PRIMEM['Greenwich',0], UNIT['Decimal Degree',0.017453292520]], PROJECTION['Transverse Mercator'], PARAMETER['Scale_Factor',0.999601], PARAMETER['Central_Meridian',-2.0], PARAMETER['Latitude_Of_Origin',49.0], PARAMETER['False_Easting',400000.0],

User Guide 111

Performing Coordinate Transformations

PARAMETER['False_Northing',-100000.0], UNIT['Meter',1.0]]

UNIT represents either an angular or linear unit of measure.

<angular unit> = <unit><linear unit> = <unit><unit> = UNIT['<name>', <conversion factor>]<conversion factor> = <number>

Where <conversion factor> must be larger than zero. It specifies per unit the number of meters for a linear unit or the number of radians for an angular unit.

Projected coordinate systems are based upon a geographic coordinate system.

Geographic Coordinates

The following is the EBNF definition of the syntax of a geographic coordinate system:

<geographic cs> = GEOGCS['<name>', <datum>, <prime meridian>, <angular unit>]<datum> = DATUM['<name>', <spheroid> {, <shift-x>, <shift-y>, <shift-z> {, <rot-x>, <rot-y>, <rot-z>, <scale_adjust> } }]<spheroid> = SPHEROID['<name>', <semi-major axis>, <inverse flattening>]<semi-major axis> = <number> <inverse flattening> = <number><prime meridian> = PRIMEM['<name>', <longitude>]<longitude> = <number>

Note Semi-major axis is measured in meters and must be > 0.

The geographic coordinate system is defined with a name (‘<name>‘) followed by the datum, the prime meridian, and the angular unit of measure. In the SpatialWare, datum has been enhanced from the OGC well-known text standard to support user defined projections. Datum includes the following information:

• shift-x, shift-y, shift-z are in meters. • rot-x, rot-y, rot-z are in seconds. • scale_adjust is in parts per million.

The sign is specified by subtracting the datum's values from WGS84.

An example of a geographic coordinate system is Longitude/Latitude (NAD 83). Its string representation is:

GEOGCS['Longitude / Latitude (NAD 83)', DATUM['GRS 80', SPHEROID['GRS 80',6378137.000000,298.257222]],PRIMEM['Greenwich',0], UNIT['Decimal Degree',0.017453292520]]


Chapter 11:

ExamplesDistances returned from spatial functions are always in the units corresponding to the projection. If you want to obtain a measurement result, such as length or area, it is possible to transform the data to another projection using HG_CSTransform(), then use the measurement function (which returns the distance in the current projection system) to return the measurement value in the units appropriate to the new projection.

Example 1 – HG_CSTransform()

The following query takes data in longitude/latitude, re-projects it into the Mercator projection, then asks for the distance between two of the points. This distance is in meters, with a base unit of Mercator.

exec sp_spatial_query 'select hg_distance (HG_CSTransform(a.sw_geometry, c.srtext,

d.srtext),HG_CSTransform(b.sw_geometry, c.srtext, d.srtext) )from Landmark1000 a,Landmark1000 b,master..HG_SpatialRef c,

master..HG_SpatialRef dwhere a.sw_member = 1 and b.sw_member = 100 and c.cs_name = ''Longitude / Latitude''and d.cs_name = ''Mercator''

'

Example 2 – HG_SphericalDist()

This example is different from Example 1 as it uses the spherical distance for the calculation. A spherical distance calculates the distance around the sphere directly, whereas the technique used in Example 1 transforms the data and then calculates the distance in the new projection.

exec sp_spatial_query 'select HG_SphericalDist(a.sw_geometry, b.sw_geometry)from Landmark1000 a,Landmark1000 b where a.sw_member = 372 and b.sw_member = 995

'

User Guide 113

Performing Coordinate Transformations


Part 3: Function Descriptions

Topics:

About Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Cast Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Aggregate Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Coordinate Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133General Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Measurement Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Observer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Spatial Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Spatial Predicate Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221User Defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

12
About Functions
Spatial functions allow you to analyze and manipulate spatial data. They are grouped into nine categories.

All functions have either an HG_ prefix or a ST_ prefix. The ST_ prefix indicates that the function or geometry representation is defined according to the international standard ISO/IEC SQL/MM. The HG_ prefix indicates that the function or geometry representation is an enhancement to the standard.

In this section:

What are Spatial Functions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118Filter Tolerance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118Data Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119Data Dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119Spherical and Ordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . .120

What are Spatial Functions?

What are Spatial Functions?SpatialWare supplies functions that work with spatial data. SpatialWare functions let you create geometric objects and work with spatial data in various ways. SpatialWare functions are divided into the following logical groupings:

• Aggregate Functions – Work across rows in a group and return one row per group. • Cast Functions – Transform data from one format to another.• Constructor Functions – Create a geometry using the ST_Spatial function (described under

Geometry Creation).• Coordinate Functions – Applied to work with coordinate system information.• General Functions – Perform operations, make queries, or change settings.• Measurement Functions – Perform calculations on geometries to find a measurable

characteristic, such as length, slope, area, or height.• Observer Functions – Return numbers, objects, or conditions from within a geometry.• Spatial Functions – Perform operations on geometries to create new geometries.• Spatial Predicates – Analyze geometries to see if they meet specific conditions. These functions

usually return TRUE or FALSE (1 or 0) values and are generally used within a WHERE clause (e.g. find overlapping geometries).

About Standards

SpatialWare follows industry standards. For details about these standards, refer to Background Information on Industry Standards on page 21. The following Cast functions follow the OGC standards:

• HG_AsBinary • HG_AsText• HG_GeometryFromBinary• HG_GeometryFromText

About the Examples

Some examples use the geomtest table. Please refer to Chapter 4: Defining Spatial Tables for instructions on how to create this spatial table if you have not already done so. Examples that populate this table are located in ST_Spatial Geometry String Formats Used with SpatialWare on page 84.

Filter ToleranceFiltering is done by setting the third parameter to the ST_Buffer function (if you do not want to use filtering you would set it to null) or by calling the HG_Filter function:

ST_Buffer(sw_geometry, double precision, double precision)HG_Filter(sw_geometry, double precision)

Filtering reduces the number of points that represent a spatial object. If an object is used as input to other functions, like ST_Overlap, reducing its level of detail improves processing time.


Chapter 12:

Data ToleranceSpatialWare functions use a data tolerance of 1.0 e-10 database units. This tolerance is absolute. Points falling within the tolerance value of one another are considered to occupy the same location, as in the diagram below:

Tolerance applies to all aspects of spatial analysis.

Data DimensionSpatialWare functions generate geometry in two dimensions, but wherever possible three ordinates are retained: geometries in two dimensions have x, y coordinate values; geometries in three dimensions have x, y, z coordinate values.

The following functions handle, measure, or verify attributes of three-dimensional geometry.

Note Geometry can be constructed using the ST_Spatial constructor function in two or three dimensions. Refer to Creating 3D Geometry on page 84.

Spatial Functions: HG_Affine3DHG_Center_In_3DST_Transform3D

Measurement Functions: HG_HeightHG_SeparationHG_SlopeHG_Slope_2ptsHG_Slope_AvgHG_Slope_MaxHG_Slope_MinHG_WidthST_Length_3DST_Perimeter_3D

Spatial Predicates: HG_AboveHG_BelowHG_Level

User Guide 119

Spherical and Ordinate Systems

Spherical and Ordinate SystemsThe following spherical measurement functions are useful to ascertain some properties such as area and distance of geometries in longitude/latitude coordinate systems.

• HG_SphericalArea• HG_SphericalBuffer• HG_SphericalCircle• HG_SphericalDistance• HG_SphericalLength• HG_SphericalPerimeter

These functions assume a spherical model of the Earth. They are not suitable for high precision applications. For such applications, it is recommended that the geometries be transformed to a suitable projected coordinate system first and then a Cartesian operation performed on the geometry.

Note These functions are designed to work only with geometries in longitude/latitude coordinate systems.

Supported UnitsSpherical functions let you specify the units to base the calculations on. Both linear and area units are supported.

Linear Units

The following table lists the linear units that can be used with the spherical measurement functions:

Argument to SQL Function Unit name

m meters

km kilometers

cm centimeters

mm millimeters

mi miles

nmi nautical miles

ft feet (also called International Feet)

in inches

yd yards

ch chains


Chapter 12:

Area Units

The following table lists the area units that can be supplied as input to spherical measurement functions:

rd rods

li links

survey ft U.S. survey feet

Argument to SQL Function Unit Name

sq m square meters

sq km square kilometers

sq cm square centimeters

sq mm square millimeters

sq mi square miles

sq nmi square nautical miles

sq ft square feet (also called International Feet)

sq in square inches

sq yd square yards

sq ch square chains

sq rd square rods

sq li square links

sq survey ft square U.S. survey feet

acre acres

hectare hectare

Argument to SQL Function Unit name

User Guide 121

Spherical and Ordinate Systems


13
Cast Functions
Cast functions transform data from one format to another.

Cast functions follow the OGC standards. For details standards refer to Background Information on Industry Standards on page 21.

In this section:

HG_AsBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124HG_AsText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124HG_GeometryFromBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125HG_GeometryFromText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

HG_AsBinary

HG_AsBinaryThe HG_AsBinary function generates an OGC well-known binary from a SpatialWare geometry.

Syntax

HG_AsBinary(spatial_obj)

• spatial_obj – An ST_Spatial.

Return Type

HG_AsBinary returns an OGC well-known binary of type image.

Example

The following example generates a temporary table called tmpbinary. This table contains the OGC well-known binary generated by HG_AsBinary from SpatialWare geometry.

exec sp_spatial_query 'select HG_AsBinary(sw_geometry) as ogcbinary into tmpbinaryfrom parcel

'

HG_AsTextThe HG_AsText function generates OGC well-known text from a SpatialWare geometry.

Syntax

HG_AsText(spatial_obj)


Return

HG_AsText returns an OGC well-known text of type text.

Example

The following example generates a temporary table called tmptxt. This table contains the OGC well-known text generated by HG_AsText from SpatialWare geometry.

exec sp_spatial_query 'select HG_AsText(sw_geometry) as ogctxt into tmptxtfrom parcel

'


Chapter 13:

HG_GeometryFromBinaryThe HG_GeometryFromBinary function interprets an OGC well-known binary and creates a SpatialWare geometry from it.

Syntax

HG_GeometryFromBinary(ogcbinary)

• ogcbinary – An OGC well-known binary of type image.

Return Type

HG_GeometryFromBinary returns an ST_Spatial.

Example

The following example queries a temporary table called tmpbinary. This table contains OGC well-known binaries generated by HG_AsBinary from SpatialWare geometry. Please refer to the description for HG_AsBinary.

exec sp_spatial_query 'select HG_GetString(HG_GeometryFromBinary(ogcbinary))from tmpbinary

'

HG_GeometryFromTextThe HG_GeometryFromText function interprets an OGC well-known text string and creates a SpatialWare geometry from it.

Syntax

HG_GeometryFromText(ogctext)

• ogctext – An OGC well-known text string of type text passed from a table.

Return Type

HG_GeometryFromText returns an ST_Spatial.

Example

The following example queries a temporary table called tmptxt. This table contains OGC well-known text generated by HG_AsText from SpatialWare geometry. Please refer to the description for HG_AsText.

exec sp_spatial_query 'select HG_GetString(HG_GeometryFromText(ogctxt))

User Guide 125

HG_GeometryFromText

from tmptxt'


14
Aggregate Functions
Spatial Aggregate functions work across rows in a group. An aggregate function returns a single-row result of type Spatial. Aggregate functions take as input one or more spatial objects of type ST_Spatial and return a single spatial object.

In this section:

HG_Aggspatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128HG_Aggunion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128HG_Aggintersection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129HG_Aggconvex_Hull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130HG_Bounding_Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

HG_Aggspatial

HG_AggspatialHG_Aggspatial returns a spatial object that contains the geometries from the spatial objects in a group.

Given the following group of spatial values:

• 'point(1,2)'• 'polyline(list{point1,2), point(3,2)})'• 'box(1,2,3,2)'• 'point(7,5)'

HG_Aggspatial returns:

st_spatial(list{point(1,2), polyline(list{point(1,2), point(3,2)}), box(1,2,3,2), point(7,5)})'

Syntax

HG_Aggspatial(spatial_obj)


Return Type

HG_Aggunion returns an ST_Spatial.

Example

exec sp_spatial_query ’select hg_aggspatial(flood100.sw_geometry)from flood100;

’

HG_AggunionHG_Aggunion returns the union of the spatial objects in the group.

HG_Aggunion returns the union, see also HG_Union on page 211, of each ST_Spatial value in the group. For a group of four ST_Spatial values (a, b, c, d), HG_Aggunion returns the equivalent to:

hg_union(hg_union(hg_union(hg_union(a, b), c), d)

HG_Union

The following diagram shows the behavior of HG_Union with the basic shape types. The right side of the arrow is the return object. 'Line' represents all Curve objects: ST_CircularArc, ST_Polyline, HG_Curve, and HG_Circle. Collections of objects follow these basic examples.


Chapter 14:

Syntax

HG_Aggunion(spatial_obj)


Return Type

HG_Aggunion returns an ST_Spatial.

Example

exec sp_spatial_query ’select hg_aggunion(flood100.sw_geometry) from flood100;

’

HG_AggintersectionHG_Aggintersection returns the intersection of the spatial objects in the group. HG_Aggintersection calls HG_Intersection, but is used for groups of ST_Spatials. For a group of four ST_Spatial values (a, b, c, d), HG_Aggintersection returns the equivalent to:

hg_intersection(hg_intersection(hg_intersection(a, b), c), d)

Syntax

HG_Aggintersection(spatial_obj)


Return Type

HG_Aggintersection returns an ST_Spatial. If there is no intersection of all the spatial objects in this group, an empty geometry is returned.

User Guide 129

HG_Aggconvex_Hull

Example

exec sp_spatial_query ’select hg_aggintersection(drain.sw_geometry)from drain;

’

HG_Aggconvex_HullHG_Aggconvex_Hull returns the convex hull for the group of spatial objects.

Syntax

HG_Aggconvex_Hull(spatial_obj)


Return Type

HG_Aggconvex_Hull returns an ST_Spatial.

Example

exec sp_spatial_query ’select hg_aggconvex_hull(pubbldg.sw_geometry)from pubbldg;

’

HG_Bounding_BoxHG_Bounding_Box returns the bounding box for the group of spatial objects. This is the minimum enclosing rectangle (MER) around all ST_Spatial values in a group.


Chapter 14:

Syntax

HG_Bounding_Box(spatial_obj)


Return Type

HG_Bounding_Box returns an ST_Spatial.

Example

exec sp_spatial_query ’select hg_bounding_box(pubbldg.sw_geometry)from pubbldg;

’

User Guide 131

HG_Bounding_Box


15
Coordinate Functions
Coordinate functions are applied to transform between coordinate systems.

For information about how SpatialWare handles coordinate systems, please refer to Chapter 11: Performing Coordinate System Transformations.

In this section:

HG_CSTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134

HG_CSTransform

HG_CSTransformHG_CSTransform is a coordinate transformation function. Given a geometry, the description of the coordinate system that it is in, and the target coordinate system, HG_CSTransform performs a transformation. The source and destination coordinate systems are described by the OGC well-known text strings.

The master..HG_SpatialRef table (located in the Master database) contains the well-known text strings for supported coordinate systems.

Coordinate system information is not stored in the system. You must know what coordinate system your data is stored in when working with coordinate systems.

For more information, refer to the chapter on Coordinate Systems.

Syntax

HG_CSTransform(spatial_obj, from_cs, to_cs)

• spatial_obj – The spatial object being transformed, an ST_Spatial.• from_cs – The coordinate system to transform from a string. • to_cs – The coordinate system to transfer to a string.

Return Type

HG_CSTransform returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(HG_CSTransform(

a.sw_geometry, b.srtext, c.srtext))from world a, master..hg_spatialref b,

master..hg_spatialref cwhere b.cs_name = ''Longitude / Latitude'' and c.cs_name = ''Robinson''

'

Coordinate systems are specified by the OGC standard well-known text representation. The well- known text strings for the coordinate systems are available in the table master..HG_SpatialRef (in the Master database). This example assumes the existence of a table called spotelev with geometries in 'Texas 4203, Central Zone (1983, US Survey feet)'.


16
General Functions
General functions perform operations, make queries, or change settings.

In this section:

HG_GetString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136HG_Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

HG_GetString

HG_GetString HG_GetString returns the text representation of a geometry (binary).

A select statement on a column of type ST_Spatial returns a non-text representation of a geometry; HG_GetString is used in a select statement to return the text representation of a selected ST_Spatial value. An ST_Spatial type is the internal, non-text representation of a spatial object.

Syntax

HG_GetString(spatial_obj)


Return Type

HG_GetString returns a text string.

Examples

This example returns all geometries in the lake table.

exec sp_spatial_query 'select HG_GetString(sw_geometry)from lake

'

This example returns buffers for every geometry in the lake table.

exec sp_spatial_query 'select sw_member, HG_GetString(

ST_Buffer(sw_geometry, 66.0, 1.0))from lake

'

HG_VersionHG_Version returns the current version of SpatialWare as a text string.

Syntax

HG_Version()

• No input is required.

Return Type

HG_Version returns an text string.


Chapter 16:

Examples

Stored procedure, sp_spatial_query, statement:

exec sp_spatial_query 'select HG_Version() from master.HG_OneRow

'

SQL statement:

select dbo.HG_Version()

User Guide 137

HG_Version


17
Measurement Functions
Measurement functions perform calculations on geometries to find a measurable characteristic, such as length, slope, area, or height.

In this section:

HG_Azimuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140HG_Azimuth_2pts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140HG_Distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141HG_Height. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142HG_Separation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142HG_Slope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143HG_Slope_2pts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143HG_Slope_Avg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144HG_Slope_Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145HG_Slope_Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145HG_SphericalArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146HG_SphericalDist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147HG_SphericalDistance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148HG_SphericalLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149HG_SphericalPerimeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149HG_Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150ST_Area. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150ST_Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151ST_Length_3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151ST_Perimeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152ST_Perimeter_3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

HG_Azimuth

HG_AzimuthHG_Azimuth returns the compass angle between the end and beginning points of a line. HG_Azimuth finds the beginning and end points of the input line, performs an HG_Azimuth_2pts operation on the two points (see page 140), and returns the result. The line direction attribute determines which point is represented as beginning or end.

Line Direction Attribute

In addition to the global attributes, ST_Line contains a direction attribute that specifies the directional property of the line. Line directions are FORWARD, REVERSE, or NULL.

The Direction of a line determines which points are considered the beginning and end points Line direction is relevant for many functions in SpatialWare, such as HG_Slope. A line has 0 to n points.

When a line’s direction is FORWARD of NULL, the beginning point is P0 and the end point is Pn. When a line is REVERSE, the beginning point is Pn and the end point is P0.

Syntax

HG_Azimuth(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_Polyline.

Return Type

HG_Azimuth returns a double precision number representing degrees.

Example

exec sp_spatial_query 'select HG_Azimuth(rdpaved.sw_geometry)from rdpaved;

'

HG_Azimuth_2ptsHG_Azimuth_2pts returns the compass angle of the second point, relative to the first. The first parameter becomes the origin point and the second parameter, the relative point. The origin point is always represented as zero degrees North.


Chapter 17:

The direction of the angle calculation is clockwise from 0 to 360 degrees.

Syntax

HG_Azimuth_2pts(spatial_obj1, spatial_obj2)

• spatial_obj1 – Must be an ST_Spatial point (the origin).• spatial_obj2 – Must be an ST_Spatial point (the relative point).

Return Type

HG_Azimuth_2pts returns a double precision number representing degrees or radians.

Example

exec sp_spatial_query 'select HG_Azimuth_2pts(

spotelev.sw_geometry,ST_Spatial(''ST_Point(1753960.182000,

10698421.103000,2784.945100)'')) from spotelev

'

HG_DistanceHG_Distance returns the cartesian distance between two geometries in a two-dimensional plane.

Syntax

HG_Distance(spatial_obj1, spatial_obj2)

• spatial_obj1 – An ST_Spatial.• spatial_obj2 – An ST_Spatial.

Return Type

HG_Distance returns a double precision number.

User Guide 141

HG_Height

Example

exec sp_spatial_query 'select HG_Distance(

sw_geometry,ST_Spatial(''ST_Point(1753960, 10698421)''))

from spotelev'

Caveat

For longitude/latitude data, use HG_SphericalDistance on page 148.

HG_HeightHG_Height returns the height of any ST_Spatial geometry. Height is measured as the change in the y-value of the object's minimum enclosing box. The object can be either two or three dimensional.

Syntax

HG_Height(spatial_obj)


Return Type

HG_Height returns a double precision number.

Example

exec sp_spatial_query 'select HG_Height(sw_geometry) from lake

'

HG_SeparationHG_Separation returns the distance between two points in a three-dimensional space.


Chapter 17:

Syntax

HG_Separation(spatial_obj1, spatial_obj2)

• spatial_obj1 – Must be an ST_Spatial representing an ST_Point.• spatial_obj2 – Must be an ST_Spatial representing an ST_Point.

Return Type

HG_Separation returns a double precision number.

Null is returned if the points are specified as two-dimensional.

Example

exec sp_spatial_query 'select HG_Separation(a.sw_geometry, b.sw_geometry)from spotelev a, spotelev b

'

HG_SlopeHG_Slope returns the slope of a three-dimensional line by finding the end points and calculating the slope. Points falling between the end points are ignored.

Syntax

HG_Slope(spatial_obj)

• spatial_obj – An ST_Spatial representing a three-dimensional ST_Polyline.

Return Type

HG_Slope returns an angle in degrees as a double precision number.

NULL is returned if a two-dimensional line is given as a parameter.

Usage

Use this function during a three-dimensional session.

Example

exec sp_spatial_query 'select HG_Slope(sw_geometry) from geomtest

'

HG_Slope_2ptsHG_Slope_2pts returns the angle between two three-dimensional points. The angle is negative if the second point is lower than the first point.

User Guide 143

HG_Slope_Avg

Slope is directional, so the order of the parameters is important. The first parameter is the beginning point and the second parameter is the end point.

Syntax

HG_Slope_2pts(spatial_obj1, spatial_obj2)

• spatial_obj1 – An ST_Spatial representing an ST_Point (the beginning point).• spatial_obj2 – An ST_Spatial representing an ST_Point (the end point).

Return Type

HG_Slope_2pts returns an angle in degrees as a double precision number.

NULL is returned if a two-dimensional points are used (points missing a z coordinate).

Example

exec sp_spatial_query 'select HG_Slope_2pts(

sw_geometry, ST_Spatial(''ST_Point(100.1, 100.2, 100.3)''))

from spotelev where sw_member = 3'

HG_Slope_AvgHG_Slope_Avg returns the average slope of all two-point line segments within a line.

The function takes a line parameter and checks for points within the line. If there are points within the line, then multiple line segments are created. The slope is determined for each segment and then the average slope of all segments is calculated.

Syntax

HG_Slope_Avg(spatial_obj)


Return Type

HG_Slope_Avg returns an angle in degrees as a double precision number.



Chapter 17:

Example

exec sp_spatial_query 'select HG_Slope_Avg(sw_geometry) from geomtestwhere sw_member = 3

'

HG_Slope_MaxHG_Slope_Max returns the maximum slope of all two-point line segments within a line. The function receives a line parameter and checks for points within the line. If there are points in the line, then multiple line segments are created. The slope is determined for each segment and the maximum slope is returned.

Syntax

HG_Slope_Max(spatial_obj)


Return Type

HG_Slope_Max returns an angle in degrees as a double precision number.


Example

exec sp_spatial_query 'select HG_Slope_Max(sw_geometry) from geomtestwhere sw_member = 3

'

HG_Slope_MinHG_Slope_Min returns the minimum slope of all two-point line segments within a line.

If there are points within the input line, then multiple line segments are created. The slope is determined for each segment and the minimum of all slopes is returned.

User Guide 145

HG_SphericalArea

Syntax

HG_Slope_Min(spatial_obj)


Return Type

HG_Slope_Min returns an angle in degrees as a double precision number.


Example

exec sp_spatial_query 'select HG_Slope_Min(sw_geometry) from geomtestwhere sw_member =3

'

HG_SphericalAreaHG_SphericalArea finds the area of a geometry, in a longitude/latitude coordinate system, assuming a spherical approximation of the Earth.

Note This function is available both as a scalar UDF and within sp_spatial_query. Refer to Chapter 21: User Defined Functions.

Syntax

HG_SphericalArea(spatial_obj, square_units)

• spatial_obj – An ST_Spatial in a longitude/latitude coordinate system.• square_units – Units as a varchar(40) for returned value. Refer to Supported Units on

page 120.

Return Type

HG_SphericalArea returns a float in the specified unit of measurement.

Example

exec sp_spatial_query 'select dbo.HG_SphericalArea(sw_geometry, ''sq km'') from world


Chapter 17:

where Country = ''Australia'''

Caveat

For non longitude/latitude data, use ST_Area on page 150.

HG_SphericalDistHG_SphericalDist returns the spherical distance between two points. The distance is calculated in meters. This function is ideal for telecom users who have data that straddles UTM boundaries.

The input geometries are assumed to be in a longitude/latitude coordinate system in the same datum. If the geometries are anything other than points, this function returns NULL.

If your application requires units other than meters it should use HG_SphericalDistance, which lets you specify the units of distance to return.

Syntax

HG_SphericalDist(point1, point2)

• point1 – An ST_Spatial (an ST_Point) in a longitude/latitude coordinate system.• point2 – An ST_Spatial (an ST_Point) in a longitude/latitude coordinate system.

Return Type

HG_SphericalDist returns a double precision number in meters.

Example

This example is in the form of a script. It creates a table called na_cities and populates it with point data representing cities: Toronto, Albany, and Las Vegas. A query is made to view the input geometry by calling HG_GetString. The spherical distance between the cities is then calculated using HG_SphericalDist. You may want to divide the result by 1000 to convert to kilometers.

create table na_cities (sw_member integer NOT NULL, city varchar(20), sw_geometry st_spatial

)exec sp_sw_spatialize_column

'dbo','na_cities','sw_geometry','sw_member',NULLinsert into na_cities values (1,

'Toronto', 'ST_Spatial(ST_Point(-79.412672,43.720834))'

)insert into na_cities values (2,

'Albany', 'ST_Spatial(ST_Point(-73.799017, 42.66575))'

)

User Guide 147

HG_SphericalDistance

insert into na_cities values (3,'Las Vegas', 'ST_Spatial(ST_Point(-115.222799160,36.205749990))'

)exec sp_spatial_query '

select city, HG_GetString(sw_geometry) from na_cities

'exec sp_spatial_query '

select a.city, b.city, HG_SphericalDist(a.sw_geometry, b.sw_geometry

) as distfrom na_cities a, na_cities bwhere a.city < b.city

'exec sp_sw_despatialize_column

'dbo','na_cities','sw_geometry','sw_member'drop table na_cities

The last two lines drop the spatial table: the spatial column is despatialized and then the table is dropped.

HG_SphericalDistanceHG_SphericalDistance finds the distance between a pair of geometries in a longitude/latitude coordinate system.

This function differs from HG_SphericalDist, which always returns result in meters.


Syntax

HG_SphericalDistance(spatial_obj1, spatial_obj2, units)

• spatial_obj1 – An ST_Spatial in a longitude/latitude coordinate system.• spatial_obj2 – An ST_Spatial in a longitude/latitude coordinate system.• units – Units as a varchar(40) for returned value. Refer to Supported Units on page 120.

Return Type

HG_SphericalDistance returns a float in the specified unit of measurement.

Example

exec sp_spatial_query 'select HG_SphericalDistance(a.sw_geometry, l.sw_geometry, ''km'') from worldcap a, worldcap l where a.Country = ''Australia'' and l.Country = ''Luxembourg''

'


Chapter 17:

Caveat

For non longitude/latitude data, use HG_Distance on page 141.

HG_SphericalLengthHG_SphericalLength finds the length of a linear geometry, in a longitude/latitude coordinate system, assuming a spherical approximation of the Earth.


Syntax

HG_SphericalLength(spatial_obj, units)

• spatial_obj – An ST_Spatial in a longitude/latitude coordinate system.• units – Units as a varchar(40) for returned value. Refer to Supported Units on page 120.

Return Type

HG_SphericalLength returns a float in a specified unit of measurement.

Example

exec sp_spatial_query 'select HG_SphericalLength(

ST_Spatial(''ST_Polyline(LIST{ST_Point(0.0, -90.0), ST_Point(0.0, 90.0)})''

), ''mi''

)from master..HG_OneRow

'

HG_SphericalPerimeterHG_SphericalPerimeter finds the perimeter of a geometry, in a longitude/latitude coordinate system, assuming a spherical approximation of the Earth.


Syntax

HG_SphericalPerimeter(spatial_obj, units)

• spatial_obj – An ST_Spatial in a longitude/latitude coordinate system.• units – Units as a varchar(40) for returned value. Refer to Supported Units on page 120.

User Guide 149

HG_Width

Return Type

HG_SphericalPerimeter returns a float in a specified unit of measurement.

HG_WidthHG_Width returns the width of any ST_Spatial geometry. Width is measured as the change in the x-value of the object's minimum enclosing box. The object can be either two or three dimensional.

Syntax

HG_Width(spatial_obj)


Return Type

HG_Width returns a double precision number.

Example

exec sp_spatial_query 'select HG_Width(sw_geometry) from lake

'

ST_AreaST_Area returns the surface area of polygon geometries; if the input geometry contains entities other than polygons, ST_Area returns a NULL value.

Syntax

ST_Area(spatial_obj)

• spatial_obj – An ST_Spatial representing a ST_Polygon.

Return Type

ST_Area returns a double precision number.


Chapter 17:

Example

exec sp_spatial_query 'select ST_Area(sw_geometry) from lake

'

Caveat

For longitude/latitude data, use HG_SphericalArea on page 146.

ST_LengthST_Length calculates the length of two dimensional line geometries; if the input geometry contains entities other than lines, ST_Length returns a NULL value.

For three-dimensional line geometries, use ST_Length_3D.

Syntax

ST_Length(spatial_obj)


Return Type

ST_Length returns a double precision number.

Example

exec sp_spatial_query 'select ST_Length(sw_geometry) from rdpavedwhere sw_member=3

'

ST_Length_3DST_Length_3D calculates the length of three dimensional line geometries; if the input geometry contains entities other than lines, ST_Length_3D returns a NULL value. For two-dimensional line geometries, use ST_Length.

Syntax

ST_Length_3D(spatial_obj)


Return Type

ST_Length_3D returns a double precision number.

User Guide 151

ST_Perimeter

Usage

Use this function with three-dimensional geometry.

Example

exec sp_spatial_query 'select ST_Length_3D(sw_geometry) from geomtest

'

ST_PerimeterST_Perimeter calculates the perimeter of two-dimensional polygon geometries; if the input geometry contains entities other than polygons, ST_Perimeter returns a NULL value.

For three-dimensional objects, use ST_Perimeter_3D.

Syntax

ST_Perimeter(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_Polygon.

Return Type

ST_Perimeter returns a double precision number.

Example

exec sp_spatial_query 'select ST_Perimeter(sw_geometry) from lake

'

ST_Perimeter_3DST_Perimeter_3D calculates the perimeter of polygon geometries in three-dimensional space; if the input geometry contains entities other than polygons, ST_Perimeter_3D returns a NULL value. For two-dimensional objects, use ST_Perimeter.

Syntax

ST_Perimeter_3D(spatial_obj)

• spatial_obj – An ST_Spatial representing a three-dimensional ST_Polygon.

Return Type

ST_Perimeter_3D returns a double precision number.

Usage



Chapter 17:

Example

exec sp_spatial_query 'select ST_Perimeter_3d(sw_geometry) from lake

'

User Guide 153

ST_Perimeter_3D


18
Observer Functions
Spatial Observer functions return numbers, objects, or conditions from within a geometry.

In this section:

HG_Begin_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157HG_Cen_X. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157HG_Cen_Y. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158HG_Cen_Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158HG_Center_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159HG_Corner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159HG_Curve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160HG_End_Arc_Rot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160HG_End_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161HG_End_Tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162HG_End_Tangent_P. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162HG_Expanded. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163HG_Exterior_Path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163HG_Extract_At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164HG_GeometryN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164HG_Interior_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165HG_Llb_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166HG_Llb_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166HG_Llb_Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167HG_Ncoords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167HG_Ncurves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168HG_Nitems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168HG_Npaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169HG_Npoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169HG_Npolygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170HG_Nsubcurves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170HG_Ori_Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171HG_Ori_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171HG_Ori_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172HG_Ori_Z. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172HG_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

HG_Pointdyn_Ori_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173HG_Pointdyn_Ori_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175HG_Pointdyn_Rot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175HG_Pointdyn_Xscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176HG_Pointdyn_Yscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176HG_PointN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177HG_Radians . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177HG_Start_Arc_Rot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178HG_Start_Tangent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178HG_Start_Tangent_P . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179HG_Subcurve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179HG_Urt_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180HG_Urt_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181HG_Urt_Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181ST_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182ST_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182ST_Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183


Chapter 18:

HG_Begin_PointHG_Begin_Point returns the start point of a line. NULL is returned if the input is not a line.

A line has 0 to n points:

Syntax

HG_Begin_Point(polyline)

• polyline – An ST_Spatial representing an ST_Polyline.

Return Type

HG_Begin_Point returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_Begin_Point(sw_geometry))from rdpaved

'

Caveat


HG_Cen_XHG_Cen_X returns the x-value of an ST_Spatial's centroid. All ST_Spatials contain information about their centroid.

Syntax

HG_Cen_X(spatial_obj)


Return Type

HG_Cen_X returns a double precision number.

User Guide 157

HG_Cen_Y

Example

exec sp_spatial_query 'select HG_Cen_X(sw_geometry)from lake

'

HG_Cen_YHG_Cen_Y returns the y-value of an ST_Spatial's centroid. All ST_Spatials contain information about their centroid.

Syntax

HG_Cen_Y(spatial_obj)


Return Type

HG_Cen_Y returns a double precision number.

Example

exec sp_spatial_query 'select HG_Cen_Y(sw_geometry)from lake

'

HG_Cen_ZHG_Cen_Z returns the z-value of an ST_Spatial's centroid. All ST_Spatials contain information about their centroid.

Syntax

HG_Cen_Z(spatial_obj)


Return Type

HG_Cen_Z returns a double precision number.

Example

exec sp_spatial_query 'select HG_Cen_Z(sw_geometry)from lake

'


Chapter 18:

HG_Center_PointHG_Center_Point returns the center point of an ST_CircularArc, or HG_Circle. The center point is the center of an arc shape. In the case of an ST_CircularArc, it is an implied center.

Syntax

HG_Center_Point(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_CircularArc, or HG_Circle.

Return Type

HG_Center_Point returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_Center_Point(sw_geometry))from geomtestwhere HG_Is_Circle(sw_geometry)

'

Caveat


HG_CornerHG_Corner is a synonym for HG_Point. It returns a specific ST_Point from an ST_Curve. ST_Curves contain zero to n ST_Points, stored sequentially in a LIST. The number parameter in HG_Corner selects a particular ST_Point from that LIST.

Syntax

HG_Corner(spatial_obj, number)

• spatial_obj – An ST_Spatial representing an ST_Curve.

User Guide 159

HG_Curve

• number – An integer representing the position of an object in a LIST.

Return Type

HG_Corner returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_Corner(sw_geometry, 3))from rdpavedwhere sw_member = 2

'

Caveat


HG_CurveHG_Curve returns a specific ST_Curve from an ST_Path. ST_Paths are composed of zero to n ST_Curves, stored sequentially in a LIST. The number parameter sent to HG_Curve selects a particular ST_Curve from that LIST.

Syntax

HG_Curve(spatial_obj, number)

• spatial_obj – An ST_Spatial representing an ST_Path.• number – An integer representing the position of an object in a LIST.

Return Type

HG_Curve returns an ST_Spatial representing an ST_Curve.

Example

exec sp_spatial_query 'select HG_GetString(HG_Curve(sw_geometry, 3))from geomtest

'

Caveat


HG_End_Arc_RotHG_End_Arc_Rot returns the ST_CircularArc's end angle in degrees: zero (0) degrees is the positive X-axis, ninety (90) degrees is the positive Y-axis.


Chapter 18:

Refer also to the description for HG_Start_Arc_Rot on page 178.

Syntax

HG_End_Arc_Rot(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_CircularArc.

Return Type

HG_End_Arc_Rot returns a real value representing degrees.

Example

exec sp_spatial_query ' select HG_End_Arc_Rot(sw_geometry) from lake'

HG_End_PointHG_End_Point returns the end point of a line.

Syntax

HG_End_Point(polyline)

• polyline – An ST_Spatial representing a ST_Polyline.

Return Type

HG_End_Point returns an ST_Spatial representing a ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_End_Point(sw_geometry))from rdpaved

'

User Guide 161

HG_End_Tangent

Caveat


HG_End_TangentHG_End_Tangent returns the tangent of an HG_Curve's end point.

Syntax

HG_End_Tangent(spatial_obj)

• spatial_obj – An ST_Spatial representing an HG_Curve.

Return Type

HG_End_Tangent returns a real value in radians.

Example

exec sp_spatial_query 'select HG_End_Tangent(sw_geometry)from geomtestwhere HG_Is_HG_Curve(sw_geometry)

'

HG_End_Tangent_PHG_End_Tangent_P returns an ST_Point on the tangent of an HG_Curve's end point.

Syntax

HG_End_Tangent_P(spatial_obj)


Return Type

HG_End_Tangent_P returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_End_Tangent_P(sw_geometry))from geomtestwhere hg_is_hg_curve(sw_geometry)

'

Caveat



Chapter 18:

HG_ExpandedHG_Expanded returns the point equivalent of an ST_Curve. For example, an ST_CircularArc is defined by three points and an equation. HG_Expanded returns a polyline (a set of straight line segments) approximation of the curve.

Syntax

HG_Expanded(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_Curve.

Return Type

HG_Expanded returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(HG_Expanded(sw_geometry))from rdpavedwhere sw_member = 1

'

Caveat


HG_Exterior_PathHG_Exterior_Path returns the exterior boundary of a polygon, an ST_Polygon. ST_Polygons have one exterior boundary and zero to n interior boundaries, defined by ST_Paths.

The input geometry must be a polygon, otherwise, HG_Exterior_Path returns NULL.

Syntax

HG_Exterior_Path(spatial_obj)

• spatial_obj – An ST_Spatial representing a ST_Polygon.

Return Type

HG_Exterior_Path returns an ST_Spatial representing a ST_Path.

Example

exec sp_spatial_query 'select HG_GetString(HG_Exterior_Path(sw_geometry))

User Guide 163

HG_Extract_At

from lake'

Caveat


HG_Extract_AtHG_Extract_At returns the primitive at a given position in a SpatialObject. The position argument can be between 0 and n-1 in a SpatialObject that has n primitives. The returned value is an instance of ST_Spatial. This function is used for extracting individual primitives in a multi-element geometry.

Syntax

HG_Extract_At(spatial_obj, ref_number)

• spatial_obj – Any ST_Spatial.• ref_number – An integer.

Return Type

HG_Extract_At returns an ST_Spatial.

Example

This example selects the first primitive of the SpatialObject whose sw_member is 1.

exec sp_spatial_query 'select HG_GetString(HG_Extract_At(sw_geometry, 0))from rdpavedwhere sw_member = 1

'

Caveat


HG_GeometryNHG_GeometryN extracts the Nth primitive in a multi-element SW_GEOMETRY, where N is a specified position. The index on HG_GeometryN is zero based. For example, zero (0) is used for the first element and one (1) is used for the second element.

If the input number is greater than the number of primitives in the geometry, NULL is returned.

Syntax

HG_GeometryN(spatial_obj, position)


Chapter 18:

• spatial_obj – An ST_Spatial.• position – An integer.

Return Type

HG_GeometryN returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(HG_GeometryN(sw_geometry, 1))from rdpavedwhere sw_member = 7

'

Caveat


HG_Interior_PathHG_Interior_Path returns a specific interior boundary from a polygon, an ST_Polygon. ST_Polygons have one exterior boundary and zero to n-1 interior boundaries, defined by ST_Paths. The interior boundaries are stored sequentially in a list. The number parameter that is sent to HG_Interior_Path selects a particular interior boundary from the list.

Syntax

HG_Interior_Path(spatial_obj, number)

• spatial_obj – An ST_Spatial representing a ST_Polygon.• number – An integer representing the position of an object in a LIST that starts with zero (i.e., 0,

1, 2, ... n).

Return Type

HG_Interior_Path returns an ST_Spatial representing an ST_Path.

Example

This example creates a polygon with a hole in it in the geomtest table:

insert into geomtest (sw_member, sw_geometry) values (27,'ST_Spatial(ST_Polygon(

HG_Box(0,0,5,5),ST_Path(LIST{

ST_Polyline(LIST{ST_Point(1,1),ST_Point(2,2)

}),ST_CircularArc(LIST{

ST_Point(2,2),

User Guide 165

HG_Llb_X

ST_Point(2,3),ST_Point(3,3)

}),ST_Polyline(LIST{

ST_Point(3,3),ST_Point(3,1),ST_Point(1,1)

})})

))')exec sp_spatial_query '

select HG_GetString(HG_Interior_Path(sw_geometry, 0))from geomtest

'

Caveat


HG_Llb_XHG_Llb_X returns the x-coordinate of the lower left corner of the minimum enclosing rectangle for the geometry.

Syntax

HG_Llb_X(spatial_obj)

spatial_obj – An ST_Spatial representing a ST_Polygon.

Return Type

HG_Llb_X returns a double precision number.

Example

exec sp_spatial_query 'select HG_Llb_X(sw_geometry)from lake

'

HG_Llb_YHG_Llb_Y returns the y-coordinate of the lower left corner of the minimum enclosing rectangle for the geometry.

Syntax

HG_Llb_Y(spatial_obj)


Chapter 18:


Return Type

HG_Llb_Y returns a double precision number.

Example

exec sp_spatial_query 'select HG_Llb_Y(sw_geometry)from lake

'

HG_Llb_ZHG_Llb_Z returns the z-coordinate of the lower left corner of the minimum enclosing rectangle for the geometry.

Syntax

HG_Llb_Z(spatial_obj)


Return Type

HG_Llb_Z returns a double precision number.

Example

exec sp_spatial_query 'select HG_Llb_Z(sw_geometry)from lake

'

HG_NcoordsHG_Ncoords returns the total number of points in an ST_Spatial, counting points embedded in other geometry constructors (ST_GeometricPrimitives). If you want just the number of ST_Points, use HG_Npoints.

Syntax

HG_Ncoords(spatial_obj)


Return Type

HG_Ncoords returns an integer.

User Guide 167

HG_Ncurves

Example

exec sp_spatial_query 'select HG_Ncoords(sw_geometry) from lake

'

HG_NcurvesHG_Ncurves returns the number of ST_Curves in an ST_Spatial. The function does not count embedded HG_Curves.

Syntax

HG_Ncurves(spatial_obj)


Return Type

HG_Ncurves returns an integer.

Example

exec sp_spatial_query 'select HG_Ncurves(sw_geometry)from rdpavedwhere sw_member < 7

'select HG_Ncurves(sw_geometry)from rdpavedwhere sw_member < 7;

HG_NitemsHG_Nitems returns the number of geometries in an ST_Spatial.

The function does not count embedded items.

Syntax

HG_Nitems(spatial_obj)


Return Type

HG_Nitems returns an integer.

Example

exec sp_spatial_query '


Chapter 18:

select HG_Nitems(sw_geometry) from lake

'

HG_NpathsHG_Npaths returns the number of ST_Paths in an ST_Spatial. The function does not count embedded ST_Paths.

Syntax

HG_Npaths(spatial_obj)


Return Type

HG_Npaths returns an integer.

Example

exec sp_spatial_query 'select HG_Npaths(sw_geometry) from lake

'

HG_NpointsHG_Npoints returns the number of ST_Points in an ST_Spatial. The function does not count embedded ST_Points.

Syntax

HG_Npoints(spatial_obj)


Return Type

HG_Npoints returns an integer.

Example

exec sp_spatial_query 'select HG_Npoints(sw_geometry) from spotelevwhere sw_member = 11

'

User Guide 169

HG_Npolygons

HG_NpolygonsHG_Npolygons returns the number of ST_Polygons in an ST_Spatial. The function does not count embedded ST_Polygons.

Syntax

HG_Npolygons(spatial_obj)


Return Type

HG_Npolygons returns an integer.

Example

exec sp_spatial_query 'select HG_Npolygons(sw_geometry) from parcelwhere sw_member < 10

'

HG_NsubcurvesHG_Nsubcurves returns the number of subcurves embedded in the ST_Lines contained by ST_Spatial. Subcurves are two-point line segments based on a line's start, end, and internal points.

Syntax

HG_Nsubcurves(spatial_obj)


Return Type

HG_Nsubcurves returns an integer.


Chapter 18:

Example

exec sp_spatial_query 'select HG_Nsubcurves(sw_geometry)from rdpaved

'

HG_Ori_RotationHG_Ori_Rotation returns the angle of rotation of an ST_Spatial's orientation point. The orientation point is an attribute of all ST_Spatials used frequently for attribute positioning.

All ST_Spatials have an orientation point, which can be used for map-attribute positioning.

The placement of the orientation point can communicate angle and rotation.

The angle of rotation is determined by the position of the orientation point, relative to the centroid

Syntax

HG_Ori_Rotation(spatial_obj)


Return Type

HG_Ori_Rotation returns a type real.

Example

exec sp_spatial_query 'select HG_Ori_Rotation(sw_geometry) from spotelevwhere sw_member = 1

'

HG_Ori_XHG_Ori_X returns the x-coordinate value of an ST_Spatial's orientation point. The orientation point is a property of all ST_Spatials, used frequently for attribute positioning. For more information, refer to HG_Ori_Rotation.

User Guide 171

HG_Ori_Y

Syntax

HG_Ori_X(spatial_obj)


Return Type

HG_Ori_X returns a double precision number.

Example

exec sp_spatial_query 'select HG_Ori_X(sw_geometry) from spotelevwhere sw_member = 11

'

HG_Ori_YHG_Ori_Y returns the y-coordinate value of an orientation point. The orientation point is a property of all ST_Spatials, used frequently for attribute positioning. For more information, refer to HG_Ori_Rotation.

Syntax

HG_Ori_Y(spatial_obj)


Return Type

HG_Ori_Y returns a double precision number.

Example

exec sp_spatial_query 'select HG_Ori_Y(sw_geometry) from spotelevwhere sw_member = 11

'

HG_Ori_ZHG_Ori_Z returns the z-coordinate value of an orientation point. The orientation point is a property of all ST_Spatials, used frequently for attribute positioning. For more information, refer to HG_Ori_Rotation.

Syntax

HG_Ori_Z(spatial_obj)


Chapter 18:


Return Type

HG_Ori_Z returns a double precision number.

Example

exec sp_spatial_query 'select HG_Ori_Z(sw_geometry) from spotelevwhere sw_member = 11

'

HG_PointHG_Point returns a specific ST_Point from an ST_Curve. ST_Curves contain zero to n ST_Points, stored sequentially in a LIST. The number parameter in HG_Point selects a particular ST_Point from that LIST. HG_Point is identical to the function HG_PointN.

Syntax

HG_Point(spatial_obj, number)

• spatial_obj – An ST_Spatial representing an ST_Curve.• number – An integer representing the position of an object in a LIST.

Return Type

HG_Point returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_Point(sw_geometry, 3))from rdpavedwhere sw_member < 24

'

Caveat


HG_Pointdyn_Ori_XHG_Pointdyn_Ori_X returns the x-coordinate value of an ST_Point's dynamic orientation point. The dynamic orientation point is one of ST_Point's dynamic attributes, used for map attribute positioning and sizing.

User Guide 173

HG_Pointdyn_Ori_X

ST_Points can store information about scale and orientation, commonly used for map attribute positioning and sizing. These attributes compose the point dynamic.

One element of the point dynamic is orientation. It is similar to the global ST_Spatial orientation, but it is an additional place to store orientation information. So, an ST_Point can have two levels of orientation: its orientation as an ST_Spatial and its orientation as an ST_Point.

The second element of the point dynamic is scale. Scale allows applications that do mapping or plotting to specify the size of an attribute associated with an ST_Point. Scaling can be done for both x and y axes.

The scale is based on one unit of plot.

Syntax

HG_Pointdyn_Ori_X(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_Point.

Return Type

HG_Pointdyn_Ori_X returns a double precision number.

Example

exec sp_spatial_query 'select HG_Pointdyn_Ori_X(sw_geometry) from spotelevwhere sw_member = 1

'


Chapter 18:

HG_Pointdyn_Ori_YHG_Pointdyn_Ori_Y returns the y-coordinate value of an ST_Point's orientation point. The orientation point is one of ST_Point's dynamic attributes, used for map attribute positioning and sizing. For more information, refer to HG_Pointdyn_Ori_X.

Syntax

HG_Pointdyn_Ori_Y(spatial_obj)


Return Type

HG_Pointdyn_Ori_Y returns a double precision number.

Example

exec sp_spatial_query 'select HG_Pointdyn_Ori_Y(sw_geometry) from spotelevwhere sw_member = 1

'

HG_Pointdyn_RotHG_Pointdyn_Rot returns the rotation, in degrees, of an ST_Point's dynamic orientation point, relative to an ST_Point. The point dynamic attributes are used frequently for map attribute positioning and sizing. For more information, refer to HG_Pointdyn_Ori_X.

Syntax

HG_Pointdyn_Rot(spatial_obj)


Return Type

HG_Pointdyn_Rot returns a value of type real.

Example

exec sp_spatial_query 'select HG_Pointdyn_Rot(sw_geometry) from spotelevwhere sw_member = 1

'

User Guide 175

HG_Pointdyn_Xscale

HG_Pointdyn_XscaleHG_Pointdyn_Xscale returns the X-axis scale value of an ST_Point's dynamic scale. Scale is an attribute of all ST_Points, used frequently for map attribute positioning and sizing. The scale is based on one unit of plot scale. For more information, refer to HG_Pointdyn_Ori_X.

Syntax

HG_Pointdyn_Xscale(spatial_obj)


Return Type

HG_Pointdyn_Xscale returns a value of type real.

Example

exec sp_spatial_query 'select HG_Pointdyn_Xscale(sw_geometry) from spotelevwhere sw_member = 1

'

HG_Pointdyn_YscaleHG_Pointdyn_Yscale returns the Y-axis value of an ST_Point's scale attribute. The scale attribute is one of ST_Point's dynamic attributes, used frequently for attribute positioning and sizing. The scale is based on one unit of plot scale.

Syntax

HG_Pointdyn_Yscale(spatial_obj)


Return Type

HG_Pointdyn_Yscale returns a value of type real.

Example

exec sp_spatial_query 'select HG_Pointdyn_Yscale(sw_geometry) from spotelevwhere sw_member = 1

'


Chapter 18:

HG_PointNHG_PointN returns the Nth point in a line geometry, where N is a specified position. The index on HG_Point is zero based. For example, zero (0) is used for the first element and one (1) is used for the second element.

If the input number is greater than the number of points in the geometry, NULL is returned.

Syntax

HG_PointN(spatial_obj, position)

• spatial_obj – An ST_Spatial representing an ST_Polyline.• position – An integer representing the position of a point in a line geometry.

Return Type

HG_PointN returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_PointN(sw_geometry, 3))from rdpavedwhere sw_member = 35

'

Caveat


HG_RadiansHG_Radians returns the subtended angle of an ST_CircularArc, or HG_Circle.

Syntax

HG_Radians(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_CircularArc, or HG_Circle.

Return Type

HG_Radians returns a double precision number.

Example

exec sp_spatial_query 'select HG_Radians(sw_geometry) from geomtest

User Guide 177

HG_Start_Arc_Rot

where HG_Is_Circle(sw_geometry)'

HG_Start_Arc_RotHG_Start_Arc_Rot returns the ST_CircularArc's start angle in degrees: zero (0) degrees is the positive X-axis, ninety (90) degrees is the positive Y-axis.

Refer also to the description for HG_End_Arc_Rot.

Syntax

HG_Start_Arc_Rot(spatial_obj)

• spatial_obj – An ST_Spatial representing an ST_CircularArc.

Return Type

HG_Start_Arc_Rot returns a real value representing degrees.

HG_Start_TangentHG_Start_Tangent returns the tangent of an HG_Curve's start point.

Syntax

HG_Start_Tangent(spatial_obj)


Return Type

HG_Start_Tangent returns a real value in radians.


Chapter 18:

Example

exec sp_spatial_query 'select HG_Start_Tangent(sw_geometry)from geomtestwhere HG_Is_HG_Curve(sw_geometry)

'

HG_Start_Tangent_PHG_Start_Tangent_P returns an ST_Point on the tangent of an HG_Curve's start point.

Syntax

HG_Start_Tangent_P(spatial_obj)

• spatial_obj – An ST_Curve.

Return Type

HG_Start_Tangent_P returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_Start_Tangent_P(sw_geometry))from geomtestwhere HG_Is_HG_Curve(sw_geometry)

'

Caveat


HG_SubcurveHG_Subcurve returns a specific subcurve from an ST_Curve. A subcurve is a curve contained in an ST_Curve. The start_point and number_of_segments parameters determine which subcurve is returned.

User Guide 179

HG_Urt_X

Syntax

HG_Subcurve(spatial_obj, start_point, number_of_segments)

• spatial_obj – An ST_Spatial representing an ST_Curve.• start_point – An integer representing the position of an ST_Point in a LIST (counting from 0).• number_of_segments – An integer representing the number of segments to return.

Return Type

HG_Subcurve returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(HG_Subcurve(sw_geometry, 1, 2))from rdpavedwhere sw_member = 8

'

Caveat


HG_Urt_XHG_Urt_X returns the x-coordinate of the upper right corner of the minimum enclosing rectangle for the geometry.

Syntax

HG_Urt_X(spatial_obj)


Return Type

HG_Urt_X returns a double precision number.


Chapter 18:

Example

exec sp_spatial_query 'select HG_Urt_X(sw_geometry)from lake

'

HG_Urt_YHG_Urt_Y returns the y-coordinate of the upper right corner of the minimum enclosing rectangle for the geometry.

Syntax

HG_Urt_Y(spatial_obj)


Return Type

HG_Urt_Y returns a double precision number.

Example

exec sp_spatial_query 'select HG_Urt_Y(sw_geometry) from lake

'

HG_Urt_ZHG_Urt_Z returns the z-coordinate of the upper right corner of the minimum enclosing rectangle for the geometry.

Syntax

HG_Urt_Z(spatial_obj)


User Guide 181

ST_X

Return Type

HG_Urt_Z returns a double precision number.

Example

exec sp_spatial_query 'select HG_Urt_Z(sw_geometry) from lake

'

ST_XST_X returns the x-coordinate of a point geometry. If the geometry is not a point, ST_X returns NULL.

Syntax

ST_X(spatial_obj)


Return Type

ST_X returns a double precision number.

Example

exec sp_spatial_query 'select ST_X(sw_geometry)from spotelev

'

ST_YST_Y returns the y-coordinate of a point geometry. If the geometry is not a point, ST_Y returns NULL.

Syntax

ST_Y(spatial_obj)


Return Type

ST_Y returns a double precision number.

Example

exec sp_spatial_query 'select ST_Y(sw_geometry)


Chapter 18:

from spotelev'

ST_ZST_Z returns the z-coordinate of a point geometry. If the geometry is not a point, ST_Z returns NULL.

Syntax

ST_Z(spatial_obj)

spatial_obj – An ST_Spatial representing an ST_Point.

Return Type

ST_Z returns a double precision number.

Example

exec sp_spatial_query 'select ST_Z(sw_geometry) from spotelev

'

User Guide 183

ST_Z


19
Spatial Functions
Spatial functions perform operations on geometries to create new geometries.

Please note that HG_GetString has been added to some of the examples in this section, so that they return geometry in text format.

In this section:

HG_Affine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187HG_Affine3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187HG_As_Curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188HG_As_Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189HG_As_Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189HG_Center_In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190HG_Center_In_3D. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191HG_Centroid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192HG_Clean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192HG_Clean_I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193HG_Clean_S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195HG_Combine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196HG_Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196HG_Convex_Hull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197HG_Difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198HG_End_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199HG_Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199HG_Erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201HG_Erase_Outside. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202HG_Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203HG_Filter_Curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204HG_Filter_Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204HG_Filter_Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204HG_Filter_Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205HG_Intersect_In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205HG_LL_Circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206HG_SphericalBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207HG_SphericalCircle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208HG_Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208HG_Start_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209

HG_Sym_Difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210HG_Union. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211ST_Adjacent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212ST_Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213ST_Contain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214ST_Overlap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215ST_Transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216ST_Transform3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218


Chapter 19:

HG_AffineThe HG_Affine function performs a 2x3 affine transformation on a geometry.

In a 2x3 affine transformation a matrix is used to specify the coefficients of the general form affine transformation:

x' = A*x + B*y + C

y' = D*x + E*y + F

Syntax

HG_Affine(spatial_obj, A, B, C, D, E, F)

• spatial_obj – An ST_Spatial.• A, B, C, D, E, F – These are 2x3 matrix double values.

Return Type

HG_Affine returns an ST_Spatial.

Example

This example scales a point (1,1) by 100 in the x direction about origin, by –100 in the y direction about origin, and then translates the result by (1, -1).

exec sp_spatial_query 'select HG_Affine (

ST_Spatial(''ST_Point(1, 1)''), 100.0, 0.0, 1.0, 0.0, -100.0, -1.0)

from dual'

In this example:

x = 1y = 1

The result will be:

x' = 100*x + 0*y + 1 = 101y' = 0*x + (-100)*y + (-1) = -101

HG_Affine3DThe HG_Affine3D function performs a 3x4 affine transformation on three-dimensional geometry.

In a 3x4 affine transformation HG_Matrix_3x4 is used to specify the coefficients of the general form affine transformation:

x' = A*x + B*y + C*z + D

User Guide 187

HG_As_Curves

y' = E*x + F*y + G*z + H

z' = I*x + J*y + K*z + L

Syntax

HG_Affine3D(spatial_obj, A, B, C, D, E, F, G, H, I, J, K, L)

• spatial_obj – An ST_Spatial.• A,B,C,D,E,F,G,H,I,J,K,L – These are 3x4 matrix double values.

Return Type

HG_Affine3D returns an ST_Spatial.

Usage


Example

This HG_Affine3D example scales a point (1,1,2) by 100 in the x direction about origin, by –100 in the y direction about origin, by 1 in the z direction about the origin, and then translates the result by (1, -1, 0).

exec sp_spatial_query 'select HG_Affine3D(

ST_Spatial(''ST_Point(1, 1, 2)''), 100.0, 0.0, 0.0, 1.0, 0.0, -100.0, 0.0, -1.0, 0.0, 0.0, 1.0, 0.0

)from dual

'

In this example x = 1, y = 1, and z = 2. The result will be:

x' = 100*x + 0*y + 0*z + 1 = 101y' = 0*1 + (-100)*y + 0*z + (-1) = -101z' = 0*x + 0*y + 1*z +0 = 2

HG_As_CurvesHG_As_Curves returns a copy of an instance of a geometry, where all polygon and path elements are replaced by their composite curves (HG_Curve).

Syntax

HG_As_Curves(spatial_obj)


Return Type

HG_As_Curves returns ST_Spatial representing an ST_Polyline.


Chapter 19:

Example

exec sp_spatial_query 'select HG_GetString(HG_As_Curves(sw_geometry))from flood100

'

HG_As_PathsHG_As_Paths returns a copy of an SW_GEOMETRY, where all polygons are replaced by the line-strings forming their boundary.

Syntax

HG_As_Paths(spatial_obj)


Return Type

HG_As_Paths returns an ST_Spatial representing an ST_Polyline.

Example

exec sp_spatial_query 'select HG_GetString(HG_As_Paths(sw_geometry))from flood100

’

HG_As_PointsHG_As_Points returns the pointal equivalent of a spatial object by breaking primitives down into their component points. In the case of a circle, only three points are returned: the center point, and two points on the circumference.

User Guide 189

HG_Center_In

Syntax

HG_As_Points(spatial_obj)


Return Type

HG_As_Points returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_As_Points(sw_geometry))from flood100

'

HG_Center_InHG_Center_In centers spatial_obj1 on spatial_obj2, in two dimensional space.

spatial_obj1 (e.g., the circle) is transformed so that its centroid overlaps the centroid of spatial_obj2 (e.g., the box).

Syntax

HG_Center_In(spatial_obj1, spatial_obj2)


Return Type

HG_Center_In returns an ST_Spatial.


Chapter 19:

Example

exec sp_spatial_query 'select HG_GetString(HG_Center_In(

flood100.sw_geometry, ST_Spatial(''ST_Point(1753960.182000, 10698421.103000)'')

)) from flood100

'

HG_Center_In_3DHG_Center_In_3D centers spatial_obj1 in spatial_obj2, in three-dimensional space.

spatial_obj1 (e.g., the circle) is transformed so that its centroid overlaps the centroid of spatial_obj2 (e.g., the box).

Syntax

HG_Center_In_3D(spatial_obj1, spatial_obj2)

• spatial_obj1 – An ST_Spatial to be centered in spatial_obj2.• spatial_obj2 – An ST_Spatial.

Return Type

HG_Center_In_3D returns an ST_Spatial.

Example

This example generates a circle in the geomtest table and then centers it with a point when HG_Center_In_3D is called.

insert into geomtest (sw_member, sw_geometry) values (28,ST_Spatial('HG_Circle(ST_Point(1,1,1), 10'))

)exec sp_spatial_query '

select HG_GetString(HG_Center_In_3D(sw_geometry, ST_Spatial(''ST_Point(2,2,2)'')

))

User Guide 191

HG_Centroid

from geomtest'

HG_CentroidHG_Centroid returns the centroid of a given geometry.

Syntax

HG_Centroid(spatial_obj)


Return Type

ST_Centroid returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select sw_member, HG_GetString(HG_Centroid(sw_geometry)) from lake

'

HG_CleanHG_Clean takes an object as input and creates a simpler topologically correct geometry.

Refer also to HG_Clean_I and HG_Clean_S, which use topology, control, and filter values.

Syntax

HG_Clean(spatial_obj)


Chapter 19:


Return Type

HG_Clean returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(HG_Clean(sw_geometry))from geomtestwhere sw_member=1

'

HG_Clean_IHG_Clean_I takes an object as input and creates a topologically correct geometry. Topology and control parameters are specified as integer values:

The following diagrams show the expected behavior with basic shape types when specifying topology and control values. The right side of the arrow is the resulting geometry. The lines could be any curve geometry: circular arc, polyline, curve, or circle. The following illustrate results for node, linear, and surface output topology options:

Output Topology Type Integer Value

undefinednodelinearsurface

-1012

Output Control Type Integer Value

discardno aggregatesdrop spikesdrop dangles

0123

User Guide 193

HG_Clean_I

The following output controls work on surfaces only: drop spikes, and drop dangles. They will have no effect if set with node or linear output topology options.

By default, the clean functions set the current topology to be 'surface'. If a linear (polyline) is given as input, then an unclosed surface is returned. In this case, the direction of the polyline is not preserved. If the topology is set to be 'linear' or 'auto-detected' then the output would be a linear object with direction preserved.

This function is the same as HG_Clean_S except that it accepts topology and control types as integer values instead of strings. Refer also to HG_Clean.

Syntax

HG_Clean_I(spatial_obj, topology, control, filter)

• spatial_obj – An ST_Spatial.• topology – The topological type as an integer.• control – The control type to build topology as an integer.• filter – The filter tolerance, specified in double precision database units.

Return Type

HG_Clean_I returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(HG_Clean_I(sw_geometry, 2, 3, 2.0))from geomtest


Chapter 19:

where sw_member=1’

HG_Clean_SHG_Clean_S takes an object as input and creates a topologically correct geometry. Topology and control parameters are specified as strings:

This function is the same as HG_Clean_I except that it accepts topology and control types as strings instead of as integer values. Please refer to HG_Clean_I for a more detailed description of what is returned by these two functions.

Refer also to the related function HG_Clean.

Syntax

HG_Clean_S(spatial_obj, topology, control, filter)

• spatial_obj – An ST_Spatial.• topology – The topological type as a Boolean value (true or false).• control – The control type to build topology as a Boolean value (true or false).• filter – The filter tolerance, specified in double precision database units.

Return Type

HG_Clean_S returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(

HG_Clean_S(sw_geometry,''surface'',''drop_dangles'',2.0))from geomtestwhere sw_member=1

'

Output Topology Type Input String

undefinednodelinearsurface

'undef''node''linear''surface'

Output Control Type Input String

discardno aggregatesdrop spikesdrop dangles

'discard''no_agg''drop_spikes''drop_dangles'

User Guide 195

HG_Combine

HG_CombineHG_Combine is a union, it dissolves the boundaries in a spatial object. HG_Combine will drop any common primitives and form only one object as shown in the following image.

Syntax

HG_Combine(spatial_obj)

• spatial_obj – A geometry collection of type ST_Spatial.

Return Type

HG_Combine returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(HG_Combine(sw_geometry))from geomtestwhere sw_member=9

'

HG_ConnectHG_Connect returns the points of connection between a line (ST_Polyline) and an SW_GEOMETRY. Connection points occur when the boundary of the SW_GEOMETRY shares a point with either the start or end of the line (or both).


Chapter 19:

Syntax

HG_Connect(spatial_obj1, spatial_obj2)

• spatial_obj – An ST_Spatial.• spatial_obj2 – An ST_Spatial representing an ST_Polyline.

Return Type

HG_Connect returns an ST_Spatial representing an ST_Point.

Example


HG_Connect(flood100.sw_geometry, rdpaved.sw_geometry))from flood100, rdpaved

'

HG_Convex_HullHG_Convex_Hull returns the minimum boundary around a spatial object without the boundary being concave. The result is the spatial object representing the convex hull of the perimeter.

User Guide 197

HG_Difference

Syntax

HG_Convex_Hull(spatial_obj)


Return Type

HG_Convex_Hull returns an ST_Spatial representing a ST_Polygon.

Example

exec sp_spatial_query 'select HG_GetString(HG_Convex_Hull(sw_geometry))from geomtestwhere sw_member=2

'

HG_DifferenceHG_Difference removes those places where two spatial objects overlap. The point set difference is returned, (A-B).

The HG_Difference function is very similar to HG_Erase except that the cutter object does not need to be a closed surface, it could be a linear object.

Syntax

HG_Difference(spatial_obj1, spatial_obj2)


Return Type

HG_Difference returns an ST_Spatial.

Example


HG_Difference(a.sw_geometry, b.sw_geometry))


Chapter 19:

from flood100 b, lake a'

HG_End_OfHG_End_Of returns the end point of a line if it matches a point in the boundary of an ST_Spatial.

Syntax

HG_End_Of(spatial_obj1, spatial_obj2)

• spatial_obj1 – An ST_Spatial.• spatial_obj2 – An ST_Spatial representing an ST_Polyline.

Return Type

HG_End_Of returns an ST_Spatial.

Example


HG_End_Of(a.sw_geometry, b.sw_geometry))from flood100 a, rdpaved b

'

HG_EnvelopeHG_Envelope returns the smallest rectangle, orthogonal to the axes, that can contain a geometry. The rectangle is an ST_Polygon.

User Guide 199

HG_Envelope

The following diagram shows the behavior of HG_Envelope with the basic shape types. The right side of the arrow is the return object. The line type represents all curve objects: circular arc, polyline, curve, and circle.

Syntax

HG_Envelope(spatial_obj)


Return Type

HG_Envelope returns an ST_Spatial representing an ST_Polygon.

Example

This query retrieves the smallest rectangle that contains the given SW_GEOMETRY:

exec sp_spatial_query 'select lake.sw_member,HG_GetString(HG_Envelope(lake.sw_geometry))from lake

'


Chapter 19:

HG_EraseHG_Erase removes those places of a target object that overlap with a cutting object. Any places where the target object overlaps with the cutter object are removed. HG_Erase produces the opposite result to HG_Erase_Outside.

HG_Erase performs a cutting operation; one spatial object is used as the target object to be cut, and another spatial object is used as the cutter. A new geometry is generated as output. Those places where the cutter object intersect with the target object are removed. If the cutter object does not intersect with the target object, then the target object remains unchanged. If the cutter object contains the target object, then the target object is removed from the result. If using a binary relationship, where object A is the target and object B is the cutter, results in object B are subtracted from object A. For example:

Note that the polygon was completely contained within the cutter object and has been removed from the result. Although the linear object has been cut into multiple pieces, the result is a single region object.

The HG_Erase function is very similar to HG_Difference except that the cutter object must be a closed surface (closed polygons). It cannot be a linear object. The HG_Difference function accepts a cutter object that is not closed, such as a linear.

Syntax

HG_Erase(spatial_obj1, spatial_obj2)

• spatial_obj1 – The target ST_Spatial.• spatial_obj2 – The cutter ST_Spatial (a closed polygon).

Return Type

HG_Erase returns an ST_Spatial.

User Guide 201

HG_Erase_Outside

Example


HG_Erase(flood100.sw_geometry, lake.sw_geometry))from flood100, lake

'

HG_Erase_OutsideHG_Erase_Outside removes those places of a target object that do not overlap with a cutting object. HG_Erase_Outside produces the opposite result to HG_Erase.

The cutter object must be a closed surface (a closed polygon).

A set of objects are target objects, and another set of objects are cutter objects. The portion of a target object, which overlaps with the cutter object is retained, and all else is discarded. A new geometry is generated as output. If the target object is contained within the cutter object then it remains in the result unchanged. If the target object does not intersect with the cutting object, then it is removed from the result. Using a binary relationship where object A is the target, and object B is the cutter, results in A intersected with B. For example:

The polygon was completely contained within the cutter object and remains unchanged in the result. Those portions of the linear object that lie outside of the cutter object are not included within the result.

The cutter object must be a closed surface (a closed polygon). It cannot be a linear object.

Syntax

HG_Erase_Outside(spatial_obj1, spatial_obj2)

• spatial_obj1 – The target ST_Spatial.


Chapter 19:

• spatial_obj2 – The cutter ST_Spatial (a closed polygon).

Return Type

HG_Erase_Outside returns an ST_Spatial.

Example


HG_Erase_Outside(drain.sw_geometry, flood100.sw_geometry))from drain, flood100

'

HG_FilterHG_Filter returns simplified geometries, either a polyline (ST_Polyline) or curve (HG_Curve), by removing points.

A curve or boundary of a polygon may have more detail than you require. Such excessive detail makes processing slower and requires more space to store the geometry. HG_Filter selects as few points of the original curve as possible, while guaranteeing that the new simplified curve will not deviate more than the specified tolerance from the original curve.

Note The filter operation uses the Douglas-Puecker algorithm (The Canadian Cartographer, Vol.10 No.2, Dec. 1973, pp.112-122), to reduce the number of points to represent a line.

Syntax

HG_Filter(spatial_obj, tolerance)

• spatial_obj – An ST_Spatial representing an ST_Polyline or HG_Curve.• tolerance – The tolerance level used in the filter calculation, in double precision database units.

Return Type

HG_Filter returns an ST_Spatial representing an ST_Polyline or HG_Curve.

Example

exec sp_spatial_query 'select HG_GetString(HG_Filter(lake.sw_geometry, 0.1))from lake

'

User Guide 203

HG_Filter_Curves

HG_Filter_CurvesHG_Filter_Curves returns all of the curves from within a spatial object of type SW_GEOMETRY.

Syntax

HG_Filter_Curves(spatial_obj)


Return Type

HG_Filter_Curves returns an ST_Spatial containing ST_Polyline.

Example

exec sp_spatial_query 'select HG_GetString(HG_Filter_Curves(sw_geometry))from geomtest

'

HG_Filter_PathsHG_Filter_Paths returns all of the paths within a spatial object of type SW_GEOMETRY.

Syntax

HG_Filter_Paths(spatial_obj)


Return Type

HG_Filter_Paths returns an ST_Spatial representing an ST_Polyline.

Example

exec sp_spatial_query 'select HG_GetString(HG_Filter_Paths(sw_geometry))from geomtest

'

HG_Filter_PointsHG_Filter_Points returns all of the point objects from within a spatial object of type SW_GEOMETRY.


Chapter 19:

Syntax

HG_Filter_Points(spatial_obj)


Return Type

HG_Filter_Points returns an ST_Spatial representing a ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(HG_Filter_Points(sw_geometry))from geomtest

'

HG_Filter_PolygonsHG_Filter_Polygons returns all of the polygons from within a spatial object.

Syntax

HG_Filter_Polygons(spatial_obj)


Return Type

HG_Filter_Polygons returns an ST_Spatial representing an ST_Polygon.

Example

exec sp_spatial_query 'select HG_GetString(HG_Filter_Polygons(sw_geometry))from geomtest

'

HG_Intersect_InHG_Intersect_In is identical to ST_Overlap. It returns all of the overlapping elements between two spatial objects. Two elements are overlapping when they share common points. If there are no overlapping elements, then NULL is returned.

User Guide 205

HG_LL_Circle

Syntax

HG_Intersect_In(spatial_obj1, spatial_obj2)


Return Type

HG_Intersect_In returns an ST_Spatial.

Example


HG_Intersect_In(flood100.sw_geometry, lake.sw_geometry))from flood100, lake

'

HG_LL_CircleHG_LL_Circle accepts the longitude/latitude of a center point and a radial distance in meters, and creates a geometry representing a search polygon. The polygon is a good approximation of a circle in longitude/latitude.

This function provides for the curvature of the Earth and takes into account the non-uniformity of the longitude/latitude coordinate system. It uses a spherical model of Earth to generate the output polygon. It is particularly useful when the search area is large, straddles UTM zones, or is located at relatively high (or low) latitudes.

All the vertices of the polygon generated by this function will be at a spherical distance (refer to HG_SphericalDist on page 147) of <dist_meters> from the <longitude> <latitude> point.

Note This is a more precise circle for radial search on longitude/latitude points than a circular region generated by either, ST_Spatial('ST_Polygon(HG_Circle(x, y, radius))') or ST_Buffer(ST_Spatial('ST_Point(x, y)', dist, filter)

Syntax

HG_LL_Circle(longitude, latitude, dist_meters)

• longitude – The longitude of the center point (x value), in degrees.• latitude – The latitude of the center point (y value), in degrees.• dist_meters – The radius of the circle to be generated in meters.

Return Type

HG_LL_Circle returns an ST_Spatial.


Chapter 19:

Example

The following example uses the World sample database. Please refer to your product Release Notes (or readme file) for a description of how to install this sample database.

This example finds all the capitals that lie within a spherical distance of 1000 kilometers from Paris.

exec sp_spatial_query 'select a.capital, HG_SphericalDist(

a.sw_geometry,b.sw_geometry) as dist_metersfrom worldcap a, worldcap bwhere b.capital = ''Paris''and ST_Overlaps(a.sw_geometry, HG_LL_Circle(

ST_x(b.sw_geometry), ST_y(b.sw_geometry), 1000000))

'

Caveat

This function generates an approximation of a circular area in the longitude/latitude coordinate system. It assumes a spherical model of Earth, and therefore may be unsuitable for applications where a high degree precision is needed. For such applications, it may be more appropriate to transform the point to a suitable projected coordinate system, perform a circular buffer, and then transform it back to Longitude/Latitude.

This function does not handle regions straddling the longitude/latitude limits. For example, it will not handle regions straddling the international date line.

HG_SphericalBufferHG_SphericalBuffer generates a buffer region around a geometry in a longitude/latitude coordinate system.

Note This function is available within sp_spatial_query, but not available as a UDF, because SQL Server functions cannot return datatypes based on image. Also, this function is not available to a user who is accessing the functionality from MapInfo Professional or MapBasic.

Syntax

HG_SphericalBuffer(spatial_obj, width, filter, units)

• spatial_obj – The target ST_Spatial in a longitude/latitude coordinate system.• width – The buffer width as a float.• filter – Filter value as a float.• units – Width and filter units as a varchar(40). Refer to Supported Units on page 120.

Return Type

HG_SphericalBuffer returns an ST_Spatial.

User Guide 207

HG_SphericalCircle

Exampleexec sp_spatial_query '

select HG_SphericalBuffer(sw_geometry, 100.0, 0.0, ''km'') from worldwhere Country = ''Luxembourg''

'

HG_SphericalCircleThis function creates a polygon approximation of a circle, given the center point in a longitude/latitude coordinate system, a radius, and radius units.

That this function is mostly similar to the function HG_LL_Circle, which is supported in sp_spatial_query, but differs in one respect, it allows you to specify the desired units explicitly.

Note This function is available both as a scalar UDF and within sp_spatial_query. It returns a varbinary(8000) as a UDF. Refer to Chapter 21: User Defined Functions.

Syntax

HG_SphericalCircle(point, radius, units)

• point – An ST_Spatial (a point). The center point of the circular polygon in a longitude/latitude coordinate system.

• radius – The radius of the circular polygon as a float value.• units – Radius units as a varchar(40). Refer to Supported Units on page 120.

Return Type

HG_SphericalCircle returns ST_Spatial.

Exampleexec sp_spatial_query '

select HG_SphericalCircle(sw_geometry, 100.0, ''km'') from worldcap where Country = ''Australia''

'

HG_SplitHG_Split splits those places of a target object that overlap the cutting object.


Chapter 19:

HG_Split combines the results of both the HG_Erase and HG_Erase_Outside functions. One object is used as the target object and a second object is used as the cutting object. A new geometry is generated as output.

The target object is compared to the cutter object. If the target and cutter objects intersect, then the result contains one object that represents the result as if an erase operation was performed, and another object that represents the result as if an erase outside operation was performed. If a target object is completely contained within a target cutter or completely outside of it, then it remains in the result unchanged. For example:

Note that the polygon was completely contained within the cutter object and remains unchanged in the result. Although the linear object has been cut into multiple pieces, the result is a single region object.

The cutter object must be a closed surface (a closed polygon). It cannot be a linear object.

Syntax

HG_Split(spatial_obj1, spatial_obj2)

• spatial_obj1 – The target ST_Spatial.• spatial_obj2 – The cutter ST_Spatial (a closed polygon).

Return Type

HG_Split returns an ST_Spatial.

Example


HG_Split(flood100.sw_geometry, lake.sw_geometry))from lake, flood100

'

HG_Start_OfHG_Start_Of returns the start point of a line if it matches a point in the boundary of an ST_Spatial.

User Guide 209

HG_Sym_Difference

Syntax

HG_Start_Of(spatial_obj1, spatial_obj2)

• spatial_obj1 – Any ST_Spatial.• spatial_obj2 – An ST_Spatial representing an ST_Polyline.

Return Type

HG_Start_Of returns an ST_Spatial.

Example


HG_Start_Of(lake.sw_geometry, flood100.sw_geometry))from flood100, lake

'

HG_Sym_DifferenceHG_Sym_Difference performs the symmetric difference (x-or) on the parameters ((A-B) Union (B-A)).

Syntax

HG_Sym_Difference(spatial_obj1, spatial_obj2)


Return Type

HG_Sym_Difference returns an ST_Spatial.

Example


HG_Sym_Difference(lake.sw_geometry, flood100.sw_geometry))


Chapter 19:

from flood100, lake'

HG_UnionHG_Union combines two geometries, and returns the union.

The following diagram shows the behavior of HG_Union with the basic shape types. The right side of the arrow is the return object. In the illustration, Line represents all Curve objects: ST_CircularArc, ST_Polyline, HG_Curve, and HG_Circle.

Collections of objects follow these basic examples. For more information on how complex collections of objects are treated in SpatialWare, see Understanding Geometry Collections.

Syntax

HG_Union(spatial_obj1, spatial_obj2)


Return Type

HG_Union returns an ST_Spatial.

User Guide 211

ST_Adjacent

Example


HG_Union(lake.sw_geometry, flood100.sw_geometry))from lake, flood100where lake.lake_cm = 17400001 and flood100.flood100_cm = 39300021

'

ST_AdjacentST_Adjacent returns a geometry made up of the points of intersection and common line segments between two spatial objects. NULL is returned if the two spatial objects have no common values, or if the two objects share interior points.

The following diagram shows the basic valid adjacency conditions. Note that polygons can only share their boundary points with other shapes. If another shape encroaches a polygon's interior, then it is no longer adjacent.

Syntax

ST_Adjacent(spatial_obj1, spatial_obj2)



Chapter 19:

Return Type

ST_Adjacent returns an ST_Spatial representing an ST_Point.

Example

exec sp_spatial_query 'select HG_GetString(ST_Adjacent(flood100.sw_geometry, pubbldg.sw_geometry)) from flood100, pubbldg where flood100.sw_member=2

'

ST_BufferST_Buffer takes a geometry, buffer distance, and filter tolerance. The filter parameter specifies a filter tolerance on the buffer creation process.

The following diagram shows the behavior of ST_Buffer with basic shape types. The object on the right side of the arrow is the return object. The Line shape type represents all curve objects: ST_CircularArc, ST_Polyline, HG_Curve, and HG_Circle.

Filter tolerance allows you to control the buffer's detail level. By default, ST_Buffer creates a buffer with the same detail as the input object. Detail is represented by the number of points in the boundary of the object.

ST_Buffer then uses the simplified curve as input and creates a buffer.

User Guide 213

ST_Contain

Syntax

ST_Buffer(spatial_obj1, width, filter)

• spatial_obj – An ST_Spatial.• width – The size of the buffer, in double precision database units. • filter – The filter tolerance, specified in double precision database units, possibly NULL.

Return Type

ST_Buffer returns an ST_Spatial representing an ST_Polygon.

Example

The following query creates a buffer 66 feet around a lake.

exec sp_spatial_query 'select sw_member, HG_GetString(

ST_Buffer(SW_GEOMETRY, 66.0, 0.1))from lake

'

Caveat

Note that ST_Buffer may produce surprising results in the Longitude/Latitude coordinate system, consider using HG_SphericalBuffer instead. SpatialWare assumes a Cartesian coordinate system when performing this function, and performs no adjustment to account for where the coordinate is on the Earth.

In the Longitude/Latitude coordinate system, buffer units are in the units of Longitude/Latitude. A "unit" is not defined well in Longitude/Latitude, as it changes depending on where you are in the world. Moreover, a "unit" means different distances on x and y directions.

ST_ContainST_Contain returns geometry1 if it is entirely contained within geometry2 and NULL if it is not. Boundaries can touch, but the inner object cannot have any points outside the containing boundary.


Chapter 19:

Syntax

ST_Contain(spatial_obj1, spatial_obj2)


Return Type

ST_Contain returns an ST_Spatial.

Example


ST_Contain(pubbldg.sw_geometry, flood100.sw_geometry))from pubbldg, flood100

'

ST_OverlapST_Overlap returns all of the overlapping elements between two spatial objects. Two elements are overlapping when they share common points. If there are no overlapping elements, then a NULL is returned.

The following diagram shows the behavior of ST_Overlap with the basic geometries. The output geometry is shown on the right side of the arrow. The line type represents all curve geometries: circular arc, polyline, curve, and circle. Note that this diagram can also be useful for understanding ST_Overlaps. The basic conditions below that return an object, will also return true with ST_Overlaps.

User Guide 215

ST_Transform

Syntax

ST_Overlap(spatial_obj1, spatial_obj2)


Return Type

ST_Overlap returns an ST_Spatial.

Example

exec sp_spatial_query 'select HG_GetString(ST_Overlap(a.sw_geometry, b.sw_geometry))from flood100 a, lake b

'

ST_TransformST_Transform moves, rotates, or scales two-dimensional geometry using a transformation matrix (sx, tx, rx, sy, ty, ry), where sx is the x factor and x is a scale factor, translation (transform) in the x-direction, and rx is rotation (in degrees) about the x axis. The sy, ty, ry values behave in the same way for the y direction.


Chapter 19:

ST_Transform requires an origin parameter, which specifies the point of rotation. Rotation is in degrees. If there is no rotation in your transformation then a NULL value can be used for the origin parameter, the default rotation point is (0,0).

All transformations can be performed at the same time, but it is not necessary to specify all three. For example, if you only want to rotate a geometry, include zeros in the matrix for scale and transform. You can set the following:

• To specify no scaling use 1.0 for x or y. • To specify no transform use 0.0 for x or y. • To specify no rotation use 0.0 for x or y.

For information on how the transformation is calculated, refer to Chapter 28: Transformation Calculation.

Refer also to ST_Transform3D on page 218 to transform a three-dimensional object.

Syntax

ST_Transform(spatial_obj, origin, sx, tx, rx, sy, ty, ry)

• spatial_obj – An ST_Spatial.• origin – The point of origin, an ST_Spatial.• sx and sy – Scale in x and y.• rx and ry – Rotation in x and y.• tx and ty – Transformation in x and y.

All values are in database units.

Return Type

ST_Transform returns an ST_Spatial.

Usage

Use this function with two-dimensional geometry.

Example

This example scales a box to create a rectangle. The point of origin is (0,0). The scale values are 2 along the x axis, and 3 along the y axis.

User Guide 217

ST_Transform3D

exec sp_spatial_query 'select HG_GetString(ST_Transform(

ST_Spatial(''HG_Box(1, 1, 2, 2)''),ST_Spatial(''ST_Point(0, 0)''),2.0, 0.0, 0.0, 3.0, 0.0, 0.0))

from master.dbo.HG_OneRow'

This example moves a box along the x and y axis. The point of origin is (0,0). The transformvalues are 3 along the x axis, and -3 along the y axis.


ST_Spatial(''HG_Box(1, 1, 2, 2)''),ST_Spatial(''ST_Point(0, 0)''),1.0, 3.0, 0.0, 0.0, -3.0, 0.0))

from master.dbo.HG_OneRow'

This example rotates a box around the point of origin by 35 degrees. The point of origin is (0,0). The rotation values are 35 for x, and 20 for y.


ST_Spatial(''HG_Box(1, 1, 2, 2)''),ST_Spatial(''ST_Point(0, 0)''),1.0, 0.0, 35.0, 0.0, 0.0, 20.0

)) from master.dbo.HG_OneRow

'

ST_Transform3DST_Transform moves, rotates, or scales three-dimensional geometry using a transformation matrix (sx, tx, rx, sy, ty, ry, sz, tz, rz), where sx is the x scale factor, tx is translation (transform) in the x-direction, and rx is rotation (in degrees) about the axis. The sy, ty, ry, and sz, tz, rz values behave in the same way in the y and z directions.


Chapter 19:

ST_Transform3D requires an origin parameter, which specifies the point of rotation. Rotation is in degrees. If there is no rotation in your transformation then a NULL value can be used for the origin parameter, the default rotation point is (0,0,0).

All transformations can be performed at the same time, but it is not necessary to specify all three. For example, if you only want to rotate a geometry, include zeros in the matrix for scale and transform. You can set the following:

• To specify no scaling use 1.0 for x, y, or z. • To specify no transform use 0.0 for x, y, or z. • To specify no rotation use 0.0 for x, y, or z.

For information on how the transformation is calculated refer to Chapter 28: Transformation Calculation.

Syntax

ST_Transform3D(spatial_obj, origin, sx, tx, rx, sy, ty, ry, sz, tz, rz)

• spatial_obj is an ST_Spatial.• origin is the point of origin, an ST_Spatial.• sx, sy, and sz are scale in x, y, and z.• rx, ry, and rz are rotation in x, y, and z.• tx, ty, and tz are transformation in x, y, and z.

All values are in database units.

Return Type

ST_Transform3D returns an ST_Spatial.

Usage


Example

This example scales a box to create a rectangle. The point of origin is (0,0,0). The scale values are 3 along the x axis, 2 along the y axis, and 4 along the z axis.

exec sp_spatial_query 'select HG_GetString(ST_Transform3D(

ST_Spatial(''HG_Box(1, 1, 2, 2)''),ST_Spatial(''ST_Point(0, 0, 0)''),3, 0, 0, 2, 0, 0, 4, 0, 0


'

This example moves a box along the x, y, and z axes. The point of origin is (0,0,0). The transform values are 3 along the x axis, -3 along the y axis, and 2 along the z axis.


ST_Spatial(''HG_Box(1, 1, 2, 2)''),

User Guide 219

ST_Transform3D

ST_Spatial(''ST_Point(0, 0, 0)''),1, 3, 0, 0, -3, 0, 0, 2, 0


'

This example rotates a box around the point of origin by 35 degrees. The point of origin is (0,0,0). The rotation values are 35 for x, 20 for y, and 40 for z.


ST_Spatial(''HG_Box(1, 1, 2, 2)''),ST_Spatial(''ST_Point(0, 0, 0)''),1, 0, 35, 0, 0, 20, 0, 0, 40


'


20
Spatial Predicate Functions
Spatial Predicates analyze geometries against specific conditions. These functions return 'TRUE' or 'FALSE' values and are generally used within a WHERE clause.

In this section:

HG_Above . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223HG_Assembled. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223HG_At_End_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224HG_At_Start_Of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225HG_Below . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226HG_Connected_To . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226HG_Identical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228HG_Is_Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228HG_Is_Circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229HG_Is_CircularArc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229HG_Is_Closed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230HG_Is_Contiguous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230HG_Is_Curve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231HG_Is_Empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231HG_Is_Forward. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232HG_Is_HG_Curve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232HG_Is_Invalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233HG_Is_Nulldir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233HG_Is_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234HG_Is_Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234HG_Is_Polygon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235HG_Is_Polyline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235HG_Is_Quad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236HG_Is_Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236HG_Is_Triangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236HG_Is_Valid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237HG_Is_Znull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237HG_Level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238ST_Adjacent_To . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238ST_Contained_By. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240

ST_Contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240ST_Equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241ST_Meets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242ST_Not_Equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243ST_Outside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243ST_Overlaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244ST_Within. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245


Chapter 20:

HG_AboveHG_Above returns TRUE if point1 has a higher z coordinate value than point2. In heterogeneous geometries, the z ordinate of the first point geometry defines the level. If both points have the same z ordinate values, neither point is higher than the other, then HG_Above returns FALSE.

This function only works with point geometry. The results are only relevant if the input points are in three dimensions (if they have z values).

Syntax

HG_Above(spatial_obj1, spatial_obj2)

• spatial_obj1 – An ST_Spatial representing a three-dimensional point (ST_Point).• spatial_obj2 – An ST_Spatial representing a three-dimensional point (ST_Point).

Return Type

HG_Above returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from spotelevwhere HG_Above(

spotelev.sw_geometry,ST_Spatial(''ST_Point(5.0, 5.0, 5.0)'')

)'

HG_AssembledThis function returns TRUE if the input ST_Spatial is assembled. All ST_Spatials contain the assembled attribute, which can be used by applications that require it. For example, an application may set Assembled to TRUE when a shape is created. If the object is manipulated at a later time by the application, the flag will be set to FALSE until it can be validated.

Syntax

HG_Assembled(spatial_obj)


Return Type

HG_Assembled returns a Boolean value.

User Guide 223

HG_At_End_Of

Example

exec sp_spatial_query 'select sw_member from rdpaved where HG_Assembled(sw_geometry)

'

HG_At_End_OfHG_At_End_Of returns TRUE if the end point of the line matches a point in the ST_Spatial's boundary.

The following diagram shows the behavior of HG_At_End_Of with the basic shape types. The Line type represents all curve objects: ST_CircularArc, ST_Polyline, HG_Curve, and HG_Circle. The end of the line is the right end.

Collections of objects follow these basic examples.

Syntax

HG_At_End_Of(spatial_obj1, spatial_obj2)


Return Type

HG_At_End_Of returns a Boolean value.


Chapter 20:

Example

exec sp_spatial_query 'select a.sw_member, b.sw_memberfrom rdpaved a, rdpaved bwhere HG_At_End_Of(a.sw_geometry,b.sw_geometry)and a.sw_member = 28

'

HG_At_Start_OfHG_At_Start_Of returns TRUE if the start point of a line matches a point in the boundary of an object.

The following diagram shows the behavior of HG_At_Start_Of with the basic shape types. HG_At_Start_Of returns a Boolean value (of TRUE or FALSE). The following diagram illustrates the behavior of HG_At_Start_Of with the basic valid shapes. All cases below return TRUE. For the diagram, the start point is always the left end of the line. Collections of objects follow these basic examples.

Syntax

HG_At_Start_Of(spatial_obj1, spatial_obj2)


Return Type

HG_At_Start_Of returns a Boolean value.

User Guide 225

HG_Below

Example

exec sp_spatial_query 'select a.sw_member, b.sw_memberfrom rdpaved a, rdpaved bwhere HG_At_Start_Of(a.sw_geometry, b.sw_geometry)and a.sw_member = 30

'

HG_BelowHG_Below returns TRUE if point1 has a lower z coordinate value than point2. In heterogeneous geometries, the z ordinate of the first point geometry defines the level. If both points have the same z ordinate values, neither point is higher than the other, then HG_Below returns FALSE.

This function only works with point geometry. The results are only relevant if the input points are in three dimensions (if they have z values).

Syntax

HG_Below(spatial_obj1, spatial_obj2)

• spatial_obj1 – An ST_Spatial representing a three-dimensional ST_Point.• spatial_obj2 – An ST_Spatial representing a three-dimensional ST_Point.

Return Type

HG_Below returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from spotelevwhere HG_Above(

spotelev.sw_geometry, ST_Spatial(''ST_Point(5.0, 5.0, 55.0)'')

)'

HG_Connected_ToHG_Connected_To returns TRUE if the end point or start point of a line matches a point in the object.


Chapter 20:

The following diagram shows the behavior of HG_Connected_To with the basic shape types. 'Line' represents all Curve objects: ST_CircularArc, ST_Polyline, HG_Curve, and HG_Circle. Collections of objects follow these basic examples. Line direction in these examples is from left to right. All of these examples will return TRUE.

Syntax

HG_Connected_To(spatial_obj1, spatial_obj2)


Return Type

HG_Connected_To returns a Boolean value.

Example

exec sp_spatial_query 'select rdpaved.sw_member from rdpaved, flood100where HG_Connected_To(

rdpaved.sw_geometry, flood100.sw_geometry)

'

User Guide 227

HG_Identical

HG_IdenticalHG_Identical returns TRUE if two spatial objects are equal (both objects must have the same primitives in the same order).

Note This function returns the same value as ST_Equals.

Syntax

HG_Identical(spatial_obj1, spatial_obj2)


Return Type

HG_Identical returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from spotelevwhere HG_Identical(

spotelev.sw_geometry, ST_Spatial(''ST_Point(1753960.182000, 10698421.103000,

2784.945100)'') )'

HG_Is_BoxHG_Is_Box returns TRUE if the input object contains only one HG_Box.

Syntax

HG_Is_Box(spatial_obj)


Return Type

HG_Is_Box returns a Boolean value.

Example

exec sp_spatial_query 'select * from parcel


Chapter 20:

where HG_Is_Box(parcel.sw_geometry)'

HG_Is_CircleHG_Is_Circle returns TRUE if the input object contains only one HG_Circle.

Syntax

HG_Is_Circle(spatial_obj)


Return Type

HG_Is_Circle returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from lakewhere HG_Is_Circle(sw_geometry)

'

HG_Is_CircularArcHG_Is_CircularArc returns TRUE if the input object contains only one ST_CircularArc.

Syntax

HG_Is_CircularArc(spatial_obj)


Return Type

HG_Is_CircularArc returns Boolean value.

Example

exec sp_spatial_query 'select sw_member from parcel where HG_Is_CircularArc(sw_geometry)

'

User Guide 229

HG_Is_Closed

HG_Is_ClosedHG_Is_Closed returns true if the input polygon, ST_Polygon, or line string, ST_Polyline, is closed. An ST_Polygon or ST_Polyline is closed if the start and end points are the same.

Syntax

HG_Is_Closed(spatial_obj)

• spatial_obj – An ST_Spatial representing a ST_Polygon or ST_Polyline.

Return Type

HG_Is_Closed returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from parcel where HG_Is_Closed(sw_geometry)

'

HG_Is_ContiguousHG_Is_Contiguous returns TRUE if the input path, ST_Path, is contiguous. An ST_Path is contiguous when all of the component curves, ST_Curve, are touching, so that the path is uninterrupted.

Syntax

HG_Is_Contiguous(spatial_obj)


Return Type

HG_Is_Contiguous returns a Boolean value.

Example

insert into geomtest (sw_member, sw_geometry)values (29, 'ST_Spatial(ST_Path(LIST{


}),ST_CircularArc(LIST{

ST_Point(2,2),ST_Point(2,3),


Chapter 20:

ST_Point(3,3)}),ST_Polyline(LIST{

ST_Point(3,3),ST_Point(3,1),ST_Point(1,1)

})}))')

exec sp_spatial_query 'select HG_Is_Contiguous(sw_geometry) from geomtest

'

HG_Is_CurveHG_Is_Curve returns TRUE if the input object is an ST_Curve.

Syntax

HG_Is_Curve(spatial_obj)


Return Type

HG_Is_Curve returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from parcel where HG_Is_Curve(sw_geometry)

'

HG_Is_EmptyHG_Is_Empty returns TRUE if the geometry is empty, FALSE if it is not.

Syntax

HG_Is_Empty(spatial_obj)


Return Type

HG_Is_Empty returns a Boolean value.

Example

This example returns the sw_member of the empty geometry.

User Guide 231

HG_Is_Forward

exec sp_spatial_query 'select sw_member from parcel where HG_Is_Empty(sw_geometry)

'

HG_Is_ForwardHG_Is_Forward returns true if the direction attribute of the input ST_Line is FORWARD. All ST_Lines have a direction attribute of FORWARD, REVERSE, or NULL.

Syntax

HG_Is_Forward(spatial_obj)

spatial_obj – An ST_Spatial representing an ST_Polyline.

Return Type

HG_Is_Forward returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from rdpaved where HG_Is_Forward(sw_geometry)

'

HG_Is_HG_CurveHG_Is_HG_Curve returns TRUE if the input object is an HG_Curve.

Syntax

HG_Is_HG_Curve(spatial_obj)


Return Type

HG_Is_HG_Curve returns a Boolean value.

Example

This example returns the sw_member of the geometry containing an HG_Curve.

exec sp_spatial_query 'select sw_member from flood100where HG_Is_hg_Curve(sw_geometry)

'


Chapter 20:

HG_Is_InvalidHG_Is_Invalid is used to determine if a curve is invalid. If a curve is invalid, then HG_Is_Invalid returns TRUE.

Syntax

HG_Is_Invalid(spatial_obj)

spatial_obj – An ST_Spatial representing a ST_Polyline.

Return Type

HG_Is_Invalid returns a Boolean value.

Example

insert into geomtest (sw_member, sw_geometry)values (30, 'ST_Spatial(ST_Path(LIST{


}), ST_CircularArc(LIST{


}), ST_Polyline(LIST{


})}))')

exec sp_spatial_query 'select sw_member, HG_Is_Invalid(sw_geometry) from geomtest

'

HG_Is_NulldirHG_Is_Nulldir returns TRUE if the direction property of the input ST_Line is 'NULL'. All ST_Lines have a direction attribute of FORWARD, REVERSE, or NULL.

Syntax

HG_Is_Nulldir(spatial_obj)


User Guide 233

HG_Is_Path

Return Type

HG_Is_Nulldir returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from rdpaved where HG_Is_Nulldir(sw_geometry)

'

HG_Is_PathHG_Is_Path returns TRUE if the input object is an ST_Path.

Syntax

HG_Is_Path(spatial_obj)


Return Type

HG_Is_Path returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from parcel where HG_Is_Path(sw_geometry)

'

HG_Is_PointHG_Is_Point returns TRUE if the input object is an ST_Point.

Syntax

HG_Is_Point(spatial_obj)


Return Type

HG_Is_Point returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member


Chapter 20:

from spotelev where HG_Is_Point(sw_geometry)

'

HG_Is_PolygonHG_Is_Polygon returns TRUE if the input object is an ST_Polygon.

Syntax

HG_Is_Polygon(spatial_obj)


Return Type

HG_Is_Polygon returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from lake where HG_Is_Polygon(sw_geometry)

'

HG_Is_PolylineHG_Is_Polyline returns TRUE if the input object is an ST_Polyline.

Syntax

HG_Is_Polyline(spatial_obj)


Return Type

HG_Is_Polyline returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from rdpavedwhere HG_Is_Polyline(sw_geometry)

'

User Guide 235

HG_Is_Quad

HG_Is_QuadHG_Is_Quad returns TRUE if the input object is an HG_Quad (any four-sided polygon).

Syntax

HG_Is_Quad(spatial_obj)


Return Type

HG_Is_Quad returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from flood100where HG_Is_Quad(sw_geometry)

'

HG_Is_ReverseHG_Is_Reverse returns TRUE if the direction attribute of the input ST_line is set to REVERSE. All ST_Lines have a direction attribute of FORWARD, REVERSE, or NULL.

Syntax

HG_Is_Reverse(spatial_obj)


Return Type

HG_Is_Reverse returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from rdpaved where HG_Is_Reverse(sw_geometry)

'

HG_Is_TriangleHG_Is_Triangle returns TRUE if the input object is an HG_Triangle.


Chapter 20:

Syntax

HG_Is_Triangle(spatial_obj)


Return Type

HG_Is_Triangle returns a Boolean.

Example

exec sp_spatial_query 'select sw_member from flood100where HG_Is_Triangle(sw_geometry)

'

HG_Is_ValidHG_Is_Valid returns TRUE if the geometry is valid, FALSE if it is not. Valid conditions of the different geometries are:

• Polygon – Valid if it is closed and has valid paths.• Path – Valid if it has two or more points and all points are unique.• Polyline – Valid if it has two or more points and all points are unique.• Circular Arc – Valid if it has exactly three points.• Circle – Valid if it has a radius greater than zero.• Point – Always valid.

Syntax

HG_Is_Valid(spatial_obj)


Return Type

HG_Is_Valid returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from lake where HG_Is_Valid(lake.sw_geometry)

'

HG_Is_ZnullHG_Is_Znull returns TRUE if the geometry has NULL z coordinates and FALSE otherwise.

User Guide 237

HG_Level

Syntax

HG_Is_Znull(spatial_obj)


Return Type

HG_Is_Znull returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from spotelev where HG_Is_Znull(sw_geometry)

'

HG_LevelHG_Level returns TRUE if point 1 has the same z coordinate value as point 2.

Syntax

HG_Level(spatial_obj1, spatial_obj2)

• spatial_obj1 – An ST_Spatial representing a three dimensional ST_Point.• spatial_obj2 – An ST_Spatial representing a three dimensional ST_Point.

Return Type

HG_Level returns a Boolean value.

Example

exec sp_spatial_query 'select sw_member from spotelevwhere HG_Level(

spotelev.sw_geometry, ST_Spatial(''ST_Point(1753960.182000, 10698421.103000,

2784.945100)''))

'

ST_Adjacent_ToST_Adjacent_To returns TRUE if two objects touch. They touch if they have one or more common boundary points, but no common interior points. ST_Adjacent_To is identical to ST_Meets.


Chapter 20:


Syntax

ST_Adjacent_To(spatial_obj1, spatial_obj2)


Return Type

ST_Adjacent_To returns a Boolean value.

Example

exec sp_spatial_query 'select rdpaved.sw_member from rdpaved, lakewhere ST_Adjacent_To(rdpaved.sw_geometry, lake.sw_geometry)

'

User Guide 239

ST_Contained_By

ST_Contained_ByST_Contained_By returns TRUE if geometry1 is entirely contained within geometry2, and FALSE if it is not. Boundaries can touch, but the inner object cannot have any points outside the containing boundary.

ST_Contained_By returns the inverse of what ST_Contains returns.

Syntax

ST_Contained_By(spatial_obj1, spatial_obj2)


Return Type

ST_Contained_By returns a Boolean value.

Example

exec sp_spatial_query 'select a.sw_member, b.sw_member from flood100 a, pubbldg b where ST_Contained_By(a.sw_geometry, b.sw_geometry)

'

ST_ContainsST_Contains returns TRUE if geometry1 entirely contains geometry2, and FALSE if it is not. Boundaries can touch, but the inner object cannot have any points outside the containing boundary. See also ST_Contain.


Chapter 20:

ST_Contains returns the inverse of what ST_Contained_By returns.

The following diagram illustrates the behavior of ST_Contains with various geometry combinations. In each of the geometry pairs, the first geometry contains the second. These cases represent the basic combinations that yield a true. Note that points can't contain anything but points. Lines can't contain polygons. In the case of a polygon, boundaries may touch, as long as the interior boundary stays within the exterior boundary.

Syntax

ST_Contains(spatial_obj1, spatial_obj2)


Return Type

ST_Contains returns a Boolean value.

Example

exec sp_spatial_query 'select a.sw_member, b.sw_member from pubbldg a, flood100 b where ST_Contains(a.sw_geometry, b.sw_geometry)

'

ST_EqualsST_Equals returns TRUE if spatial_obj1 is identical to spatial_obj2 (both objects must have the same primitives in the same order).

Note This function returns the same value as HG_Identical.

Syntax

ST_Equals(spatial_obj1, spatial_obj2)

User Guide 241

ST_Meets


Return Type

ST_Equals returns a Boolean value.

Example

exec sp_spatial_query 'select a.sw_member, a.sw_geometry, b.sw_member, b.sw_geometryfrom flood100 a, flood100 bwhere ST_Equals(a.sw_geometry, b.sw_geometry)

'

ST_MeetsST_Meets is the same as ST_Adjacent_To. It returns TRUE if the two objects touch, but do not share common interior points.


Syntax

ST_Meets(spatial_obj1, spatial_obj2)


Chapter 20:


Return Type

ST_Meets returns a Boolean value.

Example

exec sp_spatial_query 'select rdpaved.sw_member from rdpaved, lakewhere ST_Meets(rdpaved.sw_geometry, lake.sw_geometry)

'

ST_Not_EqualsST_Not_Equals returns TRUE if spatial_obj1 is not exactly identical to spatial_obj2 (no tolerance applies).

Syntax

ST_Not_Equals(spatial_obj1, spatial_obj2)


Return Type

ST_Not_Equals returns a Boolean value.

Example

exec sp_spatial_query 'select HG_GetString(pubbldg.sw_geometry)from pubbldg where (ST_Not_Equals(pubbldg.sw_geometry, HG_Box(1,1,2,2)))

'

ST_OutsideST_Outside returns TRUE only if there are no common points between the two objects.

User Guide 243

ST_Overlaps

This function is the opposite of ST_Overlaps.

Syntax

ST_Outside(spatial_obj1, spatial_obj2)


Return Type

ST_Outside returns a Boolean value.

Example

exec sp_spatial_query 'select a.sw_member from lake a, flood100 bwhere ST_Outside(a.sw_geometry, b.sw_geometry)

'

ST_OverlapsST_Overlaps returns TRUE if elements of two geometries overlap. Two elements are overlapping when they share common points. If there are no overlapping elements, then ST_Overlaps returns FALSE. See also ST_Overlap on page 215.

This function is the opposite of ST_Outside.

Syntax

ST_Overlaps(spatial_obj1, spatial_obj2)


Chapter 20:


Return Type

ST_Overlaps returns a Boolean value.

Example

This example does not use the spatial index on the table.

exec sp_spatial_query 'select ST_Overlap(flood100.sw_geometry, lake.sw_geometry)from flood100, lakewhere ST_Overlaps(flood100.sw_geometry, lake.sw_geometry)

'

ST_WithinST_Within returns TRUE if geometry1 is entirely contained within geometry 2, and FALSE if it is not. Boundaries can touch, but the inner object cannot have any points outside the containing boundary.

This is the same as ST_Contained_By.

Syntax

ST_Within(spatial_obj1, spatial_obj2)


Return Type

ST_Within returns a Boolean value.

Example

exec sp_spatial_query 'select rdpaved.sw_member from rdpaved, flood100where ST_Within(rdpaved.sw_geometry, flood100.sw_geometry)

'

User Guide 245

ST_Within


21
User Defined Functions
User Defined Functions (UDFs) created by SpatialWare have been designed to increase the functionality and performance of spatial queries. UDFs have become available with SQL Server 2000 and are provided as an alternative to using sp_spatial_query.

Full SQL Server syntax becomes available when using UDFs instead of sp_spatial_query. Examples are ORDER BY clauses and UPDATE spatial values from x, y coordinates using ST_Point.

Note sp_spatial_query is still required for certain types of spatial functions:

• Indexed spatial joins between tables.• Most spatial functions which return geometries (e.g., ST_Overlap).• Spatial aggregates.

In this section:

UDF Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248Available UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248Table-Valued UDFs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250Geometries as Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254XY Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259

UDF Syntax

UDF SyntaxThe syntax for a UDF is similar to sp_spatial_query, with sp_spatial_query and quotation marks ' ' removed. Where necessary dbo should also be added.

The syntax shown in the Examples for the listed functions in this section uses sp_spatial_query. When using UDFs, this example syntax needs to be changed to get the correct syntax for the equivalent UDF. For example:

exec sp_spatial_query 'select HG_Version() from mapinfo.mapinfo_mapcatalog

'

would need to be changed to the following for UDF use:

select dbo.HG_Version() from mapinfo.mapinfo_mapcatalog

Spatial PredicatesThe following example shows the changes in syntax that need to be made to use a spatial predicate function in UDF format. As it is a spatial predicate, a '1' should be added.

exec sp_spatial_query 'select a.sw_member, b.sw_memberfrom pubbldg a, flood100 bwhere ST_Contains(a.sw_geometry, b.sw_geometry)

'

becomes the following as a UDF:

select a.sw_member, b.sw_memberfrom pubbldg a, flood100 bwhere dbo.ST_Contains(a.sw_geometry, b.sw_geometry) = 1

This is the general format spatial predicates take for UDF usage.

Available UDFsRun the script sw_function_register.sql to create UDFs in each spatial database. All the UDFs have the owner 'dbo'. The functions are defined in the same way as in sp_spatial_query, except the return from spatial predicates must be compared with 0 or 1 in where clauses e.g., '...where st_overlaps(..., ...) = 1'.

The following is a list of available SpatialWare UDFs.

Note The syntax shown in the Examples for the listed functions uses sp_spatial_query. When using UDFs, this example syntax needs to be changed to get the correct UDF syntax for the function.


Chapter 21:

Constructor

These UDFs return values of type varbinary(254), instead of ST_Spatial, but are cast appropriately to the required data type by SQL Server. These particular constructor functions have been implemented because the spatial values returned are guaranteed to be small in their representation. Most spatial functions that return spatial values, such as ST_Overlap, are not available because SQL Server UDFs cannot return values of type image.

General

Measurements

Observer

HG_Box HG_Circle ST_Point

HG_Version

HG_Azimuth HG_Slope_2pts HG_SphericalDistance ST_Area

HG_Azimuth_2pts HG_Slope_Avg HG_SphericalLength ST_Length

HG_Distance HG_Slope_Max HG_SphericalPerimeter ST_Length_3D

HG_Height HG_Slope_Min HG_Width ST_Perimeter

HG_Separation HG_SphericalArea ST_Perimeter_3D

HG_Slope HG_SphericalDist

HG_Begin_Point HG_Llb_Z HG_Ori_X HG_Radius

HG_Cen_X HG_Ncoords HG_Ori_Y HG_Start_Arc_Rot

HG_Cen_Y HG_Ncurves HG_Ori_Z HG_Start_Tangent

HG_Cen_Z HG_Nitems HG_Pointdyn_Ori_X HG_Urt_X

HG_End_Arc_Rot HG_Npaths HG_Pointdyn_Ori_Y HG_Urt_Y

HG_End_Point HG_Npoints HG_Pointdyn_Rot HG_Urt_Z

HG_End_Tangent HG_Npolygons HG_Pointdyn_Xscale ST_X

HG_Llb_X HG_Nsubcurves HG_Pointdyn_Yscale ST_Y

HG_Llb_Y HG_Ori_Rotation HG_PointN ST_Z

User Guide 249

Table-Valued UDFs

Spatial (Indexable)

These can be used with spatial indexing.

Spatial Predicates (Indexable)

These can be used with spatial indexing. Returns 1 for True, 0 for False.

Spatial Predicates (Non-Indexable)

These are never used with spatial indexing. Returns 1 for True, 0 for False.

Table-Valued UDFsThree (3) table-valued UDFs are created whenever an R-tree is created. These UDFs have different types of searching and filtering properties: primary (p), secondary (s), and nearest neighbor (n), known as udf_type.

The three UDFs are based on the udf_type and the values used to create an R-tree table using the sp_sw_create_rtree procedure (Creating an R-Tree Index for a Spatial Table on page 48). The owner of the UDF is the same as the table owner and is therefore not displayed. They take the following form:

table_name#udf_type#spatial_column#udf_type#key_column

HG_SphericalBuffer HG_Centroid HG_Envelope

HG_At_End_Of ST_Adjacent_To ST_Outside

HG_At_Start_Of ST_Contained_By ST_Overlaps

HG_SphericalCircle ST_Contains ST_Within

HG_Connected_To ST_Equals

HG_Identical ST_Meets

HG_Above HG_Is_Closed HG_Is_Path HG_Is_Triangle

HG_Assembled HG_Is_Contiguous HG_Is_Point HG_Is_Valid

HG_Below HG_Is_Forward HG_Is_Polygon HG_Level

HG_Is_Box HG_Is_HG_Curve HG_Is_Polyline

HG_Is_Circle HG_Is_Invalid HG_Is_Quad

HG_Is_CircularArc HG_Is_Nulldir HG_Is_Reverse


Chapter 21:

Example

For table_name 'world', spatial_column 'sw_geometry', and key_column 'sw_member' the three table-based UDFs are:

world#p#sw_geometry#p#sw_member world#s#sw_geometry#s#sw_member world#n#sw_geometry#n#sw_member

Another table-valued UDF, fn_sw_udfs, can be used to get information about the other three table-valued functions.

This section describes each of the UDFs in further detail.

Primary Filtering Filtering returns a table of values for sw_member identifying geometries in a table whose Minimum Enclosing Rectangle (MER) overlaps the MER of a given geometry.

For example, primary filtering returns a table of values for sw_member identifying countries in the World table where the MER of the country overlaps the MER of a given geometry “geo”.

Syntax

table_name#p#spatial_column#p#key_column (geometry, predicate, truth)

• geometry – A geometry. • predicate – A case-insensitive name of an indexable spatial predicate, such as ST_Overlaps, or

st_overlaps.• truth – A boolean (1 or 0) value. This indicates whether the predicate is true (1) or false (0).

Default is 1.

Returns

A table with one (1) column called member.

• member – A column of type integer. This contains all the candidates for which the predicate might have the truth value. The predicate has the truth value for the respective minimum enclosing rectangles (MERs), with a small tolerance. Therefore a primary filter generally returns more rows than the secondary filter. This is because it is looking for candidates only based on the MERs of the geometries, not the exact geometries.

In some cases secondary filtering is unnecessary and primary filtering is much faster. An example where this is true is for window queries when searching for all the geometries overlapping or contained in a rectangular region.

Example

The primary filter UDF for table_name 'world', spatial_column 'sw_geometry', key_column 'sw_member', geometry 'geo', predicate 'ST_Overlaps', and truth '1' is as follows:

world#p#sw_geometry#p#sw_member(geo,'ST_Overlaps',1)

User Guide 251

Secondary Filtering (Refinement)

Secondary Filtering (Refinement)Secondary filtering, or refinement, returns a table of values for sw_member identifying geometries in a table that overlap a given geometry.

For example, secondary filtering returns a table of values for sw_member identifying countries in the World table that overlap a given geometry “geo”.

Syntax

table_name#s#spatial_column#s#key_column# (geometry, predicate, truth)

• geometry – A geometry. • predicate – A case-insensitive name of an indexable spatial predicate, such as ST_Overlaps, or

st_overlaps.• truth – A boolean (1 or 0) value. This indicates whether the predicate is true (1) or false (0).

Default is 1.

Returns

A table with one (1) column called member.

• member – A column of type integer. This contains the candidates for which the predicate has the truth value.

In some cases secondary filtering is unnecessary and primary filtering is much faster. An example where this is true is for window queries when searching for all the geometries overlapping or contained in a rectangular region.

Example

The secondary filter UDF for table_name 'world', spatial_column 'sw_geometry', key_column 'sw_member', geometry 'geo', predicate 'ST_Overlaps', and truth '1' is as follows:

world#s#sw_geometry#s#sw_member(geo,'ST_Overlaps',1)

Nearest NeighborNearest Neighbor returns a table of values for sw_member identifying geometries in a table that are closest to a given geometry.

For example, Nearest Neighbor returns a table of values for sw_member identifying countries in the World table that are closest to a given geometry.

Syntax

table_name#n#spatial_column#n#key_column (geometry, number, ties_tolerance, max_distance, points)

• geometry – A starting geometry, the target from which distances are measured. • number – An integer that specifies how many neighbors to return.


Chapter 21:

• ties_tolerance – A float. If null, the function will return no more than the number of rows specified in number, even if ties exist. If not null, the function will return any tied values within the specified tolerance distance. This may result in more than the number of rows specified in number being returned depending on the number of ties that occur. Default is null.

• max_distance – A float. Specifies a distance giving the maximum limit from the target for which to search for neighbors. If null, no distance is used for the function.

Returns

A table with two (2) columns of type member and distance.

• member – A column of type integer containing the members in the requested set of nearest neighbors. (Distances are defined as with HG_Distance)

• distance – A column of type float containing the distance of the member from the target geometry.

Distances are returned in the coordinate system currently being used.

Example

The nearest neighbor UDF for the table_name 'world', spatial_column 'sw_geometry', and key_ column 'sw_member' is as follows:

world#n#sw_geometry#n#sw_member(geo, number, ties_tolerance, max_distance, points)

fn_sw_udfsThe fn_sw_udfs identifies if an R-tree has been created by the Primary Filtering, Secondary Filtering, or Find Nearest UDF in the system for use. This is registered by the sw_function_register.sql script that registers the other scalar SpatialWare UDFs.

Syntax

fn_sw_udfs(owner, table_name, spatial_column)

• owner – A sysname value. The owner of the base table. • table_name – sysname value. The name of the base table. • spatial_column – A sysname value. The name of the geometry column of type ST_Spatial.

Returns

A row for each of the three UDFs (primary, secondary, and nearest neighbor) which has the columns udf_name, id_column, and udf_type.

• udf_name – Name of the UDF• id_column – The name of the column in the base table that corresponds to the 'member' column

that the UDF returns.• udf_type – 'p', 's', or 'n'

Example

Refer to Example 4 on page 255.

User Guide 253

Geometries as Parameters

Geometries as ParametersWhere a UDF takes a geometry as a parameter, the geometry can be passed in any of three (3) formats:

• SpatialWare blob (HGBlob). E.g., parameter comes from column of type ST_Spatial. • ASCII string. E.g., 'ST_Point(1,1)' • MapInfo blob (MIBlob). E.g., ODBC bound parameter from MapInfo-style client.

ExamplesThis section provides UDF examples:

Example 1 – Primary filtering.

Example 2 – Primary filtering and binding in parameters through ODBC.

Example 3 – Full SQL Syntax, because sp_spatial_query is not used.

Example 4 – The fn_sw_udfs call.

Example 5 – Nearest Neighbor.

Example 6 – An extended Nearest Neighbor query.

Example 1In this example, world#p#sw_geometry#p#sw_member returns the countries for which the Minimum Enclosing Rectangle (MER) of the given geometry overlaps the MER of the country.

The world#s#sw_geometry#s#sw_member UDF will generally return fewer rows for the same parameters. It does the same as world#p#sw_geometry#p#sw_member, but then qualifies the candidates that are returned from the index by evaluating the predicate, e.g., ST_Overlaps. The countries which overlap the given geometry are then returned.

select a.Countryfrom world a, world#p#sw_geometry#p#sw_member

('HG_Box(ST_Point(365268.3232, 6135926.4260), ST_Point(2107447.7323, 6757198.4576))', 'ST_Overlaps', 1) b

where a.sw_member=b.member

This might return:

Country------------------------------RussiaSwedenEstoniaFinlandLatviaNorway(6 row(s) affected)


Chapter 21:

Example 2Large geometries can be bound in as parameters through ODBC, using statements such as:

select member from dbo.world#p#sw_geometry#p#sw_member(?, 'st_overlaps', 1)

Example 3These queries do not involve sp_spatial_query. Therefore full SQL syntax is available. For example order by:

select a.Countryfrom world a, world#p#sw_geometry#p#sw_member

('HG_Box(ST_Point(365268.3232, 6135926.4260), ST_Point(2107447.7323, 6757198.4576))', 'ST_Overlaps', 1) b

where a.sw_member=b.memberorder by a.Country

Results are:

Country------------------------------EstoniaFinlandLatviaNorwayRussiaSweden(6 row(s) affected)

Example 4A call to fn_sw_udfs looks like:

select * from fn_sw_udfs('dbo','world','sw_geometry')

Results are:

(3 row(s) affected)

udf_name id_column udf_type

----------------------------------------------------------------------

WORLD#p#sw_geometry#p#sw_member sw_member p

WORLD#s#sw_geometry#s#sw_member sw_member s

WORLD#n#sw_geometry#n#sw_member sw_member n

User Guide 255

Examples

Example 5This example shows how the nearest neighbor functionality interacts with other conditions in the where clause.

To get the 10 nearest capital cities to Nairobi, do the following:

select a.Capital, a.Country, a.Cap_Pop, b.distancefrom worldcap a, worldcap#n#sw_geometry#n#sw_member

('ST_Point(3475802.512194563600,-136011.500702377120)', 10, default, default, default) b

where a.sw_member=b.memberorder by b.distance

Results are:

(10 row(s) affected)

To combine this with the condition that the population be at least 100000, execute:

select a.Capital, a.Country, a.Cap_Pop, b.distancefrom worldcap a, worldcap#n#sw_geometry#n#sw_member

('ST_Point(3475802.512194563600,-136011.500702377120)', 10, default, default, default) b

where a.sw_member=b.member and a."Cap_Pop" >= 100000order by b.distance

Capital Country Cap_Pop Distance

-----------------------------------------------------------------------

Nairobi KENYA 959000 0.0

Kampala UGANDA 773000 433488.64427111577

Dar es Salaam TANZANIA 1400000 635005.59863927646

Kigali RWANDA 232000 641736.70612508489

Bujumbura BURUNDI 240000 740054.98858213075

Mogadishu SOMALIA 700000 880055.20380446082

Addis Ababa ETHIOPIA 1423111 1113998.72935387

Moroni COMOROS 30000 1258940.9112791258

Lilongwe MALAWI 220000 1395416.404985491

Djibouti DJIBOUTI 290000 1491105.9696445295


Chapter 21:

Results are:

(9 row(s) affected)

Moroni, COMOROS has a population of only 30000. Notice that only 9 rows are returned. The query does NOT get all the capital cities with population at least 100000 and find the 10 nearest to Nairobi from these. It actually returns the 10 nearest capital cities to Nairobi and eliminates those with population less than 100000.

Example 6Example 5 assumed that we knew the coordinates of the target (Nairobi) already. This example finds the 5 nearest neighbors to the capital of Bolivia, excluding Bolivia's capital itself, without this kind of assumption:

declare @target varbinary(254) /* large enough to hold a binary representation of a point */select @target = sw_geometry from worldcap where Country = 'Bolivia'select a.Capital, a.Country, a.Cap_Pop, b.distancefrom worldcap a, worldcap#n#sw_geometry#n#sw_member(@target, 6, default,

default, 'points') bwhere a.sw_member=b.member and a.Country != 'Bolivia'order by b.distance

Results are:


--------------------------------------------------------------------

Nairobi KENYA 959000 0.0

Kampala UGANDA 773000 433488.64427111577

Dar es Salaam TANZANIA 1400000 635005.59863927646

Kigali RWANDA 232000 641736.70612508489

Bujumbura BURUNDI 240000 740054.98858213075

Mogadishu SOMALIA 700000 880055.20380446082

Addis Ababa ETHIOPIA 1423111 1113998.72935387

Lilongwe MALAWI 220000 1395416.404985491

Djibouti DJIBOUTI 290000 1491105.9696445295


------------------------------------------------------------------

Lima PERU 5826000 990280.17198354041

User Guide 257

XY Columns

This query could also be performed as follows, but the query does not use spatial indexing and is suitable for smaller tables only.

select top 5 b.Capital, b.Country, b.Cap_Pop, dbo.HG_Distance(a.sw_geometry, b.sw_geometry) distance

from worldcap a, worldcap b where a.Country = 'Bolivia' and b.Country != 'Bolivia' order by distance

XY ColumnsIn some cases you may decide to store points in 2 float columns in a table. How you use these components in your syntax may impact the efficiency of a query. The following examples illustrate this concept.

Example 1In this example, assume that columns x and y of the xy_tab table store coordinates. This statement tests whether these points are contained in geometries from another table.

select s.sw_member, xy.x, xy.yfrom st_spatial_tab s, xy_tab xywhere dbo.st_contains(s.sw_geometry,

dbo.ST_Point(xy.x, xy.y))=1

The following syntax is less elegant, but may be more efficient in some cases.

select s.sw_member, xy.x, xy.yfrom st_spatial_tab s, xy_tab xywhere dbo.st_contains(s.sw_geometry,

'st_point(' + str(xy.x,20,8) + ',' + str(xy.y,20,8) + ')')=1

Note The STR function has the format, STR ( float_expression [ , length [ , decimal ] ] ). For example, STR(xy.x, 10,3).

Example 2This second example shows a table-valued UDF, which is similar to the SpatialWare #s# functionality. It returns a row for each point in xy_tab, contained by a given ST_Spatial. For performance reasons, SQL Server indexes should be created on the x and y columns. The example illustrates the use of str(xy.x) to increase the efficiency of the query.

Asuncion PARAGUAY 607000 1422603.8170951544

Santiago CHILE 5300000 1815945.4828863281

Brasilia BRAZIL 1576657 1885918.3629935503

Quito ECUADOR 1500000 2037285.8666228096


Chapter 21:

CREATE FUNCTION xy_tab#s#x#s#y#s#sw_member#s#contains#s#1(@geo ST_Spatial) RETURNS @points TABLE(x float, y float) AS BEGIN DECLARE @mer_llx FLOAT DECLARE @mer_lly FLOAT DECLARE @mer_urx FLOAT DECLARE @mer_ury FLOAT DECLARE @ret INTEGER SELECT @mer_llx=dbo.HG_Llb_X(@geo), @mer_lly=dbo.HG_Llb_Y(@geo), @mer_urx=dbo.HG_Urt_X(@geo), @mer_ury=dbo.HG_Urt_Y(@geo) FROM master.dbo.HG_OneRow INSERT INTO @points(x, y) SELECT xy.x, xy.y FROM xy_tab xy WHERE (xy.x BETWEEN @mer_llx AND @mer_urx) AND (xy.y BETWEEN @mer_lly AND @mer_ury) AND dbo.st_contains(@geo, 'st_point(' + str(xy.x,20,8) + ',' + str(xy.y,20,8) +

')')=1 RETURN END

Note The STR function has the format, STR ( float_expression [ , length [ , decimal ] ] ). For example, STR(xy.x, 10,3).

Notes

Parameters from ColumnsThe usage of table-valued UDFs is somewhat limited, in that they cannot accept parameters which come from columns or function evaluation.

The following is not a valid query, and returns a syntax error:

select member from world#s#sw_geometry#s#sw_member('ST_Point' + '(0,0)', 'st_overlaps', 1)Server: Msg 170, Level 15, State 1, Line 1Line 1: Incorrect syntax near '+'.

This is a valid version (but does not use spatial indexing):

select sw_member from world where dbo.st_overlaps('ST_Point' + '(0,0)', 'ST_Point(0,0)') = 1

Error-HandlingUDFs have very restricted error-handling mechanisms. SpatialWare UDFs force divide-by-zero errors when they detect problems. If this happens, it may be necessary to do an equivalent query using sp_spatial_query.

User Guide 259

Notes

PredicatesWhere predicate is used as a parameter, the parameters to the predicate are given in the order indicated by 'predicate'('geocol', 'geo'). For example for:

select a."Country"from world a, world#s#sw_geometry#s#sw_member

('HG_Box(ST_Point(365268.3232, 6135926.4260), ST_Point(2107447.7323, 6757198.4576))', 'ST_Contained_By', 1) b

where a.sw_member=b.member

The predicate is satisfied if:

ST_Contained_By(world.sw_geometry,'HG_Box(ST_Point(365268.3232, 6135926.4260), ST_Point(2107447.7323, 6757198.4576))') = 1

Maximizing Performance

To maximize performance when using indexing UDFs it is important to pay attention to the query execution plans that SQL Server generates.

If there is a very restrictive non-spatial condition together with a spatial predicate, it is preferable not to use indexing UDFs.

Consider the two (2) queries that follow:

select a."Country" from world awhere a."Country" like 'S%' and dbo.st_overlaps('HG_Box(ST_Point(10.0, 10.0),

ST_Point(40.0, 40.0))', a.sw_geometry) = 1select a."Country"from world a, world#s#sw_geometry#s#sw_member('HG_Box(ST_Point(10.0, 10.0),

ST_Point(40.0, 40.0))', 'ST_Overlaps', 1) bwhere a.sw_member=b.member and a."Country" like 'S%'

From a performance perspective the first example is preferable. This is because the non-spatial condition is much more restrictive than the spatial predicate, and the spatial predicate is executed only for the few rows satisfying the non-spatial condition.

Note For sp_spatial_query usage notes and caveats please refer to Chapter 23: Usage and Caveats under the Reference section.


Part 4: References

Topics:

Troubleshooting and Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Usage and Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Importing Data with EasyLoader. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Conversion Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Understanding Coordinate Systems and Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Transformation Calculation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Coordinate Transformation Reference Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

22
Troubleshooting and Tips
This chapter contains troubleshooting notes.

In this chapter:

The Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265

The Database

The DatabaseThis section discusses the following topics (listed in alphabetical order):

• "A cursor with the name ... already exists" – Recursive Triggers• Message Log File• Size and Quantity Limits

"A cursor with the name ... already exists" – Recursive TriggersEvery spatial database must have its "Recursive triggers" setting turned OFF.

In SQL Server 2000 this can be managed through Enterprise Manager, by selecting a database and following Properties > Options > Settings. (If you are using SQL Server 2005 or 2008, refer to the online help for Management Studio.) If this setting is on, you can expect some insert and update operations to fail with the message:

"A cursor with the name ... already exists."

Or

"Maximum stored procedure nesting level exceeded..."

Message Log FileSpatialWare for SQL Server exposes a server-side log containing information on errors and exceptions. This log file is located in the log subdirectory under the directory where you have installed SpatialWare (i.e., %SW_ROOT%\log).

The log file contains useful details on the errors generated by low-level spatial operations. For example, should you get an error message to the effect that an ST_Overlap operation failed, the log file may contain more details on the reasons.

We recommend that the database administrator monitor the use and size of the log file. You may want to either truncate or archive the log file occasionally to prevent it from growing too large.

Size and Quantity LimitsYou need to be aware of the following maximum sizes and limitations:

• Absolute maximum number of connections to a database library is 16000.• Currently, the maximum number of simultaneous connections to a database server using

SpatialWare is 16000. This is the number of users that can simultaneously access the database server using either sp_spatial_query, any of the spatial triggers, or extended stored procedures such as sp_sw_create_rtree. Note that your licensing and installation parameters, or the resources on your machine can restrict you to a smaller number.

• Maximum size of geometry blobs and strings is 1 GB.• Maximum size of the query passed into sp_spatial_query is 8000 characters.• Maximum number of tables in a join statement is ten.


Chapter 22:

SQL ServerThis section discusses the following topics:

• Invalid Geometry Detected• Minor Limitations on SpatialWare Functionality• Query Analyzer• SQLServer Column not found: OBJECT• Syntax error detected at line 1: syntax error at '(' – (AND)NOT Keywords• The definition for column 'm' must include a data type• Updating and Security

Invalid Geometry DetectedAn error message of the form of "Invalid geometry detected" may occur when inserting, or updating, an invalid geometry in a spatialized column. The resulting row will have a NULL value in that column. For example, the following string is missing the ’t’ value in st_point:

insert into t(sw_member, sw_geometry) values (10000,'st_poin(1,2)')

The resulting table has a row with sw_member equal to 1000 and sw_geometry NULL.

Minor Limitations on SpatialWare FunctionalitySpatialWare for SQL Server uses the extended stored procedure mechanism; this imposes a few limitations on SpatialWare functionality. Some of these are described below. For more information on extended stored procedures and the DB library, refer to the documentation of your version of SQL Server, or the URL http://msdn.microsoft.com.

Client side programmers (who may be using ODBC or Transact-SQL directly) should take note that SQL Server extended stored procedures use the default result sets to return result sets. Only one such cursor can be open at a time for each connection.

You cannot access row sets generated by spatial queries directly using T-SQL.

Query AnalyzerWhen running SpatialWare scripts in SQL Server 2000’s Query Analyzer, you may receive the following error message if the Output Query check box is selected under Query > Current Connection Options > Advanced:

-----------------------------*/Server: Msg 113, Level 15, State 1, Line 6Missing end comment mark '*/'.

The Output Query option tries to execute all script lines, even commented lines, and should not be set for SpatialWare scripts that contain comments.


User Guide 265

http://msdn.microsoft.com

SQL Server

SQLServer Column not found: OBJECTIf you get the following error message on a query submitted via the MapInfo Expert dialog or MapBasic script, then try using the fully qualified SW_GEOMETRY reference in place of the OBJECT reference.

Error: SQLServer Column not found: OBJECT

For example, instead of using the general spatial column identifier 'OBJECT' without any additional qualifications:

select OBJECT,WORLD.SW_MEMBER from WORLD,WORLDCAPwhere WORLD.COUNTRY=WORLDCAP.COUNTRY

Use the fully qualified form:

select WORLD.SW_GEOMETRY,WORLD.SW_MEMBERfrom WORLD,WORLDCAP where WORLD.COUNTRY=WORLDCAP.COUNTRY

If the qualified query succeeds, you should check if the table is correctly registered in the MAPINFO_MAPCATALOG.

Syntax error detected at line 1: syntax error at '(' – (AND)NOT KeywordsIt is possible (though not very common) in the MapInfo Professional 'Open DBMS Table' Wizard to specify a spatial (AND) NOT condition. This produces a combination of brackets that SpatialWare will reject. You may see an error like:

Syntax error detected at line 1: syntax error at '('

It is possible to define an (AND) NOT condition successfully by using the Expert dialog, as, for example, in the following statement:

select "Capital", "State_Name", "sw_member", "MI_SYMBOLOGY", "SW_GEOMETRY"from "SQLTest"."dbo"."MX_CAPS" where ((ST_OVERLAPS( SW_GEOMETRY, ST_Spatial('' HG_BOX( ST_POINT(-108.69536880,21.03210000), ST_POINT(-92.68909920,29.87987400) ) '')))) and not ST_OVERLAPS( SW_GEOMETRY, ST_Spatial('' HG_BOX( ST_POINT(-104.23466600,21.03210000), ST_POINT(-100.82398300,25.11666900) ) ''))


Chapter 22:

The definition for column 'm' must include a data typeIf you use the "select ... into ..." construct in sp_spatial_query, and you have a literal in the select list, it will fail. For example, the following statement:

select 101 as m into tab2 from tab1

will return the following error:

Server: Msg 173, Level 11, State 1, Line 0The definition for column 'm' must include a data type.

Updating and SecurityColumn permission checks from the client applications are done at commit time (when data is saved back to the server database). If a column does not have the permissions for a particular user to update it, the following message is displayed:

'Update permission denied on column 'col_name' of object 'TABLENAME', database 'DB_NAME' owner 'owner_name' Operation cancelled.

Inserting Spatial Data – Unterminated stringPlease make sure that spatial strings (i.e., parameters to ST_Spatial( )) do not include newline characters. This can happen inadvertently when using the SQL Server 2000 Query Analyzer or the SQL Server 2005/2008 Management Studio. If this occurs, then an "Unterminated string" error will result.

Expert Dialog – Additional RulesQueries submitted via the MapInfo Expert dialog box or a MapBasic script may either use the column name SW_GEOMETRY in fully qualified form (preferred):

select WORLD.SW_GEOMETRY,WORLD.SW_MEMBERfrom WORLD,WORLDCAP where WORLD.COUNTRY=WORLDCAP.COUNTRY

Or may use the MapInfo Professional general spatial column identifier 'OBJECT' without any additional qualifications:

select OBJECT,WORLD.SW_MEMBER from WORLD,WORLDCAPwhere WORLD.COUNTRY=WORLDCAP.COUNTRY

You may get the following error message:

Error: SQLServer Column not found: OBJECT

If so, try using the fully qualified SW_GEOMETRY reference in place of the OBJECT reference.

User Guide 267

SQL Server

Performing Spatial Database QueriesThe following are a few tips to keep in mind when performing spatial database queries using either the Expert dialog in MapInfo Professional or a custom MapBasic program:

• The Expert dialog attempts to add the sp_spatial_query prefix, where appropriate, and encloses the query in quotes so it is not necessary to add the sp_spatial_query prefix in the Expert Query dialog.

• If you have strings within the query, you don't have to escape the string using two single quote ( ' ) characters instead of one. The Expert dialog performs this automatically. For example:select sw_member from rdpaved where rdname like 'GLENN%'

Note that the string in the where clause is 'GLENN%' and not ''GLENN%''.

Spatial Select and LiteralsIf you use the "select ... into ..." construct in sp_spatial_query, and you have a literal in the select list, it will fail. For example, the statement

exec sp_spatial_query ' select 101 as m into tab2 from tab1'

Returns the error:

Server: Msg 173, Level 11, State 1, Line 0

The definition for column 'm' must include a data type.


23
Usage and Caveats
This section contains usage notes and caveats for SpatialWare running with SQL Server.

In this section:

Using Indexes in an sp_spatial_query . . . . . . . . . . . . . . . . . . . . .270Uploading Transactional Data. . . . . . . . . . . . . . . . . . . . . . . . . . . .271Using Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271Using Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272Using the sp_spatial_query Stored Procedure . . . . . . . . . . . . . .272Using Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273

Using Indexes in an sp_spatial_query

Using Indexes in an sp_spatial_queryWhen you perform a search for geometries in spatial queries, indexes may be used to speed up the search. Examples for search include fetching all geometries within a given region, or joining two tables with indexable spatial predicates to determine all tuples that overlap. For a spatial join to use a spatial index on a table, the other table in the join must at least be spatializable.

The following is the list of indexable spatial predicates (i.e., spatial indexes are used for search if one of the following predicates is used in the WHERE clause of a select statement in sp_spatial_query):

The following examples illustrate how SpatialWare determines the index usage in sp_spatial_query.

A Simple Window Query

In the following example, the spatial index on the sw_geometry column of flood100 table is used.

exec sp_spatial_query 'select sw_member, sw_geometry from flood100 where ST_Overlaps(sw_geometry,

HG_Box(1756600,10703200, 1755500,10702500))'

A Qualified Window Query

In the following example, the spatial index on the sw_geometry column of flood100 table is used, and the rows that do not satisfy the clause sw_member < 2 are filtered out.


HG_Box(1756600,10703200, 1755500,10702500)) and sw_member < 2'

A variation of the above query, using the optional argument to switch spatial filtering off, so that we force the evaluation of the attribute condition first.


HG_Box(1756600,10703200, 1755500,10702500)) and sw_member < 2', FALSE

A Simple Join Query

In the following example, the index on parcel.sw_geometry and the index on flood100.sw_geometry are both used. It finds all the parcels that overlap with any of the flood zones.

HG_At_End_Of HG_Centroid ST_Adjacent_To ST_Meets

HG_At_Start_Of HG_Connected_To ST_Contained_By ST_Outside

HG_SphericalBuffer HG_Envelope ST_Contains ST_Overlaps

HG_SphericalCircle HG_Identical ST_Equals ST_Within


Chapter 23:

exec sp_spatial_query 'select a.sw_member, b.sw_member from parcel a, flood100 bwhere st_overlaps(a.sw_geometry, b.sw_geometry)

'

A Join Query with Attribute Qualifications

As a general rule, pass the geometry column of large tables (or tables where you need the spatial selectivity the most) as the first argument to the spatial predicate.

In the first example, the index on parcel.sw_geometry is used, and the clause b.sw_member = 1 is used as a pre-processor to qualify the geometries that are searched against the index on parcel. The example finds all the parcels that overlap with one particular flood zone:

exec sp_spatial_query 'select a.sw_member from parcel a, flood100 bwhere st_overlaps(a.sw_geometry, b.sw_geometry) and b.sw_member = 1

'

In this example, the index on flood100.sw_geometry is used, and the attribute condition b.sw_member = 1 is used as a way to filter out some of the rows returned by the primary spatial join. The example finds all the parcels that overlap with one particular flood zone:

exec sp_spatial_query 'select a.sw_member from parcel a, flood100 bwhere st_overlaps(b.sw_geometry, a.sw_geometry) and b.sw_member = 1

'

Note that both the examples above return the same results. The first query is more efficient. The second one is provided to highlight a possible alternative.

Uploading Transactional DataIf an application inserts a batch of records at once into a spatialized/indexed table (rather than one record at a time, in a transactional manner), the performance will be significantly better.

Using ViewsThere are several things to note about views:

1. The SQL Server "create view" knows nothing of SpatialWare; hence, no spatial predicates, for example, can be used in the view definition. However, "spatial" columns can be in the view definition, SQL Server thinking of them as merely "image" type.

2. sp_sw_spatialize_column, and similar SpatialWare stored procedures, will not accept view names as parameters, where base table names are expected.

3. Spatial queries can refer to spatial columns of views, and will give correct results, but will not use spatial indexes, meaning lower levels of performance as compared to base tables.

These limitations may be removed in a future release.

User Guide 271

Using Coordinate Systems

Three Way JoinsAlthough it is not possible to use a spatial index when handling a query involving a view, a select using a view can often be re-expressed as a three way join. In this way it is possible to use the spatial index.

For example a query of the type:

select v.sw_geometry, v.xxxx,......, v.yyyy, c.zzzz........ from v,cwhere st_overlaps(v.sw_geometry, c.sw_geometry)

where:

• v – A view that is specified as containing table a.sw_geometry, a.xxxx and b.yyyy with the join criteria being a.id = b.id

This can be re-expressed by breaking out the columns of the view definition to make use of the spatial index:

select a.sw_geometry, a.xxxx,....... b.yyyy, c.zzzz........ from a,b,cwhere st_overlaps(a.sw_geometry,c.sw_geometry) and b.id = a.id

Using Coordinate SystemsYou must know what coordinate system that your data is in. SpatialWare for SQL Server does not currently support mixed coordinate systems in a table. Therefore, your table should be in a single coordinate system. Data imported into your database should be in the same coordinate system. If it is not, you must take steps to transform it to the same coordinate system as the data in your database.

Using the sp_spatial_query Stored ProcedureThe following notes are specific to the use of the sp_spatial_query stored procedure, and detail certain limitations in syntax. UDFs provide an alternative if you encounter these limitations (refer to Chapter 21: User Defined Functions).

Note In SQL Server you can not use TEXT and IMAGE values in a Transact SQL script.

Grammar and UsageThe grammar for the SQL select statement you cannot have spatial predicates in the select list, or spatial functions in the where clause. For example, the following queries are not expected to work in this release:

exec sp_spatial_query ' select HG_Is_Polygon(sw_geometry) from parcel'exec sp_spatial_query ' select sw_geometry from parcel


Chapter 23:

where ST_Area(sw_geometry)>10'

However, you can use a spatial function in a where clause if it is called by a spatial predicate. For example, the following includes a spatial function in a where clause:

...where st_overlaps(a.sw_geometry, st_buffer(b.sw_geometry, 100.0, 0.0))

This is allowed because it is embedded in a spatial predicate.

Note Ensure that spatial strings (i.e., parameters to ST_Spatial( )) do not include newline characters. This can happen inadvertently when using the SQL Server 2000 Query Analyzer or the SQL Server 2005/2008 Management Studio. If this occurs, then an "Undetermined string" error will result.

Use of SQL Server FunctionsYou can not use SQL Server functions (mathematical, string, or otherwise) with sp_spatial_query if you are calling a spatial predicate. For example, the next statement will fail, because it is using a mathematical function and calls the spatial predicate ST_Overlaps:

exec sp_spatial_query ' select cos(sw_member) from test1 where st_overlaps( sw_geometry, st_buffer(st_spatial(''ST_Point(-95,55)''),10,1) )'

You can perform this in two steps, refer to the example under Saving the Results of a Query Into A Table for the use of a global temporary table.

Table JoinsYou can use no more than ten tables in a join within an sp_spatial_query.

Using AliasesThe following notes are specific to the use of aliases with the sp_spatial_query stored procedure.

exec sp_spatial_query ' select sw_member as sw_member ,hg_cen_x(sw_geometry) as cenx from test1 where st_overlaps( sw_geometry, st_buffer(st_spatial(''ST_Point(-95,55)''),10,1) )'

You can also use aliases with an INTO statement:

exec sp_spatial_query '

User Guide 273

Using Aliases

select sw_member as aa ,hg_cen_x(sw_geometry) as cenx into test2 from test1 where st_overlaps( sw_geometry, st_buffer(st_spatial(''ST_Point(-95,55)''),10,1) )'


24
Examples
This chapter highlights spatial examples.

In this section:

Updating the ST_Spatial Column From Longitude Latitude Values276

Updating the ST_Spatial Column From Longitude Latitude Values

Updating the ST_Spatial Column From Longitude Latitude ValuesThis statement updates the ST_Spatial column of a table from the longitude latitude values. To do this you would:

1. Alter the table to add columns (sw_member integer not null unique), and (sw_geometry st_spatial); you can use the SQL Server 2000 Query Analyzer or the SQL Server 2005/2008 Management Studio to do this. The following example alters an existing table to add a key column called SW_MEMBER and a geometry column called SW_GEOMETRY to it. alter table table1 ( sw_member integer not null unique, sw_geometry st_spatial)

2. Spatialize the SW_GEOMETRY column. To do this use the sp_sw_spatialize_column procedure. For example, in the SQL Server 2000 Query Analyzer or in the SQL Server 2005/2008 Management Studio, type the following with appropriate parameters: exec sp_sw_spatialize_column '<owner>', '<table_name>', '<spatial_column>', '<key_column>', '<storage>'

The storage value should be set to primary. For example:exec sp_sw_spatialize_column 'dbo', 'table1', 'sw_geometry', 'sw_member', 'primary'

3. The trigger to handle string to blob conversion should be set up now for the SW_GEOMETRY column. Update the column with the string constructor for the point, for example: update table1 set sw_geometry = 'ST_Point( ' + cast (longitude as varchar(40)) + ', ' + cast (latitude as varchar(40)) + ')'

For more information on how to create a spatial table, refer to Data Definition under Concepts.


25
Importing Data with EasyLoader
EasyLoader is a utility available from MapInfo Corporation that allows you to upload MapInfo TAB files to a remote database, such as Microsoft SQL Server. EasyLoader runs on Microsoft Windows. The spatial information in the TAB files is maintained in the SQL Server database and is available for viewing and analyzing in MapInfo Professional.

In this section:

About EasyLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278Running EasyLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278Uploading MapInfo TAB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . .279Using the EasyLoader Interface . . . . . . . . . . . . . . . . . . . . . . . . . .279Using the EasyLoader Commandline. . . . . . . . . . . . . . . . . . . . . .281Combining the Commandline with the Interface. . . . . . . . . . . . .286

About EasyLoader

About EasyLoaderEasyLoader is useful for automating loading or replacing data on the server. The EasyLoader upload process will:

• Create spatial columns and indexes that are required for SpatialWare. • Add an entry to the MAPCATALOG for each uploaded table (required). • Provide options for how you wish the table to be processed. • SpatialWare assumes that the name of the geometry column is SW_GEOMETRY. This is also

the name that EasyLoader uses to create the column.

EasyLoader can upload tables to SQL Server containing points, lines, polygons and text objects. Ellipses, arcs and rounded rectangles are not supported.

Using EasyLoader with SpatialWareIt is recommended that you automatically update the SW_MEMBER column of a table when using EasyLoader to import data.

In EasyLoader you should select the IDENTITY option, underneath the Options tab. Using an IDENTITY attribute on the column automatically updates the SW_MEMBER column each time a new row is inserted. This is an ease of use feature that frees you from having to assign a unique key value for each new row. SQL Server will automatically assign a unique value.

Running EasyLoaderEasyLoader runs as a standalone program by using the easyloader.exe executable file. It can also be run as a commandline utility by using its commandline arguments.

EasyLoader is available as a download from the MapInfo website (www.mapinfo.com).

You can run EasyLoader on a remote machine running Windows 98 or later.

Running from a MapInfo Professional ClientEasyLoader can be run from within MapInfo Professional.

PermissionsTo upload data to SQL Server via EasyLoader, you must have privileges to create and update tables on the database in which the new table will be created. You also need permission to update the MAPINFO_MAPCATALOG, a registry table containing metadata about spatial data. If you are using EasyLoader to initially create the MAPCATALOG, you will need permission to create a new user, MAPINFO, which is the user that will own the MAPCATALOG.


Chapter 25:

About the MAPINFO_MAPCATALOGThe MAPINFO_MAPCATALOG is a registry table for databases that stores metadata about geometry tables in the database. Using the tablename and ownername as the key, the MAPINFO_MAPCATALOG identifies the geometry column, geometry type, projection, projection bounds, and table and feature level style information. The MAPINFO_MAPCATALOG is used by a number of MapInfo products that access map data from databases, including MapInfo Professional for SQL Server. If a MAPCATALOG does not exist for a spatial database, it can be created during the upload process when running EasyLoader.

After the table is uploaded, an entry is made in the MAPINFO_MAPCATALOG to represent that table. A separate entry is made for every table you upload.

Uploading MapInfo TAB FilesTo upload MapInfo TAB files using EasyLoader:

1. Run EasyLoader.From MapInfo Professional, run EasyLoader from the MapInfo Professional Tools menu. If necessary, run Tool Manager to load and/or autoload EasyLoader onto the Tools menu. From a machine which does not have MapInfo Professional installed, double click the file EasyLoader.exe. The main EasyLoader dialog displays.

2. Under Connection Information, click the ODBC button to connect your SQL Server database. Provide the necessary connection information (e.g., data source name or User ID, password and server name). Click OK to return to the EasyLoader dialog box.

3. Click the Source Tables button to display a list of MapInfo tables from a single directory. When tables are selected for uploading, the names will display in the MapInfo Tables list box.

4. Choose the tables and select the appropriate Server Table processing task (Create new table, Append to existing table, Replace existing Table). These and additional options are explained in the Options section. The Upload button is not available until table(s) are chosen.

5. To set options for the upload process, click the Options button. The Options dialog will display. Click OK to return to the main EasyLoader dialog.

6. Click the Upload button to start the upload process. Close EasyLoader once the upload process is finished.

If you have not already created the Spatial Index during the upload process, do so now by either executing a create index statement or re-uploading the table, making sure this time to create the Spatial Index and replace the table (see steps 1-3).

Using the EasyLoader InterfaceThere are two dialogs of information: Main and Options. Under the Main dialog you can create, replace, or append to a table. You also have the option of appending to all tables. The Options dialog lets you set the spatial object type and server table processing options.

User Guide 279

Using the EasyLoader Interface

Main Dialog

Creating a New Table

A server table will be created with the name that you specify. If this option is chosen and a table with the same name already exists on the server, an error message with display, making you aware of this problem. You will need to use a different name or choose the option: Replace Existing Table, in order to upload the table.

Replacing an Existing Table

If a server table of the same name already exists, it will be dropped and a new table will be created to match the MapInfo table being uploaded when this option is selected.

Appending to an Existing Table

The MapInfo table will be appended to the server table if the server table exists and the structure of the two tables match. Otherwise, you will get an error and the table will not be uploaded.

Appending All to One Table

All MapInfo tables listed are uploaded to a single server table. The server table name is the one visible in the Server Table box. This feature is meant to be used to upload tables with the same structure and projection to one table. For example, instead of creating a new table for each street layer, check the Append All to One box, and only one table will be created. All of the tables will then be appended to this table. It is possible that some tables will not be appended if their structure differs. When this option is used with the Replace Table option, the server table will be dropped, a new table will be created, and all tables listed will be appended to that one. When used with the Create Table options, the server table will be created, and all tables listed will be appended to that one. All tables MUST have the same table structure and be in the same projection.

Options Dialog

Spatial Object Type

Choose MapInfo SpatialWare, MICODE (XY with Key), and XY. The default for loading spatial data is MapInfo SpatialWare, the spatial object type is MapInfo SpatialWare.

• MapInfo SpatialWareTo select this option, the server must have MapInfo SpatialWare installed. Tables will be uploaded as spatial data.

• XY and XY with MapInfo key (MICODE)Use this option if the server does not have MapInfo SpatialWare installed. The data will be stored as xy coordinates on the server. Therefore, the server table will be created as a point table. If the MapInfo table to be uploaded is not a point table and this option is chosen, the centroid will be abstracted and stored on the server table if you instruct it to do so. The difference between XY and MICODE is that the MICODE will provide a MapInfo key as the spatial index, hence its performance is superior to XY.


Chapter 25:

Server Table Processing

The following describes the table processing portion of the Options Dialog.

• Exclusive Use of TableYou can potentially speed up load time on large tables significantly in a multi-user environment if you know that you will be the only one attempting to update/upload the table. By NOT checking this option, the loader will verify after each commit that no other updates are made to the table while it is being uploaded. Checking this option will prevent this check from occurring which can make a significant change to the run time for large tables.

• Grant Public Access to TablePUBLIC is granted all access to the server table.

• Create Spatial IndexFor SpatialWare tables the index is created on the geometry column. A spatial index is created and Update Statistics is executed after an r-tree index is created. You may also build your own spatial index to suit your specific needs. If you choose to do this, clear this check box to save time in loading.

• Create Unique IndexA unique index is created on the column SW_MEMBER for SpatialWare. These columns are sequential numbers that are generated by the loader. These columns are always created, but do not have to be indexed.

• Create IDENTITY Column (SQL Server only)Check this box if you wish to create the key column (sw_member) with IDENTITY properties. When this feature is in use, the unique key column values will be generated automatically by SQL Server. You do not need to fill in the key manually when a new row is inserted. In version 7.0, the key column (sw_member) is created with IDENTITY property by default, which is the opposite behavior from the previous version (6.8). To upload the table without IDENTITY, select the Options button and uncheck Create IDENTITY Column.

• Style ColumnThis allows you to specify that per-row symbology is to be loaded with the data. The symbology is loaded as a text string in the column specified. The name of the column to be used may be specified in the edit text box. The name is initialized to the default column name, which is MI_STYLE. To load per-row symbology, the MAPINFO_MAPCATALOG for the database must contain the following columns RENDITIONTYPE, RENDITIONCOLUMN, RENDITIONTABLE, and NUMBER_ROWS.

Using the EasyLoader Commandline The EasyLoader commandline uses a series of flags to set options. This section describes these flags, which are:

• /A Append all Tables to One• /D Server Create Table• /E Exclusive Use of Table• /F Log File Name• /G Grant All• /I DO NOT Create a Spatial Index• /K Create Automated Key Column for SQL Server

User Guide 281

/A Append all Tables to One

• /L List of MapInfo Tables• /M MICODE/XY• /O Connection String• /P ACR• /Q Quit• /R Replace the Server Table• /U DO NOT Create a Unique Index• /T MapInfo Table Name;Server Table Name;Range• /V Oracle Version• /X Commit Interval• /Y Symbology Column Name

/A Append all Tables to OneThis flag allows multiple tables to be uploaded to a single table as long as the table structures are the same.

Syntax:

/A

/D Server Create TableGenerates TAB files to access remote DBMSs when you provide the TAB file directory. By default, EasyLoader will not generate these files. The newly generated TAB file is the Server Table Name plus _srv.TAB. The directory must be a valid directory to upload a table. Empty is treated as valid.

The commandline option is /D Pathname.

Syntax:

/D "C:\tabfiles"

/E Exclusive Use of TableYou can speed up load time on large tables significantly if you know that you will be the only one attempting to update the table. Note however, that specifying this flag does not guarantee that the loader will obtain exclusive use, you must guarantee that to the loader. The loader checks on the current maximum value of the key column (prinx) after each commit to ensure that it detects any other entries that may have been made by other processes. This flag will prevent that check from occurring, which can make a significant change to the run time for large tables.

This flag may be placed within a shortcut, allowing the interactive use of the Loader interface for other functions.

Syntax:

/E


Chapter 25:

/F Log File NameThe log file is always produced, this flag lets the user specify a log file name and location. EasyLoader.log is the default name and it will be created in the temp directory. If no path is provided, the log will be created in the same directory as the EasyLoader.exe file.

Syntax:

/F myLogFile.txt /F c:\temp\myLogFile.txt

The first example shows specifying just the name of the log file, which will be written to the directory that EasyLoader.exe is in. The second example specifies the full path for the log file.

/G Grant AllThis flag will grant all rights to PUBLIC. This flag is turned OFF by default.

Syntax:

/G

/I DO NOT Create a Spatial IndexBy default a spatial index will be created. This flag will cause a spatial index NOT to be created on the table. This flag is turned OFF by default, meaning a Spatial Index will be created.

For SpatialWare tables the index is created on the column geometry column.

Syntax:

/I

/K Create Automated Key Column for SQL ServerThe key column (sw_member) can be created with IDENTITY property as an option. When this feature is in use, the unique key column values will be generated automatically by SQL Server and the user does not need to fill the key manually when a new row is inserted. In EasyLoader version 7.0, the key column (sw_member) is created with IDENTITY property by default, which is opposite from the previous version (6.8). Therefore, by not specifying the K option in the commandline it will have the same action as specifying it as /K. For example, create the key column with IDENTITY property. If you want to turn off the property, you need to provide a keyword "NO_IDENTITY" following K. Example: /K NO_IDENTITY

Syntax:

/K

User Guide 283

/L List of MapInfo Tables

/L List of MapInfo TablesThis flag lets you specify a text file that contains a list of tables to be uploaded. The format of each line is the same as the /T flag.

Syntax:

/L ListOfTables.txt

/M MICODE/XYThis flag allows the user to specify the object type to be used if it is SpatialWare. If the /M flag is used, the user has to provide MICODE (for XY with MapInfo key) or XY (for XY) after /M. Any words other than MICODE or XY after /M are treated as an error. If the /M flag is not used, SpatialWare will be used as the default if the selected database has SpatialWare installed.

Syntax:

/M micode/M xy

/O Connection StringThis flag allows a connection string for Oracle Spatial to be passed to the program. See /S flag for ODBC connections.

Syntax:

/O user_name/password@server_name

/P ACRThis flag specifies what to do with the table(s) being loaded to the server. A is append to an existing server table, C is create a new server table, and R is replace an existing table. You must specify only one of the three choices. The create table flag will fail if a table by the same name exists on the server.

Syntax:

/P A

/Q QuitThis flag forces the loader to exit when done.

Syntax:

/Q


Chapter 25:

/R Replace the Server Table This flag will cause the server table to be dropped. The new table will be created and uploaded. A table will be created on the server even if the table did not exist originally. (This is a change from 6.0).

Syntax:

/R

/U DO NOT Create a Unique Index A Unique index will be created by default. This flag will cause a unique index NOT to be created on the table. This flag is turned OFF by default, meaning a unique Index will be created by default. See /I which controls the spatial index. For SpatialWare tables the index is created on the column SW_MEMBER and is called _ind.

Syntax:

/U

/T MapInfo Table Name;Server Table Name;Range This flag allows a single table name to be passed to the program. The separator between the MapInfo table name, the server name and the range is the semi-colon symbol. The range is in the format: starting number ending number. The server table name and the range are optional.

Syntax:

/T c:\data\states.tab;mystates;1,500

/V Oracle Version This flag allows you to load tables on an Oracle 8.1.6 server with the 8.1.5 format. This not generally recommended, but it is available if you have a special need to do this. If you want to use this flag with the dialog, see the Windows Shortcut in the Running Commandline flag section.

Syntax:

/V

/X Commit Interval This flag allows the user to specify a commit interval. EasyLoader will commit the inserted records when the commit interval is reached. The default commit interval is 1000. This same interval applies to the creation of the spatial index for Oracle Spatial. If the commit interval is set to 0 (zero), the whole range of records will be inserted as a single transaction, before a commit is issued.

User Guide 285

/Y Symbology Column Name

Syntax:

/X 500

/Y Symbology Column NameThis flag allows you to specify that per row symbology is to be loaded with the data. You can also specify the name of the column to be used. If none is provided the default column name will be used, which is MI_STYLE.

Syntax:

/Y StyleColumnName

Combining the Commandline with the InterfaceCommandline flags may be mixed with the EasyLoader interface by using a windows shortcut. This makes it easier to set flags as your default while being able to override them from the UI. There are some flags only available from the commandline.

Create a shortcut to EasyLoader:

• Right click on the shortcut and choose Properties. • Under the Shortcut tab, within the Target edit box, add on the commandline flags at the end of

the line. • When EasyLoader is run from that shortcut, the specified flags are in effect.


26
Conversion Constants
This section lists the conversion constants for converting from a given measurement to Metric. This information is supplied as a lookup table.

In this section:

Conversion Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288

Conversion Constants

Conversion ConstantsThe conversion constants for converting from Meters are given below. All conversions are in metric where a Meter is the base value. For example, there are 1000 Meters in a Kilometer:

Measurement Conversion Constant to Metric

Meter 1.0

Kilometer 1000.0

Centimeter 0.01

Millimeter 0.001

Mile 1.609344e+03

Nautical Mile 1.852000e+03

U.S. Foot 3.048006e-01

Foot (International) 3.048000e-01

Inch 2.540000e-02

Yard 9.144000e-01

Chain 2.011680e+01

Rod 5.029200e+00

Link 7.92/39.370432

Modified American Foot 12.0004584/39.37

Clarke's Foot 12.0/39.370432

Indian Foot 12.0/39.370141

Link (Benoit) 7.92/39.370113

Link (Sears) 7.92/39.370147

Chain (Benoit) 792./39.370113

Chain (Sears) 792./39.370147

Yard (Indian) 36/39.370141

Yard (Sears) 36/39.370147

Fathom 1.8288


27
Understanding Coordinate Systems and Projections
How do you flatten the curved surface of the earth so that you can draw maps on flat pieces of paper and (nearly) flat computer screens? You use a projection. A projection is a system that defines how to flatten objects. This section provides an overview of how to work with coordinate systems and projections.

In this section:

Understanding Projection and Coordinate System Terminology . .290Choosing Projections for Display. . . . . . . . . . . . . . . . . . . . . . . . .292Using Earth and Non-Earth Coordinates . . . . . . . . . . . . . . . . . . .295Working with Coordinates in SpatialWare . . . . . . . . . . . . . . . . . .295

Understanding Projection and Coordinate System Terminology

Understanding Projection and Coordinate System TerminologyWhen you transfer objects from the spherical world to the relatively flat computer screen, there is bound to be some distortion.

Mollweide (Equal-Area)

Think about it in terms of an orange. If you write the phrase “Think Visually with MapInfo” on an orange with a felt-tipped marker, the words look relatively normal. However, when you peel the orange and flatten it out, the words are barely legible. When words or objects drawn on a round surface are transferred to a flat surface some distortion must occur.

What is a Projection?

A projection is a method of reducing the distortion that occurs when objects from a spherical surface are displayed on a flat surface. There are many different types of projections, each designed to reduce the amount of distortion for a given area.

Notice the difference between the next two maps. While the first one flattens Alaska, the second shows Alaska’s true size. The relative distance between the continental US, Alaska, and Hawaii is very different in the two pictures. The border between the continental US and Canada is much more representative of a curved surface in the second projection.

Projections are most often used for:

• Digitizing a map that has an explicit projection.• importing a DXF file that has an explicit projection.• Running an application that requires the geographic precision of a given projection.• Cosmetically altering your map for output.


Chapter 27:

Projections are not used for non-earth maps, whose coordinates do not have any reference to locations on earth.

Using Latitude/Longitude

Using Azimuth Equidistant (NorthPole)

What is a Coordinate System?

A coordinate system is a set of parameters that tells you how to interpret the locational coordinates for objects. One of those parameters is projection. Although the terms are often used interchangeably, projection is only one part of a coordinate system.

Projection relates to how the objects display on a flat surface. A coordinate system tells you what projection is being used for the map, along with other reference information.

SpatialWare’s default map projection (Longitude/Latitude) is actually an equidistant cylindrical projection, using longitude/latitude coordinates. This projection is called Longitude/Latitude to convey that when you choose it, you will be working in degrees long/lat.

User Guide 291

Choosing Projections for Display

Background InformationFor further reading on projections, refer to the following document:

Map Projections – A Working Manual. Snyder, J. P. (1987). US Geological Survey Professional Paper 1395, US Government Printing Office, Washington, DC.

Choosing Projections for DisplayAs mentioned earlier, all projections create some sort of distortion. For example, some projections distort the relative area of regions. Two regions that have the same area on the earth will appear to have different areas on the map. Other projections, such as “equal area” projections, show regions with the correct area relationships (two regions that have the same area on the earth will have the same area on the map). However, equal area projections distort the shapes of regions, usually by flattening map objects near the North and South Poles.

“Conformal” projections (such as Mercator and Lambert Conformal Conic) show the shapes of small features accurately, but distort the shapes and areas of large regions.

For example, on the earth the area of Greenland is approximately 1/8 the area of South America. However, on a Mercator map, Greenland and South America appear to have the same area. While detailed areas of Greenland’s coastline are displayed with the correct shape, Greenland’s shape, as a whole, is distorted out of proportion.

If you are not familiar with the different projections (or you are changing projections for strictly cosmetic purposes), choosing the optimal projection for display may involve some trial and error. You cannot destroy or damage your data by displaying maps in different projections. Technically, you can apply any projection to any earth map. However, we offer these general guidelines:

• If you are creating a thematic map on regions (countries), an equal-area projection is recommended, especially if you are mapping the entire world.

• Use the Projections of the World for maps of the entire world. They are generally unsuitable for mapping smaller areas.

MercatorLongitude/Latitude

Greenland

South America


Chapter 27:

• For maps of the U.S., use the U.S. State Plane Coordinate Systems for maps of the respective states. You should not use them for mapping different states or other countries.

Sample Projection SystemsA projection system is a mathematical mapping of a plane. Each projection system is designed for a particular purpose. For example, the Robinson projection is optimal for thematic presentations involving the entire Earth.

Robinson

Eckert VI (Equal-Area)

User Guide 293

Choosing Projections for Display

Sinusoidal (Equal-Area)

Stereographic

Types of Coordinate Systems and Projections AvailableThe datum is established by tying a reference ellipsoid to a particular point on the earth and includes:

• The number used to identify the datum in the MAPINFOW.PRJ file.• The datum’s name.• The maps for which the datum is typically used.• The datum’s reference ellipsoid.


Chapter 27:

Using Earth and Non-Earth CoordinatesEarth coordinates and non-earth coordinates generally require different treatment. An earth coordinate contains objects that have a particular location on the earth’s surface. All maps that MapInfo sells use earth coordinates. Coordinates typically represent an object’s location in longitude and latitude, although other coordinate systems (using various projections) may be used instead.

Use earth coordinates to:

• Overlay your map onto any maps that MapInfo supplies.• Use or change projections.• Specify objects on the map in terms of longitude and latitude.

A non-earth coordinate contains objects that have no specific location on the earth’s surface. Floor plans are typical examples of non-earth maps.

Even though the floor plan describes a building that may be located somewhere on the Earth, the coordinates of objects in the floor plan are generally not referenced to positions on the Earth. Rather, the object’s coordinates are referenced to the floor plan itself, generally representing distance from the lower left corner of the floor plan.

A non-earth coordinate has a coordinate system, but since its map points are not referenced to locations on earth, the coordinate system does not contain a projection.

Floor Plan: example of a non-earth coordinate map

Working with Coordinates in SpatialWareSpatial geometry is not stored with coordinate system information. SpatialWare functions and join operations assume that spatial tables referenced in a SQL query (as operands) are all in the same coordinate system. Therefore, maintain the data in your spatial tables, or your spatial database, in a single coordinate system to ensure the accuracy of your spatial queries.

User Guide 295

Working with Coordinates in SpatialWare

If importing data to a spatial database, it is recommended that the data be saved into the same coordinate system used by all the other spatial data in the database. Transformation functions are provided to help you do this. Refer to Chapter 11: Performing Coordinate Transformations for details.

Reference tables for the Projections, Spheroids/Ellipsoids, Coordinate Units, and Datums that SpatialWare supports are provided in Chapter 29: Coordinate Transformation Reference Tables. If you need to create a new coordinate system, please contact MapInfo Technical Support for assistance.


28
Transformation Calculation
ST_Transform function performs a two dimensional transformation and the ST_Transform3D function performs a three dimensional transformation using textbook transformation calculations. This section describes the calculations.

Note that the ST_Transform and ST_Transform3D functions take a 2x3 or 3x3 matrix type respectively:

2x3 Matrix = '(sx, tx, rx, sy, ty, ry)' where rx and ry must be equal.

3x3 Matrix = '(sx, tx, rx, sy, ty, ry, sz, tz, rz).

In this section:

Two Dimensional Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . .298Three Dimensional Calculation. . . . . . . . . . . . . . . . . . . . . . . . . . .298

Two Dimensional Calculation

Two Dimensional CalculationIn a two dimensional transformation only sx, tx, rx, sy, ty, ry are used with the constraint that rx == ry:

• sx is the Scale in the X-axis,• tx is the Displacement in the X-axis,• sy is the Scale in the Y-axis,• ty is the Displacement in the Y-axis, and• rx = ry is the rotation in the xy planes in degrees.

In two dimensions, sz, tz, and rz have no meaning and must be initialized to 0.0 (or sz may be 1.0).

The effective algorithm is:

1. If the source point to be transformed is p = [x, y] then let PV = [x, y, 1]. 2. If rotation point r = [rotx, roty] is specified, then let RV = [rotx, roty, 0]. 3. Otherwise,let RV = [0, 0, 0].

set MA = [[cos(rx), -sin(rx), tx], [sin(rx), cos(rx), 0], [0, 0, 1]] 4. Set MB = [[sx, 0, tx], [0, sy, ty], [0, 0, 1]] 5. Let TV = [x', y', 1] be the result of the matrix operation:

TV = ((PV-RV)*MA*MB)+RV 6. Let the transformed point, p' be [x', y'].

Three Dimensional CalculationIn a three dimensional transformation all nine values are used, where:

• sx is the Scale in the X-axis,• tx is the Displacement in the X-axis• rx is the rotation in the yz plane,• sy is the Scale in the Y-axis,• ty is the Displacement in the Y-axis,• ry is the rotation in the xz plane,• sz is the Scale in the Y-axis,• tz is the Displacement in the Y-axis, and• rz is the rotation in the xy planes in degrees.

The effective algorithm is:

1. If the source point to be transformed is p = [x, y, z] then let PV = [x, y, z, 1]. 2. If rotation point r = [rotx, roty, rotz] is specified, then let RV = [rotx, roty, rotz, 0]; otherwise,let RV

= [0, 0, 0, 0]. 3. Set MA = [[1, 0, 0, 0], [0, cos(rx), -sin(rx), 0], [0, sin(rx), cos(rx), 0], [0, 0, 0, 1]] (yz plane rotation). 4. Set MB = [[cos(ry), 0, -sin(ry), 0], [0, 1, 0, 0], [sin(ry), 0, cos(ry), 0], [0, 0, 0, 1]] (xz plane rotation). 5. Set MC = [[cos(rz), -sin(rz),0, 0], [sin(rz), cos(rz), 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]] (xy plane rotation). 6. Set MD = [[sx, 0, 0, tx], [0, sy, 0, ty], [0, 0, sz, tz], [0, 0, 0, 1]].


Chapter 28:

7. Let TV = [x', y', z', 1] be the result of the matrix operation:TV = ((PV-RV)*MA*MB*MC*MD)+RV

8. Let the transformed point, p' be [x', y', z'].

User Guide 299

Three Dimensional Calculation


29
Coordinate Transformation Reference Tables
This section lists reference tables for Projections, Spheroids/Ellipsoids, Coordinate Units, and Datums.

In this section:

Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302Spheroids/Ellipsoids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303Coordinate Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303Datums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304

Projections

ProjectionsThe following table lists the projections supported.

Note The SQL Server implementation does not use Projection IDs.

Geographic (Lat/Long) Interrupted Goode Homolosine

Albers Conical Equal Area Mollweide

Lambert Conformal Conic Interrupted Mollweide

Mercator Hammer

Polyconic Wagner IV

Equidistant Conic Wagner VII

Transverse Mercator Oblated Equal Area

Stereographic Non-earth

Lambert Azimuthal Equal Area Transverse Mercator Danish System 45 Bornholm

Azimuthal Equidistant Transverse Mercator Danish System 34 Jylland-Fyn

Gnomonic Transverse Mercator Sjaelland

Orthographic Transverse Mercator Finnish KKJ

General Vertical Near-Side Perspective Eckert IV

Sinusiodal Eckert VI

Equirectangular Gall

Miller Cylindrical Lambert Conformal Conic (Belgium 1972)

Van der Grinten New Zealand Map Grid

Hotine Oblique Mercator Cylindrical Equal Area

Robinson Swiss Oblique Mercator

Space oblique mercator Bonne

Alaska Conformal Cassini


Chapter 29:

Spheroids/EllipsoidsThe following table lists the ellipsoids supported.

Note The SQL Server implementation does not use Ellipsoid IDs.

Coordinate UnitsThe following table lists the coordinate units supported. These units (except the last two) are also used for distance units.

Clarke 1866 Everest (Kertau) Walbeck

WGS 72 Fischer 1960 (Mercury) Bessel 1841 (NGO 1948)

Australian Fischer 1960 (South Asia) South American 1969

Krassovsky Fischer 1968 Clarke 1858

International 1924 GRS 67 Clarke 1880 (Jamaica)

Hayford Helmert 1906 Clarke 1880 (Palestine)

Clarke 1880 Hough Everest (Timbalai)

GRS 80 South American 1969 Everest (Kalianpur)

Clarke 1866 (Michigan) War Office Indonesian

Airy 1930 WGS 60 NWL 9D

Bessel 1841 WGS 66 NWL 10D

Everest WGS 84 OSU86F

Sphere Clarke 1880 (IGN) OSU91A

Airy 1930 (Ireland 1965) 0IAG 75 Plessis 1817

Bessel 1841 (Schwarzeck) MERIT 83 Struve 1860

Clarke 1880 (Arc 1950) New International 1967 Sphere (Unity)

Clarke 1880 (Merchich)

Meter Chain Indian Foot

Kilometer Rod Link (Benoit)

Centimeter Link Link (Sears)

User Guide 303

Datums

Note The SQL Server implementation does not use coordinate IDs.

Datums The datum is established by tying a reference ellipsoid to a particular point on the earth. The following table lists:

• The number used to identify the datum (the same numbers used in MapInfo Professional's MAPINFOW.PRJ file).

• The datums. • The maps (area) where they are typically used. • Their reference ellipsoid.

Millimeter Decimal degree Chain (Benoit)

Mile Gon Chain (Sears)

Nautical Mile Grad Yard (Indian)

Survey foot Modified American Foot Yard (Sears)

Foot Clarke’s Foot Fathom

Inch Decimal second

Yard Decimal minute

Number Datum Area Ellipsoid

1 Adindan Ethiopia, Mali, Senegal, Sudan Clarke 1880

2 Afgooye Somalia Krassovsky

3 Ain el Abd 1970 Bahrain Island International

4 Anna 1 Astro 1965 Cocos Islands Australian National

5 Arc 1950 Botswana, Lesotho, Malawi, Swazi-land, Zaire, Zambia, Zimbabwe

Clarke 1880

6 Arc 1960 Kenya, Tanzania Clarke 1880

7 Ascension Island 1958 Ascension Island International

8 Astro Beacon “E” Iwo Jima Island International

9 Astro B4 Sorol Atoll Tern Island International

10 Astro DOS 71/4 St. Helena Island International


Chapter 29:

11 Astronomic Station 1952 Marcus Island International

12 Australian Geodetic 1966 (AGD 66)

Australia and Tasmania Island Australian National

13 Australian Geodetic 1984 (AGD 84)

Australia and Tasmania Island Australian National

110 Belgium Belgium International

14 Bellevue (IGN) Efate and Erromango Islands International

15 Bermuda 1957 Bermuda Islands Clarke 1866

16 Bogota Observatory Colombia International

17 Campo Inchauspe Argentina International

18 Canton Astro 1966 Phoenix Islands International

19 Cape South Africa Clarke 1880

20 Cape Canaveral Florida and Bahama Islands Clarke 1866

21 Carthage Tunisia Clarke 1880

22 Chatham 1971 Chatham Island (New Zealand) International

23 Chua Astro Paraguay International

24 Corrego Alegre Brazil International

9999 Custom (see Appendix G)

1000 Deutsches Hauptdreick-snetz (DHDN)

Germany Bessel

25 Djakarta (Batavia) Sumatra Island (Indonesia) Bessel 1841

26 DOS 1968 Gizo Island (New Georgia Islands) International

27 Easter Island 1967 Easter Island International

28 European 1950 (ED 50) Austria, Belgium, Denmark, Fin-land, France, Germany, Gibraltar, Greece, Italy, Luxembourg, Nether-lands, Norway, Portugal, Spain, Sweden, Switzerland

International

29 European 1979 (ED 79) Austria, Finland, Netherlands, Nor-way, Spain, Sweden, Switzerland

International


User Guide 305

Datums

108 European 1987 (ED 87) Europe International

30 Gandajika Base Republic of Maldives International

31 Geodetic Datum 1949 New Zealand International

32 Geodetic Reference Sys-tem 1967 (GRS 67)

Worldwide GRS 67

33 Geodetic Reference Sys-tem 1980 (GRS 80)

Worldwide GRS 80

34 Guam 1963 Guam Island Clarke 1866

35 GUX 1 Astro Guadalcanal Island International

36 Hito XVIII 1963 South Chile (near 53°S) International

37 Hjorsey 1955 Iceland International

38 Hong Kong 1963 Hong Kong International

39 Hu–Tzu–Shan Taiwan International

40 Indian Thailand and Vietnam Everest

41 Indian Bangladesh, India, Nepal Everest

42 Ireland 1965 Ireland Modified Airy

43 ISTS 073 Astro 1969 Diego Garcia International

44 Johnston Island 1961 Johnston Island International

45 Kandawala Sri Lanka Everest

46 Kerguelen Island Kerguelen Island International

47 Kertau 1948 West Malaysia and Singapore Modified Ever-est

48 L.C. 5 Astro Cayman Brac Island Clarke 1866

49 Liberia 1964 Liberia Clarke 1880

113 Lisboa (DLx) Portugal International

50 Luzon Philippines (excluding Mindanao Island)

Clarke 1866

51 Luzon Mindanao Island Clarke 1866



Chapter 29:

52 Mahe 1971 Mahe Island Clarke 1880

53 Marco Astro Salvage Islands International

54 Massawa Eritrea (Ethiopia) Bessel 1841

114 Melrica 1973 (D73) Portugal International

55 Merchich Morocco Clarke 1880

56 Midway Astro 1961 Midway Island International

57 Minna Nigeria Clarke 1880

58 Nahrwan Masirah Island (Oman) Clarke 1880

59 Nahrwan United Arab Emirates Clarke 1880

60 Nahrwan Saudi Arabia Clarke 1880

61 Naparima, BWI Trinidad and Tobago International

109 Netherlands Netherlands Bessel

62 North American 1927 (NAD 27)

Continental US Clarke 1866


Alaska Clarke 1866


Bahamas (excluding San Salvador Island)

Clarke 1866


San Salvador Island Clarke 1866


Canada (including Newfoundland Island)

Clarke 1866


Canal Zone Clarke 1866


Caribbean (Turks and Caicos Islands)

Clarke 1866


Central America (Belize, Costa Rica, El Salvador, Guatemala, Honduras, Nicaragua)

Clarke 1866


Cuba Clarke 1866


User Guide 307

Datums


Greenland (Hayes Peninsula) Clarke 1866


Mexico Clarke 1866


Michigan (used only for State Plane Coordinate System 1927)

Modified Clarke 1866


Alaska, Canada, Central America, Continental US, Mexico

GRS 80

107 Nouvelle Triangulation Francaise (NTF)

France Modified Clarke 1880

1002 Nouvelle Triangulation Francaise (NTF) Green-wich Prime Meridian

France Modified Clarke 1880

111 NWGL 10 Worldwide WGS 72

75 Observatorio 1966 Corvo and Flores Islands (Azores) International

76 Old Egyptian Egypt Helmert 1906

77 Old Hawaiian Hawaii Clarke 1866

78 Oman Oman Clarke 1880

79 Ordnance Survey of Great Britain 1936

England, Isle of Man, Scotland, Shetland Islands, Wales

Airy

80 Pico de las Nieves Canary Islands International

81 Pitcairn Astro 1967 Pitcairn Island International

1000 Potsdam Germany Bessel

36 Provisional South Chilean 1963

South Chile (near 53°S) International

82 Provisional South Ameri-can 1956

Bolivia, Chile, Colombia, Ecuador, Guyana, Peru, Venezuela

International

83 Puerto Rico Puerto Rico and Virgin Islands Clarke 1866

1001 Pulkovo 1942 Germany Krassovsky

84 Qatar National Qatar International

85 Qornoq South Greenland International



Chapter 29:

1000 Rauenberg Germany Bessel

86 Reunion Mascarene Island International

112 Rikets Triangulering 1990 (RT 90)

Sweden Bessel

87 Rome 1940 Sardinia Island International

88 Santo (DOS) Espirito Santo Island International

89 São Braz São Miguel, Santa Maria Islands (Azores)

International

90 Sapper Hill 1943 East Falkland Island International

91 Schwarzeck Namibia Modified Bessel 1841

92 South American 1969 Argentina, Bolivia, Brazil, Chile, Colombia, Ecuador, Guyana, Para-guay, Peru, Venezuela, Trinidad, and Tobago

South American 1969

93 South Asia Singapore Modified Fis-cher 1960

94 Southeast Base Porto Santo and Madeira Islands International

95 Southwest Base Faial, Graciosa, Pico, Sao Jorge, Terceira Islands (Azores)

International

1003 Switzerland (CH 1903) Switzerland Bessel

96 Timbalai 1948 Brunei and East Malaysia (Sarawak and Sabah)

Everest

97 Tokyo Japan, Korea, Okinawa Bessel 1841

98 Tristan Astro 1968 Tristan da Cunha International

9999 User–defined

99 Viti Levu 1916 Viti Levu Island (Fiji Islands) Clarke 1880

100 Wake–Eniwetok 1960 Marshall Islands Hough

101 World Geodetic System 1960 (WGS 60)

Worldwide WGS 60


Worldwide WGS 66


User Guide 309

Datums


Worldwide WGS 72


Worldwide WGS 84

105 Yacare Uruguay International

106 Zanderij Surinam International



30
Glossary
AggregationA group, body, or mass composed of many distinct parts or individuals. The collecting of units or parts into a mass or whole. The condition of being collected in this way.

Algorithm A general process for solving a category of problems.

Alias1. <operating system> A name, usually short and easy to remember and type, that is translated into another name or string, usually long and difficult to remember or type. Most command interpreters (e.g. Unix's csh) allow the user to define aliases for commands, e.g. "alias l ls -al". These are loaded into memory when the interpreter starts and are expanded without needing to refer to any file.

2. <networking> One of several alternative hostnames with the same Internet address. E.g. in the Unix hosts database (/etc/hosts or NIS map) the first field on a line is the Internet address, the next is the official hostname (the "canonical name" or "CNAME"), and any others are aliases. Hostname aliases often indicate that the host with that alias provides a particular network service such as archie, finger, FTP, or World-Wide Web. The assignment of services to computers can then be changed simply by moving an alias (e.g. www.doc.ic.ac.uk) from one Internet address to another, without the clients needing to be aware of the change.

ApplicationA software program or system of programs designed to fulfill a specific user requirement.

Application FrameworkThe software environment tailored to the needs of a specific domain. Frameworks include a collection of software components that programmers use to build applications for the domain the framework addresses. Frameworks can contain specialized APIs, services, and tools, which reduce the knowledge a user or programmer needs to accomplish a specific task.

Applications Program Interface<programming> (API, or "application programming interface") The interface (calling conventions) by which an application program accesses operating system and other services. An API is defined at source code level and provides a level of abstraction between the application and the kernel (or other privileged utilities) to ensure the portability of the code.

An API can also provide an interface between a high level language and lower level utilities and services, which were written without consideration for the calling conventions supported by compiled languages. In this case, the API's main task may be the translation of parameter lists from one format to another and the interpretation of call-by-value and call-by-reference arguments in one or both directions.

Architecture<architecture> Design, the way components fit together. The term is used particularly of processors, both individual and in general. "The ARM has a really clean architecture". It may also be used of any complex system, e.g. "software architecture", "network architecture".

Area1. A generic term for a bounded, continuous, two-dimensional object that may or may not include its boundary and may be delimited by zero or more non-nested, non-intersecting inner boundaries.

2. A measure of the size of a surface.

Argument<programming> (Or "arg") A value or reference passed to a function, procedure, subroutine, command or program, by the caller. For example, in the function square(x) = x * x. x is the formal argument or "parameter" and in the call y = square(3+3). 3+3 is the actual argument. This will, in most cases, execute the function square with x having the value 6.

There are many different conventions for passing arguments to functions and procedures including call-by-value, such as a call-by-name, call-by-need. These affect whether the value of the argument is computed by the caller or the callee (the function) and whether the callee can modify the value of the argument as seen by the caller (if it is a variable).

Arguments to functions are usually, following mathematical notation, written in parentheses after the function name, separated by commas. Arguments to a program are usually given after the command name, separated by spaces, e.g.:

cat myfile yourfile hisfileHere "cat" is the command and "myfile", "yourfile", and "hisfile" are the arguments.

AzimuthThe angular distance measured clockwise from the north point of a compass.

Begin PointThe first point in a sequence of points (e.g., a line). In the case of a line, the direction property determines which point from P0 to Pn is the beginning or end.

BLOB The MapInfo BLOB is a binary representation of geometry used by MapInfo clients. This is the representation used to transfer geometries between an ODBC client and the database server.

The SpatialWare BLOB is a native binary format based on the SQL/MM object model.


Chapter 30:

BoundaryA geometry's boundary is the collection of its outermost points, which defines a closed, one-dimensional, non-intersecting element delimiting an area.

BufferGiven a distance n, the buffer of a given spatial object is the area determined such that the distance between each point on the boundary of the buffer and the spatial object is n.

Centroid A point which is the weighted mathematical center of a one or two dimensional spatial object.

Closed A line is considered closed if its start and end points are the same.

ComponentAn object adhering to a component architecture. A component is a software object, meant to interact with other components, encapsulating certain functionality or a set of functionality. A component has a clearly defined interface and conforms to a prescribed behavior common to all components within an architecture.

Constructor A constructor is a function that creates a geometry (ST_Spatial).

Contains A spatial object is contained by another spatial object if it is completely included within the other object.

Contiguous An object is contiguous if its elements are in a continuous connection.

Curve A curve is a type of line. The name does not necessarily denote a rounded shape. For example, a straight line is a type of curve.

Geometries which are considered to be part of the family of curves are ST_Polyline, ST_CirclularArc, HG_Circle, and HG_Curve.

Database Units The units of measurement used for a database. SpatialWare functions perform Cartesian planar calculations.

Direction Property All ST_Lines and sub-types include information about the direction of the line. Direction is Forward, Reverse, or NULL.

Double Precision (database units) Specifies the data type approximate numeric, with implementation-defined precision that is greater than the implementation-defined precision of REAL.

End Point The last point in a sequence of points. In the case of a line, the end point is dependent on the direction of the line.

EnterpriseA large-scale, organization-wide computer network that may include web-based, client-server, and mainframe computing technologies. Or … The highest level in an organization – includes all missions and functions.

User Guide 313

Envelope A rectangular box oriented along the axes which just barely encompasses the entire object.

External Representation The way that a data type appears to the user.

Filter Tolerance Many functions perform operations on spatial data using a filter tolerance, which determines the level of detail or accuracy that input or output will have.

Geometric Primitive Coordinates are used to form geometric primitives, and geometric primitives are used to graphically represent the location of features.

Features can be composed of the following geometric primitives:

PointA specific location consisting of x and y, or x, y, and z coordinates. Points do not have length or area. In an application, a point might be used to represent a store or customer location (e.g., a geocoded address).

Line Lines, polylines, splines, or circular arcs are all stored as a series of x, y, and z coordinate pairs with a beginning and end point. Lines have length but no area. In an application, a line might be used to represent a street or river.

Polyline Stored as a series of x, y, and z coordinate pairs with the same start and end point to form a closed surface. Polygons have area and perimeter. In an application, a polygon might represent a building, a lake, or a sales territory.

Geometry Geometry is the short form for ST_GeometricPrimitive. A geometry is one or more primitives, such as an ST_Polyline, ST_Polygon, or ST_Point.

See also Valid Geometry.

Geometry Collections ST_Spatials can contain more than one primitive. A collection is an ST_Spatial with more than one geometry.

HG_ The HG_ prefix indicates that the function or data type is an enhancement to the ISO/IEC/MM standard.

ISO/IEC SQL/MM An international standard for spatial data types and SQL queries.

Line A generic term for a one-dimensional object.

Line Segment A line segment connects a consecutive pair of points within a polyline.

MapInfo BLOBSee BLOB.


Chapter 30:

Meets Two objects meet if they are contiguous, overlapping, abutting or touching.

Minimum Enclosing Rectangle

The Minimum Enclosing Rectangle (MER) for any given map object is the smallest rectangle that completely encompasses the object.

Node A node is an end point of a line object, or an end point of a line segment, which is part of a polyline or region object.

Observer A function that returns values within a geometry (ST_Spatial).

Overlaps Two objects overlap if they have at least one point in common.

Path A path is created by one or more ST_Curves.

Parameter A parameter is an argument given to a function. When using a function, a parameter is the input. A parameter can be a number, a BOOLEAN or an ST_Spatial.

Point A point is a zero dimensional object that specifies a geometric location.

Polyline A type of ST_Curve made up of two or more points. Polylines can be straight or 'curvy'.

Polygon A closed planar area.

Predicate A predicate is a function that determines if a geometry meets a given set of conditions, and returns a Boolean value of true or false.

Relative Point When measuring azimuth, the relative point is the point that is measured against the point of origin.

RDBMS Relational Database Management System.

R-treeThe spatial index used to spatially access the geometry objects.

Shape A shape is a single geometry, such as a polygon.

Slope A slope is the degree or amount of inclination of a surface or line.

Spatial Data Data with information on location, position, size, and shape.

Spatial IndexingA method of accessing geometric data. Spatial indexing avoids sequential searching by using the coordinates of a location as a key.

User Guide 315

Spatial Object Synonym for a geometry defined by the ST_Spatial string. A spatial object could be emply, or comprised of a single geometry, or a geometry collection.

Spatial Table A table is considered "spatializable" if it has a column of type ST_Spatial and an integer column which is unique and not null (preferably primary key). A table is considered "spatial" if it has been spatially enabled using the sp_sw_spatialize_column procedure.

Spatialize To spatially enable a table using the Spatialize Column procedure. This is necessary to save spatial data to a table. Note that the table must first contain a column of type ST_Spatial.

Spatially enable A database must be spatially enabled in order for SpatialWare to use it. This involves running scripts on the database to install SpatialWare components, and create the spatial type necessary to work with SpatialWare.

SpatialWare BLOBSee BLOB.

SQL Structured Query Language.

ST_ The ST_ prefix indicates that the function or data type matches the ISO/IEC/MM standard.

String The phrases that appear in quotation marks are called strings, because they are made up of a sequence (string) of letters. Actually, strings can contain any combination of letters, numbers, punctuation marks, and other special characters.

Syntax The structure of a program.

Two-Point Line A straight ST_Polyline consisting of two points.

Tolerance Points falling within the tolerance value of one another are considered to be the same location.

Union1. <set theory> An operation on two sets which returns the set of all elements that are a member of either or both of the argument sets; normally written as an infix upper-case U symbol. The operator generalizes to zero or more sets by taking the union of the current partial result (initially the empty set) with the next argument set, in any order.

For example, (a, b, c) U (c, d, e) = (a, b, c, d, e)

2. <programming> A type whose values may be of one of a number of other types, that current type depending on conditions that are only known at run-time. A variable of union type must be allocated sufficient storage space to hold the largest component type. Some unions include extra information to say which type of value the union currently has (a "tagged union"), others rely on the program to keep track of this independently. A union contrasts with a structure or record, which stores values of all component types at once.


Chapter 30:

3. <database> An SQL operator that concatenates two result sets, that must have the same number and types of columns. The operator may be followed by the word "ALL" to indicate that results that appear in both sets should appear twice in the output.

Valid Geometry A geometry is considered valid if it is well formed and conforms to geometric rules. Examples of geometry that are not valid are degenerate lines and unclosed polygons.

Value A number or string (or other thing to be named later) that can be stored in a variable. Every value belongs to one type.

Variable A named storage location for values. All variables have a type, which is declared when the variable is created.

User Guide 317

Index

Numerics2D transformation calculation 2983D transformation calculation 298

AAggregate functions, SQL 61Aliases 52ALTER privileges 69Architecture 17Area units 121Attribute, IDENTITY 278AVG 61Azimuth Equidistant (NorthPole) 291

BBatch imports 53

CCache size, determining 48Case sensitive databases 70Clauses

Group By 61Order By 60–61

ClientsMapInfo Professional 71MapX 71–72

Collections, geometry 79, 106–107Columns, sw_member 69Constructor function, ST_Spatial 82–84Conventions 20Conversion constants for HG_SphericalDist 288Coordinate systems

defined 291overview 291

Coordinate transformations 110–113Copy

table 46COUNT 61

Create New Data Source dialog 68Create New Table dialog 47Creating

output table 62R-tree index 48–49r-tree index 48table in MI Pro 46–47table using T-SQL 45

DData

creating source 68–69deleting 53–54dimension 119spatial 52tolerance 119

Data Source Name (DSN) 68Databases

case sensitive 70troubleshooting 264

definitions 247–260Deleting data 53–54Dialogs

Create New Data Source 68Create New Table 47New DBMS Table Options 47New Table 46New Table Structure 47Open DBMS Connection 68Select Data Source 68

Dimensionfunctions that support dimension 119geometry construction 84

Documentation 19

EEarth coordinates 295Earth maps, using 295Errors

User Guide 318

missing end comment mark 265SQLServer column not found 266syntax error detected at line x 266

FFetch size 48Filegroup 48Files

MAPINFOW.PRJ 294Filter tolerance 118

GGeometry

checking by viewing 52collections 79, 106–107constructing 77–79hierarchy diagram 82overview 76–77queries 79–80string formats 84–98

geomtest, sample table 52Global temporary tables 63–64Group By clause 61

HHG_Affine 187HG_Affine3D 187HG_Aggintersection 129HG_As_Curves 188HG_As_Paths 189HG_As_Points 189HG_AsBinary 124HG_AsText 124HG_At_End_Of 224HG_At_Start_Of 225HG_Azimuth 140HG_Azimuth_2pts 140HG_Begin_Point 157HG_Below 226HG_Box, two points 85HG_Box, x, y values 86HG_Cen_X 157HG_Cen_Y 158HG_Cen_Z 158HG_Center_In 190HG_Center_In_3D 191HG_Center_Point 159HG_Centroid 192HG_Circle, center point and radius 87HG_Circle, two points 86HG_Circle, x y and radius 88HG_Clean 192

HG_Clean_I 193HG_Clean_S 195HG_Combine 196HG_Connect 196HG_Connected_To 226HG_Convex_Hull 197HG_Coordsys 128HG_Coordsys_ID 128HG_Corner 159HG_CS_AngularUnit 130HG_CS_LinearUnit 130HG_CSTransform 134HG_Curve 89, 160HG_Difference 198HG_Distance 141HG_End_Arc_Rot 160HG_End_Of 199HG_End_Point 161HG_End_Tangent 162HG_End_Tangent_P 162HG_Envelope 199HG_Erase 201HG_Erase_Outside 202HG_Expanded 163HG_Exterior_Path 163HG_Extract_At 164HG_Filter 203HG_Filter_Curves 204HG_Filter_Paths 204HG_Filter_Points 204HG_Filter_Polygons 205HG_GeometryN 164HG_GetString 52, 136HG_Height 142HG_Identical 228HG_Interior_Path 165HG_Intersect_In 205HG_Is_Box 228HG_Is_Circle 229HG_Is_CircularArc 229HG_Is_Closed 230HG_Is_Contiguous 230HG_Is_Curve 231HG_Is_Empty 231HG_Is_Forward 232HG_Is_HG_Curve 232HG_Is_Invalid 233HG_Is_Nulldir 233HG_Is_Path 234HG_Is_Point 234HG_Is_Polygon 235HG_Is_Polyline 235HG_Is_Quad 236

User Guide 319

HG_Is_Reverse 236HG_Is_Triangle 236HG_Is_Valid 237HG_Is_Znull 237HG_Level 238HG_LL_Circle 206HG_Llb_X 166HG_Llb_Y 166HG_Llb_Z 167HG_Ncoords 167HG_Ncurves 168HG_Nitems 168HG_Npaths 169HG_Npoints 169HG_Npolygons 170HG_Nsubcurves 170HG_Ori_Rotation 171HG_Ori_X 171HG_Ori_Y 172HG_Ori_Z 172HG_Point 173HG_Pointdyn_Ori_X 173HG_Pointdyn_Ori_Y 175HG_Pointdyn_Rot 175HG_Pointdyn_Xscale 176HG_Pointdyn_Yscale 176HG_PointN 177HG_Quad 90HG_Radians 177HG_Slope 143HG_Slope_2pts 143HG_Slope_Avg 144HG_Slope_Max 145HG_Slope_Min 145HG_SpatialRef tables 110–111HG_SphericalArea 146HG_SphericalBuffer 207HG_SphericalCircle 208HG_SphericalDist 147HG_SphericalDistance 148HG_SphericalLength 149HG_SphericalPerimeter 149HG_Split 208HG_Start_Arc_Rot 178HG_Start_Of 209HG_Start_Tangent 178HG_Start_Tangent_P 179HG_Subcurve 179HG_Sym_Difference 210HG_Triangle 90HG_Union 211HG_Urt_X 180HG_Urt_Y 181

HG_Urt_Z 181HG_Width 150HTML docs 19

IIcons 20IDENTITY, attribute 278Importing data, batch 53Indexes

controlling use of 60R-tree 44, 50

into predicate 52ISO standards 22

KKey Column 44

LLimitations

extended stored procedures 265sp_spatial_query 62

Linear units 120

MMAPINFOW.PRJ 294Maps

Azimuth Equidistant (NorthPole) 291earth and non-earth 295Eckert VI (Equal-Area) 293Longitude/Latitude 291–292Mercator 292Mollweide (Equal-Area) 290Robinson 293Sinusoidal (Equal-Area) 294Stereographic 294

MAX 61Microsoft SQL Server ODBC Driver 68MIN 61Mollweide (Equal-Area) 290

NNearest Neighbor operation 64–65New DBMS Table Options dialog 47New Table dialog 46New Table Structure dialog 47Non-Earth coordinate 295Non-Earth maps, using 295

OODBC

Data Source Administrator 68


driver 68OGC Well-Known text 111–112Online docs 19Open DBMS Connection dialog 68Open Geospatial Consortium (OGC) 21Operations, Nearest Neighbor 64–65Order By clause 60–61Ordinate systems 120–121overview 52

PParameters

Nearest Neighbor 64sp_spatial_query 58–59

Performing 30Populating 30Privileges

ALTER 69Procedures

sp_sw_column_is_spatialized 49sp_sw_create_rtree 48sp_sw_despatialize_column 50sp_sw_drop_rtree 50sp_sw_rtree_is_created 49sp_sw_spatialize_column 45

ProjectionsAzimuth Equidistant (NorthPole) 291choosing 292coordinate systems 291definition 290–291earth and non-earth 295Eckert VI (Equal-Area) 293Longitude/Latitude 291–292Mercator 292Mollweide (Equal-Area) 290overview 290Robinson 293Sinusoidal (Equal-Area) 294Stereographic 294

QQuery Analyzer utility 53Quotations 52QUOTED_IDENTIFIER 41–42, 62

RR-tree Index 44, 50

creating 48–49dropping 50verifying existance 49

SSample table 52Scripts

MapBasic, spatialize table 71missing end comment error 265sp_spatialize_db 41sw_function_register.sql 248, 253

Select Data Source dialog 68Size

cache 48fetch 48

sp_spatial_query 79–80choosing 57overview 56using 57–62

sp_spatialize_db script 41sp_sw_column_is_spatialized 49sp_sw_create_rtree 48sp_sw_despatialize_column 50sp_sw_drop_rtree 50sp_sw_rtree_is_created 49sp_sw_spatialize_column 45Spatial

column 44data, overview 52table, overview 44

Spatial data 52batch import 53deleting 53–54queries 79–80types 81–82

SpatializeMapBasic tool 69non-spatial table 48table 45–46, 69undo 50verify 49

Spherical systems 120–121SQL Server

binary/text column limitation 56geometry size limitation 80isql utility 58Query Analyzer 41QUOTED_IDENTIFIER 41SpatialWare overview 16troubleshooting 265–268

ST_Adjacent 212ST_Adjacent_To 238ST_Area 150ST_Buffer 213ST_CircularArc 91ST_Contain 214

User Guide 321

ST_Contained_By 240ST_Contains 240ST_Equal 241ST_GeometricPrimitive 81–82ST_Length 151ST_Length_3D 151ST_Meets 242ST_Not_Equal 243ST_Outside 243ST_Overlap 215ST_Overlaps 244ST_Path 92ST_Perimeter 152ST_Perimeter_3D 152ST_Point 93ST_Polygon, boundaries & centroid 96ST_Polygon, exterior & interior boundaries 95ST_Polygon, exterior boundary 94ST_Polygon, exterior boundary & centroid 94ST_Polyline 98ST_Separation 142ST_Spatial 82–84ST_Transform 216, 218ST_Within 245ST_X 182ST_Y 182ST_Z 183Stored procedure, sp_spatial_query 57–62String formats 84–98SUM 61sw_function_register.sql script 248sw_function_register.sql, script 253sw_member, column 69sw_spatialize_tab.mbx 46, 48, 69

TTables

copying 46creating in MI Pro 46–47creating in using T-SQL 45creating output 62global temporary 63–64HG_SpatialRef 110–111ouptputting to existing 63spatialize using T-SQL 45–46spatializing 69temporary 63unique identifier column 69

Temporary tablescreating output 62global 63–64insert statement 63

Textgeometry string formats 84–98OGC Well-Known 111–112

Tolerancedata 119filter 118

ToolsEasyLoader 277–286MapBasic’s Spatialize Table 69MapInfo’s Make Table Mappable 46sw_spatialize_tab.mbx 46, 48, 69

Transformations, coordinate 110–113Troubleshooting

database 264SQL Server 265–268

Type hierarchy diagram 82

Uudf_type 250Unique identifier column 69Units

area 121linear 120

User Defined Functions 79–80, 247–260choosing 57overview 56–57


SpatialWare 4.9.2 for SQL Server User Guide - GIS...

Documents

Transcript of SpatialWare 4.9.2 for SQL Server User Guide - GIS...