IBM DB2 OLAP Server 8.1

New API for FixPak 1 (Essbase 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()
EsbSetSpanRelationalSource()
EsbClrSpanRelationalSource()

EssResetDatabase()

Description

EssResetDatabase() clears all loaded data and resets the outline to be empty in the active database.

Syntax

ESS_FUNC_M EssResetDatabase (hCtx);

ESS_HCTX_T hCtx;

Parameters

hCtx Essbase API context handle

Return Value

None.

Notes

Data deleted and outlines reset using this function cannot be restored. Use it with care!
This function call is asynchronous. Call EssGetProcessState() after making this call until EssGetProcessState() returns a status indicating that the reset database operation is complete.

Access

This function requires that the caller have Write privilege (ESS_PRIV_WRITE) for the database, and to has selected it as the active database using EssSetActive().

Example

  ESS_FUNC_M
  ESS_ResetDb (ESS_HCTX_T     hCtx)
  {
     ESS_FUNC_M        sts = ESS_STS_NOERR;
     ESS_PROCSTATE_T pState;
     sts = EssResetDatabase(hCtx);
  
     if (!sts)
     {
        sts = EssGetProcessState (hCtx, &pState);
        while(!sts || (pState.State != ESS_STATE_DONE))
           sts = EssGetProcessState (hCtx, &pState);
  
     }
     
     return (sts);
  }

EssLocateIBH()

Description

EssLocateIBH() locates invalid block headers within the database. At the end of the locate process, a server-based IBH log file is created that can be used later in EssFixIBH() to fix the errors.

Syntax

ESS_FUNC_M EssLocateIBH (hCtx, dbName);

ESS_HCTX_T hCtx;

ESS_STR_T dbName;

Parameters

hCtx Context handle

localeName Name of the database

EssGetIBH()

Description

EssGetIBH() creates a local log file with all index combinations for which blocks contain invalid block headers. The database administrator can use this information to reload the datapoints that were identified as corrupted.

Syntax

ESS_FUNC_M EssGetIBH (hCtx, destFileName);

ESS_HCTX_T hCtx;

ESS_STR_T destFileName;

Parameters

hCtx Context handle

destFileName Name of the file in which the IBH information is to be stored at client side.

EssFixIBH()

Description

EssFixIBH() repairs invalid header block corruption in the database. Currently, it removes all the invalid blocks from the database.

Syntax

ESS_FUNC_M EssFixIBH (hCtx, action);
ESS_FUNC_M EssFixIBH (ESS_HCTX_T, ESS_IBH_ACTION);

ESS_HCTX_T hCtx;

ESS_IBH_ACTION action;

Parameters

hCtx Context handle

action An enumeration type. For this release the only valid value is REMOVE.

EssGetServerLocaleString()

Description

EssGetServerLocaleString() gets the server locale description; for example, English_UnitedStates.US-ASCII@Default.

Syntax

ESS_FUNC_M EssGetServerLocaleString (hCtx, localeString);

ESS_HCTX_T hCtx;

ESS_PSTR_T localeString;

Parameters

hCtx Context handle

localeString Address of pointer to receive allocated string of server locale description.

Return Value

If successful, returns the name of the server locale description in localeString.

Notes

The memory allocated for localeString should be freed using EssFree().

Access

This function requires no special privileges.

Example

  ESS_FUNC_M
  ESS_GetServerLocaleString (ESS_HCTX_T  hCtx)
  {
     ESS_FUNC_M     sts = ESS_STS_NOERR;
     ESS_STR_T localeStr= NULL;
  
     sts = EssGetServerLocaleString(hCtx, &localeStr);
     
     if (localeStr)
     {
        printf("server locale: %s\r\n",localeStr);
        EssFree(hInst,localeStr);
     }
     return sts;
  }

EssUpdateBAKFile()

Description

EssUpdateBAKFile() compares the security backup file essbase.bak to the security file essbase.sec and overwrites the backup file with the security file if the two files do not match.

Syntax

ESS_FUNC_M EssUpdateBAKFile (hCtx);

ESS_HCTX_T hCtx;

Parameters

hCtx Context handle

Return Value

If successful, returns Zero.

Notes

Essbase compares the security file and the backup file every time the server starts. The Essbase Application Manager can be used to automatically compare the security backup file to the security file at specified intervals or on demand. When Essbase compares the files, Essbase updates the backup file to match the security file.

Access

This function requires supervisor permission.

Example

  ESS_FUNC_M
  ESS_UpdateBAKFile (ESS_HCTX_T  hCtx)
  {
     ESS_FUNC_M     sts = ESS_STS_NOERR;
  
     sts = EssUpdateBAKFile(hCtx);
     
     return sts;
  }

EssOtlRestructure()

EssOtlRestructure() restructures an outline on the server. This is an asynchronous call. The change for this release is a new RestructType parameter (ESS_DOR_FORCE_ALLDATA) that forces a refresh of all data along with the restructured outline.

Syntax

ESS_FUNC_M EssOtlRestructure (hCtx, usRestructType);

ESS_HCTX_T	hCtx
ESS_USHORT_T	usRestructType

Parameters

hCtx Server login context handle. This must be the server on which the outline was saved using EssOtlWriteOutline().

usRestructType Type of restructuring to do. This can be one of the following values:
ESS_DOR_ALLDATA
ESS_DOR_NODATA
ESS_DOR_LOWDATA
ESS_DOR_INDATA
ESS_DOR_FORCE_ALLDATA

Return Value

Returns 0 if successful; otherwise returns OTLAPI_BAD_RESTRUCTTYPE.

Notes

You must save the outline using EssOtlWriteOutline() before calling this function.
This call is valid only for outlines saved to the server.
This call is asynchronous. You should call EssGetProcessState() after making this call until EssGetProcessState() returns a status indicating the restructure operation is complete.
In order for data to be properly restructured (saving data), the outline must have been opened using EssOtlOpenOutline() with the fKeepTrans flag set to ESS_TRUE.

Access

This function requires you to have the appropriate level of access to the specified application and/or database to contain the outline object. To restructure the outline object, you must have Application Designer or Database Designer privilege (ESS_PRIV_APPDESIGN or ESS_PRIV_DBDESIGN) for the specified application or database containing the outline.

EsbListRequests()

Description

EsbListRequests() returns information about sessions and requests in progress, terminated, or in the process of being terminated.

Syntax

  EsbListRequests (hCtx, UserName, AppName, DbName, Items)
  ByVal hCtx     As Long
  ByVal UserName As String
  ByVal AppName  As String
  ByVal DbName   As String
        Items    As Long

Parameters

hCtx	Context handle
AppName	Application name
DbName	Database name
UserName	User name
Items	Number of index and data files returned

Return Value

If successful, returns a count of the number of users in Items, and generates a list of users with access to the specified application and database that is accessible using EsbGetNextItem().

Notes

EsbListRequests() returns information about sessions and requests in progress, terminated, or in the process of being terminated.

A session is the time in seconds between an Essbase user's login and logout.
A request is a query sent to Essbase by a user or by another process; for example, starting an application or restructuring a database outline. Each session can process only one request at a time; therefore, sessions and requests have a one-to-one relationship.
This function returns information on requests and sessions initiated by the process specified by the UserName, AppName, and DbName. If these parameters are null or empty, then all the processes in the system are listed. This function returns the number of current, terminating, and terminated requests and one ESB_REQUESTINFO_T structure for each request.
After you call EsbListRequests(), call EsbGetNextItem(), using ESB_REQUESTINFO_TYPE, to retrieve the request information structures that you want.

Access

This function requires no special privileges.

Example

Declare Function EsbListRequests Lib "ESBAPIW" (ByVal hCtx As Long, ByVal UserName As String, ByVal AppName As String, ByVal DbName As String, pItems As Integer) As Long
  
  Sub ESB_ListRequests ()
     Dim Items As Integer
     Dim ReqInfo As ESB_REQUESTINFO_T
     Dim UserName As String 
     Dim AppName As String 
     Dim DbName As String 
     Dim sts As Long
  
    UserName = "Admin" 
    AppName = "Demo" 
    DbName = "Basic" 
  
     '*************
     ' List Requests
     '************* 
     sts = EsbListRequests (hCtx, Items)
  
     For n = 1 To Items
       '********************
       ' Get next Request Info 
       ' from the list
       '******************** 
       sts = EsbGetNextItem (hCtx, 
             ESB_REQUESTINFO_TYPE, ByVal ReqInfo)
     Next
  End Sub

EsbKillRequest()

Description

EsbKillRequest() terminates specific Essbase user sessions or requests.

Syntax

  EsbKillRequest (hCtx, ReqInfo)
  ByVal hCtx     As Long
  ByVal pReqInfo  As ESB_REQUESTINFO_T

Parameters

hCtx	Context handle
pReqInfo	Pointer to the Request Information structure.

Return Value

If successful, returns a count of the number of users in Items, and generates a list of users with access to the specified application and database that is accessible using EsbGetNextItem().

Notes

EsbKillRequest() uses the information in ESB_REQUESTINFO_T regarding current sessions and requests to terminate a specific Essbase user session. This function can also be used to terminate (without logging out the user) any active requests being made to an application, a database, or the system during a user session.
A session is the time in seconds between an Essbase user's login and logout.
A request is a query sent to Essbase by a user or by another process; for example, starting an application or restructuring a database outline. Each session can process only one request at a time; therefore, sessions and requests have a one-to-one relationship.
This function terminates the sessions and requests specified by the UserName, AppName, and DbName in the ESB_REQUESTINFO_T structure. If those fields are null, this function terminates all sessions and requests initiated by this process (user). The application program is responsible for allocating and freeing the memory used by ESB_REQUESTINFO_T.

Access

This function requires no special privileges.

Example

Declare Function EsbKillRequest Lib "ESAPINW" (ByVal hCtx As Long, pReqInfo As ESB_REQUESTINFO_T) As Long
  
Sub ESB_KillRequest ()
   Dim Items As Integer
   Dim pReqInfo As ESB_REQUESTINFO_T
   Dim UserName As String 
   Dim AppName As String 
   Dim DbName As String 
   Dim sts As Long

  UserName = "Admin" 
  AppName = "Demo" 
  DbName = "Basic" 

   '*************
   ' List Requests
   '************* 
   sts = EsbListRequests (hCtx, Items)

   For n = 1 To Items
     '********************
     ' Get next Request Info 
     ' from the list
     '******************** 
     sts = EsbGetNextItem (hCtx, 
           ESB_REQUESTINFO_TYPE, ByVal ReqInfo)

     Print ReqInfo.UserName

     sts = EsbKillRequest (hCtx, pReqInfo)

   Next

End Sub

EsbSetSpanRelationalSource()

Description

EsbSetSpanRelationalSource() sets the Boolean bSpanRelPart field informing Essbase that pertinent data exists in an attached relational store.

Syntax

ESS_FUNC_M EsbSetSpanRelationalSource (hCtx)

ByVal hCtx As Long

ESS_HCTX_T

hCtx;

Parameters

hCtx Essbase VB API context handle

Access

This function requires that the caller have read privilege (ESB_PRIV_READ) to one or more members in the active database.

Example

  Declare Function EsbSetRelationalSource Lib "ESBAPIW" (ByVal hCtx As Long) As Long
  
  Sub ESB_SetRelationalSource ()
     Dim sts As Long
  
     '*************************
     ' Set the bSpanRelPart  field
     '*************************
     sts = EsbSetRelationalSource (hCtx)
  
  End Sub

EsbClrSpanRelationalSource()

Description

EsbClrSpanRelationalSource() clears the Boolean bSpanRelPart field informing Essbase that pertinent data exists in an attached relational store.

Syntax

ESS_FUNC_M EsbClrSpanRelationalSource (hCtx)

ByVal hCtx As Long

ESS_HCTX_T

hCtx;

Parameters

hCtx Essbase VB API context handle

Access

This function requires that the caller have read privilege (ESB_PRIV_READ) to one or more members in the active database.

Example

  Declare Function EsbClrRelationalSource Lib "ESBAPIW" (ByVal hCtx As Long) As Long
  
  Sub ESB_ClrRelationalSource ()
     Dim sts As Long
  
     '**************************
     ' Clear the bSpanRelPart  field
     '**************************
     sts = EsbClrRelationalSource (hCtx)
  
  End Sub

hCtx	Context handle
destFileName	Name of the file in which the IBH information is to be stored at client side.

hCtx	Context handle
action	An enumeration type. For this release the only valid value is REMOVE.

hCtx	Context handle
localeString	Address of pointer to receive allocated string of server locale description.

hCtx	Server login context handle. This must be the server on which the outline was saved using EssOtlWriteOutline().
usRestructType	Type of restructuring to do. This can be one of the following values: ESS_DOR_ALLDATA ESS_DOR_NODATA ESS_DOR_LOWDATA ESS_DOR_INDATA ESS_DOR_FORCE_ALLDATA