# 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
- C Main API
  - Changes to the Initialization Structure ESS_INIT_T
  - Changes to Application Info Structure ESS_APPINFO_T
  - New Extended Application Info Structure ESS_APPINFOEX_T
  - New C API Constants
  - EssSetServerMode()
  - EssGetServerMode()
  - EssCreateApplicationEx()
  - EssConvertApplicationToUnicode()
  - EssGetApplicationInfoEx()
- C Outline API
  - EssOtlWriteOutline()
  - EssOtlOpenOutlineEx()
- C Grid API
  - Changes to Grid Initialization Structure ESSG_INIT_T
  - New Grid API Constants

## General Programming Considerations

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

- Defining Unicode Mode Client Programs
- Non-Unicode clients
- Unicode-enabled Clients in Non-Unicode Mode
- Unicode-enabled Clients in Unicode Mode
- Setting the Unicode-related Mode of the Server
- Retrieving the Unicode-related Server Mode
- Creating Unicode mode Applications
- Migrating a Non-Unicode Mode Application to Unicode Mode
- Retrieving the Unicode-related Application Information
- Saving Outlines from Unicode Mode Applications
- Opening a Unicode Outline

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:

- a non-Unicode client program communicating with the Unicode server
- a Unicode-enabled client in non-Unicode mode communicating with the Unicode server.
- a Unicode-enabled client communicating with the Unicode server.

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:

- Changes to the Initialization Structure ESS_INIT_T
- New C Main API Constants

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

- Non-Unicode format - short strings and non-Unicode encoding
- Unicode format - long strings and UTF-8 encoding

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 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.

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

- If pLocaleDescription is NULL, then this function behaves exactly as EssOtlOpenOutline().
- If this function is called by non-unicode client, the input of pLocaleDescription is ignored, and this function behaves exactly as EssOtlOpenOutline().
- The input of pLocaleDescription only take effect when it is called by Unicode client.
- In case the outline is converted to UTF-8, this locale will be used as the source language.
- If this function is not used, the locale description in ESSLANG will be used, if that is not present, the system language will be used.
- When a program attempts to open an outline on the active server, the server locale will be used. The file is copied from the server during this process so it will use the same language as the server.
- Non-unicode text files will be converted using ESSLANG, if present, otherwise using the system language. To convert text files that are in a different language than that the system is using, essutf8 must be used to convert the file.

## 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
- New Grid API Constants

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

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