DCMMS Administration Guide

	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 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.

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.1.1 or higher.

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 1.5.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.

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.

The shapefile loader (Section 3.1.1, “Shapefile Loader”) allows to update the translation table from fields like enname (English), arname (Arabic), etc.

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

dcmmstranslation('en', name)

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

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, “Custom Map”

	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
	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 10. Apache Wizard

Figure 11. Apache License

Figure 12. Apache Readme

Figure 13. Apache Information

Figure 14. Apache Setup Type

Figure 15. Apache Location

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

Figure 16. Apache Install

	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.

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 17. PHP License

Figure 18. PHP Components

	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 19. PHP Location

This section describes how to install PostgreSQL for Windows.

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

	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.

Figure 20. PostgreSQL Language Selection

Figure 21. PostgreSQL Setup

Figure 22. Installation Notes

Figure 23. Choose Installation Options

	Caution
	Click on the icon next to "PostGIS Spatial Extensions" and select Will be installed on local hard drive.

	Tip
	Instead of installing PostGIS with the PostgreSQL installer, you should install a newer version from a separate installer (at least version 1.0.3). Such an installer is available from http://www.webbased.co.uk/mca/ or from the setup folder of the DCMMS CD. Once PostgreSQL 8.1 is released, the PostGIS version included in the PostgreSQL installer will be sufficient.

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 23, “Choose Installation Options” and click Next >.

Figure 24. Service Configuration

Figure 25. Account Error

Figure 26. Password

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

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

Figure 28. Initialise Database Cluster

	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.

Figure 29. Enable Procedural Languages

Figure 30. Enable Contrib Modules

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

Figure 31. Enable PostGIS

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

Figure 32. Ready to Install

Figure 33. Installation complete

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

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 34. PostGIS License

Figure 35. PostGIS Components

	Caution
	Uncheck the option Create Database as shown in Figure 35, “PostGIS Components” and click Next >. The dcmms database will be created by the DCMMS installer.

Figure 36. PostGIS Location

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

Figure 37. PostGIS Database Connection

Figure 38. Installation Complete

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

Figure 39. DCMMS License

Figure 40. DCMMS Components

Figure 41. DCMMS Location

Figure 42. DCMMS Database Connection

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
	The installer will not overwrite existing DCMMS configuration files.

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.

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

The PostgreSQL installation should support UNICODE.

	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

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.

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

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

	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

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.0\share\contrib.

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.

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
	If you don't install PHP to c:\windows\php, some of the settings below have to be adjusted.

	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
	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

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
	You'll need a PHP/Mapscript binary compiled with PostGIS support.

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.

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 the shapefile loader of the DCMMS application (Section 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

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.

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

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

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

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

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

	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.

Figure 43. 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 44, “Catalog Path”

Figure 44. Catalog Path

	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 4.4, “Translation System”.

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 4.2, “Pressure Dependency”).

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
	Use the tileindex.exe from the mapserver distribution to create tile indexes.

	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:

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

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

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

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.

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

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

The DCMMS application allows to load GIS data in shapefile format through a web interface. Log in using a DCMMS account with administrator rights, e.g. admin. Zip the shapefile before uploading.

See the DCMMS User Guide for details on the shapefile loader.

	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);

The commandline tool shp2pgsql is part of the PostGIS distribution and used internally by the DCMMS shapefile loader web interface. 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.0\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:\Program Files\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:\Program Files\dcmms\script\create_views.sql"
        

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.