WebSphere WebSphere Business Integration Message Service Clients for C/C++ Version 1.2.7 and .NET Version 1.2.6 Operating Systems: AIX, Linux, Solaris, Windows

Coded character set identifiers

For C or C++ strings of character set identifiers (CCSIDs) that an object passes to, or receives from, XMS might require conversion. The XMSC_CLIENT_CCSID property of the object tells XMS which code page the object is using.

When an object in a C or C++ application passes a string of character data to XMS across the API XMS converts (if necessary) the character data in the string from the code page used by the object into the code page required by XMS for the data. Similarly, when an object receives a string of character data from XMS across the API XMS converts (if necessary) the character data in the string from the code page that the data is currently in into the code page used by the object. Therefore, in order to convert the character data in a string, XMS must identify which code page an object is using.

The XMSC_CLIENT_CCSID property of a ConnectionFactory, Connection, Session, MessageProducer, or MessageConsumer object specifies which code page the object is using. The value of the XMSC_CLIENT_CCSID propertyis a CCSID which identifies a code page. XMS sets the property when an application creates one of these objects, but the application can change its value subsequently.

When an application starts, XMS derives an appropriate CCSID for the application from the environment in which the application is running. This CCSID is called the process CCSID. At any time, the application can change the process CCSID by calling xmsSetClientCCSID(). This is a C function that does not belong to any class, but C++ applications can use the function as well.

When an application creates a connection factory, XMS sets the XMSC_CLIENT_CCSID property of the object. If the connection factory is created from an object definition retrieved from a repository of administered objects, and the object definition specifies a value for the XMSC_CLIENT_CCSID property, XMS uses this value to set the property. Otherwise, XMS sets the property to the special value XMSC_CCSID_PROCESS, which means that the connection factory is using the code page identified by the process CCSID.

When an application uses a connection factory to create a connection, XMS copies the XMSC_CLIENT_CCSID property of the ConnectionFactory object to the newly created Connection object. XMS copies the property only at the time the application creates the connection. If the application subsequently changes the value of the XMSC_CLIENT_CCSID property of the ConnectionFactory object, XMS does not propagate the change to the XMSC_CLIENT_CCSID property of the Connection object.

In the same way, when an application uses a connection to create a session, XMS copies the XMSC_CLIENT_CCSID property of the Connection object to the newly created Session object. When an application uses a session to create a message producer or message consumer, XMS copies the XMSC_CLIENT_CCSID property of the Session object to the newly created MessageProducer or MessageConsumer object. In each case, XMS copies the property only at the time the application creates the object.

At any time, an application can change the value of the XMSC_CLIENT_CCSID property of an object by calling the Set Integer Property method of the PropertyContext class. The application can set the property to one of the following values:
A coded character set identifier (CCSID)
The object is using the code page identified by the specified CCSID. If the application specifies either a CCSID that is not valid or a CCSID for which the platform does not support code page conversion, the call fails and XMS returns an error.
XMSC_CCSID_UTF8
The object is using the UTF-8 representation of Unicode data.
XMSC_CCSID_UTF16
The object is using the UTF-16 representation of Unicode data.
XMSC_CCSID_UTF32
The object is using the UTF-32 representation of Unicode data.
XMSC_CCSID_PROCESS
The object is using the code page identified by the process CCSID. XMS queries the process CCSID whenever it needs to determine which code page the object is using. If the application changes the process CCSID by calling xmsSetClientCCSID(), XMS detects the change the next time it determines which code page the object is using.

This is a special value of the property and is not an actual CCSID.

XMSC_CCSID_HOST
The object is using the code page identified by the CCSID that is derived from the environment in which the application is running. This CCSID is the same as the process CCSID unless the application has changed the process CCSID by calling xmsSetClientCCSID().

This is a special value of the property and is not an actual CCSID.

XMSC_CCSID_NO_CONVERSION
Strings of character data received by the object are not converted.

This is a special value of the property and is not an actual CCSID.

The strings of character data that an application passes to, and receives from, XMS include (but are not exclusively confined to) the strings in messages. The strings that require conversion might be in any of the following parts of a message:

When XMS converts the strings in an outgoing message, it uses the code page associated with the session that created the message. When XMS converts the strings in an incoming message, it uses the code page associated with the message consumer that receives the message. XMS determines the code page from the value of the XMSC_CLIENT_CCSID property of the relevant Session or MessageConsumer object.

Converting strings in messages might have an impact on performance depending on the amount of data to be converted the frequency with which conversion occurs. If you are designing applications to maximize the throughput of messages, you might want to consider ways of reducing the amount of data conversion that is required. The following examples illustrate how this can be done:
Note: The XMSC_CLIENT_CCSID property is not required for .NET applications. In .NET, all strings are passed using the native .NET string class. Because this class has a fixed encoding, no further information is required to interpret it.

Concept topic

Terms of Use | Rate this page

Last updated: 18 Jun 2008

© Copyright IBM Corporation 2005, 2008. All Rights Reserved.