Why... Why... Why?
This blog is dedicated to documenting error resolution and other tidbits that I discover while working as a Consultant in the Oracle EPM (Hyperion) field. As much of my job revolves around issue resolution, I see an opportunity to supplement the typical troubleshooting avenues such as the Oracle Knowledgebase and Oracle Forums with more pinpointed information about specific errors as they are encountered. Beware, the information found in this blog is for informational purposes only and comes without any warranty or guarantee of accuracy.

EPMVirt: Create your own Oracle Hyperion Virtual Environment:

Monday, February 23, 2015

HFM Architecture

There seems to be great deal of changes in the HFM release for Linux. I have reviewed the typical Oracle docs for info and did not find anything detailing the architecture. I figure it is worth fleshing out what I have learned. Keep in mind that I do not have any special internal knowledge so this is all just speculation based on observation.

The main tier which the user interacts with is the familiar WebLogic ADF application. This is pretty familiar to prior versions so I will gloss over this.

Moving into the application layer, the primary interface is the Java based HsxServer application. It is involved when you use LCM, create/add/delete or interact with HFM through Workspace. In Oracle terms, this is also referred to as JHsxServer (Java based). The main Java application class is oracle.epm.fm.hsxserver.HsxServer. The server does not perform any of the actual calculations. It spawns another process to act as the main calculation engine.

The HsxServer process kicks off a separate process for each HFM application, called xfmdatasource. The xfmdatasource is written in C and seems to have been ported to Unix via some abstraction layers. There is still a very Windows feel to the process, as you will see.

To start let's begin by investigating xfmdatasource.
Start with a ps listing:
 6483 oracle    20   0 1501m  54m  32m S 14.3  1.1   0:00.58 xfmdatasource.exe

Using the pid we can get the command line and environment variables used to start the process.

[oracle@EPMVirt ~]$ cat /proc/6483/cmdline

One thing to note here is the various ports xfmdatasource uses. Also useful is the logging location. To investigate errors during startup you could look in this folder. However this only works if the process starts up enough to initialize the logger.

Taking a look at the environment variables one can see some hints at ODBC and something called MW... 
xargs -n 1 -0 < /proc/6483/environ

What is the MW? MainWin...

Poking around in the MWHOME folder you can see some utilities to get a better idea. 
 reg - an mwadm command, administers the MainWin System Core (MSC)
         registry services.

Usage: mwadm command [parameters]
Following is the list of commands supported by the mwadm utility:

version displays the version number of the MSC.
help            displays help on using mwadm and its commands.
stop            stops all MSC services in an orderly manner.
start           manually starts all MSC services.
status          provides vital signs of the MSC services.
log             administers the MSC logs.
sec             administers MSC DCOM security settings.
reg             administers the MSC registry service.

export MWREGISTRY=/home/oracle/.mw/hklm_amd64_linux.bin

[oracle@EPMVirt bin]$ ./mwadm status
Run-time mode       : professional
Core Services status: running
Core Data Directory : /home/oracle/.mw/core_data/EPMVirt
RPC Port            : dynamic
[oracle@EPMVirt bin]$

Here are the unix processes involved:
[oracle@EPMVirt bin]$ ./mwadm reg -ps
uid:    500     pid:   6553     hkcu: /home/oracle/.mw/core_data/EPMVirt/.mw/hkcu.bin
uid:    500     pid:   6483     hkcu: /home/oracle/.mw/hkcu.bin
[oracle@EPMVirt bin]$

The next question to answer is how is MainWin used by xfmdatasource?

Further investigation uncovers a file, hfm_post_install_steps.sh

Towards the end of the script we see some references to MWHOME

echo "Sourcing the mainwin runtime environment required for registration ..."
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$EPM_ORACLE_HOME/products/FinancialManagement/Server
export MWHOME=$EPM_ORACLE_HOME/products/FinancialManagement/Server/mw
source $MWHOME/setmwruntime

echo "Registering COM objects ...."
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhfmcassecurity.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsxdssecurity.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsxsecurity.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsvsystemactivity.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsvsharedappdata.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsxsystemconfig.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsvscriptengine.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsvdsmemberlistscript.so
regsvr32 -c -nodisplay $EPM_ORACLE_HOME/products/FinancialManagement/Server/libhsvdsrulesom.so

What is going on here? Essentially after HFM is installed it registers COM objects using regsvr32. What is regsvr32 and what's it doing on Linux? This is part of the MainWin installation 
located in /u0/Oracle/Middleware/EPMSystem11R1/products/FinancialManagement/Server/mw/bin-amd64_linux_optimized/regsvr32

Finally, this reveals the purpose of MainWin - to house the simulated Windows registry components for COM objects required by HFM xfmdatasource process.

Next, let's shift away from MainWin for a bit and focus on the dependencies for xfmdatasource.

the xfmdatasource.exe process has the boost libraries as a prerequisite:
[oracle@EPMVirt ~]$ ldd /u0/Oracle/Middleware/EPMSystem11R1/products/FinancialManagement/Server/xfmdatasource.exe | grep boost
[oracle@EPMVirt ~]$

What is libboost?

Boost is essentially an open source set of C libraries focusing on being portable between different platforms. HFM uses boost to be more platform independent. Specifically, it looks like Boost is used in a lot of low level calls like threading, file system access. Presumably, code written using Boost would work on Linux and Windows, providing portability without having to rewrite code.

One last thing we discover looking at the xfmdatasource environment is the ODBC datasource dependency. Now let's investigate the ODBC piece. We are familiar with ODBC from Essbase drill through. However, this is the first it is being used with HFM. 

The main configuration takes place in a file called odbc.ini

[oracle@EPMVirt Oracle]$ cat ./Middleware/EPMSystem11R1/common/ODBC-64/Merant/7.1/odbc.ini
[ODBC Data Sources]
Oracle Wire Protocol=DataDirect 7.1 Oracle Wire Protocol


[Oracle Wire Protocol]
Description=DataDirect 7.1 Oracle Wire Protocol
[oracle@EPMVirt Oracle]$

The Hyperion configuration actually sets up a new TNS connection named HFMTNS located at /u0/Oracle/Middleware/user_projects/config/dbclient/tnsnames.ora. 

export TNS_ADMIN=/u0/Oracle/Middleware/user_projects/config/dbclient

[oracle@EPMVirt Oracle]$ tnsping HFMTNS

TNS Ping Utility for Linux: Version - Production on 23-FEB-2015 01:52:34

Copyright (c) 1997, 2013, Oracle.  All rights reserved.

Used parameter files:

Used TNSNAMES adapter to resolve the alias
OK (0 msec)
[oracle@EPMVirt Oracle]$

Sometimes it may be necessary to test the ODBC connection to ensure connectivity and help with troubleshooting. You can use the unix utility isql for basic connectivity.

First, setup the utility:
yum install -y unixODBC
ln -fs /u0/Oracle/Middleware/EPMSystem11R1/common/ODBC-64/Merant/7.1/odbc.ini ~/.odbc.ini
export LD_LIBRARY_PATH=/u0/Oracle/Middleware/EPMSystem11R1/common/ODBC-64/Merant/7.1/lib/

Next, try to connect:
[oracle@EPMVirt ~]$ isql -v "Oracle Wire Protocol" EPM_HSS PWD
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |

Trying apparently one step to far! Not able to perform any queries due to licencing restrictions. 
SQL> select max(starttime) from SMA_AUDIT_FACT;
[DataDirect][ODBC Oracle Wire Protocol driver]The DataDirect product you are attempting to access has been provided to you by Oracle for exclusive use with Oracle products.  You are not licensed to use this product with any application other than Oracle products.   If you would like to purchase this product for some other use, please call 800-876-3101 or visit DataDirect at www.datadirect.com
| MAX(STARTTIME)            |
|                           |
SQLRowCount returns -1
1 rows fetched


In conclusion, the post describes how HsxServer depends on xfmdatasource.exe. Some of the dependencies of xfmdatasource are Boost, MWHOME, and ODBC. Knowing more about these dependencies can greatly help in understanding the architecture.


  1. Thanks Nicholas, great information!

  2. Interesting findings... But according to Oracle HFM is using TCP connectivity between processes instead of DCOM (see here: https://blogs.oracle.com/pa/entry/financial_management_11_1_2). "MW" is short for MainWin, a cross-platform framework now known as Mainsoft (see http://www.mainsoft.com/content/mainsoft-unix-and-linux-overview ). Mainsoft for Linux/Unix is also used in Siebel products (and also by SAP!) so it's not a surprise that Oracle chose to use it for porting the old Windows-centric HFM code to Linux.

    1. Perhaps I should have written COM rather than DCOM. The hfm post install script does mention,
      echo "Registering COM objects ....", which is why the MainWin simulated registry is needed. I'll change this. Thanks