# Integrating Essbase With Your Product

Essbase Directory Structure
Customizing the Run-Time Environment
Choosing a Network Protocol
API Files You Need to Ship
API Libraries
Installing Your Application Program

## Essbase Directory Structure

A computer 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:

`\root` | Root directory: All Essbase files
`\root\bin` | Binary directory: executables, shared libraries, and other program files
`\root\client` | Client directory: Client application and database files
`\root\client\appname` | Files relating to the application appName (one for each application)
`\root\client\appname\dbname` | Files relating to the database dbName in the application appName (one for each database in the application)

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 customize 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() . Because you can change these paths, you can install these directories and files anywhere you like and rename them if you desire.

You might 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. 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,

`Dim pInit as ESB_INIT_T pInit.MessageFile="C:\PRODUCT\MESSAGE\PRODUCT.MDB"`

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 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 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 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 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, your users need a .DLL file that is specific to their network environment. The libraries that provide network support for all 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 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, rename 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 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)

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 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 API Libraries

Files Needed to Link | Files Needed to Run
--- | ---
Static Libraries | Import | Dynamic/Shared Libraries
N/A |
    ESSAPINU.LIB

    ESSOTLNU.LIB

    ESSGAPINU.LIB
    ESBAPIN.DLL (VB)
    ESSAPINU.DLL
    ESSDTU.DLL
    ESSNETU.DLL
    ESSSDU.DLL
    ESSSHRU.DLL
    ESSUTLU.DLL
    GLOBLC32.DLL
    MSVCIRT.DLL
    MSVCRT.DLL

    ESBOTLN.DLL (VB)
    ESSOTLNU.DLL
    ESSOTLSU.DLL

    ESSADDN.DLL (Grid)
    ESSCSLN.DLL (Grid)
    ESSCSV2N.DLL (Grid)
    ESSMBRN.DLL (Grid)
    ESSRETWN.DLL (Grid)
    ESSVISCN.DLL (Grid)
    ESSGAPINU.DLL (Grid)
    MFC42.DLL (Grid)

    ESSBASE.MDB
    ESSAPIW.HLP
    ESSAPIW.CNT
    \locale files

The Windows 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

Static Libraries | Dynamic Libraries
    libessapiu.a
    libessnetu.a
    libesssdu.a
    libessshru.a
    libessutlu.a
    libessglobu.a

    libessotl.a
    libesssecu.a
    libesssql.a
    libglobalcS.a
    libessopg.a
    libessglobuS.a
    libessapiuS.a
    libesssduS.a
    libessotluS.a
    libessnetuS.a
    libesssm.a
    libesssduS.a
    libessshruS.a
    libessutluS.a
    libesscsluS.a (Grid)

    essbase.mdb (binary message file)
    /locale files (binary files)

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

Static Libraries | Dynamic Libraries
    libessapi.a
    libessnet.a
    libesssd.a
    libessshr.a
    libessutl.a
    libglobalc.a

    libessotl.a
    libessapiu.sl
    libessnetu.sl
    libessopg.sl
    libessotlu.sl
    libesssdu.sl
    libesssecu.sl
    libessshru.sl
    libesssm.sl

    libesssql.sl
    libessutlu.sl
    libessglobu.sl
    /locale files

    libesscsl.sl (Grid)

    essbase.mdb

### Solaris API Libraries

Static Libraries | Dynamic Libraries
    libessapiu.a
    libessglobu.a
    libessnetu.a
    libessotlu.a
    libesssdu.a
    libessshru.a
    libessutlu.a

    libessotl.a
    libessapiu.so.1
    libessnetu.so.1
    libessopg.so.1
    libessotlu.so.1
    libesssdu.so.1
    libesssecu.so.1
    libessshru.so.1
    libesssm.so.1
    libesssql.so.1
    libessutlu.so.1
    libessglobu.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:

Runtime DLL | Description
--- | ---
`ESBAPIN.DLL` | Essbase Visual Basic Main API library.
`ESSAPINU.DLL` | Essbase database API library.
`ESSDTU.DLL` | Drill-Through reports dynamic link library.
`ESSNETU.DLL` | Essbase API network protocol library.
`ESSSDU.DLL` | Essbase system dependent library.
`ESSSHRU.DLL` | Shared API library.
`ESSUTLU.DLL` | Essbase Utility API library.
`GLOBLC32.DLL` | Global C library.
`MSVCRT.DLL` | Microsoft Visual C library.
`ESBOTLN.DLL` | Visual Basic Outline API library.
`ESSOTLN.DLL` | C Outline API library.
`ESSOTLSU.DLL` | Shared Outline API library.
`ESSADDN.DLL` | External Hook Mechanism library.
`ESSCSLN.DLL` | Dialogs for Common Spreadsheet Layer.
`ESSCSV2N.DLL` | Release 2.x compatibility library.
`ESSMBRN.DLL` | Member List library.
`ESSRETWN.DLL` | Essbase Data Retrieval Wizard.
`ESSVISCN.DLL` | Visual Clues library.
`ESSGAPINU.DLL` | Grid API library.
`MFC42.DLL` | Microsoft foundation classes library.

## 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 Windows client machines. 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, the environment variables are set in the environment section of the Windows 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 is equivalent to editing the PATH statement in the `AUTOEXEC.BAT` file on earlier Windows machines.

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 PATH environment variable. Otherwise, you will have to load them manually using the Tools | Add-In menu in the target application.

©2004 Hyperion Solutions Corporation. All Rights Reserved. http://www.hyperion.com