Using event logging from a user-defined extension

Message processing nodes and parsers are unlikely to need to write directly to the local error log, because it is recommended that a user-defined extension reports errors using exceptions. However, you can choose to write significant events, error or otherwise, for problem determination and operational purposes in the same manner as WebSphere Message Broker.

With C code, you use the utility function CciLog to do this. Two of the arguments accepted by this function, messageSource and messageNumber, define the event source and the actual integer representation of a message within that source, respectively.

For Java code, the class MbService provides static methods to log information to the event log. To log messages to the event log, you need to package your messages into a standard Java resource bundle. You can use one of the three logging methods, passing in the resource bundle name and the message key. The message is fully resolved and is then inserted as a single insert into the appropriate broker message as shown below:

For Windows systems, the messages are written to the Windows event log, and your message catalog must be delivered as a Windows DLL.

For Linux and UNIX systems, these messages are written to the SYSLOG facility, and your message catalog must be delivered as an XPG4 message catalog.

The above covers exceptions raised during normal processing. You must also provide for exceptions raised when deploying and configuring a message flow. Messages resulting from these configuration exceptions are reported back to the workbench for display to the workbench user. To facilitate this, you must create an appropriately named Java properties file and copy it to each workbench.

Building and installing a Windows event source

On Windows, the message catalog is delivered as a Windows DLL, which you must create as described below. This contains definitions of your event messages to enable the event viewer to display a readable format, based on the event message written by your application. When you compile a message catalog, a header file is created, which defines symbolic values for each event message number you have created. This header file is included by your application.

To create an event source for the Windows Event Log Service:
  1. Create a message compiler input (.mc) file with the source for your event messages. Refer to the Microsoft website, http://msdn.microsoft.com, and search on .mc file for details on the format of this input file.
  2. Compile this message file, to create a resource compiler input file, by issuing the command:
    mc -v -w -s -h c:\mymessages -r c:\mymessages mymsg.mc 

    Where c:\mymessages is the path and directory for the output files and mymsg.mc is the name of the input file.

    The message compiler produces an output header (.h) file which contains symbolic #defines that map to each message number coded in the input.mc file. This header file must be included when compiling a user-defined extension source file that uses the CciLog utility function to write an event message you have defined. The messageNumber argument to CciLog must use the appropriate value hash-defined in the output header file.

  3. Compile the output file (.rc) from the message compiler to create a resource (.res) file by issuing the command:
    RC /v <filename>.rc
  4. Create a resource DLL using the .res file by issuing the command:
    LINK /DLL /NOENTRY <filename>.res
To install the event source into the Windows Event Log Service:
  1. Start the Windows Registry Editor by issuing the command:
    regedit
  2. Create a new registry subkey for your user-defined extension under the existing structure defined in:
    HKEY_LOCAL_MACHINE
       SYSTEM
          CurrentControlSet
             Services
                EventLog
                   Application

    Right-click on Application and select New->Key. The new key is created immediately under the Application key (not under the WebSphere Message Broker key). You must give the key the name that you specify on the messageSource parameter of the CciLog invocation.

    You must create the following values for this entry:
    • The EventMessageFile String value must contain the fully qualified path for the .dll you have created to contain your messages. This is the message catalog used by CciLog.
    • The TypesSupported DWORD value must contain the value "7".