Integrating Essbase With Your Product

Essbase Directory Structure

A PC that has the Spreadsheet Add-in or Application Manager programs installed uses a predefined directory structure. The exact name of the root directory depends on the name selected during user installation, but the structure under the root directory is always the same.

The following figure shows this structure:

The root directory can have any name the user chooses at installation time. The default is \hyperion\essbase. When an Essbase client program is first loaded, it finds the root directory by checking the ARBORPATH environment variable. This variable is defined at installation time to point to the directory into which the user installed the Essbase files.

Note:The root directory name cannot include spaces.

Portions of the API use the ARBORPATH environment variable under certain conditions, so you need to be aware of whether or not the end user of your program has ARBORPATH defined. You can set up your program so that setting the ARBORPATH environment variable is not necessary for your users.

Customizing the Run-Time Environment

The Essbase API allows you to customize access to some of the API features, so you can integrate these features with your programs. Besides customizing the memory management and message handling, you can customized the following paths:

• The path to the Essbase CLIENT directory.
• The path to the Essbase Message Database.
• The path to the Essbase help file.

You can change each of these paths by passing an entry into the appropriate field of the Essbase API initialization structure when you call EsxInit() . Since you can change these paths, you can install these directories and files anywhere you like and rename them if you desire.

Most likely, you will want to place the files associated with your program in a specific directory. If this is the case, you should set these paths explicitly in ESX_INIT_T.

An alternative to setting the paths explicitly is to rely on the user's ARBORPATH and ARBORMSGPATH environment variables. When you call EsxInit(), the API can define the paths in the initialization structure based on the root directory of any pre-existing Essbase files (ARBORPATH) or on ARBORMSGPATH.

Note: All settings in the initialization structure apply only to the calling program's instance of the API library. Custom settings within your program do not affect any other programs using the API library.

Customizing the Path to the Essbase CLIENT Directory

The API uses the CLIENT directory to store any local application or database related files (such as database outlines or report scripts). The directory structure within the CLIENT directory mirrors that of the \ESSBASE\APP directory on the Essbase server. Each application has its own sub-directory, and within each application sub-directory, each database in that application has a separate sub-directory. The list of applications and databases need not match that of any particular server.

Although the structure of the application and database sub-directories is fixed, you can customize the client directory under which the application directories are created.

Setting the Local Path Field of the Initialization Structure

The primary way to set the client directory path is to explicitly set the LocalPath field in the API initialization structure to point to a string indicating the full path name of the CLIENT directory. This setting causes the API to look in this directory for all client application and database related files. For example, to set the CLIENT directory to be D:\PRODUCT\CLIENT you would make the following change to the initialization structure:ESS_INIT_T InitStruct;Initstruct.LocalPath = "D:\PRODUCT";

For Visual Basic,Dim pInit as eSB_INIT_TpInit.LocalPath="D:\PRODUCT"

A secondary way to set the client directory path is to set LocalPath to NULL. By default, Essbase then uses the ARBORPATH environment variable to determine the path to the CLIENT directory.

Customizing the Path to the Essbase Message Database

Essbase uses a message database file called, by default, ESSBASE.MDB. The API enables you to store the Essbase message database file with any file name and in any directory path you choose. You must use the ESSBASE.MDB file, but you can rename it if you wish. Using the MessageFile field of ESX_INIT_T, you can explicitly set the location and name of the message database.

Setting the MessageFile Field of the Initialization Structure

You can change the Essbase message database file name and directory path by setting the MessageFile field in the initialization structure to point to a string indicating the full path and file name of the message database. This causes the Essbase message system to look for the path and file name specified whenever it needs to reference the text of an Essbase system message. For example, if you wanted to call the message database file PRODUCT.MDB, and install it in the C:\PRODUCT\MESSAGE directory, you would make the following change to the initialization structure: ESS_INIT_T InitStruct;Initstruct.MessageFile = "C:\PRODUCT\MESSAGE\PRODUCT.MDB";

For Visual Basic,

If you don't want to set the name and location explicitly, you can set the MessageFile field to NULL. By default, the API looks for a fully qualified file name in the ARBORMSGPATH environment variable on the user's machine. If this variable is not set, the API uses the ARBORPATH environment variable, appends \BIN to it, and uses that directory name to look for ESSBASE.MDB.

Setting the ARBORMSGPATH Variable

If you want to use the ARBORMSGPATH environment variable, place an ARBORMSGPATH statement in your AUTOEXEC.BAT file if you are programming on a 32-bit Windows platform. Under UNIX, you set this variable in the environment script corresponding to your shell. See the Installation Notes topic for more information. To set the path and file name to C:\PRODUCT\MESSAGE\PRODUCT.MDB you would use the following statement: ARBORMSGPATH = C:\PRODUCT\MESSAGE\PRODUCT.MDB

If you intend to use the ARBORMSGPATH or the ARBORPATH environment variable, set the MessageFile field in ESX_INIT_T to NULL.

How Essbase Finds the Message Database

Essbase performs the following priority search to find the message database:

1. Essbase uses the directory path and file name specified in the MessageFile field of the initialization structure.
2. If the MessageFile field is set to NULL, Essbase uses the complete file and directory path specified in the ARBORMSGPATH environment variable.
3. If no ARBORMSGPATH variable is defined, Essbase uses the file name ESSBASE.MDB in the directory path specified in the ARBORPATH environment variable, in its BIN sub-directory.
4. If no ARBORPATH variable is defined, Essbase displays an error message.

Customizing the Path to the Essbase Help File

The Essbase API for Windows NT and 32-bit Windows includes a run-time help file called ESSAPIW.HLP for API functions that display dialog boxes, such as EsxAutoLogin(). ESSAPIW.HLP provides context-sensitive help topics for API-generated dialog boxes with Help buttons. If you don't write your own Help file, you can simply supply the API default help file to your users with the product installation.

Setting the HelpFile Field of the Initialization Structure

You can specify the API help file by setting the HelpFile field in the initialization structure to a string indicating the full path and file name of the API help file. The API looks for the help file whenever the user invokes a help screen.

For example, if the API help screens are included in a file called PRODUCT.HLP in the C:\PRODUCT\HELP directory set the initialization structure to the following path: ESS_INIT_T InitStruct;
InitStruct.HelpFile = "C:\PRODUCT\HELP\PRODUCT.HLP";

For Visual Basic, set the path this way:

Dim pInit as ESB_INIT_T
pInit.HelpFile="C:\PRODUCT\HELP\PRODUCT.HLP"

If this field is set to NULL, the API uses the ARBORPATH variable to find the file $ARBORPATH\BIN\ESSAPIW.HLP. If the ARBORPATH variable is not defined, the help file name is set to null, as if there is no help file. This causes an error to appear at run time when the user invokes help.

Creating Your Own On-line Help for AutoLogin

In the Windows NT and 32-bit Windows environments, the EsxAutoLogin() call displays a dialog box that contains a Help button. It also provides access to other dialog boxes with their own Help buttons. Clicking the Help button displays the ESSAPIW.HLP file (or the file specified in ESX_INIT_T), which is shipped with the Essbase API for Windows NT and 32-bit Windows as a default.

You can either use the default or define your own .HLP file. If you create your own help file, specify its path and file name in ESX_INIT_T so that the correct file appears when the user chooses the Help button.

If you plan to use EsxAutoLogin() with your own help file, then you need to include ESSHELP.H in your help project file as follows:

[MAP]
#include <ESSHELP.H>

ESSHELP.H defines the help IDs for the dialog boxes displayed by the API. When you include ESSHELP.H, you need to create topics in your help source files with context strings corresponding to the strings in the header file. For example, you need to create a topic with a context string IDH_SYSTEM_LOGIN_DB for the Essbase System Login dialog box. See ESSHELP.H for a list of context strings you should include.

If you have other context-sensitive help areas in your program, then add additional lines to the MAP section for your additional header files as follows:

[MAP]
#include <ESSHELP.H>
#include <MYHELP.H>

Choosing a Network Protocol

Essbase supports several different network protocols and different network vendor implementations by providing a number of different Essbase network drivers. The driver you need to install depends on the exact hardware, operating system, and network platform of the client machine, and on the Essbase server machine it is connecting to.

You need to determine the required network configuration and install the appropriate driver file.

Network Libraries

When distributing a program written with the Essbase API for Windows NT or 32-bit Windows, your users need a .DLL file that is specific to their network environment. The libraries that provide network support for all Windows NT and 32-bit Windows supported network configurations are included with the API, so you can redistribute them with your API programs. See the Installation Guide for information on supported network configurations.

The API installation program for Windows NT and 32-bit Windows copies two files to the \ESSBASE\API\REDIST directory:

• ESSNET.NP (Named Pipes)
  
• ESSNET.TCP (MS TCP/IP)

When you distribute an API program, you need to provide a .DLL file that corresponds to your user's network protocol. For Windows NT and 32-bit Windows, copy the appropriate file to ESSNET.DLL.

API Files You Need to Ship

For your program to work with Essbase, each client machine that runs your program must have access to the required API run-time files. If the Essbase Spreadsheet Add-in or Application Manager are already installed on a client machine, the relevant files are already available in the $ARBORPATH\BIN directory. Otherwise, you must install them as part of your product's own installation process.

General Description of Files

The files you need to run an Essbase client program are listed below. The letter N is used to identify Windows NT and 32-bit Windows programs.

The files you need to redistribute are located in the API\REDIST directory. On UNIX, if you link with static libraries, you do not need to redistribute the library files. If you link with shared (import) libraries, you also need to redistribute the library files. These files include:

• API library
• Network driver library
• Shared library
• Shared utilities and diagnostics library
• Message database (essbase.mdb)
• API help file (for Windows NT and 32-bit Windows)

For the rest of the files, see your API\REDIST directory.

The Essbase API libraries can exist anywhere on the client machine or on an accessible network file server. In general, you should include all the program executables and Essbase API libraries in a single directory.

To ensure that the operating system can find the libraries at run time, they should either be in the same directory as your executable files, or in another directory included in the user's PATH command. See Essbase Directory Structure for more information.

Platform-by-Platform File Lists

Users of applications programs deployed on Windows NT can install the Runtime Client in order to avoid downloading specific .DLL files. Refer to the Hyperion Essbase Installation Guide for information on installing the Runtime Client.

See API Libraries for a platform-by-platform list of the files you need to redistribute.

API Libraries

The following tables show the files needed to link or run the main, outline, and grid APIs for each supported platform.

Windows NT and Windows 95 (32-bit) API Libraries

ESSAPIN.LIB










ESSOTLN.LIB



ESSGAPIN.LIB

ESBAPIN.DLL (VB)
ESSAPIN.DLL
ESSDT.DLL
ESSNET.DLL
ESSSD.DLL
ESSSHR.DLL
ESSUTL.DLL
GLOBLC32.DLL
\locale files
MSVCRT.DLL

ESBOTLN.DLL (VB)
ESSOTLN.DLL
ESSOTLS.DLL

ESSADDN.DLL (Grid)
ESSCSLN.DLL (Grid)
ESSCSV2N.DLL (Grid)
ESSMBRN.DLL (Grid)
ESSRETWN.DLL (Grid)
ESSVISCN.DLL (Grid)
ESSGAPIN.DLL (Grid)
MFC40D.DLL (Grid)
MFCO40D.DLL (Grid)

ESSBASE.MDB
ESSAPIW.HLP

The Windows NT and Windows 95 32-bit ESSNET.DLL is a copy of one of the following files, depending on your network configuration:

• ESSNET.NP (Named Pipes)
  
• ESSNET.TCP (MS TCP/IP)

AIX API Libraries

libessapi.a
libessnet.a
libesssd.a
libessshr.a
libessutl.a


libessotl.a

libesssql.a
libglobalcS.a
/locale files






libesscslS.a (Grid)

essbase.mdb

On AIX, libesscsl.a is a dynamic link library, and libesssql.a is a symbolic link to the dynamic link library.

HP-UX API Libraries

libessapi.a
libessnet.a
libesssd.a
libessshr.a
libessutl.a
libglobalc.a



libessotl.a

libessapi.sl
libessnet.sl
libessotl.sl
libessshr.sl
libesssql.sl
libessutl.sl
libglobalc.sl
/locale files



libesscsl.sl (Grid)

essbase.mdb

Solaris API Libraries

libessapi.a
libessnet.a
libesssd.a
libessshr.a
libessutl.a




libessotl.a

libessapi.so.1
libessnet.so.1
libessotl.so.1
libessshr.so.1
libesssql.so.1
libessutl.so.1
libglobalc.so.1
/locale files



libesscsl.so.1 (Grid)

essbase.mdb

Description of Runtime DLLs

The following table describes the runtime DLLs listed in the previous table:

Installing Your Application Program

When you create an installation for your Essbase API program, you may wish to include the Essbase API support files as part of the installation for your application. Alternately, you can install Hyperion Essbase Runtime Client on the target machine and accept all the environment update options. That process installs all the files needed by the API and sets the PATH variable.

If you decide to include the Essbase API environment setup as part of the installation of your product, you must construct your installation process to install the files required by the Essbase API. The exact steps required depend on your program and on the target operating system. The following steps illustrate a typical installation process:

1. Prompt the user for the root installation drive and directory name, where root represents the name of the installation drive and directory; for example, C:\hyperion\essbase.
2. Create the \root and \root\bin directories.
3. Copy the product executable files to the \root\bin directory.
4. Copy any other product files to the \root directory or any sub-directories.
5. Prompt the user to choose a network protocol.
6. Copy or rename the appropriate Essbase network driver library to the \root\bin directory.
7. Copy the remaining Essbase library files to the \root\bin directory.
8. Copy the Essbase message database to the \root\bin directory.
9. In your operating system environment, define the ARBORPATH environment variable, and make it equivalent to \root\. This step is necessary only if you didn't explicitly set the client directory path in the ESX_INIT_T structure.
10. In your operating system environment, define the ARBORMSGPATH environment variable, and make it equivalent to \root\bin \filename. This specifies the custom directory path and file name for the Essbase message database. This step is necessary only if you didn't explicitly set the message database path in the ESX_INIT_T structure or if the message database cannot be found by using the ARBORPATH environment variable.

Note: These instructions are appropriate for the most common client machines, Windows 95 and Windows 98. Installing on other operating systems requires slightly different steps.

Installing API Programs on Different Platforms

If you install your program on different operating system platforms, be aware that each operating system has slightly different procedures for setting the environment variables, such as PATH, ARBORPATH, and ARBORMSGPATH.

On Windows NT, the environment variables are set in the environment section of the Windows NT System Properties. Access the system variables through the Start > Settings > Control Panel > System > Environment tab. Adding the $ARBORPATH\Bin path declaration to the path variable on Windows NT is equivalent to editing the PATH statement in the AUTOEXEC.BAT file on Windows 95 and Windows 98.

On UNIX systems, environment variables are typically set using login scripts for individual users. The standard practice for setting these variables on UNIX is to provide a script with your installation that sets the appropriate variables and can be included in a user's login script by the system administrator. For more information on setting environment variables, see the Hyperion Essbase Installation Guide .

For Add-in applications programs to work correctly you must specify C:\HYPERION\ESSBASE\BIN before specifying C:\HYPERION\ESSBASE\API\REDIST or C:\HYPERION\ESSBASE\API\LIB in the AUTOEXEC.BAT file or the Windows NT PATH environment variable. Otherwise, you will have to load them manually using the Tools | Add-In menu in the target application.