Unicode Issues in Essbase API Programs


Using the Essbase API

Only Unicode mode clients can fully work with Unicode mode applications. To enable creation of Unicode-mode clients, this release provides new or changed functionality in the following areas:


General Programming Considerations

The following sections describe Unicode mode client program initialization and Unicode related operations in the C Main API:

In general, writing Essbase applications programs for Unicode must take into account the mode of the client and of the server. The assumption made for this discussion is that the Essbase server is fully Unicode enabled, that is, the Essbase server is the latest version.

There are three basic scenarios depicting three types of client communicating with the Unicode enabled Essbase server. The three client types are:

Unicode enabled programs in non-Unicode mode can access all data on Unicode servers, but can not change the database outlines for Unicode mode applications. Only Unicode enabled client programs operating in Unicode mode have full access to both the data and the database outlines on Unicode enabled servers.


Defining Unicode Mode Client Programs

Only Unicode-mode client programs can communicate with the server using UTF-8 encoded data. To initialize a Unicode mode client program, a new field, usApiType, has been added to the ESS_INIT_T structure. This field has two possible values: ESS_API_NONUNICODE and ESS_API_UTF8. The ESS_INIT_T structure is passed to the API initialization function, EssInit().

This API initialization function is the only place to specify the mode of an application program. This topic contains the following sections:


Non-Unicode clients

The non-unicode clients are the older clients were built to work with previous version of the Essbase API. These clients deal entirely in short strings and non-unicode encoding. These older clients cannot deal with the longer strings and are, therefore, restricted to dealing with non-Unicode-enabled applications.

This type of client can not edit the outlines or rules files on a Unicode mode server.

The Essbase Application Manager, similarly to other non-Unicode clients, is supported by Unicode enabled Essbase servers in non-Unicode mode. A Unicode-enabled server can communicate in non-Unicode mode with non-Unicode clients.

The non-Unicode clients can edit outlines and rules files while not connected to a server. However, encoding can be an issue for non-Unicode clients editing rules files and for Unicode clients editing rules files and outlines.

When editing rules files or outlines a Unicode mode server, the user can select the format of the output file or let it default to being the same as the input file. The permissible output file formats are:

The files are edited internally in non-Unicode encoding by non-Unicode clients and in Unicode encoding by Unicode clients.

If the input file is to be converted from Unicode format to non-Unicode format, but cannot be converted because it contains strings that are too long, then the conversion is aborted and a diagnostic is returned to the user.


Unicode-enabled Clients in Non-Unicode Mode

New Unicode-enabled clients are built with the include files and DLLs of Unicode-enabled Essbase, but communicate with the API in native encoding. The API does not support placing client API DLLs from Unicode-enabled Essbase onto a client that is built with include files from non-Unicode Essbase. Clients must be built with the new include files in order to run with the new DLLs.

This type of client can not edit the outlines or rules files on a Unicode mode server.

To work with the new include files and DLLs, a client must support the longer maximum string lengths. For some clients, this may be as simple as recompiling with the new Essbase include files that define the longer maximum lengths.

For other clients, supporting the longer maximum lengths may require code changes. For instance, the Binary Spreadsheet Table (BST) used by the Essbase Spreadsheet Add-in uses a single byte for storing the member name byte length. Since one byte is not enough to hold the new maximum byte length for member names (320 bytes), the design of the BST must be changed to allow the spreadsheet client to support the longer maximum lengths.


Unicode-enabled client in Unicode Mode

Unicode clients are built with Unicode-enabled Essbase and communicate with the API in UTF-8.

To run as a Unicode client, a client must handle long maximum string lengths, as described in the previous subsection on new native clients. In addition, the client must communicate with the API in UTF-8.

If a client is written in Java, the conversion may be easier than if the client is written in another language. However, in either case, the changes are likely to be substantial. For instance, the client code must communicate with the operation system in non-Unicode encoding while communicating with the Essbase API in Unicode mode.


Changes to the API Initialization Structure

A new field, usApiType, was added to the initialization structure, ESS_INIT_T. The initialization structure is the only place that you can specify the Unicode-related mode of the client program. If nothing is specified, the program operates in non-Unicode mode.

The ESS_INIT structure customizes the API and sets up certain API defaults. The new field for Unicode-enabled Essbase is highlighted in bold.

typedef_struct(ess_init_t)
{
   ESS_ULONG_T,  Version;     
   ESS_PVOID_T,  UserContext; 
   ESS_USHORT_T, MaxHandles;  
   ESS_SIZE_T,   MaxBuffer;   
   ESS_STR_T,    LocalPath;   
   ESS_STR_T,    MessageFile; 
   ESS_PFUNC_T,  AllocFunc;   
   ESS_PFUNC_T,  ReallocFunc; 
   ESS_PFUNC_T,  FreeFunc;    
   ESS_PFUNC_T,  MessageFunc; 
   ESS_STR_T,    HelpFile;    
   ESS_ULONG_T,  Ess_System;  
#ifdef AD_UTF8
   ESS_USHORT_T, usApiType;
#endif
} ESS_INIT_T;

Data TypeFieldDescription
ESS_ULONG_T Version This should be set to ESS_API_VERSION
ESS_PVOID_T UserContext An optional pointer to a user-defined message context (passed as argument to a user-defined MessageFunction)
ESS_USHORT_T MaxHandles The maximum number of simultaneous context handles required by the API program (between 1 and 255). The default is 255. Reducing this number may decrease the amount of client memory used within the API for your program.
ESS_SIZE_T MaxBuffer The maximum size buffer that can be allocated in the client program (typically 64 Kbytes). The default is 64 Kbytes.
ESS_STR_T LocalPath The default local path name to use for file and object operations on the client.
If this is not set, Essbase uses the ARBORPATH environment variable by default, and appends \CLIENT to the directory name passed in. If ARBORPATH is not defined, Essbase uses \ARBOR32\CLIENT.
ESS_STR_T MessageFile Qualified path name of the Essbase message database file, ESSBASE.MDB. If this is not set, Essbase first tries to use the fully qualified path in the ARBORMSGPATH environment variable, otherwise, it uses (ARBORPATH)\BIN\ESSBASE.MDB. If ARBORPATH is not defined, an error is returned at run time.
ESS_PFUNC_T AllocFunc Pointer to the user-defined memory allocation function. All platforms: memory allocation functions use the malloc() function.
ESS_PFUNC_T ReallocFunc Pointer to the user-defined memory reallocation function. All platforms: memory allocation functions use the malloc() function.
ESS_PFUNC_T FreeFunc A pointer to the user-defined memory free function. All platforms: memory allocation functions use the free() function.
ESS_PFUNC_T MessageFunc A pointer to the user-defined message callback function.
ESS_STR_T Helpfile Fully-qualified path name of the user-defined application help file, used for help for the AutoLogin dialog box. The login help context must be defined in the help file. The default is $(ARBORPATH)\BIN\ESSAPIW.HLP. If ARBORPATH is not defined, the help file name is set to null.
ESS_ULONG_T Ess_System Reserved for internal use. Set to NULL.
ESS_USHORT_T usApiType Required. Defines whether the program is in Unicode or non-Unicode mode.

New C Main API Constants

The following constants are defined in the Essbase Main C API to enable Unicode-mode client programs. These constants are the valid values for the usApiType field of the ESS_INIT_T structure. The ESS_INIT_T structure is used by EssInit() and defines whether the client program is in Unicode mode. Only Unicode-mode client programs can send UTF-8 encoded text to the OLAP server.

Constant Definition Description
ESS_API_NONUNICODE 0x0002 The program is a non-Unicode mode client program. The client program is passing a non_Unicode encoded argument to the API. This is the default value.
ESS_API_UTF8 0x0003 The program is a Unicode mode client program. The client program is passing a UTF-8 encoded argument to the API.

Setting the Unicode-related Mode of the Server

The new function, EssSetServerMode(), sets the mode of OLAP Server to be Unicode or non-Unicode. Only when it is in Unicode mode does OLAP Server allow creation of Unicode mode applications or migration of non-Unicode mode applications to Unicode mode. Setting a Unicode mode server to non-Unicode does not affect the existing Unicode-related mode of existing applications.

Syntax

ESS_FUNC_M EssSetServerMode(hCtx, bUnicode);

Parameters

Parameter Type Description
hCtx ESS_HCTX_T Essbase API context handle (logged in)
bUnicode ESS_BOOL_T The pass-in parameter, bUnicode, where bUnicode can be one of the following values:
ESS_TRUE - Sets the server mode to Unicode. OLAP server allows creation of Unicode mode applications or migration of non-Unicode mode applications to Unicode mode.
ESS_FALSE - Sets the server mode to non-Unicode. OLAP server does not allow creation of Unicode mode applications or migration of non-Unicode mode applications to Unicode mode.

Access

EssSetServerMode() requires the caller to have (AD_ACCESS_SUPER) privilege for the logged in server.


Retrieving the Unicode-related Server Mode

The new function, EssGetServerMode(), returns a value indicating whether the server is in Unicode mode or non-Unicode mode.

Syntax

ESS_FUNC_M EssGetServerMode(hCtx, *bUnicode);

Parameters

Parameter Type Description
hCtx ESS_HCTX_T Essbase API context handle (logged in)
bUnicode ESS_BOOL_T The returned value, bUnicode, where bUnicode can be:
ESS_TRUE - OLAP Server is in Unicode mode. OLAP server allows creation of Unicode mode applications or migration of non-Unicode mode applications to Unicode mode.
ESS_FALSE - OLAP Server is in non-Unicode mode. OLAP server does not allow creation of Unicode mode applications or migration of non-Unicode mode applications to Unicode mode.

Access

The EssGetServerMode() function does not require the caller to have a special privilege.


Creating Unicode mode Applications

When defined to be in Unicode mode, OLAP Server allows creation of Unicode mode applications. Use the EssCreateApplicationEx() to create a Unicode mode application.

Syntax

ESS_FUNC_M EssCreateApplicationEx(hCtx, AppName, usAppType); 

Parameters

Parameter Type Description
hCtx ESS_HCTX_T Essbase API context handle (logged in).
AppName ESS_STR_T The name of the application to be created.
usAppType ESS_USHORT_T Whether the type of application to be created is in Unicode mode or non-Unicode mode.
The valid values are:
ESS_APP_UNICODE - 0x0003 - Create a Unicode application. The function fails if the server is not in Unicode mode.
ESS_APP_NONUNICODE - 0x0002 - Create a non-Unicode application.

Access

For a server application, the caller must have Application Create/Delete/Edit privilege (ESS_PRIV_APPCREATE).


Migrating a Non-Unicode Mode Application to Unicode Mode

When defined to be in Unicode mode, OLAP Server allows migration of non-Unicode mode applications to Unicode mode. Use the function, EssConvertApplicationToUnicode(), to create a Unicode mode application.

Syntax

ESS_FUNC_M EssConvertApplicationToUnicode(hCtx, AppName);

Parameters

Parameter Type Description
hCtx ESS_HCTX_T Essbase API context handle (logged in)
AppName ESS_STR_T The name of the application to be migrated. The named application must exist and not be in Unicode mode.

Access

The caller must have Application Create/Delete/Edit privilege (ESS_PRIV_APPCREATE).


Retrieving the Unicode-related Application Information

Use EssGetApplicationInfo() and EssGetApplicationInfoEx() to return ESS_APPINFO_T and ESS_APPINFOEX_T, respectively. These structures have been enhanced to include locale information. For more information click on the links below to go to the documentation for these two functions.

ESS_FUNC_M EssGetApplicationInfo(hCtx, AppName, ppAppInfo);

ESS_FUNC_M EssGetApplicationInfoEx(hCtx, AppName, ppAppInfoEx);

Saving Outlines from Unicode Mode Applications

The new function, EssOtlWriteOutlineEx(), works the same as EssOtlWriteOutline() except it has a new parameter that enables specifying whether to save an outline in UTF-8 encoding or in non-Unicode encoding. This section provides only the function syntax and the values for the new parameter. For other information about this new function, refer to EssOtlWriteOutline().

Syntax

ESS_FUNC_M EssOtlWriteOutlineEx(hOutline, pObject, iOtlType);

Parameters

Parameter Type Description
hOutline ESS_HOUTLINE_T Outline context handle.
pObject ESS_POBJDEF_T Outline object to write.
iOtlType ESS_ULONG_T Whether the outline is saved in Unicode mode or non-Unicode mode.
The valid values are:
ESS_OUTLINE_UTF8 0x0002 - Encoded in UTF-8.
ESS_OUTLINE_NONUNICODE 0x0003 - Not Unicode-encoded.

Opening a Unicode Outline

Open the outline of a Unicode-mode application with EssOtlOpenOutlineEx(). This function works like the standard Essbase Outline API funtion EssOtlOpenOutline() with the addition of a Unicode-specific LocaleDescription argument.

Syntax

ESS_FUNC_M EssOtlOpenOutlineEx(hCtx, pObject, fLock, fKeepTrans, pLocaleDescription, phOutline);

Parameters

Parameter Type Description
hCtx ESS_HCTX_T Essbase API context handle (logged in)
pObject ESS_POBJDEF_T Pointer to an object structure defining the outline object to open.
fLock ESS_BOOL_T Flag to determine if the outline should be locked when it is opened. This is valid only for server outlines.
fKeepTrans ESS_BOOL_T Flag to determine whether to keep transactions.
If you are opening an existing outline to make changes, and you intend to restructure the database and keep data, we recommend that you set this flag to ESS_TRUE. When ESS_TRUE, a log is kept of activities done to the outline.
If you are starting from an empty outline or are not planning on saving data when you restructure, we recommend that you set this field to ESS_FALSE. When ESS_FALSE, no log is kept, saving time and memory.
pLocalDescription ESS_STR_T The identifier used by GlobalC to identify the Locale.
The LocaleDescription is in the form of:
[language]_[territory].[codepage]@[sort] for example: Japaness_japan.MS932@binary to provide the locale description of the language of the outline file. It is the program’s responsibility to pass pLocaleDescription in the current format.
pOutline ESS_PHOUTLINE_T Pointer to an ESS_HOUTLINE_T variable. This handle is set by the API and should be passed to subsequent Outline API functions.

Access

The caller must have Application Create/Delete/Edit privilege (ESS_PRIV_APPCREATE).

Notes


Grid API

To initialize a Unicode mode client program utilizing the Grid API, a new field, usApiType, has been added to the ESSG_INIT_T structure which is passed to the API initialization function, EssGInit(). Additionally, two new Grid API constants are used to define the mode of the OLAP Server.

This topic contains the following sections:


Changes to Grid API Initialization Structure

This section describes changes to the ESSG_INIT_T structure.

This structure is passed by EssGInit.

The ESSG_INIT_T structure describes the information to be passed into the call to EssGInit. The new field for Unicode-enabled Essbase is indicated by bold text.

typedef struct
{
   ESSG_ULONG_T ulVersion;
   ESSG_ULONG_T ulMaxRows;
   ESSG_ULONG_T ulMaxColumns;
   ESSG_PFUNC_T pfnMessageFunc;
   ESSG_PVOID_T pUserdata;
   ESSG_USHORT_T usApiType;
} ESSG_INIT_T, *ESSG_PINIT_T;

Data Type Field Description
ESSG_ULONG_T ulVersion This should be set to ESSG_VERSION.
ESSG_ULONG_T ulMaxRows The maximum number of rows for the grid. The limit is 65535 rows.
ESSG_ULONG_T ulMaxColumns The maximum number of columns for the grid. The limit is 256 columns.
ESSG_PFUNC_T pfnMessageFunc Pointer to the user-defined message callback function.
ESSG_PVOID_T pUserdata Pointer to user data passed to message callback.
ESSG_UGSHORT_T usApiType Encoding type of the Grid API.

New Grid API Constants

The following new constants are defined in the Essbase Grid API to enable Unicode-mode applications. These constants are the valid values for the new usApiType field of the ESSG_INIT_T structure. The ESSG_INIT_T structure is used by EssGInit() and defines whether the OLAP Server allows creation or migration of Unicode mode applications.

Constant Definition Description
ESSG_API_UTF8 0x0003 This value enables OLAP server to create or migrate Unicode-mode applications.
ESSG_API_NONUNICODE 0x0002 This value disables the creation and migration of Unicode-mode applications on OLAP Server.

These constants are additional values for the usType field of the ESSG_DATA_T structure. The ESSG_DATA_T structure is used by EssGSendRows(), EssGGetRows(), EssGFreeRows(), and EssGCell() to specify the form of data.

Constant Definition Description
ESSG_DT_STRINGEX 0x0018 This value specifies a string extended for Unicode mode.
ESSG_DT_MEMBEREX 0x0019 This value specifies a member name extended for Unicode mode.
ESSG_DT_STRINGEXwFORMULA 0x0020 This value specifies a formula string extended for Unicode mode.
ESSG_DT_FORMULASEX 0x0021 This value specifies a formula extended for Unicode mode.

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