MQMessage.NET class
Use MQMessage to access the message descriptor and data for an IBM® MQ message. MQMessage encapsulates an IBM 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 IBM 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.
- SetProperty and GetProperty methods
- All the SetProperty and GetProperty methods throw
MQException.
The SetProperty method of MQMessage .NET class adds a new property if a property does not exist already. However, if the property already exists, then the supplied property value is added to the end of the list. When multiple values are set to a property name using SetProperty, calling GetProperty for that name returns those values sequentially in the order that those values were set.
The behavior is same for all the Set*Property and Get*Property typed methods such as GetLongProperty, SetLongProperty, GetBooleanProperty, SetBooleanProperty, GetStringProperty, and SetStringProperty.
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.