# Visual Basic Outline API

Using the Outline API
Visual Basic Outline API Declarations
Visual Basic Outline API Functions (alphabetical)
Visual Basic Outline API Functions (categorical)

## Using the Outline API

- Error Handling
- Server Outline Queries
- Outline Verification
- Memory Allocation
- Security Requirements
- Function Call Sequence
- Operation Task Sequence

## 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:

1. The programmer initializes the API as always by calling EsxInit() and EsxLogin().
2. 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.
3. 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.
4. 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.
5. The caller should call EsxOtlCloseOutline() when complete to clean up internal data structures.
6. 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:

1. Call EsxInit() before any other API function.
   The API returns an instance handle.
2. Call EsxLogin() or EsxAutoLogin() to log on to the server.
   The API returns a context handle.
3. Call EsxOtlOpenOutline() or EsxOtlNewOutline() to open or create an outline.
   The API returns an outline handle.
4. 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.
5. Call EsxOtlRestructure() to restructure the database based on the changes made to the outline.
6. Call EsxUnlockObject() to unlock the outline object if it is locked when the outline is opened.
7. Call EsxOtlCloseOutline() to free resources associated with the outline.
8. Call EsxLogout() to log off the server.
   This invalidates the context handle.
9. 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.

1. Create and initialize an ESX_INIT_T structure.
2. Initialize the Outline API by calling EsxInit().
3. Allocate any local static or global structures.
4. Log on to the required server by calling EsxLogin() or EsxAutoLogin().
5. Create and initialize an ESX_OUTLINEINFO_T structure (only for a new outline).
6. Open an existing outline or create a new outline by calling EsxOtlOpenOutline() or EsxOtlNewOutline().
7. Work on the outline.
8. Verify the outline by calling EsxOtlVerifyOutline().
9. Write the verified outline to the server by calling EsxOtlWriteOutline().
   The outline is saved with an .OTN extension.
10. 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.
11. Unlock the outline (if it was locked on opening) by calling EsxUnlockObject().
12. Free all information associated with the outline by calling EsxOtlCloseOutline().
13. Log off the server by calling EsxLogout().
14. Free any local static or global structures.
15. Terminate the API by calling EsxTerm().