IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

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:

A fixed set of messages that are provided in the product message catalog. This set provides a range of numbers for Throw nodes (BIP3001 to BIP3049), and a second range for Trace nodes (BIP3051 to BIP3099). A third range (BIP2951 to BIP2999) is provided for the ESQL statements LOG and THROW.
When you use these messages, you can also provide additional text that is displayed in the message text.
Your own messages, created in your own message catalog. You can use this additional catalog to define specialized message content, and you can include variables or inserts that are determined by the code that generates the message. You can also share your own message catalog with other applications that are not associated with IBM® Integration Bus.

When you throw an exception from ESQL by using a THROW statement, the ESQL code adds an extra leading insert that contains the name of the current component. The rest of the inserts that are provided by the ESQL script follow this leading insert. Therefore, you must consider this insert when you are writing your own message catalog.

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

Read the section appropriate to your broker operating system:

Building and installing a Windows message source
Creating an XPG/4 catalog for Linux, UNIX, and z/OS

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:

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.
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.
Compile the output file (.rc) from the message compiler to create a resource file (.res):
```
RC /v output_file.rc
```
Create a resource DLL file from the .res file:
```
LINK /DLL /NOENTRY resource_file.res
```
Append the location of the resource DLL file to the MQSI_CONSOLE_NLSPATH environment variable, for example:
```
set MQSI_CONSOLE_NLSPATH=%MQSI_CONSOLE_NLSPATH%;c:\messages
```
You can do this by creating a custom environment script in your working directory. The default location is C:\ProgramData\IBM\MQSI\Common\profiles.
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 IBM Integration Bus 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

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 MQSI_CONSOLE_NLSPATH environment variable. You can use %L and %N to represent the locale and the catalog name, for example:

export MQSI_CONSOLE_NLSPATH=${MQSI_CONSOLE_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:

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

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

as04521_.htm |

Last updated Friday, 21 July 2017