Post on 13-Jun-2020
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).
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
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
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
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
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
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
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
• 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
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 = bmfoadministrator@ngwa.com.jo
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
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
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:
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:
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);
}
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.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
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 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
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
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.
3.6. From 1.0.7 to 1.0.8Please 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 bmfouser.
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.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.
3.8. From 1.0.5 to 1.0.6Please 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 bmfouser.
Reference
64
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. 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<bmfo-info@lists.sourceforge.net>.
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
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