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:
CLIENT directory.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.
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 \Appdirectory 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.
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 beD:\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.
Essbase uses a message database file called, by default, ESSBASE.MDB. The API enables you to store the 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.
You can change the 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.
If you want to use the ARBORMSGPATH environment variable, place an ARBORMSGPATH statement in yourAUTOEXEC.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.
Essbase performs the following priority search to find the message database:
MessageFile field of the initialization structure.MessageFile field is set to NULL, Essbase uses the complete file and directory path specified in the ARBORMSGPATH environment variable.ESSBASE.MDB in the directory path specified in the ARBORPATH environment variable, in its BIN sub-directory.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.
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.
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 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>