MQeFields
MQeFields is a container data structure widely used in WebSphere MQ Everyplace. You can put
various types of data into the container. It is particularly useful for representing
data that needs to be transported, such as messages. The following code creates
an MQeFields structure:
- Java code
-
/* create an MQeFields object */
MQeFields fields = new MQeFields( );
- C code
-
MQeFieldsHndl hFields;
rc = mqeFields_new(&exceptBlock, &hFields);
MQeFields contains a collection of orderless fields. Each field consists
of a triplet of entry name, entry value, and entry value type. MQeFields forms the basis of all WebSphere MQ Everyplace messages.
Use the entity name to retrieve and update values. It is good practice
to keep names short, because the names are included with the data when the MQeFields item is transmitted.
The name must:
- Be at least 1 character long
- Conform to the ASCII character set (characters with values 20 < value < 128)
- Exclude any of the characters { } [ ] # ( ) : ; , ' " =
- Be unique within MQeFields
The following example shows how to store values in an MQeFields item:
- Java code
-
/* Store integer values into a fields object */
fields.putInt( "Int1", 1234 );
fields.putInt( "Int2", 5678 );
fields.putInt( "Int3", 0 );
- C code
-
MQeStringHndl hFieldName;
rc = mqeString_newChar8(&errStruct, &hFieldName, "A Field Name");
rc = mqeFields_putInt32(hNewFields,&errStruct,hFieldName,1234);
The following example shows how to retrieve values from an MQeFields item:
- Java code
-
/* Retrieve an integer value from a fields object */
int Int2 = fields.getInt( "Int2" );
- C code
-
MQEINT32 value;
rc = mqeFields_getInt32(hNewFields, &errStruct, &value, hFieldName);
WebSphere MQ Everyplace provides methods for storing and retrieving the
following data types:
- A fixed length array is handled using the putArrayOftype and getArrayOftype methods. type can be Byte, Short,
Int, Long, Float, or Double.
- The ability to store variable length arrays is possible, but has been
deprecated in this release. You can access these arrays using the Java puttypeArray and gettypeArray calls or the C puttypes calls. Refer to the WebSphere MQ Everyplace Java Programming Reference and WebSphere MQ Everyplace C Programming Reference for
more information.
- The Java codebase has a slightly special form of operations for Float
and Double types. This provides compatability with the MicroEdition. Floats
are put using an Int representation and Doubles are put using a Long representation.
Use the Float.floatToIntBits() and Double.doubleToLongBits() to perform the conversion. However, this is not required on the C API.
An MQeFields item may be
embedded within another MQeFields item by using
the putFields and getFields methods.
The contents of an MQeFields item
can be dumped in one of the following forms:
- binary
- Binary form is normally used to send an MQeFields or MQeMsgObject object through the network.
The dump method converts the data to binary.
This method returns a binary byte array containing an encoded form of the
contents of the item.
Note:
This is not Java serialization.
When a fixed length array is dumped and the
array does not contain any elements (its length is zero), its value is restored
as null.
- encoded string (Java only)
- The string form uses the dumpToString method of
the MQeFields item. It requires two parameters,
a template and a title. The template is a pattern string showing how the MQeFields item data should be translated, as shown
in the following example:
"(#0)#1=#2\r\n"
where
- #0
- is the data type (ascii or short, for example)
- #1
- is the field name
- #2
- is the string representation of the value
Any other characters are copied unchanged to the output string. The method successfully
dumps embedded MQeFields objects to a string,
but due to restrictions, the embedded MQeFields data
may not be restored using the restoreFromString method.