Wednesday, 27 April 2011

The out-of-the-box MapGuide/FDO experience (or: Why the installer doesn't install all FDO providers by default)

When you install MapGuide Open Source, you have the choice of the following FDO providers to install:
  • ArcSDE
  • GDAL
  • Oracle (King.Oracle)
  • MySQL
  • ODBC
  • OGR
  • PostGIS (old one)
  • PostgreSQL (new one)
  • SDF
  • SHP
  • SQLite
  • MS SQL Server Spatial (>= 2008)
  • WFS
  • WMS
For those not astutely aware, the following provider options do not get installed by default:
  • ArcSDE
  • Oracle (King.Oracle)
  • MySQL
  • PostGIS (old one)
  • PostgreSQL (new one)
The reason for this is simple. These FDO providers require additional components that are not included with the MapGuide installer due to any of the following:
  • Licensing restrictions preventing component redistribution (ArcSDE)
  • Substantially increased installer footprint (Oracle)
  • The components that are bundled (if we did bundle them) may be older or newer than what is provided by your existing DBMS installation (MySQL, PostgreSQL)
  • Any combination of the above points.
So there is an implicit assumption that if you do enable any of the above FDO providers during installation, you will need to do some extra post-installation configuration to have a functioning FDO provider. This cannot be avoided.

So what exactly do you need to do for each provider?

For ArcSDE:
For Oracle:
For MySQL:
  • You need to ensure that libmysql.dll from your MySQL installation is either in the same directory as the FDO provider dll, or the path to libmysql.dll is in the PATH environment variable (which is what Windows will use to search for dlls that need to be loaded). If you are installing MapGuide on the same machine where MySQL is installed, you shouldn't need to do anything.
For PostgreSQL/PostGIS:
  • You need to ensure that libpq.dll (and its dependencies) from your PostgreSQL installation is either in the same directory as the FDO provider dll, or the path to libpq.dll is in the PATH environment variable (which is what Windows will use to search for dlls that need to be loaded). If you are installing MapGuide on the same machine where PostgreSQL is installed, you shouldn't need to do anything.
Still stuck? Well understand that the root problem for any of the above is that the FDO provider failed to find one or more dlls that it needs in order to properly function. You can use the Dependency Walker tool to determine if your FDO provider has all its dependencies satisfied and can be loaded without issues. Here's a screenshot of Dependency Walker on the King Oracle provider dll on a fresh MapGuide installation.


Notice the question mark on OCI.dll? OCI.dll is part of the Oracle Instant Client which the King.Oracle provider requires to properly function. A question mark indicates that this dll could not be found.

So the solution is to ensure that OCI.dll (and its dependencies) are located in a directory that Windows will search dlls for. Reloading the provider dll in Dependency Walker should no longer show a question mark beside OCI.dll meaning that the provider dll has all its dependencies satisfied, meaning this provider should now be fully functional.

One more thing about this: If you did have to carry out any of these extra configuration steps, remember to restart your MapGuide Server if it is already running.

So in summary:
  • Some FDO providers are not installed by default because they require additional components. These components are not bundled into the installer for reasons explained in this post.
  • This post should hopefully point you in the right direction to configure and troubleshoot these providers should you choose to install them.

2 comments:

Gregor Skrt said...

This solved all my FDO problems / questions :) Thank you !

kintela said...

Hi

I follow with the same error of "unable to load the FDO Provider library '.\PostgreSQLProvider.dll'

I have in the same machine PostgreSQL 9.3 y Mapguide 2.5. But in the ..\osgeo\mapguide\Server\FDO\ i had not the libpq.dll. I have put it in but is not necessary to register it with rgsvr32?

Anyway I have adde to Path variable the path: "c:\PostgreSQL\9.3\lib\"

But nothing works