BMFO Administration Guide

Maher Abdel Karim

<Maher_Karim@dorsch.com.jo>

Abdulqader Jaradat

<Abdulqader_Jaradat@ngwa.com.jo>

Steffen Macke

<Steffen_Macke@dorsch.com.jo>

Baha Faqih

<Baha_Faqih@dorsch.com.jo>

Copyright © 2003 - 2004 OMS Project, DORSCH Consult, NGWA

Copyright © 2005, 2006 DORSCH Consult

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

$Date: 2006-09-26 14:06:35 +0300 (Tue, 26 Sep 2006) $

Table of Contents

General
1. Introduction
2. Requirements
2.1. Hardware
2.2. Software
2.2.1. JpGraph
2.2.2. PHP
2.3. Database Backend
2.3.1. ORACLE
2.3.2. PostgreSQL
Reference
1. Installation
1.1. Common Steps
1.1.1. Webserver
1.1.2. Java 2 Software Development Kit
1.1.3. TOMCAT
1.2. Database Backend Installation
1.2.1. ORACLE
1.2.2. ORACLE XE
1.2.3. PostgreSQL Backend
1.3. Installer-based Installation
1.3.1. PHP
1.3.2. BMFO Installer With ORACLE
1.3.3. BMFO Installer With PostgreSQL
1.4. Manual Installation
1.4.1. Database Backend
1.4.2. ORACLE
1.4.3. PostgreSQL
1.4.4. Webserver
1.4.5. PHP
1.4.6. PEAR
1.4.7. JPGraph
1.4.8. Fonts
1.4.9. BMFO
1.4.10. Servlet
1.5. Change Default Password
2. Administration
2.1. Configuration
2.2. User Management
2.3. Access Control
2.4. Aggregation
2.5. Data Loading
2.6. WIS Link
2.7. Regular Maintenance
3. Updating
3.1. From 1.2.3 to 1.2.4
3.2. From 1.2.2 to 1.2.3
3.3. From 1.2.1 to 1.2.2
3.4. From 1.1.0 to 1.2.1
3.5. From 1.0.8 to 1.1.0
3.6. From 1.0.7 to 1.0.8
3.7. From 1.0.6 to 1.0.7
3.8. From 1.0.5 to 1.0.6
4. Troubleshooting
4.1. BMFO info mailing list
4.2. Support Tracker
4.3. Complete Uninstallation
4.4. FAQ
4.4.1. Empty Summary Well Production Report
4.4.2. ORA-12520
4.4.3. Unable to load dynamic library
4.4.4. Wrong PDF Report URl
4.4.5. The PDF reports do not work
4.4.6. Logon problems (ORACLE backend)
Index

List of Figures

1. Apache Wizard
2. Apache License
3. Apache Readme
4. Apache Information
5. Apache Setup Type
6. Apache Location
7. Apache Install
8. Java License Agreement
9. Java Development Kit Custom Setup
10. Java Runtime Environment Custom Setup
11. Browser Registration
12. Java Installation Completed
13. Apache TOMCAT Setup
14. TOMCAT License Agreement
15. TOMCAT Components
16. TOMCAT Install Location
17. TOMCAT Configuration
18. TOMCAT JVM Selection
19. TOMCAT Installation Finish
20. ORACLE Installation Type
21. ORACLE Database Configuration
22. ORACLE Database Identification
23. ORACLE XE Welcome Page
24. ORACLE XE License Agreement
25. ORACLE XE Installation Folder
26. ORACLE XE Password
27. ORACLE XE Summary
28. ORACLE XE Installation Complete
29. PostgreSQL Setup
30. Installation Notes
31. Choose Installation Options
32. Service Configuration
33. Account Error
34. Password
35. Successfully granted the 'Logon as a service' right
36. Initialise Database Cluster
37. Enable procedural languages
38. Enable contrib modules
39. Enable PostGIS
40. Ready to Install
41. Installation complete
42. PHP License
43. PHP Components
44. PHP Location
45. PHP Installation Complete
46. Choose Components (Oracle)
47. ORACLE Database Connection
48. TOMCAT Connection (PostgreSQL)
49. Install Location
50. BMFO License Agreement
51. Choose Components (PostgreSQL Backend)
52. PostgreSQL Database Connection
53. TOMCAT Connection (ORACLE)
54. Install Location


General

Table of Contents

1. Introduction
2. Requirements
2.1. Hardware
2.2. Software
2.2.1. JpGraph
2.2.2. PHP
2.3. Database Backend
2.3.1. ORACLE
2.3.2. PostgreSQL

General information for BMFO administrators.


1. Introduction

This document describes how to setup and administer the Bulk Meter Flow and Operations (BMFO) application version 1.2.4.

BMFO is available from http://bmfo.sourceforge.net.

[Warning] Warning

BMFO is a web-based application, but it should be used only in an intranet environment.

If you are going to use BMFO on the internet, you should perform a security review of the application sources or add additional security measures like authentication on the web server level and SSL. BMFO is free software you can find more information available in user guides and development guides


2. Requirements

2.1. Hardware
2.2. Software
2.2.1. JpGraph
2.2.2. PHP
2.3. Database Backend
2.3.1. ORACLE
2.3.2. PostgreSQL

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


2.1. Hardware

A PC with at least two GHz CPU speed and one GB RAM is required to run the BMFO application. Note that depending on the size of the data, number of concurrent users and database backend, the actual hardware requirements can be much higher.


2.2. Software

2.2.1. JpGraph
2.2.2. PHP

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

  • Web browser

  • Web server

  • PHP

  • JPGraph

  • RDBMS

  • Java Development Kit

  • JasperReports

  • Servlet Engine, e.g. Apache TOMCAT

  • BMFO


2.2.1. JpGraph

[Caution] Caution

JpGraph is released under a dual license. QPL 1.0 (Qt Free License) for non-commercial, open-source and educational use and JpGraph Professional License for commercial use.

For BMFO systems in a production environment, a JpGraph Professional License is required. The license and more information on JpGraph are available from http://www.aditus.nu/jpgraph/.


2.2.2. PHP

PHP 4 was used until BMFO version 1.1.0.

Since version 1.2.0, BMFO is using PHP 5. PHP 4 might still work but has not been tested.

PHP 5.1.4 or later is recommended.


2.3. Database Backend

2.3.1. ORACLE
2.3.2. PostgreSQL

A relational database management system supported by the PHP dbx extension is required in order to run the application. ORACLE and PostgreSQL have been tested.

If you would like to use a different database backend contact the BMFO developers.


2.3.1. ORACLE

If ORACLE is used as the database backend, at least version 9i is required..

The free ORACLE 10g Express Edition(XE) is available for download from http://www.oracle.com/technology/software/products/database/xe/index.html.

ORACLE versions 9i and 10g have been tested with BMFO.


2.3.2. PostgreSQL

PostgreSQL versions 7.3, 7.4, 8.0 and 8.1 have been tested as database backends for BMFO.

Version PostgreSQL version 8.1 is recommended.

PostgreSQL is freely available from http://www.postgresql.org


Reference

Table of Contents

1. Installation
1.1. Common Steps
1.1.1. Webserver
1.1.2. Java 2 Software Development Kit
1.1.3. TOMCAT
1.2. Database Backend Installation
1.2.1. ORACLE
1.2.2. ORACLE XE
1.2.3. PostgreSQL Backend
1.3. Installer-based Installation
1.3.1. PHP
1.3.2. BMFO Installer With ORACLE
1.3.3. BMFO Installer With PostgreSQL
1.4. Manual Installation
1.4.1. Database Backend
1.4.2. ORACLE
1.4.3. PostgreSQL
1.4.4. Webserver
1.4.5. PHP
1.4.6. PEAR
1.4.7. JPGraph
1.4.8. Fonts
1.4.9. BMFO
1.4.10. Servlet
1.5. Change Default Password
2. Administration
2.1. Configuration
2.2. User Management
2.3. Access Control
2.4. Aggregation
2.5. Data Loading
2.6. WIS Link
2.7. Regular Maintenance
3. Updating
3.1. From 1.2.3 to 1.2.4
3.2. From 1.2.2 to 1.2.3
3.3. From 1.2.1 to 1.2.2
3.4. From 1.1.0 to 1.2.1
3.5. From 1.0.8 to 1.1.0
3.6. From 1.0.7 to 1.0.8
3.7. From 1.0.6 to 1.0.7
3.8. From 1.0.5 to 1.0.6
4. Troubleshooting
4.1. BMFO info mailing list
4.2. Support Tracker
4.3. Complete Uninstallation
4.4. FAQ
4.4.1. Empty Summary Well Production Report
4.4.2. ORA-12520
4.4.3. Unable to load dynamic library
4.4.4. Wrong PDF Report URl
4.4.5. The PDF reports do not work
4.4.6. Logon problems (ORACLE backend)

The reference for BMFO administrators.


1. Installation

1.1. Common Steps
1.1.1. Webserver
1.1.2. Java 2 Software Development Kit
1.1.3. TOMCAT
1.2. Database Backend Installation
1.2.1. ORACLE
1.2.2. ORACLE XE
1.2.3. PostgreSQL Backend
1.3. Installer-based Installation
1.3.1. PHP
1.3.2. BMFO Installer With ORACLE
1.3.3. BMFO Installer With PostgreSQL
1.4. Manual Installation
1.4.1. Database Backend
1.4.2. ORACLE
1.4.3. PostgreSQL
1.4.4. Webserver
1.4.5. PHP
1.4.6. PEAR
1.4.7. JPGraph
1.4.8. Fonts
1.4.9. BMFO
1.4.10. Servlet
1.5. Change Default Password

This section describes the BMFO installation on Windows.

Installation on other operating systems such as Linux is possible but not described in detail in this document.

Section 1.3 explains the installer-based installation. Section 1.4 has more detailed information - use this if the installer does not work for you. Installation steps that are common to both installation types are described under Section 1.1.

In the following, $BMFO and %BMFO% reference the directory where the application is installed. Replace this with the actual path or set an environment variable. $BMFO is a bash environment variable and %BMFO% a Windows enviroment variable.

The recommended installation folder for BMFO is c:\program files\bmfo.

After the installation has finished, see the Section 2.1.


1.1. Common Steps

1.1.1. Webserver
1.1.2. Java 2 Software Development Kit
1.1.3. TOMCAT

This section describes BMFO installation steps that are common to both the installer-based and manual installation.

Please choose one database backend, either ORACLE (Section 1.2.1) , ORACLE XE (Section 1.2.2) or PostgreSQL (Section 1.2.3).


1.1.1. Webserver

A webserver supporting PHP is required. The Apache webserver has been used for the development.

Apache version 2.0.59 or higher is recommended to operate BMFO.

[Caution] Caution

Until Apache 2.2 is supported by PHP 5 (Most probably in PHP 5.2.0), stick to Apache 2.0.

[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 BMFO CD or from the Apache website: http://httpd.apache.org.

Figure 1. Apache Wizard

In the Apache installer welcome page, click Next > (Figure 1).

Figure 2. Apache License

Select I accept the terms in the license agreement and click Next > (Figure 2).

Figure 3. Apache Readme

Read through the information in Figure 3 and click on Next >.

Figure 4. Apache Information

Fill in the fields Network Domain (The domain of your Organization), Server Name (The name of your BMFO 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 4).

Apache Setup Type

Figure 5. Apache Setup Type

Verify the selection in Figure 5 and click Next >.

Figure 6. Apache Location

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

[Tip] Tip

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

Figure 7. Apache Install

In the dialog shown in Figure 7, 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.

If you would like to use the Apache webserver distributed with ORACLE, please consult the ORACLE documentation for configuration and PHP installation instructions.


1.1.2. Java 2 Software Development Kit

The Java 2 Software Development Kit (J2SDK), version 1.5 or higher is required to run BMFO. Earlier Java versions will also work but require a recompilation of the bmfo_report.war web application archive.

J2SDK is available from http://java.sun.com. The download page is http://java.sun.com/j2se/1.5.0/download.html.

Select the link Download JDK 5.0 Update 5 and follow the instructions.

Run the J2SDK installer (jdk-1_5_0_05-windows-i586-p.exe).

Java License Agreement

Figure 8. Java License Agreement

Read through the license and select I accept the terms in the license agreement if you agree to the license as shown in Figure 8 and click Next >.

Java Development Kit Custom Setup

Figure 9. Java Development Kit Custom Setup

Make sure that the default features are selected as shown in Figure 9 and click Next >.

Java Runtime Environment Custom Setup

Figure 10. Java Runtime Environment Custom Setup

Make sure that the default features are selected as shown in Figure 10 and click Next >.

Figure 11. Browser Registration

Accept the default setting as shown in Figure 11 and click Next >.

Java Installation Completed

Figure 12. Java Installation Completed

Once the Java installation is completed, click on the Finish button.


1.1.3. TOMCAT

Apache TOMCAT version 5.5.17 has been tested with BMFO. Other version as well as other servlet containers should work but are not described in detail.

TOMCAT is available from the BMFO CD or http://tomcat.apache.org. The download page is http://tomcat.apache.org/download-55.cgi. Select Windows Executable under binary core distribution.

[Note] Note

Java needs to be installed before you can run TOMCAT.

Run the TOMCAT setup (apache-tomcat-5.5.17.exe).

Apache TOMCAT Setup

Figure 13. Apache TOMCAT Setup

In Figure 13 click Next >.

TOMCAT License Agreement

Figure 14. TOMCAT License Agreement

If you agree to the license in Figure 14, click on I Agree.

Figure 15. TOMCAT Components

Expand the Tomcat component and select the Service and Native components as shown in Figure 15. Click Next >.

TOMCAT Install Location

Figure 16. TOMCAT Install Location

Accept the default install location as shown in Figure 16 by clicking Next >.

Figure 17. TOMCAT Configuration

Choose and enter an appropriate TOMCAT administrator password and click Next >.

[Caution] Caution

Make sure to remember the TOMCAT administrator password as it will be required later during the installation process and for administration purposes.

[Tip] Tip

In case port 8080 is occupied already (e.g. by an ORACLE installation), you can use an alternative port like 8081. Make sure to remember the alternative port number as it will be required later during the installation process and for administration purposes.

TOMCAT JVM Selection

Figure 18. TOMCAT JVM Selection

Verify that the Java Virtual Machine (JVM) is the one installed before and click install to start the installation.

TOMCAT Installation Finish

Figure 19. TOMCAT Installation Finish

Disable the Show Readme option unless you are interested in reading the readme file. Click Finish.


1.2. Database Backend Installation

1.2.1. ORACLE
1.2.2. ORACLE XE
1.2.3. PostgreSQL Backend

You have to choose one of the possible database backends:

ORACLE (See Section 1.2.1)
ORACLE XE (See Section 1.2.2)
PostgreSQL (See Section 1.2.3)


1.2.1. ORACLE

[Caution] Caution

You don't have to follow the instructions in this chapter if you are using ORACLE XE or PostgreSQL as the database backend. See Section 1.2.2 or Section 1.2.3 in this case.

Installation instructions for ORACLE 9i or 10g.

Start the ORACLE installer.

Select Standard Installation and click Next (Figure 20).

ORACLE Installation Type

Figure 20. ORACLE Installation Type

Select the General Purpose configuration and click Next (Figure 21).

ORACLE Database Configuration

Figure 21. ORACLE Database Configuration

Enter bmfo as the Global Database Name. Click Next (Figure 22).

ORACLE Database Identification

Figure 22. ORACLE Database Identification

[Caution] Caution

If you need Arabic support, make sure to use the Windows-1256 codepage when creating the database. Changing the characterset later on in the registry will not work.

[Caution] Caution

Restart the system before continuing with the BMFO installation.


1.2.2. ORACLE XE

[Caution] Caution

You don't have to follow the instructions in this chapter if you are using ORACLE or PostgreSQL as the database backend. See Section 1.2.1 or Section 1.2.3 in this case.

Installation instructions for the ORACLE 10g Express Edition (XE) backend.

Start the ORACLE installer (OracleXE.exe).

ORACLE XE Welcome Page

Figure 23. ORACLE XE Welcome Page

On the page displayed in Figure 23 click Next >.

ORACLE XE License Agreement

Figure 24. ORACLE XE License Agreement

Read through the license agreement and activate I accept the terms in the license agreement as shown in Figure 24 if you agree to the license. Click Next >.

ORACLE XE Installation Folder

Figure 25. ORACLE XE Installation Folder

Accept the default installation folder as shown in Figure 25 and click Next >.

ORACLE XE Password

Figure 26. ORACLE XE Password

Select and enter an appropriate administrator password and click Next > (Figure 26).

[Caution] Caution

Make sure to remember the administrator password as it will be required later during the installation process (Section 1.3.2) and for administrative purposes.

ORACLE XE Summary

Figure 27. ORACLE XE Summary

Review the settings as shown in Figure 27 and click Install

ORACLE XE Installation Complete

Figure 28. ORACLE XE Installation Complete

Disable the option as shown in Figure 28 and click Finish.

[Caution] Caution

Restart the system before continuing with the BMFO installation. This will make sure that the necessary environment variables are in place.


1.2.3. PostgreSQL Backend

This section describes how to install PostgreSQL for Windows.

[Caution] Caution

You don't have to follow the instructions in this chapter if you are using ORACLE or ORACLE XE as the database backend. See Section 1.2.1 or Section 1.2.1 in this case.

The PostgreSQL installer is available from the setup folder of the BMFO CD or from http://www.postgresql.org.

Run the PostgreSQL installer and select the English language.

Figure 29. PostgreSQL Setup

Click Next >.

Figure 30. Installation Notes

Press Next > after reading the installation instructions.

Choose Installation Options

Figure 31. Choose Installation Options

Accept the settings as shown in Figure 31 and click Next >.

Figure 32. Service Configuration

Accept the default settings as shown in Figure 32 leave account password and verify password empty and click Next >.

Figure 33. Account Error

Select Yes.

Figure 34. Password

Accept the random password by clicking OK.

Successfully granted the 'Logon as a service' right

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

Click on OK.

Initialise Database Cluster

Figure 36. Initialise Database Cluster

Accept the default settings as shown in Figure 36and choose an appropriate password. Then click Next >.

[Caution] Caution

Make sure to remember the administrator password as it will be required later during the installation process and for administrative purposes.

Enable procedural languages

Figure 37. Enable procedural languages

Accept the default settings as shown in Figure 37. Make sure that "PL/pgsql" is selected. Click Next >.

Enable contrib modules

Figure 38. Enable contrib modules

Accept the default selection as shown in Figure 38 and click Next >.

Figure 39. Enable PostGIS

As shown in Figure 39 do not enable PostGIS in template1 and click Next >.

Ready to Install

Figure 40. Ready to Install

Click Next >.

Figure 41. Installation complete

If you are interested in future PostgreSQL releases, click Subscribe to pgsql-announce in order to subscribe to the pgsql-announce mailing list. Click Finish.


1.3. Installer-based Installation

1.3.1. PHP
1.3.2. BMFO Installer With ORACLE
1.3.3. BMFO Installer With PostgreSQL

Instructions for a BMFO installation on Windows using the BMFO installer. The installer automates the installation as much as possible. This is the easiest way to install BMFO.


1.3.1. PHP

PHP can be installed using the BMFO scripting installer, which is available from the BMFO CD or from http://bmfo.sourceforge.net. If you don't want to use the BMFO scripting installer to install PHP, please refer to Section 1.4.

Start the BMFO Scripting installer (bmfo-scripting-setup-5.1.4-1.exe.

Figure 42. PHP License

Click I Agree if you agree to the license (Figure 42).

Figure 43. 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 BMFO scripting installer provides all necessary packages.

Figure 44. PHP Location

Accept the default installation directory, c:\windows\php, by clicking Install (Figure 44).

PHP Installation Complete

Figure 45. PHP Installation Complete

Click Close to close the installer.


1.3.2. BMFO Installer With ORACLE

Follow these steps if you are installing BMFO with an ORACLE or ORACLE XE database backend. If you are using PostgreSQL as the database backend, refer to Section 1.3.3.

The BMFO installer is available from http://bmfo.sourceforge.net.

Run the BMFO installer (bmfo-setup-XXX.exe).

Choose ORACLE as your database backend.

Make sure that the following components ( Figure 46) are selected:

  • BMFO

  • Apache/PHP Config

  • ORACLE

  • Servlet

  • JpGraph

  • Scheduled Cleanup

Choose Components (Oracle)

Figure 46. Choose Components (Oracle)

Click Next >.

ORACLE Database Connection

Figure 47. ORACLE Database Connection

When asked for the database connection information (Figure 47), enter the database name and superuser password as entered during the database installation process (Section 1.2.1 or Section 1.2.2) and click Next >.

TOMCAT Connection (PostgreSQL)

Figure 48. TOMCAT Connection (PostgreSQL)

Verify that the TOMCAT port number is correct, enter your TOMCAT administrator password (Figure 53 like entered in Section 1.1.3) and click Next >.

[Caution] Caution

Unlike shown in Figure 53, you will most probably be using a different port than 8080 because ORACLE is occupying port 8080. Review the port number critically. Check that TOMCAT is up and running on the port you expect if necessary. See the TOMCAT documentation for details.

You can accept the default installation location as shown in Figure 49.

Figure 49. Install Location

Click Install.

Once the BMFO installer has finished, you should be able log on to BMFO using the shortcut from the Start Menu.

The default URL is http://localhost/bmfo/.

See the Quick Start section in the BMFO user guide.

The default user name is bmfo and the default password is bmfo.

[Warning] Warning

It is recommended that you change the default password "bmfo" for the ORACLE user bmfo as soon as possible for security reasons.


1.3.3. BMFO Installer With PostgreSQL

This section contains information how to install BMFO using the installer for a PostgreSQL backend. If you are installing with and ORACLE or ORACLE XE backend, please refer to Section 1.3.2.

Run the BMFO installer (bmfo-setup-XXX.exe).

BMFO License Agreement

Figure 50. BMFO License Agreement

Click I Agree if you agree to the license agreement as shown in Figure 50.

Select the components as shown in Figure 51.

Choose Components (PostgreSQL Backend)

Figure 51. Choose Components (PostgreSQL Backend)

Click Next >.

[Caution] Caution

Change the user name to "postgres" as shown in Figure 52. Enter the PostgreSQL superuser password which you've entered before (Section 1.2.3, Figure 36).

PostgreSQL Database Connection

Figure 52. PostgreSQL Database Connection

Click Next >.

TOMCAT Connection (ORACLE)

Figure 53. TOMCAT Connection (ORACLE)

Verify that the TOMCAT port number is correct, enter your TOMCAT administrator password (Figure 53 like entered in Section 1.1.3) and click Next >.

You can accept the default installation location as shown in Figure 54.

Figure 54. Install Location

Click Install.

Once the BMFO installer has finished, you should be able log on to BMFO using the shortcut from the Start Menu.

The default user name is bmfo and the default password is bmfo.

[Warning] Warning

It is recommended that you change the default password "bmfo" for the PostgreSQL user bmfo as soon as possible for security reasons.


1.4. Manual Installation

1.4.1. Database Backend
1.4.2. ORACLE
1.4.3. PostgreSQL
1.4.4. Webserver
1.4.5. PHP
1.4.6. PEAR
1.4.7. JPGraph
1.4.8. Fonts
1.4.9. BMFO
1.4.10. Servlet

General installation instructions to run BMFO on Windows. Similar installation steps are required on other operating systems, like Linux.


1.4.1. Database Backend

SQL Data Definition Language scripts are available for creating the required tables in ORACLE or Postgres databases. The scripts are located in the script folder of the BMFO distribution.

The scripts set up the necessary table structure for the application.


1.4.2. ORACLE

[Note] Note

%BMFO% in this section refers to the actual BMFO installation directory. If this path contains spaces, you have to quote appropriately.

%BMFO%\script\prepare_oracle.sql is the first script, to be executed by the ORACLE system account.

The scripts %BMFO%\script\create_bmfo_ddl.sql, %BMFO%\script\oracle_ddl.sql and %BMFO%\script\create_views.sql have to be executed using the bmfo user. For example in SQL Plus:

@%BMFO%\script\create_bmfo_ddl.sql
@%BMFO%\script\oracle_ddl.sql
@%BMFO%\script\create_views.sql

Remember to replace %BMFO% with the actual location of the BMFO application.

[Warning] Warning

The default password for the ORACLE user bmfo is "bmfo". For security reasons it should be changed as soon as possible.

To finish, run script\oracle_role.sql as the ORACLE system user.


1.4.3. PostgreSQL

Use the following commands to manually create and initialize the bmfo database on a PostgreSQL backend:

createdb -U postgres bmfo
createuser -U postgres bmfo
createlang -d bmfo -U postgres plpgsql
psql -d bmfo -U bmfo -f %BMFO%\script\create_bmfo_ddl.sql
psql -d bmfo -U postgres -f %BMFO%\script\postgresql_ddl.sql
psql -d bmfo -U postgres -f %BMFO%\script\create_views.sql
[Warning] Warning

The default password for the PostgreSQL user bmfo is "bmfo". For security reasons it should be changed as soon as possible.


1.4.4. Webserver

If you are using an ORACLE backend, the following lines have to be added to httpd.conf:

SetEnv ORACLE_HOME "c:\ORACLE\Ora90"
SetEnv TEMP "c:\temp"

As the admin folder contains pages that perform administrative tasks, it should be protected by a password on the Apache level. See the Apache documenation for the details.


1.4.5. PHP

PHP, the Hypertext Pre-Processor is required in order to run the application. PHP versions older than 5.1.4 have not been tested with BMFO 1.2.0.

[Caution] Caution

Please install the zipfile distribution (windows binaries zip file)of PHP, not the installer version. Also install the PECL modules.

Notice the difference between the PHP installer and the BMFO Scripting installer.

PHP is available from http://www.php.net. The following page provides the required package (version 5.1.4): http://www.php.net/get/php-5.1.4-Win32.zip/from/a/mirror

Extract the zip file to c:\windows and rename the folder php-5.1.4 to php.

At least the following PHP extensions have to be loaded:

  • dbx

  • gettext

  • dbase

  • gd

  • pgsql

1.4.5.1. php.ini

The php.ini file should be edited accordingly. The important settings are summarized below:

[PHP]

max_execution_time = 300

extension=php_dbase.dll
extension=php_dbx.dll
extension=php_gd2.dll
extension=php_gettext.dll
extension=php_iconv.dll
extension=php_oci8.dll
extension=php_pgsql.dll

[mail function]
SMTP = igwa_2
sendmail_from = bmfoadministrator@ngwa.com.jo
[Caution] Caution

Remember to adjust the php.ini settings according to your needs.

PHP should serve the pages with UTF-8 encoding. This can be achieved by adding the following line to php.ini:

  default_charset = "utf-8";

Make sure that session support is enabled, by adjusting the following line:

  session.save_path=c:\tmp

Make sure that the temporary directory c:\tmp exists.

The PHP 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-cgi.exe"


1.4.6. PEAR

Install the following PEAR packages:

Pager
DataObject
DataObject_FormBuilder

PEAR is the PHP Extensible Application Repository.

PEAR can be found under http://pear.php.net.


1.4.7. JPGraph

JPGraph is a graphing package for PHP. It is required for the graph display in the application.

JpGraph is available from http://www.aditus.nu/jpgraph/.

In order to install JPGraph, unzip the JPGraph zipfile and copy the files from the folder stripped-src if available to%BMFO%\jpgraph


1.4.8. Fonts

[Caution] Caution

Some PDF reports require that the Arial TrueType font is installed in c:\windows\fonts\arial.ttf. If you cannot install the font there, it is necessary to compile the JasperReports with a different path for the font.


1.4.9. BMFO

Copy %BMFO%\conf\dataobject.ini.oracle or %BMFO%\conf\dataobject.ini.postgresql to %BMFO%\conf\dataobject.ini.

If you are using ORACLE, copy %BMFO%\include\dbx_connect_oracle.php to %BMFO%\include\dbx_connect.php. If you are using PostgreSQL, copy %BMFO%\include\dbx_connect_postgresql.php to %BMFO%\include\dbx_connect.php. Please review the connection settings in the files and adjust them if required.


1.4.10. Servlet

Deploy the servlet (bmfo_reports.war) to the servlet container and adjust $strServletUrl in include/dbx_connect.php if necessary.


1.5. Change Default Password

[Important] Important

BMFO installs a default user account with the user name bmfo and the password bmfo. For security reasons you should change this immediately.


2. Administration

2.1. Configuration
2.2. User Management
2.3. Access Control
2.4. Aggregation
2.5. Data Loading
2.6. WIS Link
2.7. Regular Maintenance

Description of various BMFO administration tasks.


2.1. Configuration

BMFO has some configuration options available through variables in include/dbx_config.php.

In case of problems opening the PDF and XLS reports generated by the servlets, replace "localhost" in strServletUrl with the name of the server.


2.2. User Management

When using the ORACLE backend, grant the role "bmforole" to new users.


2.3. Access Control

BMFO allows to limit access to selected operational areas on a per-user basis.

After you installed BMFO the wizard will create two roles,bmforole role which you have to assign it from SQL to any new full control user and bmforeadonly role which you have to assign it from SQL for any new read only user.

Access for a user to an operational area is granted by inserting a record to the UserOperationalArea table containing the user name and the operational area's coded value.

As of BMFO version 1.0.6, access control is enforced for all write operations and a number of reporting functions.

The following SQL statement can be used to allow the user "Username" to all operational areas:

insert into UserOperationalArea (select
UserOperationalArea_seq.nextval, 'Username', codedvalue from OperationalArea)


2.4. Aggregation

BMFO allows to aggregate meter readings using the Aggregation field of the Meter table.

If you don't plan to use aggregation, simply fill the Aggregation field from the FacilityID field like in the following example:

update Meter set Aggregation=FacilityID

See the user guide for details.


2.5. Data Loading

The admin folder of the BMFO distribution contains a utility script that allows loading of a dBase (.dbf) file to the meter table.

The default path to load the file (c:\temp\meter.dbf) can be adjusted by editing admin/load_meter_data.php.

[Tip] Tip

When managing meter location in a geographic information system (GIS), the DBF file can be created by saving the locations as a shapefile.


2.6. WIS Link

Information regarding the link to WIS. WIS is the Water Information System. It uses an ORACLE backend. BMFO interacts with WIS in both directions:

  • Export of production data through the WIS export file created from the BMFO web interface (SQL script with WIS insert statements is created).

  • Import of meter locations (Meter objects) from WIS. This requires a database link to WIS.

In order to create a database link to the WIS database, tnsnames.ora should contain configuration statements like the following:

WIS =
      (DESCRIPTION =
        (ADDRESS_LIST =
          (ADDRESS = (PROTOCOL = TCP)(HOST = wisserver)(PORT = 1521))
        )
        (CONNECT_DATA =
          (SID = ORCL)
        )
      )

The SQL statement to create the link from the BMFO database (ORACLE backend) to the WIS database looks like this:

create database link wislink connect to username
  identified by password using 'wis';

A script to create the meters from WIS is available in script/wis2bmfo.sql.

On the WIS side, the BMFO_METER_VIEW is required. This can be created using script/create_wis_views.sql.

Deletion of existing Meter, OperationaArea and AdministrativeArea together with the insertion of new values is done through script/wis2bmfo.sql.

The following commandline statement should be scheduled to run every night:

sqlplus user/password@bmfo @wis2bmfo.sql


2.7. Regular Maintenance

Delete the records in the ReportImage table from time to time. These are temporary records that are only used to reference the image names.


3. Updating

3.1. From 1.2.3 to 1.2.4
3.2. From 1.2.2 to 1.2.3
3.3. From 1.2.1 to 1.2.2
3.4. From 1.1.0 to 1.2.1
3.5. From 1.0.8 to 1.1.0
3.6. From 1.0.7 to 1.0.8
3.7. From 1.0.6 to 1.0.7
3.8. From 1.0.5 to 1.0.6

This section gives detailed information on the necessary steps to update the BMFO application.

[Caution] Caution

Please backup the database before updating.


3.1. From 1.2.3 to 1.2.4

To upgrade the application, do the following:

  1. Run the BMFO installer and select the "BMFO" and "Update" components.

  2. Update the servlet. Use the TOMCAT Manager to verify that the version number of the servlet is now 1.2.4.


3.2. From 1.2.2 to 1.2.3

BMFO versions 1.2.0 to 1.2.2 were inserting superfluous installation records upon data entry of operation records. To overcome this problem, verify that you have only installation records for the "Unknown" meter:

select distinct EquipmentOID from InstallationRecord
If the query only returns "Unknown", delete the superfluous installation records with the following query:
delete from InstallationRecord where ID in
        (select ID from Installationrecord i where RecordDate >
          (select min(i2.RecordDate) from InstallationRecord i2 where
            i.NetworkOID = i2.NetworkOID))

You should also make sure that there is at least one installation record for every meter location that has operation records:

        insert into InstallationRecord
        (select NetworkOID, 1, 'Unknown', '', ID, installationrecordid.nextval,
        RecordDate from OperationsRecord o where NetworkOID in
        (select OperationsRecord.NetworkOID from OperationsRecord left
        outer join InstallationRecord on
        InstallationRecord.NetworkOID = OperationsRecord.NetworkOID
        where InstallationRecord.NetworkOID is null)
        and RecordDate in
        (select min(RecordDate) from OperationsRecord o2 where
        o.NetworkOID = o2.NetworkOID)
        and ID = (select min(ID) from OperationsRecord o3 where
        o.NetworkOID = o3.NetworkOID and o.RecordDate = o3.RecordDate));

To upgrade the application, do the following:

  1. Run the BMFO installer and select the "BMFO" and "Update" components.

  2. Update the servlet.


3.3. From 1.2.1 to 1.2.2

  1. If you are using an ORACLE backend, add the following function to dbx_connect.php:

    /**
 * Escape a string for a database query.
 * @param $strString String that should be escaped.
 * Returns the string escaped by dbx_escape_string().
 */
function bmfo_escape_string($strString) {
  GLOBAL $rdbms;
  return dbx_escape_string($rdbms, $strString);
}

    If you are using an PostgreSQL backend, add the following function to dbx_connect.php:

    /**
 * Escape a string for a database query.
 * @param $strString String that should be escaped.
 * Returns the string escaped by pg_escape_string().
 */
function bmfo_escape_string($strString) {
  return pg_escape_string($strString);
}

  2. Run the BMFO installer and select the "BMFO" and "Update" components.

  3. Update the Servlet.


3.4. From 1.1.0 to 1.2.1

The major change in version 1.2.1 is the switch to PHP 5. It is recommended to completely remove PHP 4 from the system before installing BMFO Scripting 5.1.4. If necessary, see the complete uninstallation instructions (Section 4.3).

Please follow the steps below to update the sytem:

  1. Install JDK 1.5.0-08.

  2. Install TOMCAT 5.5.17

  3. Delete Apache's httpd.conf.

  4. Update Apache to version 2.0.59.

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

  6. Install BMFO Scripting (PHP) 5.1.4.

  7. Run the BMFO installer.

    For an installation with an ORACLE database backend select the following components:

    • BMFO

    • Apache/PHP Configuration

    • Upgrade ORACLE

    • Servlet

    When asked for database connection information, use the bmfo account with the respective password.

    For an installation with a PostgreSQL database backend, select the following components:

    • BMFO

    • Apache/PHP Configuration

    • Upgrade PostgreSQL

    • Servlet

  8. Please insert the following configuration line to include/dbx_connect.php:

    $GLOBALS['boolDebug'] = false;


3.5. From 1.0.8 to 1.1.0

Please follow the steps below to update the system:

  1. Install JDK 1.5.0-07.

  2. Install TOMCAT 5.5.17

  3. Update Apache to version 2.0.58.

  4. Install DCMMS Scripting (PHP) 4.4.2-2.

  5. Run the BMFO Installer.

    For an installation with an ORACLE database backend, grant the right to create public synonyms to the bmfo user.

    [Warning] Warning

    You will have to create the synonyms yourself, if you forget to grant this right to user bmfo.

    Run the BMFO 1.1.0 installer and select the following components:

    • BMFO

    • Upgrade ORACLE

    • Servlet

    When asked for database connection information, use the bmfo account with the respective password.

    For an installation with a PostgreSQL database backend, select the following components:

    • BMFO

    • Upgrade PostgreSQL

    • Servlet

[Note] Note

Make sure that the new field Destination in the Meter table is filled with correct values. The field is a foreign key referencing CodedValue from the OperationalArea table. For meters that transfer water from one operational area to another, it describes the destination operational area. The information is used in the water balance.

[Caution] Caution

When you are using an ORACLE backend and are experiencing problems logging on after the ugrade, make sure that you use the "===" operator instead of "==" in dbx_connect.php.


3.6. From 1.0.7 to 1.0.8

Please follow the steps below to update the system:

  1. Run the DCMMS Installer.

    For an installation with an ORACLE database backend, grant the right to create public synonyms to the bmfo user.

    [Warning] Warning

    You will have to create the synonyms yourself, if you forget to grant this right to user bmfo.

    Run the BMFO 1.0.8 installer and select the following components:

    • BMFO

    • Upgrade ORACLE

    • Servlet

    When asked for database connection information, use the bmfo account with the respective password.

    For an installation with a PostgreSQL database backend, select the following components:

    • BMFO

    • Upgrade PostgreSQL

    • Servlet


3.7. From 1.0.6 to 1.0.7

The 1.0.7 release is a pure bugfix release of the 1.0.6 release. As no changes were done to the data model, simply running the installer, selecting the DCMMS component and updating the servlet is sufficient.


3.8. From 1.0.5 to 1.0.6

Please follow the steps below to update the system:

  1. Install JDK 1.5.0.

  2. Install TOMCAT 5.5.

  3. Update Apache to version 2.0.55.

  4. Install DCMMS Scripting (PHP) 4.4.1.

  5. Run the DCMMS Installer.

    For an installation with an ORACLE database backend, grant the right to create public synonyms to the bmfo user.

    [Warning] Warning

    You will have to create the synonyms yourself, if you forget to grant this right to user bmfo.

    Run the BMFO 1.0.6 installer and select the following components:

    • BMFO

    • Upgrade ORACLE

    • Servlet

    • Scheduled Cleanup

    When asked for database connection information, use the bmfo account with the respective password.

    For an installation with a PostgreSQL database backend, select the following components:

    • BMFO

    • Upgrade PostgreSQL

    • Servlet

    • Scheduled Cleanup

  6. Set up access control using the UserOperationalArea table (Section 2.3).

  7. Fill the Aggregation field in the Meter table (Section 2.4).


4. Troubleshooting

4.1. BMFO info mailing list
4.2. Support Tracker
4.3. Complete Uninstallation
4.4. FAQ
4.4.1. Empty Summary Well Production Report
4.4.2. ORA-12520
4.4.3. Unable to load dynamic library
4.4.4. Wrong PDF Report URl
4.4.5. The PDF reports do not work
4.4.6. Logon problems (ORACLE backend)

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


4.1. BMFO info mailing list

The BMFO 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=32236. or by sending an email to <bmfo-info@lists.sourceforge.net>.


4.2. Support Tracker

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

[Caution] Caution

Please make sure that you look at all bug reports support requests, not only the open ones.


4.3. Complete Uninstallation

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

[Warning] Warning

Make sure that you have backed up your BMFO data (database dump file).

  1. Uninstall Apache through the Control Panel.

  2. Uninstall ORACLE, ORACLE XE or PostgreSQL through the Control Panel.

  3. Uninstall TOMCAT through the Control Panel.

  4. Uninstall BMFO through the Control Panel.

  5. Uninstall BMFO Scripting through the Control Panel.

  6. Delete c:\program files\postgresql.

  7. Delete c:\program files\bmfo.

  8. Delete c:\windows\php.

  9. Delete c:\windows\pear.

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

  11. Delete c:\program files\Apache Group.

  12. Delete c:\program files\Apache Software Foundation.

  13. Delete c:\tmp

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

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

    net user postgres /delete

  16. Verify that the BMFO folder was removed from the Start Menu.

  17. Reboot.


4.4. FAQ

4.4.1. Empty Summary Well Production Report
4.4.2. ORA-12520
4.4.3. Unable to load dynamic library
4.4.4. Wrong PDF Report URl
4.4.5. The PDF reports do not work
4.4.6. Logon problems (ORACLE backend)

Frequently asked questions.


4.4.1. Empty Summary Well Production Report

Check if the Aggregation field of the Meter table is filled if the generated Summary Well Production Reports are empty or if the value "null" appears in the record.


4.4.2. ORA-12520

If you encounter an error like the following the Apache's error.log, restart the database:

[Tue Sep 26 12:14:40 2006] [error] [client 127.0.0.1] PHP Warning: oci_connect(): ORA-12520: TNS:listener could not find available handler for requested type of server

This was encountered for example during the webtest run.


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


4.4.4. Wrong PDF Report URl

In case the PDF and XLS report generation does not work because of a wrong URL (e.g. using localhost instead of the real server name), make sure that strServletUrl is configured correctly (Section 2.1).


4.4.5. The PDF reports do not work

[Caution] Caution

This information only applies to BMFO prior to version 1.0.6.

The PDF reports are not working. An empty page or a page with an error message appears.

Check the [Java] section in php.ini. Make sure that the filenames are correct.

Review the error log of the webserver. In the case of Apache, this is the file error.log in the logs folder of the Apache installation.


4.4.6. Logon problems (ORACLE backend)

If you are using an ORACLE backend and are experiencing logon problems after an BMFO upgrade, check that you are using the "===" operator in dbx_connect.php instead of "==".


Index

A

access control, Access Control
administration, Administration
aggregation, Aggregation
Aggregation, Empty Summary Well Production Report
Apache, Webserver, Webserver
httpd.conf, Webserver, php.ini
Apache TOMCAT, TOMCAT

B

backend, Database Backend
ORACLE, ORACLE, ORACLE
ORACLE XE, ORACLE XE
PostgreSQL, PostgreSQL, PostgreSQL Backend

C

configuration, Configuration
access control, Access Control
aggregation, Aggregation
dataobject.ini, BMFO
dbx_config.php, Configuration
dbx_connect.php, BMFO, Servlet

D

data
loading, Data Loading
database, Database Backend
ORACLE, ORACLE, ORACLE
ORACLE XE, ORACLE XE
PostgreSQL, PostgreSQL, PostgreSQL Backend
DLL, Unable to load dynamic library

F

FAQ, FAQ
files
databobject.ini, BMFO
dbx_config.php, Configuration
dbx_connect.php, BMFO, Servlet
httpd.conf, Webserver, php.ini
php.ini, php.ini
fonts, Fonts

G

general, General

H

hardware, Hardware

I

installation, Installation, ORACLE
Apache, Webserver, Webserver
BMFO, BMFO Installer With ORACLE, BMFO Installer With PostgreSQL
Java 2 Software Development Kit, Java 2 Software Development Kit
Linux, Manual Installation
manual, Manual Installation
ORACLE, ORACLE
ORACLE XE, ORACLE XE
PHP, PHP, PHP
PostgreSQL, PostgreSQL Backend, PostgreSQL
TOMCAT, TOMCAT
Webserver, Webserver
introduction, Introduction

J

Java 2 Software Development Kit, Java 2 Software Development Kit
JgGraph, JpGraph, JPGraph

L

Linux, Manual Installation
logon, Logon problems (ORACLE backend)

M

mailing list, BMFO info mailing list
maintenance, Regular Maintenance

O

ORA-12520, ORA-12520
ORACLE, ORACLE, ORACLE, Logon problems (ORACLE backend)
ORACLE XE, ORACLE XE

P

password
default, Change Default Password
PDF, Empty Summary Well Production Report, The PDF reports do not work
PEAR, PEAR
PHP, PHP, PHP, PHP
PEAR, PEAR
php.ini, php.ini
PostgreSQL, PostgreSQL, PostgreSQL Backend

R

reference, Reference
regular maintenance, Regular Maintenance
report
Summary Well Production, Empty Summary Well Production Report
requirements, Requirements

S

Servlet, Servlet
software, Software
Summary Welll Production Report, Empty Summary Well Production Report
support
mailing list, BMFO info mailing list
tracker, Support Tracker

T

TOMCAT, TOMCAT
troubleshooting, Troubleshooting
Troubleshooting
FAQ, FAQ

U

update, Updating
user
management, User Management, Access Control
user account
default, Change Default Password

W

WIS, WIS Link