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:
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.
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:
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.
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 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.
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 Type | Field | Description |
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. |
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. |
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.
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.
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).
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).
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);
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. |
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
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:
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. |
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. |
![]() |
©2004 Hyperion Solutions Corporation. All Rights Reserved. http://www.hyperion.com |