C Outline API
Using the Outline API
C Outline API Declarations
C Outline API Functions (alphabetical)
C Outline API Functions (categorical)
C Outline API Example
Using the Outline API
Outline API Introduction
The Outline API is a set of functions for creating, maintaining, and manipulating Essbase outlines
from within a custom application. With the Outline API, you have the same ability to manipulate
database outlines from within code as you have using the Outline Editor in the Application Manager.
The Outline API is an important part of the Essbase API Toolkit with interfaces for C and
Visual Basic. The Outline API is used in conjunction with the Essbase API and requires a
server connection.
Error Handling
Outline API functions return 0 when they succeed; if they fail they return an error status value as defined in esserror.h for C and esberror.bas for Visual Basic. Functions of the main API use the error message callback routine and pass an error number to the message handler. The handler uses the essbase.mdb message database to determine the error message and display an error message to the user.
Outline API functions do not ordinarily use the error message callback routine when returning an error status. The error callback routine is called in the following situations:
- If you call functions that use the network (EsxOtlOpenOutline(),
EsxOtlWriteOutline(), and EsxOtlRestructure()),
and they incur errors on non-outline related actions.
- If a NULL is found during routine checking when passed into
the Outline API, and API_NULL_ARG is returned.
- If a bad outline handle (HOUTLINE) is passed into any call
requiring an outline handle, and OTLAPI_BAD_HOUTLINE is returned.
Server Outline Queries
Several functions support a query interface to the outline API such that the outline does not need to be downloaded from the server and completely read into memory. These Outline API functions support only server outlines. Prior to opening the outline, the user must log in to a server, setting up a valid Essbase login context.
Error handling for these functions is done via the standard API error handling mechanism. Therefore, any message callback that the caller has specified from EsxInit() is called on errors.
Here's the way it works:
- The programmer initializes the API as always by calling EsxInit()
and EsxLogin().
- The programmer calls EsxOtlOpenOutlineQuery() to "open"
the outline from the server and bring back some initial information.
The information brought back from the server is all information
in the ESX_OUTLINEINFO_T structure and for each dimension,
all relevant information in the ESX_OTLMBR_T internal structure,
which includes the ESX_MBRINFO_T structure.
- The caller needs to get information about members, so he calls
EsxOtlQueryMembers() with the appropriate flags to get
an array of member handles back. The EsxOtlQueryMembers()
call returns all relevent information in the ESX_OTLMBR_T
internal structure. The user can then call any of the EsxOtlGetXxxx()
calls that relate to a specific member by passing in one of the
returned member handles. See the comments section in the EsxOtlQueryMembers()
call for more information about which calls are supported when
the outline is opened in "query" mode.
- When the caller is done with the data returned from an EsxOtlQueryMembers()
call, he should call EssOtlFreeMembers() or EsbOtlFreeMember() to free the array
of members.
- The caller should call EsxOtlCloseOutline() when complete
to clean up internal data structures.
- The caller terminates the API as always by calling EsxLogout()
and EsxTerm().
Outline Verification
The Outline API is designed to prevent the caller from creating an illegal outline. To check the outline, use the EsxOtlVerifyOutline() function to verify it before saving it to the server. The Outline API calls EsxOtlVerifyOutline() automatically when an outline is written to the server, if it was not called previously.
Each function call in the Outline API verifies that processing by the caller does not result in an illegal outline. For example, EsxOtlRenameMember() checks a new member name to make sure that it is valid and does not already exist in the outline. Here are a few exceptions to this automatic validation:
- EsxOtlOpenOutline() allows the caller to read in a
previously created outline that is illegal. This outline could
be illegal because the Outline Editor in the Application Manager
allows you to save an invalid outline to a local file. Any existing
errors are detected when EsxOtlVerifyOutline() is called.
Also, some individual operations are illegal during processing
if the outline starts out as illegal.
- EsxOtlDeleteMember() and EsxOtlDeleteDimension()
do not check for any alias combinations that contain a deleted
member. EsxOtlVerifyOutline() detects this condition.
- EsxOtlSetMemberFormula() allows you to enter an illegal
formula, and EsxOtlVerifyOutline() does not check member
formulas. An illegal member formula causes failure during restructure.
EsxGetProcessState() displays the error message returned
from the server.
Memory Allocation
The Essbase API provides a set of memory management functions, EsxAlloc(), EsxRealloc(), and EsxFree(). These functions, plus all internal API memory allocations, call memory allocation routines pointed to by the AllocFunc, ReallocFunc, and FreeFunc fields of the ESX_INIT_T initialization structure.
If you are using your own custom memory allocation functions, make sure your memory allocation scheme can handle allocating many small memory buffers.
Security Requirements
Because you can use the Outline API to create, edit, and delete outlines, you must be aware of some security issues when creating an application that uses the Outline API. These issues impact only programs that create, edit, or save outlines during a session.
To manipulate outlines through the Outline Editor in the Application Manager, you must have Application Designer or higher privileges. You also need these privileges to use a program that uses the Outline API during execution. If you do not have these privileges, Outline API calls that read or write outlines from the server do not work. See the Database Administrator's Guide for more detailed information on security and privilege levels.
For example, you are writing a new EIS end-user application that allows your users to explore a number of "what-if" situations during a session. To do this, the program dynamically creates a number of Essbase databases during a session. These databases (and their outlines) are temporary and are not saved after the session terminates. You can approach this situation in several ways:
- If you want the user to be able to create an application and multiple databases during a session, give the user the Create/Delete Application privilege. This privilege must be assigned by an Essbase Supervisor prior to running the program. This is a relatively high privilege level in Essbase, but if the user does not have access to other programs, such as the Application Manager, there is little impact on the overall system security.
- If you do not need multiple databases available at the same time, you can have the Essbase Supervisor create a temporary application and database during the installation of your program. The program itself manipulates the temporary database without having to create a new database for each "what-if" situation.
With the second approach, a user requires only the lower and more restricted Database Designer privilege. You could have the Essbase Supervisor set up a special group with Database Designer privilege only for your temporary application and database. Users can be assigned to that group. The users would revert to ordinary user privilege for any other access to the system. This approach offers less security exposure, but does require more set up prior to running your program.
Function Call Sequence
When you use the Outline API, your program must call some API functions before others. Follow this basic call sequence:
- Call EsxInit() before any other API function.
The API returns an instance handle.
- Call EsxLogin() or EsxAutoLogin() to log on to the server.
The API returns a context handle.
- Call EsxOtlOpenOutline() or EsxOtlNewOutline()
to open or create an outline.
The API returns an outline handle.
- Call EsxOtlWriteOutline() to write the current outline
to the server. EsxOtlVerifyOutline() is called automatically by the API
before the outline is saved, unless you call it before this.
- Call EsxOtlRestructure() to restructure the database
based on the changes made to the outline.
- Call EsxUnlockObject() to unlock the outline object
if it is locked when the outline is opened.
- Call EsxOtlCloseOutline() to free resources associated
with the outline.
- Call EsxLogout() to log off the server.
This invalidates the context handle.
- Call EsxTerm() to end the session.
This invalidates the instance handle.
A Typical Outline API Task Sequence
This is a typical order of operations for a simple Outline API application.
- Create and initialize an ESX_INIT_T structure.
- Initialize the Outline API by calling EsxInit().
- Allocate any local static or global structures.
- Log on to the required server by calling EsxLogin()
or EsxAutoLogin().
- Create and initialize an ESX_OUTLINEINFO_T structure
(only for a new outline).
- Open an existing outline or create a new outline by calling
EsxOtlOpenOutline() or EsxOtlNewOutline().
- Work on the outline.
- Verify the outline by calling EsxOtlVerifyOutline().
- Write the verified outline to the server by calling EsxOtlWriteOutline().
The outline is saved with an .OTN extension.
- Restructure the database by calling EsxOtlRestructure().
The .OTN file is changed to an .OTL file. This is an asynchronous
function call; therefore, you should call EsxGetProcessState()
until the process is complete.
- Unlock the outline (if it was locked on opening) by calling
EsxUnlockObject().
- Free all information associated with the outline by calling
EsxOtlCloseOutline().
- Log off the server by calling EsxLogout().
- Free any local static or global structures.
- Terminate the API by calling EsxTerm().