Format of message control information and message data
The queue manager is only interested in the format of the control information within a message, whereas applications that handle the message are interested in the format of both the control information and the data.
Format of message control information
Control information in the character-string fields of the message descriptor must be in the character set used by the queue manager. The CodedCharSetId attribute of the queue manager object defines this character set. Control information must be in this character set because when applications pass messages from one queue manager to another, message channel agents that transmit the messages use the value of this attribute to determine what data conversion they must perform.
Format of message data
You can specify any of the following:
- The format of the application data
- The character set of the character data
- The format of numeric data
To do this, use these fields:
- Format
- This indicates to the receiver of a message the format of the application data in the message.
When the queue manager creates a message, in some circumstances it uses the Format field to identify the format of that message. For example, when a queue manager cannot deliver a message, it puts the message on a dead-letter (undelivered message) queue. It adds a header (containing more control information) to the message, and changes the Format field to show this.
The queue manager has a number of built-in formats with names beginning "MQ", for example MQFMT_STRING. If these do not meet your needs, define your own formats (user-defined formats), but not use names beginning with "MQ" for these.
When you create and use your own formats, write a data-conversion exit to support a program getting the message using MQGMO_CONVERT.
- CodedCharSetId
- This defines the character set of character data in the message. If you want to set this character set to that of the queue manager, you can set this field to the constant MQCCSI_Q_MGR or MQCCSI_INHERIT.
When you get a message from a queue, compare the value of the CodedCharSetId field with the value that your application is expecting. If the two values differ, you may need to convert any character data in the message or use a data-conversion message exit if one is available.
- Encoding
- This describes the format of numeric message data that contains binary integers, packed-decimal integers, and floating point numbers. It is usually encoded according to the particular machine on which the queue manager is running.
When you put a message on a queue, normally specify the constant MQENC_NATIVE in the Encoding field. This means that the encoding of your message data is the same as that of the machine on which your application is running.
When you get a message from a queue, compare the value of the Encoding field in the message descriptor with the value of the constant MQENC_NATIVE on your machine. If the two values differ, you may need to convert any numeric data in the message or use a data-conversion message exit if one is available.
Application data conversion
Application data may need to be converted to the character set and the encoding required by another application where different platforms are concerned. It may be converted at the sending queue manager, or at the receiving queue manager. If the library of built-in formats does not meet your needs, define your own. The type of conversion depends on the message format which is specified in the format field of the message descriptor, MQMD.
Messages with MQFMT_NONE specified are not converted.
Conversion at the sending queue manager
You must set the CONVERT channel attribute to YES if you need the sending message channel agent (MCA) to convert the application data.
The conversion is performed at the sending queue manager for certain built-in formats and for user-defined formats if a suitable user exit is supplied.
Built-in formats
These include:
- Messages that are all characters (using the format name MQFMT_STRING)
- WebSphere MQ defined messages, for example Programmable Command Formats
WebSphere MQ uses Programmable Command Format messages for administration messages and events (the format name used is MQFMT_ADMIN in this case). You can use the same format (using the format name MQFMT_PCF) for your own messages, and take advantage of the built-in data conversion.
The queue manager built-in formats all have names beginning with MQFMT. They are listed and described in WebSphere MQ Application Programming Reference under the Format field of the Message descriptor (MQMD).
Application-defined formats
For user-defined formats, application data conversion must be performed by a data-conversion exit program (for more information, see Chapter 11, Writing data-conversion exits). In a client-server environment, the exit is loaded at the server and conversion takes place there.
Conversion at the receiving queue manager
Application message data may be converted by the receiving queue manager for both built-in and user-defined formats. The conversion is performed during the processing of an MQGET call if the MQGMO_CONVERT option is specified. For details, see WebSphere MQ Application Programming Reference.
Coded character sets
WebSphere MQ products support the coded character sets that are provided by the underlying operating system.
When you create a queue manager, the queue manager coded character set ID (CCSID) used is based on that of the underlying environment. If this is a mixed code page, WebSphere MQ uses the SBCS part of the mixed code page as the queue manager CCSID.
For general data conversion, if the underlying operating system supports DBCS code pages then WebSphere MQ is able to use it.
See the documentation for your operating system for details of the coded character sets that it supports.
You need to consider application data conversion, format names, and user exits when writing applications that span multiple platforms. For details of the MQGET call, the Convert characters call, the MQGMO_CONVERT option, and the built-in formats, see WebSphere MQ Application Programming Reference. See Chapter 11, Writing data-conversion exits for information about invoking and writing data-conversion exits.
WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.