DistribMapX

Chapter 17: Distributing Your MapX Application 17 Chapter ➤ MapX Customer Installation ➤ Installing MapX ➤ Installing Support for Spatial Server Access Handlers Distributing Your MapX Application The MapX product you have purchased from MapInfo is a developer's kit. It contains MapX, sample programs, an on-line help system, sample maps and geosets, and various utilities and other support files. This chapter deals with distributing your MapX application(s) to your customers. Please be reminded that you must purchase a Use License (i.e., seat) as evidenced by a MapInfo License certificate for each user of each application that you distribute with MapX functionality as described in the MapInfo Standard License/Development Environments, which is included in your product packaging. ➤ Installing Raster Format ➤ Installing Maps and Geosets ➤ Adding Keys to the Windows Registry String ➤ Passing in the MapX License ➤ Redistributing Your MapX Application with MrSID Application with ECW ➤ Redistributing Your MapX Chapter 17: Distributing Your MapX Application MapX Customer Installation Providing the MapX Control (i.e. the piece of MapX that needs to be distributed within your applications in order for them to work properly) in your MapX applications can be a difficult task for the inexperienced programmer due to the high number of dependent files and their complex structure. Therefore, MapInfo Corporation has begun automating the distribution process. Basically, there are two methods of distributing the MapX Control with your MapX applications. They are: • Use the MapX Installer that is provided on the MapX CD. This is the easiest method of distribution as it entails very little effort on the part of a MapX developer because certain procedures and tasks are automated. Integrate the MapX within the application you wish to distribute. This method of distribution is labor intensive and requires a substantial level of detail orientation, but provides programmers with the highest degree of control and customizing capabilities possible. • Files Installed Automatically with the Installer Running [ CD\Install\ setup.exe ] will install the following in the default MapX installation directory: C:\Program Files\MapInfo\MapX 5.0 • • • • The MapX control mapx50.dll Ιts support dlls The raster and grid dlls and handlers The default dataset drivers System dlls will also be installed in the appropriate locations (see Installing MapX on page 254). You can use setup.exe to install the default data supplied with MapX by passing it a "-data" command line argument. Integrating MapX into Applications at Runtime When you deliver your application to customers, you will need to install: • • • • The software you created MapX Control (Either via the MapX Installer –OR– your own, customized version) Related support files Maps and geosets that are used by your application Ideally you will incorporate the installation of MapX into your installation procedure so that your end user will not need to perform a separate installation to install MapX. There are four main steps to installing and distributing MapX applications: 1. Install the necessary files onto your user's computer. 2. Run utilities (such as regsvr32.exe) to register specific files on the user's system. 3. Add specific keys to the Windows registry 4. Pass in the MapX license string at application runtime. 252 MapInfo MapX Developer Guide v5.0 MapX Customer Installation Note: If you are using MapX in a dialog with Visual C++, VisualBasic, Delphi, or PowerBuilder they will take care of creating MapX with the correct license string and therefore you can skip this section. If you are creating the MapX control using the CMapX::Create() method in Visual C++ you do need to take this extra step. The files that are installed with MapX can be divided into the following categories: Required files: • • MapX DLL and its dependent DLLs Windows system files: including fonts, MFC, and OLE dlls Optional files: • • • Dataset drivers (used for databinding) Import/Export raster handlers Maps and Geosets MapInfo MapX Developer Guide v5.0 253 Chapter 17: Distributing Your MapX Application Installing MapX If you have installed MapX on your own computer, it’s easy to get a rough idea of how many files are used by MapX. MapX v4.x installs the program files under the following path “\Program Files\Common Files\MapInfo Shared\MapX Common”. MapX v5.0, by default, stores all of the required files in "\Program Files\MapInfo\MapX 5.0". This directory should be used for the MapX required files, whereas all of the files necessary for your application should go under a directory meaningful to the end-user and your specific application. Note: MapX uses some files that are not located in the MapX program directory. For example, MapX uses MFC and OLE dlls that reside in the Windows System directory. We also recommend that the MapX Program directory be: "\Program Files\MapInfo\MapX 5.0". The following table describes what files need to be installed and where they should be installed to. Files Where to Install Files Other Special Requirements Do a version check before replacing these files. If older version, during replace files may be in use and require a reboot if that is the case. Must be registered using regsvr32.exe Must be registered using regsvr32.exe. Prior to registering, make sure the MapX dependent files are installed. Must be registered using regtyplib.exe Mfc42.dll, msvcp60.dll, msvcrt.dll, ALT.dll, \Windows\System MFC42.dll, MFC42U.dll (for unicode platforms) Olepro32.dll, oleaut32.dll Mapx50.dll \Windows\System MapX common directory mdatasetint.tlb MapX common directory 254 MapInfo MapX Developer Guide v5.0 Installing MapX Files Where to Install Files Other Special Requirements MapX dependent files: MapX Program ALLTYPE.DLL, AllTypeRes.dll, AppSelection.dll directory ChangeManager.dll, ColLookupSystem.dll, CommandProcessor.dll, CommandProcessorRes.dll, COORDSYS.DLL, CoordSysRes.dll, CustomProperties.dll, DAENGINE.DLL, DAEngineRes.dll, DBINFO.DLL, DBInfoRes.dll, DBLAYER.DLL, DBLayerRes.dll, DELPHIMM.DLL, ExprPacket.dll, ExprPacketCreator.dll, ExprPacketCreatorRes.dll, ExprPacketRes.dll, FcnInfoServer.dll, FcnInfoServerRes.dll, FIND.DLL, FINDRES.DLL, GEO.DLL, GeoDictionaryManager50.exe, GeoDictionaryManagerIntl50.dll, GeoObject.dll, GeoObjectProcess.dll, GeoObjectProcessRes.dll, GeoObjectRes.dll, GEORES.DLL, GEOSET.DLL, GeosetManager50.exe, GeosetManagerIntl50.dll, GeosetRes.dll, GRIDDLL.DLL, LEGEND.DLL, LegendRes.dll, libspw_mi.dll, MapBasicInternalFcn.dll, MapBasicInternalFcnRes.dll, MapBasicTranslator.dll, MapBasicTranslatorRes.dll, MAPINFOW.FNT, MAPINFOW.PRJ, MAPPER.DLL, MapperRes.dll, MAPX.ABB, MAPX.PEN, MAPX50.DLL, MapXADODS.dll, MapXDAODS.dll, MapXRDODS.dll, mapxstate.dll, mapxstateres.dll, mdatasetint.tlb, MIAPP.DLL, MIAPPRES.DLL, MIDLG50.DLL, MIDLIN50.DLL, MILEXER.DLL, MILexerRes.dll, MIMetadata.dll, MIOCI.DLL, MIODBC.DLL, MIRDB.DLL, MIRDBRES.DLL, mirdbspatial.dll, mirdbspatialRes.dll, MIWINDOW.DLL, MIWindowRes.dll, MOCIDataset50.dll, MODBCDataset.dll, MSafeArrayDataset.dll, MXINTL50.DLL, mxmldataset.dll, RASTER.DLL, RasterRes.dll, REGSVR32.EXE, RegTypLib.exe, STYLES.DLL, TextFileReader.dll, TextFileReaderRes.dll Thematics.dll, ThematicsRes.dll, TOKENS.DLL, TOOLS.DLL, UTILITY.DLL, UtilityRes.dll, WINMGR.DLL, WinMgrRes.dll, XMLUTIL.DLL, XMLUTILRES.DLL, MapInfo MapX Developer Guide v5.0 255 Chapter 17: Distributing Your MapX Application Files Where to Install Files Other Special Requirements These fonts have to be installed and registered with the operating system. Please see below for more information. Only required if using layers with the NAD 27 and NAD 83 coordinate systems. MapX font files; Windows\Fonts ARIAL.TTF, MAPIS___.TTF, MAPSYM.TTF, directory TTMIAR__.TTF, TTMICG__.TTF, TTMIMI__.TTF, TTMIOG__.TTF, TTMIOS__.TTF, TTMIRE__.TTF, TTMITC__.TTF, TTMIWE__.TTF Nadcon support files: ALASKA.LAS, ALASKA.LOS, CONUS.LAS, CONUS.LOS, HAWAII.LAS, HAWAII.LOS, PRVI.LAS, PRVI.LOS, STGEORGE.LAS, STGEORGE.LOS, STLRNC.LAS, STLRNC.LOS, STPAUL.LAS, STPAUL.LOS Bitmap symbols: TOWE1-32.BMP, POLI1-32.BMP, MBOX232.BMP, GOLF1-32.BMP, TOWE2-32.BMP, RAIL1-32.BMP, MOSQ1-32.BMP, HOSP132.BMP, IEL2-32.BMP, RAIL2-32.BMP, ONEW132.BMP, HOUS1-32.BMP, ADG1-32.BMP, ONEW2-32.BMP, HOUS2-32.BMP, ADG232.BMP, HOUS3-32.BMP, ANK1-32.BMP, ANK232.BMP, OOK1-32.BMP, AMP1-32.BMP, TRAF132.BMP, AR1-32.BMP, TRUC1-32.BMP, RAIL332.BMP, AUT1-32.BMP, TRUC2-32.BMP, REST132.BMP, PENC1-32.BMP, HUR1-32.BMP, YIEL132.BMP, STAT1-32.BMP, PIN1-32.BMP, HYDR132.BMP, AMBU1-32.BMP, STOP1-32.BMP,PIN232.BMP, INTE1-32.BMP, COMP1-32.BMP, SYNA1-32.BMP, PIN3-32.BMP, LITE1-32.BMP, FARM1-32.BMP, TARG1-32.BMP, PIN4-32.BMP, LITE2-32.BMP, FAST1-32.BMP, TAXI1-32.BMP, PIN5-32.BMP, MAIL1-32.BMP, FIRE1-32.BMP, TEMP1-32.BMP, PIN6-32.BMP, MBOX1-32.BMP, GLOB1-32.BMP, MapX Program directory Underneath the MapX Only required if using Program directory, in a custom bitmap symbols. directory called Custsymb. For example: \Program Files\MapInfo\MapX\ Custsymb 256 MapInfo MapX Developer Guide v5.0 Installing MapX Installing Fonts MapX also uses some TrueType fonts. These font files (*.ttf) must be copied to Window’s Font Folder. Fonts must also be registered with Windows. If you are using a third-party software package to create your installer, that package might handle font registration for you. Otherwise, you can register fonts manually, by calling the Win32 AddFontResource routine. Once a font is properly registered, the registry contains a corresponding key under: • -or• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Fonts MapInfo MapX Developer Guide v5.0 257 Chapter 17: Distributing Your MapX Application Installing Support for Spatial Server Access If accessing data in a spatially enabled RDBMS like SpatialWare for Oracle, Informix, or DB2 or Oracle 8i Spatial, then the drivers below are needed. Spatial Server SpatialWare MapInfo ODBC Oracle 8i Spatial Dataset drivers Miodbc.dll, mirdb.dll, mirdbspatialres.dll, mirdbspatial.dll Mioci.dll, mirdb.dll, mirdbspatialres.dll Installation requirements Odbc32.dll must exist in system path Odbc32.dll must exist in system path Registering Files and Installing Dataset Drivers As mentioned in the preceding table, some files need to be ‘registered’. Most of the files that need to be registered can be registered by running the utility regsvr32.exe: • • • regsvr32 /s regsvr32 /s regsvr32 /s If your application uses the ODBC data driver, you must register MODBCDataset.dll. If your application uses the Notes data driver, you must register MNotesDataset.dll and MMapXColumnInfo.dll. If your application uses either the ODBC or the Notes data driver, you must register the type library as follows: regtyplib MapX allows you to bind data to a map layer. Please see,”Chapter 9: Putting Your Data On The Map” on page 99 for additional information. Note: All of these dataset drivers should be installed in the same directory as MapX. This table illustrates the various options for data binding and what the installation requirements are. All of the files below must be registered with ressup32.exe. Dataset source type Lotus Notes ODBC Delphi v3 Delphi v4 Dataset drivers Mnotesdataset.dll MODBCDataset.dll MgenDSetDrvr.dll, Dslibp.dll MgenDSetDrvr.dll, Dslibp4.dll Installation Requirements Nnotes.dll must be in the system path Odbc32.dll must be in the system path Delphimm.dll must be in the system path Borlndmm.dll must be in the system path. Run RegisterDS4.exe on Dslibp4.dll 258 MapInfo MapX Developer Guide v5.0 Installing Support for Spatial Server Access Dataset source type Delphi v5 Dataset drivers MgenDSetDrvr.dll, Dslibp5.dll Installation Requirements Borlndmm.dll must be in the system path. Run RegisterDS5.exe on Dslibp5.dll Borlndmm.dll must be in the system path. Run registerDS6.exe on Dslibp6.dll Delphi v6 MgenDSetDrvr.dll, Dslibp6.dll Safe Array ADO v2.0 RDO v2.0 OCI DAO XML MsafeArrayDataset.dll MapXADODS.dll, ATL.dll MapXRDODS.dll, ATL.dll MOCIDataset50.dll MapXDAODS.dll mxmldataset.dll ADO must be installed RDO must be installed Oracle client, mioci.dll, and mirdb.dll must be installed MDAC v2.5 or greater msxml4 must be installed MapInfo MapX Developer Guide v5.0 259 Chapter 17: Distributing Your MapX Application Installing Raster Format Handlers MapX also allows the developer to incorporate raster images into their application. A MapX application may open or write to various raster image types. The appropriate drivers must be included when distributing your application. MapX can use one of many different libraries to load a raster image. When a raster image is loaded by MapX, it will search for these DLLs and ask them if the given file can be read by that DLL. Once one answers yes, MapX knows which DLL will be doing format handling for the file. The Format handlers will be named "xxxxxxxx.RHx". The base part of the name is based on the format. The extension always begins with RH, but can end in any letter (A-Z). When searching for a format handler, MapX starts with RHA, then RHB, and so forth until RHZ. This allows MapX to prioritize which handlers are used. For example, SPOT files need to be checked for before any other formats since they are just raw data that can be confused with other formats. The SPOT handler's extension is RHD. The Halo format handlers (the standard built in ones) are named RHV. The Lead Tools are named RHX. The LEADTOOLS Win32 Pro provided by ©LEAD Technologies, Inc and HALO Imaging libraries provided by Media Cybernetics are included with MapX. You may use either of these to display most raster files in MapX. LeadTools will load the entire raster image into memory at the time the image is referenced in MapX. This will mean that the image will take longer to load, but panning and zooming will be faster. HALO will only load what it needs to display into memory, so it will load the image faster, but panning and zooming will be slower. By default, HALO will be attempted first. You may change this order by either not including the HALO libraries when distributing your application, or by renaming the LeadTools handler from a .rhx to a .rhu or anything else not used before the letter “x”. There may also be some formats which are not supported by either library and therefore will have their own separate library. Note: All of these raster handlers should be installed in the same directory as MapX. Here is a table of handlers included with MapX: Format Handler All Raster types Lead Tools Format Handler MIRASTER.DLL (MIRASTERU.DLL for unicode) LTFIL12N.DLL, LTKRN12N.DLL, LTDIS12N.DLL, LEADTOOL.RHX BMP: LFBMP12N.DLL JPG: LFCMP12N.DLL GIF: LFGIF12N.DLL J2K: LFJ2K12N.DLL PNG: LFPNG12N.DLL PSD: LFPSD12N.DLL TIF: LFTIF12N.DLL, LFFAX12N.DLL WMF: LFWMF12N.DLL Supported Raster Types and DLLs needed 260 MapInfo MapX Developer Guide v5.0 Installing Raster Format Handlers Supported Raster Types and DLLs needed BMP: miffbmp.dll GIF: miffgif.dll JBPG: miffjpeg.dll PCX: miffpcx.dll TGA: mifftga.dll TIF: mifftiff.dll Or you may use the Lead Tools or Halo TIF library BIL ECW Format Handler Halo Libraries Format Handler Halo.rhv, Mihiffl.dll TIF SPOT ECW TIFF.RHL Spot.rhd ECW.RHL NCSCNET.DLL NCSECW.DLL NCSECWEX.DLL NCSUTIL.DLL MIGRID.DLL ( MIGRIDU.DLL for Unicode) MIRASTER.DLL (MIRASTERU.DLL - for Unicode) GRIDDLL.DLL, MIG.GHL ADAGASRP.RHL CADRGCIB.RHL VMGRID.DLL, NWGRD30.GHL DTED.GHL Northwood Grid (as raster) GRD MapInfo Grid Government Government Northwood Grid (as grid) DTED MIG ADRG, ASRP CADRG, CIB, NITF GRD DT? DEM DEM USGS Digital Elevation DEM.GHL Grid GTOPO Grid GTOPO30.GHR MapInfo MapX Developer Guide v5.0 261 Chapter 17: Distributing Your MapX Application Installing Maps and Geosets Registering a geoset is a convenient way of registering each MapInfo table associated with that geoset into the GeoDictionary. By registering a MapInfo table in the GeoDictionary, that table can be used for autobinding. To get more information regarding autobinding, please refer to, ”Chapter 9: Putting Your Data On The Map” on page 99. If it is determined that you need to use the GeoDictionary, when you register a geoset, GeoDictionaryManager50.exe adds appropriate entries into the Geodictionary (geodict.dct). If the Geodictionary does not exist, GeoDictionaryManager50.exe creates one. This step must be done after all of the Geosets and associated tables are installed on the user’s machine. Double check your geoset to see what the expected paths are for each table. For example, if you created a geoset using MapInfo tables on different areas of your hard drive, the geoset will specify the full path to anything not in the same directory as the geoset. If redistributing this geoset, the tables will have to be found in the same paths as the original geoset. To avoid this problem, copy all MapInfo tables into the same directory prior to creating the geoset. Then create the geoset in that same directory. 262 MapInfo MapX Developer Guide v5.0 Adding Keys to the Windows Registry Adding Keys to the Windows Registry MapX also uses the following five registry keys (which your installer must create on the end-user's system, if they do not exist already). The MapX installer creates these keys when you install MapX on your system. Therefore, if you want to see what these registry keys should look like, view your system's registry using a utility such as regedit.exe. Key HKEY_LOCAL_MACHINE\Software\_ MapInfo\MapX 5.0\GeoDictionary Description String - The GeoDictionary key has the file specification for the geodictionary file. Example: C:\Program Files\myappdir\Maps\GeoDict.DCT String - The SearchPaths key has semicolondelimited file specifications of where map files and geosets may exist; it defaults to an empty string ("") other than in the directory specified in the GeoDictionary key. String - Has the location of the folder where MapX and support files are Located. Example: \Program Files\Common Files\MapInfo Shared\MapX Common String - Location of MapX Control and support files. String - MapX version. HKEY_LOCAL_MACHINE\Software\_ MapInfo\MapX 5.0 \SearchPaths HKEY_LOCAL_MACHINE\Software\_ MapInfo\MapX 5.0\ CommonDLLDir HKEY_LOCAL_MACHINE\Software\MapInfo\_ MapX\5.0\Program Dir HKEY_LOCAL_MACHINE\Version Code\ Note: The GeoDictionary path is used when adding a geoset to the MapX object without specifying the full path of the Geoset and when using autobinding. In addition, the SearchPaths key is not necessary if not using the GeoDictionary. See “Installing Maps and Geosets” to determine whether or not these keys are necessary for your application. MapInfo MapX Developer Guide v5.0 263 Chapter 17: Distributing Your MapX Application Passing in the MapX License String In order to instantiate a runtime version of MapX on your user’s computer, the license string must be passed in at the time of object creation during the executing of your application. Note: If you are using MapX in a dialog with Visual C++, VisualBasic, Delphi, or PowerBuilder they will take care of creating MapX with the correct license string and therefore you can skip this section. If you are creating the MapX control using the CMapX::Create() method in Visual C++ you do need to take this extra step. Visual C++ Again, if using MapX in a dialog in Visual C++, you do not need to perform this step. In order to successfully create the MapX object, you must pass the license string as the bstrLicKey parameter to CMapx::Create(). 264 MapInfo MapX Developer Guide v5.0 Redistributing Your MapX Application with MrSID Redistributing Your MapX Application with MrSID In the event Licensee wishes to deploy an application which supports the MrSID file format (*.sid), Licensee shall include the following text: MrSID software (specifically the mrsid32.dll) is used under license and is Copyright © 1995-2002, LizardTech, Inc., 1008 Western Ave., Suite 200, Seattle, WA 98104. All rights reserved. MrSID is protected by U.S. Patent No. 5,710,835. Foreign patents are pending. Unauthorized use or duplication prohibited. Patented technology in the Software was developed in part through a project at the Los Alamos National Laboratory, funded by the U.S. Government and managed by the University of California. The U.S. Government has reserved rights in the technology, including a non-exclusive, nontransferable, irrevocable, paid-up license to practice or have practiced throughout the world, for or on behalf of the United States, inventions covered by the patent, and has other rights under 35 U.S.C. § 200-212 and applicable implementing regulations. For further information, contact Lizardtech. MapInfo MapX Developer Guide v5.0 265 Chapter 17: Distributing Your MapX Application Redistributing Your MapX Application with ECW If you need to deploy an application which supports the ECW raster file format (*.ecw), you must include the following copyright information: ECW for MapInfo is Copyright MapImagery Limited. See the MapImagery web site http://www.mapimagery.com for more information. The ECW compression format is Copyright Earth Resource Mapping. See the Earth Resource Mapping web site: http://www.ermapper.com for more information. The ECW compression Technology is covered by one or more of U.S. Patent Nos. 6,201,897 266 MapInfo MapX Developer Guide v5.0