# 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

- EssCreateStorageTypedApplication()
- EssMdxTrig()
- EssGetSpoolFile()
- EssDeleteAllSplFiles()
- EssDeleteSplFile()
- EssListSpoolFiles()
- EssDisplayTriggers()

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

## New Visual Basic Main API Functions

- EsbCreateStorageTypedApplication

## New C Outline API Functions

- EssOtlQueryAttributesEx

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

- EssOtlGetNextAliasCombination()
- EssOtlDeleteAliasCombination()
- EssOtlAddAliasCombination()

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

- EssGetMessage()
- EssVerifyFormula()
- EssVerifyRulesFile()

## New C Outline API Functions

- EssOtlVerifyFormula()
- EssOtlVerifyOutlineEx()

## New C Grid API Functions

- EssGConnectEx()
- EssGBeginSamplingZoomIn()

## New Visual Basic API Functions

- EsbClrSpanRelationalSource()()
- EsbSetSpanRelationalSource()
- EsbBeginDataload()
- EsbEndDataload()
- EsbCreateExtUser()
- EsbCreateFilter()
- EsbGetDatabaseInfoEx()
- EsbGetUserEx()
- EsbSetUserEx()
- EsbListCalcFunctions()
- EsbListLogins()
- EsbListUsersEx()
- EsbLogSize()
- EsbWriteToLogFile()

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

- EssResetDatabase()
- EssLocateIBH()
- EssGetIBH()
- EssFixIBH()
- EssGetServerLocaleString()
- EssUpdateBAKFile()

## Changed C Outline API Function

- EssOtlRestructure()

## New Visual Basic API Functions

- EsbListRequests()
- EsbKillRequest()
- EsbSetSpanRelationalPartition()
- EsbClrSpanRelationalPartition()

# Migrating to Release 6.5

## New C API Functions and Structures

- EssClrSpanRelationalSource()
- EssSetSpanRelationalSource()
- EssListLogins()
- ESS_LOGININFO_T()
- EssCreateExtUser()
- EssListUsersEx()
- EssGetUserEx()
- EssSetUserEx()
- ESS_USERINFOEX_T()

## Enhanced C API Functions and Structures

- EssGetMemberInfo()
- EssCheckMemberName()
- EssGetMemberCalc()
- EssQueryDatabaseMembers()
- ESS_MEMBERINFO_T
- ESS_MBRINFO_T
- EssGSetGridOption()
- EssGGetGridOption()
- ESS_DBSTATE_T

# Migrating to Release 6.2

## New C Main API Functions and Structures

- EssListRequests()
- EssKillRequest()
- ESS_REQUESTINFO_T
- ESS_REQ_STATE_T
- EssListCalcFunctions()

# 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 EssCheckAttributes() EssFreeStructure() EssGetAssociatedAttributesInfo() EssGetAttributeInfo() EssGetAttributeSpecifications() | New Visual Basic Main Attributes Functions EsbCheckAttributes() EsbGetAssociatedAttributesInfo() EsbGetAttributeInfo() EsbGetAttributeSpecifications()
New C Main Attributes Structures ESS_ATTRIBUTEINFO_T ESS_ATTRIBUTEVALUE_T ESS_ATTRSPECS_T ESS_PARTOTL_DIMASSOCCHG_API_T ESS_PARTOTL_MBRASSOCCHG_API_T | New Visual Basic Main Attributes Structures ESB_ATTRIBUTEINFO_T ESB_ATTRSPECS_T
New C Outline Attributes Functions EssOtlAssociateAttributeDimension() EssOtlAssociateAttributeMember() EssOtlDisassociateAttributeDimension() EssOtlDisassociateAttributeMember() EssOtlFindAttributeMembers() EssOtlFreeStructure() EssOtlGetAssociatedAttributes() EssOtlGetAttributeInfo() EssOtlGetAttributeSpecifications() EssOtlQueryAttributes() EssOtlSetAttributeSpecifications() | New Visual Basic Outline Attributes Functions EsbOtlAssociateAttributeDimension() EsbOtlAssociateAttributeMember() EsbOtlDisassociateAttributeDimension() EsbOtlDisassociateAttributeMember() EsbOtlFindAttributeMembers() EsbOtlGetAssociatedAttributes() EsbOtlGetAttributeInfo() EsbOtlGetAttributeSpecifications() EsbOtlQueryAttributes() EsbOtlSetAttributeSpecifications()
New C Outline Attributes Structure ESS_ATTRIBUTEQUERY_T | New Visual Basic Outline Attributes Structure ESB_ATTRIBUTEQUERY_T
Existing C Main Functions Changed for Attributes EssGetDimensionInfo() EssGetMemberInfo() EssQueryDatabaseMembers() | Existing Visual Basic Main Functions Changed for Attributes EsbGetDimensionInfo() EsbGetMemberInfo() EsbQueryDatabaseMembers()
Existing C Main Structures Changed for Attributes ESS_DIMENSIONINFO_T ESS_MEMBERINFO_T ESS_PARTOTL_DIMCHG_API_T ESS_PARTOTL_MBRCHG_API_T ESS_PARTOTL_OSN_RELATIVES_API_T | Existing Visual Basic Main Structures Changed for Attributes ESB_DIMENSIONINFO_T ESB_MEMBERINFO_T
Existing C Outline Functions Changed for Attributes EssOtlAddDimension() EssOtlAddMember() EssOtlGetMemberInfo() EssOtlMoveMember() EssOtlRenameMember() EssOtlSetMemberInfo() EssOtlVerifyOutline() | Existing Visual Basic Outline Functions Changed for Attributes EsbOtlAddDimension() EsbOtlAddMember() EsbOtlGetMemberInfo() EsbOtlMoveMember() EsbOtlRenameMember() EsbOtlSetMemberInfo() EsbOtlVerifyOutline()
Existing C Outline Structures Changed for Attributes ESS_MBRINFO_T | Existing Visual Basic Outline Structures Changed for Attributes ESB_MBRINFO_T

### Other APIs

Enhanced Database Member Query (Existing C Main Function) EssQueryDatabaseMembers() | Enhanced Database Member Query (Existing Visual Basic Main Function) EsbQueryDatabaseMembers()
Database File Information (New C Main Function and Structure) EssListDbFiles() ESS_DBFILEINFO_T | Database File Information (New Visual Basic Main Function and Structure) EsbListDbFiles() ESB_DBFILEINFO_T
Location Aliases (New C Main Functions) EssCreateLocationAlias() EssDeleteLocationAlias() EssGetLocationAliasList() | Location Aliases (New Visual Basic Main Functions) EsbCreateLocationAlias() EsbDeleteLocationAlias() EsbGetLocationAliasList()
Timestamp Query (New C Outline Function) EssOtlGetUpdateTime() | Timestamp Query (New Visual Basic Outline Function) EsbOtlGetUpdateTime()
Performance Stats (New C Main Functions) EssDumpPerfStats() EssGetStatBufSize() EssResetPerfStats() |
Extended Member Query (New C Outline Functions and Structure) EssOtlGetMemberField() EssOtlQueryMembersEx() ESS_OTLQUERYERRORLIST_T |

## Platforms

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

- On Windows, Essbase provides 32-bit versions of the C and Visual Basic APIs. There is no Visual Basic Grid API. See API Libraries for a list of libraries you need to link and run with your program.
- On Solaris, HP-UX, and AIX, Essbase provides support for the Main API, Outline API and Grid API components of the Essbase API in C.

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 :

- EssQueryDatabaseMembers()
- EssOtlQueryMembers()
- EssOtlQueryMembersByName()
- EssOtlQueryMembersEx()

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.

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