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

Create an MQMessage object and then use the Read and Write methods to transfer data between the message and other objects in the application. Send and receive MQMessage objects using the Put and Get methods of the MQDestination, MQQueue and MQTopic classes.

• Properties
• Read and Write message methods
• Buffer methods
• Property methods
• Constructors

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.

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.

1. Binary integer

   MQC.MQENC_INTEGER_NORMAL

   Big-endian integers.

   MQC.MQENC_INTEGER_REVERSED

   Little-endian integers, as used in Intel architecture.

2. Packed-decimal

   MQC.MQENC_DECIMAL_NORMAL

   Big-endian packed-decimal, as used by z/OS .

   MQC.MQENC_DECIMAL_REVERSED

   Little-endian packed-decimal.

3. 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 value is:

MQC.MQENC_INTEGER_REVERSED |
MQC.MQENC_DECIMAL_REVERSED |
MQC.MQENC_FLOAT_IEEE_REVERSED

The default setting causes WriteInt to write a little-endian integer, and ReadInt to read a little-endian integer. If you set the flag 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.

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 is MQC.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

Application-defined feedback values in the range MQC.MQFB_APPL_FIRST to MQC.MQFB_APPL_LAST can also be used. The default value of this field is MQC.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. We 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.

The default value is 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 is MQC.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

Application-defined values can also be used, in the range MQC.MQMT_APPL_FIRST to MQC.MQMT_APPL_LAST. The default value of this field is MQC.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

The default value is 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 is MQC.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

The default value is 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

The default value is 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 and MQC.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.

Any combination of the four report types can be requested:

• 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.
  1. Confirm on arrival
     • MQC.MQRO_COA
     • MQC.MQRO_COA_WITH_DATA
     • MQC.MQRO_COA_WITH_FULL_DATA **

  2. Confirm on delivery
     • MQC.MQRO_COD
     • MQC.MQRO_COD_WITH_DATA
     • MQC.MQRO_COD_WITH_FULL_DATA **

  3. Exception
     • MQC.MQRO_EXCEPTION
     • MQC.MQRO_EXCEPTION_WITH_DATA
     • MQC.MQRO_EXCEPTION_WITH_FULL_DATA **

  4. 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 the application is likely to access a z/OS queue manager, regardless of the platform on which the application is running.

• 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
  

• We 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. We 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 or sbyte 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-endian MQC.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 and MQC.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.

public bool ReadBoolean();

public void WriteBoolean(bool value);

public byte ReadByte()
public byte ReadUnsignedByte()

public void Write(int value)
public void WriteByte(int value)
public void WriteByte(byte value)
public void WriteByte(sbyte value)

public byte[] ReadBytes(int count)
public void ReadFully(ref byte[] value)
public void ReadFully(ref sbyte[] value)
public void ReadFully(ref byte[] value, int offset,int length)
public void ReadFully(ref sbyte[] value, int offset,int length)

public void Write(byte[] value)
public void Write(sbyte[] value)
public void Write(byte[] value, int offset,int length)
public void Write(sbyte[] value, int offset,int length)
public void WriteBytes(string value)

public void WriteDecimal2(short value)

public void WriteDecimal4(short value)

public void WriteDecimal8(short value)

public double ReadDouble()

public void WriteDouble(double value)

public float ReadFloat()

public void WriteFloat(float value)

public void WriteInt2(int value)

public int readDecimal4()
public int ReadInt()
public int ReadInt4()

public void WriteInt(int value)
public void WriteInt4(int value)

public void WriteInt8(long value)

public long ReadDecimal8()
public long ReadLong()
public long ReadInt8()

public void WriteLong(long value)

public Object ReadObject()

public void WriteObject(Object object)

public short ReadShort()
public short ReadDecimal2()
public short ReadInt2()

public void WriteShort(int value)

public string ReadString(int length)

public void WriteString(string string)

public ushort ReadUnsignedShort()
public ushort ReadUInt2()

public string ReadLine()
public char ReadChar()

public void WriteChar(int value)
public void WriteChars(string string)

public string ReadUTF()

public void WriteUTF(string string)

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 returns n, 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.

public boolean GetBooleanProperty(string name);
public boolean GetBooleanProperty(string name, MQPropertyDescriptor pd);

public void SetBooleanProperty(string name, boolean value);
public void SetBooleanProperty(string name, MQPropertyDescriptor pd, boolean value);

public sbyte GetByteProperty(string name);
public sbyte GetByteProperty(string name, MQPropertyDescriptor pd);

public void SetByteProperty(string name, sbyte value);
public void SetByteProperty(string name, MQPropertyDescriptor pd, sbyte value);

public sbyte[] GetBytesProperty(string name);
public sbyte[] GetBytesProperty(string name, MQPropertyDescriptor pd);

public void SetBytesProperty(string name, sbyte[] value);
public void SetBytesProperty(string name, MQPropertyDescriptor pd, sbyte[] value);

public double GetDoubleProperty(string name);
public double GetDoubleProperty(string name, MQPropertyDescriptor pd);

public void SetDoubleProperty(string name, double value);
public void SetDoubleProperty(string name, MQPropertyDescriptor pd, double value);

public float GetFloatProperty(string name);
public float GetFloatProperty(string name, MQPropertyDescriptor pd);

public void SetFloatProperty(string name, float value);
public void SetFloatProperty(string name, MQPropertyDescriptor pd, float value);

public short GetInt2Property(string name);
public short GetInt2Property(string name, MQPropertyDescriptor pd);

public void SetInt2Property(string name, short value);
public void SetInt2Property(string name, MQPropertyDescriptor pd, short value);

public int GetInt4Property(string name);
public int GetInt4Property(string name, MQPropertyDescriptor pd);

public void SetInt4Property(string name, int value);
public void SetInt4Property(string name, MQPropertyDescriptor pd, int value);

public long GetInt8Property(string name);
public long GetInt8Property(string name, MQPropertyDescriptor pd);

public void SetInt8Property(string name, long value);
public void SetInt8Property(string name, MQPropertyDescriptor pd, long value);

public long GetLongProperty(string name);
public long GetLongProperty(string name, MQPropertyDescriptor pd);

public void SetLongProperty(string name, long value);
public void SetLongProperty(string name, MQPropertyDescriptor pd, long value);

public Object GetObjectProperty(string name);
public Object GetObjectProperty(string name, MQPropertyDescriptor pd);

public void SetObjectProperty(string name, Object value);
public void SetObjectProperty(string name, MQPropertyDescriptor pd, Object value);

public short GetShortProperty(string name);
public short GetShortProperty(string name, MQPropertyDescriptor pd);

public void SetShortProperty(string name, short value);
public void SetShortProperty(string name, MQPropertyDescriptor pd, short value);

public string GetStringProperty(string name);
public string GetStringProperty(string name, MQPropertyDescriptor pd);

public void SetStringProperty(string name, string value);
public void SetStringProperty(string name, MQPropertyDescriptor pd, string value);

Constructors

public MQMessage();

Creates an MQMessage object with default message descriptor information and an empty message buffer.

Parent topic: The IBM MQ .NET classes and interfaces