After you complete your application, you may want to distribute it to others and deploy it on other machines. Most application distributors choose to create special setup programs that copy all necessary files and register pertinent software objects on the target computer. The language or application you use to create these programs is entirely up to you. Software setup programs generally display friendly menus of choices and options. Depending on the type of components used by your application, various program files and other components may need to be installed and self-registered.
The information in this document focuses on the installation requirements for MapObjects only and does not address the requirements of any additional components or runtime libraries that your application may also need. See your particular programming environment documentation for details on how to properly distribute your applications.
When you distribute your application, you must ensure that all applicable components are properly registered in the target system's registry database and that all the necessary support files are available. Depending on the programming environment used to develop your application, this task may or may not be automated.
MapObjects ActiveX Components must be properly registered in the target system's registration database. You can do this by running RegSvr32.exe and passing the name of the component file on the command line. RegSvr32.exe is a freely distributeable program provided by Microsoft and it is installed in the MapObjects installation directory. Your setup program can alternatively use each component's exported DllRegisterServer function to perform the same actions as running RegSvr32.exe on the component. See DllRegisterServer in Microsoft's OLE SDK documentation for details.
Since more and more software is COM-based, most setup program generators today have the ability to self-register files. If your setup program generation software does not include this ability, you can add lines to your setup program that call RegSvr32 with the name of the component on the command line. See your particular setup program generator documentation for information on how to call external programs.
You can also use a /s at the beginning of the command line to make the process silent, otherwise RegSvr32 will display a success or failure dialog after the self-registration attempt:
RegSvr32.exe /s C:\Windows\System\MO10.ocx
Depending on what your MapObjects application does, you'll have to deploy different sets of files as specified in the following sections.
Note: You may under no circumstances distribute the file named Mo10.lic. Distribution of this file constitutes a violation of your License Agreement with ESRI.
Files marked with an asterisk (*) in the sections below require that they be self-registered on the target system. Other files need only be copied, but a note of caution here -- some of the files are dependencies for other files during self-registration. For example, AF10.dll itself doesn't need to be self-registered but it is a dependency of MO10.ocx, so it must be accessible during the registration process. Files that are in the Windows\System(32) directory, the Windows directory, and the current directory as well as directories noted in the PATH variable are accessible. To self-register files in a directory other than the Windows\System directory (not advised), you should change paths so that the directory containing all dependent files is the current one before attempting self-registration.
In general, it is a good idea to copy all files before your setup program begins self-registration to make sure all dependent files have been copied. See your particular installation program generator's applicable documentation on how to self-register OLE servers and .OCX files.
Core Components
All MapObjects applications must be redistributed with at least the following core components:
- MO10.ocx*
- AF10.dll
- Shape.dll*
- MFC40.dll*
- MSVCRT40.dll
- OLEPRO32.dll*
Image Components
If your application utilizes image layers such as tiff or bmp, you must install the following image component:
- AIImage.dll*
Coverage Components
If your application utilizes ArcInfo or PC ARC/INFO Coverages, you must install the following component:
- Coverage.dll*
SDE Software Components
If your application utilizes SDE 2.1, you must install the following SDE components:
- SDE.dll*
- SDE21.dll
If your application utilizes SDE 3.0, you must install the following SDE components:
- MoSDE30.dll*
- MoSde30Table.dll*
- SDE30.dll
- Pe.dll
- Sg.dll
MapObjects ships with several optional plugin components that allow you to access and utilize external databases with your MapObjects programs. These table objects are commonly used in AddRelate operations and Geocoding. The requirements for these objects are detailed below.
Microsoft ODBC Tables
You can use the ODBC Shape File driver to connect to any ODBC-compliant database. If you use
this functionality in your MapObjects program, you will need to install the following components
using the procedure outlined below.
Alternatively, you may install ODBC yourself, using the ODBC SDK in your installation program code. Ensure that all of the standard ODBC redistributeable files along with ShpDrivr.dll* (located in the ODBCShp folder on your MapObjects installation CD) are properly installed to the target computer's System directory. All of the necessary files in uncompressed form may be found on the MapObjects Installation CD in the Microsoft\ODBC directory. These core ODBC files are freely distributeable.
Microsoft DAO Tables
Microsoft's Data Access Objects can be used to connect to Microsoft Access databases and to many other standard databases through
JET ISAM extensions. If you use this functionality in your MapObjects program, you will need to install the following components:
Note: Consult Microsoft for details on the redistribution and licensing of DAO. Visual Basic Application Setup Wizard automatically adds DAO to your installation if you use Visual Basic.
INFO Tables
If you use INFO tables in your MapObjects program, you will need to install the following component:
If your application makes use of the TrueType fonts provided with MapObjects such as ESRI_Environment.ttf, these fonts must be properly installed on the target machine. In addition, fonts must be registered with the target system. See your particular setup program maker's documentation for details on how to register fonts or alternatively, see the Win32 SDK documentation on how to perform this operation using OS functions. You can also download a sample VB program that shows how to install and register TrueType fonts.
If you use Microsoft Visual Basic as your development environment, you can use Visual Basic SetupWizard to generate a setup program for your application. See the chapter about "Distributing Your Applications" in the Visual Basic Programmer's Guide for details on how to properly use Visual Basic SetupWizard. For each of the following SetupWizard Steps, take the following actions that are specific to creating a Setup program for an application that uses MapObjects.
Step 1
Select your Visual Basic Project.
Step 2
If you use the MapObjects DAO Attribute Table plugin and you need to connect to databases other than Microsoft Access, check the appropriate Data Access Engine.
Steps 3-5
Follow the Setup Wizard instructions.
Step 6
Select "Install in application directory" as your Deployment Model.
Step 7 (if your application uses optional components or is distributed with data)
| If you use | Component |
|---|---|
| Image Support: | Aiimage.dll |
| ArcInfo or PC ARC/INFO Coverages: | Coverage.dll |
| Microsoft ODBC tables: | OdbcTbl.dll |
| Microsoft DAO tables: | JetTable.dll |
| INFO tables: | InfoTable.dll |
| MoPlus or any separately purchased ESRI Plugins and/or OLE Objects: | MoPlus.dll (or as specified in your extension product documentation) |
| SDE 2.1: | Sde.dll & Sde21.dll |
Sharing
After adding optional components, ensure that each of the files you have added, including auto-dependencies which may appear, are indicated as Shared Files by selecting each item, clicking "File Details" and setting the "Install as shared file" check box. This will invoke usage counts on these files and ensure that multiple programs that use MapObjects on the target machine will install and uninstall properly.
Click Finish
Visual Basic Application Setup Wizard will generate a setup program on floppies or in the specified directory. A special list file will be generated on floppy disk one or in the setup directory. This list file contains all the files and associated instructions that your setup program uses during installation to the target machine.
SETUP.LST File
Here is an excerpt from the [Files] portion of SETUP.LST for a fictitious application named SuperMap.exe which uses a large number of optional components. Note that your application may use different files and the version numbers of the .DLL files and .OCX may be different than those that appear here.
Example SETUP.LST
[Files]
File23=1,,SHAPE.DL_,SHAPE.DLL,$(WinSysPath),$(DLLSelfRegister),
$(Shared),8/27/1996,64512,1.0.1.190
File21=1,,MO10.OC_,MO10.OCX,$(WinSysPath),$(DLLSelfRegister),
$(Shared),8/27/1996,382976,1.0.1.190 File22=1,,AF10.DL_,AF10.DLL,$(WinSysPath),,$(Shared),8/27/1996,510976,1.0.1.190
File24=1,,MSXB3032.DL_,MSXB3032.DLL,$(WinSysPathSysFile),
$(DLLSelfRegister),,9/27/1995,260368,3.0.0.2120
File25=1,,Coverage.dl_,Coverage.dll,$(WinSysPath),$(DLLSelfRegister), $(Shared),8/27/1996,136704,1.0.1.190
File26=1,,JetTable.dl_,JetTable.dll,$(WinSysPath), $(DLLSelfRegister), $(Shared),8/27/1996,36864,1.0.1.190
File27=1,,InfoTable.dl_,InfoTable.dll,$(WinSysPath), $(DLLSelfRegister), $(Shared),8/27/1996,43008,1.0.1.190
File28=1,,OdbcTbl.dl_,OdbcTbl.dll,$(WinSysPath),$(DLLSelfRegister), $(Shared),8/27/1996,36864,1.0.1.190
File29=1,,ODBC32.DL_,ODBC32.DLL,$(WinSysPath),, $(Shared),6/6/1995,64512,2.50.30.6
File30=1,,ds16gt.dl_,ds16gt.dll,$(WinSysPath),, $(Shared),6/6/1995,5024,2.10.23.23
File31=1,,ds32gt.dl_,ds32gt.dll,$(WinSysPath),, $(Shared),6/6/1995,6144,2.50.30.6
File32=1,,odbc.in_,odbc.inf,$(WinSysPath),, $(Shared),1/12/1996,1549
File33=1,,odbc16gt.dl_,odbc16gt.dll,$(WinSysPath),, $(Shared),6/6/1995,24272,2.50.30.6
File34=1,,odbc32gt.dl_,odbc32gt.dll,$(WinSysPath),, $(Shared),6/6/1995,8704,2.50.30.6
File35=1,,odbcad32.ex_,odbcad32.exe,$(WinSysPath),, $(Shared),8/15/1995,7168,2.50.30.6
File36=1,,odbccp32.dl_,odbccp32.dll,$(WinSysPath),, $(Shared),8/2/1996,91136,2.50.30.6
File37=1,,odbccr32.dl_,odbccr32.dll,$(WinSysPath),, $(Shared),6/6/1995,167936,2.50.30.6
File38=1,,odbcinst.hl_,odbcinst.hlp,$(WinSysPath),,
$(Shared),6/6/1995,18321
File39=1,,odbcint.dl_,odbcint.dll,$(WinSysPath),, $(Shared),8/2/1996,32768,2.50.30.6
File40=1,,ShpDrivr.dl_,ShpDrivr.dll,$(WinSysPath),, $(Shared),4/23/1996,290816,1.0.0.0
File41=1,,Sde.dl_,Sde.dll,$(WinSysPath),$(DLLSelfRegister), $(Shared),8/27/1996,46592,1.0.1.190
File42=1,,SDE21.DL_,SDE21.DLL,$(WinSysPath),,
$(Shared),4/24/1996,170496
File43=1,,AIImage.dl_,AIImage.dll,$(WinSysPath),
$(DLLSelfRegister),$(Shared),8/27/1996,145920,1.0.1.190
File44=1,,supermap.EX_,supermap.EXE,$(AppPath),
$(EXESelfRegister),,4/18/1996,10240,1.0.0.0
SETUP.LST Notes:
$(DLLSelfRegister) and $(EXESelfRegister) tell the setup program to register these components in the target system's registry.
$(Shared) indicates that this component can be shared between multiple programs and that DLL counting should be used when installing/uninstalling.
$(WinSysPath) specifies that this component will be installed in the target system's windows system directory. The last three items are file date,
size and version.
In many cases you'll be supplying data with your application. The most significant issue regarding this aspect of deploying your application involves how to accommodate where users install the geographic data. Users may choose to install the application in a location other than the default, so you may want to provide a way for your installation to locate the data you ship in a way that makes it easy for the application code to use it in a seamless manner. Most of the sample applications that come with MapObjects make use of a scheme like this. Each application includes a module that has a function that returns the data path of a folder containing the data required. You may want to pursue a similar scheme for your application.
Here's an example:
' Function name: ReturnDataPath
' Return type: String
' Dependencies: Uses InStrL function
'
' Description: Returns the full path to the specified data directory.
'
' Args: dataDir - Directory to search for
'
Public Function ReturnDataPath(dataDir As String) As String
Dim sPath As String
Dim iLastPos As Integer
sPath = App.Path
iLastPos = InStrL(sPath, "\")
ReturnDataPath = Left(sPath, iLastPos - 1) + "\..\Data\" + dataDir
End Function
' Function name: InStrL
' Return type: Integer
' Dependencies: None
'
' Description: Returns the character position of the last occurrence
' of srchString in inString. If there is no match, 0 is
' returned. This provides the same functionality that VB's
' InStr function provides, except that it searches backwards.
'
' Args: inString - String to examine
' srchString - String to search for
'
Public Function InStrL(inString As String, srchString As String) As Integer
Dim iLastPos As Integer 'Set to 0 on initialization
' Check srchString -- a 0-length string will match every time
If Len(srchString) Then
' Set iLastPos to the last matching position
Dim iCurPos As Integer
Do
iLastPos = iCurPos
iCurPos = InStr(iCurPos + 1, inString, srchString, vbTextCompare)
Loop Until iCurPos = 0
End If
InStrL = iLastPos
End Function
The code above assumes the geographic data resides in a folder named Data that's at
the same level as the folder that contains the application.
If you plan to distribute MapObjects applications you've developed, it is important to understand that many applications, perhaps yours and another company's, may be utilizing the same MapObjects components. If your uninstallation program removes a shared component when its DLL-count is not zero and there are other applications that require MapObjects to function, your uninstallation will cause the other MapObjects applications to cease to function. For this reason, your application's setup and uninstallation programs should install and uninstall MapObjects components as shared components.
Per usual DLL standards, MapObjects components should be copied with version checking to make sure a newer version of the file is not overwritten by your installation.
Consult your particular installation generator's applicable documentation about how to properly copy and uninstall files as shared components with version checking.
A shared file is copied just as any normal file would be. The difference is what is done after the file is copied, and how uninstallation of the file is handled. Shared files are often termed "component" files.
Shared Component Installation
This is the normal progression that is performed during the installation of a shared component file. Most
setup program generators automatically perform this when a shared file is installed, and perform the reverse
operation when the file is uninstalled. You must, however, tell the program generator that the file is to be
installed as a shared file, and whether or not the file is a self-registering file (see more about this under
How to tell if a file is self-registering).
Each time a shared component file is installed, the file is first copied, then a registry key value under HKEY_LOCAL_MACHINE:\Software\Microsoft\Windows\CurrentVersion\SharedDLLs is created or incremented. The name of the key is the fully-qualified installed location of the file and the value is set to the number of times the component is installed, e.g., if it is the second time the component is installed, the value is 2.
After the file has been copied, if the file has been marked as self-registering by the setup program, the component is registered by calling the file's DllRegisterServer method. The componenent is registered each time it is is installed because a user may choose a different install location than it was previoulsly installed.
It should be noted that self-registering files are not necessarily registered as soon as they are copied. Often, a component file will require one or more other files, known as dependencies, before it can be self-registered. Each dependent file may have its own dependencies. For this reason, setup programs often install all their files before any registration takes place. See more about this under How to obtain a file's dependencies.
Shared Component UnInstallationEach time a shared component file is uninstalled, the same value that was created or incremented when it was installed is decremented. When a DLL-counted file is uninstalled and the decremented value reaches zero, the uninstallation program prompts the user to remove the component file. If the user indicates s/he wants to remove the component, it is removed. Some programs may ask if you want to do the same for all shared component files that have reached a DLL-count of zero.
If the file was registered when it was installed, the component is unregistered by calling the file's DllUnregisterServer method before it is removed. If the file is uninstalled and the value is decremented but the DLL-count is not zero, the uninstall program does not prompt for anything and the component is left there. This explains why some uninstallation programs leave files after the software has been uninstalled. Shared files that have not reached a zero count on uninstallation are not unregistered either; doing so may cause a shared application based on the component to fail.
You can tell whether a file is self-registering by browsing the file to see if it contains the two procedures DllRegisterServer and DllUnregisterServer. If the file does not contain these two methods, it is not a self-registering file. You can browse the file with Microsoft's QuickView utility, installed during a custom installation of your Operating System.
Using QuickView, look for the DllRegisterServer and DllUnregisterServer functions under the Name column of Export Table:
Another way to determine which files in a directory are self-registering is to use Find from the command line to locate which files contain the text "DllRegisterServer," e.g.,
find "DllRegisterServer" *.*
Before a self-registering file can be self-registered, you must make sure that all its dependencies are installed. Using QuickView to view the file you are insterested in, look under Import Table. Any file listed under this section is a dependency of the file being browsed.
In the illustration above, which depicts the MapObjects component Coverage.dll, you can see the file AF10.DLL under Import Table, so you know that file must be installed before attempting to register Coverage.dll. If it is attempted to be self-registered without AF10.dll first being copied to the same folder that Coverage.dll is in or a directory in the path, an error will result.
The function names listed under Ordinal Function Name are the imported functions used when the file being browsed is loaded into memory and run. For purposes of determining dependent files, you can ignore these.
Sometimes some of the dependencies are Operating System components that are always installed, such as KERNEL32.dll, GDI32.dll, and USER32.dll. You don't need to worry about installing these components because they were installed with the OS. Scroll down to view all the dependencies. All the files listed until you get to the Section Table are dependent files, and must exist before registration is attempted.
MapObjects is a developer product and its components are installed in a separate folder so you can easily find and repackage distributable components. Even though component files can be installed and registered in any folder, the usual convention is to install and register application components in the Windows\System(32) folder. This general rule applies not only to MapObjects-based applications, but any common component files installed with any application.
There are exceptions to this rule, however. If your application requires DAO or OLE DB, for example, Microsoft has specific rules as to where and how these components are to be installed and uninstalled. If your application requires specialized components such as these, consult the specialized product's SDK documentation for information on how to redistribute the components. If your application requires DAO 3.0, you can download a DAO 3.0 installation program from this Web site, which your setup program can use to install DAO 3.0.
The location MapObjects components are installed in is important because there are a lot of MapObjects applications being distributed by different software developers.
Suppose for example, your MapObjects 1.2-based application's setup program installs your product and MapObjects components in its own folder. Your application will work this way because components can be installed and registered anywhere. Now another company, XYZ, hasn't upgraded to MapObjects 1.2 yet and they have a product based on MapObjects 1.1a. Company XYZ's setup program correctly installs MapObjects components to the Windows\System(32) folder with version checking to make sure newer components are not overwritten with older ones.
When someone who already has your product installs company XYZ's product, because their installation doesn't find any MapObjects components in the Windows\System(32) folder, it copies the 1.1a components and registers them there. All MapObjects applications use the most recently registered components, so now both your product and company XYZ's are using the MapObjects 1.1a components. XYZ's application works fine but yours won't work correctly if it uses any of the enhanced MapObjects 1.2 functionality.
If, on the other hand, your setup program had installed components to the Windows\System(32) folder in the first place, both applications would function correctly. The MapObjects 1.2 components would not have been overwritten because of version checking, and MapObjects 1.2 is backward-compatible with older applications.
If you test your application's setup program on the same computer you use to develop your application and you followed the recommendation above about installing MapObjects components to the Windows\System(32) folder, you will need to reregister MapObjects components in your development folder in order to use the MapObjects design-time license in your development environment.
You can use RegSvr32.exe, installed in your MapObjects folder during installation to do this. In Windows Explorer, go to your MapObjects installation folder and drag MO10.OCX, SHAPE.DLL and any other MapObjects components your setup program reregistered and drop each one on RegSvr32.exe. Or from the command line, use the syntax:
regsvr32 mo10.ocx
See the Registration Utility below to make this task easier.
There is a handy utility the MapObjects Team uses to quickly register files in different locations. This utility is included on the MapObjects 1.2 product media. You can also download the registration utility from this Web site. Sorry, this won't work on Windows NT 3.51.
There is a DAO 3.0 installation program included on the MapObjects 1.2 product media. You can also download the DAO 3.0 installation program from this Web site. This is the same program that the MapObjects 1.2 setup program uses to install DAO on your computer. If you want to insure that DAO 3.0 is distributed with your MapObjects applications, you can call this program from your application's setup program to install DAO.
If you prefer to install DAO 3.0 yourself, the redistributable DAO components are on the MapObjects 1.2 product media. If you decide to do this, it is advised that you consult the Microsoft DAO 3.0 SDK documentation to correctly install and register DAO components in the proper locations with version checking to make sure newer versions of the files are not overwritten by your installation.
Click the link above for more information.
Note: If you use the DAO30.EXE program from this Web site or on the MapObjects 1.2 product media, you don't need to repackage the DAO component files with your installation - they are compressed into the executable.
According to Microsoft, when running a setup that was created by the Visual Basic Setup Wizard or Package and Deployment Wizard (PDW), the following error message may be generated:
[file path and name]
"An access violation occurred while copying the file."
where "[file path and name]" is the name of the file, including the complete
path, that Setup is attempting to copy. See Article ID #Q216368 in Microsoft's
Knowledge Base for further details, or contact
Microsoft Developer Support.
Suggestion: Install Visual Studio 6.x Service Pack 3 since many PDW
issues were remedied in the patch, including this one.