Migrating to Release 7.1

Aggregate Storage Considerations

The structure of Aggregate Storage mode databases affects the results of queries. Click HERE for more information on querying Aggregate Storage databases.

New C Main API Functions

The new trigger functions are included in the File Functions categorical listing.

New Visual Basic Main API Functions

New C Outline API Functions

Deleted C Outline API Functions

Three API functions were deleted from the Essbase C Outline API. Programs that contain these functions should be changed to avoid unnecessary errors. The three deleted functions are :

Warning:
Programs compiled with the Release 7.x API do not work with earlier server releases.

Essbase API programs compiled with header files from a specific release must use the libraries from the same release. For example, if the header files are from version 6.2, you cannot use 6.5 run-time libraries. If your header files were from 6.5 you can not use 7.0 run-time libraries.


Migrating to Release 7.0

New C Main API Functions

New C Outline API Functions

New C Grid API Functions

New Visual Basic API Functions

An extended user information structure, ESB_USERINFOEX_T, has been added for use with EsbGetUserEx(), EsbSetUserEx(), and EsbListUsersEx().

Client application programs using the Essbase release 7.0 runtime client must handle the new Grid API data types, the extended User Information structure ESS_USERINFOEX_T, and the extended Application Information structure ESS_APPINFOEX_T.

The names of many library files have changed for this release. For a complete list of the new file names, refer to Essbase API Library Files.

Client Grid API programs should be revised to take into account new Grid API Structures and Grid API data types.


Migrating to Release 6.5.1

New C API Functions

Changed C Outline API Function

New Visual Basic API Functions


Migrating to Release 6.5

New C API Functions and Structures

Enhanced C API Functions and Structures


Migrating to Release 6.2

New C Main API Functions and Structures


Migrating to Release 6.1

New Features in Release 6.1
Platforms

New Features in Release 6.1

This document contains a set of working sample applications and a tutorial-style explanation of the basic concepts needed to get started writing API programs.

Warning:
Programs compiled with the Release 6.x API do not work with previous server releases.
Programs compiled with the Release 5 API work with Release 6.x and Release 5 servers.

Attributes APIs

New C Main Attributes Functions

New Visual Basic Main Attributes Functions

New C Main Attributes Structures

New Visual Basic Main Attributes Structures

New C Outline Attributes Functions

New Visual Basic Outline Attributes Functions

New C Outline Attributes Structure

New Visual Basic Outline Attributes Structure

Existing C Main Functions
Changed for Attributes

Existing Visual Basic Main Functions
Changed for Attributes

Existing C Main Structures
Changed for Attributes

Existing Visual Basic Main Structures
Changed for Attributes

Existing C Outline Functions
Changed for Attributes

Existing Visual Basic Outline Functions
Changed for Attributes

Existing C Outline Structures
Changed for Attributes

Existing Visual Basic Outline Structures
Changed for Attributes

Other APIs

Enhanced Database Member Query
(Existing C Main Function)

Enhanced Database Member Query
(Existing Visual Basic Main Function)

Database File Information
(New C Main Function and Structure)

Database File Information
(New Visual Basic Main Function and Structure)

Location Aliases
(New C Main Functions)

Location Aliases
(New Visual Basic Main Functions)

Timestamp Query
(New C Outline Function)

Timestamp Query
(New Visual Basic Outline Function)

Performance Stats
(New C Main Functions)

Extended Member Query
(New C Outline Functions and Structure)


Platforms

The Hyperion Essbase API is supported on all Essbase client and server platforms:

Because Visual Basic is not available on UNIX, the Visual Basic API is not supported on UNIX platforms.

For installation information, see the Hyperion Essbase Installation Guide.

See Building an Application Program on UNIX.

APIs and Platforms

The following table lists the available APIs on the supported platforms:

  Main API
in C
Main API in VB Outline API in C Outline API in VB Grid API in C
Windows yes yes yes yes yes
AIX yes N/A yes N/A yes
HP-UX yes N/A yes N/A yes
Solaris yes N/A yes N/A yes

Querying Aggregate Storage Databases

Release 7.1 presents the ability to page outlines of Aggregate Storage databases with very large numbers of members. Aggregate Storage databases can have a much higher number of members than block storage databases. Certain precautions need to be exercised by applications programs using functions that retrieve members from the server. This section outlines those considerations.

There are four Essbase API functions that request member sets from the Essbase server. The four functions are :

Each of these functions operates differently. EssOtlQueryMembers() and EssOtlQueryMembersByName() enable programs to cursor through the outline. The cursoring is controlled by a flexible and complex specification of members in the outline. The rest of this discussion deals primarily with these two functions and cursoring.

The cursoring options are not available for EssQueryDatabaseMembers() and EssOtlQueryMembersEx(). EssQueryDatabaseMembers() takes a report style input. EssOtlQueryMembersEx() takes a FIX style input. Determine the potential maximum count of the result set returned by these two functions by first calling EssOtlQueryMembers(). This step will ensure that the query using these two functions for the actual members from the server will not overwhelm the server's memory resources.

Alternately, the size of the result set from EssOtlQueryMembersEx() can also be controlled through the paramater pMaxCount to accomplish "first N" functionality.

EssOtlQueryMembers() and EssOtlQueryMembersByName() request member sets by applying one or more metadata operations on a member in the outline. These two functions enable the ability to cursor over the result sets. Both functions present the option to return the count of the members in the result set instead of the actual set of members.

These two functions take the following parameters as input: (hOutline, hMember (pszMember), pPredicate, pMbrCounts, phMemberArray)

Cursoring can be achieved by populating contents of pMbrCounts structure appropriately. The ability to cursor has always been available in the two functions. However, both functions have been improved for better performance on Aggregate Storage outlines. For this reason, programmers should consider using cursoring when working with databases that have very large outlines.

The member counts structure pMbrCounts (ESS_MBRCOUNTS_T) consists of 4 fields - ulStart, ulMaxCount, ulTotalCount and pulReturnCount. The ulStart and ulMaxCount fields are input arguments to the API. The ulTotalCount and pulReturnCount are values returned from the API. If the ulStart and ulMaxCount fields are both set to zero 0, the API returns the entire result set of the operation requested This is the default behavior.

An API application program can request different ranges of members from the server by changing the value of the ulStart and ulMaxCount fields. The server does not expect the API program to request consecutive ranges. The server always returns the total size of the result set in the ulTotalCount field. Determining the total size is an expensive operation in terms of time. If you are implementing cursoring, requesting the ulTotalCount on each call is redundant. To eliminate extra calculations of ulTotalCount set the new predicate option ESS_NOTOTALCOUNTS option in the pPredicate structure. This option is relevant only if you are using the ESS_COUNTONLY option to request the actual result set of an operation as opposed to just the count of the result set. The ESS_NOTOTALCOUNTS option is ignored when ESS_COUNTONLY is also specified.

The following sample C code illustrates the notion of cursoring.

ESS_PREDICATE_T predicate; 
ESS_MBRCOUNTS_T counts; 
memset(&predicate, '\0', sizeof(predicate); 
memset(&counts, '\0', sizeof(counts); 
predicate.ulQuery = queryPredicate 
predicate.ulOptions = ESS_NOTOTALCOUNTS |  optionPredicate
counts.ulStart = 0; 
counts.ulMaxCount = 1000; 
do { 
     sts = EssOtlQueryMembers(….); 
     if (!sts && counts.ulReturnCount > 0) { 
        // add results to result list, process the result, free member handles as appropriate
     } 
     counts.ulStart += counts.ulReturnCount; 
} while (!sts && counts.ulReturnCount >0	); 
        // Note that the setting of ESS_NOTOTALCOUNTS option
		// ensures that the total size of the result set is not 
		// returned in the counts.ulTotalCount field when not required.

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