mapmarker extended stored procedure for sql...

MapMarker Extended Stored Procedure

for SQL Server

Getting Started

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.

©1992–2000 MapInfo Corporation. All rights reserved. MapInfo Help ©1992–2000 MapInfo Corporation. All rights reserved.

MapInfo, MapInfo Professional, the MapInfo "Rainbow" logo, MapXtreme, MapInfo MapX, MapMarker, MapMarker Plus, MapXsite, MapXtend, StreetPro, TargetPro, and SpatialWare are trademarks of MapInfo Corporation and its affiliated companies. Other marks are the property of their respective owners.

MapInfo welcomes your comments and suggestions.

Contact MapInfo Corporation on the Internet at http://www.mapinfo.com

This documentation reflects the contributions of almost all of the women and men who work for MapInfo Corporation. It was specifically produced by Anne Thorne, with the help of Michael Berner, Marie Costa, Colleen Cox, Juliette Funiciello-Vunk, Lindsay Guttshall, Allison Hastings, Ed McElroy, Max Morton, Gayle Patenaude, Dianne Ritter, Larry Strianese, and Ursula Toelke. These members of the Documentation Department are indebted to MapInfo’s Quality Assurance Department and, of course, to all the members of the Product Development team that engineered this project.

MapInfo welcomes your comments and suggestions.

MapMarker Extended Stored Procedure for SQL Server v1.1

February 2001

MapInfo Corporate Headquarters: MapInfo Europe Headquarters: Germany:

Voice: (518) 285-6000 Voice: +44 (0)1753.848.200 Voice: +49 (0)6142-203-400

Fax: (518) 285-6060 Fax: +44 (0)1753.621.140 Fax: +49 (0)6142-203-444

Sales Info Hotline: (800) 327-8627 email: [email protected] email:[email protected]

US Government Sales: (800) 619-2333

Technical Support Hotline: (518) 285-7283Technical Support Fax: (518) 285-6080

Toll-free telephone support is available in the U.S. and Canada. Contact your MapInfo sales representative for details. For international customers, please use the Technical Support Fax number.

Chapter 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1About MapMarker ESP for SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Software Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Extended Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Documentation for MapMarker ESP for SQL Server . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2: Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Installing MapMarker ESP for SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Reinstalling MapMarker ESP for SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Uninstalling MapMarker ESP for SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 3: Working with MapMarker ESP for SQL Server . . . . . . . . 15About Geocoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Preparing to Geocode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Extended Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Result Codes Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Geocoding Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Chapter 4: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Appendix A: MapMarker ESP for SQL Server and MapMarker Server Preference Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Appendix B: Glossary of Address and Geocoding Terms . . . . . . . . 53

Appendix C: SpatialWare and MapMarker ESP for SQL Server . . . . 55

Chapter 1: Introduction

OverviewMapMarker Extended Stored Procedure (ESP) for SQL Server is for users of Microsoft SQL Server who wish to add SQL Server spatial points or longitude/latitude information to their address records for display and spatial analysis purposes. This is accomplished by a process known as geocoding.

MapMarker ESP for SQL Server uses NT server architecture to interact with the powerful geocoding engine in MapMarker from a SQL Server database.

Certain geocoding parameters may be specified and set through an interface provided with the package. These can then be defined as a set for use with a particular run or call.

An extremely useful feature is that MapMarker ESP for SQL Server allows geocoding calls to be implemented on a trigger action. This provides the automatic updating of database address information.

You may geocode addresses individually or process an entire table using the functions and procedures provided with the package.

MapMarker ESP for SQL Server also allows full integration with SpatialWare’s rich suite of spatial analysis capabilities.

To learn how to use MapMarker ESP for SQL Server, look at the samples that are installed in the ..\MMESP\demo directory. A summary of these samples is described in the section Geocoding Examples.


About MapMarker ESP for SQL Server

As shown in the diagram above, MapMarker ESP for SQL Server is provided as a package which integrates SQL Server with the MapMarker Geocoding Engine.

MapMarker ESP for SQL Server is implemented as a set of Extended Stored Procedures (geocodeTable, geocodeAddress, findAddress) and Settings (Preference table, Metadata table and regular Stored Procedures).

SQL Server clients may open a SQL Server session either through an Open Database Connection (ODBC), using Microsoft tools such as Interactive SQL (isql) or db_library. The clients’ requests are passed to the MapMarker Server by MapMarker ESP for SQL Server using a Remote Procedure Call (RPC). These requests are then submitted to, and performed by, the MapMarker Geocoding Engine. The results are passed back through the MapMarker Server.

The MapMarker Server is a standalone application which is provided with MapMarker 6.x and MapMarker Plus 6.x which extends its functionality. It is used to handle the management of requests to and from the MapMarker geocoding engine. It supports a queueing and multi-

2


threading function for multiple geocoding requests and provides a buffer for results. It also ensures the correct interface to the SQL Server database functionality, particularly in allowing the use of database triggers. Please refer to your MapMarker Server and MapMarker 6.x and MapMarker Plus 6.x product guides for more detailed information.

The SQL Server provides data storage, session management, and a container for stored procedures.

A database trigger interface is built into MapMarker ESP for SQL Server to enable automatic address updating and insertion. This option is possible using the findLocation functions. See Preferences on page 29 for further information.

Mapinfo SpatialWare for SQL Server is fully supported by MapMarker ESP. Point data is written into separate x, y columns and can also be written to SpatialWare geometry format in SQL Server. MapMarker ESP for SQL Server is compatible with all SpatialWare format geometries. SpatialWare allows the storage, access, management, and manipulation of spatial data as a standard component in a data set. If you wish to use the SpatialWare geometry format, it must be specified in the preferences before geocoding. Point data is always written in separate x, y columns but the SpatialWare geometry format is only written to if explicitly specified in preferences. Use the @returnSpatial preference from the preferences table to change this. See Preferences on page 29 for more information.

3


Software RequirementsThe following software is required to geocode SQL Server records:

• MapMarker ESP for SQL Server – MapInfo product for geocoding SQL Server records.

• SQL Server v7.0 (certified with Service Pack 3) or SQL Server 2000 – Microsoft relational database.

• MapMarker 6.x or MapMarker Plus 6.x – MapInfo’s geocoding engine and Address Dictionary products. Included with MapMarker and MapMarker Plus is MapMarker Server which communicates between MapMarker and MapMarker ESP for SQL Server.

The MapMarker Server runs as an NT service on Windows NT and Windows 2000, or as a console application on Windows 95/98.

SpatialWare is fully supported by MapMarker ESP for SQL Server and may be used with this product. You will need a SpatialWare license if you wish to use SpatialWare with MapMarker ESP for SQL Server.

Important: We assume you are familiar with SQL Server (and SpatialWare if used), including how to update tables, add columns, create spatial indexes (for SpatialWare) etc.

4


FeaturesThe following are features of MapMarker ESP for SQL Server. For more information on these, see Chapter 3: Working with MapMarker ESP for SQL Server. They can be divided into two (2) types: Extended Stored Procedures and Settings.

Extended Stored Procedures

Geocoding a Table of Addresses• sp_geocodeTable, sp_geocodeTableLastLine – Both used to geocode a table of

addresses.

Geocoding a Single Address• sp_findLocation, sp_findLocationLastLine – Both used to geocode a single

address and return one (1) row. These may also be used with MapMarker ESP for SQL Server's database trigger functionality.

• sp_geocodeAddress, sp_geocodeAddressLastLine – These return a result set as opposed to the one (1) row of sp_findLocation. The result set may consist of none(0), one (1) or more rows.

Settings

Preferencesmm_preferences – This is a table which stores the definitions of geocoding preferences.

The following extended stored procedures are provided to assist you in changing settings in your geocoding.

• sp_create_preference – Creates a new preference and saves it in the mm_preferences table.

• sp_delete_preference – Deletes an existing preference.

• sp_set_default_preference – Assigns a default preference.

• sp_get_default_preference – Outputs a default preference.

• sp_set_preference – Changes particular preference parameters.

5


Metadatamm_geocode_metadata – This is a table which stores information about input/output tables used in a geocoding request.

The following extended stored procedures are provided to assist you in creating and changing metadata entries for your geocoding.

• sp_create_metadata – Creates a new metadata entry.

• sp_delete_metadata – Deletes a metadata entry.

• sp_set_metadata – Changes particular metadata parameters.

Documentation for MapMarker ESP for SQL ServerSeveral sources of documentation are provided to assist you with using MapMarker ESP for SQL Server effectively. We recommend you read the following documents carefully before using MapMarker ESP for SQL Server:

• Getting Started with MapMarker ESP for SQL Server (this document) provides installation instructions, gives a product overview, and information on how to use the product.

• For assistance with MapMarker Server installation and usage, see the HTML document Getting Started with MapMarker Server, provided with that product.

• For more information on geocoding and the MapMarker Geocoding Engine, refer to the MapMarker Product Guide and Online Help.

• For information related to SQL Server and SpatialWare operations, see the SQL Server and SpatialWare documentation sets respectively.

6

Chapter 2: Installation

System Requirements• Windows NT 4.0 (certified with Service Pack 6a) or Windows 2000 (certified with

Service Pack 1).

• Approximate hard disk space needed:

– 928K to install software.

Also refer to the hardware configuration requirements described in your SQL Server and MapMarker Server documentation. MapMarker ESP for SQL Server has the same requirements as these.

Installing MapMarker ESP for SQL Server

Before you startWe recommend that you install MapMarker ESP for SQL Server, MapMarker Server and MapMarker on the same machine as SQL Server.

The following is the recommended order in which to install SQL Server, SpatialWare (if used), MapMarker, MapMarker Server and MapMarker ESP for SQL Server.

1. Install SQL Server. Please refer to your SQL documentation for installation and setup instructions.

Note: If you have a license and wish to install SpatialWare, you must do so now. You must

ensure that your database is prepared for SpatialWare. This involves creating spatial tables or spatializing existing tables, populating them and creating R-tree indexes to enable spatial querying. Please refer to your SpatialWare for SQL Server documentation for installation and setup instructions.

2. Install MapMarker 6.x, or MapMarker Plus 6.x. It is advisable to install this on the same machine as SQL Server. Test that MapMarker is installed correctly and will run. MapMarker Server is automatically installed with MapMarker or MapMarker Plus. Refer to the MapMarker Supplemental Guide or Getting Started for installation instructions. You will be required to call MapInfo Corporation for a data access code during the installation.

3. Start the MapMarker Server by choosing Start>Settings>Control Panel>Services>choose MapMarker Server and click Start. This must be started for MapMarker ESP for SQL Server to run correctly.

You can also start MapMarker Server as a console application.


Note: If you have SQL Server running on your machine, you must stop it before you install

MapMarker ESP for SQL Server. MapMarker ESP uses the same .dll as SQL Server for installation. This will be locked if SQL Server is running and you will not be able to install MapMarker ESP successfully.

InstallationFollow these instructions if you are installing MapMarker ESP for SQL Server for the first

time. If you are re-installing MapMarker ESP for SQL Server, please see Reinstalling MapMarker ESP for SQL Server on page 13.

To install MapMarker ESP for SQL Server software:

1. Insert the MapMarker ESP for SQL Server CD. A setup install wizard starts automatically.

If the setup wizard does not start automatically choose Run from the Windows NT or 2000 Start menu. In the Open: box type e:\setup.exe, where e is the CD-ROM drive letter. The MapMarker ESP for SQL Server setup wizard displays. Alternatively select the Browse button from the Run window. Find e:\setup.exe, select it and click open.

2. At the Welcome dialog click Next to proceed.

3. Click Yes to accept the License Agreement.

4. You will be asked to make sure SQL Server is not running. SQL Server must not be running to install MapMarker ESP for SQL Server successfully. Is SQL Server stopped? If SQL Server is stopped click Yes to proceed. If SQL Server is not stopped, click No. Setup will exit. You must stop SQL Server running and start installation again.

5. At the Choose Destination Dialog, to accept the default location select Next. MapMarker ESP for SQL Server automatically locates where the latest version of MapMarker is installed and defaults as ..\MMESP in the same directory. e.g., d:\MapMarker Plus 6.2\MMESP, where MapMarker Plus 6.2 is the most recent version of MapMarker and d is the hard drive. You may Browse to another location,

8


but it is advisable to install this software in the same directory as MapMarker. Click Next.

6. At the Setup type dialog, choose from Typical, Compact or Custom installation. Default is Typical, and is suggested for most users, Compact installs the minimum required options and Custom allows users to select components.

9


7. If you wish to perform a Custom installation, options include program files, documentation and example files. Check the components you want to install. Click Next.

8. Setup then installs the required files and restarts SQL Server and configures the MapMarker components. This is done by automatically running the mmESPinstall.sql script.

9. At the Setup Complete dialog click Finish. Setup is complete.

10


Note: If at anytime during setup you wish to stop installing select Cancel. At the Exit

Setup dialog select Exit Setup to exit, or Resume to continue installation.

File locationsThe files associated with MapMarker EPS for SQL Server can be found by default in the MapMarker Plus 6.2\MMESP directory. This is where the MmESPinstall.sql, MmESPuninstall.sql (which creates the tables and stored procedures and registers the extended procedures included with MapMarker ESP for SQL Server) and the MmESPinstall.log files can be found. Also included here is the \demo directory which includes the example files findlocation.sql, geocodeTable.sql and geocodeTrigger.sql. The \doc directory includes relevant documentation in HTML files – index.htm.

The .dll for MapMarker ESP for SQL Server, mmsql.dll, is located in the Microsoft SQL Server\Mssql\binn directory.

11


Installation ErrorsMost of the errors which may occur during installation will generally be associated with SQL Server.

If you receive an error message during installation, write down the location of the log file. Following installation find the log file e.g. MmESPinstall.log and investigate the error.

The most common causes of problems are:

• Errors related to the SQL Server connection. Ensure SQL Server is running when testing MapMarker ESP for SQL Server and that it is able to connect. Consult your SQL Server documentation for more detailed information about this.

• Errors related to user privileges. Ensure you have permission to create tables and perform operations on your data set. Contact your system administrator to change these settings if necessary.

Reinstalling MapMarker ESP for SQL ServerFollow these instructions if you wish to re-install MapMarker ESP for SQL Server.

To reinstall MapMarker ESP for SQL Server, you should run the setup once again, which will install the necessary files and procedures to the MapMarker Plus 6.2 directory, by default. This involves the same procedure as outlined in the section on Installation on page 8. Please refer to this section for further details about installing MapMarker ESP for SQL Server.

12


Uninstalling MapMarker ESP for SQL ServerMapMarker ESP for SQL Server installs a program on your system that you can use to remove MapMarker ESP for SQL Server from your system when necessary. There are three (3) methods to uninstall MapMarker ESP for SQL Server:

1. Remove the program from the Control Panel using the Add/Remove programs option. Choose Start>Settings>Control Panel>Add/Remove Programs>selecting MapInfo MapMarker ESP from the list of programs and clicking OK.

OR

2. Execute the MmESPuninstall.sql script. Select Start>Programs>SQL Server program group>Query Analyzer, paste the script into a window in SQL Server’s Query Analyzer and run. Running the MmESPuninstall.sql script will drop the misys schema and any tables within this schema.

OR

3. Execute the MmESPuninstall.sql script using a DOS command line. Open this by choosing Start>Run. Type cmd in the Open: box. A command line window will appear. The type the following line, which will log you into ISQL and run the install script.

isql -S server_name -u Login_id -p Password -i "d:\Program Files\MapMarker Plus 6.2\MMESP\MmESPuninstall.sql"

where:

server_name is the name of the server you are using.

Login_id is your login id.

Password is your system password.

"d:\Program Files\MapMarker Plus 6.2\MMESP\MmESPuninstall.sql" is the location of your MmESPuninstall.sql file.

4. Uninstallation of MapMarker ESP for SQL Server completes. The folders and files will remain in the MMESP directory, but the Extended Stored Procedures will be removed from the master database in SQL Server.

13


14

Chapter 3: Working with MapMarker ESP for SQL Server

MapMarker ESP for SQL Server is made up of two (2) types of features. The first are a set of Extended Procedures which include procedures to geocode single, or tables of, addresses. The second are Settings which include preferences table and metadata table which store definitions used in geocoding. The preferences table stores definitions and information about geocoding preferences. The metadata table stores information about geocoding requests.

About GeocodingGeocoding is a process where a record containing address information is matched to an address with coordinates in a search dictionary. If a match is found, the geographic coordinates of the match record are assigned to the input address to complete the process.

Records are geocoded to street level. If a street level match cannot be made, MapMarker will attempt to match it to the nearest postal centroid. You can select different preferences to modify your results when geocoding. These preferences allow you to choose the parameters by which you want to geocode. See Preferences on page 29 for more information.

Direct postal centroid geocoding and Address Dictionary browsing are not supported.

Preparing to GeocodeBefore you can geocode your records, there are a few things to consider. First you need to define your requirements. Do you simply want the latitude/longitude of what MapMarker thinks is the "best match"? If address elements are not the same, which of them should take preference?

For geocoding a table you may need to add columns to hold the output information you want returned. This may include candidate street, city, state, postal code, latitude, longitude, postal carrier route, census, etc. The source and results tables must be linked by a common (primary) key. It is recommended that the tables are related in a one-to-one relationship then each address record in the source table will have a corresponding record in the results table connected by the key values. You must also ensure your columns are the correct type and length. Check this with the requirements of the function you are going to use. It is your responsibility to do this.

MapMarker ESP for SQL Server provides default preference settings for geocoding as described in Preferences on page 29. If you want to change these settings to your own options, you must do this before starting to geocode.


You must ensure the tables you are using have been described in the metadata table before geocoding. See Metadata on page 37 for more details.

Remember that for fastest geocoding operations, it is recommended that you sort your table by ZIP Code before running MapMarker. Please see your MapMarker documentation for more information.

When the appropriate columns have been added and populated, you are ready to geocode.

Extended Stored ProceduresGeocoding a database using MapMarker ESP for SQL Server can be done in two ways: geocoding either a table of addresses or a single address.

To geocode an entire table (or a portion selected by a where clause), use the sp_geocodeTable and sp_geocodeTableLastLine functions. See Geocoding a Table of Addresses on page 17 for more information.

To geocode single addresses, use the sp_geocodeAddress and sp_geocodeAddressLastLine functions. These procedures return results in a result set of one (1) or more rows. See Geocoding a Single Address on page 20 for more information.

To geocode single addresses where only one (1) row of information is required (in separate fields) or if you wish to use the database trigger functionality, use the sp_findLocation and sp_findLocationLastLine functions. These functions take different parameters if used for the trigger. See Triggers on page 24 for more information.

These functions are executed in the Query Analyzer in SQL Server. Please refer to your SQL Server documentation for more information on this.

16


Geocoding a Table of Addresses

Procedures sp_geocodeTable, sp_geocodeTableLastLine

Use the sp_geocodeTable and sp_geocodeTableLastLine functions to geocode a table of addresses.

sp_geocodeTable is used if the input data set is comprised of separate fields. i.e., firm, address, city, state, postalcode and postaladdoncode are all given as separate column

headings.

sp_geocodeTableLastLine is used if the input data is given as a "last line". LastLine is a single string containing the address information in an unparsed form i.e., firm, address and LastLine (which includes city, state, postalcode, and postaladdoncode fields).

You must look at your data to see what form your tables take and choose the correct function.

Before geocoding, the tables must be described in the metadata table, see Metadata on page 37. If the data in your input table contains fields which do not appear below, you must change your tables.

The descriptions below give the composition of the source tables of address for each function.

sp_geocodeTable

sp_geocodeTableLastLine

firm varchar(256), Input: The firm name.

address varchar(256), Input: The street portion of the address

city varchar(40), Input: The city portion of the address.

state (country_division) varchar(40), Input: The state, province, or other country division portion of the address.

postalcode varchar(10), Input: The postal code information for the address.

postaladdoncode varchar(10); Input: The additional postal code information, such as the +4 ZIP Code extension in the U.S.


address varchar(256), Input: The street portion of the address

lastline varchar(40), Input: String containing the unparsed city, state (country_division), postalcode and postaladdoncode information for the address.

17


The following shows the parameters of both the sp_geocodeTable and sp_geocodeTableLastLine functions.

sp_geocodeTable and sp_geocodeTableLastLine

Note: The functions read the supplied parameters in order. If a parameter is not required it

must not be omitted. It must either be set to null or left as an empty string.

Example: sp_geocodeTable

exec sp_geocodeTable ’database_name.dbo.input_table’, ’database_name.dbo.output_table’, null, ’preference’;

These procedures return a result set showing the following statistics from the geocoding run:Total rowsTimeMatchedNot MatchedDuplicatedStreet Matched [one of the following codes is returned]

S5 – Street LevelS4 – ShapePath

input_table varchar(256), Input: The name of the table containing the address information. (Required)

[output_table varchar(256)], Output: The name of the destination table. This may be null i.e., where the output table is the same as the input table. If you would like to see the result codes or further information in your output table you must add these columns and ensure they are described in the metadata table also. (Optional)

[where varchar(2047)], Input: A string to be appended to the where clause. To geocode only pre-selected rows, specify the where string without the ’where’ keyword. (Optional) e.g. ’city = ’’Albany’’ and country = ’’US’’ or city = ’’Troy’’’

preference varchar(30)]; Input: A @preferenceName from the mm_preferences table (See Preferences on page 29). If preference is null, left as an empty string, or not specified in the execute statement, then the default preference as defined in mm_preferences will be used. In turn if mm_preferences does not have a default preference then the default preference from the Geocode Engine will be used. (Optional)

18


S3 – ZIP+4S2 – ZIP+2S1 – ZIP CodeSX – Street IntersectionS0 – No Centroid Zip

Centroid [one of the following codes is returned]Z3 – ZIP+4Z2 – ZIP+2Z1 – ZIP CodeZ0 – No Centroid

Intersection MatchesAddresses Corrected

House NumberStreet NameCityPostalcode

The data is returned as a row. Each of the previous fields being a column heading.

The demo script geocodeTable.sql, found in the MapMarker\MMESP\demo directory, gives some examples of how to use the sp_geocodeTable and sp_geocodeTableLastLine procedures. See geocodeAddress.sql in Geocoding Examples on page 45 for more information.

Total Rows Time Matched Not Matched Duplicated etc.

20 2 18 2 0

19


Geocoding a Single Address

Procedures sp_findLocation, sp_findLocationLastLineThere are two (2) sets of functions provided to geocode a single address. The first are the sp_findLocation and sp_findLocationLastLine functions. If an address is geocoded successfully, these functions return fields of exactly one (1) row. It is important to note that these functions are designed to return only the best candidate even if multiple candidates are available. Therefore a situation may arise where a poor geocode is returned even though it is the best candidate.

These functions are also used (with different parameters) with database triggers. This is the automatic updating of tables when new addresses are added or existing ones updated. See Triggers on page 24 for more information.

sp_findLocation is used if the input data set is comprised of separate fields. i.e., firm, street, city, state, postalcode, postaladdoncode, citysubdivision and preference are all given as separate column headings.

sp_findLocationLastLine is used if the input data is given as a "last line". LastLine is a single string containing the address information in an unparsed form i.e., firm, street, preference and LastLine (which includes city, state, postalcode, postaladdoncode and citysubdivision fields).

Note: MapMarker ESP for SQL Server only accepts one line of street information in the input

address.

sp_findLocation and sp_findLocationLastLine do not use tables for their input data, they get data in the form of parameters. The parameters for each function are outlined below.

sp_findLocation


street varchar(256), Input: The street portion of the address




[postaladdoncode varchar(10),] Input: The additional postal code information, such as the +4 ZIP Code extension in the U.S.

20


1 This feature is not supported in the current release of the MapMarker ESP for SQL Server.

sp_findLocationLastLine

Examples of how to perform single geocodes can be found in the ..\MMESP\demo folder in your MapMarker directory. The example file findLocation.sql geocodes single addresses which return fields of exactly one (1) row. For more information see Geocoding Examples on page 45.

Example: sp_findLocation

sp_findLocation ’MapInfo’, null, ’Troy’, null, ’12180’;

Example: sp_findLocationLastLine

sp_findLocationLastLine ’MapInfo’, ’1 Global View’, ’Troy NY 12180’;

The demo script findLocation.sql, found in the MapMarker\MMESP\demo directory, gives some examples of how to use the sp_findLocation and sp_findLocationLastLine procedures. See findLocation.sql in Geocoding Examples on page 45 for more information.

[citysubdivision1 varchar(10)], Input: The city subdivision. MapMarker ESP for SQL Server only uses this for Puerto Rico addresses.

[preference varchar(30)]; Input: The preference name.


street varchar(256), Input: The street portion of the address.

lastline varchar(256), Input: String containing the unparsed city, state and postalcode information for the address.

[preference varchar(30)]; Input: The preference name.

21


Procedures sp_geocodeAddress, sp_geocodeAddressLastLineThe second type of functions are sp_geocodeAddress and sp_geocodeAddressLastLine. These return a result set of one (1) or more rows.

sp_geocodeAddress is used if the input data set is comprised of separate fields. i.e., firm, street, city, state (country_division), postalcode, postaladdoncode, citysubdivision and preference are all given as separate column headings.

sp_geocodeAddressLastLine is used if the input data is given as a "last line". LastLine is a single string containing the address information in an unparsed form i.e., firm, street, preference and LastLine (which includes city, state, postalcode, postaladdoncode and citysubdivision fields).

sp_geocodeAddress and sp_geocodeAddressLastLine do not use tables for their input data, they get data in the form of parameters. The parameters for each function are outlined below.

sp_geocodeAddress







[postaladdoncode varchar(10),] Input: The additional postal code information, such as the +4 ZIP Code extension in the U.S.

[citysubdivision1 varchar(10),] Input: The city subdivision. MapMarker ESP for SQL Server only uses this for Puerto Rico addresses.

[preference varchar(30);] Input: The preference name

22


sp_geocodeAddressLastLine

Note: The functions read the parameters in order. If a parameter is not required it must not

be omitted. It must either be set to null or left as an empty string.

Please note that these functions are not used with the trigger capabilities. This is because they return a result set, as opposed to a single row. The trigger function needs a single row of results to operate.

Examples of how to perform single geocodes which return a result set can be found in the ..\MMESP\demo folder in your MapMarker directory. The example file geocodeAddress.sql geocodes a single address which returns a result set of one (1) or more rows. For more information see Geocoding Examples on page 45 .

Example: sp_geocodeAddress

exec sp_geocodeAddress ’MapInfo’, null, ’Troy’, null, ’12180’, ’8399’;

Example: sp_geocodeAddressLastLine

exec sp_geocodeAddressLastLine ’MapInfo’, ’1 Global View’, ’Troy NY

12180 8399’;

The demo script geocodeAddess.sql, found in the MapMarker\MMESP\demo directory, gives some examples of how to use the sp_geocodeAddress and sp_geocodeAddressLastLine procedures. See geocodeAddress.sql in Geocoding Examples on page 45 for more information.



lastline varchar(256), Input: string containing the unparsed city, state and postalcode information for the address.

[preference varchar(30);] Input: The preference name

23


TriggersTriggers allow automatic single address geocoding. When an address is updated or added to a table the trigger automatically geocodes the changes. The sp_findLocation and sp_findLocationLastLine procedures geocode a single address and return the result into variables (shown below as the output fields).

sp_findLocation is used if the input data set is comprised of separate fields. i.e., firm, street, city, country_division, postalcode, postaladdoncode, citysubdivision and preference are all given as separate column headings.

sp_findLocationLastLine is used if the input data is given as a "last line". LastLine is a single string containing the address information in an unparsed form i.e., firm, street, preference and LastLine (which includes city, country_division, postalcode, postaladdoncode and citysubdivision fields).

You must look at your data to see what form your tables take and choose the correct function.

These procedures do not have any optional parameters – a description is given below. You will notice that the output fields for both functions include longitude, latitude, precision, census, result and sw_geometry. These are fields provided by MapMarker ESP for SQL Server during processing.

The parameters shown below are used with sp_findLocation and sp_findLocationLastLine in the trigger code which is used to automatically update your table.

sp_findLocation




country_division varchar(40), Input: The state, province, or other country division portion of the address.


postaladdoncode varchar(10), Input: The additional postal code information, such as the +4 ZIP Code extension in the U.S.

citysubdivision1 varchar(40), Input: The city subdivision. MapMarker ESP for SQL Server only uses this for Puerto Rico addresses.

24


sp_findLocationLastLine

preference varchar(30), Input: The preference name.

firm output varchar(256), Output: The firm name.

street output varchar(256), Output: The street portion of the address

city output varchar(40), Output: The city portion of the address.

country_division output varchar(40), Output: The state, province, or other country division portion of the address.

postalcode output varchar(10), Output: The postal code information for the address.

postaladdoncode output varchar(10), Output: The additional postal code information, such as the +4 ZIP Code extension in the U.S.

citysubdivision1 output varchar(40), Output: The city subdivision. MapMarker ESP for SQL Server only uses this for Puerto Rico addresses.

longitude output float, Output: The latitude value for a match candidate.

latitude output float, Output: The longitude value for a match candidate.

precision output int, Output: A number that identifies match precision (street level, shape path, intersection or ZIP centroid).

census output varchar(21), Output: Census block tabulation number.

result output varchar(12), Output: Geocoding result code.

sw_geometry output binary(56); Output: The spatial geometry format which may be used with SpatialWare (if licensed).



lastline varchar(40), Input: String containing the unparsed CITY, COUNTRY_DIVISION and POSTALCODE information for the address.

preference varchar(30), Input: The preference name.

firm output varchar(256), Output: The firm name.

street output varchar(256), Output: The street portion of the address

25



The trigger is implemented by adding the sql code to a table on which you wish to perform automatic updates. When you change the address of a firm, the table is automatically updated with the new geocode.

An excerpt from the example file geocodeTrigger.sql is shown overleaf. It is found in the MapMarker\MMESP\demo directory. It shows an example of geocoding single addresses using triggers. The example file is provided in two (2) sections and the first is shown here. The first is an update trigger (for use when information in the table is changed or updated), the second is an insert trigger (for use when rows are added to the table).

city output varchar(40), Output: The city portion of the address.

country_division output varchar(40), Output: The state, province, or other country division portion of the address.

postalcode output varchar(10), Output: The postal code information for the address.

postaladdoncode output varchar(10), Output: The additional postal code information, such as the +4 ZIP Code extension in the U.S.

citysubdivision1 output varchar(40), Output: The city subdivision. MapMarker ESP for SQL Server only uses this for Puerto Rico addresses.

longitude output float, Output: The latitude value for a match candidate.

latitude output float, Output: The longitude value for a match candidate.

precision output int, Output: A number that identifies match precision (street level, shape path, intersection or ZIP centroid).

census output varchar(21), Output: Census block tabulation number.

result output varchar(12), Output: Geocoding result code.

sw_geometry output binary(56); Output: The spatial geometry format which may be used with SpatialWare (if licensed).

26


Example-- Update triggerif exists (select * from sysobjects where id = object_id(’geocode’) and OBJECTPROPERTY(id, ’IsTrigger’) = 1)DROP TRIGGER geocodegoCREATE TRIGGER geocode ON mm_inoutFOR UPDATEASdeclare @firm varchar(256),@street varchar(256),@city varchar(256),@state varchar(256)declare @zip varchar(10),@plus4 varchar(10),@urb varchar(40)declare @ofirm varchar(256),@ostreet varchar(256),@ocity varchar(40),@ostate varchar(40)declare @ozip varchar(10),@oplus4 varchar(10),@ourb varchar(40)declare @lat float, @lon float, @pres intdeclare @census varchar(21), @result varchar(12)declare @sw_geometry binary(56)declare @preference varchar(30)declare @prim varchar(50)declare ins cursor local for select prim, firm, adr, city, state, zip, zip4 from insertedbegin set nocount on set @preference = ’’

if update(adr) or update(firm) or update(city) or update(state) or update(zip) or update(zip4)begin if cursor_status(’local’,’ins’) <> -1 close ins open insFETCH NEXT FROM ins into @prim,@firm, @street, @city, @state, @zip, @plus4WHILE (@@FETCH_STATUS = 0)beginexec sp_findLocation @firm,@street,@city,@state,@zip,@plus4,@urb, @preference,@ofirm output,@ostreet output,@ocity output,@ostate output,@ozip output,@oplus4 output,@urb output,@lon output,@lat output,@pres output,@census output,@result output,@sw_geometry outputupdate mm_inout set ofirm=@ofirm,oadr=@ostreet,ocity=@ocity, ostate=@ostate,ozip=@ozip,ozip4=@oplus4,olat=@lat,olong=@lon, precisionname=@pres,ocensus=@census,result=@result, sw_geometry=@sw_geometry WHERE prim = @primFETCH NEXT FROM ins into @prim,@firm,@street,@city,@state,@zip,@plus4

27


end close ins end set nocount offendgo

For more information on using the trigger example, see Geocoding Examples on page 45.

28


Settings

PreferencesThe table mm_preferences stores definitions of geocoding preferences. One of them is marked as default.

A preference is used to define how a geocode request is handled. It contains several different setting options. This enables you to define the settings you require for your geocoding. Preferences can be given a name and may be used by calling it. There are three main types of settings: MapMarker Server, Geocode and Result settings.

The MapMarker Server settings define a host name, HTTP router, URL, and a serial number which is passed to the Geocode Engine.

The Geocode settings fine tune a geocode request by defining match requirements such as exact house number match, street name, postal code, intersection and so on.

The Result settings define what kind of information will be returned as a result for the

candidate input information. These include Last line info (city, state, postal code, postal info1 carrier route, LACS, delivery point), firm’s name, street, census block, spatial BLOB and number of candidates.

Some preferences such as batchCount are tuning parameters which customize the geocoding output, but do not affect the process itself.

mm_preferences provides default settings for geocoding (given here). If you wish to change these settings you must do so before you start to geocode.

29


MM_PREFERENCES TABLE

Field Type Description

preferenceName char(30) A unique identifier or name for the preferences.

serialNumber char(30) The serial number for the geoengine if it has been started in restricted mode. Default is null.

clientID1 char(20) The ID for MapMarker ESP for SQL Server schema used. Default is ’misys’.

httpServer char(80) ISS host name or IP address, which routes RPC requests to the MapMarker Server if specified, else NULL. This is only required if MapMarker Server is on a machine which is remote to the SQL Server database.

tcpServerHost char(80) The host name or IP address of the machine where the MapMarker Server is located. Default ’localhost’.

countryID char(2) The country ID defines the international MapMarker Server setting which is used for geocoding. Default ’US’.

exactMatchHouseNumber char(1) T to require exact match on house number. T=True, F=False. Default is T.

exactMatchStreetName char(1) T to require exact match on street name. T=True, F=False. Default is F.

exactMatchPostalCode char(1) T to require exact match on postal code. T=True, F=False. Default is F.

matchIntersections char(1) T to attempt street intersection matching on input addresses. T=True, F=False. Default is F.

useCASSMode char(1) T to use the USPS CASS standards when geocoding. Overrides other preference settings. T=True, F=False. Default is F.

expandSearch char(1) T to expand the search area for finding candidates. T=True, F=False. Default is F.

limitExpandedSearch char(1) T to restrict the candidates returned by the expanded search to the current countryDivision. T=True, F=False. Default is T.

expandRadius int The radius of the expanded search in miles. (0-99) Default is 10.

30


distUnit int The distance unit used for the linearOffset and perpendicularSetback: 0 = foot; 1=degree; 2=inch; 3=link; 4=survey foot; 5=yard; 6=rod; 7=chain; 8=mile; 9=nautical mile; 10=millimeter; 11=centimeter; 12=meter; 13=kilometer. Default is 0.

linearOffset float The position of the geocoded point with respect to the nearest street corner. Default is 20.

perpendicularSetback float The position of the geocoded point with respect to the center of the street line. Default is 25.

miscPrefString1 char(80) Provides additional preference information when a non-U.S. geocoding engine is used for international addresses. Default is null.

maxNumCandidates int The maximum number of candidates to return for a geocode request. Default is 5.

maxNumRangesPerCandidate1 int The maximum number of address ranges to return for each candidate. Default is 5.

multiMatched char(1) N indicates that an address with several close candidates will not be geocoded, F means return the first close candidate. N=No, F=First. Default is F.

unMatched char(1) N indicates that an address with several close candidates but no exact match will not be geocoded, F means return the first close candidate, and C means return the postal centroid coordinates. N=No, F=First, C=Centroid. Default is N.

returnCloseCandidatesOnly char(1) T indicates that only close match candidates will be returned, F means return all candidates. T=True, F=False. Default is T.

returnFirm2 char(1) T indicates that the candidate firm name will be returned. T=True, F=False. Default is T.

returnStreets2 char(1) T indicates that the candidate street address (and street2 if localized) information will be returned. T=True, F=False. Default is T.

returnLastLineInfo2 char(1) T indicates that the candidate city subdivision, city, state and postal code (and postal code add-on if localized) will be returned. T=True, F=False. Default is T.


31


1 This feature is not supported in the current release of MapMarker ESP for SQL Server.

2 When these preferences are turned off (set to False), the candidates will only show latitude, longitude, result code, and precision.

3 Effective only in table geocoding mode.

returnPostalInfo1, 2 char(1) T indicates that the candidate carrier route, check digit, LACS status and delivery point will be returned. T=True, F=False. Default is T.

returnCensus2 char(1) T indicates that the candidate census block information will be returned. T=True, F=False. Default is T.

returnSpatial2 char(1) T indicates that the spatial BLOB will be returned. T=True, F=False. Default is F.

stopOnError char(1) T indicates that processing will not be continued if any geocoding/database errors occur. T=True, F=False. Default is F.

mode3 char(1) Defines how MapMarker ESP for SQL Server will store results in a destination table.I=indicates the cartridge will attempt to Insert a result into the destination table, and will update if this is not possible. (i.e. if the result already exists in the destination table)U=indicates the cartridge will attempt to Update the destination table, and will insert if updating is not possible. Default is I.

batchCount int The number of grouped geocode requests returned in one batch when geocoding a table. Since returned information can be lengthy, it is recommended that your batch size is below 20. This is a tuning parameter and will not affect the geocoding itself.

Default_Preference char(1) T indicates that the current preference is set as the default. T=True, F=False. Default is ’ ’.


32


Managing Geocoding PreferencesMapMarker ESP for SQL Server has procedures which can be used to manage preferences and modify them to your needs. MapMarker ESP for SQL Server is initially set to use the same defaults as MapMarker, including a required exact match to house number and a relaxed match to street name and postal code. If you wish, you can leave the defaults as they are.

The sp_create_preference procedure creates a new preference and saves it in the mm_preferences table. The procedure has one (1) required parameter : @preferenceName, and a set of further optional parameters. If you decide not to set all the optional parameters, you should specify a logical name for your preference to allow you to identify which parameters you have set. The serialNumber, clientID, and HTTP information describe the connection to the MapMarker Server. batchCount is for table geocoding. The remaining parameters are settings for the geocoding engine. See Preferences on page 29 for a description of these settings.

sp_create_preference

@preferenceName SYSNAME,

[@serialNumber SYSNAME = null,]

[@clientID SYSNAME = ’misys’,]

[@httpServer SYSNAME = null,]

[@tcpServerHost SYSNAME = ’localhost’,]

[@countryID SYSNAME = ’US’,]

[@exactMatchHouseNumber char(1) = ’T’,]

[@exactMatchStreetName char(1) = ’F’,]

[@exactMatchPostalCode char(1) = ’F’,]

[@matchIntersections char(1) = ’F’,]

[@useCASSMode char(1) = ’F’,]

[@expandSearch char(1) = ’F’,]

[@limitExpandedSearch char(1) = ’T’,]

[@expandRadius decimal = 10,]

[@distUnit decimal = 0,]

[@linearOffset decimal = 20,]

[@perpendicularSetback decimal = 25,]

[@miscPrefString decimal = null,]

[@maxNumCandidates decimal = 5,]

[@maxNumRangesPerCandidate decimal = 5,]

[@returnCloseCandidatesOnly char(1) = ’T’,]

33


You can create a new preference and specify the parameters you require as shown in the two (2) examples below:

Example: sp_create_preference

sp_create_preference ’name1’, @expandSearch=’T’;sp_create_preference ’name1’, @returnSpatial=’T’, @useCASSMode=’T’;

name1 = The name you wish to call your preference.

Deleting a preferenceThis procedure deletes an existing preference. If the default preference is deleted, then the first preference in the mm_preferences table is set as default. You invoke the procedure by supplying the preference name to be deleted.sp_delete_preference @preferenceName;

Example: sp_delete_preference

sp_delete_preference ’name1’;

name1 = The preference you wish to delete.

[@multiMatched char(1) = ’F’,]

[@unMatched char(1) = ’S’,]

[@returnFirm char(1) = ’T’,]

[@returnStreets char(1) = ’T’,]

[@returnLastLineInfo char(1) = ’T’,]

[@returnPostalInfo char(1) = ’T’,]

[@returnCensus char(1) = ’T’,]

[@returnSpatial char(1) = ’F’,]

[@stopOnError char(1) = ’F’,]

[@mode char(1) = ’I’,]

[@batchCount decimal = 20,]

[@default_preference char(1) = ’’];

34


Assigning a default preferenceThis procedure assigns @preferenceName as a default preference. The corresponding default_preference entry in table MM_PREFERENCES is changed to ’T’ and all the others in that column are changed to ’F’.sp_set_default_preference @preferenceName;

Example: sp_set_default_preference

sp_set_default_preference ’name1’;

name1 = The preference you wish to set as default.

Printing the default preference nameThis procedure prints to screen the name of the preference that is currently set as default. sp_get_default_preference @preferenceName;

Example: sp_get_default_preference

sp_get_default_preference;

The output from this procedure is shown below.

Setting a preferenceThis procedure allows you to change the following settings for a particular @preferenceName. Given below are the default settings for this procedure.

sp_set_preference

preferenceName

name1

@preferenceName SYSNAME,

[@serialNumber SYSNAME = null,]

[@clientID SYSNAME = null,]

[@httpServer SYSNAME = null,]

[@tcpServerHost SYSNAME = null,]

[@countryID SYSNAME = null,]

[@exactMatchHouseNumber char(1) = null,]

[@exactMatchStreetName char(1) = null,]

[@exactMatchPostalCode char(1) = null,]

[@matchIntersections char(1) = null,]

[@useCASSMode char(1) = null,]

[@expandSearch char(1) = null,]

35


sp_set_preference allows you to change one or more parameters at a time. Refer to the two (2) examples shown below.

Example: sp_set_preference

sp_set_preference ’name1’, @returnSpatial=’T’;

andsp_set_preference ’name1’, @expandSearch=’F’, @matchIntersections=’T’;

name1 = The existing preference you wish to change.

[@limitExpandedSearch char(1) = null,]

[@expandRadius decimal = null,]

[@distUnit decimal = null,]

[@linearOffset decimal = null,]

[@perpendicularSetback decimal = null,]

[@miscPrefString decimal = null,]

[@maxNumCandidates decimal = null,]

[@maxNumRangesPerCandidate decimal = null,]

[@returnCloseCandidatesOnly char(1) = null,]

[@multiMatched char(1) = null,]

[@unMatched char(1) = null,]

[@returnFirm char(1) = null,]

[@returnStreets char(1) = null,]

[@returnLastLineInfo char(1) = null,]

[@returnPostalInfo char(1) = null,]

[@returnCensus char(1) = null,]

[@returnSpatial char(1) = null,]

[@stopOnError char(1) = null,]

[@mode char(1) = null,]

[@batchCount decimal = null];

36


MetadataThe table mm_geocode_metadata is used to store information about the input and output tables used in a table geocoding request. The metadata contains a fully qualified table name, type of table (input, output, or input/output), and the column names of address and result information.

A source table and a destination table must be described in the metadata before a table can be geocoded. The metadata table can keep only one metadata row per source/destination table. This means that if the input table can be geocoded into itself it should be described using the input/output format. i.e. have one (1) table which has columns for the output data in addition to the input data. e.g., firm, street, city,......firmOutput, streetOutput, cityOutput.

Most of the columns in the metadata table store names taken from the columns in the source/destination tables.

If your fields are longer than those given below, they will be truncated. It is your responsibility to ensure your tables are formatted correctly.

MM_GEOCODE_METADATA TABLE

Column Type Description Type of source/destination column

tableName varchar(256) Fully qualified name of table

input char(1) T indicates the table may be used as a source of addresses. T=True, F=False.

output char(1) T indicates the table may be used for storing found candidates. T=True, F=False.

primarykeyname2 varchar(32) Name of Primary key column. double, varchar, int, float

firm varchar(32) The firm name. varchar(256)

address varchar(32) The first line of the address. varchar(256)

address21 varchar(32) The second line of the address.This is not used by MapMarker ESP for SQL Server. It may be used to return international street address information by a different geocoding engine.

varchar(256)

citySubdivision1 varchar(32) MapMarker ESP for SQL Server only uses this for Puerto Rico addresses.

varchar(40)

city varchar(32) The city portion of the address. varchar(40)

37


countryDivision varchar(32) The state, province, or other country division portion of the address.

varchar(40)

country1 varchar(32) This is a 2 character code representing the country portion of the address. e.g. CA is Canada.

varchar(2)

postalCode varchar(32) The postal code information for the address.

varchar(10)

postaladdoncode varchar(32) The additional postal code information, such as the +4 ZIP Code extension in the US.

varchar(10)

lastline varchar(32) The unparsed city, state/province, and postal information.

varchar

oFirm varchar(32) The output column for firm name. varchar(256)

oAddress varchar(32) The output column for the first line of the address.

varchar(256)

oAddress21 varchar(32) The output column for the second line of the address.

varchar(256)

oCitysubdivision1 varchar(32) The output column for the city subdivision.

varchar(40)

oCity varchar(32) The output column for the city. varchar(40)

oCountrydivision varchar(32) The output column for the country division.

varchar(40)

oPostalcode varchar(32) The output column for the postal code.

varchar(10)

oPostalAddonCode varchar(32) The output column for the postal add on code.

varchar(10)

resultCode varchar(32) The geocoding code that describes a candidate’s match status.

varchar(10)

censusBlock varchar(32) U.S. Census Bureau code that uniquely identifies a geographic area for census reporting.

varchar(15)

deliveryPoint1 varchar(32) A two-digit code that along with the Check Digit is used to form the delivery point barcode on U.S. mail pieces.

char(2)

checkDigit1 varchar(32) A one-digit code that together with Delivery Point is used to form the delivery point bar code on U.S. mail pieces.

char(1)


38


1 This feature is not supported in the current release of MapMarker ESP for SQL Server. It is not supported by MapMarker server.

2 MapMarker ESP for SQL Server provides a flexible schema to support different combinations of source/destination primary keys:

Note on Primary Keys in mm_geocode_metadata• If a destination table does not have a primary key, all rows will be inserted without a

primary key value.

• If the primary key of a source table has a different primary key from the destination table or it is of a shorter length (varchar type), the value of an internal counter (of length 1 to n) is used as a unique primary key value.

• If the source and destination primary keys are different but have the same type and length, the primary key value will be copied from source to destination.

• MapMarker ESP for SQL Server does not check for an existing primary key in the actual tables, but only in the metadata information.

The procedure sp_create_metadata is used to create a new metadata entry. The procedure does not check for the existence of a table, however the table name should be fully qualified (meaning it should contain database, schema and table names). i.e., [db_name].[db_owner].[table_name]. The parameters this function takes are given overleaf.

LACS1 varchar(32) The USPS LACS code. char(1)

carrierRoute1 varchar(32) The carrier route number. char(5)

longitude varchar(32) The longitude of the candidate address.

float

latitude varchar(32) The latitude of the candidate address.

float

spatial varchar(32) Spatial representation of the candidate address.

binary, image, ST_Spatial

precisionName varchar(32) Indicates the type of match candidate: street level, street intersection, shape path, point on segment with no address ranges, or ZIP Code centroid (1, 2, or 3 for ZIP Code, ZIP+2 and ZIP+4 centroids, respectively).

int

bcloseMatch varchar(32) Name of the column to write if the geocoded address is considered a close match or not.

int


39


sp_create_metadata

@tableName,

[@input char(1) = ’T’],

[@output char(1) = null],

[@primaryKeyname varchar(32) = null,]

[@firm varchar(32) = null,]

[@address varchar(32) = null,]

[@address2 varchar(32) = null,]

[@citySubdivision varchar(32) = null,]

[@city varchar(32) = null,]

[@countryDivision varchar(32) = null],

[@country varchar(32) = null],

[@postalCode varchar(32) = null,]

[@postalAddonCode varchar(32) = null,]

[@lastLine varchar(32) = null,]

[@oFirm varchar(32) = null,]

[@oAddress varchar(32) = null,]

[@oAddress2 varchar(32) = null,]

[@oCitySubdivision varchar(32) = null,]

[@oCity varchar(32) = null,]

[@oCountryDivision varchar(32) = null,]

[@oPostalcode varchar(32) = null,]

[@oPostalAddoncode varchar(32) = null,]

[@resultCode varchar(32) = null,]

[@censusBlock varchar(32) = null,]

[@deliveryPoint varchar(32) = null,]

[@checkDigit varchar(32) = null,]

[@LACS varchar(32) = null,]

[@carrierRoute varchar(32) = null,]

[@longitude varchar(32) = null,]

[@latitude varchar(32) = null,]

[@spatial varchar(32) = null,]

[@precisionName varchar(32) = null,]

[@bcloseMatch varchar(32) = null,]

40


To create metadata you must match the column headings of your source/destination tables which correspond to the parameters in the metadata table. For example if the column heading for 'firm' in your input or output table is 'FIRM_NAME’, you must enter this as the '@firm' parameter. If you do not wish to use some of the parameters you must specify them as null in the input line. Use the descriptions given in the mm_geocode_metadata table to determine the necessary input.

Example: sp_create_metadata

sp_create_metadata ’master.dbo.myTable’, T, T, prim, firm_name, address, null, null, city;

You must ensure that the parameters follow the order shown in the procedure description above, otherwise the data will be entered into the incorrect column.

It is sensible to open the mm_geocode_metadata table after creating metadata to check that the information has been entered correctly. The procedure sp_set_metadata is used to change a particular parameter of the metadata.

sp_set_metadata

@tableName,

[@input char(1) = null],

[@output char(1) = null],

[@primaryKeyname varchar(32) = null,]

[@firm varchar(32) = null,]

[@address varchar(32) = null,]

[@address2 varchar(32) = null,]

[@citySubdivision varchar(32) = null,]

[@city varchar(32) = null,]

[@countryDivision varchar(32) = null,]

[@country varchar(32) = null,]

[@postalCode varchar(32) = null,]

[@postalAddonCode varchar(32) = null,]

[@lastLine varchar(32) = null,]

[@oFirm varchar(32) = null,]

[@oAddress varchar(32) = null,]

[@oAddress2 varchar(32) = null,]

[@oCitySubdivision varchar(32) = null,]

[@oCity varchar(32) = null,]

[@oCountryDivision varchar(32) = null,]

41


You must supply the parameters in the order in which they are listed above. If you do not wish to specify a parameter you must enter null.

You do not need to quantify all the parameters which follow the ones you change.

Example: sp_set_metadata

sp_set_metadata ’master.dbo.myTable’, T, T, null, firm;

You cannot change metadata parameters to null. Typing null for a parameter merely skips over it.

[@oPostalcode varchar(32) = null,]

[@oPostalAddoncode varchar(32) = null,]

[@resultCode varchar(32) = null,]

[@censusBlock varchar(32) = null,]

[@deliveryPoint varchar(32) = null,]

[@checkDigit varchar(32) = null,]

[@LACS varchar(32) = null,]

[@carrierRoute varchar(32) = null,]

[@longitude varchar(32) = null,]

[@latitude varchar(32) = null,]

[@spatial varchar(32) = null,]

[@precisionName varchar(32) = null,]

[@bcloseMatch varchar(32) = null,]

42


Result Codes DefinedMapMarker returns a result code for every address it attempts to match. The code represents whether a match was made, the type of match it is, and gives information about the quality of the match. The result codes for geocoded addresses may be found in the resultCode column in the metadata table.

The result code is an alphanumeric code of 1-10 characters. They fall into three categories:

• Single close match to street level (S category)

• Postal Code centroid match (Z category)

• Non-matches (N category)

For S and Z categories, the first two characters represent the positional accuracy of the match, i.e., where the point for the record would spot on a street map.

For the S category matches there are an additional 8 characters that define the precision with which MapMarker matched to the individual components in the input address. If MapMarker did not match on a particular address component, the code would contain a dash. For example, a single close match to a street address that matched to all address components except house number would look like: S5-PNTSCZA.

43


S Category: Single Close Match to Street Level

Eight Additional Precision Characters:

Z Category: Postal Code Match

N Category: Non-matches

S5 Matched to a street address.

S4 Matched to an interpolated point on the street segment.

S3 Matched to a ZIP+4 centroid (centerpoint of the ZIP+4 boundary).

S2 Matched to a ZIP+2 centroid (centerpoint of the ZIP+2 boundary).

S1 Matched to a ZIP Code centroid (centerpoint of the ZIP Code boundary).

SX Matched to a street intersection.

S0 Single close match, no coordinates available.

H Matched to house number.

P Matched to street prefix.

N Matched to street name.

T Matched to street type.

S Matched to street suffix.

C Matched to city name.

Z Matched to ZIP Code.

A or U Match came from MapMarker Address Dictionary (A) or customized user dictionary (U).

Z3 ZIP+4 centroid match.

Z2 ZIP+2 centroid match.

Z1 ZIP Code centroid match.

Z0 ZIP Code match, no coordinates available.

N No close match.

NX No close street intersection match.

ND Data for given postal code or city/state is unavailable.

44


Geocoding ExamplesTo learn how to geocode to MapMarker using SQL Server, look at the demos in the ..\MMESP\demo directory on your hard drive.

They include:

createDemoTable.sql: This script creates the tables you will need to use with the other example scripts. It creates tables mm_demo, mm_inout and mm_out. You can also refer to this script when performing your own queries to ensure your tables are set up correctly. Copy the

script and paste it as a query in Query Analyzer and run. This example script does not have a return code. If the script runs successfully you will see the tables created. You should run this script first so the tables are created for the other example scripts to use.

findLocation.sql: Demonstrates how to geocode a single address which returns fields of exactly one (1) row. Copy the script and paste it as a query in Query Analyzer and run. This example script does not have a return code. If the script runs successfully you will see the output without errors. If it fails you will see an error message.

geocodeAddress.sql: Demonstrates how to geocode a single address which returns a result set. This example script does not have a return code. If the script runs successfully you will see the output without errors. If it fails you will see an error message.

geocodeTrigger.sql: Demonstrates how to add a trigger to a table that invokes a geocoding request when the information geoaddress column changes. This script consists of two (2) triggers: an update trigger (called geocode) and an insert trigger (called geocodeIns). The update trigger automatically re-geocodes entries in your table as company address information is changed or updated. The insert trigger automatically geocodes entries when a new row is added. The script produces tests both triggers by inserting MapInfo’s address into table mm_inout and shows the geocoding output. It then nullifies (i.e., deletes) the geocode values and performs an update and displays the geocoding results.

To run the script, copy it and paste it as a query in Query Analyzer and then run. If it runs successfully you will see the output without errors, otherwise you will see an error message.

geocodeTable.sql: Demonstrates how to geocode a table of addresses. This script uses the tables provided by createDemoTable.sql for the geocoding process. The script creates metadata for the tables used and then runs examples of both sp_geocodeTable and sp_geocodeTableLastLine. The results are outputted to tables and then retrieved with an SQL select statement.

45


46

Chapter 4: Troubleshooting

When trying to determine why you cannot geocode your record or table, begin by checking the system from the base product up. Be sure that you followed the installation order for the products. Consider the following.

MapMarker: Is MapMarker 6.x or MapMarker Plus 6.x installed? Can you geocode to it directly? Do you have data loaded? Use the sample table US_ADDR.tab in the \MapMarker\sampdata directory as a test.

MapMarker Server: Check the TCP/IP connection, whichever is appropriate for your situation. Check the connections with your custom client application, as well. You can do this using httpServer and tcpServerHost preferences in the mm_preferences table (see Preferences on page 29). Verify that you can geocode an address. Is the command line server working? Does it geocode? If not, check that the settings and preferences match the working MapMarker. Check if the server is actually running. Look in Start>Settings>Control Panel>Services. MapMarker Server should be listed and have the status of ’Started’, if it doesn’t click the Start button. If you are trying to use a servlet, is your web service running? Can you invoke a sample servlet provided with the web server? Do you have the correct URL? Refer to the MapMarker Server Getting Started document for additional troubleshooting guidelines.

MapMarker ESP for SQL Server: Check the TCP/IP connections between MapMarker ESP for SQL Server and the MapMarker Server. Does your account have privileges for the requested operation? Are your tables in the correct form? Have they been described in the metadata table? Make sure that all the columns have been described, check spelling, syntax, and punctuation. Have you added the correct columns? Have you checked the default settings? Ensure that you have set up your data and settings correctly for the particular geocoding operation you wish to perform. Do you have a place to output your results? Have you fully qualified your tables? Are you using the correct database?


Error CodesThe following error codes may be returned by MapMarker ESP for SQL Server. In the event of an error, verify that MapMarker and the MapMarker Server are running and test that they can access the Address Dictionary by geocoding an address. The error codes below can provide more information for MapInfo Technical Support if an error occurs.

Error Code Description

20010 Runtime reported exception.

20050 Error allocation memory.

20100 Error geocode handle.

20110 Cannot create a number.

20120 No SpatialWare license.

20130 Cannot find SpatialWare license.

21000 Failed login.

21010 Failed connecting to server.

21020 Failed setting DB option.

21025 Too few parameters.

21030 Failed reading parameter.

21035 Failed reading value of the parameter.

21040 Parameter must be OUTPUT.

21050 Wrong length of the parameter.

21060 Cannot return parameter.

21070 No preference.

21080 Incorrect number of parameters.

21732 RPC server is not available.

21733 RPC server is too busy.

21710 RPC request is failed.

22000 Failed sending candidate description to client.

22010 Failed sending candidate values to client.

25000 Failed RPC connecting.

25010 Failed RPC disconnecting.

26000 No table metadata.

26001 Table doesn’t exist.

30001 MapMarkerServer ERROR: MALLOC_ERR.

48


30002 MapMarkerServer ERROR: MEMORY_CORRUPTED_ERR.

30003 MapMarkerServer ERROR: BAD_PARAM_ERR.

30004 MapMarkerServer ERROR: FILE_NOT_FOUND_ERR.

30005 MapMarkerServer ERROR: FILE_OPEN_ERR.

30006 MapMarkerServer ERROR: FILE_READ_ERR.

30007 MapMarkerServer ERROR: FILE_WRITE_ERR.

30008 MapMarkerServer ERROR: INDEX_OPEN_ERR.

30009 MapMarkerServer ERROR: INDEX_ACCESS_ERR.

30010 MapMarkerServer ERROR: BAD_DATABASE_ERR.

30011 MapMarkerServer ERROR: END_OF_DATA.

30012 MapMarkerServer ERROR: BAD_POSTAL_CODE.

30013 MapMarkerServer ERROR: UNINIT_DB_COMPONENT.

30014 MapMarkerServer ERROR: BAD_INPUT_ADDRESS.

30015 MapMarkerServer ERROR: NO_DATA_AVAILABLE.

30016 MapMarkerServer ERROR: INVALID_ACCESS_ERR.

30018 MapMarkerServer ERROR: BAD_LICFILE_ERR.

30019 MapMarkerServer ERROR: EXCEEDED_LIMIT.

30020 MapMarkerServer ERROR: USER_DICT_SCAN_DONE.

30022 MapMarkerServer ERROR: HIGHRISE_MULTIPLE_MATCH_ON_SEGMENT

XXXX Unknown error:

Error Code Description

49


50

Appendix A: MapMarker ESP for SQL Server and MapMarker Server Preference Comparison

MapMarker ESP for SQL Server

MapMarker Server Location Priority

preferenceName N/A N/A N/A

serialNumber SerialNumber Startup.txt Must Match

clientID N/A N/A N/A

httpServer N/A N/A N/A

tcpServerHost N/A N/A N/A

countryID N/A Geocoding Engine Parameters

MM ESP for SQL Server

exactMatchHouseNumber exactMatchHouseNumber Geocoding Engine Parameters


exactMatchStreetName exactMatchStreetName Geocoding Engine Parameters


exactMatchPostalCode exactMatchPostalCode Geocoding Engine Parameters


matchIntersections doIntersections Geocoding Engine Parameters


useCASSMode useCASSMode Geocoding Engine Parameters


expandSearch doExpand Geocoding Engine Parameters


limitExpandedSearch limitExpandedSearch Geocoding Engine Parameters


expandRadius searchRadius Geocoding Engine Parameters


distUnit distUnit Geocoding Engine Parameters


linearOffset offset Startup.txt MM ESP for SQL Server

perpendicularSetback setback Startup.txt MM ESP for SQL Server

miscPrefString N/A N/A N/A

Appendix A: MapMarker ESP for SQL Server and MapMarker Server Preference Comparison

maxNumCandidates candSize Startup.txt Server-> MM ESP can set to <= to Server

maxNumRangesPerCandidate rangeSize Startup.txt Server-> MM ESP can set to <= to Server

multiMatched N/A N/A N/A

unMatched N/A N/A N/A

returnCloseCandidatesOnly returnCloseMatchesOnly Geocoding Engine Parameters


returnFirm returnFirm Geocoding Engine Parameters


returnStreets returnStreets Geocoding Engine Parameters


returnLastLineInfo returnLastlineInfo Geocoding Engine Parameters


returnPostalInfo returnPostalInfo Geocoding Engine Parameters


returnCensus returnCensus Geocoding Engine Parameters


returnSpatial N/A N/A N/A

stopOn Error N/A N/A N/A

mode N/A N/A N/A

batchCount N/A N/A N/A

default_preference N/A N/A N/A

MapMarker ESP for SQL Server

MapMarker Server Location Priority

52

Appendix B: Glossary of Address and Geocoding Terms

Candidate: Record from the MapMarker Address Dictionary that is considered a potential match for the input address, based on its score.

Carrier Route: USPS address element that describes a given mail delivery or collection route within a 5-digit ZIP Code. There are five possible Carrier Route codes: Bnnn = P.O. Box; Hnnn = Highway Contract; Rnnn = Rural Route; Cnnn = City Delivery; and Gnnn = General Delivery (where n = a number).

CASS Mode: A strict manner of geocoding records, based on the standards set by the USPS Coding and Accuracy Support System (CASS), which strives for accurate addresses for mail pieces. Geocoding in this way matches records to the exact house number, street name and ZIP Code. Other geocoding preferences are overridden.

Census Block: U.S. Census Bureau code that uniquely identifies a geographic area for census reporting. Up to a 15-digit alphanumeric code can be returned for a successful match, depending on the result code. The census value is interpreted as follows:

SSCCCTTTTTTGBB(B)

where

S = State Federal Information Processing Standard (FIPS) code (2 characters)

C = County FIPS code (3 characters)

T = Census Tract (6 characters)

G = Census Block Group (1 character)

B = Census Block (typically 2 characters. The third character means the block was split from another block.)

S5 matches return the full code to the Census Block level. S1, S2, S3, Z1, Z2 and Z3 matches return the Block Group code (12 digits). No value is returned for S4

matches.

Check Digit: A one-digit code that together with Delivery Point is used to form the delivery point bar code on U.S. mail pieces.

City Subdivision: A subdivision of the city. Used in the U.S. for Puerto Rican urbanization areas.

City: Name of city.

Country Division: Name of subdivision of a country; in the U.S. the country division is a state.

Appendix B: Glossary of Address and Geocoding Terms

Delivery Point: A two-digit code that along with the Check Digit is used to form the delivery point barcode on U.S. mail pieces.

Firm: Name of the firm, business, or organization at the address.

Locatable Address Conversion System (LACS): A one-character code that indicates the record can be converted from a U.S. rural route address to a city-style address, using a separate USPS conversion product.

MapMarker Address Dictionary: The search dictionary used for matching U.S. addresses

during geocoding.

Postal Code Add-on: Additional postal zone identifier. In the U.S. it is a 4-digit extension to the 5-digit ZIP Code.

Postal Code: Unique identifier for postal mailing zones. In the U.S. it is a 5- or 9-digit ZIP Code.

Precision: Indicates the type of match candidate: street level (20), street intersection (30), shape path (10, point on segment with no address ranges), or ZIP Code centroid (1, 2, or 3 for ZIP Code, ZIP+2 and ZIP+4 centroids, respectively). The numbers in parentheses refer to the precision’s return value.

Range: House numbers along a street segment. Can be even, odd or both on each side of the street.

Result Code: A 10-character alphanumeric code that describes the type and accuracy of the geocoding match. See “Result Codes Defined” on page 34 for more information.

Score: The weighted rank given to a candidate, based on geocoding preferences set for the engine and the quality of the input address.

Street: Name of the street.

54

Appendix C: SpatialWare and MapMarker ESP for SQL Server

MapMarker ESP for SQL Server fully supports SpatialWare for SQL Server. You may write to the SpatialWare geometry formats in SQL Server. SpatialWare allows the storage, access, management, and manipulation of spatial data as a standard component of a data set.

If you have a MapInfo SpatialWare license and wish to use SpatialWare with MapMarker ESP for SQL Server, please consider the following guidelines.

Before you start, please refer to the SpatialWare for SQL Server documentation on how to prepare your database and tables for SpatialWare. This will involve creating spatial tables, spatializing existing tables, populating them and creating R-tree indexes to enable spatial querying.

• You must ensure that your tables have x and y columns to insert the geocoded co-ordinates and also a column into which the SpatialWare sw_geometry can be inserted.

• If you have an existing SpatialWare table you wish to use with MapMarker ESP for SQL Server you must add a column into which the SpatialWare sw_geometry can be inserted.

• Before you start to geocode, the SpatialWare table you wish to use must be described in the metadata. You must set the Metadata parameter @spatial to 'T' (true) if you wish to return spatial geometries. Please see Metadata on page 37 for more information on creating and changing metadata.

• If you wish to return sw_geometry this must be explicitly specified using the Preferences setting @returnSpatial. Please see Preferences on page 29 for more information on changing this setting.

• SpatialWare tables MUST have a primary key (e.g., sw_member) which you must set before starting to perform geocoding functions on your data.

Appendix C: SpatialWare and MapMarker ESP for SQL Server

56

Index

AAddress dictionary 15, 54Assigning a default preference

35

CCASS mode 53Candidate 53Carrier route 53Census block 53Changing metadata 41Check digit 53City subdivision 53Country division 53Creating a preference 33Creating metadata 40

DData, input

sp_findLocation 20sp_findLocationLastLine

21sp_geocodeAddress 22sp_geocodeAddressLastLi

ne 23sp_geocodeTable 17sp_geocodeTableLastLine

17Data, point 3Database

triggers 3Db_library 2Dblib 2Default preference

assigning 35displaying 35

Deleting a preference 34Delivery point 54Demo scripts

createDemoTable.sql 45findLocation.sql 21, 45geocodeAddress.sql 23, 45geocodeTable.sql 19, 45geocodeTrigger.sql 27, 45

Documentation 6

EError codes 48Errors

SQL Server 12installation 12user privileges 12

Example filescreateDemoTable.sql 45findLocation.sql 21, 45geocodeAddress.sql 23, 45geocodeTable.sql 19, 45geocodeTrigger.sql 27, 45

Examples, of proceduressp_create_metadata 41sp_create_preference 34sp_delete_preference 34sp_findLocation 21sp_findLocationLastLine

21sp_geocodeAddress 23sp_geocodeAddressLastLi

ne 23sp_geocodeTable 18sp_get_default_preference

35sp_set_default_preference

35sp_set_metadata 42sp_set_preference 36

Extended stored procedures 2, 5, 16

FFile locations 11

GGeocoding 1

about 15extended stored

procedures, using 16managing preferences 33–

36preparation 15single address 5single addresses 20–28sp_findLocation 5sp_findLocationLastLine 5sp_geocodeAddress 5sp_geocodeAddressLastLi


5table of addresses 5tables 15tables of addresses 17–19

Geocoding examples 45Glossary 53–54

IISQL 2Installation 7–12

Index

compact 9custom 9typical 9

Installation errors 12

LLACS 54Lastline 17License

SpatialWare 4, 7Locations, file 11Log files 12

MMMESP

about 2overview 1

Managing geocoding preferences 33–36

MapInfo SpatialWare 3, 7MapMarker 2MapMarker Geocoding Engine

2MapMarker Plus 2Mapinfo SpatialWare 4Metadata 37–42

changing 41creating 40mm_geocode_metadata

table 37primary keys 39procedures 6sp_create_metadata 6sp_delete_metadata 6sp_set_metadata 6

Microsoft SQL Server 3MmESPinstall.sql script 10MmESPuninstall.sql script 13

Multi-threading 3

NN category 44

OODBC 2Output

sp_geocodeTable 18Overview

mmesp 1

PParameters

sp_create_metadata 40sp_create_preference 33sp_findLocation 20sp_findLocation (Triggers)

24sp_findLocationLastLine


(Triggers) 25sp_geocodeAddress 22sp_geocodeAddressLastLi



Point data 3Precision 54Precision characters 44Preference comparison 51Preferences 29–36

mm_preferences table 30overview 29procedures 5

sp_create_preference 5sp_delete_preference 5sp_get_default_preference


5sp_set_preference 5

Pre-installation 7Primary keys 39

Printing the preference name 35

Proceduresextended stored 5sp_create_metadata 40sp_create_preference 33sp_delete_preference 34sp_findLocation 20sp_findLocation (Triggers)



(Triggers) 24sp_geocodeAddress 22sp_geocodeAddressLastLi

ne 22sp_geocodeTable 17–19sp_geocodeTableLastLine

17–19sp_get_default_preference



QQualified table name 37Queueing 2

58 MapMarker ESP for SQL Server

Index

RRange 54Reinstallation 12Remote procedure call (RPC) 2Requirements

software 4system 7

Result Codesprecision characters 44

Result code 54Result codes

N category 44S category 44Z category 44overview 43

Result setexactly one row 20one or more rows 22

Resultssp_geocodeTable 18

SS category 44SQL Server 3SQL Server session, opening 2SQL statements

uninstalling 13Score 54Scripts, running

mmESPuninstall.sql 13Setting a preference 35Settings 2, 5, 29–42Setup 8Software requirements 4SpatialWare 3, 4, 7System requirements 7

TTables

mm_geocode_metadata 37mm_preferences 30preparing 15

Triggers 3, 24–28sp_findLocation 24sp_findLocationLastLine

24Troubleshooting 47–49

MMESP 47MapMarker 47MapMarker Plus 47MapMarker server 47

UUninstallation 13

mmESPuninstall.sql script 13

Using MMESP 15–42

ZZ category 44

MapMarker ESP for SQL Server 59

Index

60 MapMarker ESP for SQL Server

mapmarker extended stored procedure for sql...

Documents