DCMMS Administration Guide

Maher Abdel Karim

<Maher_Karim@dorsch.com.jo>

Steffen Macke

<Steffen_Macke@dorsch.com.jo>

Dennis Vilovic

<Dennis_Vilovic@dorsch.com.jo>

Sammer Srouji

<Samer_Srouji@dorsch.com.jo>

Copyright © 2006 - 2009 DORSCH Consult Water and Environment

Copyright © 2006 Dorsch Consult

Copyright © 2003 -2005 Dorsch Consult,NGWA

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available from the Free Software Foundation (http://www.gnu.org).

2009-02-28

Table of Contents

1. General
1.1. Introduction
1.1.1. Typographic Conventions
1.1.2. UML
1.1.3. Deployment
1.2. Overview
1.3. Requirements
1.3.1. Hardware
1.3.2. Software
1.3.2.1. Operating System
1.3.2.2. PostGIS
1.3.3. Folder Structure
1.3.4. Administrator
1.4. Concepts
1.4.1. Services
1.4.2. Windows Users
1.4.3. PostgreSQL users
1.4.4. Translation System
1.4.4.1. Gettext
1.4.4.2. The dcmmstranslation() Function
1.4.4.3. Map File Localization
1.4.5. Mailing Lists
2. Reference
2.1. Installation
2.1.1. DCMMS 2.0.0 and next versions Windows installation
2.1.1.1. MS4W base installation
2.1.1.2. PostgreSQL
2.1.1.3. PostGIS 1.3.5 Installation
2.1.1.4. DCMMS 2.0.4 MS4W base installation
2.1.1.5. Sample data
2.1.2. DCMMS 1.1.2 and previous versions Windows Installation
2.1.2.1. Apache
2.1.2.2. PHP
2.1.2.3. PostgreSQL
2.1.2.4. PostGIS
2.1.2.5. DCMMS
2.1.2.6. Sample data
2.1.3. Manual Installation
2.1.3.1. PostgreSQL
2.1.3.2. PostGIS
2.1.3.3. PostArabic
2.1.3.4. Fuzzystrmatch
2.1.3.5. Apache
2.1.3.6. PHP
2.1.3.7. Mapserver
2.1.3.8. DCMMS
2.1.3.9. Sample data
2.1.4. Default Accounts
2.1.5. Checklist
2.1.6. Optional Tools
2.1.6.1. Active Perl
2.1.6.2. GIX
2.1.6.3. poEdit
2.1.6.4. R
2.2. Configuration
2.2.1. Configuration Files
2.2.2. Custom Map
2.2.2.1. Tiled Shapefiles
2.2.2.2. PostGIS Layers
2.2.2.3. Tiled Images
2.2.2.4. Valve Symbols
2.2.3. Plug-Ins
2.2.3.1. Identify Plug-Ins
2.2.3.2. Search Plug-Ins
2.2.4. Database Side Customization
2.3. Administration
2.3.1. GIS Data Loading
2.3.1.1. Shapefile Loading
2.3.1.2. shp2pgsql
2.3.1.3. AdministrativeArea, Village and Landmark
2.3.2. Unit Cost Data Loading
2.3.3. Recurring Tasks
2.3.3.1. Backup
2.3.3.2. Restore
2.3.3.3. Merge DCMMS Databases
2.3.3.4. Removing Temporary Files
2.3.3.5. Quality Control
2.3.4. Security
2.3.5. Database
2.4. Analysis
2.4.1. Repairs per PressurizedMain
2.4.2. Pressure Dependency
2.5. Procedures
2.5.1. GIS Data Review
2.6. Updating
2.6.1. From 1.1.2 to 2.0.4
2.6.2. From 1.1.2 to 2.0.0
2.6.3. From 1.1.1 to 1.1.2
2.6.4. From 1.1.0 to 1.1.1
2.6.5. From 1.0.5 to 1.1.0
2.6.6. From 1.0.4 to 1.0.5
2.6.7. From 1.0.3 to 1.0.4
2.6.8. From 1.0.1 to 1.0.3
2.6.9. From 1.0.1 to 1.0.2
2.6.10. From 1.0.0 to 1.0.1
2.7. Frequently Asked Questions
2.7.1. There are too many coded values. How can I remove them?
2.7.2. How to add e.g. a new material?
2.7.3. How can I distinguish between Arabic and English texts in an SQL query?
2.8. Troubleshooting
2.8.1. DCMMS Info Mailing List
2.8.2. Support Tracker
2.8.3. Complete Uninstallation
2.8.4. Problems with Transparent Symbols
2.8.5. Shapefile Loading problems
2.8.6. Configuration error: PHP time != PostgreSQL time
2.8.7. Permission Denied for Relation CauseDomain
2.8.8. ERROR: column "oid" does not exist
2.8.9. New Landmarks Disappear
2.8.10. PostgreSQL Update
2.8.11. PostgreSQL Database Server Service
2.8.11.1. PostgreSQL Database Server Service Fails to Start
2.8.12. FATAL ERROR: PHP extension 'MapScript' is not loaded
2.8.13. Map Display
2.8.14. Restore
2.8.15. Unable to Load Dynamic Library
2.8.16. Header already sent error
2.8.17. Log Files
2.8.18. MapLab
2.8.19. Htdig
2.8.20. Cygwin PostgreSQL Upgrade
3. Administrator Certification
3.1. 2006 Certification Questions
3.1.1. Security
3.1.2. Engineering
3.1.3. Customization
3.1.4. Technology
3.1.5. Windows
3.1.6. PostgreSQL
3.1.7. Administration
3.1.8. Mapserver
3.1.9. PHP
3.1.10. GIS
3.1.11. Plug-Ins
3.1.12. Community
Index

List of Figures

1.1. UML Legend
1.2. Stand-Alone Deployment
1.3. Client-Server Deployment
1.4. Internet Deployment
1.5. Component Diagram
1.6. Control Panel
1.7. Services Panel
1.8. Windows Users
1.9. PostgreSQL Users
2.1. Unblock Apache service
2.2. PostgreSQL Installers
2.3. PostgreSQL Windows One click Installers
2.4. PostgreSQL Setup
2.5. Choose Installation Path
2.6. Choose Installation Path
2.7. Choose Data folder Installation Path
2.8. Enter the Password for the postgres super user
2.9. Choose Installation Path
2.10. Choose Database Port
2.11. Choose Database locale
2.12. Installation ready
2.13. Installation Completed
2.14. PostGIS License
2.15. PostGIS Components
2.16. PostGIS Location
2.17. PostGIS Database Connection
2.18. Installation Complete
2.19. Installer language
2.20. DCMMS License
2.21. DCMMS Components
2.22. DCMMS Location
2.23. DCMMS Database Connection
2.24. Apache Wizard
2.25. Apache License
2.26. Apache Readme
2.27. Apache Information
2.28. Apache Setup Type
2.29. Apache Location
2.30. Apache Install
2.31. PHP License
2.32. PHP Components
2.33. PHP Location
2.34. PostgreSQL Language Selection
2.35. PostgreSQL Setup
2.36. Installation Notes
2.37. Choose Installation Options
2.38. Service Configuration
2.39. Account Error
2.40. Password
2.41. Successfully granted the 'Logon as a service' right
2.42. Initialise Database Cluster
2.43. Enable Procedural Languages
2.44. Enable Contrib Modules
2.45. Enable PostGIS
2.46. Ready to Install
2.47. Installation complete
2.48. PostGIS License
2.49. PostGIS Components
2.50. PostGIS Location
2.51. PostGIS Database Connection
2.52. Installation Complete
2.53. DCMMS License
2.54. DCMMS Components
2.55. DCMMS Location
2.56. DCMMS Database Connection
2.57. poEdit PHP parser settings
2.58. Catalog Path
2.59. NGWA GIS Data Review

List of Examples

2.1. PostGIS Connection Example
2.2. Excerpt from identifyplugin.ini
2.3. Excerpt from searchplugin.ini
2.4. Customer Search Plug-In Configuration
2.5. First lines of sample customer.txt file
2.6. PostgreSQL 8.0 Backup
2.7. PostgreSQL 8.1 Restore
2.8. Old AreaOfInterest Class
2.9. New AreaOfInterest Class
2.10. PostGIS 1.0.3 Update
2.11. Run update_dcmms_ddl.sql


Chapter 1. General

Table of Contents

1.1. Introduction
1.1.1. Typographic Conventions
1.1.2. UML
1.1.3. Deployment
1.2. Overview
1.3. Requirements
1.3.1. Hardware
1.3.2. Software
1.3.2.1. Operating System
1.3.2.2. PostGIS
1.3.3. Folder Structure
1.3.4. Administrator
1.4. Concepts
1.4.1. Services
1.4.2. Windows Users
1.4.3. PostgreSQL users
1.4.4. Translation System
1.4.4.1. Gettext
1.4.4.2. The dcmmstranslation() Function
1.4.4.3. Map File Localization
1.4.5. Mailing Lists


1.1. Introduction

1.1.1. Typographic Conventions
1.1.2. UML
1.1.3. Deployment

This document describes how to setup and administer the DC Maintenance Management System (DCMMS) application version 1.1.2+svn .

In addition Section 2.4, “Analysis” covers some data analysis options.

DCMMS is available from http://dcmms.sourceforge.net.

While it is possible to run DCMMS on other operating systems, this document focuses on the DCMMS administration under Windows.

Feedback on DCMMS is welcome and can be addressed to <dcmms-info@lists.sourceforge.net>.

DCMMS Developer Guide and DCMMS User Guide provide additional information about the application.

Professional DCMMS administrators should go through the certification process (See Chapter 3, Administrator Certification).

This document is available in different formats (PDF, HTML, CHM and DocBook XML) and languages (English and French).


1.1.1. Typographic Conventions

A "\" at the end of the line in program listings means that the line continues in the next line.


1.1.2. UML

This document uses Unified Modeling Language (UML) diagrams to illustrate various aspects of the DCMMS application.

For those not familiar with the UML symbology, Figure 1.1, “UML Legend” provides a basic UML legend.

Figure 1.1. UML Legend


1.1.3. Deployment

The DCMMS application can be installed in a stand-alone setup or in a client-server environment.

Figure 1.2. Stand-Alone Deployment

Figure 1.3. Client-Server Deployment

[Caution] Caution

The DCMMS application is meant to run in an intranet environment. If you want to use the application over the internet you should protect it by a proper firewall and/or VPN setup. To run the application directly on an internet server would require a complete security audit of the application code.

Regardless of the type of installation, it is important that the administrator stays up-to-date with the latest Apache, PostgreSQL, Windows and PHP releases to avoid security leaks.

Figure 1.4. Internet Deployment

In addition to the outlined approach it might be possible to run a DCMMS on server on the internet if it is hardened with SSL and additional access control on the Apache side (E.g. client-side certificates).


1.2. Overview

Figure 1.5, “Component Diagram” gives overview of DCMMS and its components. Depending on the GIS data sources to be used, other components might be required or optional components could be removed.

The database components can run on other servers.

Figure 1.5. Component Diagram


1.3. Requirements

1.3.1. Hardware
1.3.2. Software
1.3.2.1. Operating System
1.3.2.2. PostGIS
1.3.3. Folder Structure
1.3.4. Administrator

This section describes the hard- and software requirements of the DCMMS application.


1.3.1. Hardware

A PC with at least 256 MB RAM and at least 1 GHz CPU speed.

The actual hardware requirements might be higher depending on the size and nature of the map data as well as the number of concurrent users.

To print the workorders, a printer with at least 300dpi resolution is required.

[Tip] Tip

Call-center grade headphones are strongly recommended in order to receive customer complaint calls.

[Tip] Tip

An optical mouse is recommended for all DCMMS clients.


1.3.2. Software

1.3.2.1. Operating System
1.3.2.2. PostGIS

The following software packages are required to run the DCMMS application:

  • PostgreSQL

  • PostGIS

  • Apache (Other web servers will also work)

  • PHP

  • The following PEAR modules:

    • DB

    • DB_DataObject

    • DB_DataObject_FormBuilder

    • Date

    • HML_Common

    • HTML_QuickForm

    • HTML_QuickForm_Controller

    • HTML_QuickForm_SelectFilter

    • HTML_Table

    • Image_Canvas

    • Image_Color

    • Image_Graph

    • Log

    • Pager

  • Mapserver (PHP Mapscript)

  • Web browser

Section 2.1, “Installation”covers the installation of all required software packages.

If it is intended to use the Arabic interface of the DCMMS application, the PostArabic software package is required in addition.


1.3.2.1. Operating System

[Caution] Caution

While it might be possible to install the DCMMS server on other Windows flavors, only Windows 2003 Server and Windows XP are recommended.

The filesystem of c: must be NTFS and not FAT.

Windows XP,2000 installations have been tested and should work. Windows NT, 95, 98 are ME not recommended.

Installation of DCMMS on other operating systems such as Linux may require minor changes to the source code. Please contact the DCMMS developers if you are having problems. The initial DCMMS version was created on Linux.


1.3.2.2. PostGIS

At least PostGIS 1.0.0 (lwpostgis.sql) is required to run DCMMS without adjustments to the source code.

It is recommended to use at least PostGIS 1.3.5 or higher.


1.3.3. Folder Structure

On Windows, the following folders contain files that belong to the standard DCMMS installation:

+ c:
|
+--+ ms4w
|  |
|  +--+ Apache
|  |  |
|  |  +--- conf
|  |  |
|  |  +--- logs
|  |
|  +--+ apps
|  |  |
|  |  +--+ dmms
|  |     |
|  |     +--- conf
|  |     |
|  |     +--- data
|  |     |
|  |     +--- htdocs
|  |     |
|  |     +--- include
|  |     |
|  |     +--- plugin
|  |
|  +--+ httpd.d
|  |
|  +--+ tmp
|     |
|     +--- ms_tmp
|
+--+ Program Files
|   |
|   +--+ PostgreSQL
|      |
|      +--+ 8.3
|         |
|         +--- data
|
+--+ windows
   |
   +--- fonts

[Note] Note

Note that your actual folder structure might be different, e.g. when you use a Non-English version of Windows XP. Use the structure above as a reference when you're not sure where to install things.

[Tip] Tip

If you are installing manually, you should install the software to the above mentioned folders.

The PostgreSQL folder holds the PostgreSQL installation, the Apache2 folder the Apache webserver and the php folder the PHP installation. The tmp folder holds temporary files (e.g. PHP session information) and the ms_tmp folder contains temporary map files created by mapserver.

For most of the software packages these folders are the default on a system with an English version of the Windows operating system. The folders will be created during the installation process described below.

c:\ms4w\apps\dcmms\config contains all configuration files with the exception of c:\ms4w\apps\dcmms\include\dcmconfig.php.

c:\ms4w\apps\dcmms\doc contains the documentation in various formats: CHM, DocBook XML, HTML, PDF.

c:\ms4w\apps\dcmms\data contains GIS data (shape files) used by the application. However this location is not fixed and may be overridden in the map file.

c:\ms4w\apps\dcmms\plugin contains application plug-ins (extensions that extend the functionality).


1.3.4. Administrator

Basic computer knowledge together with this guide should be sufficient to administer a stand-alone installation.

Any administrator will benefit from knowledge in SQL, PostgreSQL, the Windows command line interface (cmd.exe), Windows user administration, Windows services, GIS (e.g. ArcView), mailing lists - however such knowledge is not a requirement.

Various support possibilities are available to support new administrators (See Section 2.8.2, “Support Tracker”, Section 2.8.1, “DCMMS Info Mailing List”).


1.4. Concepts

1.4.1. Services
1.4.2. Windows Users
1.4.3. PostgreSQL users
1.4.4. Translation System
1.4.4.1. Gettext
1.4.4.2. The dcmmstranslation() Function
1.4.4.3. Map File Localization
1.4.5. Mailing Lists

This section outlines important concepts that are relevant to the DCMMS administration.


1.4.1. Services

This section introduces Windows services.

Apache and PostgreSQL run as Windows services.

To open the Services Panel, open the Control Panel from the Start Menu as shown in Figure 1.6, “Control Panel”.

Figure 1.6. Control Panel

In the Control Panel, click on the following icon:

Open the Services Panel by clicking on the this shortcut:

The Services Panel is displayed in Figure 1.7, “Services Panel”.

Figure 1.7. Services Panel

The Status column shows the services that are currently running. In Figure 1.7, “Services Panel” is running ("Started") while the Removable Storage is not running (empty Status column).

To start a service, click on the [image] button.

To stop a service, click on the [image] button.

In both cases, verify the success in the Status column of the service list.

For additional information on Windows services, consult your Windows documentation.


1.4.2. Windows Users

Important information on Windows user accounts.

Figure 1.8. Windows Users

Figure 1.8, “Windows Users” shows users that are important for the DCMMS administration. Note that the unpriviledged users account to operate DCMMS are omitted.

For additional information on Windows user accounts, consult your Windows documentation.

[Note] Note

While the Windows user accounts "system" and "postgres", you don't have to know their passwords.

[Note] Note

The name of the Windows user account to run the PostgreSQL database service (default: postgres) can be changed during the PostgreSQL installation.


1.4.3. PostgreSQL users

Introduction to PostgreSQL user management.

Figure 1.9. PostgreSQL Users

Figure 1.9, “PostgreSQL Users” shows PostgreSQL users that are important for the DCMMS administration. Windows users and system boundaries are shown to clarify the relationships.

The PostgreSQL documentation which you can access e.g. through the Start Menu (after PostgreSQL installation) or on the PostgreSQL website contains additional information on PostgreSQL user management.

[Caution] Caution

Don't get confused by the two "postgres" accounts: Even though they have the same name, they are different things, one lives inside PostgreSQL and one inside Windows. You don't have to know the password of the Windows account "postgres" (The PostgreSQL intaller is creating a long, random password for it), but you have to know the password of the PostgreSQL account "postgres".

Please follow the PostgreSQL installation instructions carefully (Section 2.1.2.3, “PostgreSQL”).


1.4.4. Translation System

1.4.4.1. Gettext
1.4.4.2. The dcmmstranslation() Function
1.4.4.3. Map File Localization

If you are going to use DCMMS in more than one language and would like to use the DCMMS translation system for your data, you should read this section.

DCMMS is actually using two translation systems: GNU gettext for text that occurs in the PHP sources and the dcmmstranslation() for text stored inside the PostgreSQL database.

[Note] Note

The dcmmstranslation() is not yet used for all text stored inside the PostgreSQL database (especially coded values). This will change gradually in the future. For the time being administrators and developers have to understand both translation systems.

Both gettext and dcmmstranslation() will fall back to the two letter ISO language code in case no translation is found for the five letter code (E.g. the "ar" translation is returned if "ar_JO" was requested and no translation was found).


1.4.4.1. Gettext

GNU gettext is a widely used system for translation management.

DCMMS is using the PHP gettext extension, the translations are edited in the locale/*/LC_MESSAGES/dcmms.po files. Replace "*" with a two letter ("ar") or five letter ("ar_JO") language code.

In order to be used by gettext, the source files (dcmms.po) files have to be compiled to dcmms.mo files.

Editing and compilation is conveniently done with poEdit (Section 2.1.6.3, “poEdit”). poEdit is also capable of extracting the translation terms from PHP sources.

Messages that have to be translated but are not included in the PHP sources should be added to include/i18n.php. This is the case e.g. for coded values from the database.


1.4.4.2. The dcmmstranslation() Function

Messages residing in the PostgreSQL database should be internationalized using the dcmmstranslation().

The dcmmstranslation() function looks up translations from the Translation table.

The name field of the AdministrativeArea, Landmark and Village should contain the name in the primary language that is used to operate the application. E.g. in the case of landmarks, this is the field that is filled and used if no other translation is given. Additional translations are stored in the translation table.

To use translations, e.g. in map files, use the following statement:

dcmmstranslation('en', name)
where 'en' is the ISO code of the language you want to use.

If no matching translation is found in the translation table, the term to translate is returned by dcmmstranslation().


1.4.4.3. Map File Localization

DCMMS allows to use language-specific map files.

The application replaces "%s" with the two-letter ISO language in the following dcmconfig.php configuration option:

$_SESSION["strMapFile"] = "conf/sample_%s.map";

This way it is possible to encapsulate language specific information in the map files.

PostGIS layers used in the map files can use the dcmmstranslation() function for translation.

See also Section 2.2.2, “Custom Map”


1.4.5. Mailing Lists

Mailing lists are automated distribution systems for emails.

The majority of the software products mentioned in this document offer a multitude of mailing lists to keep users and administrators updates about the latest releases as well as potential security issues.

[Tip] Tip

If you are not familiar with mailing lists yet, take the time to familiarize with the techniques to subscribe and to post to them.


Chapter 2. Reference

Table of Contents

2.1. Installation
2.1.1. DCMMS 2.0.0 and next versions Windows installation
2.1.1.1. MS4W base installation
2.1.1.2. PostgreSQL
2.1.1.3. PostGIS 1.3.5 Installation
2.1.1.4. DCMMS 2.0.4 MS4W base installation
2.1.1.5. Sample data
2.1.2. DCMMS 1.1.2 and previous versions Windows Installation
2.1.2.1. Apache
2.1.2.2. PHP
2.1.2.3. PostgreSQL
2.1.2.4. PostGIS
2.1.2.5. DCMMS
2.1.2.6. Sample data
2.1.3. Manual Installation
2.1.3.1. PostgreSQL
2.1.3.2. PostGIS
2.1.3.3. PostArabic
2.1.3.4. Fuzzystrmatch
2.1.3.5. Apache
2.1.3.6. PHP
2.1.3.7. Mapserver
2.1.3.8. DCMMS
2.1.3.9. Sample data
2.1.4. Default Accounts
2.1.5. Checklist
2.1.6. Optional Tools
2.1.6.1. Active Perl
2.1.6.2. GIX
2.1.6.3. poEdit
2.1.6.4. R
2.2. Configuration
2.2.1. Configuration Files
2.2.2. Custom Map
2.2.2.1. Tiled Shapefiles
2.2.2.2. PostGIS Layers
2.2.2.3. Tiled Images
2.2.2.4. Valve Symbols
2.2.3. Plug-Ins
2.2.3.1. Identify Plug-Ins
2.2.3.2. Search Plug-Ins
2.2.4. Database Side Customization
2.3. Administration
2.3.1. GIS Data Loading
2.3.1.1. Shapefile Loading
2.3.1.2. shp2pgsql
2.3.1.3. AdministrativeArea, Village and Landmark
2.3.2. Unit Cost Data Loading
2.3.3. Recurring Tasks
2.3.3.1. Backup
2.3.3.2. Restore
2.3.3.3. Merge DCMMS Databases
2.3.3.4. Removing Temporary Files
2.3.3.5. Quality Control
2.3.4. Security
2.3.5. Database
2.4. Analysis
2.4.1. Repairs per PressurizedMain
2.4.2. Pressure Dependency
2.5. Procedures
2.5.1. GIS Data Review
2.6. Updating
2.6.1. From 1.1.2 to 2.0.4
2.6.2. From 1.1.2 to 2.0.0
2.6.3. From 1.1.1 to 1.1.2
2.6.4. From 1.1.0 to 1.1.1
2.6.5. From 1.0.5 to 1.1.0
2.6.6. From 1.0.4 to 1.0.5
2.6.7. From 1.0.3 to 1.0.4
2.6.8. From 1.0.1 to 1.0.3
2.6.9. From 1.0.1 to 1.0.2
2.6.10. From 1.0.0 to 1.0.1
2.7. Frequently Asked Questions
2.7.1. There are too many coded values. How can I remove them?
2.7.2. How to add e.g. a new material?
2.7.3. How can I distinguish between Arabic and English texts in an SQL query?
2.8. Troubleshooting
2.8.1. DCMMS Info Mailing List
2.8.2. Support Tracker
2.8.3. Complete Uninstallation
2.8.4. Problems with Transparent Symbols
2.8.5. Shapefile Loading problems
2.8.6. Configuration error: PHP time != PostgreSQL time
2.8.7. Permission Denied for Relation CauseDomain
2.8.8. ERROR: column "oid" does not exist
2.8.9. New Landmarks Disappear
2.8.10. PostgreSQL Update
2.8.11. PostgreSQL Database Server Service
2.8.11.1. PostgreSQL Database Server Service Fails to Start
2.8.12. FATAL ERROR: PHP extension 'MapScript' is not loaded
2.8.13. Map Display
2.8.14. Restore
2.8.15. Unable to Load Dynamic Library
2.8.16. Header already sent error
2.8.17. Log Files
2.8.18. MapLab
2.8.19. Htdig
2.8.20. Cygwin PostgreSQL Upgrade


2.1. Installation

2.1.1. DCMMS 2.0.0 and next versions Windows installation
2.1.1.1. MS4W base installation
2.1.1.2. PostgreSQL
2.1.1.3. PostGIS 1.3.5 Installation
2.1.1.4. DCMMS 2.0.4 MS4W base installation
2.1.1.5. Sample data
2.1.2. DCMMS 1.1.2 and previous versions Windows Installation
2.1.2.1. Apache
2.1.2.2. PHP
2.1.2.3. PostgreSQL
2.1.2.4. PostGIS
2.1.2.5. DCMMS
2.1.2.6. Sample data
2.1.3. Manual Installation
2.1.3.1. PostgreSQL
2.1.3.2. PostGIS
2.1.3.3. PostArabic
2.1.3.4. Fuzzystrmatch
2.1.3.5. Apache
2.1.3.6. PHP
2.1.3.7. Mapserver
2.1.3.8. DCMMS
2.1.3.9. Sample data
2.1.4. Default Accounts
2.1.5. Checklist
2.1.6. Optional Tools
2.1.6.1. Active Perl
2.1.6.2. GIX
2.1.6.3. poEdit
2.1.6.4. R

This section outlines several installation options for the DCMMS application.

If you are updating an existing installation please refer to Section 2.6, “Updating”.

[Tip] Tip

The manual installation instructions will also work on operating systems like Linux.

[Tip] Tip

Please report all DCMMS installation problems in order to allow the developers to further enhance the installation process.


2.1.1. DCMMS 2.0.0 and next versions Windows installation

2.1.1.1. MS4W base installation
2.1.1.2. PostgreSQL
2.1.1.3. PostGIS 1.3.5 Installation
2.1.1.4. DCMMS 2.0.4 MS4W base installation
2.1.1.5. Sample data

How to install DCMMS on Windows XP Professional or Windows 2003 Server.

How to install DCMMS on Windows XP Professional or Windows 2003 Server.

Please contact the DCMMS developers if you are looking for a DCMMS CD release.

All installers mentioned below area available in the setup folder of the CD.


2.1.1.1. MS4W base installation

This section describes how to install MS4W for Windows.

The MS4W installer is available from the setup folder of the DCMMS CD or from http://www.maptools.org/dl/ms4w/.

There is two types of MS4W installers

              Zip file based MS4W installer, if this type is selected, the file
              should be extracted to c:\MS4W.

              Binary EXE excutable MS4W installer, this installer will install
              the MS4W package with all it's contents to  C:\MS4W.
[Note] Note

Using the ms4w-2.3.1-setup.exe require to have an internet connection to download the package components.

[Important] Important

It is recommended to use the Zip based MS4W installer.

Extract the zip file to C:\MS4W

After extraction, the Apache service should be installed by double click on the Apache-install.bat

[Important] Unblock the Apache service

For security reasons, the Apache service should be unblocked in order to be used

Unblock Apache service

Figure 2.1. Unblock Apache service


2.1.1.2. PostgreSQL

This section describes how to install PostgreSQL for Windows.

The PostgreSQL installer (postgresql-8.3.6-1-windows.exe) is available from the setup folder of the DCMMS CD or from http://www.enterprisedb.com/products/pgdownload.do#windows/.

[Note] Note

If you are going to download the PostgreSQL from the internet, Please consider that there is two Windows packages, It is recommended to download the PostgreSQL Windows One-Click Installers

Figure 2.2. PostgreSQL Installers

PostgreSQL Windows One click Installers

Figure 2.3. PostgreSQL Windows One click Installers

[Note] Note

PostGIS extension can be installed using the PostgreSQL 8.3 Application stack builder.

[Important] Important
An Internet connection should be available.

[Important] Important
IF THIS STEP IS DONE, YOU CAN SKIP THE PostGIS 1.3.5 Installation STEP, AND GO TO DCMMS 2.0.0 MS4W base installation STEP.

Figure 2.4. PostgreSQL Setup

Click Next >.

Choose Installation Path

Figure 2.5. Choose Installation Path

Choose Installation Path

Figure 2.6. Choose Installation Path

Choose Data folder Installation Path

Figure 2.7. Choose Data folder Installation Path

Enter the Password for the postgres super user

Figure 2.8. Enter the Password for the postgres super user

Choose Installation Path

Figure 2.9. Choose Installation Path

Choose Database Port

Figure 2.10. Choose Database Port

[Note] Note
Do not change the locale, keep the default settings as the default is UTF8
Choose Database locale

Figure 2.11. Choose Database locale

Click on the next button to start the installation.

Figure 2.12. Installation ready

When the installation is finished, the installer will ask to run the Stack builder, The stack title can be used to install additional componenets on top of PostgreSQL.

[Important] Important

Running the Stack builder requires to have an internet connection, if you do not have it, uncheck the check box.

[Important] Important

If you run the Stack builder, and installed the PostGIS, You can skip the PostGIS installation

Figure 2.13. Installation Completed


2.1.1.3. PostGIS 1.3.5 Installation

The PostGIS installer (postgis-pg83-setup-1.3.5-1.exe) is available from the setup folder of the DCMMS CD or from http://postgis.refractions.net/.

Figure 2.14. PostGIS License

Click on I Agree if you agree to the PostGIS license in Figure 2.48, “PostGIS License”.

Figure 2.15. PostGIS Components

[Caution] Caution

Uncheck the option Create Database as shown in Figure 2.49, “PostGIS Components” and click Next >.

The dcmms database will be created by the DCMMS installer.

Figure 2.16. PostGIS Location

Accept the default settings as shown in Figure 2.50, “PostGIS Location” and click Next >.

[Note] Note

The destination folder is your PostgreSQL installation folder and might differ from the one shown in Figure 2.50, “PostGIS Location”

PostGIS Database Connection

Figure 2.17. PostGIS Database Connection

Accept the default settings as shown in Figure 2.51, “PostGIS Database Connection” and enter the password you have chosen for the PostgreSQL superuser "postgres" (Section 2.1.2.3, “PostgreSQL”). Click Install.

Figure 2.18. Installation Complete

Click Close


2.1.1.4. DCMMS 2.0.4 MS4W base installation

The following steps should be followed in order to setup DCMMS 2.0.4 MS4W based version

The lastest version of the MS4W backage should be downloaded, and extracted to C:\MS4W

Click on the DCMMS 2.0.4 setup in order to install the DCMMS.

The DCMMS installer will copy the needed file under the C:\MS4W folder

The files will be copied to c:\MS4W\apache\htdocs

The files will be copied to c:\MS4W\httpd.d

The files will be copied to c:\MS4W\apache\a

Start the DCMMS Setup, which is available from the setup folder of the DCMMS CD or from the internet: http://dcmms.sourceforge.net.

Figure 2.19. Installer language

Select the language, and Click on OK.

Figure 2.20. DCMMS License

Click on I Agree if you agree to the license shown in the license dialog (Figure 2.20, “DCMMS License”).

Figure 2.21. DCMMS Components

Select all DCMMS components except Update as shown in Figure 2.21, “DCMMS Components” and click Next >.

Figure 2.22. DCMMS Location

Accept the default installation path, c:\ms4w, as shown in Figure 2.22, “DCMMS Location” and click Next >.

DCMMS Database Connection

Figure 2.23. DCMMS Database Connection

Enter the PostgreSQL superuser "postgres" password (As entered in Figure 2.8, “Enter the Password for the postgres super user”). Click Install.

You should now be able to start the DCMMS from the Start Menu or through the shortcut on the Desktop. Note that the full functionality will only be available once you've completed the data set, e.g. by loading the sample data.

[Note] Note

The installer will not overwrite existing DCMMS configuration files.


2.1.1.5. Sample data

The DCMMS sample installer is available in the setup folder of the CD or on the internet: http://dcmms.sourceforge.net.

Run the installer and adjust the default installation path, c:\ms4w\apps\dcmms.


2.1.2. DCMMS 1.1.2 and previous versions Windows Installation

2.1.2.1. Apache
2.1.2.2. PHP
2.1.2.3. PostgreSQL
2.1.2.4. PostGIS
2.1.2.5. DCMMS
2.1.2.6. Sample data

How to install DCMMS on Windows XP Professional or Windows 2003 Server.

How to install DCMMS on Windows XP Professional or Windows 2003 Server.

Please contact the DCMMS developers if you are looking for a DCMMS CD release.

All installers mentioned below area available in the setup folder of the CD.


2.1.2.1. Apache

[Tip] Tip

If you are running Skype, you may want to shutdown Skype while you are installing Apache as Skype might otherwise prevent Apache from using port 80.

[Tip] Tip

If the Apache installation is not fully successful because another program (e.g. IIS) is already using port 80, simply edit httpd.conf to use another port (e.g. "Listen 81" instead of "Listen 80" and run the Apache setup again. Choosing the repair option will complete the Apache installation.

Run the Apache installer. The Apache installer is available from the setup folder of the DCMMS CD or from the Apache website: http://httpd.apache.org.

Figure 2.24. Apache Wizard

In the Apache installer welcome page, click Next > (Figure 2.24, “Apache Wizard”).

Figure 2.25. Apache License

Select I accept the terms in the license agreement and click Next > (Figure 2.25, “Apache License”).

Figure 2.26. Apache Readme

Read through the information in Figure 2.26, “Apache Readme” and click on Next >.

Figure 2.27. Apache Information

Fill in the fields Network Domain (The domain of your Organization), Server Name (The name of your DCMMS server) and Administrator's Email Address (Your email address). Verify that the option for All Users, on Port 80, as a Service is selected and click Next > (Figure 2.27, “Apache Information”).

Apache Setup Type

Figure 2.28. Apache Setup Type

Verify the selection in Figure 2.28, “Apache Setup Type” and click Next >.

Figure 2.29. Apache Location

Make sure that the Destination Folder is C:\Program Files\Apache Group and click Next >.

[Tip] Tip

The DCMMS installer reads the Apache installation folder from the Windows registry. You can install Apache to different locations.

Figure 2.30. Apache Install

In the dialog shown in Figure 2.30, “Apache Install”, click Install.

[Tip] Tip

If the Apache installation fails because another application is using port 80, you can use the following commands to find out which application is using port 80:

netstat -aon
tasklist
Look for the process id (PID) of the process occupying port 80 and find the application of the process id.


2.1.2.2. PHP

Run the DCMMS Scripting installer. The installer is available from the setup folder of the CD or from the DCMMS website: http://dcmms.sourceforge.net.

Figure 2.31. PHP License

Click I Agree if you agree to the license (Figure 2.31, “PHP License”).

Figure 2.32. PHP Components

Click Next >.

[Tip] Tip

PEAR modules can be easily installed and upgraded over the internet. See the PEAR documentation for details. However, the DCMMS scripting installer provides all necessary packages.

Figure 2.33. PHP Location

Accept the default installation directory, c:\windows\php, by clicking Install (Figure 2.33, “PHP Location”).


2.1.2.3. PostgreSQL

This section describes how to install PostgreSQL for Windows.

The PostgreSQL installer (postgresql-8.1.msi) is available from the setup folder of the DCMMS CD or from http://pgfoundry.org/projects/pginstaller/.

[Note] Note

Don't get confused by the two PostgreSQL installer files. They are both required and can only be installed together.

Run the PostgreSQL installer and select the English language.

PostgreSQL Language Selection

Figure 2.34. PostgreSQL Language Selection

Click Start > to begin the Installation

Figure 2.35. PostgreSQL Setup

Click Next >.

Figure 2.36. Installation Notes

Press Next > after reading the installation instructions.

Choose Installation Options

Figure 2.37. Choose Installation Options

Note that the PostgreSQL installation path is not important. Please accept the default installation path provided by the installer.

Accept the other settings as shown in Figure 2.37, “Choose Installation Options” and click Next >.

Figure 2.38. Service Configuration

Accept the default settings as shown in Figure 2.38, “Service Configuration” and click Next >. Instead of "Z1027" your installer will show the name of your computer.

Figure 2.39. Account Error

Select Yes.

Figure 2.40. Password

Accept the random password by clicking OK.

[Tip] Tip

You don't have to remember the random password. It is only used internally to run the PostgreSQL service on Windows. See Section 1.4, “Concepts” for detailed information.

Successfully granted the 'Logon as a service' right

Figure 2.41. Successfully granted the 'Logon as a service' right

Click on OK.

Initialise Database Cluster

Figure 2.42. Initialise Database Cluster

Accept the default settings as shown in Figure 2.42, “Initialise Database Cluster” and choose an appropriate password for the PostgreSQL superuser "postgres". Enter the password to the Password and Password (again) fields then click Next >.

[Caution] Caution

You'll need this password (for the PostgreSQL superuser "postgres") later on during the installation process e.g. while running the DCMMS setup and for database maintenance purposes. Make sure that you remember it well.

Enable Procedural Languages

Figure 2.43. Enable Procedural Languages

Accept the default settings as shown in Figure 2.43, “Enable Procedural Languages”. Make sure that "PL/pgsql" is selected. Click Next >.

Enable Contrib Modules

Figure 2.44. Enable Contrib Modules

Accept the default selection as shown in Figure 2.44, “Enable Contrib Modules” and click Next >.

Figure 2.45. Enable PostGIS

As shown in Figure 2.45, “Enable PostGIS”, leave the option Enable PostGIS in template1 unchecked and click Next >.

PostGIS will be enabled for the dcmms database by the DCMMS installer.

Ready to Install

Figure 2.46. Ready to Install

As shown in Figure 2.46, “Ready to Install”, PostgeSQL can be installed now. Click Next >.

Figure 2.47. Installation complete

Click Finish.

[Tip] Tip

As mentioned in Figure 2.47, “Installation complete”, it is recommended to subscribe to the pgsql-announce mailing list to stay up-to-date with the latest PostgreSQL developments.


2.1.2.4. PostGIS

Once the PostgreSQL setup has finished, start the PostGIS setup which is available in the setup folder of the CD or on the internet: http://www.webbased.co.uk/mca/.

Figure 2.48. PostGIS License

Click on I Agree if you agree to the PostGIS license in Figure 2.48, “PostGIS License”.

Figure 2.49. PostGIS Components

[Caution] Caution

Uncheck the option Create Database as shown in Figure 2.49, “PostGIS Components” and click Next >.

The dcmms database will be created by the DCMMS installer.

Figure 2.50. PostGIS Location

Accept the default settings as shown in Figure 2.50, “PostGIS Location” and click Next >.

[Note] Note

The destination folder is your PostgreSQL installation folder and might differ from the one shown in Figure 2.50, “PostGIS Location”

PostGIS Database Connection

Figure 2.51. PostGIS Database Connection

Accept the default settings as shown in Figure 2.51, “PostGIS Database Connection” and enter the password you have chosen for the PostgreSQL superuser "postgres" (Section 2.1.2.3, “PostgreSQL”). Click Install.

Figure 2.52. Installation Complete

Click Close


2.1.2.5. DCMMS

Start the DCMMS Setup, which is available from the setup folder of the DCMMS CD or from the internet: http://dcmms.sourceforge.net.

Figure 2.53. DCMMS License

Click on I Agree if you agree to the license shown in the license dialog (Figure 2.53, “DCMMS License”).

Figure 2.54. DCMMS Components

Select all DCMMS components except Update as shown in Figure 2.54, “DCMMS Components” and click Next >.

Figure 2.55. DCMMS Location

Accept the default installation path, c:\program files\dcmms, as shown in Figure 2.55, “DCMMS Location” and click Next >.

DCMMS Database Connection

Figure 2.56. DCMMS Database Connection

Enter the PostgreSQL superuser "postgres" password (As entered in Figure 2.42, “Initialise Database Cluster”). Click Install.

You should now be able to start the DCMMS from the Start Menu or through the shortcut on the Desktop. Note that the full functionality will only be available once you've completed the data set, e.g. by loading the sample data.

[Note] Note

The installer will not overwrite existing DCMMS configuration files.


2.1.2.6. Sample data

The DCMMS sample installer is available in the setup folder of the CD or on the internet: http://dcmms.sourceforge.net.

Run the installer and accept the default parameters, especially the default installation path, c:\program files\dcmms.


2.1.3. Manual Installation

2.1.3.1. PostgreSQL
2.1.3.2. PostGIS
2.1.3.3. PostArabic
2.1.3.4. Fuzzystrmatch
2.1.3.5. Apache
2.1.3.6. PHP
2.1.3.7. Mapserver
2.1.3.8. DCMMS
2.1.3.9. Sample data

How to install DCMMS manually.

[Note] Note

This section might be useful only for installations on non-Windows platforms and for developers who are interested in the details of the DCMMS installation process.

[Tip] Tip

The DCMMS installer sources (e.g. dcmms.nsi) may contain additional helpful information on the installation process.

[Caution] Caution

The following expects that various PostgreSQL binaries, such as psql.exe or createlang.exe are in the PATH. If necessary, you have to change your PATH environment variable to include the bin folder of your PostgreSQL installation.


2.1.3.1. PostgreSQL

The PostgreSQL database is available from http://www.postgresql.org.

The PostgreSQL installation should support UNICODE.

[Warning] Warning

You may run into problems if you use a binary PostgreSQL distribution under Linux or UNIX. In order to use PostGIS and specifically GEOS from PostgreSQL, the binaries have to be linked against libstc++. The PostGIS documentation contains details regarding this issue.

In order to enforce DCMMS logins with password authentication, the pg_hba.conf configuration file should be altered like in the following example:

# TYPE  DATABASE    USER      IP-ADDRESS  IP-MASK           METHOD
host    all         postgres  127.0.0.1   255.255.255.255   trust
host    dcmms       all       127.0.0.1   255.255.255.255   password

Note that this still allows the PostgreSQL superuser postgres to connect to PostgreSQL server without authentication. However the user postgres is not allowed to log on to DCMMS.

[Note] Note

The instructions below assume that the PostgreSQL administrator is named postgres and that the postmaster is running on the local machine (localhost). If this is not the case for you, you'll have to adjust the commands accordingly. The same applies to the connection method - if your postmaster is not configured to accept TCP/IP connections, you have to adjust the commands (and possibly the DCMMS configuration).

Create a new database named dcmms using UNICODE, load the PL/SQL language to the database:

createdb -U postgres -h localhost --encoding=UNICODE dcmms
createlang -U postgres -h localhost plpgsql dcmms

If PL/SQL was created in template1, the second command will fail. Ignore the error message in this case.


2.1.3.2. PostGIS

PostGIS is available from http://postgis.refractions.net .

Follow the installation instructions in the PostGIS documentation.

Once PostGIS is installed, change to the directory containing postgis.sql and spatial_ref_sys.sql and load PostGIS to the dcmms database:

psql -U postgres -h localhost -f postgis.sql dcmms
psql -U postgres -h localhost -f spatial_ref_sys.sql dcmms


2.1.3.3. PostArabic

PostArabic is a small module that adds Arabic shaping functionality to PostgreSQL.

[Tip] Tip

The PostArabic installation is only required in order to display Arabic map labels. If you are not interested in Arabic map labels, you can skip the PostArabic installation.

The PostArabic sources are available from the DCMMS download page.

Follow the installation instructions in the file README.arabic.

Change to the directory containing arabic.sql and load PostArabic to the dcmms database:

psql -U postgres -h localhost -f arabic.sql dcmms


2.1.3.4. Fuzzystrmatch

DCMMS allows the fuzzy search of landmarks. Through the fuzzy search, landmarks can be found even if the search term was misspelled.

The fuzzystrmatch module of the PostgreSQL distribution is used for this purpose.

To compile and install the fuzzystrmatch module, go to the contrib folder of your PostgreSQL source tree and execute the following commands:

make
make install
psql -U postgres -h localhost -f fuzzystrmatch.sql

If you are using the Windows PostgreSQL installer, you find fuzzystrmatch.dll in c:\Program Files\PostgreSQL\8.1\share\contrib.


2.1.3.5. Apache

The Apache webserver is available from http://httpd.apache.org .

Follow the installation instructions in the Apache documentation.

Apache is configured through the httpd.conf file. In order to access the DCMMS application by a convenient URL like http://localhost/dcmms/, you should add lines like the following to httpd.conf:

Alias /dcmms "c:/program files/dcmms/"
<Directory "c:/program files/dcmms">
  Options Indexes Multiviews
</Directory>

Alias /ms_tmp/ "c:/tmp/ms_tmp/"

The second alias line configures the location of temporary files created by PHP/Mapscript. You will have to adjust the DCMMS sources to use the same alias and path. Adjust the path names according to your DCMMS installation path.


2.1.3.6. PHP

The PHP scripting language is available from www.php.net.

DCMMS is currently using PHP 4.*. Use of DCMMS with PHP 5.0 will require some small changes to the application and is not recommended yet. Please contact the DCMMS developers if PHP 5.0 is a requirement for your installation.

Follow the installation instructions in the PHP documentations.

[Note] Note

If you don't install PHP to c:\windows\php, some of the settings below have to be adjusted.

[Caution] Caution

Because of previous PHP/Mapscript limitations, it is recommended to install PHP as a CGI command.

The use of PHP as an Apache module is not very well tested with DCMMS and may lead to instabilities. If you are testing such a setup, please share your experiences with the DCMMS developers.

The installation can be completed with the following three lines in httpd.conf:

ScriptAlias /php/ "c:/windows/php/"
AddType application/x-httpd-php .php
Action application/x-httpd-php "/php/php.exe"

Again, make sure that the path names above match the ones on your system.

Add the following DCMMS-specific configuration settings to c:\windows\php.ini:

default_mimetype = "text/html"
default_charset = "utf-8"

include_path = ".;c:\windows\php\pear"

error_reporting  =  E_ALL & ~E_NOTICE

extension_dir = "c:/windows/php/extensions"
enable_dl = On

allow_call_time_pass_reference = On

file_uploads = On
upload_tmp_dir = c:\tmp
upload_max_filesize = 20M

extension=php_gd2.dll
extension=php_gettext.dll
extension=php_pgsql.dll
extension=php_zip.dll
extension=php_mapscript_46.dll

[Session]
session.save_path = c:/tmp

[Caution] Caution

In order to use gettext in PHP on Linux, the PHP safe mode has to be enabled. The reason is that the putenv() function to set the locale will fail otherwise. In php.ini:

safe_mode = On


2.1.3.7. Mapserver

On Windows, install the mapserver distribution with PHP/Mapscript, which is available from the internet under http://maptools.org.

On other operating systems, install PHP/Mapscript from the Mapserver distribution which is available from http://mapserver.gis.umn.edu/index.html.

Make sure that the PHP/Mapscript extension is loaded in php.ini.

[Note] Note

You'll need a PHP/Mapscript binary compiled with PostGIS support.


2.1.3.8. DCMMS

The DCMMS source tarball is available from http://dcmms.sourceforge.net.

The SQL scripts create_dcmms_ddl.sql and create_views.sql in the script folder of the DCMMS distribution create users and data model for the application.

Change the directory to the script folder and run the scripts on the dcmms database:

psql -U postgres -h localhost -f create_dcmms_ddl.sql dcmms
psql -U postgres -h localhost -f create_views.sql dcmms

Copy the default configuration file, include/dcmconfig.php.default to include/dcmconfig.php.

Review the settings in dcmconfig.php and adjust if necessary.

Copy the default DataObject configuration file conf/dataobject.ini.default to conf/dataobject.ini.

Review the settings in dataobject.ini and adjust if necessary - especially all settings that include a path.

Copy the default identify plugin configuration file conf/identifyplugin.ini.default to conf/identifyplugin.ini.

Review the settings in identifyplugin.ini and adjust if necessary - especially all settings that include a path.

You should now be able to log on to the DCMMS application, using a URL like http://localhost/dcmms.


2.1.3.9. Sample data

A sample data set is available from the DCMMS download page.

Unpack the files to the data folder of your DCMMS installation.

Load the AdministrativeArea, Village and Landmark shapefiles to the database. This can be done using Gshp2pgsql (Section 2.3.1, “GIS Data Loading”) or using the following commands from the commandline:

set PGCLIENTENCODING=WINDOWS-1256
psql -d dcmms -U postgres -h localhost -f administrativearea.sql
psql -d dcmms -U postgres -h localhost -f village.sql
psql -d dcmms -U postgres -h localhost -f landmark.sql
In this case, the commands have to be executed in the data folder.


2.1.4. Default Accounts

Upon first installation, the DCMMS application will provide two default PostgreSQL (DCMMS) users:

  • User dcmms with password dcmms.

  • User admin with password admin.

As the name indicates, admin has administrator rights, whereas the user dcmms has not.

See Section 1.4.3, “PostgreSQL users” for detailed information on Windows and PostgreSQL users.

[Caution] Caution

On production systems, you should change the default passwords as soon as possible for security reasons.


2.1.5. Checklist

The following points should be checked before a DCMMS goes into production:

  • Administrator passwords on the Windows and PostgreSQL level

  • System clock setting

  • User rights (use the Windows "guest" account if possible for DCMMS users)

  • Security updates

  • Network connections including Firewall

  • Eventually all removable media drives should be disabled to prevent installation of software (applies to standalone systems that should be specially hardened).

  • The PostgreSQL timezone setting. If necessary, adjust postgresql.conf, e.g. by adding a line like

    timezone = 'GMT-3'

    You can check the timezone setting by the following SQL statement:

    select now()

    Failure to configure the timezone correctly will result in the following error message in the logon page: Configuration Error: PHP Time != PostgreSQL time.

    See also Section 2.8.6, “Configuration error: PHP time != PostgreSQL time”.


2.1.6. Optional Tools

2.1.6.1. Active Perl
2.1.6.2. GIX
2.1.6.3. poEdit
2.1.6.4. R

This section describes the installation of various optional tools that ease the DCMMS administration and configuration.


2.1.6.1. Active Perl

Active Perl is a PERL distribution for Windows.

It is freely available from http://www.activestate.com.

PERL is the programming language used for some PostGIS maintenance tools like postgis_restore.pl.

On other operating systems like Linux, you will most likely be able to use the PERL distribution that is already installed.


2.1.6.2. GIX

GIX is an ArcView 3.* extension that allows to export views to mapserver map files.

GIX is available from http://gix.sourceforge.net.

[Note] Note

You can only use fragments from the map files created by GIX as ArcView 3.* does not support PostGIS.

See Section 2.2.2, “Custom Map” for details regarding the DCMMS map files.


2.1.6.3. poEdit

To edit the dcmms.po files, poEdit is recommended. It is freely available from http://poedit.sourceforge.net.

[Tip] Tip

Install poEdit version 1.3.1 or higher.

In order to extract the translation messages from the PHP sources, the following settings should be applied.

Start poEdit.

Select Preferences from the File menu.

Select the Parser tab and click on the New button.

poEdit PHP parser settings

Figure 2.57. poEdit PHP parser settings

Fill in the settings as shown in Figure 2.57, “poEdit PHP parser settings”

Close the dialogs.

Open a dcmms.po file.

Choose Options... from the Catalog menu.

In the Paths tab, add the path to the DCMMS source as shown in Figure 2.58, “Catalog Path”

Figure 2.58. Catalog Path

[Caution] Caution

Make sure that you enter the actual path to the DCMMS sources on your system.

Once the settings above have been applied, it is possible to update the catalog by selecting Update from sources from the Catalog menu.

See also Section 1.4.4, “Translation System”.


2.1.6.4. R

The R statistical analysis package can be used for the analysis. R is available from http://www.r-project.org/.

R can be used e.g. to analyze the pressure dependency of maintenance events (Section 2.4.2, “Pressure Dependency”).


2.2. Configuration

2.2.1. Configuration Files
2.2.2. Custom Map
2.2.2.1. Tiled Shapefiles
2.2.2.2. PostGIS Layers
2.2.2.3. Tiled Images
2.2.2.4. Valve Symbols
2.2.3. Plug-Ins
2.2.3.1. Identify Plug-Ins
2.2.3.2. Search Plug-Ins
2.2.4. Database Side Customization

This section describes how to configure DCMMS after successfull installation.


2.2.1. Configuration Files

The file include/dcmconfig.php contains the configuration of the DCMMS application.

A default configuration file is stored under include/dcmconfig.php.default. Copy this file to include/dcmconfig.php if necessary.

The configuration file can be edited using any text editor.

All other configuration files can be found in the conf folder: c:\ms4w\apps\dcmms\conf.

The PHP configuration file php.ini is installed by default under c:\windows.

The intSRID variable in dcmconfig.php is used to specify the spatial referencing system identifier for your spatial data. The PostGIS documentation contains detailed information about spatial reference systems. PostGIS stores SRIDs in the spatial_ref_sys table. A value of "-1" can be used in case no real SRID is available. However, the specification of an SRID is very important in order to expose the data through services like WMS.


2.2.2. Custom Map

2.2.2.1. Tiled Shapefiles
2.2.2.2. PostGIS Layers
2.2.2.3. Tiled Images
2.2.2.4. Valve Symbols

How to use your own maps with DCMMS.

Create your own map file(s) and edit the following line in dcmconfig.php to point to this file:

$_SESSION["strMapFile"] = "conf/sample_%s.map";

[Warning] Warning

When customizing the map files, make sure to use other names than sample_en.map. An update of the application would otherwise overwrite your customized map files.

Adjust dcmconfig.php accordingly.

In the default configuration, you need one map file for every language (%s will be replaced with the two-letter ISO language code).

If you would like to use DCMMS in more than one language, please also read Section 1.4.4, “Translation System”.

[Note] Note

The "DESCRIPTION" metadata information must be provided for layers that return results for the identify tool.

In addition, the "TEMPLATE" has to be set for the respective class.

The following layers are required and should be copied from the sample files:

AdministrativeArea
AreaOfInterest
Landmark
PressurizedMain
Village
[Tip] Tip

The default map resolution in map.php can be configured in the map file. Look for a line like the following:

SIZE 600 450

Currently the following configurations are possible without changes to the PHP source:
SIZE 400 300
SIZE 600 450
SIZE 800 600

[Tip] Tip

DCMMS comes with symbol and font definitions in the files etc\symbols.sym and etc\fonts.txt. It is recommended that you use different files for custom symbol and font definitions.

A DCMMS update will overwrite these files.
[Tip] Tip

Use shptree.exe from the mapserver distribution to index large shape files used by the application.

Indexes created by shptree.exe will increase the performance when PHP/Mapscript is dealing with these files.

Note that the shptree.exe index format differs e.g. from the one used by ArcView.

[Tip] Tip

ArcView 3.* users may want to use the GIX extension to transfer symbology from ArcView to the mapserver map file.

See Section 2.1.6.2, “GIX”.

The mapserver documentation available from http://mapserver.gis.umn.edu/ contains detailed information about the mapfile syntax.


2.2.2.1. Tiled Shapefiles

Tiled shapefiles allow mapserver to maximize performance for large shapefile datasets.

The ngwa.map map file provides an example of tiled shapefile usage.

Please refer to the mapserver documentation for details on tiled shapefiles.

[Tip] Tip

Use the tileindex.exe from the mapserver distribution to create tile indexes.

[Caution] Caution

Uniform shapefiles have to be used when they are tiled. They have to have exactly the same number of fields in the same order.

To re-order shapefile fields using ArcView 3.*, follow these steps:

  • Open a View.

  • Add the shapefile as a Theme to the View.

  • Open the attribute table.

  • Drag and drop the field headers until they are in the correct order.

  • Go back to the View.

  • Select Theme->Convert to Shapefile.


2.2.2.2. PostGIS Layers

The DCMMS application replaces the dummy user name and password in the mapfile with the information provided by the user when logging on. Example 2.1, “PostGIS Connection Example” shows an example PostGIS connection line from a mapfile.

Example 2.1. PostGIS Connection Example

CONNECTION "dbname=dcmms user=dummy password=dummy host=localhost"

[Important] Important

Make sure that the PostgreSQL "dcmmsuser" group has the right to select from the tables used for your PostGIS layers.


2.2.2.3. Tiled Images

Tiled images allow mapserver to maximize performance for large raster datasets.

The following steps are required to prepare the tiled images, and include them on the map file.

Please refer to the mapserver documentation for details on tiled images.

Use the gdaltindex.exe from the mapserver distribution to create tile indexes.

Example of usage:

gdaltindex sana_index.shp *.tif
[Tip] Tip

In order to increase the display, and rendering performance of the images it is prefered to create over views for these images using the following command:

gdaladdo -r average imagename.tif 2 4 8 16 32 64 128

You can add the tiled images on the map file using the following statements:

          LAYER
              NAME "satellite"
              STATUS default
              TILEINDEX "c:\ms4w\apps\dcmms\tiff\image_index.shp"
              TILEITEM "Location"
              TYPE RASTER
          END
[Tip] Tip

When using raster data, it is recommended to change the IMAGETYPE parameter to "JPEG" as it offers good compression for raster data.


2.2.2.4. Valve Symbols

esri_0 c:/windows/fonts/esri_0.ttf
LAYER
  NAME Valve
  data "c:/ms4w/apps/dcmms/data/valve"
  TYPE POINT
  STATUS DEFAULT
  maxscale 5000
  labelmaxscale 5000
  labelitem "symbol"
  labelangleitem "angle"
  CLASS
    NAME 'Valve'
    template "ttt_query.html"
    SYMBOL "circle"
    SIZE 1
    COLOR 0 0 255
    LABEL
    color 0 0 255
    position cc
    font esri_0
    type truetype
    size 10
  END
  END

  METADATA
    "DESCRIPTION" "Valve"
    "RESULT_FIELDS" "DIAMETER"
  END
  TOLERANCE 5
END


2.2.3. Plug-Ins

2.2.3.1. Identify Plug-Ins
2.2.3.2. Search Plug-Ins

Plug-Ins provide configurable and extensible ways to extend the application functionality in a way that is compatible with future releases of the the software.


2.2.3.1. Identify Plug-Ins

Plug-ins for the identify tool of the map page allow to extend the functionality of the application.

The plug-ins are configured in conf/identifyplugin.ini. The file is a simple text file that can be edited with any text editor.

DCMMS comes with the ImageIdentifyPlugin - see Section 2.2.3.1.1, “Image Identify Plug-In” for details.

Example 2.2. Excerpt from identifyplugin.ini

; Configuration file for map.php plug-ins
[IdentifyPlugin]
Plugin1 = ImageIdentifyPlugin
Layer1 = village
;Plugin2 = ???
;Layer2 = ???

  • Lines starting with ";" are comments and are ignored.

  • Section header of the IdentifyPlugin section.

  • The class ImageIdentifyPlugin (from plugin/imageidentifyplugin.php) will be loaded as the first plug-in. The configuration line for the second plug-in starts with "Plugin2"

  • The first plug-in will be used when the identify tool selects features in the "village" layer.

  • The configuration lines for the second plug-in are commented out, this plug-in has been disabled.

Note that identifyplugin.ini can also contain configuration options for the individual plug-ins (in different sections). See the "[Plugin1]", "[Plugin2]", ... sections for details.

2.2.3.1.1. Image Identify Plug-In

The ImageIdentifyPlugin provides functionality to link systematically stored images to map elements. This is similar to the ArcView "hot links".

The DCMMS sample data together with the provided sample configuration files can be used to illustrate the use of ImageIdentifyPlugin.


2.2.3.2. Search Plug-Ins

Search plug-ins allow additional search functionality to be added to the find tool that is displayed on every page. Use of search plug-ins is triggered by configurable keywords that are followed by a colon (":") and the search term itself.

Search plug-ins are easy to implement. The DCMMS Developer Guide contains the details.

The search plug-ins are configured in conf/searchplugin.ini. The file is a simple text file that can be edited with any text editor.

DCMMS includes the CustomerSearchPlugin - see Section 2.2.3.2.1, “Customer Search Plug-In” for details.

Example 2.3. Excerpt from searchplugin.ini

; Configuration file for search.php plug-ins   1
[SearchPlugin]   2
Plugin1 = CustomerSearchPlugin   3
; The keyword that triggers the plug-in to be executed. Case sensitive.
Keyword1 = customer   4
;Plugin2 = ???   5
;Keyword2 = ???   6

[Plugin1]   7

Lines starting with ";" are comments and are ignored.

The section header starting the search plug-in configuration section.

The CustomerSearchPlugin class is the first plug-in that is registered with the application. Keyword1 will define when the plug-in is executed. Additional configuration parameters for the

The first plug-in (CustomerSearchPlugin will be executed when the keyword "customer" is used (e.g. using the search term "customer:311").

An additional plug-in can be added by uncommenting this line and replacing the question marks with the plug-in class name.

This header starts the configuration section for Plugin1, in this example the CustomerSearchPlugin. See Section 2.2.3.2.1, “Customer Search Plug-In” for details.

2.2.3.2.1. Customer Search Plug-In

The customer search plug-in allows to find customer locations on their map using a numeric identifier like the contract number.

Geocoded customer locations (polygons) are required in order to use the plug-ins functionality. The CustomerSearchPlugin class in plugin/customersearchplugin.php contains the implementation.

The plug-in assumes a two table structure where the first table (customer) contains the search term (customer ID) and the geocode as a foreign key. The second table (building) contains the geocode and the polygon geometry that will be used to determine the map extent. The relationship between customer and building is one-to-many.

Example 2.4, “Customer Search Plug-In Configuration” contains a snippet from searchplugin.ini with an example CustomerSearchPlugin configuration.

Example 2.4. Customer Search Plug-In Configuration

[Plugin1]   1
; PEAR DB Data Source Name (DSN). See PEAR DB documentation for details.   2
DSN = pgsql://dcmms:dcmms@localhost/customer   3
; Name of the table that contains customer id and geocode.
CustomerTable = customer   4
; Name of the id field in the customer table. Should be indexed.
CustomerID = id   5
; Name of the geocode field in the customer table
CustomerGeocode = geocode   6
; Name of the table that contains geocode and polygon geometry. Should be indexed.
BuildingTable = building   7
; Name of the geocode field in the building table
BuildingGeocode = nwsa_pk   8
; Name of the geometry field in the building table
BuildingGeometry = the_geom   9

Section "Plugin1" contains the CustomerSearchPlugin configuration if CustomerSearchPlugin was registered as Plugin1 (See Example 2.3, “Excerpt from searchplugin.ini”).

Lines starting with ";" are comments.

In this case, the customer database from the PostgreSQL server running on localhost will be used with the user name dcmms and the password dcmms.

The "customer" table will be queried for the search term (ID) provided by the user.

The "id" field of the customer table contains the customer id.

The "geocode" field of the customer table will be used to join the building table (foreign key).

The "building" table will be joined against the customer table. It contains the geographic information.

The "nwsa_pk" field (primary key) will be used to join the customer table.

The "the_geom" field of the building table contains the polygon geometry that will be used to determine the map extent.

[Tip] Tip

The necessary SQL statements to create the table structure required for this example configuration is described in source code comments in plugin/customersearchplugin.ini.

[Important] Important

Note that the DSN configuration option contains database user name and password in clear text. Take protective measures like locking down this particular user account or protect conf/searchplugin.ini from unauthorized access.

[Tip] Tip

If your customer data resides in an ORACLE database, the following instructions show how to move the data to an PostgreSQL database using ArcView 3.x:

Create an ODBC connection to your ORACLE database.

In the ArcView Project GUI, connect to the database using Project->SQL Connect....

Query the table that contains the customer information.

In the ArcView table, choose Table->Properties.. from the menu.

Make all fields except the id and geocode fields invisible.

Close the Table Properties dialog.

Ensure that the id field is before the geocode field.

Export the table to a delimited text file by choosing File->Export... from the menu.

The exported file should look like in Example 2.5, “First lines of sample customer.txt file”.

Example 2.5. First lines of sample customer.txt file

"Id","Nwsa_pk"
48859,1617410105001701
48433,1318310119001821

The customer.txt file can be loaded to PostgreSQL using the following SQL statement (adjust the path to the file accordingly):

copy customer from 'c:/tmp/customer.txt' with csv header
[Tip] Tip

The building table can be created directly from a polygon shapefile that contains the geocode field. See Section 2.3.1, “GIS Data Loading” for different options to load shapefiles to GIS databases.


2.2.4. Database Side Customization

Through modification of lookup table values in the database, DCMMS can be customized to meet different needs. Please explore the DCMMS data model and the DCMMS database for details.

[Caution] Caution

To prevent future DCMMS updates from overwriting your customizations (or your customizations colliding with future DCMMS coded values, you are strongly advised to coordinate your database-side customizations with the developers, e.g. by sending an email to <dcmms-devel@lists.sourceforge.net>.


2.3. Administration

2.3.1. GIS Data Loading
2.3.1.1. Shapefile Loading
2.3.1.2. shp2pgsql
2.3.1.3. AdministrativeArea, Village and Landmark
2.3.2. Unit Cost Data Loading
2.3.3. Recurring Tasks
2.3.3.1. Backup
2.3.3.2. Restore
2.3.3.3. Merge DCMMS Databases
2.3.3.4. Removing Temporary Files
2.3.3.5. Quality Control
2.3.4. Security
2.3.5. Database

This section describes various tasks related to the DCMMS administration.


2.3.1. GIS Data Loading

2.3.1.1. Shapefile Loading
2.3.1.2. shp2pgsql
2.3.1.3. AdministrativeArea, Village and Landmark

This section discusses various ways to load GIS data in various formats to the dcmms database.

[Tip] Tip

Not all GIS data used by the application has to be loaded to the database. Data that is only displayed on the map and not used otherwise in the application can be kept in its original format and location if it is supported by Mapserver. This is the case for shapefiles. Unless you are restoring a backup, only the following three layers of GIS data have to be loaded to the DCMMS database:

AdministrativeArea
Landmark
Village

Besides the options described in the following sections, tools like ogr, QGIS or FME can also be used to load the data.

If you would like to load and use data in multiple languages, an understanding of the translation system (Section 1.4.4, “Translation System”) is required.

[Tip] Tip

For ArcView 3.x users, the AV PostGIS Connection extension is the preferred way to load shapefiles to PostGIS:

http://avpgcon.sourceforge.net


2.3.1.1. Shapefile Loading

When loading certain shapefiles to the DCMMS database, it might be required to drop the views before loading and to restore them after loading. The scripts script/drop_views.sql and script/create_views.sql can be used for this purpose.

[Note] Note

Data that is edited in DCMMS uses sequences to determine the next primary key. For this reason it might be necessary to adjust a sequence if certain shapefiles are loaded. One example is the landmark table. The following SQL statement shows how to set the correct start value for the sequence after the landmark shapefile is loaded:

select setval('landmark_seq', max(gid) from landmark);

[Note] Note

You may also want to update the Translation table after loading shapefiles that contain translations (Section 1.4.4, “Translation System”).


2.3.1.2. shp2pgsql

The commandline tool shp2pgsql is part of the PostGIS distribution and used internally by Gshp2pgsql. It allows to load shapefiles to PostGIS tables.

Make sure that shp2pgsql.exe and psql.exe are in the path:

PATH=%PATH%;c:\Program Files\PostgreSQL\8.1\bin

If necessary, adjust the encoding used by psql through the PGCLIENTENCODING environment variable:

set PGCLIENTENCODING=WINDOWS-1256

Before the AdministrativeArea, Landmark or Village shapefiles are loaded to the database, the DCMMS views have to be dropped:

psql -d dcmms -U postgres -f \
"c:\ms4w\apps\dcmms\script\drop_views.sql"

Load the shapefile to the database:

shp2pgsql -d -D landmark.shp landmark > landmark.sql
psql -d dcmms -U postgres -f landmark.sql

If the table does not exist in your database yet, omit the "-d" option when calling shp2pgsql. See the shp2pgsql documentation for details.

Recreate the views if necessary:

psql -d dcmms -U postgres -f \
"c:\ms4w\apps\dcmms\script\create_views.sql"


2.3.1.3. AdministrativeArea, Village and Landmark

How to prepare AdministrativeArea, Village and Landmark layers to be loaded to the application.

The features of AdministrativeArea shall not overlap and cover the whole area where landmarks are possibly inserted. The features of Village shall not overlap and cover the whole area where landmarks are possibly inserted. It is recommened to create a rectangular covering area around both classes.

The application expects the administra field in Landmark shall be filled with the CodedValue from the AdministrativeArea that contains (intersects) the landmark.


2.3.2. Unit Cost Data Loading

In case you have the unit cost information saved in an Excel sheet, to load unit cost information to the PostgreSQL database do the following:

  1. Delete all the fields from the file except for the folowing fields:

    1. ID

    2. Diameter1

    3. Diameter2

    4. Price

    5. Unit ID (The Subtype in Material, Staff or Equipment)

    [Important] Important

    You should keep the same fields order and Delete the names of the field.

  2. Save the Excel sheet file as a "Text(Tab delimited)" file

  3. Execute the following SQL statements for the Material cost file:

    delete from materialcost;
copy materialcost from
'D:\\sandbox\\water\\dcmms\\txt_cost_sheet.txt'
with NULL as ''
delimiter as '\t';

  4. Repeat the same statements for the tables staffcost, equipmentcost


2.3.3. Recurring Tasks

2.3.3.1. Backup
2.3.3.2. Restore
2.3.3.3. Merge DCMMS Databases
2.3.3.4. Removing Temporary Files
2.3.3.5. Quality Control


2.3.3.1. Backup

[Tip] Tip

You can use pgAdmin III as well as the commandline tools pg_dump or pg_dumpall to backup your DCMMS database. Please refer to the pgAdmin III and PostgreSQL documentation for detailed information on how to perform the backups. In addition, the instructions below explain how to backup the database using the PostgreSQL command line tool pg_dumpall.

For all GIS data displayed in the DCMMS maps, follow your usual backup strategies.

In order to backup the content of the DCMMS database, do the following:

  1. Open a Windows commandline (e.g. by executing %SYSTEMROOT%\system32\cmd.exe).

  2. Execute the command below to create a dump file of the database. The dump file will be saved as c:\dcmms-backup.sql.

    pg_dumpall -c -U postgres -h localhost > c:\dcmms-backup.sql

    [Caution] Caution

    You have to make sure that pg_dumpall is in your PATH.

  3. Write the dump file to a suitable backup media (e.g. a rewritable CD-ROM or a tape) and store it in a safe place.

[Important] Important

Make sure that you also backup your map and configuration and symbol files (c:\Program Files\dcmms\include\dcmconfig.php and all files under c:\ms4w\apps\dcmms\conf).


2.3.3.2. Restore

[Tip] Tip

Restore is available through pgAdmin III as well as the commandline tools psql or pg_restore. Please refer to the pgAdmin III and PostgreSQL documentation for details how to restore a database dump. In addition, the instructions below explain how to restore the database using the PostgreSQL command line tool psql.

Restore all the GIS data used in the map from your GIS data backups.

In order to restore a previous dump file of the DCMMS database, execute the following commands:

  1. Open a Windows commandline (e.g. by executing %SYSTEMROOT%\system32\cmd.exe).

  2. Restore the dump file:

    psql -f c:\dcmms-backup.sql -U postgres -h localhost -d dcmms
    Where c:\dcmms-backup.sql is the path to the dump file - adjust this accordingly if your dump file is not c:\dcmms-backup.sql. Alternatively, you can copy your dump file to c:\dcmms-backup.sql

    You may be asked to enter the password of the PostgreSQL superuser "postgres".

[Tip] Tip

Remember to drop the database and create an empty one before restoring your backup. Use "UTF-8" as the database encoding when creating the database.


2.3.3.3. Merge DCMMS Databases

This section describes the necessary steps to merge workorders, maintenance records and resource information from two DCMMS databases.

Before the data from the databases can be merged, it has to be ensured that the two different databases use different workorder numbers. In the following example, the workorder numbers will be shifted by a 1,000,000 offset to achieve this namespace separation. To shift existing DCMMS records to another number "namespace", the following SQL commands can be used:

alter table maintenance drop constraint "$1";
alter table resource drop constraint "$1";
update workorder set id=id+1000000;
update maintenance set id=id+1000000;
update resource set maintenanceoid=maintenanceoid+1000000;
update resource set id=id+1000000;
update seal set id=id+1000000;
update history set id=id+1000000;
update history set recordoid=recordoid+1000000;
alter table maintenance add constraint "$1" foreign key(id) references
  workorder(id);
alter table resource add constraint "$1" foreign key(maintenanceoid) references
  maintenance(id);

This shift should be accompanied with re-setting the sequence numbers with the same offset as demonstrated with the SQL commands below:

drop sequence history_seq;
drop sequence landmark_seq;
drop sequence workorder_seq;
drop sequence ResourceID;
drop sequence seal_seq;
create sequence history_seq start 1000000;
create sequence landmark_seq start 1000000;
create sequence workorder_seq start 1000000;
create sequence ResourceID start 1000000;
create sequence seal_seq start 1000000;

Once the workorder IDs are unique throughout both databases, a special database dump can be created from the first database using the following commands in the Windows commandline:

pg_dump -U postgres -t history -D -a dcmms > dcmms_merge.sql
pg_dump -U postgres -t workorder -D -a dcmms >> dcmms_merge.sql
pg_dump -U postgres -t maintenance -D -a dcmms >> dcmms_merge.sql
pg_dump -U postgres -t equipment -D -a dcmms >> dcmms_merge.sql
pg_dump -U postgres -t material -D -a dcmms >> dcmms_merge.sql
pg_dump -U postgres -t staff -D -a dcmms >> dcmms_merge.sql
pg_dump -U postgres -t seal -D -a dcmms >> dcmms_merge.sql

Before merging the data into the second database, all data in the namespace of the first database have to be deleted. For example by using an SQL statement like the following:

select purgeWorkorder(ID) from Workorder where ID > 1000000

The dump file dcmms_merge.sql can be restored to the second database using the psql command:

psql -U postgres -f dcmms_merge.sql dcmms

If this procedure is repeated, the records that have been merged previously should be removed before merging again. This avoids PostgreSQL complaining of constraint violations (Uniqueness of primary keys).


2.3.3.4. Removing Temporary Files

Remove old files from c:\tmp and c:\tmp\ms_tmp.

[Caution] Caution

Be careful not to delete the c:\tmp\ms_tmp folder itself. If you delete the folder by accident, recreate it immediately.

The DCMMS installer schedules a task that runs the script c:\program files\dcmms\script\recreate_tmp.bat every day at 12:01.

The Schedule can be changed or deleted through the Windows Task Scheduler:

  • Select Start Menu->Control Panel.

  • Choose Performance and Maintenance from the list.

  • Click on Scheduled Task. The task will most probably be called at1.


2.3.3.5. Quality Control

All data related to the DCMMS business processes should be checked, at least with some samples.

The following list is a preliminary list of checks that should be performed:

  • The data entry quality should be checked by comparing the workorder sheets against the contents of the database.

  • The database information should be verified with the customers that filed the complaints.

  • The recorded diameter and material of pipes should be checked against the GIS water network data, if available.


2.3.4. Security

[Caution] Caution

A damaged DCMMS installation can be difficult to repair and may require a complete re-installation of the system. For this reason, a proper user privilege separation is of utmost importance.

The user operating the DCMMS application on the server must not have any administrator rights assigned.

The PostgreSQL administrator and the postgres accounts should be guarded by good passwords (not "password", "1234567quot; or "") and these password should only be known to the administrators.

[Caution] Caution

When changing the password of the Windows user "postgres", the administrator has to re-enter the postgres password in the properties of the PostgreSQL Database Server 8.1 service.


2.3.5. Database

Database administration can be performed e.g. using pgAdmin which is included in the PostgreSQL installation. The SQL language can be used to perform those tasks that are not directly accessible through the pgAdmin GUI.

See the PostgreSQL documentation for detailed information regarding the PostgreSQL database and SQL commands.

[Tip] Tip

Experienced ORACLE administrators that are used to work with sqlplus may prefer the psql commandline environment over pgAdmin.


2.4. Analysis

2.4.1. Repairs per PressurizedMain
2.4.2. Pressure Dependency

Advanced analysis possibilites.


2.4.1. Repairs per PressurizedMain

The script script/create_pressurizedmain_analysis.sql can be used to calculate the number of repairs for each pressurizedmain.

To remove the result fields and the nearest() function from the database, use the script script/delete_pressurizedmain_analyis.sql.


2.4.2. Pressure Dependency

The pressure dependency of leaks can be proofed by showing that the repair frequency is higher in areas with higher network pressure.

To simplify the analysis, the topographic elevation will be used as an indicator of the network pressure. It is assumed that the lower areas of a distribution zone show higher static pressures.

The analysis can be performed by overlaying the elevation distribution of reported leaks with the elevation distribution of network nodes. Histograms are a suitable way to visualize these distributions.

The assignment of elevations to network nodes and leak repair locations can be done e.g. from spot elevations with ArcView's Geoprocessing Wizard or from a Digital Terrain Model (DTM). You should discard those node elevation that are higher than the maximum leak repair elevation or lower than the lowest leak repair elevation.

Once the elevations have been assigned, the R statistical analysis package can be used for the analysis. R is available from http://www.r-project.org/.

[Note] Note

The following example assumes that the elevation information is stored in the elevation fields of the DBF files.

  1. In R, load the "foreign" package by selecting Package->Load Package... from the menu. This allows you to load DBF data.

  2. In the R Console, load your DBF files into the objects leak and maintenance:

    leak <- read.dbf("c:\\leak.dbf")
node <- read.dbf("c:\\node.dbf")

  3. The summary function can be used to check if the import was successful:

    summary(leak)

  4. Filtering of data is possible with the following command:

    filteredelevation <- node$Elevation[node$Elevation > 500 &
  node$Elevation > 1000]

  5. The following commands allow to overlay the histograms:

    hist(filteredelevation, col="yellow", main="", freq=FALSE,
  ylim=c(0, 0.03), xlab="Elevation in m", breaks=20)
hist(leak$Elevation, border="red", col="red", density=30, main="",
  add=TRUE, freq=FALSE, breaks=20)
legend(425,0.025,c("Maintenance Events", "Network Nodes"),
  merge=TRUE, fill=c("red", "yellow"), density=c(30, 100))

  6. The created image can be saved in various formats.

If the histogram shows that the distribution of the leak repairs is shifted to the left compared to the distribution of the network nodes, the leak distribution is most probably pressure-dependent.


2.5. Procedures

2.5.1. GIS Data Review

A collection of best practise procedures that help to administer DCMMS installations.


2.5.1. GIS Data Review

How GIS data is managed and reviewed in the case of NGWA.

NGWA's GIS data is kept in shapefile format, managed by the CVS version management system.

NGWA GIS Data Review

Figure 2.59. NGWA GIS Data Review

Figure 2.59, “NGWA GIS Data Review” outlines activities, roles and responsibilities of the GIS data review process. The process ensures that only quality-checked data is used in the DCMMS production system.

The DCMMS Manager has to check the lastest GIS data in the CVS using a DCMMS test installation. If necessary, the GIS operators have to correct errors (e.g. different field names used in a tiled set of shapefiles). Once the data has passed the quality control, the DCMMS has to mark the files in the CVS with the tag DCMMS.

[Important] Important

The DCMMS manager should update each shapefile used in the DCMMS indidually: Update the shapefile on the test machine, update the indexes, view it in the application. Updating of all files at the same time bears the risk of not being able to identify the file that causes the problem.

The DCMMS administrator is responsible for the CVS update script on the server. The script updates shapefile tilesets, shapefile indexes and the GIS data used in the DCMMS production system.

The following batch file illustrates the update on gisserver:

        e:
    cd sandbox\dcmms\ngwa
        cvs update -dP -C -r DCMMS
    tile4ms lot_line_index.txt lot_line_index
    tile4ms gravitymain_index.txt  gravitymain_index
    tile4ms pressurizedmain_index.txt pressurizedmain_index
    shptree ajlun\mapping\lot\lot_line.shp
    shptree ajlun\water\network\pressurizedmain.shp
    shptree ajlun\sewer\network\kufranja\gravitymain.shp
    shptree al_koura\mapping\lot\lot_line.shp
    shptree al_koura\water\network\pressurizedmain.shp
    shptree badia\mapping\lot\lot_line.shp
    shptree badia\water\network\pressurizedmain.shp
    shptree irbid\mapping\lot\lot_line.shp
    shptree irbid\water\network\pressurizedmain.shp
    shptree irbid\sewer\network\irbid\gravitymain.shp
    shptree irbid\sewer\network\dougrah\gravitymain.shp
    shptree jarash\mapping\lot\lot_line.shp
    shptree jarash\water\network\pressurizedmain.shp
    shptree jarash\sewer\network\gravitymain.shp
    shptree kinana\mapping\lot\lot_line.shp
    shptree kinana\water\network\pressurizedmain.shp
    shptree mafraq\mapping\lot\lot_line.shp
    shptree mafraq\water\network\pressurizedmain.shp
    shptree mafraq\sewer\network\mafraq\gravitymain.shp
    shptree ramtha\mapping\lot\lot_line.shp
    shptree ramtha\water\network\pressurizedmain.shp
    shptree ramtha\sewer\network\gravitymain.shp
    shptree shouna\mapping\lot\lot_line.shp
    shptree shouna\water\network\pressurizedmain.shp
    shptree ubaid\mapping\lot\lot_line.shp
    shptree ubaid\water\network\pressurizedmain.shp
    shptree ubaid\sewer\network\gravitymain.shp

The Windows Task Scheduler is used to run the update script every night.


2.6. Updating

2.6.1. From 1.1.2 to 2.0.4
2.6.2. From 1.1.2 to 2.0.0
2.6.3. From 1.1.1 to 1.1.2
2.6.4. From 1.1.0 to 1.1.1
2.6.5. From 1.0.5 to 1.1.0
2.6.6. From 1.0.4 to 1.0.5
2.6.7. From 1.0.3 to 1.0.4
2.6.8. From 1.0.1 to 1.0.3
2.6.9. From 1.0.1 to 1.0.2
2.6.10. From 1.0.0 to 1.0.1

New releases of DCMMS may use an updated data model. The following section describes two updating approaches.

If you are upgrading more than one minor number, please apply the individual updating instructions in the right sequence. However, if this includes multiple PostgreSQL or PostGIS updates, it should be sufficient to just perform the most current PostgreSQL and PostGIS updates.

[Tip] Tip

Whenever you're upgrading PostGIS or PostgreSQL, please also refer to the related upgrading information in the the PostGIS and PostgreSQL documentation respectively.

[Caution] Caution

Before every update of DCMMS, you should backup your data. See Section 2.3.3.1, “Backup” for the details.


2.6.1. From 1.1.2 to 2.0.4

Version 2.0.3 is a maintenance and bug fix, and additional added fuctionality release .

This release have many additions, especially in the reporting, and complaint information.

DCMMS 2.0.4 Installer Update

  • Run the DCMMS 2.0.4 installer. Select the "DCMMS" and "Update" components.

    • DCMMS 2.0.4 Manual Update

    If you are not using DCMMS on Windows or are having problems with the Installer update, please follow the procedure below:

  • Extract the DCMMS 2.0.4 distribution to c:\MS4W\apps\dcmms

  • Execute drop_views.sql, update_dcmms_ddl.sql and create_views.sql .


2.6.2. From 1.1.2 to 2.0.0

The 2.0.0 release marks a series of underlying technology changes. Use of PHP 5, MS4W and PostgreSQL 8.2 illustrates these changes.

Add the new monetary formatting option to dcmconfig.php. E.g.:

/**
 * Formatting options for monetary things. Used with the PostgreSQL to_char()
 * function.
 */
$_SESSION['strMonetaryFormat'] = '999999.99';

Add the new spatial referencing system identifier (SRID) to dcmconfig.php. E.g.:

/**
 * The spatial referencing system identifier (SRID) that should be used to for the spatial
 * data.
 */
$_SESSION['intSRID'] = 32636;

See the PostGIS documentation for more information on the spatial referencing system identifier.

Search plug-ins can now be used to provide additional search services such as zoom to a customer location (See Section 2.2.3.2, “Search Plug-Ins”).

Shapefile loader and dumper have been removed from the DCMMS application. You can used Gshp2pgsql and Gpgsql2shp instead.


2.6.3. From 1.1.1 to 1.1.2

Version 1.1.2 is a maintenance and bug fix release that does not add any additional functionality.

The workorder subtype descriptions are now translated using dcmmstranslation().

  • Run the DCMMS 1.1.2 installer. Select the "DCMMS" and "Update" components.

Procedure 2.1. DCMMS 1.1.2 Installer Update

If you are not using DCMMS on Windows or are having problems with the Installer update, please follow the procedure below:

  1. Extract the DCMMS 1.1.2 distribution to c:\Program Files\dcmms

  2. Execute drop_views.sql, update_dcmms_ddl.sql and create_views.sql as shown in Example 2.11, “Run update_dcmms_ddl.sql”.

Procedure 2.2. DCMMS 1.1.2 Manual Update


2.6.4. From 1.1.0 to 1.1.1

Version 1.1.1 is a maintenance and bug fix release that does not add any additional functionality.

  1. Install PostGIS 1.1.2 (Section 2.1.2.4, “PostGIS”).

  2. Run the DCMMS 1.1.1 installer. Select the "DCMMS" and "Update" components.

Procedure 2.3. DCMMS 1.1.1 Installer Update

If you are not using DCMMS on Windows or are having problems with the Installer update, please follow the procedure below:

  1. Update PostGIS to 1.1.2 (Don't forget to run lwpostgis_upgrade.sql on the dcmms database).

  2. Extract the DCMMS 1.1.1 distribution to c:\Program Files\dcmms

  3. Execute drop_views.sql, update_dcmms_ddl.sql and create_views.sql as shown in Example 2.11, “Run update_dcmms_ddl.sql”.

Procedure 2.4. DCMMS 1.1.1 Manual Update


2.6.5. From 1.0.5 to 1.1.0

As the status field was moved from the workorder table to the maintenance table, it it necessary to adjust the filter setting for the pending workorder layers in the map files from

filter "status = 1"
to
filter "1=(select status from maintenance where maintenance.id=workorder.id)"

Because PostgreSQL versions starting with 8.1.0 are not generating OID columns by default, it might be necessary to update your map files. See Section 2.8.8, “ERROR: column "oid" does not exist”.

Windows users should follow the steps below for an installer-based update:

  1. Backup the database (Example 2.6, “PostgreSQL 8.0 Backup”). Also backup other PostgreSQL databases you might be running on your system.

  2. Document users and groups that are relevant for DCMMS.

  3. Uninstall PostgreSQL 8.0 through the Control Panel.

  4. Delete the folder c:\program files\postgresql.

  5. Delete the Windows user "postgres", e.g. with the following command:

    net user postgres /delete

  6. Reboot the system.

  7. Install PostgreSQL 8.1.3 (Section 2.1.2.3, “PostgreSQL”).

  8. Install PostGIS 1.1.1 (Section 2.1.2.4, “PostGIS”).

  9. Recreate users and groups. When creating the login roles, make sure to activate the option "Inherit rights from parent roles"

  10. Run the DCMMS 1.1.0 installer. Select the "Create Database" and "PostArabic" components.

  11. Use ActivePerl (Section 2.1.6.1, “Active Perl”) to restore the database (Example 2.7, “PostgreSQL 8.1 Restore”).

  12. Run the DCMMS 1.1.0 installer. Select the "DCMMS" and "Update" components.

Procedure 2.5. DCMMS 1.1.0 Installer Update

Example 2.6. PostgreSQL 8.0 Backup

set PGUSER=postgres
set PGPASSWORD=password
set PGCLIENTENCODING=WINDOWS-1256
set PGPATH=c:\program files\postgresql\8.0
PATH=%PATH%;c:\program files\postgresql\8.0\bin
pg_dump -Fc dcmms > dcmms.dump

Example 2.7. PostgreSQL 8.1 Restore

set PGUSER=postgres
set PGPASSWORD=password
set PGCLIENTENCODING=WINDOWS-1256
set PGPATH=c:\program files\postgresql\8.1
PATH=%PATH%;c:\program files\postgresql\8.1\bin
dropdb dcmms
"%PGPATH%\share\contrib\postgis\postgis_restore.pl" \
"%PGPATH%\share\contrib\lwpostgis.sql" \
dcmms dcmms.dump "-E UNICODE" > restore.log

If you are not using DCMMS on Windows or are having problems with the Installer update, please follow the procedure below:

  1. Install PHP 4.4.2.

  2. Install PEAR Date 1.4.6.

  3. Backup the database (Example 2.6, “PostgreSQL 8.0 Backup”).

  4. Update PostgreSQL to 8.1.3.

  5. Update PostGIS to 1.1.1.

  6. Install PostArabic 1.0.0.

  7. Using Perl (Section 2.1.6.1, “Active Perl”, restore the database as shown in Example 2.7, “PostgreSQL 8.1 Restore”.

  8. Extract the DCMMS 1.1.0 distribution to c:\Program Files\dcmms

  9. Execute drop_views.sql, update_dcmms_ddl.sql and create_views.sql as shown in Example 2.11, “Run update_dcmms_ddl.sql”.

  10. Update PHP/Mapscript to version 4.6.1

  11. Change the PostgreSQL binary location in include/dcmconfig.php: Replace C:\Program Files\PostgreSQL\8.0\bin\ with C:\Program Files\PostgreSQL\8.1\bin\.

Procedure 2.6. DCMMS 1.1.0 Manual Update


2.6.6. From 1.0.4 to 1.0.5

Version 1.0.5 is a bug fix and maintenance release that brings several improvements to the DCMMS application.

[Caution] Caution

As mapserver 4.6.0 supports hatching, you should change the definition of the AreaOfInterest class in your map files. The old definition is shown in Example 2.8, “Old AreaOfInterest Class” and the new one is shown in Example 2.8, “Old AreaOfInterest Class”.

Example 2.8. Old AreaOfInterest Class

CLASS
  NAME 'AreaOfInterest'
  SYMBOL "circle"
  SIZE 1
  COLOR 255 255 0
  OUTLINECOLOR 255 255 0
END

Example 2.9. New AreaOfInterest Class

CLASS
  NAME 'AreaOfInterest'
  STYLE
  SYMBOL "aoihatch"
    SIZE 10
    WIDTH 2
    ANGLE 45
    COLOR 255 255 0
    OUTLINECOLOR 255 255 0
  END
END
[Caution] Caution

Make sure that you change your field names from arlocation to arname and enlocation to name. Likewise, ardescript should become arname and endescript should become name.

Note that the new translation system is more flexible. The name field does not necessarily have to contain English values.

See Section 1.4.4, “Translation System” for more information on the new translation system.

[Caution] Caution

The format of the IdentifyPlugin configuration file (conf\identifyplugin.ini) has changed. See Section 2.2.3.1, “Identify Plug-Ins” and conf\identifyplugin.ini.default for the details.

Windows users should follow these steps using the DCMMS installer:

  1. Install DCMMS Scripting 4.4.0.

  2. Upgrade PostgreSQL to 8.0.3 (Run upgrade.bat from the PostgreSQL distribution. The file is also available in the setup folder of the DCMMS CD).

  3. Install PostGIS 1.0.3 (See Section 2.1.2.4, “PostGIS”).

  4. Use ActivePerl (Section 2.1.6.1, “Active Perl”) to update PostGIS to 1.0.3 as shown in Example 2.10, “PostGIS 1.0.3 Update”.

  5. Run the DCMMS 1.0.5 installer.

  6. Use the "DCMMS" and "Update" components in the DCMMS setup.

  7. Make sure that error_reporting is configured correctly in c:\windows\php.ini:

    error_reporting  = E_ALL & ~E_NOTICE

Procedure 2.7. DCMMS 1.0.5 Installer Update

Example 2.10. PostGIS 1.0.3 Update

set PGUSER=postgres
set PGPASSWORD=password
set PGCLIENTENCODING=WINDOWS-1256
set PGPATH=c:\program files\postgresql\8.0
PATH=%PATH%;c:\program files\postgresql\8.0\bin
pg_dump -Fc dcmms > dcmms.dump
dropdb dcmms
"%PGPATH%\share\contrib\postgis\postgis_restore.pl" \
"%PGPATH%\share\contrib\lwpostgis.sql" \
dcmms dcmms.dump "-E UNICODE" > restore.log

If you are not using DCMMS on Windows or are having problems with the Installer update, please follow the procedure below:

  1. Install PHP 4.4.0.

  2. Install PEAR Date 1.4.3.

  3. Install PEAR DB 1.7.6.

  4. Install PEAR DB_DataObject 1.7.14.

  5. Install PEAR DB_DataObjectFormBuilder 0.15.0.

  6. Install PEAR HTML_Common 1.2.1.

  7. Install PEAR HTML_QuickForm 3.2.4pl1.

  8. Install PEAR HTML_QuickForm_Controller 1.0.4.

  9. Install PEAR HTML_QuickForm_SelectFilter 1.0.0RC1.

  10. Install PEAR Image_Color 1.0.1.

  11. Install PEAR Image_Graph 0.4.0.

  12. Install PEAR HTML_Table 1.5.

  13. Install PEAR Pager 2.3.0.

  14. Install PEAR Validate 0.4.1.

  15. Update PostgreSQL to 8.0.3.

  16. Install PostGIS 1.0.3.

  17. Using Perl, update PostGIS to 1.0.3 as shown in Example 2.10, “PostGIS 1.0.3 Update”.

  18. Extract the DCMMS 1.0.5 distribution to c:\Program Files\dcmms

  19. Execute drop_views.sql, update_dcmms_ddl.sql and create_views.sql as shown in Example 2.11, “Run update_dcmms_ddl.sql”.

  20. Update PHP/Mapscript to version 4.6.0

  21. Replace "php_mapscript_44.dll" with "php_mapscript_46.dll" in c:\windows\php.ini.

  22. Make sure that the Translation table has the primary key constraint.

    If it is missing, create it with the following statement;

    ALTER TABLE translation ADD CONSTRAINT translation_pkey
  PRIMARY KEY("language", term);

  23. Confirm that allow_call_time_pass_reference is set to "On" in c:\windows\php.ini.

  24. Make sure that error_reporting is configured correctly in c:\windows\php.ini:

    error_reporting  = E_ALL & ~E_NOTICE

  25. Compare conf\dataobject.ini and conf\dataobject.ini.default. Update conf\dataobject.ini if necessary.

Procedure 2.8. DCMMS 1.0.5 Manual Update

Example 2.11. Run update_dcmms_ddl.sql

psql -U postgres -h localhost -f drop_views.sql dcmms
psql -U postgres -E UNICODE -h localhost -f update_dcmms_ddl.sql dcmms
psql -U postgres -h localhost -f create_views.sql
[Tip] Tip

One of the new features in 1.0.5 is the visual identification of duplicate workorders. You should add a new layer to show the area of interest for the pending workorders. This allows the visual identification of duplicate complaints. E.g. add the following to your map files before the first layer:

# PendingWorkorders
LAYER
  CONNECTIONTYPE postgis
  NAME PendingWorkorders
  maxscale 15000
  TYPE POLYGON
  STATUS DEFAULT
  CONNECTION "dbname=dcmms user=dummy password=dummy host=localhost"
  DATA "areaofinterest from workorder using unique oid using SRID=-1"
  filter "status = 1"
  CLASS
    NAME 'PendingWorkorders'
    STYLE
      SYMBOL "aoihatch"
      SIZE 8
      WIDTH 1
      ANGLE 315
      COLOR 255 150 150
      OUTLINECOLOR 255 150 150
    END
  END
  TOLERANCE 15
END # Layer

If you are not using a custom symbol file (not etc/symbols.sym), you should add the following symbol definition to it:

SYMBOL
  NAME 'aoihatch'
  TYPE HATCH
END
[Note] Note

There may be error messages caused by the update_dcmms_ddl.sql script that can be savely ignored. If you cannot judge yourself if the error message should be ignored, please file a support request including the suspicious error messages.

[Note] Note

When upgrading PostgreSQL, make sure that your postgresql.conf customizations are preserved (See Section 2.1.5, “Checklist”).

[Note] Note

Note that the introduction of the History table requires to update batch files used in the merging process (See Section 2.3.3.3, “Merge DCMMS Databases”).


2.6.7. From 1.0.3 to 1.0.4

Version 1.0.4 is a bug fix and maintenance release that brings several improvements to the DCMMS application.

See the "Upgrading" section in the PostGIS Manual for information how to upgrade to the latest PostGIS version.

You can use ActivePerl to run postgis_restore.pl. For example:

set PGUSER=postgres
set PGPASSWORD=password
set PGCLIENTENCODING=WINDOWS-1256
set PGPATH=c:\program files\postgresql\8.0
PATH=%PATH%;c:\program files\postgresql\8.0\bin
pg_dump -Fc dcmms > dcmms.dump
dropdb dcmms
postgis_restore.pl "%PGPATH%\share\contrib\lwpostgis.sql" \
dcmms dcmms.dump > restore.log

There are several changes to the data model, see script/update_dcmms_ddl.sql for the details.

The new streamlined GIS data translation system requires one map file per language. Existing map files and include/dcmconfig.php have to be adjusted manually. See the default configuration files for an example how the new system works.

The IdentifyPlugin configuration file is new and has to be adjusted where necessary (Section 2.2.3.1, “Identify Plug-Ins”).

User looking for improved performance should use PostGIS 1.0.0 or better with the definitions in lwpostgis.sql file. As of PostgreSQL 8.0.2, this is not part of the PostgreSQL installer, but a separate installer is available from the internet. Note that there's a known bug with the shapefile loader in PostGIS 1.0.0. The DCMMS installer will use lwpostgis.sql instead of postgis.sql when it is found.


2.6.8. From 1.0.1 to 1.0.3

Version 1.0.3 is a bug-fix release that fixes a problem in the update_dcmms_ddl.sql (See bug #1098354 for the details). In addition it provides some documentation how the Cygwin-based PostgreSQL database can be migrated to the native Windows version.

There are two upgrade options from the Cygwin PostgreSQL version to the native Windows one: You can edit an SQL dump file of the database or you can dump only the contents of selected tables. While the first option might be quicker, the second one ensures that you also update to the latest PostGIS version. Following are some hints:

  • Dump your Cygwin PostgreSQL database as a SQL file. Make sure that all references to the fuzzystrmatch module are like the following: '$libdir/fuzzystrmatch'. All references to PostGIS should look like the following: '$libdir/libpostgis.dll'. All references to PostArabic should look like the following: '$libdir/libarabic.dll'.

    The edits can be performed e.g. using sed.

  • Create the database structure from scratch e.g. using create_dcmms_ddl.sql. Dump only those tables you want to transfer. The dump procedure described in Section 2.3.3.3, “Merge DCMMS Databases” gives a good example how you can do this. AdministrativeArea, Village and Landmark should be loaded via the shapefile loader.


2.6.9. From 1.0.1 to 1.0.2

For the Windows installation of DCMMS the most notable change in version 1.0.2 is the use of the native Windows PostgreSQL version 8.0. The Windows release of PostgreSQL includes an updated version of pgAdmin III featuring backup and restore functions. For this reason, the backup and restore functionality has been removed from the DCMMS interface.

When updating to version 1.0.2, make sure that all PostGIS layers in your mapfiles have a dummy user and password entry in the connection line like in Example 2.1, “PostGIS Connection Example”. The password entry was previously omitted.

Make sure that you update your dcmconfig.php as some functions might not work otherwise.


2.6.10. From 1.0.0 to 1.0.1

Please follow the steps below to update a Windows installation of DCMMS from version 1.0.0 to 1.0.1.

  • Remove Apache and install the latest version. This is optional.

  • Uninstall DCMMS Scripting by running c:\program files\php\uninstall-dcmms-scripting-4.3.5-2.exe.

  • Install the new DCMMS Scripting version.

  • Install the new DCMMS version. The following components should be selected in the DCMMS installer:

    • DCMMS

    • Mapserver

    • Apache/PHP Config

    • Scheduled Cleanup

    • Update

  • Restart Apache or reboot the system.

[Caution] Caution

When you are upgrading from DCMMS 1.0.0 to 1.0.1 and the logon.php page is empty, make sure that you've installed the PEAR module "Log".


2.7. Frequently Asked Questions

2.7.1. There are too many coded values. How can I remove them?
2.7.2. How to add e.g. a new material?
2.7.3. How can I distinguish between Arabic and English texts in an SQL query?


2.7.1. There are too many coded values. How can I remove them?

The coded values in the standard DCMMS installation cover the needs of all DCMMS users. If your installation does not need some of those values, simply remove them from the respective tables in the database. You can use pgAdmin for this.

[Caution] Caution

When removing coded values, make sure that these have not been used during the data entry. Migrate those critical values to others first.


2.7.2. How to add e.g. a new material?

Materials in DCMMS are simple records in the MaterialDomain table of the dcmms database. Adding a material is as simple as adding a new record. See Section 2.2.4, “Database Side Customization” for the details.


2.7.3. How can I distinguish between Arabic and English texts in an SQL query?

The following query snippet can be used to identify Arabic texts:

where ascii(text) > 200


2.8. Troubleshooting

2.8.1. DCMMS Info Mailing List
2.8.2. Support Tracker
2.8.3. Complete Uninstallation
2.8.4. Problems with Transparent Symbols
2.8.5. Shapefile Loading problems
2.8.6. Configuration error: PHP time != PostgreSQL time
2.8.7. Permission Denied for Relation CauseDomain
2.8.8. ERROR: column "oid" does not exist
2.8.9. New Landmarks Disappear
2.8.10. PostgreSQL Update
2.8.11. PostgreSQL Database Server Service
2.8.11.1. PostgreSQL Database Server Service Fails to Start
2.8.12. FATAL ERROR: PHP extension 'MapScript' is not loaded
2.8.13. Map Display
2.8.14. Restore
2.8.15. Unable to Load Dynamic Library
2.8.16. Header already sent error
2.8.17. Log Files
2.8.18. MapLab
2.8.19. Htdig
2.8.20. Cygwin PostgreSQL Upgrade

This section gives help to solve problems with the DCMMS installation.


2.8.1. DCMMS Info Mailing List

The dcmms-info mailing list may provide help to solve problems, either through the archives which are available under http://sourceforge.net/mailarchive/forum.php?forum_id=32901. or by sending an email to <dcmms-info@lists.sourceforge.net>.

See also Section 1.4.5, “Mailing Lists”.


2.8.2. Support Tracker

The bug and support trackers are available through the DCMMS website, http://dcmms.sourceforge.net .

[Caution] Caution

Please make sure that you look at all bug reports and support requests, not only the open ones. Eventually, a similar problem has occurred before and the support request is already closed.


2.8.3. Complete Uninstallation

The uninstallation steps described below will completely remove DCMMS and all of its components.

[Warning] Warning

Make sure that you have backed up your DCMMS data.

  1. Uninstall Apache through the Control Panel.

  2. Uninstall PostgreSQL through the Control Panel.

  3. Uninstall PostGIS through the Control Panel.

  4. Uninstall DCMMS through the Control Panel.

  5. Uninstall DCMMS Scripting through the Control Panel.

  6. Uninstall DCMMS Sample through the Control Panel.

  7. Delete c:\program files\postgresql.

  8. Delete c:\program files\dcmms.

  9. Delete c:\windows\php.

  10. Delete c:\windows\pear.

  11. Delete c:\windows\php.ini.

  12. Delete c:\tmp

  13. Verify that the Scheduled Task "at1" was removed. Delete if necessary.

  14. Delete the Windows user "postgres", e.g. with the following command:

    net user postgres /delete

  15. Verify that the DCMMS folder was removed from the Start Menu.

  16. Reboot.


2.8.4. Problems with Transparent Symbols

If symbols like the hatching of in the area of interest symbol do not show transparent parts as expected, make sure that you use the following configuration line in the LAYER definition of your mapfiles:

TRANSPARENCY ALPHA

This applies especially when overlaying raster data with partially transparent symbols.


2.8.5. Shapefile Loading problems

When encountering problems after loading shapefiles, use the DCMMS data model to double check that the required fields of all tables are in place.


2.8.6. Configuration error: PHP time != PostgreSQL time

The PostgreSQL timezone needs to be changed if DCMMS reports the error "Configuration error: PHP time != PostgreSQL time".

pgAdmin can be used to edit postgresql.conf: Select Tools->Server configuration->postgresql.conf from the menu.

Change the timezone value to e.g. GMT-2

Save the configuration: Select File->Save from the menu.

Reload the server configuration: Select File->Reload server from the menu.

Restart the PostgreSQL service.

[Note] Note

You can check the timezone setting by the following SQL statement:

select now()

This time needs to equal the system time (as displayed e.g. in the task bar).

[Note] Note

The error message on the logon page contains the correct timezone setting.

[Important] Important

Timezone names in Windows and PostgreSQL are different. If your Windows timezone is GMT-3, you'll have to use the PostgreSQL timezone setting GMT+3.


2.8.7. Permission Denied for Relation CauseDomain

When running PostgreSQL 8.1 and creating login roles using pgAdmin, make sure to check the option "Inherits rights from parent roles". Otherwise the following error messages might occurr when logging on:

Warning: pg_query(): Query failed: ERROR: permission denied for relation causedomain in C:\dcmms\index.php on line 62

Warning: Your data model might be outdated. Please contact your administrator.


2.8.8. ERROR: column "oid" does not exist

Starting with version 8.1.0, PostgreSQL is not creating the OID column by default any more.

Map files used with DCMMS up to version 1.0.5 may have implicitly used the OID column.

To fix the problem locate the layer with the problem. The layer name is mentioned in the error message. For example: Failed to draw layer named 'Landmark'.

Locate the layer in the map file. For example:

DATA "the_geom from landmarkview using SRID=-1"

Add the missing "using unique" statement. For the above example:

DATA "the_geom from landmarkview using unique id using SRID=-1"

Repeat this for all problematic layers


2.8.9. New Landmarks Disappear

If newly inserted landmarks do not show up in the selection list, most probably they have been digitized outside of the Village or AdministrativeArea boundaries. See Section 2.3.1, “GIS Data Loading” for further information on quality control of Village and AdministrativeArea.


2.8.10. PostgreSQL Update

When upgrading a PostgreSQL installation using upgrade.bat, the PostGIS version might be downgraded if PostGIS was first installed through the PostgreSQL installer and later upgraded using the stand-alone installer.

Fix this by installing the latest PostGIS installation again.


2.8.11. PostgreSQL Database Server Service

2.8.11.1. PostgreSQL Database Server Service Fails to Start

If the application fails to connect to the database, check that the "PostgreSQL Database Server" service is up and running on the server. The Windows Services control panel can be reached for example by right-mouse clicking on the Apache Monitor symbol in the taskbar and selecting Open Services from the context menu.

[Tip] Tip

If you're running a firewall, make sure that the firewall is not blocking the connection from PHP to PostgreSQL.


2.8.11.1. PostgreSQL Database Server Service Fails to Start

[Tip] Tip

Try to reboot the machine. Alternatively, log on as administrator and restart the service. The most common startup problem is a leftover postmaster.pid file.

If the PostgreSQL Database Server service fails to start, the Windows event log might provide useful information.

[Caution] Caution

If the PostgreSQL service fails to start make sure that there is no file named c:\program.


2.8.12. FATAL ERROR: PHP extension 'MapScript' is not loaded

Make sure that PHP mapscript is configured as an extension in php.ini.

Make sure that php_mapscript_46.dll exists c:\windows\php\extensions.

Copy php_mapscript_46.dll to c:\windows\php and use depends.exe to verify that all DLL dependencies are fullfilled. depends.exe is available e.g. with the Windows XP Service Pack 2 Support Tools.


2.8.13. Map Display

If map labels are not displayed properly (e.g. garbage diameters) and you're using tiled shapefiles, check that all your shapefiles have exactly the same table definition. Field name, type and order have to be exactly the same in all your shapefile tiles.


2.8.14. Restore

Suppose you have problems restoring a DCMMS database and you are getting the following error message: psql:dcmms-jerash-2004-01-19.sql.lib:34: ERROR: could not load library "/usr/lib/postgis.dll": dlopen: Win32 error 127

Edit your sql file and replace all occurrences of /usr/lib/postgis.dll with $libdir/postgis.dll.

If there are error messages like ERROR: function geometryfromtext(text, integer) does not exist., the text to geometry cast might be missing. It can be recreated with the following SQL command

create cast (text as geometry)
  with function geometry(text) as implicit;

[Warning] Warning

The better way to fix this problem is to use the PostGIS postgis_restore.pl script.


2.8.15. Unable to Load Dynamic Library

When trying to open a page, the following message appears on the server: Unknown(): Unable to load dynamic 'C:/Program Files/PHP/extensions\php_gettext.dll' - The specified module could not be found.

The following points may help to solve the problem:

  • Make sure that you've installed the zip distribution of PHP and not the installer version

  • Copy the file libintl-1.dll from c:\program files\php\dlls to c:\winnt\system32 or c:\windows\system32.

    This also applies to iconv.dll - in this case, copy iconv.dll to c:\windows\system32 or c:\winnt\system32.

    The dll files can be found in the folder dlls of the PHP distribution

See also Section 2.8.12, “FATAL ERROR: PHP extension 'MapScript' is not loaded”.


2.8.16. Header already sent error

If you have a PHP error displayed on the page "Warning: Cannot modify header information - headers already sent by ". The solution of this error is changing the output_buffering variable to <B> on </B>.


2.8.17. Log Files

Apache, PostgreSQL, PHP and some of the installers write log files that are often helpful when troubleshooting.

The level of verbosity of the server logs can often be specified in the server configuration files.

The following locations might contain important log files:

  • %TEMP% - log files of the DCMMS installer scripts

  • c:\program files\PostgreSQL\8.1\data\pg_log - folder with log file of the PostgreSQL server.

  • The windows system log files.


2.8.18. MapLab

DCMMS requires a long maximum execution time for PHP scripts, MapLab requires a short one (30 seconds).

In order to ovecome this problem, it may be required to use two different php.ini files.

As MapLab is using the .phtml extension for the PHP files, this is possible with the following directive in httpd.conf:

SetEnvIf Request_URI "\.phtml" PHPRC=c:/

Note that this directive has to be inserted after the SetEnvIf module is loaded.


2.8.19. Htdig

Make sure that the DCMMS application is not indexed by htdig. This will lead to an endless loop and slow down your system.

The htdig package offers as search engine for websites. Please check wether you're running htdig before investigating further.


2.8.20. Cygwin PostgreSQL Upgrade

When upgrading from the Cygwin PostgreSQL version to the native Windows version, it could happen that some fields are too short while restoring because UNIX newlines (1 character) are converted to Windows newlines (2 characters). In this case, the dcmms.dump.ascii file generated by postgis_restore can be edited to adjust the field definitions.

Note that dcmms.dump.ascii has the same encoding as the database (probably UTF-8).

[Note] Note

This refers to rather old DCMMS versions.


Chapter 3. Administrator Certification

Table of Contents

3.1. 2006 Certification Questions
3.1.1. Security
3.1.2. Engineering
3.1.3. Customization
3.1.4. Technology
3.1.5. Windows
3.1.6. PostgreSQL
3.1.7. Administration
3.1.8. Mapserver
3.1.9. PHP
3.1.10. GIS
3.1.11. Plug-Ins
3.1.12. Community

The stability of a DCMMS installation largely depends on sound administration practises. The following questions shall help DCMMS administrators to verify their understanding

Security relevant questions count triple.

Contact the DCMMS developers on <dcmms-devel@lists.sourceforge.net> if you wish to become a certified DCMMS administrator.

It is recommended to renew the certification every two years.


3.1. 2006 Certification Questions

3.1.1. Security
3.1.2. Engineering
3.1.3. Customization
3.1.4. Technology
3.1.5. Windows
3.1.6. PostgreSQL
3.1.7. Administration
3.1.8. Mapserver
3.1.9. PHP
3.1.10. GIS
3.1.11. Plug-Ins
3.1.12. Community


3.1.1. Security

  1. Give an example of a strong password (Note that you should never use this particular password because it is revealed in this certification!):

    ...

  2. Give an example of a weak password (Note that you should never use this particular password because it is revealed in this certification!):

    ...

  3. Why are strong passwords important?

    ...

  4. Summarize your firewall setup. How does this setup improve security?

  5. Imagine a decicated DCMMS server with only one Windows account used by the administrator. What is more important to secure the system?

    a) Antivirus updates

    b) Windows updates

  6. Imagine a standard DCMMS installation being accessed over an unsecured WLAN connection. What can be done in order to improve security?

    ...


3.1.2. Engineering

  7. Why does the Maintenance table contain the Diameter1 and Diameter2 fields? Is one diameter field not sufficient?

    ...

  8. What is the difference between Diameter1 and Diameter2?

    ...

  9. What is the difference between the simple "maintenance density" and "per-pipe maintenance density"?

    ...


3.1.3. Customization

  10. How can a new pipe material be added to the DCMMS?

    ...

  11. When changing the symbol configuration what should you do in order bo be compatible with future DCMMS releases?

    ...

  12. Why is it a bad idea to use a customized conf/sample_en.map on a production system?

    ...

  13. When changing the font configuration, what is necessary to allow seamless upgarding the DCMMS installer?

    ...


3.1.4. Technology

  14. A DCMMS server with the start URL http://www.dcmms.org/dcmms/logon.php has been changed to use port 81. What is the new start URL?

    ...

  15. What are the different components of the URL https://www.dcmms.org:441/dcmms/logon.php?

    ...

  16. What is the default port for the HTTP protocol?

    ...

  17. What is the default port for the HTTPS protocol?

    ...

  18. What is the difference between the HTTP and HTTPS protocols?

    ...

  19. What is your preferred backup media?

    ...

  20. What is a mailing list?

    ...


3.1.5. Windows

  21. Which tool can be used to track down DLL problems?

    ...

  22. Which tools can be used to identify the program that occupies a port?

    ...

  23. Which tool can be used to copy a Truetype font from c:\windows\fonts to a different directory?

    ...

  24. What is the suffix for TrueType fonts?

    ...

  25. Which filesystem should be used?

    ...

  26. Which filesystem should not be used?

    ...


3.1.6. PostgreSQL

  27. There are different PostgreSQL tools. Which one do you use for database administration tasks?

    ...

  28. In which file do you adjust the PostgreSQL timezone setting?

    ...

  29. Which are the two PostgreSQL backup formats that are relevant for DCMMS?

    ...

  30. How do you restore a DCMMS database that has been backed up using pgAdmin (A database dcmms already exists on the system) ?

    ...

  31. Which SQL snippet can be used to distinguish Arabic texts from English texts?

    ...

  32. What is the default port used by PostgreSQL

    ...

  33. You are confronted with a PostgreSQL database where you do not know the password of the PostgreSQL postgres account. How do you work around this problem?

    ...


3.1.7. Administration

  34. Which email address should you use to obtain DCMMS support?

    ...

  35. What is the URL of the DCMMS support tracker?

    ...

  36. Which files should be backed up besides the DCMMS database?

    ...

  37. Please provide the link to one of your posts to the dcmms-info mailing list:

    ...

  38. Please provide the link to an RFE you have posted:

    ...

  39. How do you contact the developers if there is a bug in the application?

    ...

  40. Why should you address questions to the dcmms-info mailing list and not just to an individual developer?

    ...

  41. Which mailing lists which you have subscribed in order to get notified of DCMMS component updates?

    ...

  42. Which programming languages have been used to write DCMMS?

    ...


3.1.8. Mapserver

  43. Which configuration files contain information about the keymap?

    ...

  44. What is the name of your keymap image file?

    ...

  45. How can you improve performance of raster data?

    ...

  46. How can you improve performance of vector data?

    ...

  47. Which mapserver mechanism can be used if different parts of your organisation work on shapefiles in parallel (e.g. water in different regional operating units)?

    ...

  48. What is the equivalent of an Mapserver *.map file in ArcMap?

    ...


3.1.9. PHP

  49. How can you find out which PHP version is installed?

    ...


3.1.10. GIS

  50. What different tools do you know to load shapefiles to PostGIS?

    ...

  51. Which OGC standard is implemented by PostGIS?


3.1.11. Plug-Ins

  52. Which plug-ins are available out-of-the-box with DCMMS?

    ...

  53. Which plug-ins do you have configured on your production system?

    ...

  54. Why does DCMMS support plug-ins?

    ...

  55. What different DCMMS plug-in types do you know?

    ...


3.1.12. Community

  56. Please provide a list of users (email addresses) that you have encouraged to join the dcmms-user mailing list:

    ...

  57. What are your contributions to the DCMMS user community?

    ...


Index

A

add material, How to add e.g. a new material?
administration, Administration
AdministrativeArea, AdministrativeArea, Village and Landmark
analysis, Analysis
per pipe, Repairs per PressurizedMain
pressure dependency, Pressure Dependency
Apache, Apache
Arabic, How can I distinguish between Arabic and English texts in an SQL query?
ArcView, Customer Search Plug-In, GIS Data Loading
AV PostGIS Connection Extension, GIS Data Loading

B

backup, Backup

C

certification, Administrator Certification
checklist, Checklist
coded value, Database Side Customization
concepts, Concepts
configuration, Configuration Files, Configuration error: PHP time != PostgreSQL time
identify plug-in, Identify Plug-Ins
search plug-in, Search Plug-Ins
configuration files, Folder Structure
contact, Troubleshooting
customer search plug-in, Customer Search Plug-In
customization
database side, Database Side Customization
Cygwin, Cygwin PostgreSQL Upgrade

D

data
model, AdministrativeArea, Village and Landmark
preparation, AdministrativeArea, Village and Landmark
data loading, GIS Data Loading
data model
outdated, Permission Denied for Relation CauseDomain
database, Database
merge, Merge DCMMS Databases
dcmconfig.php, Configuration Files
DCMMS 2.0.0, DCMMS 2.0.4 MS4W base installation
dcmms-info, DCMMS Info Mailing List
depends.exe, FATAL ERROR: PHP extension 'MapScript' is not loaded
deployment, Deployment
DLL, Unable to Load Dynamic Library

E

email, Introduction, Troubleshooting
error, Configuration error: PHP time != PostgreSQL time
extend, Plug-Ins
extension
mapscript, FATAL ERROR: PHP extension 'MapScript' is not loaded

F

FAQ, Frequently Asked Questions
files
create_views.sql, Shapefile Loading
drop_views.sql, Shapefile Loading
postgresql.conf, Configuration error: PHP time != PostgreSQL time
temporary, Removing Temporary Files
find tool, Search Plug-Ins
firewall, Checklist
folder structure, Folder Structure
format
monetary, From 1.1.2 to 2.0.0
Frequently Asked Questions, Frequently Asked Questions

G

gettext, Gettext
GIS
data, GIS Data Loading
GIX, GIX, Custom Map
guest account, Checklist

H

htdig, Htdig

I

identify tool, Identify Plug-Ins
identifyplugin.ini, Identify Plug-Ins
image identify plug-in, Image Identify Plug-In
installation, Installation
Windows, DCMMS 2.0.0 and next versions Windows installation, DCMMS 1.1.2 and previous versions Windows Installation
Internationalization, Translation System
introduction, Introduction

K

keyword, Search Plug-Ins

L

Landmark, AdministrativeArea, Village and Landmark
landmark
disappears, New Landmarks Disappear
loading, Shapefile Loading, Shapefile Loading problems
data, GIS Data Loading, Unit Cost Data Loading
Localization, Translation System
log files, Log Files
lookup table, Database Side Customization

M

mailing list, Mailing Lists, DCMMS Info Mailing List
dcmms-devel, Database Side Customization, Administrator Certification
dcmms-info, DCMMS Info Mailing List
map display, Map Display
map file, Map File Localization
MapLab, MapLab
MapScript, FATAL ERROR: PHP extension 'MapScript' is not loaded
merge, Merge DCMMS Databases
MS4W, DCMMS 2.0.4 MS4W base installation

N

netstat, Apache
new material, How to add e.g. a new material?

O

oid, ERROR: column "oid" does not exist
ORACLE, Customer Search Plug-In
overview, Tiled Images

P

passwords, Checklist
performance, Tiled Images
permission denied, Permission Denied for Relation CauseDomain
pgAdmin, Database
PHP header, Header already sent error
php.ini, Configuration Files
php_mapscript_46.dll, FATAL ERROR: PHP extension 'MapScript' is not loaded
plug-in, Plug-Ins
customer search, Customer Search Plug-In
identify, Identify Plug-Ins
image identify, Image Identify Plug-In
search, Search Plug-Ins
port, Apache
PostgreSQL
connection problem, PostgreSQL Database Server Service
startup failure, PostgreSQL Database Server Service Fails to Start
upgrade, PostgreSQL Update
postgresql.conf, Checklist, Configuration error: PHP time != PostgreSQL time
pressure
dependency, Pressure Dependency
procedures, Procedures
psql, Database

Q

quality, Quality Control
query snippet, How can I distinguish between Arabic and English texts in an SQL query?

R

raster data, Tiled Images, Problems with Transparent Symbols
requirements, Requirements
administrator, Administrator
PostGIS, PostGIS
software, Hardware, Software
restore, Restore, Restore

S

scheduled cleanup, Removing Temporary Files
search, Search Plug-Ins
security, Checklist, Security
shapefile loading, Shapefile Loading, Shapefile Loading problems
shp2pgsql, shp2pgsql
spatial_ref_sys, Configuration Files
SQL, Customer Search Plug-In, How can I distinguish between Arabic and English texts in an SQL query?
SRID, Configuration Files, From 1.1.2 to 2.0.0
support, Troubleshooting
mailing list, Mailing Lists, DCMMS Info Mailing List

T

tasklist, Apache
temporary files, Removing Temporary Files
tiles, Tiled Images
timezone, Checklist, Configuration error: PHP time != PostgreSQL time
training, Administrator Certification
translation, Database Side Customization
translation system, Translation System
transparency, Problems with Transparent Symbols
troubleshooting, Troubleshooting
oid, ERROR: column "oid" does not exist

U

unit cost
loading, Unit Cost Data Loading
update, Updating
user
PostgreSQL, PostgreSQL users
Windows, Windows Users

V

valve, Valve Symbols
Village, AdministrativeArea, Village and Landmark

W

WMS, Configuration Files