See the Map Server Overview for general information on Manifold IMS (Internet Map Server). This topic covers some of the same points in slightly different ways since often one of these points has been overlooked.
Read through this entire topic at least once, then print it out in hard copy and go through it line by line, checking each line off with a pen or pencil as you investigate. Take nothing for granted and assume nothing. For example, don't assume permissions are correctly set. Actually check each and every file and folder involved for the right permissions on the IUSR_ or NETWORK SERVICE or ASPNET account, as the case may be.
Running Manifold IMS has to do mostly with elementary operation of Windows as well as Microsoft's Internet Information Server (IIS) or whatever HTTP server is being used. Running Manifold IMS itself is very simple.
Of course, IMS can't run on a web server machine if Manifold has not been installed and activated on that machine.
In all cases of debugging, login using the Administrator account on the machine being used as a web server. Use the actual, local Administrator account (which may need to be enabled for usage in Vista) and not just some account that you are sure has Administrator privileges, whether it be a local account or a domain account. Use the actual, local Administrator account.
Tech tip: Users (especially in Vista) who are convinced the account they are using has "adequate administrative privileges" should be the first to login using the actual, local Administrator account.
To run a web site you need basic Windows administration skills. You must understand what is mean by a login and what is meant by permissions and how to check and set permissions. Any good book on Windows administration will explain this. If you do not know what permissions are and how to check and set them, you will not be able to identify and eliminate the most common user errors that prevent IMS web sites from running.
Verify Manifold installation
The first step in case of trouble is to verify that Manifold has been installed and activated on the web server machine. This is easy to do: Gain physical access to the web server machine and login using the Administrator account. Stop IIS. Reboot the machine. Verify IIS is still stopped. Now, launch Manifold interactively. Does Manifold come up without any activation dialog? If yes, you have Manifold installed and activated on the web server machine. Check the Help - About dialog and verify that you are not running Personal Edition (Personal Edition does not have IMS). While you have the Help - About dialog open, write down the exact build number in use, the Manifold edition in use and any extensions that are installed. Exit Manifold. Restart IIS.
If you have installed a Manifold edition other than a Runtime license and you cannot launch Manifold interactively, then you have not correctly installed Manifold and Manifold IMS will not work.
Note that the above verification is not possible if you have installed Manifold using a Manifold Runtime license. Runtime licenses cannot be launched interactively. The lack of an ability to launch Manifold interactively for debugging purposes is one reason that runtime licenses are not recommended for IMS beginners.
Verify installation of accessories
Some web sites may involve accessory software, either Manifold extensions or software provided by third parties. Check to make sure any such software has been installed. The most common errors:
· Verify presence of required Manifold extensions. If your web site utilizes features from Business Tools, Geocoding Tools or Surface Tools make sure these have been installed and activated. You can verify this in the Help - About dialog that was opened in the above paragraphs.
· Verify presence of image server modules, if used. Many web sites use Image Servers to fetch background images. Make sure that the web server machine has the required modules installed (usually placed in the Manifold installation folder). It is a very common error to create a project on some development machine using image server modules and then to forget to install the required image server .dll files on the web server machine as well.
· Verify presence of other required software. If your web application uses other software, such as DBMS packages or other software, make sure the required applications have been installed. For example, if you have created a web page using Excel web queries as shown in the A Flashy Demo - Web Queries and KML example topic, you will need to have Microsoft Excel installed on the web server.
Verify web server operation
The next step in case of trouble is to verify that your machine is capable of operating as a web server and that you know how to create and operate simple web pages on that machine. This is not something to be taken for granted, especially if other people have had access to your web server machine, as it is possible that some person or security update has altered IIS or other Windows settings in a way that prevents basic web server functions from operating as you expect.
Before debugging any problems with Manifold IMS, please create a simple web site not using Manifold IMS on your web server and browse it from a different machine. If you cannot create a web site on your web server that does not use Manifold IMS, then most likely the problem (or, at least one of the problems) has nothing to do with Manifold IMS. Get your web server running first with a simple web site.
For example, if you are running Windows Server 2003 you might discover that no web site using .asp pages can run.
Important: For enhanced security, Microsoft's Windows Server 2003 product comes with Internet Information Server configured so that .asp pages are not enabled. .asp pages must be turned on within IIS for Manifold IMS to function correctly.
When running Manifold IMS in 64-bit Windows editions, use of 32-bit ASP / ASP .NET must be enabled. See the discussion in the Creating a Web Site topic.
Create a Simple HTML Page
In your web page publication folder, create a file called hello.html that contains the following text:
Can you view this file as a web page from your local machine? Can you view this web page from your intranet or Internet as you would like to see your IMS site? If you cannot view this file, do not proceed any further with IMS until you can figure out how to create, publish and view this simple web page.
Create a Simple ASP Page
Once you know you can create and view a simple HTML file you know that your web server is operational. The next step is to verify that it can handle ASP by creating and viewing a simple .asp file.
If you are creating IMS pages using VBScript, create a file called hellovb.asp that contains the following text:
Can you view the .asp file as a web page from your local machine? Can you view this web page from your intranet or Internet as you would like to see your IMS site? If you cannot view this file, do not proceed any further with IMS until you can figure out how to create, publish and view this simple .asp web page.
Create a Simple ASP .NET Page
ASP .NET is not enabled by default in recent versions of IIS. To verify ASP .NET is up and running create a file called test.aspx in your root web server directory and paste the following into it:
<h1> The date is <%
Visit test.aspx with a browser and if you see a sentence giving the current system date ASP .NET is working. [This example was contributed by user mlinth on the Georeference forum, and comes from the book Beginning ASP.NET 3.5 in VB 2008: From Novice to Professional, Second Edition by Matthew MacDonald.]
The Manifold side of troubleshooting consists mainly of checking that Manifold is correctly installed, is available to all users, and that the files needed to be used are where the config.txt file says they are. Check the following:
· Has Manifold Professional Edition or higher been installed on the web server machine? Note that Manifold Personal Edition does not include IMS.
· When Manifold was installed on the web server machine, did you login as Administrator to do the installation? Note that Vista may require the Administrator account to be enabled before you can use it.
· When Manifold was installed, was it installed for use by all users?
· If it is more than 30 days since the serial number was issued, has Manifold been permanently installed using an Activation key on the web server machine?
· When Manifold was activated, did you login as Administrator when entering the Activation key?
· Are you attempting to run Manifold simultaneously in interactive mode and as the IMS map server at the same time? Execute an IISRESET when changing from interactive use of Manifold to IMS use or vice versa.
· Have you copied all the files created by the Export Web Page dialog to the correct folder within the Inetpub/wwwroot folder hierarchy on the web server machine?
· Has the .map file being used been placed at the location specified for it in the config.txt file?
· If you are using ASP, does the system's IUSR_ user login have permission to execute Manifold.exe in the Manifold System installation folder? Check this using Windows Explorer to view the security settings on the file.
· If you are using ASP, does the system's IUSR_ user login have permission to read the .map file in use? Check this using Windows Explorer to view the security settings on the file.
· If you are using ASP, does the system's IUSR_ user login have permission to read and write the system's TEMP folder? Check this using Windows Explorer to view the security settings on the file.
· If you are using ASP, does the system's IUSR_ user login have permission to read and write all folders and files used in the application, such as temp folders for linked images, .mdb or other files used in linked tables, or database access for components linked from databases?
· When working with Windows Server 2003, have .asp files been enabled in IIS?
· When working with Windows Server 2003, does the NETWORK SERVICE account have all the permissions enumerated for the IUSR_ account above?
· When working with Windows XP x64, does the NETWORK SERVICE account have all the permissions enumerated for the IUSR_ account above?
· If you are using ASP .NET, does the ASPNET account have all the permissions enumerated for the IUSR_ account above?
· If you are working in a 64-bit Windows edition, have you installed a 32-bit version of the .NET framework as well as the 64-bit .NET framework?
The number one problem with IMS reported to tech support is that users neglect to add the IUSR_ account with access permissions to security settings for the .map file in use. A related error is that after checking permissions are correct users edit the .map file with Manifold and, without realizing it, change permissions so that the IUSR_ account no longer has access permissions to the .map file. Saving a .map file with Manifold will preserve file permissions on Windows 2000 and later systems, but this is always something worth checking.
To check permissions, using Windows Explorer (do not just depend on the IIS management console or other server management console), right click on the .map file, choose Properties and verify in the Security tab that the IUSR_ account for the system has necessary read and execute permissions.
Very important: In 32-bit and 64-bit versions Windows Server 2003 and in 64-bit Windows XP the account used for Internet visitors is not the IUSR_ account as with earlier Windows versions. Instead, the NETWORK SERVICE account is used. When ASP .NET is employed the ASPNET account is used.
Windows Server 2003 and 64-bit Windows XP operators should understand the NETWORK SERVICE account is meant in all cases where this documentation discusses the IUSR_ account.
Web pages operating in an ASP.NET environment may require different permission settings than those operating in an ASP environment. For example, the default login used by ASP.NET is ASPNET, while the default login used by ASP is either the IUSR_ account or the NETWORK SERVICE account. When running in ASP .NET, the .map file and all other data being accessed from the ASP.NET environment must be readable by the ASPNET user account.
ASP .NET operators should understand the ASPNET account is meant in all cases where this documentation discusses the IUSR_ account.
While there is no end of trouble that can arise from willful misconfiguration of Microsoft Internet Information Server when attempting clever tricks, in the case of simple web sites problems arise most frequently from a handful of common errors:
§ Can you create and browse a simple web page not involving Manifold IMS on the web server machine? If you have not correctly configured or installed Microsoft IIS on the web server machine so that you can create simple web pages without using IMS, then you will not be able to serve web pages involving Manifold IMS either.
§ Attempting to run a web site with Manifold IMS at the same time Manifold is running interactively on the same system. Do not run Manifold interactively at the same time you are trying to run IMS. To make sure Manifold is not being run interactively, reboot the web server machine after running Manifold interactively.
§ Failure to arrange required read and execute privileges for the IUSR_ account (or, the NETWORK SERVICE account or ASPNET account if applicable). The IUSR_ account must be able to access the .map project as well as any tables required for linked tables or linked drawings and it must be able to execute Manifold System. The IUSR_ account must also have read and write privileges in the system TEMP folder as well as execute privileges for the Manifold.exe executable. In case of trouble, always check the permissions on the .map file. Use Windows Explorer to check all permissions: don't rely on the IIS management console to check permissions. If any linked components appear in the project, the IUSR_ account must have required privileges to work with those files as well. For example, if an .mdb file is used to generate a linked drawing the IUSR_ account must have read and write permissions for that folder so that the lock file for the .mdb file can be created. When checking permissions, open Internet Explorer, right click on the file or folder, choose Properties and then check the settings in the Security tab. Don't assume that the web administration dialogs used by IIS will set these permissions for you. If using image servers, the IUSR_ account must have read and write privileges in the folder used to cache the image server tiles.
§ If you have opened the .map file in Manifold System, check the permissions again. They might have been resent to not include the IUSR_ account. Saving a .map file with Manifold will preserve file permissions on Windows 2000 and later systems, but this is always something worth checking.
§ Failing to install Manifold System on the web server machine for use by all users (a checkbox in one of the Manifold System installation dialogs).
§ Neglecting to maintain links correctly when working with a project that uses linked tables, linked drawings or Enterprise Edition components.
§ Attempting to use Enterprise Edition features, such as shared components, on a web server machine that is not licensed for Enterprise Edition.
§ Failure to install the Geocoding Tools extension as well as the geocoding database within the Manifold System installation folder when using queries that include geocoding functions (or failure to have MapPoint installed if it is being used as an alternative geocoder).
§ Failure to install or activate (using an Activation key) features contained in the Business Tools, Geocoding Tools or Surface Tools extensions if these features are used by the IMS application.
§ Neglecting to place the .map file where the config.txt file says it is supposed to be.
Manifold or the map server won't launch
· To run the map server and serve web pages, no interactive session with Manifold can be running on the same machine.
· To work with Manifold interactively, no map server session can be running on the same machine.
· Do an iisreset command in the Windows Command Prompt window before attempting to work with Manifold interactively after the map server has been active.
· Make sure to save the .map file after creating it or making any alterations interactively in Manifold. The .map file must be saved before the map server can use it. After editing a .map file, make sure by using Windows Explorer to view Security settings that the IUSR_ account (or, the NETWORK SERVICE account or ASPNET account if applicable) still has read permissions on the .map file.
· Have you provided a serial number and Activation key? When Manifold is running as a map server it will not raise the Activation dialog. Before attempting to use the map server within Manifold you must launch Manifold interactively at least once to provide a serial number for preliminary installation, or a serial number and Activation key for permanent installation. See the Activation Keys and Serial Numbers topic. If you provided just a serial number without an activation key and it has been more than 30 days since the serial number was issued, you will have to launch Manifold System interactively so you can provide a serial number and an Activation key for permanent installation.
· When installing Manifold, did you install Manifold System for everyone to use on the computer? This is the default choice in the installation dialogs.
· When you installed Manifold System, did you login as Administrator to perform the install? If you activated Manifold System using a serial number and Activation key, did you login as Administrator to do so? It is a common error to think that using an account which supposedly has "Administrator" rights is an OK substitute for using the actual Administrator account. Avoid unpleasant surprises by using the actual, local Administrator account.
· Check access permissions on the .map file as noted below.
· When using a .map project using Enterprise Edition features, the web server must have Manifold System Enterprise Edition installed.
· Note that in Windows Server 2003 or 64-bit XP the account used for Internet visitors is not the IUSR_ account as with earlier Windows versions. Instead, the NETWORK SERVICE account is used. Likewise, when running ASP .NET the account used is ASPNET.
· The .map file used with the web site must have security permissions such that the IUSR_ account (or, the NETWORK SERVICE account or ASPNET account if applicable) used for Internet browsers has read access. Manifold must be installed for everyone to use on the machine. If any linked drawings or linked tables are used in the project that is published, the IUSR_ account must have all necessary privileges required to work with the tables that control those linked drawings or linked tables. Note: the "IUSR_" account is named using the computer name of the web server machine. If the web server machine is named "GODZILLA" this account will be called "IUSR_GODZILLA".
· When using linked images in an IMS web application it is important that the web application has read and write permissions in the cache folder, or otherwise it will not be able to use the tiles cached for the linked image.
General problems browsing the web site
· Confirm IIS is operational by launching Internet Explorer and browsing http://localhost …If this does not work, IIS is not functioning. You must have IIS functioning correctly before attempting to work with Manifold IMS within IIS.
· Verify the directory to which the Manifold IMS project is published is within the publication directory structure of IIS. Create a small test.html file and then browse to it using http://localhost/pathname/test.html where "pathname" is the directory path to the directory in which you are placing your Manifold IMS files.
· Check to make sure Manifold is not running on the system interactively. Manifold IMS cannot function on a machine where an interactive Manifold session is running. Close all Manifold sessions, reboot and try the browser again.
· Make sure no interactive Manifold sessions running on different machines are trying to use, across a local network, the .map file from which the Manifold IMS site was published. Manifold IMS needs to use that .map file during operation and no other process should use that .map file.
· If a newer version or service pack of Manifold has been installed, or if you have worked with Manifold interactively on the web server machine, reboot the system to make sure there are no older processes lingering.
· After changing either the .map file in use or any of the .asp files or accessory files in the Manifold IMS site, do an iisreset in the Windows Command Prompt window to unload all objects involved so that the new versions are guaranteed to be in use.
· Client browsers must be at least "4.x" vintage IE, Netscape, Mozilla or Opera browsers when the "Compatible" template is used to generate a site.
· The Info button is not available in sites generated using the "Compatible" template.
· Client browsers must be at least "5.x" vintage IE, Netscape, Mozilla or Opera browsers when the "Standard" templates are used to generate a site.
· When developing a Manifold web site on one machine and then installing the site and .map file on a different machine that is used as a server, make sure that the server machine is correctly updated with the correct .map file.
· Make sure the server machine has the latest version of Microsoft Internet Explorer installed (at least IE 6 is required).
· Make sure the server machine is running Windows Internet Information Server 5.0 or more recent.
· Check that the server machine has the same version of Manifold installed together with the most recent service pack (if any have been issued) as the development machine. For example, if your development machine uses Manifold 8 and the web server is still running Manifold 7x, the web server machine won't be able to open the Release 8 version .map file.
Queries don't work as expected
· Stop IIS in Internet Services Manager. Execute an iisreset in a Windows command prompt window. Launch Manifold interactively on the server machine and see if the query works correctly.
· Check the component that is published (it will be listed in the config.txt file in the IMS web site files). Does the query in any way refer to a component outside that which is published?
· Is the query a SELECT query? Only SELECT queries are allowed.
· Does the query generate more than 200 records for the table? Only the first 200 records will be published to the web page.
· Does the query use features available only through extensions? If so, has the requisite extension been installed?
A site that worked before no longer works
· Check to make sure that IIS is running.
· If IIS is running and the browser shows an error message citing a particular .asp file and a line number, check to make sure there is not an interactive session of Manifold running on the server.
· Make sure Manifold has not been removed (de-installed) from the web server.
· Using Windows Explorer check permissions for IUSR_ on all files and folders involved. Note that re-editing a .map file can change permissions on that file.
· Check to make sure that the Manifold installation has not been damaged (e.g., the Manifold directory in the installation has accidentally had files deleted , etc.)
· Perform disk maintenance to make sure disk errors or other problems have not damaged the Manifold installation.
· Verify there is adequate disk space for all temporary files created by Manifold IMS.
· Reboot the system to fix any Windows instability.
· Did you activate your copy of Manifold? It could be more than 30 days since your serial number was issued and an Activation key is now required as well as a serial number.
· Make sure no interactive sessions of Manifold are running on the web server.
If geocoding functions do not work within IMS check the following:
§ Manifold Geocoding Tools extension has been installed.
§ The Geocoding Database has been installed into the GCDB folder within the main Manifold installation folder. By default, this location is C:\Program Files\Manifold System\GCDB.
§ All state files required for the geocoding database are present (that is, required files have not been removed after installation).
§ If MapPoint is to be used as an alternative geocoding data source, has MapPoint been correctly installed? Note from the main IMS topics that MapPoint requires special permissions settings.
More performance is needed
· Read and think carefully about every line of the Performance Tips topic.
· Read and think carefully about every line of the Optimizing Performance topic.
· Eliminate any unused fields in the components being published.
· Eliminate any unused components in the project being published.
· Make a backup copy first, and then simplify the drawings used by increasing the size of the View - Properties - Precision parameter and then running Normalize Topology. Most drawings used in web applications can be reduced in size/complexity by a factor of ten without any objectionable visual effects. This will dramatically speed up the site.
· Don't use images when drawings will do.
· If you must use images, use linked images that are compressed images or linked images served from an Oracle Spatial server or other DBMS server.
· Make sure that all components appearing in a map have the same native projection, which should be the same as the map's projection.
· Use a smaller size window in the IMS site. Users may be complaining because you are sending very large images to them that take time to download through a slow Internet link.
· Use x64 Windows and x64 Manifold.
· Add RAM memory to the system. RAM is cheap. Install gigabytes of it. Install enough so the entire .map file plus all of your Windows processes can be in RAM.
· Use large, fast hard disks spinning at 7200 RPM or faster.
· Use SATA interfaces on your disks and configure a striped RAID array.
· Specify a static (predefined size) Windows page file that is far larger than ever will be necessary. This is faster than a dynamically re-sized page file.
· Use multiple hard disks. If you have two disk drives keep the system TEMP directory on a different disk drive than the web site. Ideally, if you have four disk drives the system TEMP directory, the system page file, the .map file and IIS and the web site will all be on different disk drives. This allows the disk drive heads to seek independently from each other as each of these four different files is used. This is less of a factor if you have so much RAM that the page file or the .map files do not require any disk accesses.
· Use faster processors or use multiple, multicore processors.
Problems with ASP .NET
· Did you choose an ASP .NET version of the templates in the Export Web Page dialog?
· ASP .NET allows use of dependent DLLs, which if the system is misconfigured will lead to error messages such as "A dynamic link library(DLL) initialization routine failed." The most likely reason one or more DLLs are not getting initialized when loaded in an ASP.NET environment is that the system can not locate the dependent DLL modules to which it is linked. To work around this, include the path to the Manifold installation folder into the system PATH variable. That is, go to Control Panel - System - Advanced - Environment Variables and append the path for the Manifold installation folder (typically, C:\Program Files\Manifold System) to the system (not user!) PATH variable. Then restart IIS, or, better yet, reboot the machine. This should get rid of the problem.
· Web pages operating in an ASP.NET environment may require different permission settings than those operating in an ASP environment. For example, the default login used by ASP.NET is ASPNET, while the default login used by ASP is IUSR_xxx, where xxx is the machine name. The .map file and all other data being accessed from the ASP.NET environment must be readable by the ASPNET user account. Use Windows Explorer to check the security settings for all files involved in your web site to make sure that ASPNET can read them or execute them (in the case of executables such as manifold.exe). See the analogous discussion for the IUSR_ account.
Map Server Overview
Creating a Web Site
IMS Config.txt Options
Publishing Multiple Pages