MQMessage .NET class
Use MQMessage to access the message descriptor and data for a WebSphere® MQ message. MQMessage encapsulates a WebSphere MQ message.
Class
System.Object
│
└─ IBM.WMQ.MQBase
│
└─ IBM.WMQ.MQBaseObject
│
└─ IBM.WMQ.MQMessage
public class IBM.WMQ.MQMessage extends IBM.WMQ.MQBaseObject;
Create an MQMessage object and then use the Read and Write methods to transfer data between the message and other objects in your application. Send and receive MQMessage objects using the Put and Get methods of the MQDestination, MQQueue and MQTopic classes.
Properties
Test for MQException being thrown when getting properties.
public string AccountingToken {get; set;}
- Part of the identity context of the message; it helps an application
to charge for work done as a result of the message. The default value
is
MQC.MQACT_NONE
. public string ApplicationIdData {get; set;}
- Part of the identity context of the message. ApplicationIdData is
information that is defined by the application suite, and can be used
to provide additional information about the message or its originator.
The default value is
""
. public string ApplicationOriginData {get; set;}
- Information defined by the application that can be used to provide
additional information about the origin of the message. The default
value is
""
. public int BackoutCount {get;}
- A count of the number of times the message has previously been returned and backed out by an MQQueue.Get call as part of a unit of work. The default value is zero.
public int CharacterSet {get; set;}
The coded character set identifier of character data in the message.
Set CharacterSet to identify the character set of character data in the message. Get CharacterSet to find out in what character set has been used to encode character data in the message.
.NET applications always run in Unicode, whereas in other environments applications run in the same character set as the queue manager is running under.
The ReadString and ReadLine methods convert the character data in the message to Unicode for you.
The WriteString method converts from Unicode to the character set encoded in CharacterSet. If CharacterSet is set to its default value,
MQC.MQCCSI_Q_MGR
, which is 0, no conversion takes place and CharacterSet is set to 1200. If you set CharacterSet to some other value, WriteString converts from Unicode to the alternate value.Note: Other read and write methods do not use CharacterSet.- ReadChar and WriteChar read and write a Unicode character to and from the message buffer without conversion.
- ReadUTF and WriteUTF convert between a Unicode string in the application, and a UTF-8 string, prefixed by a 2-byte length field, in the message buffer.
- Byte methods transfer bytes between the application and the message buffer without alteration.
public byte[] CorrelationId {get; set;}
- For an MQQueue.Get call, the correlation identifier
of the message to be retrieved. The queue manager returns the first
message with a message identifier and a correlation identifier that
match the message descriptor fields. The default value,
MQC.MQCI_NONE
, helps any correlation identifier to match. - For an MQQueue.Put call, the correlation identifier to set.
- For an MQQueue.Get call, the correlation identifier
of the message to be retrieved. The queue manager returns the first
message with a message identifier and a correlation identifier that
match the message descriptor fields. The default value,
public int DataLength {get;}
- The number of bytes of message data remaining to be read.
public int DataOffset {get; set;}
- The current cursor position within the message data. Reads and writes take effect at the current position.
public int Encoding {get; set;}
- The representation used for numeric values in the application
message data. Encoding applies to binary, packed
decimal, and floating point data. The behavior of the read and write
methods for these numeric formats is altered accordingly. Construct
a value for the encoding field by adding one value from each of these
three sections. Alternatively, construct the value combining the values
from each of the three sections using the bitwise OR operator.
- Binary integer
MQC.MQENC_INTEGER_NORMAL
- Big-endian integers.
MQC.MQENC_INTEGER_REVERSED
- Little-endian integers, as used in Intel architecture.
- Packed-decimal
MQC.MQENC_DECIMAL_NORMAL
- Big-endian packed-decimal, as used by z/OS®.
MQC.MQENC_DECIMAL_REVERSED
- Little-endian packed-decimal.
- Floating-point
MQC.MQENC_FLOAT_IEEE_NORMAL
- Big-endian IEEE floats.
MQC.MQENC_FLOAT_IEEE_REVERSED
- Little-endian IEEE floats, as used Intel architecture.
MQC.MQENC_FLOAT_S390
- z/OS format floating points.
The default setting causes WriteInt to write a little-endian integer, and ReadInt to read a little-endian integer. If you set the flagMQC.MQENC_INTEGER_REVERSED | MQC.MQENC_DECIMAL_REVERSED | MQC.MQENC_FLOAT_IEEE_REVERSED
MQC.MQENC_INTEGER_NORMAL
flag instead, WriteInt writes a big-endian integer, and ReadInt reads a big-endian integer.Note: A loss in precision can occur when converting from IEEE format floating points to zSeries format floating points. - Binary integer
public int Expiry {get; set;}
- An expiry time expressed in tenths of a second, set by the application
that puts the message. After the expiry time of a message has elapsed,
it is eligible to be discarded by the queue manager. If the message
specified one of the
MQC.MQRO_EXPIRATION
flags, a report is generated when the message is discarded. The default value isMQC.MQEI_UNLIMITED
, meaning that the message never expires. public int Feedback {get; set;}
- Use Feedback with a message of type
MQC.MQMT_REPORT
to indicate the nature of the report. The following feedback codes are defined by the system:MQC.MQFB_EXPIRATION
MQC.MQFB_COA
MQC.MQFB_COD
MQC.MQFB_QUIT
MQC.MQFB_PAN
MQC.MQFB_NAN
MQC.MQFB_DATA_LENGTH_ZERO
MQC.MQFB_DATA_LENGTH_NEGATIVE
MQC.MQFB_DATA_LENGTH_TOO_BIG
MQC.MQFB_BUFFER_OVERFLOW
MQC.MQFB_LENGTH_OFF_BY_ONE
MQC.MQFB_IIH_ERROR
MQC.MQFB_APPL_FIRST
toMQC.MQFB_APPL_LAST
can also be used. The default value of this field isMQC.MQFB_NONE
, indicating that no feedback is provided. public string Format {get; set;}
- A format name used by the sender of the message to indicate the
nature of the data in the message to the receiver. You can use your
own format names, but names beginning with the letters
MQ
have meanings that are defined by the queue manager. The queue manager built-in formats are:MQC.MQFMT_ADMIN
- Command server request/reply message.
MQC.MQFMT_COMMAND_1
- Type 1 command reply message.
MQC.MQFMT_COMMAND_2
- Type 2 command reply message.
MQC.MQFMT_DEAD_LETTER_HEADER
- Dead-letter header.
MQC.MQFMT_EVENT
- Event message.
MQC.MQFMT_NONE
- No format name.
MQC.MQFMT_PCF
- User-defined message in programmable command format.
MQC.MQFMT_STRING
- Message consisting entirely of characters.
MQC.MQFMT_TRIGGER
- Trigger message
MQC.MQFMT_XMIT_Q_HEADER
- Transmission queue header.
MQC.MQFMT_NONE
. public byte[] GroupId {get; set;}
- A byte string that identifies the message group to which the physical
message belongs. The default value is
MQC.MQGI_NONE
. public int MessageFlags {get; set;}
- Flags controlling the segmentation and status of a message.
public byte[] MessageId {get; set;}
-
For an MQQueue.Get call, this field specifies the message identifier of the message to be retrieved. Normally, the queue manager returns the first message with a message identifier and correlation identifier that match the message descriptor fields. Allow any message identifier to match using the special value
MQC.MQMI_NONE
.For an MQQueue.Put call, this field specifies the message identifier to use. If
MQC.MQMI_NONE
s specified, the queue manager generates a unique message identifier when the message is put. The value of this member variable is updated after the put, to indicate the message identifier that was used. The default value isMQC.MQMI_NONE
. public int MessageLength {get;}
- The number of bytes of message data in the MQMessage object.
public int MessageSequenceNumber {get; set;}
- The sequence number of a logical message within a group.
public int MessageType {get; set;}
- Indicates the type of the message. The following values are currently
defined by the system:
MQC.MQMT_DATAGRAM
MQC.MQMT_REPLY
MQC.MQMT_REPORT
MQC.MQMT_REQUEST
MQC.MQMT_APPL_FIRST
toMQC.MQMT_APPL_LAST
. The default value of this field isMQC.MQMT_DATAGRAM
. public int Offset {get; set;}
- In a segmented message, the offset of data in a physical message from the start of a logical message.
public int OriginalLength {get; set;}
- The original length of a segmented message.
public int Persistence {get; set;}
- Message persistence. The following values are defined:
MQC.MQPER_NOT_PERSISTENT
If you set this option in a reconnectable client, the
MQRC_NONE
reason code is returned to the application when the connection is successful.MQC.MQPER_PERSISTENT
If you set this option in a reconnectable client, the
MQRC_CALL_INTERRUPTED
reason code is returned to the application after the connection is successful.MQC.MQPER_PERSISTENCE_AS_Q_DEF
MQC.MQPER_PERSISTENCE_AS_Q_DEF
, which takes the persistence for the message from the default persistence attribute of the destination queue. public int Priority {get; set;}
- The message priority. The special value
MQC.MQPRI_PRIORITY_AS_Q_DEF
can also be set in outbound message. The priority for the message is then taken from the default priority attribute of the destination queue. The default value isMQC.MQPRI_PRIORITY_AS_Q_DEF
. public int PropertyValidation {get; set;}
- Specifies whether validation of properties takes place when a
property of the message is set. Possible values are:
MQCMHO_DEFAULT_VALIDATION
MQCMHO_VALIDATE
MQCMHO_NO_VALIDATION
MQCMHO_DEFAULT_VALIDATION
. public string PutApplicationName {get; set;}
- The name of the application that put the message. The default
value is
""
. public int PutApplicationType {get; set;}
- The type of application that put the message. PutApplicationType can
be a system-defined or user-defined value. The following values are
defined by the system:
MQC.MQAT_AIX
MQC.MQAT_CICS
MQC.MQAT_DOS
MQC.MQAT_IMS
MQC.MQAT_MVS
MQC.MQAT_OS2
MQC.MQAT_OS400
MQC.MQAT_QMGR
MQC.MQAT_UNIX
MQC.MQAT_WINDOWS
MQC.MQAT_JAVA
MQC.MQAT_NO_CONTEXT
, which indicates that no context information is present in the message. public DateTime PutDateTime {get; set;}
- The time and date that the message was put.
public string ReplyToQueueManagerName {get; set;}
- The name of the queue manager to send reply or report messages.
The default value is
""
, and the queue manager provides the ReplyToQueueManagerName. public string ReplyToQueueName {get; set;}
- The name of the message queue to which the application that issued
the get request for the message sends
MQC.MQMT_REPLY
andMQC.MQMT_REPORT
messages. The default ReplyToQueueName is""
. public int Report {get; set;}
- Use Report to specify options about report and
reply messages:
- Whether reports are required.
- Whether the application message data is to be included in the reports.
- How to set the message and correlation identifiers in the report or reply.
- Specify any combination of the four report types. Selecting any
of the three options for each report type, depending on whether the
application message data is to be included in the report message.
- Confirm on arrival
MQC.MQRO_COA
MQC.MQRO_COA_WITH_DATA
MQC.MQRO_COA_WITH_FULL_DATA
**
- Confirm on delivery
MQC.MQRO_COD
MQC.MQRO_COD_WITH_DATA
MQC.MQRO_COD_WITH_FULL_DATA
**
- Exception
MQC.MQRO_EXCEPTION
MQC.MQRO_EXCEPTION_WITH_DATA
MQC.MQRO_EXCEPTION_WITH_FULL_DATA
**
- Expiration
MQC.MQRO_EXPIRATION
MQC.MQRO_EXPIRATION_WITH_DATA
MQC.MQRO_EXPIRATION_WITH_FULL_DATA
**
Note: Values marked with**
in the list are not supported by z/OS queue managers. Do not use them if your application is likely to access a z/OS queue manager, regardless of the platform on which the application is running. - Confirm on arrival
- Specify one of the following to control how the message ID is
generated for the report or reply message:
MQC.MQRO_NEW_MSG_ID
MQC.MQRO_PASS_MSG_ID
- Specify one of the following to control how the correlation ID
of the report or reply message is to be set:
MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID
MQC.MQRO_PASS_CORREL_ID
- Specify one of the following to control the disposition of the
original message when it cannot be delivered to the destination queue:
MQC.MQRO_DEAD_LETTER_Q
MQC.MQRO_DISCARD_MSG
**
- If no report options are specified, the default is:
MQC.MQRO_NEW_MSG_ID | MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID | MQC.MQRO_DEAD_LETTER_Q
- You can specify one or both of the following to request that the
receiving application sends a positive action or negative action report
message.
MQC.MQRO_PAN
MQC.MQRO_NAN
public int TotalMessageLength {get;}
- The total number of bytes in the message as stored on the message queue from which this message was received.
public string UserId {get; set;}
- UserId is part of the identity context of the message. The queue manager generally provides the value. You can override the value if you have authority to set the identity context.
public int Version {get; set;}
- The version of the MQMD structure in use.
Read and Write message methods
The Read and Write methods
perform the same functions as the members of the BinaryReader and BinaryWriter classes
in the .NET System.IO
namespace. See MSDN for the
full language syntax and usage examples. The methods read or write
from the current position in the message buffer. They move the current
position forward by the number of bytes read or written.
- All the methods throw IOException.
- The ReadFully methods automatically resize
the target
byte
orsbyte
array to fit the message exactly. A null array is also resized. - Read methods throw EndOfStreamException.
- WriteDecimal methods throw MQException.
- ReadString, ReadLine and WriteString methods convert between Unicode and the character set of the message; see CharacterSet.
- The Decimal methods read and write packed decimal
numbers encoded either in big-endian,
MQC.MQENC_DECIMAL_NORMAL
, or little-endianMQC.MQENC_DECIMAL_REVERSE
format, according to the value of Encoding. Decimal ranges and corresponding .NET types are as follows:Decimal2/short
- -999 to 999
Decimal4/int
- -9999999 to 9999999
Decimal8/long
- -999999999999999 to 999999999999999
- The Double and Float methods
read and write floating values encoded in IEE big-endian and little-endian
formats,
MQC.MQENC_FLOAT_IEEE_NORMAL
andMQC.MQENC_FLOAT_IEEE_REVERSED
, or in S/390 format,MQC.MQENC_FLOAT_S390
, according to the value of Encoding. - The Int methods read and write integer values
encoded in big-endian,
MQC.MQENC_INTEGER_NORMAL
, or little-endian,MQC.MQENC_INTEGER_REVERSED
, format, according to the value of Encoding. The integers are all signed, except for the addition of an unsigned 2-byte integer type. The integer sizes, and .NET and WebSphere MQ types are as follows:- 2 byte
short
,Int2
,ushort
,UInt2
- 4 byte
int
,Int4
- 8 byte
long
,Int8
- WriteObject transfers the class of an object, the values of its non-transient and non-static fields, and the fields of its supertypes, to the message buffer.
- ReadObject creates an object from the class of the object, the signature of the class, and the values of its non-transient and non-static fields, and the fields of its supertypes.
Target type | Method signatures |
---|---|
Boolean |
|
Byte |
|
Bytes |
|
Decimal2 |
|
Decimal4 |
|
Decimal8 |
|
Double |
|
Float |
|
Int2 |
|
Int4 |
|
Int8 |
|
Long |
|
Object |
|
Short |
|
string |
|
Unsigned Short |
|
Unicode |
|
UTF |
|
Buffer methods
public void ClearMessage();
Throws IOException.
Discards any data in the message buffer and sets the data offset back to zero.
public void ResizeBuffer(int size)
-
Throws IOException.
A hint to the MQMessage object about the size of buffer that might be required for subsequent get operations. If the message currently contains message data, and the new size is less than the current size, the message data is truncated.
public void Seek(int pos)
-
Throws IOException, ArgumentOutOfRangeException, ArgumentException.
Moves the cursor to the absolute position in the message buffer given by pos. Subsequent reads and writes act at this position in the buffer.
public int SkipBytes(int i)
-
Throws IOException, EndOfStreamException.
Moves forward
n
bytes in the message buffer and returnsn
, the number of bytes skipped.SkipBytes method blocks until one of the following events occurs:- All the bytes are skipped
- The end of message buffer is detected
- An exception is thrown
Property methods
public void DeleteProperty(string name);
Throws MQException.
Deletes a property with the specified name from the message.name
- The name of the property to delete.
public System.Collections.IEnumerator GetPropertyNames(string name)
Throws MQException.
Returns an IEnumerator of all the property names matching the specified name. The percent sign'%'
can be used at the end of the name as a wildcard character to filter the properties of the message, matching on zero, or more characters, including the period.name
- The name of the property to match on.
- All the SetProperty and GetProperty methods throw MQException
Type | Method signatures |
---|---|
Boolean |
|
Byte |
|
Bytes |
|
Double |
|
Float |
|
Int2 |
|
Int4 |
|
Int8 |
|
Long |
|
Object |
|
Short |
|
string |
|
Constructors
public MQMessage();
- Creates an MQMessage object with default message descriptor information and an empty message buffer.