Generating a new code page converter

Generate a code page converter to handle conversions of data that belongs to a code page that is not in the default set of code pages that are provided by IBM® Integration Bus.

Before you begin

Read Code page converters, which provides information about what a code page converter is, and about the code pages that IBM Integration Bus supports.
If you apply a fix pack to IBM Integration Bus that increases the ICU version, recompile the code page converters that are used by IBM Integration Bus message flows or the DFDL parser. (The ICU version is listed in the fix pack document on the IBM Support site.)

About this task

This information is split into the following sections:

Making a new code page converter
Making the new code page converter available to IBM Integration Bus message flows
Making the new code page converter available to the DFDL parser

Making a new code page converter

Procedure

Create or find a mapping data file with the file extension .ucm for the converter that you require.
You can download .ucm files from the ICU Character set mapping files archive. These mapping data files are available and can be modified without restriction.
An example mapping data file is ibm-1284_P100-1996.ucm. (ICU is an external open source project, not an IBM tool.)
Rename the .ucm to a file name with the format ibm-number.ucm where number is a number that you choose to identify the code page. Make sure that this number is not already used in one of the Supported code pages.
For example, you could rename ibm-1284_P100-1996.ucm to ibm-1284.ucm.
Go to ICU downloads, download the source code and build binaries for your system. If you have problems building the converter, see the ICU user guide.
Extract the files from the binary distribution archive into a temporary directory.
Copy the library and binary files to a directory in the environment PATH and LIBPATH. (Alternatively, copy the library and binary files to directory that is not temporary, and modify the environment PATH and LIBPATH to include this directory.)
One of the extracted files is makeconv.exe; use this makeconv tool to convert the mapping data file (.ucm files) into a binary converter file (.cnv file), by entering the following command:
```
makeconv mapping_file.ucm 
```
where mapping_file.ucm is the mapping data file that you are using.
The name of the binary converter file that makeconv produces is:
```
mapping_file.cnv
```
where mapping_file.cnv is the name of the mapping data file that was converted.
To make the .cnv file for ibm-1284.ucm, use the following command:
```
makeconv ibm-1284.ucm
```

Making the new code page converter available to IBM Integration Bus message flows

Procedure

Copy the file with the file extension .cnv for the code page that you need, into a directory that IBM Integration Bus can access.
The name and location of the file is of the form
```
ibm-1284.cnv
```
and is located in the $ICU_DATA/icudt##<platform-suffix> directory, where icudt## is the version of ICU, which you can find in the fix pack document on the IBM Support site; for example, icudt51 for IBM Integration Bus version 10.0.0.11. <platform-suffix> is one of the following values:
- l for little-endian ASCII platforms
- b for big-endian ASCII platforms
- e for EBCDIC platforms
Optional: If you do not want the new code page converter to be in the same location as other ICU data, you must associate the broker with the new directory where the converter is stored (the directory added must contain the full path, not including the icudt48x subdirectory):
- To create a new broker that is associated with the converter, include the -c parameter on the mqsicreatebroker command.
- To alter an existing broker to recognize the converter, include the -c parameter on the mqsichangebroker command.
- To affect all the products and the broker command-line tools that are using ICU, add the directory to the ICU_DATA environment variable. If you have used either the mqsicreatebroker command or the mqsichangebroker command to specify the code page converter to be used, the broker ignores the ICU_DATA value.
  Note: To ensure consistent behavior in all components, modify the ICU_DATA environment variable.

Making the new code page converter available to the DFDL parser

Before you begin

The DFDL component includes its own copy of the ICU libraries. This copy might be a different version level to those libraries used by IBM Integration Bus. In this case, if the new code page is to be used for DFDL parsing, the new code page converter must also be copied into a specific location that can be accessed by DFDL. The DFDL component uses the environment variable ICU_DATA as a root location to search for convert tables. This environment variable should already have been set for you by running mqsiprofile.

Procedure

Copy the new code page convert .cnv file to a subdirectory beneath the location that is specified in the ICU_DATA environment variable. This subdirectory might need to be created, and its name must match the version of the ICU libraries that are supplied with the DFDL component.

For IBM Integration Bus, the new code page converter file is copied into the $ICU_DATA/icudt48<platform-suffix> directory, where the number 48 denotes the version of ICU (4.8) that IBM Integration Bus uses.

To check if the level of ICU that is used by DFDL is different to that used by IBM Integration Bus, complete one of the following tasks for your platform:
1. On Linux® and UNIX systems, look under the following path to find a library name that starts with libicudata*:
```
<product installation path>/dfdlc/lib
```
  The numerical suffix to the file name denotes the ICU version.
2. On z/OS® systems, look under the following path to find libraries with names that start with libicudata*:
```
<product installation path>/lib
```
  Any libraries that have a numerical suffix that is not 48 are the DFDL ICU libraries, and the suffix denotes the ICU version.
3. On Windows systems, look under the following path to find libraries with names that start with icudt*:
```
<product installation path>\bin
```
  Any libraries that have a numerical suffix that is not 48 are the DFDL ICU libraries, and the suffix denotes the ICU version.
If the ICU version that is used by the DFDL component within IBM Integration Bus is not 48, a new subdirectory that is named icudt<DFDL-icu-version><platform-suffix> must be created under the $ICU_DATAdirectory.
For example: If ICU libraries with a suffix of 51 are found, then the new code page converter file for DFDL must be copied to $ICU_DATA/icudt51<platform-suffix> directory, where the <platform-suffix> is one of the following values:
- l for little-endian ASCII platforms
- b for big-endian ASCII platforms
- e for EBCDIC platforms