Defining a Custom Message Function in C Programs

The C API allows you to supply a custom message handling function which you can use to trap error messages before they are processed by the API. You may want to code a custom message handling function, either to trap particular error conditions, or to ensure uniform processing and display of all user messages throughout your program. If you choose not to supply a custom message function, all message processing is handled by the API default message handler.

To define a custom message function in a program, you must write the function and set the MessageFunc field in the API initialization structure to point to your custom function before calling EssInit().

Coding the Custom Message Handling Function

You can use any name you wish for this function and its arguments, but it must be declared in the following form:

ESS_FUNC_M      CustomMessage (
ESS_PVOID_T     UserContext,     /* user context pointer */
ESS_LONG_T      MessageNumber,   /* Essbase message number */
ESS_USHORT_ T   Level,           /* message level */
ESS_STR_T       LogString,       /* message log string */
ESS_STR_T       MessageString    /* message string */
);

In this code, the fields are defined as follows:

The UserContext argument is a copy of the pointer passed in the UserContext field of the initialization structure to the EssInit() function during API initialization (see Initializing the C Main API). You can use this pointer to contain any application-specific context information which is required during custom message processing, but typically it is used to pass a structure containing state information for your program.
The MessageNumber argument is used to trap messages returned by specific error conditions (individual error message codes are defined in the header file (esserror.h).
The Level argument is used to trap messages based on the message level, which denotes whether the message is an information, warning, or error message.

The LogString argument receives the server log entry information as a string. It passes strings of the form:

[Date & Time] Server/Application/Database/Username/Thread/Message#

For example:

[Fri Feb 04 11:51:18 1994]Elm/Sample/Basic/Admin//1012550

The MessageString argument contains the message text as a string. It passes the complete message text, for example:
```
Total Calc Elapsed Time : [46] seconds
```
The default API message handler displays both the log string and the message string on successive lines, (either within the message dialog, or just written to the stdout stream). For example:
```
[Fri Feb 04 11:51:18 1994]Elm/Sample/Basic/Admin//1012550 Total Calc Elapsed Time : [46] seconds
```

Setting the MessageFunc Field to Point to Your Function

Pointers to the custom message function must be assigned to the MessageFunc field of the initialization structure passed to the EssInit() function (see Initializing the C Main API).

Using a Custom Function to Control Message Processing

The custom message function is called before an Essbase Server returns a message or the Essbase API returns an error. When the function is called, the arguments passed to it contain the message number, message level, log string, and error string for that particular message. For each message, the function can use these argument values to choose whether to process the message, ignore it, or return it to the API for default processing:

What the return code means to the API—A return value of zero denotes that the function processed the message successfully and that no further action needs to be taken by the API. If the return code is non-zero, the message is passed to the default API message handling function for further processing and display. To have your program ignore a message, simply return a zero from the custom message function.
Note:
The API automatically frees the log and message strings when it has finished processing the message. Do NOT attempt to free them within your code.

Determining which return code your function should generate—To determine which return code to generate, you can code the custom message function to check the MessageNumber argument, and/or the Level argument. For example, a program might ignore all information messages, and possibly also any warning messages (you can make this a user-definable setting) by testing the Level argument against the appropriate constant defined in ESSAPI.H (for example, ESS_LEVEL_WARNING), and returning zero if the value is equal to or below the required value. For other messages the function should either process them internally and return a zero value, or return a non-zero value to ensure that they are processed by the default API message handler.

Note:

You should not attempt to call any Essbase API functions from within your custom message function, with the exception of the memory management API functions, EssAlloc(), EssRealloc(), and EssFree().

If you define your own custom message handling function, any other applications simultaneously using the API will not be affected; each application which calls EssInit() can independently choose whether to define its own custom message function or just use the default message handler.