v.3.0 user’s guide - mapinfo pro™ - desktop gis | gis...

v.3.0User’s 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.© 2002 MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo and MapMarker are trademarks of MapInfo Corporation and/or its affiliates. MapInfo Corporate Headquarters:Voice: (518) 285-6000Fax: (518) 285-6060Sales Info Hotline: (800) 327-8627Government Sales Hotline: (800) 619-2333Technical Support Hotline: (518) 285-7283Technical Support Fax: (518) 285-6080Contact information for North American offices is located at: http://www.mapinfo.com/company/contact_corporate.cfm.Contact information for European and Middle East offices is located at: http://www.mapinfo.com/company/contact_europe.cfm.Contact information for Asia Pacific offices is located at: http://www.mapinfo.com/company/contact_asiapacific.cfm.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.February 2003

Table of Contents

Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Integration Considerations for Users of Previous Versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Documentation for the MapInfo Geocoding Cartridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge . . . . 9Product Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Installing MapInfo Geocoding Cartridge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Upgrading from Version 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Uninstalling the MapInfo Geocoding Cartridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 3: Working with the MapInfo Geocoding Cartridge. . . . . . . . . . . . . . . . . . . . . . 20Preparing to Geocode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Using the MapInfo Geocoding Cartridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Geocoding a Single Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Geocoding a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Oracle Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24The GEOADDRESS2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24The CANDIDATE2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28The ADDRESSRANGE2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30The ADDRESSRANGEUNIT2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32The CANDIDATESET2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34The ADDRESSRANGESET2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34The ADDRESSRANGEUNITSET2 Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34The MM_PREFERENCE2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35The INPUTTABLEINFO2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37The OUTPUTTABLEINFO2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Managing Geocoding Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 4: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Preliminary Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46MapInfo Geocoding Cartridge Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Appendix A: MapInfo Geocoding Cartridge Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 49geoaddr_demo.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50single_fields.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50single_geoaddr.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

User’s Guide Chapter 1:

MapInfo Geocoding Cartridge 3.0

© 2002 MapInfo Corporation. All rights reserved. 4 GeocodingCartridge.pdf

table_fields.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51table_geoaddr.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52trigger_fields.trg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52trigger_geoaddr.trg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Appendix B: Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Glossary of Address and Geocoding Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Introduction

In this chapter:

! Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6! What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6! Integration Considerations for Users of Previous Versions . . . . . . . . . . . . . . . . . . . . . . . 7! Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7! Documentation for the MapInfo Geocoding Cartridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1

User’s Guide Chapter 1: Introduction



Product Overview

MapInfo Geocoding Cartridge 3.0 allows you to add Oracle® spatial points (MISYS.SDO_GEOMETRY type) or x/y coordinate information to your Oracle8i or Oracle9i database address records for display and analysis in mapping software. MapInfo Geocoding Cartridge 3.0 is a Java-based tool that allows you to interact with the powerful geocoding engine in MapMarker from an Oracle8i or Oracle 9i database. The cartridge uses the new class of MapMarker XML Servers for geocoding.

You can geocode addresses individually or process an entire table using the functions and procedures provided with the cartridge. Records are geocoded to the street level, and if a street level match cannot be made, MapMarker can attempt to match it to the nearest postal or geographic centroid. Direct postal centroid geocoding, browsing the Address Dictionary, and querying the server, are not supported.

To familiarize yourself with how the MapInfo Geocoding Cartridge can be used, look at the samples that are installed in the MapInfoGeocodingCartridge3.0\demo folder of your installation directory. A summary of these samples is described in MapInfo Geocoding Cartridge Examples in Appendix A on page 49.

What’s New

The following features have been added to the new version of the MapInfo Geocoding Cartridge. For more information on these features, see Working with the MapInfo Geocoding Cartridge on page 20.

• MapInfo Geocoding Cartridge now uses the new MapMarker XML Servers for geocoding. Any countries implemented with this server can now be geocoded (for example, users of MapMarker J Server USA version 3.0, MapMarker Deutschland Java Edition, MapMarker España Java Edition, MapMarker Great Britain Java Edition, or MapMarker Italia Java Edition).

• Coordinate system information (SRID) is now stored in the CANDIDATE2 object and can be written to the output table, allowing for correct creation of MDSYS.SDO_GEOMETRY objects.

• All functionality of a country’s geocoder can be accessed from the MapInfo Geocoding Cartridge for street level geocoding using the cartridge’s country-specific layers (where available).

• All character fields in the GEOADDRESS2, CANDIDATE2, ADDRESSRANGE2 and new ADDRESSRANGEUNIT2 objects now support up to 256 characters.

• The MM_PREFERENCE2 object has been added to use country-specific layers to allow the storing and retrieving of all base preferences for the XML client, as well as country-specific preferences (with additional country cartridge layers, where available).




• The ADDRESSRANGEUNIT2 object has been added to store unit information as a separate object from the AddressRange object in order to conform to the XML client interface.

• A conversion utility is supplied for converting MapInfo Geocoding Cartridge 2.0 address and preference objects to the new 3.0 versions.

Integration Considerations for Users of Previous Versions

MapInfo Geocoding Cartridge 3.0 has a radically different underlying structure than version 2.0; it has been redesigned to use the new MapMarker XML Server as its geocoding server. MapInfo strongly recommends that you backup offline all tables containing GEOADDRESS2 objects, if not your entire geocoding database, so you can recover from any problems you might encounter should the upgrade process be unsuccessful.

After you have backed up your data and you have installed the upgrade, you will have to run functions from the conversion package (MM_CONVERT) in order to migrate all version 2.0 objects to version 3.0 objects. Once the migration is complete you may drop all old objects and tables, and then edit all triggers and stored procedures to use the new object structure.

MapInfo Geocoding Cartridge 2.0 will no longer function once MapInfo Geocoding Cartridge 3.0 is installed.

For a more detailed explanation of this upgrade procedure, see Upgrading from Version 2.0 on page 18.

Software Requirements

Geocoding Oracle8i and Oracle9i records requires the following software:

• MapInfo Geocoding Cartridge 3.0 — product for geocoding Oracle8i and Oracle9i records.• Oracle8i (Oracle 8.1.7), Oracle9i release 1, and Oracle9i release 2, with the Spatial option

— Spatial database with Java options. • Any of the new XML-based geocoding servers.

Install the MapInfo Geocoding Cartridge, as well as a MapMarker XML Server on the same machine as Oracle8i or Oracle9i, or place the XML Server and engine on a separate machine. The MapInfo Geocoding Cartridge will run on any Oracle platform. Consult your Oracle8i or Oracle9i documentation for Oracle system requirements, and your MapMarker product documentation for specific XML Server requirements.

Important: We assume you are familiar with Oracle8i or Oracle9i databases, including how to update tables, add columns, create objects, and perform other such actions.




Documentation for the MapInfo Geocoding Cartridge

Several sources of documentation are provided to assist you with using the MapInfo Geocoding Cartridge effectively:

• This MapInfo Geocoding Cartridge 3.0 User’s Guide provides installation instructions and an information on how to use the MapInfo Geocoding Cartridge.

• The MapInfo Geocoding Cartridge 3.0 Quick Installation Card provides an overview of the installation instructions for the MapInfo Geocoding Cartridge.

• For assistance with MapMarker XML Server installation and usage, refer to the documentation provided with that MapMarker product.

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

• For information related to Oracle8i/Oracle9i operations, see the Oracle8i/Oracle9i documentation set.

Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge

In this chapter:

! Product Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10! Installing MapInfo Geocoding Cartridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10! Upgrading from Version 2.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18! Uninstalling the MapInfo Geocoding Cartridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2

User’s Guide Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge



Product Installation Overview

There are two installation options for MapInfo Geocoding Cartridge 3.0: a full installation and an upgrade from a previous version. If performing a full installation, please refer to Installing MapInfo Geocoding Cartridge on page 10. If performing an upgrade, please refer to Upgrading from Version 2.0 on page 18.

Installing MapInfo Geocoding Cartridge

The installation of MapInfo Geocoding Cartridge is a two step process. First run the installer on the product CD to lay down the MapInfo Geocoding Cartridge files (see Running the Installer below). Once the installation from the CD is complete, you must run the system.sql and misys.sql files to actually install the MapInfo Geocoding Cartridge (see Installing the Files on page 17).

Running the InstallerTo install MapInfo Geocoding Cartridge 3.0 files from the CD:

1. Place the MapInfo Geocoding Cartridge software CD in your CD-ROM drive.2. Run install.htm from the MapInfo Geocoding Cartridge CD. Select the installation package

for your platform. The installation is copied to a temporary location on your system. Alternatively, you can bypass the browser. Go to the appropriate OS folder on the product CD under /InstData and run the install executable.

The Introduction dialog displays.

3. On the Introduction dialog, click NEXT to proceed.




The Important Information dialog displays.

4. Read the release information and then click NEXT.The License Agreement dialog displays.

5. Accept the agreement and then click NEXT to proceed.




The Choose Install Folder dialog displays.

6. At the Choose Install Folder dialog, accept the default location to install MapInfo Geocoding Cartridge or browse to another location. Click NEXT.

The Choose Install Set dialog displays.

7. Select the FULL option if performing a new MapInfo Geocoding Cartridge installation, else select the UPGRADE option.

Note: If performing an upgrade, make sure you have completed all the required upgrade steps prior to running this installer. See Upgrading from Version 2.0 on page 18 for more information. If you have not performed the upgrade steps, click CANCEL to quit the installer and perform those steps before installing the product upgrade.

Click NEXT.




The Choose type of Installation dialog displays.

8. Select whether you are installing on an ORACLE CLIENT machine or an ORACLE SERVER and then click NEXT.Perform a Client installation if you are installing on a machine that will connect to an Oracle server elsewhere on your network. Perform a Server installation if you are installing on the Oracle server machine.

If you select ORACLE SERVER, continue with step 10.

The DataBase Alias Name dialog displays.

9. Specify the database alias to which your Oracle Client connects in the DATABASE ALIAS field and then click NEXT.




The MISYS Account Information dialog displays.

10. Type your MISYS PASSWORD, MISYS DEFAULT TABLESPACE, and MISYS TEMPORARY TABLESPACE into the corresponding fields and then click NEXT. If performing an upgrade, only the MISYS PASSWORD field is displayed in the dialog.

Note: The default tablespace values supplied in the installer may differ from those in your database. Enter valid values for your database in this dialog.

The Server URL Information dialog displays.

11. Type the SERVER URL for your MapMarker Server into the corresponding field and then click NEXT.




The Choose Shortcut Folder dialog displays.

12. At the Choose Shortcut Folder dialog, accept the default location in which to install a documentation shortcut, browse to another location, or choose one of the other available options. Click NEXT.The Pre-Installation Summary dialog displays.

13. Review the information in the Pre-Installation Summary dialog, making sure all settings are correct. If you need to make any corrections, click PREVIOUS to navigate back through the installation wizard and make the necessary changes on the appropriate dialogs. If all settings are correct, click INSTALL to start the product installation.




The Installing MapInfo(TM)GeocodingCartridge3.0 dialog displays.

If you decide you do not want to install MapInfo Geocoding Cartridge, click CANCEL.

Once the installation process is finished, the View Read Me File dialog displays.

14. Select YES and click NEXT to view the readme file.




The MapInfo(TM)GeocodingCartridge3.0 Read Me File dialog displays.

15. Read the contents of the readme file and when ready to continue, click NEXT.The Install Complete dialog displays.

16. At the Install Complete dialog, click DONE to exit the software installer.

Installing the FilesAfter you run the MapInfo Geocoding Cartridge 3.0 installer, you must run two SQL files to finish the product installation.

1. Run the system.sql file as SYSTEM.2. Run the misys.sql file as MISYS.

Note: When running these files in SQL*Plus, ensure your working directory is the same directory where the .sql files are located.




Upgrading from Version 2.0

There are many major structural differences between MapInfo Geocoding Cartridge 2.0 and version 3.0. MapInfo Geocoding Cartridge 3.0 now uses the new MapMarker XML Server as its geocoding server. You must follow the steps below in order to avoid problems when upgrading from version 2.0 to version 3.0.

1. Backup all your tables that contain GEOADDRESS objects (preferably the entire database) to an offline location before installing the version 3.0 upgrade.

2. Drop the old java code used by MapInfo Geocoding Cartridge 2.0 by executing commands similar to the following:

dropjava -v -u MISYS/[passwd]@[dbname] MapMarkerJServer.jar;

dropjava -v -u MISYS/[passwd]@[dbname] mapmarker.jar;

where [passwd] is your MISYS password and [dbname] is the database name where the MapInfo Geocoding Cartridge 2.0 is installed.

Note: If executing these commands from SQL*Plus, you must begin the command with ‘host’ as follows:

host dropjava -v -u MISYS/[passwd]@[dbname] MapMarkerJServer.jar;

host dropjava -v -u MISYS/[passwd]@[dbname] mapmarker.jar;

When executing these commands in SQL*Plus, ensure your working directory is the same directory where the .jar files are located.

3. Follow the instructions in Installing MapInfo Geocoding Cartridge on page 10, choosing the UPGRADE option on the Choose Install Set dialog in step 7.

Note: After running the upgrade installer, both version 2.0 and version 3.0 will be installed and active on your system. Version 2.0 will no longer be able to geocode, but the GEOADDRESS object will still exist.

4. Run the misys.sql file as MISYS.5. Using the MM_CONVERT package, migrate all version 2.0 objects to version 3.0 objects.

This includes converting the GEOADDRESS objects to GEOADDRESS2 objects. This package also contains methods to convert the MM_PREFERENCE objects to MM_PREFERENCE2 objects. See MM_CONVERT package on page 19 for information on using the MM_CONVERT package.

6. After all data has been converted, drop the MM_CONVERT package, then modify existing tables and other user-defined objects to use the new MapInfo Geocoding Cartridge objects exclusively, drop the old preference tables, and then drop all other remaining old objects.

7. Edit all triggers and other stored procedures to use the new structure of the various objects




MM_CONVERT packageThe MM_CONVERT package is contained within the mmconvert.sql file, which is located in the \install\sql folder of your product installation directory. This package contains methods to handle converting various version 2.0 objects to version 3.0 objects. When you run these methods, all the USA-specific fields of the old objects are moved to the correct fields of the new objects as if all the objects related to the USA.

Functions within the MM_CONVERT package include:

• function convert(address in GEOADDRESS) return GEOADDRESS2• function convert(address in GEOADDRESS, country in VARCHAR2) return

GEOADDRESS2• function convert(preference in MM_PREFERENCES) return MM_PREFERENCE2• procedure convertPreferenceTable;

Uninstalling the MapInfo Geocoding Cartridge

To remove the MapInfo Geocoding Cartridge objects from the database:

1. Open an SQL*Plus session and connect as the MISYS user.2. Navigate to the install\sql directory under the product installation directory.3. Execute the drop_cart_objs.sql script.4. Log out of the SQL*Plus session.

To remove the files installed on your machine, launch the uninstall program located in the UninstallerData folder of your product installation directory:

Uninstall MapInfo(TM)GeocodingCartridge3.0.exe

Working with the MapInfo Geocoding Cartridge

In this chapter:

! Preparing to Geocode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21! Using the MapInfo Geocoding Cartridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21! Geocoding a Single Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22! Geocoding a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22! Oracle Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24! The GEOADDRESS2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24! The CANDIDATE2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28! The ADDRESSRANGE2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30! The ADDRESSRANGEUNIT2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32! The CANDIDATESET2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34! The ADDRESSRANGESET2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34! The ADDRESSRANGEUNITSET2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34! The MM_PREFERENCE2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35! The INPUTTABLEINFO2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37! The OUTPUTTABLEINFO2 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39! Managing Geocoding Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3

User’s Guide Chapter 3: Working with the MapInfo Geocoding Cartridge



Preparing to Geocode

Before you can geocode your records, there are a few things to consider. First you need to define your requirements. Do you need all possible address candidates for your input address? Do you need street number range information? Or do you simply want the coordinates of what MapMarker thinks is the “best” match?

If you want multiple candidates or address range information added to an existing table, you will need to add a column of type MISYS.GEOADDRESS2 and copy input address information into the appropriate fields of the GEOADDRESS2. For geocoding a table when you do not need to save multiple candidates, you will need to add columns to hold the output information you want returned.

When the appropriate columns have been added and the GEOADDRESS2 column is populated (if used), you are ready to geocode.

Note: When matching to intersections, if an ampersand character appears in a string literal argument when constructing a GEOADDRESS2 object, the character must be double quoted (i.e. four single quotes with an ampersand character in the middle) in the string literal. For example, when specifying an intersection in the street attribute, the string literal may be specified as follows:'main street ''&&'' park avenue'

or you can use the CHR function:'main street' || chr(38) || chr(38) || 'park avenue'

where chr(38) is equivalent to the ASCII &.

Using the MapInfo Geocoding Cartridge

Geocoding in the database using the MapInfo Geocoding Cartridge can be done in two ways: geocode a single address or a table of addresses.

To geocode single addresses, use the findLocation call of the MISYS.GEOADDRESS2 object. Although this call requires a GEOADDRESS2 object, we include an example of how to call this without adding a GEOADDRESS2 object to your table. See MapInfo Geocoding Cartridge Examples in Appendix A on page 49.

To geocode an entire table (or a portion selected by a where clause), use the MISYS.MM_USER.geocode_Table procedure. Some versions of geocode_Table require a GEOADDRESS2 object column, others do not.




Geocoding a Single Address

Single addresses are geocoded by using the findLocation call of the GEOADDRESS2 object. Use of the GEOADDRESS2 object can be transparent to the user. See the single_fields.sql file under the MapInfoGeocodingCartridge3.0\demo directory for an example of a routine that asks for the information necessary to geocode.

Another instance of single address geocoding can be invoked automatically via a trigger when an address is updated or added to a table. Triggers can be set to work with GEOADDRESS2 columns or the address values in individual columns. Examples of how to perform single geocodes can be found in the MapInfoGeocodingCartridge3.0\demo directory. The following example files geocode single addresses: single_fields.sql, single_geoaddr.sql, trigger_fields.trg and trigger_geoaddr.trg.

Geocoding a Table

Use the geocode_Table procedure to geocode a table of addresses. Some versions of this procedure require a GEOADDRESS2 object column, others do not. The geocode_Table procedures are defined in the MM_USER package. The system administrator or MISYS account must grant execute permission on the MM_USER package to other accounts that will use the geocode_Table procedure. MISYS must also be granted select on the input table and insert/update on the output table.

You may return one or more candidates for each record in your table. To return multiple candidates or address range information, your table must contain a column of GEOADDRESS2 objects. The GEOADDRESS2 objects should be populated with the input address information. When you invoke the geocode_Table procedure, it will geocode the table and put returned candidates, ranges, and units into the GEOADDRESS2 objects.

When you are interested in returning a single candidate, there are geocode_Table calls that do not require a GEOADDRESS2 object to be added to your table. The results for a single candidate can be placed in the source table or a second table. To make calling easier, we have defined the INPUTTABLEINFO2 and OUTPUTTABLEINFO2 objects, which you can place in a table to store information for the tables you want to geocode.

All of the geocode_Table forms below take an augmented where clause to be appended to the select statement. To select only a certain state to be geocoded, specify a where clause which includes a table alias, like the following:

' geoaddr.areaName1 = ''NY'' '

where:

geoaddr = object name of type GEOADDRESS2.

areaName1 = attribute of geoaddr object.




You may use geocode_Table with default preferences, use a preferences name from the MISYS_PREFERENCES2 table, or create an MM_PREFERENCES2 object to be used for geocoding. The geocode_Table procedures are described below for each situation. The first candidate is returned by default. If you want to have another candidate returned, use the GEOADDRESS2 object.

Using Default PreferencesThe following procedure examples use the default geocoding preferences specified in the MISYS_DEFAULT_PREFERENCES2 table. To create and set default preferences, see Managing Geocoding Preferences on page 42.

PROCEDURE GEOCODE_TABLE(inputtable INPUTTABLEINFO2,outputtable OUTPUTTABLEINFO2,whereclause VARCHAR2)

PROCEDURE GEOCODE_TABLE(geoaddress2table VARCHAR2, geoaddress2columnname VARCHAR2,keycolumn VARCHAR2,whereclause VARCHAR2)

Using Preferences from MISYS_PREFERENCES2 TableThe following procedure examples use the preferences with the given name from the MISYS_PREFERENCES2 table. When using a preference name the name must match exactly one entry in the MISYS_PREFERENCES2 table (including case).

PROCEDURE GEOCODE_TABLE(inputtable INPUTTABLEINFO2,outputtable OUTPUTTABLEINFO2,preferencename VARCHAR2,whereclause VARCHAR2)

PROCEDURE GEOCODE_TABLE(geoaddress2table VARCHAR2,geoaddress2columnname VARCHAR2,keycolumn VARCHAR2,preferencename VARCHAR2,whereclause VARCHAR2)

Using the Preferences ObjectThe following procedures geocode using the preferences object passed in the third parameter:

PROCEDURE GEOCODE_TABLE(inputtable INPUTTABLEINFO2,outputtable OUTPUTTABLEINFO2,preference MM_PREFERENCE2,whereclause VARCHAR2)

PROCEDURE GEOCODE_TABLE(geoaddress2table VARCHAR2,geoaddress2columnname VARCHAR2,keycolumn VARCHAR2,preference MM_PREFERENCE2,whereclause VARCHAR2)




Oracle Object Types

The MapInfo Geocoding Cartridge defines several new Oracle8i object types. These types are used to communicate with the MapMarker XML Server, a Java-based implementation for communicating with the MapMarker geocoding engine.

Single-record or table geocoding is performed by the GEOADDRESS2 object, which is also used for storing multiple return candidates or address ranges.

The GEOADDRESS2 object also uses some other defined object types. The CANDIDATE2 type lists a single possible resulting address (including coordinate information) for a geocode request, the ADDRESSRANGE2 type gives address range information for a candidate, and the ADDRESSRANGEUNIT2 type holds the unit information associated with an address range. Three additional types are used. A CANDIDATESET2, found in a GEOADDRESS2 object, is a VARRAY of CANDIDATE2 objects. An ADDRESSRANGESET2, found in a GEOADDRESS2 object, is a VARRAY of ADDRESSRANGE2 objects. An ADDRESSRANGEUNITSET2, found in a GEOADDRESS2 object, is a VARRAY of ADDRESSRANGEUNIT2 objects.

Information on columns for table geocoding is stored in INPUTTABLEINFO2 and OUTPUTTABLEINFO2 objects.

The MM_PREFERENCE2 type holds geocoding preference information for the geocoding engine.

The GEOADDRESS2 Object

The GEOADDRESS2 object type defines the attributes and functions required to geocode single addresses. It is also used for table geocoding where you wish to look at address range information or store results for more than one candidate. The address information to be geocoded is placed in the appropriate fields of the GEOADDRESS2 object, and the findLocation function geocodes the address and populates the CANDIDATESET2 with the returned candidates.

The parts of the GEOADDRESS2 object are described below.

Field Type Description

country VARCHAR2(3) Input: the ISO standard abbreviation for the country of the input address

genericField1 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific product documentation







genericField5 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation








placeName VARCHAR2(256) Input: placename, usually a business name or well known landmark

preAddress VARCHAR2(256) Input: the String assigned by the country geocoder to preAddress

addressNumber VARCHAR2(256) Input: address numberThis may be blank and the address number included in the mainAddress.

preDirectional VARCHAR2(256) Input: pre direction of a parsed input street

preThoroughfareType VARCHAR2(256) Input: pre type of a parsed input street

mainAddress VARCHAR2(256) Input: street addressDifferent countries may be implemented to use this field for a different purpose, based on local address requirements.

postThouroughfareType VARCHAR2(256) Input: post type of a parsed input street





postDirectional VARCHAR2(256) Input: post directional of a parsed input street

postAddress VARCHAR2(256) Input: post address infoIn most implementations this field holds the lastLine (the postal code and any areaNames in unparsed format).

postCode1 VARCHAR2(256) Input: postal code1 for the address

postCode2 VARCHAR2(256) Input: postal code2 for the address

areaName1 VARCHAR2(256) Input: name of the geographic/administrative entity that is the largest sub-set of a countryIn the United States this is the State, in Germany it is the Region.

areaName2 VARCHAR2(256) Input: name of the next smallest area of a countryIn the United States this is the County, in Germany it is the District.

areaName3 VARCHAR2(256) Input: name of the next smallest area of a countryIn the United States this is the City, in Germany it is the Town.

areaName4 VARCHAR2(256) Input: name of the next smallest area of a countryIn the United States this is the Urbanization or Neighborhood, in Germany it is the Locality.

unitValue VARCHAR2(256) Input: unit value

unitType VARCHAR2(256) Input: unit type

TotalCandidates NUMBER Output: total number of candidates found by the geocoder for the input address

ReturnedCandidates NUMBER Output: size of the candidates collection. This is the number of the total candidates that the cartridge returned and is at most the number of total candidates.

CloseCandidates NUMBER Output: number of the total candidates that the geocoder considered close matches. Close candidates are ordered first in the candidate array.

errorCode NUMBER Output: number corresponding to a type of address related error. Does not include server, user and database errors, as these errors abort the geocoding process.

errorMessage VARCHAR2(256) Output: text of an address related error





GEOADDRESS2 Object Functions and ProceduresThere are several functions and procedures defined for the GEOADDRESS2 object:

findLocation reads address information from the GEOADDRESS2 object and populates the CANDIDATESET2, ADDRESSRANGESET2, and ADDRESSRANGEUNITSET2 with the resulting information. It is available both as a function returning a GEOADDRESS2 and a procedure. ScrubAddress is also a function and a procedure returning a GEOADDRESS2 object.

The syntax of the calls is described below.

candidates CANDIDATESET2 Output: all of the available/requested candidates for this address after geocoding

ranges ADDRESSRANGESET2 Output: all of the available/requested address ranges for this address after geocoding

units ADDRESSRANGEUNITSET2 Output: all of the available/requested range units for this address after geocoding

Method Description

findLocation() – (function) Returns a new GEOADDRESS2 object. Geocodes using the default preferences – an application exception error results if there is no default preference or if there are too many rows in the default preference table. Results returned in the returned object.

findLocation(preferenceName) – (function) Returns a new GEOADDRESS2 object. Geocodes using the preference specified – an application exception error results if that preference does not exist or if more than one row in the preference table has that name. Results returned in the returned object.

findLocation(preference) – (function) Returns a new GEOADDRESS2 object. Geocodes using the MM_PREFERENCE2 object passed in. Results returned in the returned object.

findLocation() – (procedure) Geocodes using the default preferences – raises an application exception error if there is no default preference or if there are too many rows in the default preference table. Results returned in the calling object.

findLocation(preferenceName) – (procedure) Geocodes using the preference specified – raises an application exception error if that preference does not exist or if more than one row in the preference table has that name. Results returned in the calling object.

findLocation(preference) – (procedure) Geocodes using the preference object passed in. Results returned in the calling object.

isGeocoded() Returns 1 if the geoaddress candidates array contains any candidates, otherwise returns 0.

getX(candidateIndex in NUMBER default 1) Returns the x-coordinate of the candidate at the given index.

getY(candidateIndex in NUMBER default 1) Returns the y-coordinate of the candidate at the given index.





The CANDIDATE2 Object

The CANDIDATE2 object is used to hold the candidates returned by the cartridge when the GEOADDRESS2 is geocoded. These candidates contain address information as well as location information. The actual contents of some fields is dependant on the country and the implementation of the geocoding solution used.

getOracleSpatialObject(candidateIndex in NUMBER default 1)1

Returns the MDSYS.SDO_GEOMETRY object containing x and y information and SRID for the candidate at the given index.

getNumCandidates() Returns the number of candidates in the GEOADDRESS2 object.

getNumRangesForCandidate(candidateIndex in NUMBER default 1)

Returns the number of address ranges for the candidate at the given index.

getNumRangeUnitsForRange(addressRangeIndex in NUMBER)

Returns the number of address range units for the range at the given index.

scrubAddress(candidateIndex in NUMBER default 1) – (function)

Replaces the input geoaddress information with the address information from the candidate at the given index. Extreme care should be used when calling this function because it modifies the original address information.

scrubAddress(candidateIndex in NUMBER default 1) – (procedure)

Allows you to replace the input information with the information of candidate x. If the candidate index is out of bounds or the GEOADDRESS2 object has not been geocoded an error will be raised.

getCandidate(candidateIndex in NUMBER default 1)

Returns the CANDIDATE2 in the GEOADDRESS2 object.

getRange(rangeIndex in NUMBER) Returns the ADDRESSRANGE2 in the GEOADDRESS2 object.

getUnit(unitIndex in NUMBER) Returns the ADDRESSRANGEUNIT2 in the GEOADDRESS2 object.

1 When you create a table that contains a MDSYS.SDO_GEOMETRY object, you should insert a row into the USER_SDO_GEOM_METADATA or SDO_GEOM_METADATA (depending on which version you are using) describing the table, column, SRID, and DIM_INFO for those objects.


country VARCHAR2(3) the ISO standard abbreviation for the country this candidate is in

genericField1 VARCHAR2(256) the String assigned by the country geocoder to the genericField1

genericField2 VARCHAR2(256) the String assigned by the country geocoder to the genericFiled2



Method Description




genericField5 VARCHAR2(256) only filled in for countries that provide a cartridge translation layer (and this layer is installed in the database)

genericField6 VARCHAR2(256) only filled in for countries that provide a cartridge translation layer

genericField7 VARCHAR2(256) requires translation layer






placeName VARCHAR2(256) the placename of a candidate address

formattedStreet VARCHAR2(256) the formatted street address (not parsed into individual fields, for example: ’10 Main St Apt 2’)

preAddress VARCHAR2(256) the String assigned by the country geocoder to preAddress

addressNumber VARCHAR2(256) the address number for the candidate (some implementations may return this combined with street address info in one or more of the following fields)

preDirectional VARCHAR2(256) the String assigned by the country geocoder to preDirectional

preThoroughfareType VARCHAR2(256) the String assigned by the country geocoder to the preThoroughfareType

mainAddress VARCHAR2(256) the String assigned by the country geocoder to the mainAddress field. In most countries candidates this will be the complete street address, and may include the address number.

postThoroughfareType VARCHAR2(256) the post type for the street address, if available

postDirectional VARCHAR2(256) the post directional, if available

PostAddress VARCHAR2(256) the String assigned to the postAddress field

postCode1 VARCHAR2(256) the candidates postal code 1. This is the first part of a postal code for countries that have two or the entire postal code for others. In the USA this would be the zipcode.

postCode2 VARCHAR2(256) the candidates postal code 2. This is the rest of the postal code info for countries that have more than one part. In the USA this would be the zip+4.

areaName1 VARCHAR2(256) the largest administrative boundary name (state, province, etc.)

areaName2 VARCHAR2(256) the next largest boundary name (county, shire, etc.)

areaName3 VARCHAR2(256) the next largest boundary name (city, commune, etc.)

areaName4 VARCHAR2(256) the next largest boundary name (urbanization, locality, etc.)





The ADDRESSRANGE2 Object

The ADDRESSRANGE2 lists the street house ranges for a match candidate. The parts of an ADDRESSRANGE2 object are described below. Many of these fields may be left blank, depending on the country.

unitValue VARCHAR2(256) the unit value for this candidate

unitType VARCHAR2(256) the unit type for this candidate

rangeCount NUMBER the count of how many elements in the GEOADDRESS2 ranges are for this candidate

firstRange NUMBER the position of the first ADDRESSRANGE2 in the GEOADDRESS2 ranges collection. This will be 0 in the case where the rangeCount is 0, and 1 or greater otherwise. This marks an improvement in handling ranges and allows users to access to correct ADDRESSRANGE2 without having to iterate through all of the previous CANDIDATE2 objects to count how many ADDRESSRANGE2 objects each has.

x NUMBER the x coordinate for the candidate

y NUMBER the y coordinate for the candidate

SRID NUMBER the Oracle SRID, which represents the coordinate system the x and y coordinates should be interpreted in

closeMatchFlag CHAR(1) T if true (if the geocoder considered this candidate a closematch). F if false.

resultCode VARCHAR2(256) the result code for the candidate. This corresponds to the type of point returned as well as which fields in the input address matches the corresponding fields in this candidate.



genericField1 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation








genericField5 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation








placeName VARCHAR2(256) placename, usually a business name or well known landmark


addressNumber VARCHAR2(256) address numberThis may be blank and the address number included in the mainAddress.

preDirectional VARCHAR2(256) pre direction of a parsed input street

preThoroughfareType VARCHAR2(256) pre type of a parsed input street

mainAddress VARCHAR2(256) street addressDifferent countries may be implemented to use this field for a different purpose, based on local address requirements.

postThouroughfareType VARCHAR2(256) post type of a parsed input street

postDirectional VARCHAR2(256) post directional of a parsed input street

postAddress VARCHAR2(256) post address infoIn most implementations this field holds the lastLine (the postal code and any areaNames in unparsed format).

postCode1 VARCHAR2(256) postal code1 for the address


areaName1 VARCHAR2(256) name of the geographic/administrative entity that is the largest sub-set of a countryIn the United States this is the State, in Germany it is the Region.





The ADDRESSRANGEUNIT2 Object

This object holds the unit informationassociated with an address range. The server allows for returning multiple RangeUnits per range. It contains all of the address fields as well as specific unit fields. Many of these fields may be empty, depending on the country.

areaName2 VARCHAR2(256) name of the next smallest area of a countryIn the United States this is the County, in Germany it is the District.

areaName3 VARCHAR2(256) name of the next smallest area of a countryIn the United States this is the City, in Germany it is the Town.

areaName4 VARCHAR2(256) name of the next smallest area of a countryIn the United States this is the Urbanization or Neighborhood, in Germany it is the Locality.

unitValue VARCHAR2(256) unit value

unitType VARCHAR2(256) unit type

candidateIndex NUMBER a field that holds the number of the candidate that this range belongs

rangeUnitCount NUMBER the number of ADDRESSRANGEUNIT2 object for this range

firstRangeUnit NUMBER the index of the first rangeUnit for this range

lowHouse VARCHAR2(256) the low address of the range

highHouse VARCHAR2(256) the high address of the range

rangeCondition VARCHAR2(256) information related to what address numbers are between the from and the to. In the USA these conditions would be (O)dd, (E)ven, (B)oth. In some other countries it may have other meanings. So a from of 1 and a to of 9 with a range condition of Odd would also contain 3, 5, and 7. If the condition were Both it would contain all the integers from 1 to 9. A Even condition for this range would not be correct.

rangeSide NUMBER 0 = left, 1 = right (default to left if the side is not known)



















placeName VARCHAR2(256) placename, usually a business name or well known landmark


addressNumber VARCHAR2(256) address numberThis may be blank and the address number included in the mainAddress.

preDirectional VARCHAR2(256) pre direction of a parsed input street

preThoroughfareType VARCHAR2(256) pre type of a parsed input street

mainAddress VARCHAR2(256) street addressDifferent countries may be implemented to use this field for a different purpose, based on local address requirements.

postThouroughfareType VARCHAR2(256) post type of a parsed input street

postDirectional VARCHAR2(256) post directional of a parsed input street

postAddress VARCHAR2(256) post address infoIn most implementations this field holds the lastLine (the postal code and any areaNames in unparsed format).







The CANDIDATESET2 Object

This is a collection of CANDIDATE2 object in a VARRAY. The first object is at index 1.

The ADDRESSRANGESET2 Object

This is a collection of ADDRESSRANGE2 objects in a VARRAY. The first object is at index 1.

The ADDRESSRANGEUNITSET2 Object

This is a collection of ADDRESSRANGEUNIT2 objects in a VARRAY. The first object is at index 1.

areaName1 VARCHAR2(256) name of the geographic/administrative entity that is the largest sub-set of a countryIn the United States this is the State, in Germany it is the Region.

areaName2 VARCHAR2(256) name of the next smallest area of a countryIn the United States this is the County, in Germany it is the District.

areaName3 VARCHAR2(256) name of the next smallest area of a countryIn the United States this is the City, in Germany it is the Town.

areaName4 VARCHAR2(256) name of the next smallest area of a countryIn the United States this is the Urbanization or Neighborhood, in Germany it is the Locality.

unitValue VARCHAR2(256) unit value

unitType VARCHAR2(256) unit type

rangeIndex NUMBER a field that holds the number of the candidate that this range belongs

lowUnit VARCHAR2(256) a field holding the low unit value for this unit

highUnit VARCHAR2(256) a field holding the high unit value for this unit





The MM_PREFERENCE2 Object

The MM_PREFERENCE2 object type is used to define how a geocode request is handled. Different preferences can be created to match different geocoding needs.

To modify the default settings in the MapInfo Geocoding Cartridge, create or modify a preferences object in the MISYS_PREFERENCES2 table, and then use MM_ADMIN.set_default_preferences to make that preference the single entry in the MISYS_DEFAULT_PREFERENCES2 table. Other preferences may be stored in the MISYS_PREFERENCES2 table and passed to the geocoding engine when the row is being geocoded. The parts of an MM_PREFERENCE2 object are as follows.


name VARCHAR2(256) the name of the preference. All access to the preferences may be by name so as to avoid needing to have the various object and package members updated whenever a change to the preference type is required.

CloseOnly CHAR(1) field to determine if only closematches will be returned. ‘T’ = true, ‘F’ = false.

MaxCandidates NUMBER the maximum number of candidates to return for an input address geocode

maxRangesPerCandidate NUMBER the maximum number of ADDRESSRANGE2 objects to return for each candidate

MaxRangeUnitsPerRange NUMBER the maximum number of ADDRESSRANGEUNIT2 objects to return for each range

serverURL VARCHAR2(256) the URL of the server. This is used by the Java side code to open a connection to the server from the client.

batchSize NUMBER how often output info is committed in the database.

PostalFallback CHAR(1) determines if the geocoder can attempt to fallback to a postal centroid in the event that no closematches are found on street geocoding. The country implementation must support this for any centroids to be returned. ‘T’ = true, ‘F’ = false.

GeographicFallback CHAR(1) determines if the geocoder can attempt to fallback to a geographic centroid when no street closematches can be found. ‘T’ = true, ‘F’ = false.If both this and fallBackToPostal are true, the country implementation will decide which takes precedence.

cornerOffsetUnit VARCHAR2(2) corresponds to the defined unit types for controlling how the offset distances should be interpreted

cornerOffsetDistance NUMBER the number of distUnits the segment on which interpolation should be shrunk. The effect in practice is to move the two end-point addresses in cornerOffset distance and compute all in between addresses from this imaginary segment.




streetOffsetUnit VARCHAR2(2) the unit of measurement to interpret the streetOffset in

streetOffsetDistance NUMBER the number of distUnits the street result should be offset from the center-line of the street segment. Only applies to points interpolated based on address ranges.

RequestSRID NUMBER the SRID coordinates should be returned in. Will be overridden for table geocoding with an output SDO_GEOMETRY column.

mustMatchAddressNumber CHAR(1) determines if closematches must match the input address number (T= true)

mustMatchMainAddress CHAR(1) determine if the street name fields must match the input for closematches (T= true)

mustMatchAreaName1 CHAR(1) close candidates must match the areaName1 given in input (T= true)




mustMatchPostal CHAR(1) if set to T (true) closematches must match the input postal code

mustMatchInput CHAR(1) if set to T (true) the above preferences are also set to T where appropriate

genericFlag1 CHAR(1) to be interpreted by a specific country’s implementation








genericField1 VARCHAR2(256) any country-specific input other than a true or false setting









The INPUTTABLEINFO2 Object

The INPUTTABLEINFO2 object serves as a pointer to address information stored in a given address. For each of the fields, specify the name of the column used to hold that value for the table or null if there is no column for that value (for example, input postCode1). All the named columns should contain character data.





tableName VARCHAR2(65) column in the named table containing a unique identifier naming the table that is described

KeyColumn VARCHAR2(32) column in the named table linking input to output

countryColumn VARCHAR2(32) column in the named table containing the ISO standard abbreviation for the country this input address is in

genericField1Column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion
















placeNameColumn VARCHAR2(32) column in the named table containing the placename of a input address

preAddressColumn VARCHAR2(32) column in the named table containing the String assigned by the country geocoder to preAddress

addressNumberColumn VARCHAR2(32) column in the named table containing the address number for the input address (some implementations may return this combined with street address info in one or more of the following fields)

preDirectionalColumn VARCHAR2(32) column in the named table containing the pre direction of a parsed input street

preThoroughfareTypeColumn VARCHAR2(32) column in the named table containing the pre type of a parsed input street

mainAddressColumn VARCHAR2(32) column in the named table containing the street addressDifferent countries may be implemented to use this field for a different purpose, based on local address requirements.

postThoroughfareTypeColumn VARCHAR2(32) column in the named table containing the post type of a parsed input street

postDirectionalColumn VARCHAR2(32) column in the named table containing the post directional of a parsed input street

postAddressColumn VARCHAR2(32) column in the named table containing the post address infoIn most implementations this field holds the lastLine (the postal code and any areaNames in unparsed format).

postCode1Column VARCHAR2(32) column in the named table containing the postal code1 for the address

postCode2Column VARCHAR2(32) column in the named table containing the postal code2 for the address

areaName1Column VARCHAR2(32) column in the named table containing the name of the geographic/administrative entity that is the largest sub-set of a countryIn the United States this is the State, in Germany it is the Region.

areaName2Column VARCHAR2(32) column in the named table containing the name of the next smallest area of a countryIn the United States this is the County, in Germany it is the District.





The OUTPUTTABLEINFO2 Object

The OUTPUTTABLEINFO2 object stores information that defines where the output from the geocoding request should be placed. The attributes of the OUTPUTTABLEINFO2 object are defined below, along with the suggested column type and minimum size for the output table, where appropriate. All attributes of the OUTPUTTABLEINFO2 object are String types.

areaName3Column VARCHAR2(32) column in the named table containing the name of the next smallest area of a countryIn the United States this is the City, in Germany it is the Town.

areaName4Column VARCHAR2(32) column in the named table containing the name of the next smallest area of a countryIn the United States this is the Urbanization or Neighborhood, in Germany it is the Locality.

unitValueColumn VARCHAR2(32) column in the named table containing the unit value

unitTypeColumn VARCHAR2(32) column in the named table containing the unit type

defaultCountry CHAR(3) column in the named table containing the default country to be used when the INPUTTABLEINFO2 country field is empty or a record in the input table does not have a value in this field.


tableName VARCHAR2(65) column in the named table where the fully qualified output table name will be written

keyColumn VARCHAR2(32) column in the named table where the column name linking input to output will be written

countryColumn VARCHAR2(32) column in the named table where the ISO standard abbreviation for this candidate’s country will be written

genericField1Column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion
















placeNameColumn VARCHAR2(32) column in the named table where the placename of a candidate address will be written

formattedStreetColumn VARCHAR2(32) column in the named table where the formatted street address will be written (not parsed into individual fields, for example: ’10 Main St Apt 2’)

preAddressColumn VARCHAR2(32) column in the named table where the String assigned by the country geocoder to preAddress will be written

addressNumberColumn VARCHAR2(32) column in the named table where the address number for the candidate will be written (some implementations may return this combined with street address info in one or more of the following fields)

preDirectionalColumn VARCHAR2(32) column in the named table where the pre direction of a parsed input street will be written

preThoroughfareTypeColumn VARCHAR2(32) column in the named table where the pre type of a parsed input street will be written





mainAddressColumn VARCHAR2(32) column in the named table where the street address will be written.Different countries may be implemented to use this field for a different purpose, based on local address requirements.

postThoroughfareTypeColumn VARCHAR2(32) column in the named table where the post type of a parsed input street will be written

postDirectionalColumn VARCHAR2(32) column in the named table where the post directional of a parsed input street will be written

postAddressColumn VARCHAR2(32) column in the named table where the post address info will be written.In most implementations this field holds the lastLine (the postal code and any areaNames in unparsed format).

postCode1Column VARCHAR2(32) column in the named table where the postal code1 for the address will be written

postCode2Column VARCHAR2(32) column in the named table where the postal code2 for the address will be written

areaName1Column VARCHAR2(32) column in the named table where the name of the geographic/administrative entity that is the largest sub-set of a country will be written.In the United States this is the State, in Germany it is the Region.

areaName2Column VARCHAR2(32) column in the named table where the name of the next smallest area of a country will be written.In the United States this is the County, in Germany it is the District.

areaName3Column VARCHAR2(32) column in the named table where the name of the next smallest area of a country will be written.In the United States this is the City, in Germany it is the Town.

areaName4Column VARCHAR2(32) column in the named table where the name of the next smallest area of a country will be written.In the United States this is the Urbanization or Neighborhood, in Germany it is the Locality.

unitValueColumn VARCHAR2(32) column in the named table where the unit value will be written

unitTypeColumn VARCHAR2(32) column in the named table where the unit type will be written

xColumn VARCHAR2(32) column in the named table where the x coordinate for the input address will be written

yColumn VARCHAR2(32) column in the named table where the y coordinate for the input address will be written

SRIDColumn VARCHAR2(32) column in the named table where the Oracle SRID will be written.The Oracle SRID represents the coordinate system the x and y coordinates should be interpreted in





Managing Geocoding Preferences

The MapInfo Geocoding Cartridge installs a default preference (see Installed Default Preference on page 43), however; these settings may be modified for your needs. To change these settings, use the functions in the MM_ADMIN package. The system administrator or MISYS account may grant execute permission on this package to other accounts as needed.

Preferences are stored in the MISYS_PREFERENCES2 table. The MISYS_DEFAULT_PREFERENCES2 table contains one entry, a pointer to the MM_PREFERENCE2 object in MISYS_PREFERENCES2 which is to be used for default geocoding preferences. Whenever the Cartridge is invoked without a preference name or a preference object, the default preference is used.

To determine which preference is the default the user can run MISYS.MM_ADMIN.print_default_preference_name. This prints the preference name of the default preference.

spatialObjectColumn VARCHAR2(32) column in the named table where the name of a MDSYS.SDO_GEOMETRY column to put the point returned by the geocoder will be written

closematchFlagColumn VARCHAR2(32) column in the named table that will contain a T if true (if the geocoder considered this candidate a closematch). F if false.

TotalCandidatesColumn VARCHAR2(32) column in the named table where the total number of candidates found by the geocoder for the input address will be written

TotalCloseCandidatesColumn VARCHAR2(32) column in the named table where the total number of candidates that the geocoder considered close matches will be written. Close candidates are ordered first in the candidate array.

resultCodeColumn VARCHAR2(32) column in the named table where the result code for the candidate will be written. This corresponds to the type of point returned as well as which fields in the input address matches the corresponding fields in this candidate.

errorCodeColumn VARCHAR2(32) column in the named table where the number corresponding to a type of address related error will be written. Does not include server, user and database errors, as these errors abort the geocoding process.

errorMessageColumn VARCHAR2(32) column in the named table where the text of an address related error will be written





The syntax for setting up preferences is shown below. The preference name is used as the index in the MISYS_PREFERENCES2 table. The server URL connection information describes the connection to the MapMarker XML Server. The BatchCount is used as the commit interval when using the geocode_Table procedures. The remaining parameters are settings of the geocoding engine. See the MM_PREFERENCE2 object for a description of these settings.

Installed Default Preferencename VARCHAR2 default initialfrefs,closeOnly CHAR(1) default F,maxCandidates NUMBER default 1,maxRangesPerCandidate NUMBER default 0,MaxRangeUnitsPerRange NUMBER default 0,serverURL VARCHAR2 default [dependant on installer],batchSize NUMBER default 1,postalFallback CHAR(1) default T,geographicFallback CHAR(1) default T,cornerOffsetUnit VARCHAR2 default ft,cornerOffsetDistance NUMBER default 20,streetOffsetUnit VARCHAR2 default ft,streetOffsetDistance NUMBER default 20,RequestSRID NUMBER default 8307(WGS-84),mustMatchAddressNUMBER CHAR(1) deafult F,mustMatchAreaName1 CHAR(1) deafult F,mustMatchAreaName2 CHAR(1) deafult F,mustMatchAreaName3 CHAR(1) deafult F,mustMatchAreaName4 CHAR(1) deafult F,mustMatchPostal CHAR(1) deafult F,mustMatchInput CHAR(1) deafult F,genericFlag1 CHAR(1) deafult F,genericFlag2 CHAR(1) deafult F,genericFlag3 CHAR(1) deafult F,genericFlag4 CHAR(1) deafult F,genericFlag5 CHAR(1) deafult F,genericFlag6 CHAR(1) deafult F,genericFlag7 CHAR(1) deafult F,genericFlag8 CHAR(1) deafult F,genericField1 VARCHAR2 default null,genericField2 VARCHAR2 default null,genericField3 VARCHAR2 default null,genericField4 VARCHAR2 default null,genericField5 VARCHAR2 default null,genericField6 VARCHAR2 default null,genericField7 VARCHAR2 default null,genericField8 VARCHAR2 default null);

To create the default preferences, an MM_ADMIN procedure sets an object in the MISYS_PREFERENCES2 table to be the sole entry in the MISYS_DEFAULT_PREFERENCES2 table. You invoke this procedure giving it the preference name of the preferences to be set as default.

procedure set_default_preferences(preferenceName in VARCHAR2);

Use the following procedure to print out the name of the preference that is currently the default preference.

MM_ADMIN.print_default_preference_name




To print the current version, use the following procedure:

MM_ADMIN.print_product_version(country in VARCHAR2)

If the country is null or not installed, only the core MapInfo Geocoding Cartridge version is printed.

Troubleshooting

In this chapter:

! Preliminary Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46! MapInfo Geocoding Cartridge Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4

User’s Guide Chapter 4: Troubleshooting



Preliminary Considerations

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.

MapMarker XML Server Consider the following.

• Do you have the correct URL? • Can you geocode from the Oracle server machine using the MapMarkerClientGUI

sample?• Verify that you can geocode an address. • Does it geocode? If not, check that the settings and preferences match the working

MapMarker. • If you have your own application to function the Server, compare it to the

MapMarkerClientGUI.

Refer to the MapMarker XML Server documentation that shipped with your MapMarker product for additional troubleshooting guidelines.

MapInfo Geocoding CartridgeConsider these questions.

• Does the MISYS account exist? • Does your account have privileges for the requested operation? • Does MISYS have privileges to your input/output table?

input: select

output: update/insert

• If geocoding from a schema other than MISYS, have you included the schema as part of the input/output table names?




MapInfo Geocoding Cartridge Error Codes

The following error codes may be returned by the MapInfo Geocoding Cartridge. In the event of an error, verify that MapMarker and the MapMarker J Server are running and test that they can access the Address Dictionary by geocoding an address. If the error refers you to the Oracle log, it is found in the udump directory of the admin area for the database. The error codes below can provide more information for MapInfo Technical Support if an error occurs.

Error Code Description

ORA-20000: 1 No default preference.

ORA-20000: 2 Too many default preference entries.

ORA-20000: 3 Problem selecting default preference or named preference.

ORA-20000: 4 No preference named XXX found.

ORA-20000: 5 Geoaddress not geocoded.

ORA-20000: 6 No candidate at index.

ORA-20000: 7 No addressrange at index.

ORA-20000: 8 No input country given.

ORA-20000: 9 No server url given.

ORA-20000: 10 Internal error accessing CANDIDATESET2.

ORA-20000: 11 Internal error accessing ADDRESSRANGESET2.

ORA-20000: 12 Internal error accessing ADDRESSRANGEUNITSET2.

ORA-20000: 13 Internal error assigning GEOADDRESS2.

ORA-20000: 14 Internal error assigning CANDIDATESET2.

ORA-20000: 15 Internal error assigning ADDRESSRANGESET2.

ORA-20000: 16 Internal error assigning ADDRESSRANGEUNITSET2.

ORA-20000: 17 Invalid OUTPUTTABLEINFO2.

ORA-20000: 18 Internal error setting up input table.

ORA-20000: 19 Internal error accessing input records.

ORA-20000: 20 Internal error setting up output table.

ORA-20000: 21 Internal error outputting to output table. Note: A more detailed error message may exist in the trace file. See your Oracle

documentation for information on working with trace files.

ORA-20000: 22 Internal error updating GEOADDRESS2.

ORA-20000: 23 Internal error translating MM_PREFERENCE2.




ORA-20000: 24 Internal error translating GEOADDRESS2.

ORA-20000: 25 Internal error translating CANDIDATE2.

ORA-20000: 26 Internal error translating ADDRESSRANGE2.

ORA-20000: 27 Internal error translating ADDRESSRANGEUNIT2.

ORA-20000: 28 Internal error handling SRID.

ORA-20000: 29 Internal error creating input address.

ORA-20000: 30 Internal error handling metadata SRID for output table.

ORA-20000: 31 Internal error accessing MM_PREFERENCE2.

ORA-20000: 32 NULL key read from input table.

ORA-20000: 33 No ADDRESSRANGEUNIT2 at index.

Error Code Description

MapInfo Geocoding Cartridge Examples

To learn how to geocode to MapMarker using the MapInfo Geocoding Cartridge, look at the demos in the MapInfoGeocodingCartridge3.0\demo directory for example SQL scripts. To run them, log in as MISYS.

In this appendix:

! geoaddr_demo.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50! single_fields.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50! single_geoaddr.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51! table_fields.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51! table_geoaddr.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52! trigger_fields.trg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52! trigger_geoaddr.trg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

A

User’s Guide Chapter A: MapInfo Geocoding Cartridge Examples



geoaddr_demo.sql

This script demonstrates how to geocode addresses in a GEOADDRESS2 object and return the best match candidate.

1. The script creates a table named testgeo1 with a GEOADDRESS2 object and a Oracle spatial object.

2. It then inserts address information into the addr column of the table leaving the spatial object as null.

3. The addr column is then geocoded using the MapInfo Geocoding Cartridge defaults.4. Once the addr column has been geocoded, the spatial column of the table is updated with

the best match candidates.5. The addr column is then scrubbed using information returned by the MapMarker Server.

After running this demonstration script, you can remove the testgeo1 table by uncommenting and executing the last line in the script:

drop table testgeo1;

single_fields.sql

This script demonstrates how to geocode a single address when you do not have a GEOADDRESS2 object.

Note: This script uses the first candidate even if there are multiple, equal matches.

1. The script turns on tracing so dbms_output will show up.2. Then it creates a MISYS.GEOADDRESS2 object containing the address to be geocoded.3. The script then geocodes using the MapInfo Geocoding Cartridge defaults.4. If successful, the x/y coordinates of the first candidate are shown.

After running this demonstration script, you can remove the temporary procedure created by this example by uncommenting and executing the last line in the script:

drop procedure single_fields;




single_geoaddr.sql

This script demonstrates how to geocode a single address in a GEOADDRESS2 object.

1. The script turns on tracing so dbms_output will show up.2. Then it creates a MISYS.GEOADDRESS2 object containing the address to be geocoded.3. The script then geocodes using the MapInfo Geocoding Cartridge defaults.4. If successful, the x/y coordinates of the first candidate are shown.

After running this demonstration script, you can remove the temporary procedure created by this example by uncommenting and executing the last line in the script:

drop procedure single_geoaddr;

table_fields.sql

This script demonstrates how to geocode a table when address information is not contained in GEOADDRESS2 objects. To use the code contained in this script on your own table, you must replace the table and column names with names applicable to your table.

Note: This script uses only the street, zip, x and y fields. You may want to expand it to use other fields such and city, state, output firm, etc. It also uses the first candidate even if there are multiple, equal matches.

1. The script first drops table temp_geotable. This will show an error if the table does not exist.

2. It then creates and populates a temporary table and inserts the table metadata into USER_SDO_GEOM_METADATA.

3. Table temp_geotableout is then dropped. This will show an error if the table does not exist.4. A second temporary table is then created for storing geocode results.5. The script then creates a procedure named table_fields that assigns the

INPUTTABLEINFO2 and OUTPUTTABLEINFO2 objects and calls the geocode_table procedure. Next, the table_fields procedure is called and the results are selected from the tables.

After running this demonstration script, you can remove the temporary data created by this example by uncommenting and executing the last three lines in the script:

drop table temp_geotable;drop table temp_geotableout;drop procedure table_fields;




table_geoaddr.sql

This script demonstrates how to geocode a table when address information is contained in a GEOADDRESS2 object. It also shows how to create a new preferences object to use during the geocode. To use the code contained in this script on your own table, you must replace the table and GEOADDRESS2 column names with names applicable to your table.

1. The script turns on tracing so dbms_output will show up.2. Table temp_geotable is then dropped. This will show an error if the table does not exist.3. The script then creates and populates a temporary table.4. A procedure that will geocode the table using new preference settings is then created. The

default preferences are modified to allow for 4 candidates, each with 3 ranges and 3 range units.

5. The table is then geocoded using the modified MapInfo Geocoding Cartridge settings.

After running this demonstration script, you can remove the temporary data created by this example by uncommenting and executing the last line in the script:

drop table temp_geotable;

trigger_fields.trg

This script demonstrates how to geocode a new or updated record when you do not have a GEOADDRESS2 column. If you don't have a MISYS.GEOADDRESS2 column in your table you can use the code supplied within this script. You must replace the table and column names with names applicable to your table.

Note: This code uses the first candidate even if there are multiple, equal matches.

1. This script first drops table temp_coltrigger. This will show an error if the table does not exist.

2. Then a new table named temp_coltrigger is created containing company, add1, add2, city, state, and zip columns. Next, OutFirm, OutStreet, OutCity, OutState, OutZIP, longitude, latitude, and georesult columns are added to the table.

3. The trigger is then created.4. A new address is then inserted. After the insert, candidate information should be

automatically inserted into the temp_coltrigger table.


drop table temp_coltrigger;




trigger_geoaddr.trg

This script demonstrates how to add a trigger to a table that invokes a geocoding request when the information GEOADDRESS2 column changes. This trigger will geocode a row whenever its GEOADDRESS2 column changes, assuming that you store the street address information in a column of type GEOADDRESS2.

1. This script first drops table temp_geotrigger. This will show an error if the table does not exist.

2. Then a new table named temp_geotrigger is created.3. A trigger is defined so that upon insert or update of a GEOADDRESS2 object, the x and y

coordinates of the object is returned.4. Two valid addresses and one invalid address are then inserted into the table.5. Addresses are then inserted. After the insert, candidate information should be

automatically inserted into the geoaddr column of the temp_coltrigger table.


drop table temp_geotrigger;

Glossary

In this appendix:

! Glossary of Address and Geocoding Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

B

User’s Guide Appendix B: Glossary



Glossary of Address and Geocoding Terms

CandidateRecord from the MapMarker Server that is considered a potential match for the input address, based on its score.

CityName of city.

CoordinateAn x,y location in a Cartesian coordinate system, or a Latitude, Longitude location in an earth coordinate system. Coordinates represent locations on a map relative to other locations. Earth coordinate systems may use the equator and the Greenwich prime meridian as fixed reference points. Plane coordinate systems describe a two-dimensional x,y location in terms of distance from a fixed reference and are usually in the first quadrant so that all coordinates are positive numbers.

Country DivisionName of subdivision of a country.

DatabaseAny organized collection of data. The term is often used to refer to a single file or table of information in MapInfo.

GeocodeThe process of assigning X and Y coordinates to records in a table or database so that the records can be displayed as objects on a map.

PlacenameName of a firm, business, or organization at the address.

Post CodeUnique identifier for postal mailing zones.

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

Result CodeA alphanumeric code that describes the type and accuracy of the geocoding match.

User’s Guide Appendix B: Glossary



StreetName of the street.

UnitA subdivision of a specific location (for example, a suite in an office building or an apartment in a residential building).

v.3.0 user’s guide - mapinfo pro™ - desktop gis | gis...

Documents