java.lang.Object | *- com.ibm.mq.MQMessage |
MQMessage represents both the message descriptor and the data for a WebSphere MQ message. There is group of readXXX methods for reading data from a message, and a group of writeXXX methods for writing data into a message. The format of numbers and strings used by these read and write methods can be controlled by the encoding and characterSet member variables. The remaining member variables contain control information that accompanies the application message data when a message travels between sending and receiving applications. The application can set values into the member variable before putting a message to a queue and can read values after retrieving a message from a queue.
Part of the identity context of the message; it allows an application to cause work done as a result of the message to be appropriately charged.
The default value is "MQC.MQACT_NONE".
Part of the identity context of the message; it 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 "".
Information defined by the application that can be used to provide additional information about the origin of the message.
The default value is "".
A count of the number of times the message has previously been returned by an MQQueue.get() call as part of a unit of work, and subsequently backed out.
The default value is zero.
This specifies the coded character set identifier of character data in the application message data. The behavior of the readString, readLine and writeString methods is altered accordingly.
The default value for this field is MQC.MQCCSI_Q_MGR. If the
default value is used, CharacterSet 819 (iso-8859-1/latin/ibm819) is
assumed. The character set values you can use will depend upon the JVM
you use. Table 13 shows coded character set identifiers and the characterSet
values to use:
Table 13. Character set identifiers
| characterSet | Description |
|---|---|
| 37 | ibm037 |
| 437 | ibm437 / PC Original |
| 500 | ibm500 |
| 819 | iso-8859-1 / latin1 / ibm819 |
| 1200 | Unicode |
| 1208 | UTF-8 |
| 273 | ibm273 |
| 277 | ibm277 |
| 278 | ibm278 |
| 280 | ibm280 |
| 284 | ibm284 |
| 285 | ibm285 |
| 297 | ibm297 |
| 420 | ibm420 |
| 424 | ibm424 |
| 737 | ibm737 / PC Greek |
| 775 | ibm775 / PC Baltic |
| 813 | iso-8859-7 / greek / ibm813 |
| 838 | ibm838 |
| 850 | ibm850 / PC Latin 1 |
| 852 | ibm852 / PC Latin 2 |
| 855 | ibm855 / PC Cyrillic |
| 856 | ibm856 |
| 857 | ibm857 / PC Turkish |
| 860 | ibm860 / PC Portuguese |
| 861 | ibm861 / PC Icelandic |
| 862 | ibm862 / PC Hebrew |
| 863 | ibm863 / PC Canadian French |
| 864 | ibm864 / PC Arabic |
| 865 | ibm865 / PC Nordic |
| 866 | ibm866 / PC Russian |
| 868 | ibm868 |
| 869 | ibm869 / PC Modern Greek |
| 870 | ibm870 |
| 871 | ibm871 |
| 874 | ibm874 |
| 875 | ibm875 |
| 912 | iso-8859-2 / latin2 / ibm912 |
| 913 | iso-8859-3 / latin3 / ibm913 |
| 914 | iso-8859-4 / latin4 / ibm914 |
| 915 | iso-8859-5 / cyrillic / ibm915 |
| 916 | iso-8859-8 / hebrew / ibm916 |
| 918 | ibm918 |
| 920 | iso-8859-9 / latin5 / ibm920 |
| 921 | ibm921 |
| 922 | ibm922 |
| 930 | ibm930 |
| 932 | PC Japanese |
| 933 | ibm933 |
| 935 | ibm935 |
| 937 | ibm937 |
| 939 | ibm939 |
| 942 | ibm942 |
| 948 | ibm948 |
| 949 | ibm949 |
| 950 | ibm950 / Big 5 Traditional Chinese |
| 954 | EUCJIS |
| 964 | ibm964 / CNS 11643 Traditional Chinese |
| 970 | ibm970 |
| 1006 | ibm1006 |
| 1025 | ibm1025 |
| 1026 | ibm1026 |
| 1089 | iso-8859-6 / arabic / ibm1089 |
| 1097 | ibm1097 |
| 1098 | ibm1098 |
| 1112 | ibm1112 |
| 1122 | ibm1122 |
| 1123 | ibm1123 |
| 1124 | ibm1124 |
| 1250 | Windows Latin 2 |
| 1251 | Windows Cyrillic |
| 1252 | Windows Latin 1 |
| 1253 | Windows Greek |
| 1254 | Windows Turkish |
| 1255 | Windows Hebrew |
| 1256 | Windows Arabic |
| 1257 | Windows Baltic |
| 1258 | Windows Vietnamese |
| 1381 | ibm1381 |
| 1383 | ibm1383 |
| 2022 | JIS |
| 5601 | ksc-5601 Korean |
| 33722 | ibm33722 |
For an MQQueue.get() call, this field specifies the correlation identifier of the message to be retrieved. Normally the queue manager returns the first message with a message identifier and correlation identifier that match those specified. The special value MQC.MQCI_NONE allows any correlation identifier to match.
For an MQQueue.put() call, this specifies the correlation identifier to use.
The default value is MQC.MQCI_NONE.
This member variable specifies the representation used for numeric values in the application message data; this applies to binary, packed decimal, and floating point data. The behavior of the read and write methods for these numeric formats is altered accordingly.
The following encodings are defined for binary integers:
The following encodings are defined for packed-decimal integers:
The following encodings are defined for floating-point numbers:
A value for the encoding field should be constructed by adding together one value from each of these three sections (or using the bitwise OR operator). The default value is:
MQC.MQENC_INTEGER_NORMAL | MQC.MQENC_DECIMAL_NORMAL | MQC.MQENC_FLOAT_IEEE_NORMAL
For convenience, this value is also represented by MQC.MQENC_NATIVE. This setting causes writeInt() to write a big-endian integer, and readInt() to read a big-endian integer. If the flag MQC.MQENC_INTEGER_REVERSED flag had been set instead, writeInt() would write a little-endian integer, and readInt() would read a little-endian integer.
Note that a loss in precision can occur when converting from IEEE format floating points to System/390(R) format floating points.
An expiry time expressed in tenths of a second, set by the application that puts the message. After a message's expiry time 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.
This is used with a message of type MQC.MQMT_REPORT to indicate the nature of the report. The following feedback codes are defined by the system:
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.
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:
The default value is MQC.MQFMT_NONE.
A byte string that identifies the message group to which the physical message belongs.
The default value is "MQC.MQGI_NONE".
Flags controlling the segmentation and status of a message.
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 those specified. The special value MQC.MQMI_NONE allows any message identifier to match.
For an MQQueue.put() call, this specifies the message identifier to use. If MQC.MQMI_NONE is 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.
The sequence number of a logical message within a group.
Indicates the type of the message. The following values are currently defined by the system:
Application-defined values can also be used. These should be in the range MQC.MQMT_APPL_FIRST to MQC.MQMT_APPL_LAST.
The default value of this field is MQC.MQMT_DATAGRAM.
In a segmented message, the offset of data in a physical message from the start of a logical message.
The original length of a segmented message.
Message persistence. The following values are defined:
The default value is MQC.MQPER_PERSISTENCE_AS_Q_DEF, which indicates that the persistence for the message should be taken from the default persistence attribute of the destination queue.
The message priority. The special value MQC.MQPRI_PRIORITY_AS_Q_DEF can also be set in outbound messages, in which case the priority for the message is taken from the default priority attribute of the destination queue.
The default value is MQC.MQPRI_PRIORITY_AS_Q_DEF.
The name of the application that put the message. The default value is "".
The type of application that put the message. This may be a system-defined or user-defined value. The following values are defined by the system:
The default value is the special value MQC.MQAT_NO_CONTEXT, which indicates that no context information is present in the message.
The time and date that the message was put.
The name of the queue manager to which reply or report messages should be sent.
The default value is "".
If the value is "" on an MQQueue.put() call, the QueueManager fills in the value.
The name of the message queue to which the application that issued the get request for the message should send MQC.MQMT_REPLY and MQC.MQMT_REPORT messages.
The default value is "".
A report is a message about another message. This member variable enables the application sending the original message to specify which report messages are required, whether the application message data is to be included in them, and also how the message and correlation identifiers in the report or reply are to be set. Any, all or none of the following report types can be requested:
For each type, only one of the three corresponding values below should be specified, depending on whether the application message data is to be included in the report message.
The valid values are:
You can specify one of the following to control how the message Id is generated for the report or reply message:
You can specify one of the following to control how the correlation Id of the report or reply message is to be set:
You can specify one of the following to control the disposition of the original message when it cannot be delivered to the destination queue:
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 send a positive action or negative action report message.
Part of the identity context of the message; it identifies the user that originated this message.
The default value is "".
Create a new message with default message descriptor information and an empty message buffer.
public void clearMessage()
Throws IOException.
Discard any data in the message buffer and set the data offset back to zero.
public int getDataLength()
Throws MQException.
The number of bytes of message data remaining to be read.
public int getDataOffset()
Throws IOException.
Return the current cursor position within the message data (the point at which read and write operations take effect).
public int getMessageLength
Throws IOException.
The number of bytes of message data in this MQMessage object.
The total number of bytes in the message as stored on the message queue from which this message was retrieved (or attempted to be retrieved). When an MQQueue.get() method fails with a message-truncated error code, this method tells you the total size of the message on the queue.
See also MQQueue.get.
Returns the version of the structure in use.
public boolean readBoolean()
Throws IOException.
Read a (signed) byte from the current position in the message buffer.
public char readChar()
Throws IOException, EOFException.
Read a Unicode character from the current position in the message buffer.
public short readDecimal2()
Throws IOException, EOFException.
Read a 2-byte packed decimal number (-999..999). The behavior of this method is controlled by the value of the encoding member variable. A value of MQC.MQENC_DECIMAL_NORMAL reads a big-endian packed decimal number, and a value of MQC.MQENC_DECIMAL_REVERSED reads a little-endian packed decimal number.
public int readDecimal4()
Throws IOException, EOFException.
Read a 4-byte packed decimal number (-9999999..9999999). The behavior of this method is controlled by the value of the encoding member variable. A value of MQC.MQENC_DECIMAL_NORMAL reads a big-endian packed decimal number, and a value of MQC.MQENC_DECIMAL_REVERSED reads a little-endian packed decimal number.
public long readDecimal8()
Throws IOException, EOFException.
Read an 8-byte packed decimal number (-999999999999999 to 999999999999999). The behavior of this method is controlled by the encoding member variable. A value of MQC.MQENC_DECIMAL_NORMAL reads a big-endian packed decimal number, and MQC.MQENC_DECIMAL_REVERSED reads a little-endian packed decimal number.
public double readDouble()
Throws IOException, EOFException.
Read a double from the current position in the message buffer. The value of the encoding member variable determines the behavior of this method.
Values of MQC.MQENC_FLOAT_IEEE_NORMAL and MQC.MQENC_FLOAT_IEEE_REVERSED read IEEE standard doubles in big-endian and little-endian formats respectively.
A value of MQC.MQENC_FLOAT_S390 reads a System/390 format floating point number.
public float readFloat()
Throws IOException, EOFException.
Read a float from the current position in the message buffer. The value of the encoding member variable determines the behavior of this method.
Values of MQC.MQENC_FLOAT_IEEE_NORMAL and MQC.MQENC_FLOAT_IEEE_REVERSED read IEEE standard floats in big-endian and little-endian formats respectively.
A value of MQC.MQENC_FLOAT_S390 reads a System/390 format floating point number.
public void readFully(byte b[])
Throws Exception, EOFException.
Fill the byte array b with data from the message buffer.
public void readFully(byte b[],
int off,
int len)
Throws IOException, EOFException.
Fill len elements of the byte array b with data from the message buffer, starting at offset off.
public int readInt()
Throws IOException, EOFException.
Read an integer from the current position in the message buffer. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_INTEGER_NORMAL reads a big-endian integer, a value of MQC.MQENC_INTEGER_REVERSED reads a little-endian integer.
public short readInt2()
Throws IOException, EOFException.
Synonym for readShort(), provided for cross-language WebSphere MQ API compatibility.
public int readInt4()
Throws IOException, EOFException.
Synonym for readInt(), provided for cross-language WebSphere MQ API compatibility.
public long readInt8()
Throws IOException, EOFException.
Synonym for readLong(), provided for cross-language WebSphere MQ API compatibility.
public String readLine()
Throws IOException.
Converts from the codeset identified in the characterSet member variable to Unicode, and then reads in a line that has been terminated by \n, \r, \r\n, or EOF.
public long readLong()
Throws IOException, EOFException.
Read a long from the current position in the message buffer. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_INTEGER_NORMAL reads a big-endian long, a value of MQC.MQENC_INTEGER_REVERSED reads a little-endian long.
public Object readObject()
Throws OptionalDataException, ClassNotFoundException, IOException.
Read an object from the message buffer. The class of the object, the signature of the class, and the value of the non-transient and non-static fields of the class are all read.
public short readShort()
Throws IOException, EOFException.
public String readString(int length)
Throws IOException, EOFException.
Read a string in the codeset identified by the characterSet member variable, and convert it into Unicode.
Parameters:
public int readUInt2()
Throws IOException, EOFException.
Synonym for readUnsignedShort(), provided for cross-language WebSphere MQ API compatibility.
public int readUnsignedByte()
Throws IOException, EOFException.
Read an unsigned byte from the current position in the message buffer.
public int readUnsignedShort()
Throws IOException, EOFException.
Read an unsigned short from the current position in the message buffer. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_INTEGER_NORMAL reads a big-endian unsigned short, a value of MQC.MQENC_INTEGER_REVERSED reads a little-endian unsigned short.
public String readUTF()
Throws IOException.
Read a UTF string, prefixed by a 2-byte length field, from the current position in the message buffer.
public void resizeBuffer(int size)
Throws IOException.
A hint to the MQMessage object about the size of buffer that may 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.
Move the cursor to the absolute position in the message buffer given by pos. Subsequent reads and writes will act at this position in the buffer.
Throws EOFException if pos is outside the message data length.
public void setDataOffset(int offset)
Throws IOException.
Move the cursor to the absolute position in the message buffer. This method is a synonym for seek(), and is provided for cross-language compatibility with the other WebSphere MQ APIs.
public void setVersion(int version)
Specifies which version of the structure to use. Possible values are:
You should not normally need to call this method unless you wish to force the client to use a version 1 structure when connected to a queue manager that is capable of handling version 2 structures. In all other situations, the client determines the correct version of the structure to use by querying the queue manager's capabilities.
public int skipBytes(int n)
Throws IOException, EOFException.
Move forward n bytes in the message buffer.
This method blocks until one of the following occurs:
Returns the number of bytes skipped, which is always n.
public void write(int b)
Throws IOException.
Write a byte into the message buffer at the current position.
public void write(byte b[])
Throws IOException.
Write an array of bytes into the message buffer at the current position.
public void write(byte b[],
int off,
int len)
Throws IOException.
Write a series of bytes into the message buffer at the current position. len bytes will be written, taken from offset off in the array b.
public void writeBoolean(boolean v)
Throws IOException.
Write a boolean into the message buffer at the current position.
public void writeByte(int v)
Throws IOException.
Write a byte into the message buffer at the current position.
public void writeBytes(String s)
Throws IOException.
Writes out the string to the message buffer as a sequence of bytes. Each character in the string is written out in sequence by discarding its high eight bits.
public void writeChar(int v)
Throws IOException.
Write a Unicode character into the message buffer at the current position.
public void writeChars(String s)
Throws IOException.
Write a string as a sequence of Unicode characters into the message buffer at the current position.
public void writeDecimal2(short v)
Throws IOException.
Write a 2-byte packed decimal format number into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_DECIMAL_NORMAL writes a big-endian packed decimal, a value of MQC.MQENC_DECIMAL_REVERSED writes a little-endian packed decimal.
Parameters
public void writeDecimal4(int v)
Throws IOException.
Write a 4-byte packed decimal format number into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_DECIMAL_NORMAL writes a big-endian packed decimal, a value of MQC.MQENC_DECIMAL_REVERSED writes a little-endian packed decimal.
Parameters
public void writeDecimal8(long v)
Throws IOException.
Write an 8-byte packed decimal format number into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_DECIMAL_NORMAL writes a big-endian packed decimal, a value of MQC.MQENC_DECIMAL_REVERSED writes a little-endian packed decimal.
Parameters:
public void writeDouble(double v)
Throws IOException
Write a double into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
Values of MQC.MQENC_FLOAT_IEEE_NORMAL and MQC.MQENC_FLOAT_IEEE_REVERSED write IEEE standard floats in Big-endian and Little-endian formats respectively.
A value of MQC.MQENC_FLOAT_S390 writes a System/390 format floating point number. Note that the range of IEEE doubles is greater than the range of S/390(R) double precision floating point numbers, and so very large numbers cannot be converted.
public void writeFloat(float v)
Throws IOException.
Write a float into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
Values of MQC.MQENC_FLOAT_IEEE_NORMAL and MQC.MQENC_FLOAT_IEEE_REVERSED write IEEE standard floats in big-endian and little-endian formats respectively.
A value of MQC.MQENC_FLOAT_S390 will write a System/390 format floating point number.
public void writeInt(int v)
Throws IOException.
Write an integer into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_INTEGER_NORMAL writes a big-endian integer, a value of MQC.MQENC_INTEGER_REVERSED writes a little-endian integer.
public void writeInt2(int v)
Throws IOException.
Synonym for writeShort(), provided for cross-language WebSphere MQ API compatibility.
public void writeInt4(int v)
Throws IOException.
Synonym for writeInt(), provided for cross-language WebSphere MQ API compatibility.
public void writeInt8(long v)
Throws IOException.
Synonym for writeLong(), provided for cross-language WebSphere MQ API compatibility.
public void writeLong(long v)
Throws IOException.
Write a long into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_INTEGER_NORMAL writes a big-endian long, a value of MQC.MQENC_INTEGER_REVERSED writes a little-endian long.
public void writeObject(Object obj)
Throws IOException.
Write the specified object to the message buffer. The class of the object, the signature of the class, and the values of the non-transient and non-static fields of the class and all its supertypes are all written.
public void writeShort(int v)
Throws IOException.
Write a short into the message buffer at the current position. The value of the encoding member variable determines the behavior of this method.
A value of MQC.MQENC_INTEGER_NORMAL writes a big-endian short, a value of MQC.MQENC_INTEGER_REVERSED writes a little-endian short.
public void writeString(String str)
Throws IOException.
Write a string into the message buffer at the current position, converting it to the codeset identified by the characterSet member variable.
public void writeUTF(String str)
Throws IOException.
Write a UTF string, prefixed by a 2-byte length field, into the message buffer at the current position.