Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its

Transcription

1 v.3.0 User s Guide

2 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 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) Fax: (518) Sales Info Hotline: (800) Government Sales Hotline: (800) Technical Support Hotline: (518) Technical Support Fax: (518) Contact information for North American offices is located at: Contact information for European and Middle East offices is located at: Contact information for Asia Pacific offices is located at: 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

3 Table of Contents Chapter 1: Introduction Product Overview What s New Integration Considerations for Users of Previous Versions Software Requirements Documentation for the MapInfo Geocoding Cartridge Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge Product Installation Overview Installing MapInfo Geocoding Cartridge Upgrading from Version Uninstalling the MapInfo Geocoding Cartridge Chapter 3: Working with the MapInfo Geocoding Cartridge Preparing to Geocode Using the MapInfo Geocoding Cartridge Geocoding a Single Address Geocoding a Table Oracle Object Types The GEOADDRESS2 Object The CANDIDATE2 Object The ADDRESSRANGE2 Object The ADDRESSRANGEUNIT2 Object The CANDIDATESET2 Object The ADDRESSRANGESET2 Object The ADDRESSRANGEUNITSET2 Object The MM_PREFERENCE2 Object The INPUTTABLEINFO2 Object The OUTPUTTABLEINFO2 Object Managing Geocoding Preferences Chapter 4: Troubleshooting Preliminary Considerations MapInfo Geocoding Cartridge Error Codes Appendix A: MapInfo Geocoding Cartridge Examples geoaddr_demo.sql single_fields.sql single_geoaddr.sql

4 Chapter 1: table_fields.sql table_geoaddr.sql trigger_fields.trg trigger_geoaddr.trg Appendix B: Glossary Glossary of Address and Geocoding Terms MapInfo Corporation. All rights reserved. 4 GeocodingCartridge.pdf

5 Introduction 1 In this chapter:! Product Overview ! What s New ! Integration Considerations for Users of Previous Versions ! Software Requirements ! Documentation for the MapInfo Geocoding Cartridge

6 Chapter 1: Introduction Product Overview 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 countryspecific preferences (with additional country cartridge layers, where available) MapInfo Corporation. All rights reserved. 6 GeocodingCartridge.pdf

7 Chapter 1: Introduction 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 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 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: 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 MapInfo Corporation. All rights reserved. 7 GeocodingCartridge.pdf

8 Chapter 1: Introduction Documentation for the MapInfo Geocoding Cartridge Several sources of documentation are provided to assist you with using the MapInfo Geocoding Cartridge effectively: This User s Guide provides installation instructions and an information on how to use the MapInfo Geocoding Cartridge. The 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 MapInfo Corporation. All rights reserved. 8 GeocodingCartridge.pdf

9 Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 2 In this chapter:! Product Installation Overview ! Installing MapInfo Geocoding Cartridge ! Upgrading from Version ! Uninstalling the MapInfo Geocoding Cartridge

10 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge Product Installation Overview There are two installation options for : 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 Installer To install 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 MapInfo Corporation. All rights reserved. 10 GeocodingCartridge.pdf

11 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 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 MapInfo Corporation. All rights reserved. 11 GeocodingCartridge.pdf

12 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 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 MapInfo Corporation. All rights reserved. 12 GeocodingCartridge.pdf

13 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 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 MapInfo Corporation. All rights reserved. 13 GeocodingCartridge.pdf

14 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 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 MapInfo Corporation. All rights reserved. 14 GeocodingCartridge.pdf

15 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 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 MapInfo Corporation. All rights reserved. 15 GeocodingCartridge.pdf

16 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 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 MapInfo Corporation. All rights reserved. 16 GeocodingCartridge.pdf

17 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge 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 Files After you run the 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 MapInfo Corporation. All rights reserved. 17 GeocodingCartridge.pdf

18 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge Upgrading from Version 2.0 There are many major structural differences between MapInfo Geocoding Cartridge 2.0 and version 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 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 MapMarkerJServer.jar; dropjava -v -u 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 MapMarkerJServer.jar; host dropjava -v -u 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 2002 MapInfo Corporation. All rights reserved. 18 GeocodingCartridge.pdf

19 Chapter 2: Installing, Upgrading, and Uninstalling MapInfo Geocoding Cartridge MM_CONVERT package The 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 2002 MapInfo Corporation. All rights reserved. 19 GeocodingCartridge.pdf

20 Working with the MapInfo Geocoding Cartridge 3 In this chapter:! Preparing to Geocode ! Using the MapInfo Geocoding Cartridge ! Geocoding a Single Address ! Geocoding a Table ! Oracle Object Types ! The GEOADDRESS2 Object ! The CANDIDATE2 Object ! The ADDRESSRANGE2 Object ! The ADDRESSRANGEUNIT2 Object ! The CANDIDATESET2 Object ! The ADDRESSRANGESET2 Object ! The ADDRESSRANGEUNITSET2 Object ! The MM_PREFERENCE2 Object ! The INPUTTABLEINFO2 Object ! The OUTPUTTABLEINFO2 Object ! Managing Geocoding Preferences

21 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 MapInfo Corporation. All rights reserved. 21 GeocodingCartridge.pdf

22 Chapter 3: Working with the MapInfo Geocoding Cartridge 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: where: ' geoaddr.areaname1 = ''NY'' ' geoaddr = object name of type GEOADDRESS2. areaname1 = attribute of geoaddr object MapInfo Corporation. All rights reserved. 22 GeocodingCartridge.pdf

23 Chapter 3: Working with the MapInfo Geocoding Cartridge 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 Preferences The 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 outputtable OUTPUTTABLEINFO2, whereclause VARCHAR2) INPUTTABLEINFO2, PROCEDURE GEOCODE_TABLE(geoaddress2table geoaddress2columnname VARCHAR2, keycolumn VARCHAR2, whereclause VARCHAR2) VARCHAR2, Using Preferences from MISYS_PREFERENCES2 Table The 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 outputtable OUTPUTTABLEINFO2, preferencename VARCHAR2, whereclause VARCHAR2) INPUTTABLEINFO2, PROCEDURE GEOCODE_TABLE(geoaddress2table geoaddress2columnname VARCHAR2, keycolumn VARCHAR2, preferencename VARCHAR2, whereclause VARCHAR2) VARCHAR2, Using the Preferences Object The following procedures geocode using the preferences object passed in the third parameter: PROCEDURE GEOCODE_TABLE(inputtable outputtable OUTPUTTABLEINFO2, preference MM_PREFERENCE2, whereclause VARCHAR2) INPUTTABLEINFO2, PROCEDURE GEOCODE_TABLE(geoaddress2table geoaddress2columnname VARCHAR2, keycolumn VARCHAR2, preference MM_PREFERENCE2, whereclause VARCHAR2) VARCHAR2, 2002 MapInfo Corporation. All rights reserved. 23 GeocodingCartridge.pdf

24 Chapter 3: Working with the MapInfo Geocoding Cartridge 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 genericfield2 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific product documentation genericfield3 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific product documentation 2002 MapInfo Corporation. All rights reserved. 24 GeocodingCartridge.pdf

25 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description genericfield4 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 genericfield6 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield7 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield8 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield9 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield10 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield11 VARCHAR2(256) Input: any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield12 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 number This 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 address Different 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 2002 MapInfo Corporation. All rights reserved. 25 GeocodingCartridge.pdf

26 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description postdirectional VARCHAR2(256) Input: post directional of a parsed input street postaddress VARCHAR2(256) Input: post address info In 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 country In 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 country In 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 country In 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 country In 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 2002 MapInfo Corporation. All rights reserved. 26 GeocodingCartridge.pdf

27 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description 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 GEOADDRESS2 Object Functions and Procedures There 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. Method findlocation() (function) findlocation(preferencename) (function) findlocation(preference) (function) findlocation() (procedure) findlocation(preferencename) (procedure) findlocation(preference) (procedure) isgeocoded() getx(candidateindex in NUMBER default 1) gety(candidateindex in NUMBER default 1) Description 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. 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. Returns a new GEOADDRESS2 object. Geocodes using the MM_PREFERENCE2 object passed in. Results returned in the returned object. 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. 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. Geocodes using the preference object passed in. Results returned in the calling object. Returns 1 if the geoaddress candidates array contains any candidates, otherwise returns 0. Returns the x-coordinate of the candidate at the given index. Returns the y-coordinate of the candidate at the given index MapInfo Corporation. All rights reserved. 27 GeocodingCartridge.pdf

28 Chapter 3: Working with the MapInfo Geocoding Cartridge getoraclespatialobject(candidateindex in NUMBER default 1) 1 getnumcandidates() Method getnumrangesforcandidate(candidateindex in NUMBER default 1) getnumrangeunitsforrange(addressrange Index in NUMBER) scrubaddress(candidateindex in NUMBER default 1) (function) scrubaddress(candidateindex in NUMBER default 1) (procedure) getcandidate(candidateindex in NUMBER default 1) getrange(rangeindex in NUMBER) getunit(unitindex in NUMBER) Description Returns the MDSYS.SDO_GEOMETRY object containing x and y information and SRID for the candidate at the given index. Returns the number of candidates in the GEOADDRESS2 object. Returns the number of address ranges for the candidate at the given index. Returns the number of address range units for the range at the given index. 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. 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. Returns the CANDIDATE2 in the GEOADDRESS2 object. Returns the ADDRESSRANGE2 in the GEOADDRESS2 object. 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. 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. Field Type Description 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 genericfield3 VARCHAR2(256) the String assigned by the country geocoder to the genericfield3 genericfield4 VARCHAR2(256) the String assigned by the country geocoder to the genericfield MapInfo Corporation. All rights reserved. 28 GeocodingCartridge.pdf

29 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type 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 genericfield8 VARCHAR2(256) requires translation layer genericfield9 VARCHAR2(256) requires translation layer genericfield10 VARCHAR2(256) requires translation layer genericfield11 VARCHAR2(256) requires translation layer genericfield12 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.) 2002 MapInfo Corporation. All rights reserved. 29 GeocodingCartridge.pdf

30 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description 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. 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. Field Type Description country VARCHAR2(3) the ISO standard abbreviation for the country this candidate is in genericfield1 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation genericfield2 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation genericfield3 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation genericfield4 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation 2002 MapInfo Corporation. All rights reserved. 30 GeocodingCartridge.pdf

31 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description genericfield5 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield6 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield7 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield8 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield9 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield10 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield11 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield12 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 preaddress VARCHAR2(256) the String assigned by the country geocoder to preaddress addressnumber VARCHAR2(256) address number This 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 address Different 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 info In most implementations this field holds the lastline (the postal code and any areanames in unparsed format). postcode1 VARCHAR2(256) postal code1 for the address postcode2 VARCHAR2(256) postal code2 for the address areaname1 VARCHAR2(256) name of the geographic/administrative entity that is the largest subset of a country In the United States this is the State, in Germany it is the Region MapInfo Corporation. All rights reserved. 31 GeocodingCartridge.pdf

32 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description areaname2 VARCHAR2(256) name of the next smallest area of a country In the United States this is the County, in Germany it is the District. areaname3 VARCHAR2(256) name of the next smallest area of a country In the United States this is the City, in Germany it is the Town. areaname4 VARCHAR2(256) name of the next smallest area of a country In 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) 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. Field Type Description country VARCHAR2(3) the ISO standard abbreviation for the country this candidate is in genericfield1 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation genericfield2 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation 2002 MapInfo Corporation. All rights reserved. 32 GeocodingCartridge.pdf

33 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description genericfield3 VARCHAR2(256) any country-specific address or location information; refer to your country-specific product documentation genericfield4 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 genericfield6 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield7 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield8 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield9 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield10 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield11 VARCHAR2(256) any country-specific address or location information; refer to your country-specific MapInfo Geocoding Cartridge layer documentation genericfield12 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 preaddress VARCHAR2(256) the String assigned by the country geocoder to preaddress addressnumber VARCHAR2(256) address number This 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 address Different 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 info In most implementations this field holds the lastline (the postal code and any areanames in unparsed format). postcode1 VARCHAR2(256) postal code1 for the address postcode2 VARCHAR2(256) postal code2 for the address 2002 MapInfo Corporation. All rights reserved. 33 GeocodingCartridge.pdf

34 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description areaname1 VARCHAR2(256) name of the geographic/administrative entity that is the largest subset of a country In the United States this is the State, in Germany it is the Region. areaname2 VARCHAR2(256) name of the next smallest area of a country In the United States this is the County, in Germany it is the District. areaname3 VARCHAR2(256) name of the next smallest area of a country In the United States this is the City, in Germany it is the Town. areaname4 VARCHAR2(256) name of the next smallest area of a country In 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 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 MapInfo Corporation. All rights reserved. 34 GeocodingCartridge.pdf

35 Chapter 3: Working with the MapInfo Geocoding Cartridge 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. Field Type Description 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 endpoint addresses in corneroffset distance and compute all in between addresses from this imaginary segment MapInfo Corporation. All rights reserved. 35 GeocodingCartridge.pdf

36 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description 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) mustmatchareaname2 CHAR(1) close candidates must match the areaname2 given in input (T= true) mustmatchareaname3 CHAR(1) close candidates must match the areaname3 given in input (T= true) mustmatchareaname4 CHAR(1) close candidates must match the areaname4 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 genericflag2 CHAR(1) to be interpreted by a specific country s implementation genericflag3 CHAR(1) to be interpreted by a specific country s implementation genericflag4 CHAR(1) to be interpreted by a specific country s implementation genericflag5 CHAR(1) to be interpreted by a specific country s implementation genericflag6 CHAR(1) to be interpreted by a specific country s implementation genericflag7 CHAR(1) to be interpreted by a specific country s implementation genericflag8 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 genericfield2 VARCHAR2(256) any country-specific input other than a true or false setting genericfield3 VARCHAR2(256) any country-specific input other than a true or false setting genericfield4 VARCHAR2(256) any country-specific input other than a true or false setting genericfield5 VARCHAR2(256) any country-specific input other than a true or false setting 2002 MapInfo Corporation. All rights reserved. 36 GeocodingCartridge.pdf

37 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description genericfield6 VARCHAR2(256) any country-specific input other than a true or false setting genericfield7 VARCHAR2(256) any country-specific input other than a true or false setting genericfield8 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. Field Type Description 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 genericfield2column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield3column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield4column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield5column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield6column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield7column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield8column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield9column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion 2002 MapInfo Corporation. All rights reserved. 37 GeocodingCartridge.pdf

38 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description genericfield10column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield11column VARCHAR2(32) column in the named table containing any country-specific address or location information; use at your discretion genericfield12column 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 address 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 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 info 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 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 country In 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 country In the United States this is the County, in Germany it is the District MapInfo Corporation. All rights reserved. 38 GeocodingCartridge.pdf

39 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description areaname3column VARCHAR2(32) column in the named table containing the name of the next smallest area of a country In 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 country In 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. 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. Field Type Description 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 genericfield2column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield3column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion 2002 MapInfo Corporation. All rights reserved. 39 GeocodingCartridge.pdf

40 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description genericfield4column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield5column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield6column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield7column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield8column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield9column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield10column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield11column VARCHAR2(32) column in the named table where any country-specific address or location information will be written; use at your discretion genericfield12column 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 2002 MapInfo Corporation. All rights reserved. 40 GeocodingCartridge.pdf

41 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description 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 2002 MapInfo Corporation. All rights reserved. 41 GeocodingCartridge.pdf

42 Chapter 3: Working with the MapInfo Geocoding Cartridge Field Type Description 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 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 MapInfo Corporation. All rights reserved. 42 GeocodingCartridge.pdf

43 Chapter 3: Working with the MapInfo Geocoding Cartridge 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 Preference name 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 2002 MapInfo Corporation. All rights reserved. 43 GeocodingCartridge.pdf

44 Chapter 3: Working with the MapInfo Geocoding Cartridge 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 MapInfo Corporation. All rights reserved. 44 GeocodingCartridge.pdf

45 Troubleshooting 4 In this chapter:! Preliminary Considerations ! MapInfo Geocoding Cartridge Error Codes

46 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 Cartridge Consider 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? 2002 MapInfo Corporation. All rights reserved. 46 GeocodingCartridge.pdf

47 Chapter 4: Troubleshooting 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 ORA-20000: 2 ORA-20000: 3 ORA-20000: 4 ORA-20000: 5 ORA-20000: 6 ORA-20000: 7 ORA-20000: 8 ORA-20000: 9 ORA-20000: 10 ORA-20000: 11 ORA-20000: 12 ORA-20000: 13 ORA-20000: 14 ORA-20000: 15 ORA-20000: 16 ORA-20000: 17 ORA-20000: 18 ORA-20000: 19 ORA-20000: 20 ORA-20000: 21 ORA-20000: 22 ORA-20000: 23 No default preference. Too many default preference entries. Problem selecting default preference or named preference. No preference named XXX found. Geoaddress not geocoded. No candidate at index. No addressrange at index. No input country given. No server url given. Internal error accessing CANDIDATESET2. Internal error accessing ADDRESSRANGESET2. Internal error accessing ADDRESSRANGEUNITSET2. Internal error assigning GEOADDRESS2. Internal error assigning CANDIDATESET2. Internal error assigning ADDRESSRANGESET2. Internal error assigning ADDRESSRANGEUNITSET2. Invalid OUTPUTTABLEINFO2. Internal error setting up input table. Internal error accessing input records. Internal error setting up output table. 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. Internal error updating GEOADDRESS2. Internal error translating MM_PREFERENCE MapInfo Corporation. All rights reserved. 47 GeocodingCartridge.pdf

48 Chapter 4: Troubleshooting Error Code ORA-20000: 24 ORA-20000: 25 ORA-20000: 26 ORA-20000: 27 ORA-20000: 28 ORA-20000: 29 ORA-20000: 30 ORA-20000: 31 ORA-20000: 32 ORA-20000: 33 Description Internal error translating GEOADDRESS2. Internal error translating CANDIDATE2. Internal error translating ADDRESSRANGE2. Internal error translating ADDRESSRANGEUNIT2. Internal error handling SRID. Internal error creating input address. Internal error handling metadata SRID for output table. Internal error accessing MM_PREFERENCE2. NULL key read from input table. No ADDRESSRANGEUNIT2 at index MapInfo Corporation. All rights reserved. 48 GeocodingCartridge.pdf

49 MapInfo Geocoding Cartridge Examples A 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 ! single_fields.sql ! single_geoaddr.sql ! table_fields.sql ! table_geoaddr.sql ! trigger_fields.trg ! trigger_geoaddr.trg

50 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; 2002 MapInfo Corporation. All rights reserved. 50 GeocodingCartridge.pdf

51 Chapter A: MapInfo Geocoding Cartridge Examples 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; 2002 MapInfo Corporation. All rights reserved. 51 GeocodingCartridge.pdf

52 Chapter A: MapInfo Geocoding Cartridge Examples 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. 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_coltrigger; 2002 MapInfo Corporation. All rights reserved. 52 GeocodingCartridge.pdf

53 Chapter A: MapInfo Geocoding Cartridge Examples 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. 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_geotrigger; 2002 MapInfo Corporation. All rights reserved. 53 GeocodingCartridge.pdf

54 Glossary B In this appendix:! Glossary of Address and Geocoding Terms