BMFO Administration Guidebmfo.sourceforge.net/doc/administration/bmfo...Figure 7. Apache Install In the dialog shown in Figure 7, click Install. Tip If the Apache installation fails

BMFO Administration GuideMaher Abdel Karim

Abdulqader Jaradat

Steffen Macke

Baha Faqih

BMFO Administration GuideMaher Abdel KarimAbdulqader JaradatSteffen MackeBaha Faqih

Published $Date: 2006-09-26 14:06:35 +0300 (Tue, 26 Sep 2006) $Copyright © 2003 - 2004 OMS Project, DORSCH Consult, NGWACopyright © 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.2or 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).

http://www.gnu.org

Table of ContentsGeneral ................................................................................................................................... 1

1. Introduction ................................................................................................................... 12. Requirements ................................................................................................................. 1

2.1. Hardware ............................................................................................................. 12.2. Software .............................................................................................................. 1

2.2.1. JpGraph ...................................................................................................... 12.2.2. PHP ........................................................................................................... 2

2.3. Database Backend .................................................................................................. 22.3.1. ORACLE .................................................................................................... 22.3.2. PostgreSQL ................................................................................................. 2

Reference ................................................................................................................................ 31. Installation ..................................................................................................................... 3

1.1. Common Steps ...................................................................................................... 31.1.1. Webserver ................................................................................................... 31.1.2. Java 2 Software Development Kit ...................................................................101.1.3. TOMCAT ..................................................................................................15

1.2. Database Backend Installation .................................................................................221.2.1. ORACLE ...................................................................................................221.2.2. ORACLE XE ..............................................................................................251.2.3. PostgreSQL Backend ....................................................................................31

1.3. Installer-based Installation ......................................................................................421.3.1. PHP ..........................................................................................................421.3.2. BMFO Installer With ORACLE .....................................................................461.3.3. BMFO Installer With PostgreSQL ...................................................................50

1.4. Manual Installation ...............................................................................................551.4.1. Database Backend ........................................................................................551.4.2. ORACLE ...................................................................................................561.4.3. PostgreSQL ................................................................................................561.4.4. Webserver ..................................................................................................561.4.5. PHP ..........................................................................................................561.4.6. PEAR ........................................................................................................581.4.7. JPGraph .....................................................................................................581.4.8. Fonts .........................................................................................................581.4.9. BMFO .......................................................................................................581.4.10. Servlet .....................................................................................................58

1.5. Change Default Password .......................................................................................592. Administration ..............................................................................................................59

2.1. Configuration .......................................................................................................592.2. User Management .................................................................................................592.3. Access Control .....................................................................................................592.4. Aggregation .........................................................................................................592.5. Data Loading .......................................................................................................592.6. WIS Link ............................................................................................................602.7. Regular Maintenance .............................................................................................60

3. Updating ......................................................................................................................603.1. From 1.2.3 to 1.2.4 ................................................................................................613.2. From 1.2.2 to 1.2.3 ................................................................................................613.3. From 1.2.1 to 1.2.2 ................................................................................................613.4. From 1.1.0 to 1.2.1 ................................................................................................623.5. From 1.0.8 to 1.1.0 ................................................................................................633.6. From 1.0.7 to 1.0.8 ................................................................................................643.7. From 1.0.6 to 1.0.7 ................................................................................................643.8. From 1.0.5 to 1.0.6 ................................................................................................64

4. Troubleshooting .............................................................................................................654.1. BMFO info mailing list ..........................................................................................654.2. Support Tracker ....................................................................................................654.3. Complete Uninstallation .........................................................................................65

iv

4.4. FAQ ...................................................................................................................664.4.1. Empty Summary Well Production Report .........................................................664.4.2. ORA-12520 ................................................................................................664.4.3. Unable to load dynamic library .......................................................................664.4.4. Wrong PDF Report URl ................................................................................674.4.5. The PDF reports do not work .........................................................................674.4.6. Logon problems (ORACLE backend) ..............................................................67

Index .....................................................................................................................................68

BMFO Administration Guide

v

List of Figures1. Apache Wizard ...................................................................................................................... 42. Apache License ..................................................................................................................... 53. Apache Readme .................................................................................................................... 64. Apache Information ............................................................................................................... 75. Apache Setup Type ................................................................................................................ 86. Apache Location ................................................................................................................... 97. Apache Install ......................................................................................................................108. Java License Agreement .........................................................................................................119. Java Development Kit Custom Setup ........................................................................................1210. Java Runtime Environment Custom Setup ................................................................................1311. Browser Registration ...........................................................................................................1412. Java Installation Completed ..................................................................................................1513. Apache TOMCAT Setup ......................................................................................................1614. TOMCAT License Agreement ...............................................................................................1715. TOMCAT Components ........................................................................................................1816. TOMCAT Install Location ....................................................................................................1917. TOMCAT Configuration ......................................................................................................2018. TOMCAT JVM Selection .....................................................................................................2119. TOMCAT Installation Finish .................................................................................................2220. ORACLE Installation Type ...................................................................................................2321. ORACLE Database Configuration ..........................................................................................2422. ORACLE Database Identification ..........................................................................................2523. ORACLE XE Welcome Page ................................................................................................2624. ORACLE XE License Agreement ..........................................................................................2725. ORACLE XE Installation Folder ............................................................................................2826. ORACLE XE Password .......................................................................................................2927. ORACLE XE Summary .......................................................................................................3028. ORACLE XE Installation Complete .......................................................................................3129. PostgreSQL Setup ...............................................................................................................3230. Installation Notes ................................................................................................................3331. Choose Installation Options ..................................................................................................3432. Service Configuration ..........................................................................................................3533. Account Error .....................................................................................................................3534. Password ...........................................................................................................................3635. Successfully granted the 'Logon as a service' right .....................................................................3636. Initialise Database Cluster ....................................................................................................3737. Enable procedural languages .................................................................................................3838. Enable contrib modules ........................................................................................................3939. Enable PostGIS ..................................................................................................................4040. Ready to Install ...................................................................................................................4141. Installation complete ............................................................................................................4242. PHP License ......................................................................................................................4343. PHP Components ................................................................................................................4444. PHP Location .....................................................................................................................4545. PHP Installation Complete ....................................................................................................4646. Choose Components (Oracle) ................................................................................................4747. ORACLE Database Connection .............................................................................................4848. TOMCAT Connection (PostgreSQL) ......................................................................................4949. Install Location ...................................................................................................................5050. BMFO License Agreement ...................................................................................................5151. Choose Components (PostgreSQL Backend) ............................................................................5252. PostgreSQL Database Connection ..........................................................................................5353. TOMCAT Connection (ORACLE) .........................................................................................5454. Install Location ...................................................................................................................55

vi

GeneralGeneral information for BMFO administrators.

1. IntroductionThis document describes how to setup and administer the Bulk Meter Flow and Operations (BMFO) applicationversion 1.2.4.

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

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 applica-tion 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 developmentguides

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

2.1. HardwareA PC with at least two GHz CPU speed and one GB RAM is required to run the BMFO application. Note that de-pending on the size of the data, number of concurrent users and database backend, the actual hardware require-ments can be much higher.

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

1

http://bmfo.sourceforge.net

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 li-cense 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 BackendA relational database management system supported by the PHP dbx extension is required in order to run the ap-plication. 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 ht-tp://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

General

2

http://www.aditus.nu/jpgraph/

http://www.oracle.com/technology/software/products/database/xe/index.html

http://www.oracle.com/technology/software/products/database/xe/index.html

http://www.postgresql.org

ReferenceThe reference for BMFO administrators.

1. InstallationThis 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 in-staller does not work for you. Installation steps that are common to both installation types are described underSection 1.1.

In the following, $BMFO and %BMFO% reference the directory where the application is installed. Replace this withthe actual path or set an environment variable. $BMFO is a bash environment variable and %BMFO% a Windowsenviroment 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 StepsThis section describes BMFO installation steps that are common to both the installer-based and manual installa-tion.

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

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

Tip

If you are running Skype, you may want to shutdown Skype while you are installing Apache asSkype 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 usingport 80, simply edit httpd.conf to use another port (e.g. "Listen 81" instead of "Listen 80" andrun 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 theApache website: http://httpd.apache.org.

3

http://httpd.apache.org

Figure 1. Apache Wizard

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

Reference

4

Figure 2. Apache License

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

Reference

5

Figure 3. Apache Readme

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

Reference

6

Figure 4. Apache Information

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

Reference

7

Figure 5. Apache Setup Type

Verify the selection in Figure 5 and click Next >.

Reference

8

Figure 6. Apache Location

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

Tip

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

Reference

9

Figure 7. Apache Install

In the dialog shown in Figure 7, click Install.

Tip

If the Apache installation fails because another application is using port 80, you can use the follow-ing 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 pro-cess id.

If you would like to use the Apache webserver distributed with ORACLE, please consult the ORACLE document-ation 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 ver-sions 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.

Reference

10

http://java.sun.com

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

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 shownin Figure 8 and click Next >.

Reference

11

Figure 9. Java Development Kit Custom Setup

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

Reference

12

Figure 10. Java Runtime Environment Custom Setup

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

Reference

13

Figure 11. Browser Registration

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

Reference

14

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 containersshould work but are not described in detail.

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

Note

Java needs to be installed before you can run TOMCAT.

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

Reference

15

http://tomcat.apache.org

http://tomcat.apache.org/download-55.cgi

http://tomcat.apache.org/download-55.cgi

Figure 13. Apache TOMCAT Setup

In Figure 13 click Next >.

Reference

16

Figure 14. TOMCAT License Agreement

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

Reference

17

Figure 15. TOMCAT Components

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

Reference

18

Figure 16. TOMCAT Install Location

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

Reference

19

Figure 17. TOMCAT Configuration

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

Caution

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

Tip

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

Reference

20

Figure 18. TOMCAT JVM Selection

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

Reference

21

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

You don't have to follow the instructions in this chapter if you are using ORACLE XE or Postgr-eSQL 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).

Reference

22

Figure 20. ORACLE Installation Type

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

Reference

23

Figure 21. ORACLE Database Configuration

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

Reference

24

Figure 22. ORACLE Database Identification

Caution

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

Caution

Restart the system before continuing with the BMFO installation.

1.2.2. ORACLE XE

Caution

You don't have to follow the instructions in this chapter if you are using ORACLE or PostgreSQL asthe 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).

Reference

25

Figure 23. ORACLE XE Welcome Page

On the page displayed in Figure 23 click Next >.

Reference

26

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 24if you agree to the license. Click Next >.

Reference

27

Figure 25. ORACLE XE Installation Folder

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

Reference

28

Figure 26. ORACLE XE Password

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

Caution

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

Reference

29

Figure 27. ORACLE XE Summary

Review the settings as shown in Figure 27 and click Install

Reference

30

Figure 28. ORACLE XE Installation Complete

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

Caution

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

1.2.3. PostgreSQL Backend

This section describes how to install PostgreSQL for Windows.

Caution

You don't have to follow the instructions in this chapter if you are using ORACLE or ORACLE XEas 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 fromhttp://www.postgresql.org.

Run the PostgreSQL installer and select the English language.

Reference

31

http://www.postgresql.org

Figure 29. PostgreSQL Setup

Click Next >.

Reference

32

Figure 30. Installation Notes

Press Next > after reading the installation instructions.

Reference

33

Figure 31. Choose Installation Options

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

Reference

34

Figure 32. Service Configuration

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

Figure 33. Account Error

Select Yes.

Reference

35

Figure 34. Password

Accept the random password by clicking OK.

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

Click on OK.

Reference

36

Figure 36. Initialise Database Cluster

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

Caution

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

Reference

37

Figure 37. Enable procedural languages

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

Reference

38

Figure 38. Enable contrib modules

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

Reference

39

Figure 39. Enable PostGIS

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

Reference

40

Figure 40. Ready to Install

Click Next >.

Reference

41

Figure 41. Installation complete

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

1.3. Installer-based InstallationInstructions for a BMFO installation on Windows using the BMFO installer. The installer automates the installa-tion 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 ht-tp://bmfo.sourceforge.net. If you don't want to use the BMFO scripting installer to install PHP, please refer to Sec-tion 1.4.

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

Reference

42



Figure 42. PHP License

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

Reference

43

Figure 43. PHP Components

Click Next >.

Tip

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

Reference

44

Figure 44. PHP Location

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

Reference

45

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

Reference

46

http://bmfo.sourceforge.net/

• Scheduled Cleanup

Figure 46. Choose Components (Oracle)

Click Next >.

Reference

47

Figure 47. ORACLE Database Connection

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

Reference

48

Figure 48. TOMCAT Connection (PostgreSQL)

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

Caution

Unlike shown in Figure 53, you will most probably be using a different port than 8080 because OR-ACLE is occupying port 8080. Review the port number critically. Check that TOMCAT is up andrunning 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.

Reference

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

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

It is recommended that you change the default password "bmfo" for the ORACLE user bmfo as soonas 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 areinstalling with and ORACLE or ORACLE XE backend, please refer to Section 1.3.2.

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

Reference

50

http://localhost/bmfo/

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.

Reference

51

Figure 51. Choose Components (PostgreSQL Backend)

Click Next >.

Caution

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

Reference

52

Figure 52. PostgreSQL Database Connection

Click Next >.

Reference

53

Figure 53. TOMCAT Connection (ORACLE)

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

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

Reference

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

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

Warning

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

1.4. Manual InstallationGeneral installation instructions to run BMFO on Windows. Similar installation steps are required on other operat-ing systems, like Linux.

1.4.1. Database Backend

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

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

Reference

55

1.4.2. ORACLE

Note

%BMFO% in this section refers to the actual BMFO installation directory. If this path containsspaces, 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

The default password for the ORACLE user bmfo is "bmfo". For security reasons it should bechanged 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 bmfocreateuser -U postgres bmfocreatelang -d bmfo -U postgres plpgsqlpsql -d bmfo -U bmfo -f %BMFO%\script\create_bmfo_ddl.sqlpsql -d bmfo -U postgres -f %BMFO%\script\postgresql_ddl.sqlpsql -d bmfo -U postgres -f %BMFO%\script\create_views.sql

Warning

The default password for the PostgreSQL user bmfo is "bmfo". For security reasons it should bechanged 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 theApache level. See the Apache documenation for the details.

1.4.5. PHP

Reference

56

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

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): ht-tp://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.dllextension=php_dbx.dllextension=php_gd2.dllextension=php_gettext.dllextension=php_iconv.dllextension=php_oci8.dllextension=php_pgsql.dll

[mail function]SMTP = igwa_2sendmail_from = [email protected]

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 tophp.ini:

default_charset = "utf-8";

Reference

57

http://www.php.net

http://www.php.net/get/php-5.1.4-Win32.zip/from/a/mirror

http://www.php.net/get/php-5.1.4-Win32.zip/from/a/mirror

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 .phpAction application/x-httpd-php "/php/php-cgi.exe"

1.4.6. PEAR

Install the following PEAR packages:

PagerDataObjectDataObject_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 avail-able to%BMFO%\jpgraph

1.4.8. Fonts

Caution

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

1.4.9. BMFO

Copy %BMFO%\conf\dataobject.ini.oracle or %BMFO%\conf\dataobject.ini.postgresqlto %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 in-clude/dbx_connect.php if necessary.

Reference

58

http://pear.php.net

http://www.aditus.nu/jpgraph/

1.5. Change Default Password

Important

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

2. AdministrationDescription of various BMFO administration tasks.

2.1. ConfigurationBMFO 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 strSer-vletUrl with the name of the server.

2.2. User ManagementWhen using the ORACLE backend, grant the role "bmforole" to new users.

2.3. Access ControlBMFO 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 toany new full control user and bmforeadonly role which you have to assign it from SQL for any new read onlyuser.

Access for a user to an operational area is granted by inserting a record to the UserOperationalArea tablecontaining 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 (selectUserOperationalArea_seq.nextval, 'Username', codedvalue from OperationalArea)

2.4. AggregationBMFO 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 follow-ing example:

update Meter set Aggregation=FacilityID

See the user guide for details.

2.5. Data LoadingThe admin folder of the BMFO distribution contains a utility script that allows loading of a dBase (.dbf) file tothe meter table.

Reference

59

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

Tip

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

2.6. WIS LinkInformation 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 withWIS 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 statementslike 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 lookslike this:

create database link wislink connect to usernameidentified 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/cre-ate_wis_views.sql.

Deletion of existing Meter, OperationaArea and AdministrativeArea together with the insertion ofnew 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 MaintenanceDelete the records in the ReportImage table from time to time. These are temporary records that are only usedto reference the image names.

3. Updating

Reference

60

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

Caution

Please backup the database before updating.

3.1. From 1.2.3 to 1.2.4To 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.3BMFO 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 wherei.NetworkOID = i2.NetworkOID))

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

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

To upgrade the application, do the following:


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:

Reference

61

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

}


3. Update the Servlet.

3.4. From 1.1.0 to 1.2.1The major change in version 1.2.1 is the switch to PHP 5. It is recommended to completely remove PHP 4 fromthe system before installing BMFO Scripting 5.1.4. If necessary, see the complete uninstallation instructions (Sec-tion 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:

Reference

62

• 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.0Please follow the steps below to update the system:

1. Install JDK 1.5.0-07.

2. Install TOMCAT 5.5.17


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

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



• BMFO


• Servlet

Note

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

Reference

63

Caution

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


1. Run the DCMMS Installer.


Warning



• BMFO

• Upgrade ORACLE

• Servlet



• BMFO


• Servlet

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


1. Install JDK 1.5.0.

2. Install TOMCAT 5.5.


4. Install DCMMS Scripting (PHP) 4.4.1.

5. Run the DCMMS Installer.


Reference

64

Warning



• BMFO

• Upgrade ORACLE

• Servlet




• BMFO


• Servlet


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. TroubleshootingThis section gives help to solve problems with the BMFO installation.

4.1. BMFO info mailing listThe BMFO info mailing list may provide help to solve problems, either through the archives which are availableunder http://sourceforge.net/mailarchive/forum.php?forum_id=32236. or by sending an email to<[email protected]>.

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

Caution

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

4.3. Complete UninstallationThe uninstallation steps described below will completely remove BMFO and all of its components.

Warning

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

Reference

65

http://sourceforge.net/mailarchive/forum.php?forum_id=32236


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. FAQFrequently 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 Reportsare 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:listenercould 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:

Reference

66

• 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 orc:\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 insteadof the real server name), make sure that strServletUrl is configured correctly (Section 2.1).

4.4.5. The PDF reports do not work

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 ofthe 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 thatyou are using the "===" operator in dbx_connect.php instead of "==".

Reference

67

IndexAaccess control, 59administration, 59aggregation, 59Aggregation, 66Apache, 3, 56

httpd.conf, 56, 58Apache TOMCAT, 15

Bbackend, 2

ORACLE, 2, 22ORACLE XE, 25PostgreSQL, 2, 31

Cconfiguration, 59

access control, 59aggregation, 59dataobject.ini, 58dbx_config.php, 59dbx_connect.php, 58, 58

Ddata

loading, 59database, 2

ORACLE, 2, 22ORACLE XE, 25PostgreSQL, 2, 31

DLL, 66

FFAQ, 66files

databobject.ini, 58dbx_config.php, 59dbx_connect.php, 58, 58httpd.conf, 56, 58php.ini, 57

fonts, 58

Ggeneral, 1

Hhardware, 1

Iinstallation, 3, 22

Apache, 3, 56BMFO, 46, 50Java 2 Software Development Kit, 10Linux, 55

manual, 55ORACLE, 56ORACLE XE, 25PHP, 42, 56PostgreSQL, 31, 56TOMCAT, 15Webserver, 3

introduction, 1

JJava 2 Software Development Kit, 10JgGraph, 1, 58

LLinux, 55logon, 67

Mmailing list, 65maintenance, 60

OORA-12520, 66ORACLE, 2, 22, 67ORACLE XE, 25

Ppassword

default, 59PDF, 66, 67PEAR, 58PHP, 2, 42, 56

PEAR, 58php.ini, 57

PostgreSQL, 2, 31

Rreference, 3regular maintenance, 60report

Summary Well Production, 66requirements, 1

SServlet, 58software, 1Summary Welll Production Report, 66support

mailing list, 65tracker, 65

TTOMCAT, 15troubleshooting, 65Troubleshooting

FAQ, 66

U

68

update, 60user

management, 59, 59user account

default, 59

WWIS, 60

Index

69

Documents

BMFO Administration Guidebmfo.sourceforge.net/doc/administration/bmfo...Figure 7. Apache Install In the dialog shown in Figure 7, click Install. Tip If the Apache installation fails