Start of change

Creating message catalogs

Create your own message catalogs to write tailored entries to the local error log.

In some error and other situations, you might choose to write information to the error log so that you can track what is happening in a message flow. You can use the Throw and Trace built-in nodes to generate entries in the log, or you can create your own nodes and user exits, and write entries in the log from your user-defined extensions.

You can write either or both of the following sets of messages:

Start of changeThe instructions in this topic describe how to create message catalogs for C programs. If you want to create a Java resource bundle, refer to the documentation for the Java 2 Platform, Standard Edition.End of change

Read the section appropriate to your broker operating platform:

Building and installing a Windows message source

On Windows®, you must create your additional message catalog as a DLL file. The DLL file contains definitions of your event messages which the event viewer can display in a readable format, based on the event message written by your application. When you compile a message catalog, a header file is created that defines symbolic values for each event message number you have created. You must include the header file in 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® Developer Network Web site, and search on .mc file for details on the format of this input file.
  2. Compile the message file to create a resource compiler input file:
    mc -v -w -s -h c:\mymessages -r c:\mymessages mymsg.mc

    where c:\mymessages is the location of the output files and mymsg.mc is the name of the input file.

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

  3. Compile the output file (.rc) from the message compiler to create a resource file (.res):
    RC /v output_file.rc
  4. Create a resource DLL file from the .res file:
    LINK /DLL /NOENTRY resource_file.res
  5. Start of changeAppend the location of the resource DLL file to the MQSI_CONSOLE_NLSPATH environment variable, for example:
    set MQSI_CONSOLE_NLSPATH=%MQSI_CONSOLE_NSPATH%;c:\messages
    You can do this by creating a custom environment script in your working directory. The default location is %ALLUSERSPROFILE%\Application Data\IBM\MQSI\common\profiles where %ALLUSERSPROFILE% is the environment variable that defines the system working directory. The default value is C:\Documents and Settings\All Users. The actual value might be different on your computer.End of change
  6. Install the event source into the Windows Event Log Service:
    1. Start the Windows Registry Editor:
      regedit
    2. Create a new registry subkey for your user-defined extension under the existing structure:
      HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application

      Right-click 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 for the messageSource on a utility function in your user-defined extension (for example, CciLog) or as the property of the built-in node that you have included in your message flow.

      Create the following values for this entry:

      EventMessageFile
      Set the value of this string to contain the fully qualified path for the DLL file that you have created to contain your messages. This entry represents the message catalog.
      TypesSupported
      Set the DWORD value to "7".

Creating an XPG/4 catalog for Linux, UNIX, and z/OS

Start of change

On Linux®, UNIX®, and z/OS® systems, messages are written to the SYSLOG facility. If you want to use your own message catalog, you must create an XPG/4 message catalog.

The process for creating a message catalog (a .cat file) depends on the operating system on which you are creating it. The commands that you use are typically gencat (create or modify a message catalog) and dspcat (to display all or part of a message catalog). The gencat command merges text files that contain your message text, to create or modify a formatted catalog. The text files typically have a file extension of .msg.

You must append the location of the message catalog to the NLSPATH environment variable. You can use %L and %N to represent the locale and the catalog name, for example:
export NLSPATH=${NLSPATH}:${MY_INST_PATH}/messages/%L/%N:${MY_INST_PATH}/messages/En_US/%N
In this example, the English version is hardcoded later in the search path, ensuring that messages are displayed even in locales for which no .cat file exists.
The messages that you define in the .msg files can include variables that are substituted at run time. Such variables must be of the format {number}, where {number} is the message insert number, surrounded by braces. The first message insert is numbered 0. For example:
1234 "MSG1234E: \ 
Syntax Error. \n 
The value '{0}' is not valid for property '{1}'.\n
Correct it and then reissue the command.\n"

If you create a message catalog on one operating system, you cannot port it to another operating system because the catalogs are binary-encoded. However, you can use the same .msg files as input to the gencat command on another system.

See the relevant information in the documentation for your operating system. For example:

  • AIX platform For AIX®, see the Commands Reference in the information center.
  • z/OS platform Forz/OS, see the UNIX System Services Command Reference in the LibraryCenter.

You must also check the information about additional supported locales, if you want to use messages in locales other than US English.

End of change
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2009Copyright IBM Corporation 1999, 2009.
Last updated : 2009-01-07 15:23:06

as04521_

End of change