MQeFields API

Primitive

The MQeFields object is a container of zero or more fields. A field is identified by its field name, a null terminated string, a data type, and field data.

General constraint

With WebSphere MQ Everyplace Version 2.0 on a PalmOS device, the maximum number of MQeFields object handles is limited to 13, and the maximum MQeFields object (message object) size is 12 KB.

Array APIs

Two sets of APIs are defined to encode the MQeFields arrays. One set of APIs starts with MQeFieldsArrayOf* and the other starts with MQeFields*Array. These two sets of APIs look alike, but the underlying encoding scheme for the elements of the array is different.

MQeFieldsArrayOf*

These APIs treat the entire array as a single block of data, and a single field is used to hold this block. Once this block of data is included in the MQeFieldsArrayOf* APIs, the application program cannot delete or append to the individual elements in the array. These APIs operate on primitives data types, and they are:

MQeFields*Array

This set of APIs encodes each element of the array as a separate field, plus an extra field that holds the array length. In other words, this encoding scheme treats the array as a vector. The benefit of this encoding is that it allows the programmer to modify the individual element and to dynamically adjust the array size.

The encoding for each element in the array to a field consists of the following parts:

Field name
This is created from the concatenation of the field name of the array; a separator character (which is a colon, ":"), and the index of the element. For example, if the field name of the array is foo, then the field name for the first, second, and the nth elements are foo:0, foo:1 and foo:n-1.

Field type
The same type as the array.

Field data
Individual element of the array.

The array length, (the number of elements), is encoded in a separate field and is accessible to the programmer using the MQeFieldsGetArrayLength and MQeFieldsPutArrayLength APIs.

This set of APIs includes the following:

Base APIs

Table 2 lists the core MQeFields APIs.

Table 2. MQeFields base API

API Description
MQeFieldsAlloc() Allocate a new MQeFields object and returns a handle to it.
MQeFieldsDelete() Delete an existing field in the MQeFields object.
MQeFieldsDump() Serialize the internal name/value pair fields into a byte array for storage or communication.
MQeFieldsDumpLength() Get the total number of bytes needed to hold the serialized fields in the MQeFields object.
MQeFieldsEquals() Compare two MQeFields object and determines if they are the same.
MQeFieldsFields() Return the number of fields in the MQeFields object.
MQeFieldsFree() Deallocate an MQeFields object and recovers its resources.
MQeFieldsGet() Given a field name, return the field.
MQeFieldsGetArray() Given a name, returns an array from fields generated by the name.
MQeFieldsGetByArrayOfFd() Get an array of fields.
MQeFieldsGetByIndex() Given an index, return the field at the index.
MQeFieldsGetByStruct() Given a data structure and its fields structure descriptor, populate the data structure with the fields.
MQeFieldsHide() Exclude a field from an MQeFields comparison API, MQeFieldsEquals()
MQeFieldsPut() Put a field into an MQeFields object.
MQeFieldsPutArray() Given a name, put an array as fields generated by the name.
MQeFieldsPutByArrayOfFd() Given an array of field descriptors and associated field data, put them into the fields.
MQeFieldsPutByStruct() Given a data structure and its fields structure descriptor, create the fields.
MQeFieldsRead() Read from a field as an output stream.
MQeFieldsRestore() Resolve a byte array into name/value pair fields and store them in an MQeFields object.
MQeFieldsType() Extract the object type of an MQeFields object.
MQeFieldsWrite() Write to a field as an input stream.

MQeFields macros and helper APIs

The APIs and macros listed in Table 3 are supplied for compatibility with the Java API. These APIs are built on top of the APIs listed in Table 2.

Table 3. MQeFields macros and helper APIs

API Description
MQeFieldsContains() Determine if the MQeFields object contains a specific field.
MQeFieldsCopy() Copy one or all fields from one MQeFields object to another.
MQeFieldsDataLength() Determine the size of the data.
MQeFieldsDataType() Determine the data type of a field.
MQeFieldsGetArrayLength() Extract the length of an array.
MQeFieldsGetArrayOfByte() Extract an array of byte from an MQeFields object.
MQeFieldsGetArrayOfDouble() Extract an array of doubles (MQEDOUBLE) from an MQeFields object.
MQeFieldsGetArrayOfFloat() Extract an array of floats (MQEFLOAT) from an MQeFields object.
MQeFieldsGetArrayOfInt() Extract an array of 32 bit integers (MQEINT32) from an MQeFields object.
MQeFieldsGetArrayOfLong() Extract an array of 64 bit integers (MQEINT64) from an MQeFields object.
MQeFieldsGetArrayOfShort() Extract an array of 16 bit integers (MQEINT16) from an MQeFields object.
MQeFieldsGetAscii() Extract the data from an MQeFields object as an ASCII string.
MQeFieldsGetAsciiArray() Extract the data from an MQeFields object as an array of ASCII strings.
MQeFieldsGetBoolean() Extract the data from an MQeFields object as a boolean value.
MQeFieldsGetByte() Extract data from an MQeFields object as a byte (MQEBYTE).
MQeFieldsGetByteArray() Extract data from an MQeFields object as an array of byte arrays.
MQeFieldsGetDouble() Extract data from an MQeFields object as a double floating point (MQEDOUBLE).
MQeFieldsGetDoubleArray() Extract data from an MQeFields object as a double floating point array.
MQeFieldsGetFields() Extract a field object handle (MQEHFIELD) from an MQeFields object.
MQeFieldsGetFloat() Extract data from an MQeFields object as a float (MQEFLOAT).
MQeFieldsGetFloatArray() Extract data from an MQeFields object as a float (MQEFLOAT) array.
MQeFieldsGetInt() Extract data from an MQeFields object as an integer (MQEINT32).
MQeFieldsGetIntArray() Extract data from an MQeFields object as an integer (MQEINT32) array.
MQeFieldsGetObject() Extract the object type of an MQeFields object.
MQeFieldsGetLong() Extract data from an MQeFields object as a 64 bit (MQEINT64) integer.
MQeFieldsGetLongArray() Extract data from an MQeFields object as a 64 bit (MQEINT64) integer array.
MQeFieldsGetShort() Extract data from an MQeFields object as a 16 bit (MQEINT16) short.
MQeFieldsGetShortArray() Extract data from an MQeFields object as a 16 bit (MQEINT16) short array.
MQeFieldsGetUnicode() Extract data from an MQeFields object as a Unicode string.
MQeFieldsGetUnicodeArray() Extract data from an MQeFields object as a Unicode array.
MQeFieldsPutArrayLength() Put an array length.
MQeFieldsPutArrayOfByte() Put an array of byte (MQEBYTE) into an MQeFields object.
MQeFieldsPutArrayOfDouble() Put an array of double (MQEDOUBLE) into an MQeFields object.
MQeFieldsPutArrayOfFloat() Put an array of float (MQEFLOAT) into an MQeFields object.
MQeFieldsPutArrayOfInt() Put an array of 32 bit (MQEINT32) integer into an MQeFields object.
MQeFieldsPutArrayOfLong() Put an array of 64 bit (MQEINT64) integer into an MQeFields object.
MQeFieldsPutArrayOfShort() Put an array of 16 bit (MQEINT16) integer into an MQeFields object.
MQeFieldsPutAscii() Put an ascii string into an MQeFields object.
MQeFieldsPutAsciiArray() Put an array of ascii strings into an MQeFields object.
MQeFieldsPutBoolean() Put a boolean value into an MQeFields object.
MQeFieldsPutByte() Put a byte (MQEBYTE) value into an MQeFields object.
MQeFieldsPutByteArray() Put an array of byte (MQEBYTE) arrays into an MQeFields object.
MQeFieldsPutDouble() Put a double (MQEDOUBLE) into an MQeFields object.
MQeFieldsPutDoubleArray() Put an array of doubles (MQEDOUBLE) into an MQeFields object.
MQeFieldsPutFields() Put a field object handle into an MQeFields object.
MQeFieldsPutFloat() Put a float (MQEFLOAT) into an MQeFields object.
MQeFieldsPutFloatArray() Put an array of floats (MQEFLOAT) into an MQeFields object.
MQeFieldsPutInt() Put a 32 bit (MQEINT32) integer into an MQeFields object.
MQeFieldsPutIntArray() Put an array of 32 bit (MQEINT32) integers into an MQeFields object.
MQeFieldsPutLong() Put a 64 bit (MQEINT64) integer into an MQeFields object.
MQeFieldsPutLongArray() Put an array of 64 bit (MQEINT64) integers into an MQeFields object.
MQeFieldsPutShort() Put a 16 bit (MQEINT16) short integer into an MQeFields object.
MQeFieldsPutShortArray() Put an array of 16 bit (MQEINT16) short integers into an MQeFields object.
MQeFieldsPutUnicode() Put an Unicode string into an MQeFields object
MQeFieldsPutUnicodeArray() Put an array of Unicode strings into an MQeFields object.

Data type definitions

The data types shown in Table 4 are used in the definitions of the APIs.

Table 4. MQeFields data type definitions

API Description
MQECHAR A signed 8-bit integer.
MQETCHAR A platform dependent character.
MQEBYTE An unsigned 8-bit integer.
MQEINT16 A two-byte integer that is aligned on even-byte boundary.
MQEINT32 A four-byte integer that is aligned on even-byte boundary.
MQEINT64 An eight-byte integer that is aligned on even-byte boundary.
MQEFLOAT A four-byte floating point that is aligned on even-byte boundary.
MQEDOUBLE An eight-byte floating point that is aligned on quad-byte boundary.
MQECHAR * A null terminated ASCII character array of MQECHAR.
MQETCHAR * A null terminated Unicode character array of MQETCHAR.

MQeField data structure

The field descriptor data structure contains information about a field in the MQeFields object. It is used as an input and an output parameter with MQeFieldsGetByArrayOfFd and as an output parameter with MQeFieldsGetByIndex.

  MQEFIELD {
  MQEBYTE  fd_datatype;           /* Field data type */
  MQEBYTE  __pad;              /* Unused padding byte */
  MQEINT16  fd_namelen;            /* Field name */
  MQECHAR * fd_name;             /* Pointer to the field name */
  MQEBYTE * fd_data;             /* Pointer to the field data */
  MQEINT32  fd_datalen;            /* Number of datatype elements in */ 
                        /* the field data */
  MQEBYTE * fd_base;             /* Base pointer (platform specific) */
};

MQECHAR * fd_name
A pointer to the null terminated string name of the field. Application programs should use the following guidelines for field names:

MQEINT32 fd_namelen
The length of the fd_name. The input value specifies the size (in MQECHAR) of the fd_name buffer for operations that retrieve the name of a field. The output value specifies the size (in MQECHAR) of the fd_name of the field, for operations that retrieve the name of a field. These sizes do not include a terminating NULL.

MQEBYTE fd_type
The data type of the field data.

MQEBYTE * fd_data
A pointer to the field data.

MQEINT32 fd_datalen
The number of data elements (not bytes) in fd_data . The input values of fd_datalen and fd_datatype specify the size of the buffer provided by fd_data (when not NULL). The output value specifies the total number of elements for the field.

MQEBYTE * fd_base
The platform specific base pointer for data, should be NULL unless specifically being used.

MQeField structure descriptor

The MQeField structure descriptor holds information about a field to be added to or retrieved from an MQeFields object using the MQeFieldsPutByStruct and MQeFieldsGetByStruct APIs.

typedef struct MQeFieldStructDescriptor_st {
  PMQECHAR  sd_name;    /* Pointer to the field name */
  MQEINT32  sd_namelen;   /* Length of field name */
  MQEBYTE  sd_datatype;  /* Type of field */
  MQEBYTE  sd_flags;    /* flags describing field layout in struct */
  MQEINT32  sd_dataoff;   /* data offset in struct */
  MQEINT32  sd_datalen;   /* (offset of) data length for field */
} MQEFIELDDESC;

PMQECHAR sd_name
A pointer to the null terminated string name of the field. Application programs should use the following guidelines for field names:

MQEINT32 sd_namelen
The length of the sd_name.

MQEBYTE sd_datatype
The data type of the field data.

MQEBYTE * sd_flags
Flags that describe the type of data to put or get. See MQeField Structure Descriptor Flags

MQEINT32 sd_dataoff
The offset of the element to get or put.

MQEBYTE * sd_datalen
The length of the element to get or put.

MQeFields structure descriptor flags

The field structure descriptor sd_flags field can be initialized with flags that define the operation of the MQeFieldsPutByStruct and MQeFieldsGetByStruct APIs.

Name Value Action
MQSTRUCT_LEN 0x1 struct offset sd_datalen is a pointer to length, not number of elements
MQSTRUCT_DATA 0x2 struct offset sd_dataoff is a pointer to data, not start of data block
MQSTRUCT_NODATA 0x4 Get operations only extract the length of the field's data. Storage for the data is managed separately. Put operations ignore descriptors with this bit set.

Field data types

Each field in the MQeFields object is tagged with one of the data types defined below. The size of a single element of the data type is specified below.


Type Value Data Representation
MQE_TYPE_UNTYPED 0xC0 1 byte (8 bits)
MQE_TYPE_ASCII 0xC1 1 byte (8 bits)
MQE_TYPE_UNICODE 0xC2 2 byte (16 bits)
MQE_TYPE_BOOLEAN 0xC3 1 byte (8 bits)
MQE_TYPE_BYTE 0xC4 1 byte (8 bits)
MQE_TYPE_SHORT 0xC5 2 byte (16 bits)
MQE_TYPE_INT 0xC6 4 byte (32 bits)
MQE_TYPE_LONG 0xC7 4 byte (32 bits)
MQE_TYPE_FLOAT 0xC8 4 byte (32 bits)
MQE_TYPE_DOUBLE 0xC9 8 byte (64 bit)
MQE_TYPE_ARRAYELEMENTS 0xCA 4 byte (32 bits)
MQE_TYPE_FIELDS 0xCB 4 byte (a handle) (32 bits)

Base pointers

Many of the base APIs include a platform specific base pointer that has a platform specific interpretation. For platforms without any interpretation, it should be set to NULL.

Platform interpretations

The following platforms have an interpretation for the base pointer.

PalmOS
Under PalmOS, the base pointer is interpreted as the base of a locked database record when the corresponding destination buffer is a location within the locked record. If the destination buffer is regular memory, the base pointer should be NULL.

MQeFieldsAlloc

Description
Allocates a new MQeFields object and returns a handle to it. The handle represents an MQeFields object. It must be specified on all subsequent calls from the application that access the MQeFields object. This handle ceases to be valid when the MQeFieldsFree call is issued, or when the unit of processing that defines the scope of the handle terminates.

Syntax
#include <hmq.h>
MQEHFIELDS MQeFieldsAlloc( MQEHSESS hSess, MQECHAR * Type, 
              MQEINT32 * pCompCode, MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQECHAR * Type - input

"" or NULL
An untyped MQeFields object that is used for restore, MQeFieldsRestore.

com.ibm.mqe.MQeFields
The base MQeFields object type

com.ibm.mqe.MQeMsgObject
A field object with two additional MQeFields, a 64 bit unique identifier, and the string name of the origin queue manager.

com.ibm.mqe.MQeAdminMsg

com.ibm.mqe.MQeQueueAdminMsg

com.ibm.mqe.MQeQueueManagerAdminMsg

com.ibm.mqe.MQeFragmentor

A non-recognized type string defaults to the base field object type with its type string set to the input type string.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEHFIELDS hFlds
The handle to an MQeFields object. If any error occurs during the allocation, then an MQEHANDLE_NULL is returned.

Implementation
On PalmOS 3.0 the underlying storage allocation element comes from a record in the database.

Example
#include <hmq.h>
static static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
 
hSess = MQeInitialize("MyAppsName", &compcode, &reason);
hFlds = MQeFieldsAlloc( hSess, FieldsType, &compcode, &reason);

See Also

MQeFieldsDelete

Description
Delete a field in the MQeFields object.

Given a field name, remove its associated field from the MQeFields object.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsDelete( MQEHSESS hSess,
										MQEHFIELDS hFlds, 
										MQECHAR * pName, 
            						MQEINT32 * pCompCode, 
										MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
Handle to an MQeFields object.

MQECHAR * pName - input
Null terminated string name of the field. A null or a zero length string is not valid.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND

The field was not found in the MQeFields object.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
Returns '0' on success, or '-1' on failure.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
/*
 * Add some fields to the fields object... 
		and one of them is "XYZ"
 */
 ...
 
/*
 * Now delete field named "XYZ"
 */
rc = MQeFieldsDelete( hSess, hFlds, "XYZ", 
								&compcode, &reason);
 

See Also
MQeFieldsPut

MQeFieldsDump

Description
Serializes the encoded fields in an MQeFields object into a byte array.

This functions supports partial dumps. Between partial dumps, the programmer should not add or delete any field in the MQeFields object. If fields are added or deleted, inconsistencies may occur between the data that has already been copied out and the data that is waiting to be copied. This causes errors when the user tries to restore the MQeFields object from the byte array.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsDump( MQEHSESS hSess,
									MQEHFIELDS hFlds, 
									MQEINT32 srcOff, 
            					MQEBYTE pBuf[], 
									MQEINT32 BufLen, 
									MQEVOID *pBase, 
           					MQEINT32 * pCompCode, 
									MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
Handle to an MQeFields object.

MQEINT32 srcOff - input
The offset into internal byte array representation of the MQeFields object at which the dump should start

MQEBYTE pBuf[] - output
The buffer to hold the dumped bytes

MQEINT32 BufLen - input
The number of bytes to dump

MQEVOID *pbase - input
The base pointer for the output buffer pBuf

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of bytes copied into the buffer.
  • On failure, returns '-1'.

Implementation
The byte order in which the primitive data types are dumped is big-endian.

Example
/**
   This example shows how to dump the 
		fields object into an array of fix-size buffers.
 */
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
 
static   MQECHAR * textBuf  = 
						"The Owl and the Pussy Cat went to sea.";
static   MQEBYTE   byteBuf[] = 
						{ 0xAB, 0xCD, 0x12, 0x44};
 
#define  MAX_CHUNK_SIZE 16
MQEHSESS   hSess;
MQEHFIELDS hFlds;
MQEINT32   compcode;
MQEINT32   reason;
MQEINT32   int32Val;
MQEINT32   i, offset;
MQEINT32   chunk, nchunks;
MQEBYTE ** buf_array;
MQEINT32   nbytes;
MQEINT32   rc;
 
hSess   = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds   = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
/* Put some fields into the fields object */
int32Val = 0x12345678;
rc = MQeFieldsPut( hSess, hFlds, "x", 
							MQE_TYPE_INT, 
							&int32Val, 1, 
							&compcode, 
							&reason); 
rc = MQeFieldsPut( hSess, hFlds, "nm", 
							MQE_TYPE_ASCII, 
							textBuf, 
							strlen(textBuf), 
							&compcode, 
							&reason); 
rc = MQeFieldsPut( hSess, hFlds, "b" , 
							MQE_TYPE_BYTE, 
							byteBuf, 4, 
							&compcode, 
							&reason); 
 
nbytes  = MQeFieldsDumpLength( hSess, hFlds, 
											&compcode, &reason);
 
offset  = 0;
i       = 0;
 
/*
 * Calc number of chunks needed 
		to hold the dump byte array
 */
nchunks = nbytes/MAX_CHUNK_SIZE;   
chunk = nbytes%MAX_CHUNK_SIZE;
 
/*
 * Allocate the buf array.
 */
 
while (nchunks != 0)
{
   buf_array[i] = (MQEBYTE*) malloc(MAX_CHUNK_SIZE);
   rc = MQeFieldsDump( hSess, hFlds, 
								offset, 
								&buf_array;[i][0], 
								MAX_CHUNK_SIZE, NULL,
								&compcode, 
								&reason);
   offset  += MAX_CHUNK_SIZE;
   nchunks--;
   i++;
}
 
buf_array[i] = (MQEBYTE*) malloc(chunk);
rc = MQeFieldsDump( hSess, hFlds, 
							offset, 
							&buf_array;[i][0], 
							chunk, 
							NULL, 
							&compcode, 
							&reason);
 
/* Do something with the buf_array[], like store it into a file. */

See Also

MQeFieldsDumpLength

Description
Returns the total number of bytes that are used to hold the fields in this MQeFields object. The application programmer can use this number to allocate a memory chunk to hold all the fields.This API is used in conjunction with MQeFieldsDump().

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsDumpLength( MQEHSESS hSess,
											MQEHFIELDS hFlds, 
               						MQEINT32 * pCompCode, 
											MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS Flds - input
The handle to an MQeFields object.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values::

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
  • On success, returns the number of bytes used to hold the field object data.
  • On failure, returns '-1'.

Example
See example in MQeFieldsDump.

See Also

MQeFieldsEquals

Description
Compares two typed MQeFields objects and determine if they both have the same fields.

This API determines if two MQeFields objects are the same by comparing every visible field in the first object with the corresponding visible field in the second object. If the second object does not have a corresponding visible field, or its value is different, then the two MQeFields objects are considered unequal, and the result is '0'. If the two MQeFields objects are not unequal, then the result depends on whether the second MQeFields object contains exactly the same number of visible fields, in which case the result is '1', or more visible fields, in which case the result is '2'. This comparison does not depend on the order in which the fields are inserted or stored in each of the MQeFields objects; all that matters is that both MQeFields objects contain the same fields. The types of the MQeFields objects do not affect the result of the comparison, however both MQeFields objects must be typed (they may not be allocated with type MQE_OBJECT_TYPE_MQE_FIELDS_UNTYPE). The test recurses into nested fields.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsEquals( MQEHSESS hSess, 
									MQEHFIELDS hFlds1, 
									MQEHFIELDS hFlds2, 
             					MQEINT32 * pCompCode, 
									MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds1 - input
The first MQeFields object handle.

MQEHFIELDS hFlds2 - input
The second MQeFields object handle.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds1, hFlds2;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", &compcode, &reason );
hFlds1 = MQeFieldsAlloc( hSess, FieldsType, &compcode, &reason);
hFlds2 = MQeFieldsAlloc( hSess, FieldsType, &compcode, &reason);
 
/*
 * Add some fields to the fields objects... and one of them is "XYZ"
 */
 ...
 
/*
 * Now test their equivalence
 */
rc = MQeFieldsEquals( hSess, hFlds1, hFlds2, &compcode, &reason);
 

See Also MQeFieldsHide.

MQeFieldsFields

Description
Returns the total number of fields in an MQeFields object.

From this number, the application can use MQeFieldsGetByIndex to iterate through the indices and retrieve all the fields in the MQeFields object.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsFields( MQEHSESS hSess, 
									MQEHFIELDS hFlds, 
             					MQEINT32 * pCompCode, 
									MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
On success, returns the number of fields.

Example
#include <hmq.h>
static  MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
static  MQECHAR * textBuf  = 
						"The Owl and the Pussy Cat went to sea.";
static  MQEBYTE   byteBuf[] 
						= { 0xAB, 0xCD, 0x12, 0x44 };
 
MQEHSESS   hSess;
MQEHFIELDS hFlds;
MQEINT32   compcode;
MQEINT32   reason;
MQEINT32   int32Val;
MQEINT32   nFlds;
MQEINT32   rc,i;
MQEFIELD   fd;
 
hSess   = MQeInitialize("MyAppsName", &compcode, &reason);
hFlds   = MQeFieldsAlloc( hSess, FieldsType, &compcode, &reason);
 
int32Val = 0x12345678;
rc = MQeFieldsPut( hSess, hFlds, "x", 
							MQE_TYPE_INT,  
							&int32Val;, 1, 
							&compcode, 
							&reason); 
rc = MQeFieldsPut( hSess, hFlds, "nm", 
							MQE_TYPE_ASCII, 
							textBuf, 
							strlen(textBuf), 
							&compcode, 
							&reason); 
rc = MQeFieldsPut( hSess, hFlds, "b", 
							MQE_TYPE_BYTE,  
							byteBuf, 4, 
							&compcode, 
							&reason); 
 
nFlds = MQeFieldsFields( hSess, hFlds, 
									&compcode, 
									&reason);
/* nFlds is 4 
	(3 added above + 1 field object identifier field) */
/* Ignore the first field 
		(field object identifier) - start at 1 */ 
 
for (i=1; i<nFlds; i++) {
 
   memset( &fd, 0, sizeof(fd));
   
   /* Get each field by index */
   rc = MQeFieldsGetByIndex( hSess, hFlds, i, 
										&fd, 1, 
										&compcode, 
										&reason);
   fd.fd_name = (MQECHAR *) malloc(fd.fd_namelen+1);
   fd.fd_data = (MQEBYTE *) 
						malloc(fd.fd_datalen * 
						MQE_SIZEOF(fd.fd_datatype));
 
   rc = MQeFieldsGetByIndex( hSess, hFlds, i, 
										&fd, 1, 
										&compcode, 
										&reason);
   fd.fd_name[fd.fd_namelen] = '\0';
   
   free(fd.fd_name);
   free(fd.fd_data);

See Also
MQeFieldsGetByIndex

MQeFieldsFree

Description
Deallocates an MQeFields object and recovers its resources.

Syntax
#include <hmq.h>
MQEVOID MQeFieldsFree( MQEHSESS hSess, 
								MQEHFIELDS hFlds, 
            				MQEINT32 * pCompCode, 
								MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEVOID

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
 
hSess = MQeInitialize("MyAppsName", &compcode, &reason);
hFlds = MQeFieldsAlloc( hSess, FieldsType, &compcode, &reason);
MQeFieldsFree( hSess, hFlds, &compcode, &reason);

See Also
MQeFieldsAlloc

MQeFieldsGet

Description
Given a field name, retrieves the data type, length of field data and field data. This API is used to retrieve information about a field with a given name. The datatype is returned in the pointer. MQeFieldsGetByArrayOfFd should be used to get a field with a specific datatype.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsGet( MQEHSESS hSess, MQEHFIELDS hFlds, 
            MQECHAR * pName, MQEBYTE * pDataType, 
            MQEVOID * pData, MQEINT32 nElements, MQEVOID *pBase, 
            MQEINT32 * pCompCode, MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQECHAR * pName - input
The null terminated string name of the field.

MQEBYTE * pDataType - input and output
The input value is used with nElements to specify the size of the data buffer. The output value is the type of the field.

MQEVOID * pData - input and output
The destination buffer to receive the copy of the field data. If this parameter is a NULL, then the number of the elements of datatype is returned.

If data type is MQE_TYPE_FIELDS, then a single field object handle MQEHFIELDS is returned.

If data type is MQE_TYPE_UNTYPED, then it is treated as an array of bytes.

MQEINT32 nElements - input
Specifies the size of the pData buffer in the number of elements of the input value of *pDataType. If pDataType is NULL, the default is MQE_TYPE_BYTE. If pData is NULL, then this parameter is ignored.

MQEVOID * pBase - input
A platform specific base pointer.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output

Return Value

MQEINT32
  • On success, returns the number of elements.
  • On failure, returns '-1'.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEBYTE  datatype;
MQEINT32  n;
MQEBYTE * pdata;
MQEBYTE * buf;
MQEINT32  rc;
 
hSess = MQeInitialize("MyAppsName", &compcode, &reason);
hFlds = MQeFieldsAlloc( hSess, FieldsType, &compcode, &reason);
 
/*
 * Add some fields to the fields object... and one of them is "XYZ"
 */
 ...
 
/* Get the field data length */
n = MQeFieldsGet( hSess, hFlds, "XYZ", &datatype, NULL, 0, NULL, 
         &compcode, &reason);
 
/* Verfify that datatype is correct. */
 
/* Get some space to put the data */
buf = (MQEBYTE *)calloc(n, MQE_SIZEOF(datatype));
 
/* Get the field data */
rc = MQeFieldsGet( hSess, hFlds, "XYZ", &datatype, &buf, n, NULL,
         &compcode, &reason);
 

See Also
MQeFieldsPut

MQeFieldsGetArray

Description
Given a field name, retrieves the data type and a portion of an encoded array into a buffer. The output data type is the data type of the initial source array element. All remaining source array elements must be of the same type for this call to complete successfully. Returns the number of elements on success.

If an error occurs, returns the source count of the offending element or '-1'.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsGetArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
              MQECHAR * pName, MQEBYTE * pDataType, 
              MQEINT32 sOff, MQEVOID * pDstBuf, MQEINT32 dstLen, 
              MQEVOID *pBase, MQEINT32 * pCompCode, 
              MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the array. A null or a zero length string is invalid. Field names for each array element are constructed as described in MQeFields*Array.

MQEBYTE * pDataType - input and output
The data type for the buffer. The input value is used with dstLen to specify the size of the data buffer. The output value is the type of the initial source array element. If this parameter is NULL, MQE_TYPE_BYTE is used as the input value.

MQEINT32 sOff - input
The index of the initial source array element. the data to be copied.

MQEVOID * pDstBuf - input
The destination buffer to receive the array data. The initial source array element is copied to pDstBuf[0] (not pDstBuf[sOff] ). The size of the buffer is specified by the combination of dstLen and the input value of *pDataType. If this parameter is NULL, then no data is copied.

MQEINT32 dstLen - input
Specifies the size of the pData buffer in terms of the number of elements of the input value of *pDataType. If this parameter is less than or equal to 0, no data is copied.

MQEVOID * pBase - input
A platform specific base pointer.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values::

MQE_EXCEPT_NOT_FOUND

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

MQE_EXCEPT_TYPE
The data type of an array element does not match the type of the initial source array element or the number of array elements encoded in hFlds is invalid.

MQE_EXCEPT_DATA
The field containing the size of the array contains an invalid value.

MQE_EXCEPT_INVALID_ARGUMENT
sOff is less than '0' or greater than or equal to the number of elements in the source array.

Return Value

MQEINT32
  • On success, returns the number of elements in the source array.
  • On failure, returns a count of the number of elements processed in the source array including the failing element.
  • If an error occurs prior to any elements being processed, '-1' is returned.

Example
#include <hmq.h>;
static     MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
static     MQEINT32 intBuf[4]  = 
				{ 0x12345678, 0xDEADBEEF, 0xC0D1F1ED, 0x1DEC0DED};
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
MQEBYTE    datatype;
MQEINT32   n;
MQEINT32   rc;
MQEINT32 * buf;
#define NULL 0
 
hSess = MQeInitialize("MyAppsName", 
								&compcode, 
								&reason);
hFlds = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, 
									&reason);
 
/*
* Add some fields to the fields object... 
		and one of them is the array "XYZ"
*/
MQeFieldsPutArray( hSess, hFlds, "XYZ", 
							MQE_TYPE_INT, 
							intBuf, 4, 
							&compcode, 
							&reason); 
 
/* Get the field data length and datatype */
n = MQeFieldsGetArray( hSess, hFlds, "XYZ", 
							&datatype, 0, 
								NULL, 0, 
								NULL, 
							&compcode, 
							&reason);
 
/* Get some space to put the data */
buf = malloc( n * MQE_SIZEOF(datatype));
 
/* Get the field data */
rc = MQeFieldsGetArray( hSess, hFlds, "XYZ", 
								&datatype, 0, 
								buf, n, 
								NULL, 
								&compcode, 
								&reason);

See Also
MQeFieldsPut

MQeFieldsGetByArrayOfFd

Description
Get fields data and data lengths from an MQeFields object for the names specified in the array of field descriptors. For each descriptor, both the field name and datatype must match to be successful.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsGetByArrayOfFd( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQEFIELD pFds[], MQEINT32 nFds, 
                 MQEINT32 * pCompCode, MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

(MQEFIELD *) pFds - input/output
An array of MQeField_st data structures. For each descriptor, the size destination buffer is determined by the input values of fd_datatype and fd_datalen. For successful descriptors, the output value of fd_datalen is set to the number of elements (not bytes) of the specified field.

The length of a field name is determined from the fd_name field, the fd_namelen field is ignored.

MQEINT32 nFds - input
Number of fields in the pFds array.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR. The error for the corresponding index to fail.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

MQE_EXCEPT_TYPE
The field for a descriptor did not match the datatype.

MQE_EXCEPT_NOT_FOUND
No field was found for a descriptor.

Return Value

MQEINT32
  • On success, returns the number of descriptors successfully updated .
  • On failure, returns a count of the number of descriptors processed, including the failing descriptor.
  • If an error occurs prior to any descriptors being processed, '-1' is returned.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
static const MQECHAR textVal[] = 
							"The Owl and the Pussy Cat went to sea.";
 
/* template for fields */
static const MQEFIELD PFDS[] = {
    {MQE_TYPE_BYTE, 0, 7, "fooByte", 
				(MQEBYTE *)0, 0, (MQEBYTE *)0},  
    {MQE_TYPE_SHORT, 0, 8, "fooShort", 
				(MQEBYTE *)0, 0, (MQEBYTE *)0},  
    {MQE_TYPE_LONG, 0, 7, "fooLong", 
				(MQEBYTE *)0, 0, (MQEBYTE *)0},  
    {MQE_TYPE_ASCII, 0, 7, "fooText", 
				(MQEBYTE *)0, 0, (MQEBYTE *)0}, 
    };
#define NFDS (sizeof(PFDS)/sizeof(PFDS[0]))
MQEHSESS  hSess;
MQEINT32  compcode;
MQEFIELD  Fds[NFDS];
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEBYTE  byteVal;
MQEINT16  int16Val;
MQEINT32  int32Val;
MQEBYTE  datatype;
MQEINT32  rc;
MQEINT32  nFlds,i;
 
hSess = MQeInitialize("MyAppsName", 
								&compcode, &reason);
hFlds = MQeFieldsAlloc( hSess, FieldsType, 
								&compcode, &reason);
 
 
/* Put some fields in the fields 
	object using MQeFieldsPutByArrayOfFd() */
 
byteVal = 0xAE;
int16Val = 0x9876;
int32Val = 0x12345678;
 
/* Copy template */
memcpy(Fds,PFDS,sizeof(Fds));
 
Fds[0].fd_data = 
Fds[0].fd_datalen = 1;
Fds[1].fd_data = 
Fds[1].fd_datalen = 1;
Fds[2].fd_data = 
Fds[2].fd_datalen = 1;
Fds[3].fd_data = [0];
Fds[3].fd_datalen = sizeof(textVal);
 
compcode = MQECC_OK, reason = 0;
MQFieldsPutByArrayOfFd( hSess, hFlds, 
									Fds, NFDS, 
									&compcode, 
									&reason);
 
/* Copy template */
memcpy(Fds,PFDS,sizeof(Fds));
 
/* Get data lengths */
rc = MQeFieldsGetByArrayOfFd( hSess, hFlds, 
											Fds, NFDS, 
											&compcode, 
											&reason);
 
/* Get space for each field data */
for( i=0; i<rc; i++) {
 int len = Fds[i].fd_datalen*
				MQE_SIZEOF(Fds[i].fd_datatype);
 if (len > 0) {
  Fds[i].fd_data = (MQEBYTE *) malloc(len);
 } 
}
 
/* Get all the fields defined in field descriptor array in one shot */
compcode = MQECC_OK, reason = 0;
MQFieldsGetByArrayOfFd( hSess, hFlds, 
									Fds, NFDS, 
									&compcode, 
									&reason);

See Also
MQeFieldsPutByArrayOfFd,

MQeFieldsGetByIndex

Description
Copies information about some fields in an MQeFields object into an array of descriptors. This call is used to discover information about the fields in an MQeFields object without providing the field names. This is useful if the contents of the MQeFields object are fully defined. If an MQeFields object has N fields indexed from 0 to N-1 , then MQeFieldsGetByIndex returns information about the nFlds starting at index startIndex. The indices of the individual fields are guaranteed to stay the same for successive calls to MQeFieldsGetByIndex only as long as there are no other intervening operations on the MQeFields object.

Index 0 is special, it is a field with an empty name (fd_namelen is '0') that contains the encoded type name (MQE_TYPE_ASCII) of the MQeFields object. It is provided primarily to support the debugging of communication problems with a peer WebSphere MQ Everyplace system. Programs that are trying to enumerate the fields in an MQeFields object would usually start with index 1. The number of fields returned by MQeFieldsFields includes this special field.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsGetByIndex( MQEHSESS hSess, MQEHFIELDS hFlds, 
               MQEINT32 startIndex, MQEFIELD pFds[],
               MQEINT32 nFlds, MQEINT32 * pCompCode, 
               MQEINT32 * pReason);

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQEINT32 startIndex - input
The starting index field to begin processing the descriptors.

(MQEFIELD) pFds - input and output
An array of fields descriptors data structures. The input values of each descriptor determines how much information is copied on output:

Name
Is copied into fd_name[0..fd_namelen] , if fd_name is not NULL.

Data
Is copied into the (byte) buffer fd_data[0..fd_datalen*MQE_SIZEOF(fd_datatype)] if fd_data is not NULL. An integral number of the field's data type elements are copied. The input values of fd_namelen , fd_datatype and fd_datalen are used, not the field's actual datatype and length values.

On output, each descriptor is modified to reflect the field's actual values:

fd_datatype
is set to the field's datatype.

fd_namelen
is set to the length of the field's name.

fd_datalen
is set to the number of elements in the field (of the field's datatype, not the input datatype).

MQEINT32 nFlds - input
The number of fields to copy, (the number of elements in pFds).

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_ARGUMENT
An index greater than the number of fields, startIndex<= 0 , nFlds<= 0, or pFlds is NULL.

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of descriptors successfully updated .
  • On failure, returns a count of the number of descriptors processed, including the failing descriptor.
  • If an error occurs prior to any descriptors being processed, '-1' is returned.

Example
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
   static  const MQECHAR * textVal  = 
					"The Owl and the Pussy Cat went to sea.";
   /* template for fields */
   static  const MQEFIELD PFDS[] = {
           {MQE_TYPE_BYTE, 0, 7, "fooByte", 
						(MQEBYTE *)0, 0, (MQEBYTE *)0},   
           {MQE_TYPE_SHORT, 0, 8, "fooShort", 
						(MQEBYTE *)0, 0, (MQEBYTE *)0},   
           {MQE_TYPE_LONG, 0, 7, "fooLong", 
						(MQEBYTE *)0, 0, (MQEBYTE *)0},   
           {MQE_TYPE_ASCII, 0, 7, "fooText", 
						(MQEBYTE *)0, 0, (MQEBYTE *)0},  
           };
   #define NFDS 4
   MQEHSESS   hSess;
   MQEINT32   compcode;
   MQEINT32   reason;
   MQEHFIELDS hFlds;
   MQEBYTE    byteVal;
   MQEINT16   int16Val;
   MQEINT32   int32Val;
   MQEFIELD   Fds[NFDS], fd;
   MQEINT32   rc, nFlds, i;
 
   hSess = MQeInitialize("MyAppsName", 
									&compcode, &reason);
   hFlds = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
   /* Put some fields in the fields object 
			using MQeFieldsPutByArrayOfFd() */
 
   byteVal  = 0xAE;
   int16Val = 0x9876;
   int32Val = 0x12345678;
 
   /* Copy template */
   memcpy(Fds,PFDS,sizeof(Fds));
 
   Fds[0].fd_data = &byteVal;
   Fds[0].fd_datalen = 1;
   Fds[1].fd_data = &int16Val;
   Fds[1].fd_datalen = 2;
   Fds[2].fd_data = &int32Val;
   Fds[2].fd_datalen = 4;
   Fds[3].fd_data = (void *) &textVal[0];
   Fds[3].fd_datalen = strlen(textVal);
 
   rc = MQeFieldsPutByArrayOfFd( hSess, hFlds, 
												Fds, NFDS, 
												&compcode, 
												&reason);
 
   /* Get the fields out by index*/
   nFlds     = MQeFieldsFields( hSess, hFlds, 
											&compcode, 
											&reason);
 
   /* Get the fields one by one 
		(without knowing the field names) */
   /* Start at 1 - ignore index 0 
		(field object identifier)   */
 
   for (i=1; i<nFlds; i++)
   {
 
      fd.fd_name = NULL;
      fd.fd_namelen = 0;
      fd.fd_datatype = MQE_TYPE_BYTE;
      fd.fd_data = NULL;
      fd.fd_datalen = 0;
      fd.fd_base = 0;
 
      /* Use get by index to get datatype, 
				namelen and datalen */
      MQeFieldsGetByIndex(hSess, hFlds, i, 
									&fd, 1, 
									&compcode, 
									&reason);
 
      /* Allocate space for the field name */
      fd.fd_name = malloc( fd.fd_namelen+1 ); 
 
      /* Allocate space for the data */
      fd.fd_data = 
				malloc( fd.fd_datalen * 
				MQE_SIZEOF(fd.fd_datatype)); 
 
      /* Get all the data and the name, 
			now we have allocated space */
 
      MQeFieldsGetByIndex(hSess, hFlds, i, 
									&fd, 1, 
									&compcode, 
									&reason);
 
      /* Null terminate the name */
      fd.fd_name[fd.fd_namelen] = '\0';
      
      free( fd.fd_data );
      free( fd.fd_name );
   }

See Also

MQeFieldsGetByStruct

Description
Copy one or more fields from an MQeFields object directly into a data structure.

Given a pointer to a user data structure and its corresponding struct descriptors, this API gets all the MQeFields data into the data structure. Processing stops as soon as a descriptor fails or when all descriptors are extracted. This API is similar to MQeFieldsGetByArrayOfFd, as a match is only successful if both the field name and data type match the input descriptor. It differs by constructing the data buffers for the various fields from a single pointer value, as appropriate when extracting fields into a data structure. The platform specific base pointer is not available with this call (treated as NULL).

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsGetByStruct( MQEHSESS hSess, MQEHFIELDS hFlds, 
                MQEVOID * pStruct, 
                (struct MQFieldStructDescriptor_st) pfsd[], 
                MQEINT32 nSds, MQEINT32 * 
                pCompCode, MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

PMQEVOID pStruct - output
A pointer to the target data structure.

(struct MQFieldStructDescriptor_st *) pfsd - input and output
A definition that defines the relation between the elements in the pStruct and the fields in the MQeFields object. On output, if the input value of the sd_flagsparameter has the MQSTRUCT_LEN bit set, then sd_datalen is updated to contain the number of elements in the field.

MQEINT32 nSds - input/output
The number of elements in the array pointed to by pfsd

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
One or more fields needed to populate the data structure may be missing .

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of descriptors successfully updated .
  • On failure, returns a count of the number of descriptors processed, including the failing descriptor.
  • If an error occurs prior to any descriptors being processed, '-1' is returned.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
struct myData_st
{
   MQEINT32 x;           /* simple variable */
   MQECHAR *name  ;      /* pointer to name buffer */
   MQEINT32 namelen;     /* length of name */
   MQEBYTE  buf[8];      /* fixed buffer in struct */
   MQEINT32 fieldlen;    /* length of a field, buffer not in struct */
};
 
MQEINT32 field[10];     
/* buffer whose length is in a structure */
 
/* A possible sample definition of MQEFIELDDESC for myData_st */
static MQEFIELDDESC myDataStruct_fd[] = {
 
   {"x", 1, MQE_TYPE_INT, 0, 0, 1},
 
   {"name", 4, MQE_TYPE_ASCII, MQSTRUCT_LEN|MQSTRUCT_DATA, 4, 64},
 
   {"buf",  3, MQE_TYPE_BYTE, 0, 12, 8},
 
   {"field",5, MQE_TYPE_INT, MQSTRUCT_LEN|MQSTRUCT_NODATA, 20, 0}
};
 
static  MQECHAR * textBuf  = 
			"The Owl and the Pussy Cat went to sea.";
static  MQEBYTE   byteBuf[] 
			= { 0xAB, 0xCD, 0x12, 0x44};
 
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
struct myData_st myData;
MQEINT32  int32Val;
MQEINT32  rc;
 
for (rc=0; rc<sizeof(field)/sizeof(field[0]); 
		rc++) field[rc]=rc;
 
hSess   = MQeInitialize("MyAppsName", 
									&compcode, 
									&reason);
hFlds   = MQeFieldsAlloc( hSess, 
										FieldsType, 
										&compcode, 
										&reason);
 
/* Put some fields into the fields object. */
int32Val = 0xABABBABA;
rc = MQeFieldsPut( hSess, hFlds, "x", 
							MQE_TYPE_INT, 
							&int32Val, 1, 
							&compcode, 
							&reason); 
 
rc = MQeFieldsPut( hSess, hFlds, 
							"name", 
							MQE_TYPE_ASCII, 
							textBuf, 
							strlen(textBuf), 
							&compcode, 
							&reason); 
 
rc = MQeFieldsPut( hSess, hFlds, "buf", 
							MQE_TYPE_BYTE, 
							byteBuf, 4, 
							&compcode, 
							&reason); 
 
rc = MQeFieldsPut( hSess, hFlds, 
							"field", 
							MQE_TYPE_INT, 
							field, 10, 
							&compcode, 
							&reason); 
 
/* Retrieve all the fields out at once and 
		populate the user data structure. */
 
rc = MQeFieldsGetByStruct( hSess, hFlds, 
										&myData, 
										myDataStruct_fd, 4, 
										&compcode, 
										&reason);

See Also
MQeFieldsPutByStruct

MQeFieldsHide

Description
Excludes this field from the field comparison API, MQeFieldsEquals. Each field has a hide bit (initially '0') associated with it. This API allows the application to set or clear the hide bit. The hide bit is considered part of the value of a field, it is cleared if a field with the same name is put into the MQeFields object. The value of the hide bit is exported when the MQeFields object is serialized with MQeFieldsDump, so hidden fields remain hidden when MQeFields objects are transported to a different WebSphere MQ Everyplace system.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsHide( MQEHSESS hSess, MQEHFIELDS hFlds, 
            MQECHAR * pName, MQEINT32 hide, 
            MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string name of the field. A null or a zero length string is invalid.

MQEINT32 hide - input

'0'
Clears field element's hide bit, rendering it eligible for comparison by MQeFieldsEquals.

nonzero
Sets field element's hide bit, rendering it ineligible for comparison by MQeFieldsEquals.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
The specified field is not present in the MQeFields object.

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
Returns '0' on success, or '-1' on failure.

Example
See example in MQeFieldsEquals.

See Also
MQeFieldsEquals.

MQeFieldsPut

Description
Puts a field into the MQeFields object.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsPut( MQEHSESS hSess, MQEHFIELDS hFlds, 
            MQECHAR * pName, MQEBYTE DataType, 
            MQEVOID * pData, MQEINT32 nElements, 
            MQEINT32 * pCompCode, MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string name of the field. A null or a zero length string is invalid.

MQEBYTE DataType - input
The data type of the field data. This parameter cannot be a null and its value must be one of the defined values. See Field data types.

MQEVOID * pData - input
The data buffer. If NULL, an internal buffer is allocated whose size is specified by the nElements parameter. You can then use MQeFieldsWrite to put data into this pre-allocated buffer. And this internal buffer is initialized to zeros for the data types,
  • MQE_TYPE_BYTE
  • MQE_TYPE_SHORT
  • MQE_TYPE_INT
  • MQE_TYPE_LONG
  • MQE_TYPE_ASCII
  • MQE_TYPE_UNICODE
  • MQE_TYPE_UNTYPED
  • MQE_TYPE_FLOAT
  • MQE_TYPE_DOUBLE

If DataType is MQE_TYPE_FIELDS, pData must not be null.

MQEINT32 nElements - input
The number of elements of type DataType in pData. This must be greater than '0'. If the DataType is MQE_TYPE_FIELDS, MQE_TYPE_ARRAY_ELEMENTS, or MQE_TYPE_BOOLEAN, nElements must '1'.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If MQECC_ERROR, *pReason could be:

MQE_EXCEPT_INVALID_HANDLE
If either hSess or hFlds are invalid handles.

MQE_EXCEPT_INVALID_ARGUMENT
If an invalid argument is used.

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
Returns '0' on success, or '-1' on failure.

Valid input parameter combinations

pName DataType DataLen Data Comment
! null * >0 ! null Normal usage
! null * >0 null Preallocate a field data.
null * * * Error

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEHFIELDS hFlds;
MQEBYTE  datatype;
MQEINT32  n;
MQEINT32  data;
MQEINT32  compcode;
MQEINT32  reason;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, 
								&reason);
hFlds  = MQeFieldsAlloc( hSess, 
									FieldsType, 
									&compcode, 
									&reason);
 
/* Put a 4-bytes integer into the fields object. */
datatype = MQE_TYPE_INT;
n    = 1;
data   = 0x12345678;
rc = MQeFieldsPut( hSess, hFlds, 
							"MyData", 
							datatype, 
							(MQEBYTE *) 
							&data, n, 
         				&compcode, 
							&reason);

See Also
MQeFieldsGet

MQeFieldsPutArray

Description
Given a name, put an array as individual fields with the field names derived from the name.

Syntax
#include <hmq.h>
MQEVOID MQeFieldsPutArray( MQEHSESS hSess, MQEHFLDS hFlds, 
              MQECHAR* pName, MQEBYTE DataType, MQEVOID * pData, 
              MQEINT32 nElements, MQEINT32 * pCompCode, 
              MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string name of the field. A null or a zero length string is invalid.

MQEBYTE DataType - input
The data type of the field data. See Field data types. This may not be MQE_TYPE_ASCII or MQE_TYPE_UNICODE as the length of each ascii or unicode string in the array is required. Use MQeFieldsPutAsciiArray or MQeFieldsPutUnicodeArray for these field types.

MQEVOID * pData - input
A data buffer whose size is determined from DataType and nElements .

MQEINT32 nElements - input
Number of elements of type DataType in pData . This must be greater than or equal to 0.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE
If either hSess or hFlds are invalid handles.

MQE_EXCEPT_INVALID_ARGUMENT
If an invalid argument is used.

MQE_EXCEPT_ALLOCATION_FAILED

Return Value
MQEVOID

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEHFIELDS hFlds;
MQEBYTE  datatype;
MQEINT32  n = 5;
MQEINT32  data[5];
MQEINT32  compcode;
MQEINT32  reason;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", &compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, &compcode, &reason);
 
/* Put an array of 32 bit integers into the fields object. */
datatype = MQE_TYPE_INT;
data[0]   = 0x12345678;
data[1]   = 0xFEEDBABE;
data[2]   = 0xCAFEBABE;
data[3]   = 0xCOD1F1ED;
data[4]   = 0x1DEC0DED;
MQeFieldsPutArray( hSess, hFlds, "MyData", datatype, (MQEBYTE *) 
         &data, n, &compcode, &reason);

See Also
MQeFieldsGetArray

MQeFieldsPutByArrayOfFd

Description
Creates a set of fields in the MQeFields object given an array of field descriptors. Returns the number of successfully processed descriptors, or '-1' if an error occurred before any descriptors were processed. Descriptors are processed in order and the call fails as soon as the first descriptor fails.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsPutByArrayOfFd( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECONST MQEFIELD pFds[], MQEINT32 nFds, 
                 MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
A session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQEFIELD * pFds - input
An array of struct MQeField_st field descriptors. Puts a field named fd_name into an MQeFields object with fd_datalen elements of type fd_datatype. The field data is taken from fd_data if it is not NULL, otherwise, the field data is set to zero. The fd_namelen field is not used by this call. The field name's length is determined from fd_name .

MQEINT32 nFds - input
Number of descriptors in the pFds array.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of descriptors successfully put.
  • On failure, returns a count of the number of descriptors processed including the failing descriptor.
  • If an error occurs prior to any descriptors being processed, -1 is returned.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
static const MQECHAR * textVal = 
					"The Owl and the Pussy Cat went to sea.";
static const MQEFIELD PFDS[] = {
          {MQE_TYPE_BYTE, 0, 0, "fooByte", 0, 0, 
					(MQEBYTE *)0},
          {MQE_TYPE_SHORT, 0, 0, "fooShort", 0, 0, 
					(MQEBYTE *)0},
          {MQE_TYPE_LONG, 0, 0, "fooLong", 0, 0, 
					(MQEBYTE *)0},
          {MQE_TYPE_ASCII, 0, 0, "fooText", 0, 0, 
					(MQEBYTE *)0}
    };
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEBYTE  byteVal;
MQEINT16  int16Val;
MQEINT32  int32Val, 
				pDataLen[2], 
				*pDataLen2;
MQEVOID * ppData[4], 
			** ppData2, 
			**ppData3;
MQEINT32  rc, nFlds;
MQEINT32  i; 
MQEBYTE  datatype;
MQEFIELD * pFds;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, 
								&reason);
hFlds  = MQeFieldsAlloc( hSess, 
									FieldsType, 
									&compcode, 
									&reason);
 
 
/* Put some fields in the fields object 
		using MQeFieldsPutByArrayOfFd() */
 
byteVal = 0xAE;
int16Val = 0x9876;
int32Val = 0x12345678;
PFDS[0].fd_fd_datalen = sizeof(byteVal);
PFDS[1].fd_fd_datalen = sizeof(int16Val);
PFDS[2].fd_fd_datalen = sizeof(int32Val);
PFDS[3].fd_fd_datalen = strlen(textVal);
PFDS [0].fd_data = (MQEVOID *)&byteVal;
PFDS [1].fd_data = (MQEVOID *)&int16Val;
PFDS [2].fd_data = (MQEVOID *)&int32Val;
PFDS [3].fd_data = (MQEVOID *) textVal;
 
MQFieldsPutByArrayOfFd( hSess, hFlds, PFDS, 4, 
								&compcode, &reason);
 
/* Get the field lengths, not data */
for (i=0;i<4;i++) {
 PFDS[i].fd_fd_datalen = 0;
 PFDS[i].fd_data = (MQEVOID *)0;
}
nFlds = MQFieldsGetByArrayOfFd( hSess, hFlds, PFDS, 4, 
											&compcode, &reason);
 
if (nFlds > 0) {
 /* Get space for field data */
 for( i=0; i<nFlds; i++) {
   PFDS[i].fd_data = (MQEVOID *) 
   malloc(PFDS[i].fd_datalen*mqe_sizeof
								(PFDS[i].fd_datatype));
 }
 /* Get all the fields defined in field 
		descriptor array in one shot */
 nFlds = MQFieldsGetByArrayOfFd( hSess, hFlds, 
												PFDS, nFds, 
												&compcode, 
												&reason);
}

See Also
MQeFieldsGetByArrayOfFd,

MQeFieldsPutByStruct

Description
Given a pointer to a user data structure and an array of structure descriptors, this API puts all the elements in the data structure that are identified by the structure descriptors into the MQeFields object. Returns the number of descriptors successfully processed, or '-1', if an error occurred before any descriptor was processed.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsPutByStruct( MQEHSESS hSess, MQEHFIELDS hFlds, 
                MQEVOID * pStruct, 
                struct MQeFieldStructDescriptor pfsd[], 
                MQEINT32 nSds, MQEINT32 * pCompCode, MQEINT32 * 
                pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

PMQEVOID pStruct - input
A pointer to the data structure that is the source of the data.

struct MQeFieldStructDescriptor * pfsd - input
A definition that defines the relation between the elements in the pStruct and the fields in the MQeFields object.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of fields put successfully.
  • On failure, returns a count of the number of descriptors processed including the failing descriptor.
  • If an error occurs prior to any descriptors being processed, '-1' is returned.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
struct myData_st
{
   MQEINT32 x;           
	/* simple variable */
   MQECHAR *name  ;      
	/* pointer to name buffer */
   MQEINT32 namelen;     
	/* length of name */
   MQEBYTE  buf[8];      
	/* fixed buffer in struct */
   MQEINT32 fieldlen;   
 	/* length of a field, buffer not in struct */
};
 
MQEINT32 field[10];      
/* buffer whose length is in a structure */
 
 
/* A possible sample definition of MQEFIELDDESC for myData_st  */
 
static MQEFIELDDESC 
			myDataStruct_fd[] = {
   		{"x", 1, MQE_TYPE_INT, 0, 0, 1},
   {"name", 4, MQE_TYPE_ASCII, 
			MQSTRUCT_LEN|MQSTRUCT_DATA, 4, 64},
   {"buf",  3, 
			MQE_TYPE_BYTE, 0, 12, 8},
   {"field",5, MQE_TYPE_INT, 
			MQSTRUCT_LEN|MQSTRUCT_NODATA, 20, 0}
};
 
static  MQECHAR * textVal  = 
			"The Owl and the Pussy Cat went to sea.";
static  MQECHAR   textBuf[] = { 0xAB, 0xCD, 0x12, 0x44};
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
struct myData_st myData;
MQEINT32  int32Val;
MQEINT32  rc;
 
/* Initialize data */
myData.x = 20;
myData.name = textVal;
myData.namelen = strlen(textVal);
myData.fieldlen = 10;
for (rc=0; rc<4; 
			rc++) myData.buf[rc] = textVal[rc];
for (rc=0; rc<sizeof(myData.buf); 
			rc++) myData.buf[rc] = 0;
for (rc=0; rc<myData.fieldlen; rc++) field[rc] = rc;
 
hSess   = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds   = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
/* Put the data structure into the fields object. */
rc = MQeFieldsPutByStruct( hSess, hFlds, 
										&myData , 
										myDataStruct_fd, 4, 
										&compcode, 
										&reason);
/* Add "field" whose length is in myData.fieldlen */
rc = MQeFieldsPut( hSess, hFlds, 
							"field", MQE_TYPE_INT, 
							&field, 
							myData.fieldlen, 
							&compcode, 
							&reason); 

See Also
MQeFieldsGetByStruct

MQeFieldsRead

Description
Reads a portion of a field's data block. Returns the number of elements read, or '-1' if an error occurred.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsRead( MQEHSESS hSess, 
				 MQEHFIELDS hFlds, MQECHAR * pName, 
            MQEBYTE DataType, MQEVOID * pDestBuf, MQEINT32 srcOff, 
            MQEINT32 srcLen, MQEVOID * pBase, MQEINT32 * pCompCode, 
            MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string name of the field. A null or a zero length string is invalid.

MQEBYTE DataType - input
The data type of the named field. It must match the data type of the field in the MQeFields object. The value MQE_TYPE_FIELDS in not a valid argument.

MQEBYTE * pDestBuf - output
The destination buffer for the read operation

MQEINT32 srcOff - input
The offset position into the field data to start the read.

MQEINT32 srcLen - input
Number of bytes to read

MQEVOID * pBase - input
The base pointer for the destination buffer pDestBuf .

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_ARGUMENT
Invalid inputs, for example, pDestBuf is a NULL.

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_NOT_FOUND
The named field is not in the MQeFields object.

MQE_EXCEPT_TYPE
The type of the named field does not match DataType .

MQE_EXCEPT_DATA
The field data is not suitable for reading, (for example too short or null)

MQE_EXCEPT_EOF
The srcOff starts beyond the end of the field's data block.

Return Value

MQEINT32
  • On success, returns the number of elements read successfully.
  • On failure, returns '-1'.

Example
#include <hmq.h>
 
static MQECHAR const * FieldsType = "com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEHFIELDS hFlds;
MQEINT32  compcode;
MQEINT32  reason;
MQEINT32  i, nread;
MQECHAR  buf[64];
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
/* Allocate a 128 byte buffer field */
rc = MQeFieldsPut( hSess, hFlds, "y" , 
							MQE_TYPE_BYTE, 
							NULL , 128, 
         				&compcode, &reason); 
 
/* Fill the buffer with values 0-127 */
for (i=0; i<128; i++) {
  char c=i;
  MQeFieldsWrite( hSess, hFlds, "y" , i, &c, 1, 
						&compcode, &reason); 
}
 
/* Read 64 byte out into an output buf, nread = 64 */
nread = MQeFieldsRead( hSess, hFlds, "y", 
								MQE_TYPE_BYTE, 
									buf, 0, 64, NULL, 
            				&compcode, &reason);

See Also

MQeFieldsRestore

Description
An MQeFields object can be restored from a logical byte array to an MQeFields handle using a sequence of MQeFieldsRestore calls. Each individual call does a partial restore of the MQeFields object, specifying the next subarray of the logical byte array. This allows a large MQeFields object to be restored using a smaller buffer. The first call specifies the total length of logical byte array as well as the first partial restore length. The MQeFields handle maintains some restore state in between partial restore calls. It returns the number of bytes consumed by this partial restore.

If the MQeFields handle has a type initially, then the type of the restored MQeFields object must match it, or an error occurs. If not, then the type of the MQeFields handle is set to the type of the restored MQeFields object.

If an error occurs during one of the partial restores, the MQeFields object's internal restore state enters an invalid state, and no further updates are made to the MQeFields handle. The remaining calls should be made with valid arguments (except that the content of the data buffer is ignored), in order to return the MQeFields handle to an inactive restore state. A partially restored field handle (the restore aborted with only some of the fields added) reverts to an inactive state if any other MQeFields operations use the MQeFields handle.

Syntax
#include <hmq.h>
MQINT32 MQeFieldsRestore( MQEHSESS hSess, MQEHFIELDS hFlds, 
             MQEINT32 dumpLen, MQEBYTE data[], MQEINT32 dataLen, 
             MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
The field object handle that is being restored. An MQE_HANDLE_NULL handle is a invalid input. This field object handle should be allocated by MQeFieldsAlloc with "" as the type input parameter to restore an arbitrary MQeFields object.

MQEINT32 dumpLen - input
The total dump length of the MQeFields object. This parameter is only used on the first partial restore, although it is recommended that subsequent calls use the same original value.

MQEBYTE data[] - input
The data byte array from which to perform a partial restore of the MQeFields object.

MQEINT32 dataLen - input
The number of bytes to restore. This is the length of the current partial restore.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE
The fields object handle is invalid.

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_ALLOCATION_FAILED

MQE_EXCEPT_DATA
The byte array could be corrupted. The restore operation could not reconstruct the MQeFields object.

Return Value

MQINT32
  • On success, returns the number of bytes restored.
  • On failure, returns '-1'.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
struct myData_st
{
   MQEINT32 x;           
/* simple variable */
   MQECHAR *name  ;      
/* pointer to name buffer */
   MQEINT32 namelen;     
/* length of name */
   MQEBYTE  buf[8];      
/* fixed buffer in struct */
   MQEINT32 fieldlen;    
/* length of a field, buffer not in struct */
};
 
MQEINT32 field[10];      
/* buffer whose length is in a structure */
 
 
/* A possible sample definition of MQEFIELDDESC for myData_st */
static MQEFIELDDESC myDataStruct_fd[] = {
   {"x", 1, MQE_TYPE_INT, 0, 0, 1},
   {"name", 4, MQE_TYPE_ASCII, 
			MQSTRUCT_LEN|MQSTRUCT_DATA, 4, 64},
   {"buf",  3, 
			MQE_TYPE_BYTE, 0, 12, 8},
   {"field",5, MQE_TYPE_INT, 
			MQSTRUCT_LEN|MQSTRUCT_NODATA, 20, 0}
};
 
static  MQECHAR * textVal  = 
			"The Owl and the Pussy Cat went to sea.";
static  MQECHAR   textBuf[] 
			= { 0xAB, 0xCD, 0x12, 0x44};
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
struct myData_st myData;
MQEINT32  int32Val;
MQEINT32  rc;
 
/* Initialize data */
myData.x = 20;
myData.name = textVal;
myData.namelen = strlen(textVal);
myData.fieldlen = 10;
for (rc=0; rc<4; rc++) myData.buf[rc] = 
			textVal[rc];
for (rc=0; rc<sizeof(myData.buf); rc++) 
			myData.buf[rc] = 0;
for (rc=0; rc<myData.fieldlen; rc++) 
			field[rc] = rc;
 
hSess   = MQeInitialize("MyAppsName", 
									&compcode, 
									&reason);
hFlds   = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, 
									&reason);
 
/* Put the data structure 
	into the fields object. */
rc = MQeFieldsPutByStruct( hSess, hFlds, 
									&myData , 
									myDataStruct_fd, 4, 
									&compcode, 
									&reason);
/* Add "field" whose length is in myData.fieldlen */
rc = MQeFieldsPut( hSess, hFlds, 
							"field", 
							MQE_TYPE_INT, 
							&field, 
							myData.fieldlen, 
							&compcode, 
							&reason); 

See Also

MQeFieldsType

Description
Determines the string name of an MQeFields object. Returns the length of the name (not including the terminating NULL) on success. Returns '0' on error.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsType( MQEHSESS hSess, MQEHFIELDS hFlds, 
            MQECHAR * pTypeName, MQEINT32 typeLen, 
            MQEINT32 * pCompCode, MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pTypeName input and output
The output buffer that the MQeFields object type string name is to be copied into. If NULL, no data is returned.

MQEINT32 typeLen - input
The size of the pTypeName buffer in MQECHAR format. If pTypeName is a NULL, this parameter is ignored.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
  • On success, returns the length of the type name (not including the terminating NULL).
  • On failure, returns '-1'.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQECHAR * pname;
MQEINT32  datalen, rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, 
								&reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, 
									&reason);
 
/* Get the length of object type name */
datalen = MQeFieldsType( hSess, hFlds, 0, 
									NULL, 
									&compcode, 
									&reason);
pname  = (MQECHAR *) 
			malloc(datalen+1);
 
/* Get the object type name */
rc   = MQeFieldsType( hSess, hFlds, 
								pname, datalen, 
								&compcode, 
								&reason);
 

MQeFieldsWrite

Description
Writes into the data block of an existing field in an MQeFields object. Returns the number of elements written, or '-1' if an error occurs.

Syntax
#include <hmq.h>
MQEINT32 MQeFieldsWrite( MQEHSESS hSess, 
				MQEHFIELDS hFlds, MQECHAR * pName, 
           MQEBYTE DataType, MQEINT32 dstOffset, 
           MQEBYTE * pSrcBuf, MQEINT32 srcLen, 
           MQEINT32 * pCompCode, MQEINT32 * pReason) 
 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
The field name. A null or a zero length string is invalid.

MQEINT32 DataType - input
The data type of field. The types MQE_TYPE_FIELDS and MQE_TYPE_BOOLEAN are invalid.

MQEINT32 * dstOffset - input
The offset into the field data to start the write

MQEBYTE * pSrcBuf - input
The source buffer

MQEINT32 srcLen - input
The number of elements of type DataType to write.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_ARGUMENT
Invalid inputs. For example, pSrcBuf is a NULL

MQE_EXCEPT_TYPE
DataType does not match data type of the field.

MQE_EXCEPT_NOT_FOUND
No field with name pName found in hFlds

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_EOF
End of field reached.

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of elements written.
  • On failure, returns '-1'.

Example
#include <hmq.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEHFIELDS hFlds;
MQEINT32  compcode;
MQEINT32  reason;
MQEINT32  i, nread;
MQECHAR  buf[64];
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, 
								&reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, 
									&reason);
 
/* Allocate a 128 byte buffer field */
rc = MQeFieldsPut( hSess, hFlds, "y" , 
							MQE_TYPE_BYTE, 
							NULL, 128, 
         				&compcode, 
							&reason); 
 
/* Fill the buffer with values 0-127 */
for (i=0; i<128; i++) {
char c=i;
MQeFieldsWrite( hSess, hFlds, "y", 
						MQE_TYPE_BYTE, i, 
						&c, 1, 
        				&compcode, 
						&reason); 
}
 
/* Read 64 byte out into an output buf, nread = 64 */
nread = MQeFieldsRead( hSess, hFlds, "y", 
								MQE_TYPE_BYTES, 
								buf, 0, 64, 
								NULL, 
            				&compcode, 
								&reason);

See Also

MQeFieldsContains

Description
Determines whether the MQeFields object contains a specific field.

Syntax
#include <hmq.h>
#include <hmqHelper.h>
MQEINT32 MQeFieldsContains( MQEHSESS hSess, MQEHFIELDS hFlds, 
              MQECHAR * pName, MQEINT32 * pCompCode, 
              MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
  • '1' the MQeFields object contains the given field
  • '0' the field is not found.
  • '-1' failure.

See Also
MQeFieldsGet

MQeFieldsCopy

Description
Copy one or all fields from one MQeFields object to another.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsCopy( MQEHSESS hSess, MQEHFIELDS hSrcFlds, 
            MQEHFIELDS hDstFlds, MQEINT32 Option, 
            MQECHAR * pName, MQEINT32 * pCompCode, 
            MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hSrcFlds - input
The handle of the source MQeFields object.

MQEHFIELDS hDstFlds - input
The handle of the destination MQeFields object.

MQEINT32 Option - input

MQE_FIELDS_OPTION_NONE
This is the default option. It copies the specified field from the source MQeFields object to the destination MQeFields object, but does not replace the data if the field is found in the destination MQeFields object.

MQE_FIELDS_OPTION_ALL_FIELDS
If specified, this API copies all fields from the source MQeFields object to the destination MQeFields object.

MQE_FIELDS_OPTION_REPLACE
If specified, this API overwrites any fields in the destination MQeFields object that have the same field name as the field from the source MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. If MQE_FIELDS_OPTION_ALL_FIELDS is specified, then this parameter is ignored. A null or a zero length string is invalid.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT
Field name too short or too long.

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32

Returns '0' on success, or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
static const MQECHAR * textVal = 
			"The Owl and the Pussy Cat went to sea";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds1, hFlds2;
MQEINT32  n;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, 
								&reason);
hFlds1 = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, 
									&reason);
rc   = MQeFieldsPut( hSess, hFlds1, 
								"ibm", 
								MQE_TYPE_UNICODE, 
								strlen(textVal)), 
           				 textVal, 
								&compcode, 
								&reason); 
 
MQeFieldsCopy( hSess, hFlds1, 
						hFlds2, 
						MQE_FIELDS_OPTION_ALL_FIELDS, 
						NULL, 
       				&compcode, 
						&reason);
 
n    = MQeFieldsDataLen( hSess, 
									hFlds2, 
									"ibm", 
									&compcode, 
									&reason);
 
pData  = (MQEBYTE *) 
			calloc(n, MQE_SIZEOF(datatype));
 
/* Copy out the data */
rc   = MQeFieldsGetAscii( hSess, 
									hFlds2, 
									"ibm", 
									pData, n, 
              				&compcode, 
									&reason);

See Also
MQeFieldsGet

MQeFieldsDataLength

Description
Return the number of elements in a field, in units of the field's data type, or '-1' on error.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsDataLength(MQEHSESS hSess, 
											MQEHFIELDS hFlds, 
											MQECHAR * pName, 
               						MQEINT32 * pCompCode, 	
											MQEINT32 * pReason) 

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
  • On success, returns the number of elements in the field.
  • On failure, returns '-1'.

Pseudo-code
MQEINT32 MQeFieldsDataLength( hSess, 
											hFlds, 
											pName, 
											pCompCode, 
											pReason) {
  MQEBYTE datatype=0;
  MQEINT32 datalen;
  datalen = MQeFieldsGet( hSess, 
									hFlds, 
									pName, 
									&datatype, 
									NULL, 0, 
									NULL, 
              				pCompCode, 
									pReason);
  return datalen;
}

See Also
MQeFieldsGet

MQeFieldsDataType

Description
Returns the field data type, or '-1' on error.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEBYTE MQeFieldsDataType( MQEHSESS hSess, 
										MQEHFIELDS hFlds, 
										MQECHAR * pName, 
              					MQEINT32 * pCompCode, 
										MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEBYTE
Returns the field data type or '-1' on failure.

See Also
MQeFieldsGet

MQeFieldsGetArrayLength

Description
Gets the number of elements in an encoded array. Returns the number of elements, or '-1' on error.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsGetArrayLength( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_TYPE
The field is not an encoded array.

MQE_EXCEPT_DATA
The field is not a valid encoded array.

Return Value

MQEINT32
  • On success, returns the number of elements in the encoded array.
  • On failure, returns '-1'.

Example
#include <hmq.h>
#include <:hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
MQEBYTE    datatype;
MQEINT32   data[2], n;
MQEINT32 * pData;
MQEINT32   rc;
 
 
hSess   = MQeInitialize("MyAppsName", 
									&compcode, 
									&reason);
hFlds   = MQeFieldsAlloc( hSess, 
										FieldsType, 
										&compcode, 
										&reason);
data[0] = 0x12345678;
data[1] = 0xDEADBEEF;
rc      = MQeFieldsPutIntArray(hSess, hFlds, 
											"foo", data, 2, 
											&compcode, 
											&reason); 
 
/* Get the data length */
n 		= MQeFieldsGetArrayLength( hSess, 
												hFlds, 
												"foo", 
												&compcode, 
												&reason );
 
datatype= MQE_TYPE_INT;
pData   = malloc(n * MQE_SIZEOF(datatype));
 
/* Copy out the data */
rc      = MQeFieldsGetIntArray( hSess, 
												hFlds, 
												"foo", 
												pData, 0, n, 
												&compcode, 
												&reason );
 

See Also
MQeFieldsPutArrayLength

MQeFieldsGetBoolean, MQeFieldsGetByte, MQeFieldsGetShort, MQeFieldsGetInt, MQeFieldsGetLong, MQeFieldsGetDouble, MQeFieldsGetFloat

Description
Extracts typed data from the MQeFields object as a single 1, 2, 4, or 8-byte integer, float or double.

Syntax
#include <hmq.h>
#include <hmqHelper.h> 
MQEINT32 MQeFieldsGetBoolean( MQEHSESS hSess, 
					MQEHFIELDS hFlds, MQECHAR * pName, 
              MQEBYTE * pBoolean, MQEINT32 * pCompCode, 
              MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetByte( MQEHSESS hSess, 
										MQEHFIELDS hFlds, MQECHAR * pName, 
             						MQEBYTE * pByte, 
										MQEINT32 * pCompCode, 
             						MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetShort( MQEHSESS hSess, 
										MQEHFIELDS hFlds, MQECHAR * pName, 
             						MQEINT16 * pShort, 
										MQEINT32 * pCompCode, 
              					MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetInt( MQEHSESS hSess, 
									MQEHFIELDS hFlds, MQECHAR * pName, 
             					MQEINT32 * pInt, 
									MQEINT32 * pCompCode, 
             					MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetLong( MQEHSESS hSess, 
									MQEHFIELDS hFlds, MQECHAR * pName, 
             					MQEINT64 * pLong, MQEINT32 * pCompCode, 
             					MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetFloat( MQEHSESS hSess, 
										MQEHFIELDS hFlds, MQECHAR * pName, 
              					MQEBYTE * pFloat, 
										MQEINT32 * pCompCode, 
              					MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetDouble( MQEHSESS hSess, 
										MQEHFIELDS hFlds, MQECHAR * pName, 
              					MQEBYTE * pDouble, 
										MQEINT32 * pCompCode, 
              					MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEBYTE * pBoolean - output
The returned boolean value.

MQEBYTE * pByte - output
The returned byte value.

MQEINT16 * pShort - output
The returned short value.

MQEINT32 * pInt - output
The returned 4 byte integer value.

MQEINT64 * pLong - output
The returned 8 byte integer value.

MQEFLOAT * pFloat - output
The returned double value.

MQEDOUBLE * pDouble - output
Returned float value.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output

Return Value

MQEINT32
Returns '0' on success or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEBYTE  booleanVal;
MQEBYTE  byteVal;
MQEINT16  int16Val;
MQEINT32  int32Val;
MQEINT64  int64Val;
MQFLOAT  floatVal;
MQDOUBLE  doubleVal;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
byteVal  = 1;
rc    = MQeFieldsPut( hSess, hFlds, "bool",  
								MQE_TYPE_BYTE, &booleanVal, 1, 
             				&compcode, &reason); 
byteVal  = 0x45;
rc    = MQeFieldsPut( hSess, hFlds, "b",  
								MQE_TYPE_BYTE, &byteVal, 1, 
             				&compcode, &reason); 
int16Val  = 32000;
rc    = MQeFieldsPut( hSess, hFlds, "sh", 
								MQE_TYPE_SHORT, 
								&int16Val, 1, 
            				&compcode, &reason); 
int32Val  = 2000000000;            
rc    = MQeFieldsPut( hSess, hFlds, "int", 
								MQE_TYPE_INT, 
								&int32Val, 1, 
            				&compcode, &reason); 
int64Val.hi = 265;
int64Val.lo = 2000000000;
rc    = MQeFieldsPut( hSess, hFlds, "lg", 
								MQE_TYPE_LONG, 
								&int64Val, 1, 
            				&compcode, &reason); 
floatVal  = 2.55;
rc    = MQeFieldsPut( hSess, hFlds, "f",  
								MQE_TYPE_FLOAT, 
								&floatVal, 1, 
            				&compcode, &reason); 
doubleVal = 2.3413453231e-63;
rc    = MQeFieldsPut( hSess, hFlds, "d",  
								MQE_TYPE_DOUBLE, 
								&doubleVal, 1, 
            				&compcode, &reason); 
 
booleanVal = 0;
byteVal  = 0;
int16Val  = 0;
int32Val  = 0;
int64Val.lo  = 0;
int64Val.hi  = 0;
floatVal = 0.0;
aDouble = 0.0;
 
/* Get the data */
MQeFieldsGetBoolean ( hSess, hFlds, "bool", 
								&booleanVal, 
								&compcode, 
								&reason);
MQeFieldsGetByte ( hSess, hFlds, "b", 
							&byteVal, 
							&compcode, 
							&reason);
MQeFieldsGetShort ( hSess, hFlds, "sh" , 
							&int16Val, 
							&compcode, 
							&reason);
MQeFieldsGetInt  ( hSess, hFlds, "int", 
							&int32Val , 
							&compcode, 
							&reason);
MQeFieldsGetLong ( hSess, hFlds, "lg", 
						&int64Val , 
						&compcode, 
						&reason);
MQeFieldsGetFloat ( hSess, hFlds, "f", 
							&floatVal , 
							&compcode, 
							&reason);
MQeFieldsGetDouble( hSess, hFlds, "d", 
							&doubleVal , 
							&compcode, 
							&reason);

See Also

MQeFieldsGetFields

Description
Extracts a nested MQeFields object from an MQeFields handle.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEHFIELDS MQeFieldsGetFields( MQEHSESS hSess, MQEHFIELDS hFlds, 
                MQECHAR * pName, MQEINT32 * pCompCode, 
                MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output

Return Value

MQEHFIELDS
  • Returns the field object handle of the given field.
  • On error returns MQEHANDLE_NULL.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
const char * hello = "Hello World";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds1, hFlds2, hFlds3;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds1 = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
hFlds2 = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
/* Put hFlds1 into hFlds2 */
rc   = MQeFieldsPut( hSess, hFlds1, "ibm", 
								MQE_TYPE_ASCII, hello, 
            				strlen(hello), 
								&compcode, &reason); 
rc   = MQeFieldsPutFields( hSess, hFlds2, 
										"ibmFields", hFlds1, 
               					&compcode, &reason);
/* hFlds1 is no longer valid */
 
/* Retrieve hFlds1 as hFlds3 from hFlds2 */
hFlds3 = MQeFieldsGetFields( hSess, hFlds2, 
										"ibmFields", 
                          	&compcode, &reason);
 
/* Extract the "ibm" field */
datalen = MQeFieldsGet( hSess, hFlds3, "ibm", 
								&datatype, 
								NULL, 0, NULL, 
            				&compcode, &reason); 
pData  = malloc(datalen+1);
datalen = MQeFieldsGet( hSess, hFlds3, "ibm", 
								&datatype, 
								pData, 0, 
								datalen, 
            				&compcode, 
								&reason); 
pData[datalen] = '\0';
printf("Field is %s\n", pData);
 
/* Free the fields resources */
MQeFieldsFree( hSess, hFlds3, 
					&compcode, &reason);
MQeFieldsFree( hSess, hFlds2, 
					&compcode, &reason);

See Also
MQeFieldsPutFields

MQeFieldsGetArrayOfByte, MQeFieldsGetArrayOfShort, MQeFieldsGetArrayOfInt, MQeFieldsGetArrayOfLong, MQeFieldsGetArrayOfFloat, MQeFieldsGetArrayOfDouble

Description
Extracts the data from the MQeFields object as an array of 1, 2, 4, and 8-byte integers, floats and doubles.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsGetArrayOfByte( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEVOID * pBytes, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetArrayOfShort( MQEHSESS hSess, MQEHFIELDS hFlds, 
                  MQECHAR * pName, MQEVOID * pShorts, 
                  MQEINT32 n, MQEINT32 * pCompCode, 
                  MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetArrayOfInt( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEVOID * pInts, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetArrayOfLong( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEVOID * pLongs, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetArrayOfFloat( MQEHSESS hSess, MQEHFIELDS hFlds, 
                  MQECHAR * pName, MQEVOID * pFloats, 
                  MQEINT32 n, MQEINT32 * pCompCode, 
                  MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetArrayOfDouble( MQEHSESS hSess, MQEHFIELDS hFlds, 
                  MQECHAR * pName, MQEVOID * pDoubles, 
                  MQEINT32 n, MQEINT32 * pCompCode, 
                  MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEVOID * pBytes - output
The returned byte value.

MQEVOID * pShorts - output
The returned short value.

MQEINT32 * pInts - output
The returned 4 byte integer value.

MQEVOID * pLongs - output
The returned 8 byte integer value.

MQEVOID * pFloats - output
The returned double value.

MQEVOID * pDoubles - output
The returned float value.

MQEINT32 n - input
The size of the input buffer, in elements of the corresponding call.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output

Return Value

MQEINT32
  • On success, returns the number of elements in the array.
  • On failure, returns '-1'.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
MQEBYTE    bytes[5];
MQEINT16   shorts[2];
MQEINT32   ints[3];
MQEINT64   longs[2];
MQEINT32   rc;
 
hSess    = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds    = MQeFieldsAlloc( hSess, FieldsType, 
										&compcode, &reason);
bytes[0] = 0x30;
bytes[1] = 0x31;
bytes[2] = 0x32;
bytes[3] = 0x33;
bytes[4] = 0x34;
rc       = MQeFieldsPut( hSess, hFlds, "b",  
									MQE_TYPE_BYTE, bytes, 5, 
									&compcode, &reason); 
shorts[0]= 32000;
shorts[1]= 32020;
rc       = MQeFieldsPut( hSess, hFlds, "sh", 
									MQE_TYPE_SHORT, shorts, 2, 
									&compcode, &reason); 
ints[0]  = 2000100000;
ints[1]  = 2000020000;
ints[2]  = 2000003000;
rc       = MQeFieldsPut( hSess, hFlds, "int", 
									MQE_TYPE_INT, ints, 3, 
									&compcode, &reason); 
longs[0].hi = 265;
longs[0].lo = 2000000000;
longs[1].hi = 2000000000;
longs[1].lo = 255;
rc       = MQeFieldsPut( hSess, hFlds, "lg", 
									MQE_TYPE_LONG, longs, 2, 
									&compcode, &reason); 
 
memset(bytes , 0, sizeof(bytes));
memset(shorts, 0, sizeof(shorts));
memset(ints  , 0, sizeof(ints));
memset(longs , 0, sizeof(longs));
 
/* Get the data */
MQeFieldsGetArrayOfByte ( hSess, hFlds, "b", 
										bytes  , 5, 
										&compcode, &reason );
MQeFieldsGetArrayOfShort( hSess, hFlds, "sh", 
										shorts , 2, 
										&compcode, &reason );
MQeFieldsGetArrayOfInt  ( hSess, hFlds, "int", 
										ints, 3, 
										&compcode, &reason );
MQeFieldsGetArrayOfLong ( hSess, hFlds, "lg", 
										longs  , 2, 
										&compcode, &reason );

See Also

MQeFieldsGetAscii, MQeFieldsGetUnicode, MQeFieldsGetObject

Description
Extracts an array of MQECHAR, MQEINT16, or MQEBYTE from a single field in the MQeFields object. The extracted arrays are not terminated with an additional NULL, so if the field data is not terminated the extracted string is not. Returns the length of the field data (not the extracted string) as the number of elements (not bytes) or '-1' on error.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsGetAscii( MQEHSESS hSess, 
									MQEHFIELDS hFlds, 
              				MQECHAR* pName, MQEBYTE* pData, 
             					MQEINT32 DataLen, MQEINT32* 
              				pCompCode, MQEINT32* pReason) 
 
MQEINT32 MQeFieldsGetUnicode( MQEHSESS hSess, 
										MQEHFIELDS hFlds, 
               					MQECHAR* pName, MQEINT16 pData, 
              					MQEINT32 DataLen, 
               					MQEINT32* pCompCode, MQEINT32* pReason) 
 
MQEINT32 MQeFieldsGetObject( MQEHSESS hSess, 
										MQEHFIELDS hFlds, 
										MQECHAR* pName, 
               					MQEBYTE* pData, 
										MQEINT32 DataLen, 
               					MQEINT32 * pCompCode, 
										MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEBYTE * pData - output
The caller supplied destination buffer to receive the output data.

MQEINT16 * pData - output
The caller supplied destination buffer to receive the output data.

MQEINT32 DataLen - input
The maximum number of elements to copy

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output

Return Value

MQEINT32
  • On success, returns the number of elements in the field.
  • On failure, returns '-1'.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
static const MQECHAR * textVal = 
			"The Owl and the Pussy Cat went to sea";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEINT32  n;
MQEBYTE  datatype;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, 
								&reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
rc   = MQeFieldsPut( hSess, hFlds, "ibm", 
								MQE_TYPE_ASCII, 
								strlen(textVal)), 
            				textVal, 
								&compcode, 
								&reason); 
 
/* Get the data length */
n    = MQeFieldsDataLen( hSess, hFlds, "ibm", 
									&compcode, &reason);
 
datatype= MQE_TYPE_ASCII;
pData  = (MQEBYTE *) 
			calloc(n, MQE_SIZEOF(datatype));
 
/* Copy out the data */
rc   = MQeFieldsGetAscii( hSess, hFlds, "ibm", 
									pData, n, 
									&compcode, &reason);

See Also

MQeFieldsGetShortArray, MQeFieldsGetIntArray, MQeFieldsGetLongArray, MQeFieldsGetFloatArray, MQeFieldsGetDoubleArray

Description
Extracts an encoded array from the MQeFields object as an array of 2, 4, or 8-byte integers, floats, or doubles.

Returns the number of elements successfully extracted, or '-1' on an error.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsGetShortArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEINT16 * pData, 
                 MQEINT32 srcOff, MQEINT32 n, 
                 MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetIntArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
                MQECHAR * pName, MQEINT32 * pData, 
                MQEINT32 srcOff, MQEINT32 n, 
                MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetLongArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
                MQECHAR * pName, MQEINT64 * pData, 
                MQEINT32 srcOff, MQEINT32 n, 
                MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetFloatArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEFLOAT * pData, 
                 MQEINT32 srcOff, MQEINT32 n, 
                 MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsGetDoubleArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEDOUBLE * pData, 
                 MQEINT32 srcOff, MQEINT32 n, 
                 MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string name of the field. A null or a zero length string is invalid.

MQEINT16 * pData - output
The returned short value.

MQEINT32 * pData - output
The returned 4 byte integer value.

MQEINT64 * pData - output
The returned 8 byte integer value.

MQEFLOAT * pData - output
The returned double value.

MQEDOUBLE * pData - output
The returned float value.

MQEINT32 srcOff - input
The starting index for source array.

MQEINT32 n - input
The number of elements to get.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_DATA
srcOff is out of range, or invalid array encoding.

MQE_EXCEPT_TYPE
Field element does not match requested type.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
  • On success, returns the number of elements in the source array.
  • On failure, returns a count of the number of elements processed in the source array including the failing element.
  • If an error occurs prior to any elements being processed, '-1' is returned.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
MQEINT16   shorts[2];
MQEINT16*  gotShorts;
MQEINT32   ints[3];
MQEINT32*  gotInts;
MQEINT64   longs[2];
MQEINT64*  gotLongs;
MQEINT32   rc;
MQEINT32   length;
#define NULL 0
 
hSess    = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds    = MQeFieldsAlloc( hSess, FieldsType, 
										&compcode, &reason);
 
shorts[0]= 32000;
shorts[1]= 32020;
MQeFieldsPutArray( hSess, hFlds, "sh", 
							MQE_TYPE_SHORT, 
							&shorts[0], 2, 
							&compcode, 
							&reason); 
ints[0]  = 2000100000;
ints[1]  = 2000020000;
ints[2]  = 2000003000;
MQeFieldsPutArray( hSess, hFlds, "int", 
							MQE_TYPE_INT, 
							&ints[0], 3, 
							&compcode, 
							&reason); 
longs[0].hi = 265;
longs[0].lo = 2000000000;
longs[1].hi = 2000000000;
longs[1].lo = 255;
MQeFieldsPutArray( hSess, hFlds, "lg", 
							MQE_TYPE_LONG, 
							&longs[0], 2, 
							&compcode, 
							&reason); 
 
/* Get the data */
length = MQeFieldsGetShortArray ( hSess, hFlds, "sh", 
												NULL, 0, 0, 
												&compcode, 
												&reason );
gotShorts = malloc(length * MQE_SIZEOF
							( MQE_TYPE_SHORT ));
MQeFieldsGetShortArray ( hSess, hFlds, "sh", 
									gotShorts, 0, 
									length, 
									&compcode, 
									&reason );
 
length = MQeFieldsGetIntArray   ( hSess, hFlds, "int", 
												NULL, 0, 0, 
												&compcode, 
												&reason );
gotInts = malloc(length * MQE_SIZEOF
							( MQE_TYPE_INT ));
MQeFieldsGetIntArray   ( hSess, hFlds, "int", 
									gotInts, 0, 
									length, 
									&compcode, 
									&reason );
 
length = MQeFieldsGetLongArray  ( hSess, hFlds, "lg", 
												NULL, 0, NULL, 
												&compcode, 
												&reason );
gotLongs = malloc(length * MQE_SIZEOF
								( MQE_TYPE_LONG ));
MQeFieldsGetLongArray  ( hSess, hFlds, "lg", 
									gotLongs, 0, 
									length, 
									&compcode, 
									&reason );

See Also

MQeFieldsGetAsciiArray, MQeFieldsGetUnicodeArray, MQeFieldsGetByteArray

Description
Extracts an encoded two dimensional array of MQECHAR, MQESHORT, or MQEBYTE. Starting at source index srcOff. Extract at most n arrays, into each of the buffers provided by ppData. The input values in pDataLen indicate the size of the buffer. The output values indicate the size of the corresponding string in the field, or '-1' if an error occurred for the string at the corresponding index. Both ppStr and pDataLen start at base '0' regardless of the value of srcOff .

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsGetAsciiArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQECHAR * ppData[], 
                 MQEINT32 pDataLen[], MQEINT32 srcOff, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
MQEINT32 MQeFieldsGetUnicodeArray( MQEHSESS hSess, MQEHFIELDS hFlds,
                  MQECHAR * pName, MQEINT16 * ppData[], 
                  MQEINT32 pDataLen[], MQEINT32 srcOff, 
                  MQEINT32 n, MQEINT32 * pCompCode, 
                  MQEINT32 * pReason) 
MQEINT32 MQeFieldsGetByteArray( MQEHSESS hSess, MQEHFIELDS hFlds, 
                MQECHAR * pName, MQEBYTE * ppData[], 
                MQEINT32 pDataLen[], 
                MQEINT32 srcOff, MQEINT32 n, 
                MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQECHAR * ppData[] - output
Array of n buffers, starting at index '0'. If any buffer is NULL, then data is not extracted for that buffer. If NULL, then all buffers are treated as NULL.

MQEINT16 * ppData[] - output
Array of n buffers, starting at index '0'. If any buffer is NULL, then data is not extracted for that buffer. If NULL, then all buffers are treated as NULL.

MQEBYTE * ppData[] - output
Array of n buffers, starting at index '0'. If any buffer is NULL, then data is not extracted for that buffer. If NULL, then all buffers are treated as NULL.

MQEINT32 pDataLen[] - input and output
Array of n buffer lengths. The input values specify the length of the buffer in MQECHAR. The output values specify the length of the array element in the MQeFields object in MQECHAR. If NULL, then all buffer lengths are considered to be '0'.

MQEINT32 srcOff - input
The starting source index from which to copy the array elements.

MQEINT32 n - input
The number of elements to get. If '0', the number of elements in the field is returned.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
A field was not found.

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_ALLOCATION_FAILED

MQE_EXCEPT_TYPE
The data type of an array element does not match the type of the initial source array element, or the number of array elements encoded in hFlds is invalid.

MQE_EXCEPT_DATA
The field containing the size of the array contains an invalid value.

MQE_EXCEPT_INVALID_ARGUMENT
scrOff is less than '0' or greater than or equal to the number of elements in the source array.

Return Value

MQEINT32
  • On success, returns the number of in the encoded array.
  • On failure, returns a count of the number of elements processed in the array including the failing element.
  • If an error occurs prior to any elements being processed, '-1' is returned.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
		"com.ibm.mqe.MQeFields";
static const MQECHAR * textArray[] = 
        { "The Owl and the Pussy Cat went to sea",
         "Here we go round the Mulberry bush",
         "Jack and Jill went up the hill" };
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEINT32  pStrLen[3], n, *pStrLen2;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
pStrLen[0] = strlen(textArray[0]);
pStrLen[1] = strlen(textArray[1]);
pStrLen[2] = strlen(textArray[2]);
rc = MQeFieldsPutAsciiArray( hSess, hFlds, "ibm", 
										textArray, pStrLen, 3, 
              					&compcode, &reason); 
 
/* 1. Get number of elements */
n = MQeFieldsGetAsciiArray( hSess, hFlds, "ibm", 
										NULL, NULL, 0, 0, 
              					&compcode, &reason);
 
/* Get space for array of string length */
pStrLen2 = (MQEINT32 *) 
				malloc(n * sizeof(MQEINT32));
memset(pStrLen2, 0, n * sizeof(MQEINT32));
 
/* 2. Get array of string length */
n = MQeFieldsGetAsciiArray( hSess, hFlds, "ibm", 
										NULL, pStrLen2, 0, n, 
              					&compcode, &reason);
 
/* Get space for array of string */
for (i=0; i<n; i++) {
  pStr[i] = (MQECHAR *) 
								malloc(pStrLen[j]+1);
  memset(pStr[i], 0, 
			pStrLen[j]+1);
}
 
/* 2. Get array of strings */
n = MQeFieldsGetAsciiArray( hSess, hFlds, "ibm", 
										pStr, pStrLen2, 0, n, 
              					&compcode, &reason);
 

See Also

MQeFieldsPutArrayLength

Description
Puts the number of elements in an encoded array.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutArrayLength( 
						MQEHSESS hSess, MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEINT32 nElements, 
                 MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT32 nElements - input
The number of array elements

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
Returns '0' on success, or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
 
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS   hSess;
MQEINT32   compcode;
MQEINT32   reason;
MQEHFIELDS hFlds;
MQEINT32   n, data0, data1;
MQEINT32 * pData;
MQEINT32   rc;
 
hSess   = MQeInitialize("MyAppsName", 
				&compcode, &reason);
hFlds   = MQeFieldsAlloc( hSess, FieldsType, 
				&compcode, &reason);
 
/* Manual construction of an 
/*integer array (vector) with two elements) */
data0 = 0x12345678;
data1 = 0xBEEFDEAD;
MQeFieldsPut( hSess, hFlds, "foo:0", 
					MQE_TYPE_INT, 
					&data0, 1, 
					&compcode, 
					&reason); 
MQeFieldsPut( hSess, hFlds, "foo:1", 
					MQE_TYPE_INT, 
					&data1, 1, 
					&compcode, 
					&reason); 
MQeFieldsPutArrayLength( hSess, hFlds, 
									"foo", 2, 	
									&compcode, 
									&reason); 
 
/* Get the data length */
n       = MQeFieldsGetArrayLength( hSess, hFlds, "foo", 
												&compcode, 
												&reason );
 
pData   = malloc(n * MQE_SIZEOF
						(MQE_TYPE_INT));
 
/* Get back the data */
rc      = MQeFieldsGetIntArray( hSess, hFlds, "foo", 
												pData, 0, n, 
												&compcode, &reason );

See Also
MQeFieldsGetArrayLength

MQeFieldsPutBoolean

Description
Puts a boolean value into an MQeFields object.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutBoolean( MQEHSESS hSess, MQEHFIELDS hFlds, 
               MQECHAR * pName, MQEBYTE aBool, 
               MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEBYTE aBool - input
A boolean value

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
Returns '0' on success, or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType 
				= "com.ibm.mqe.MQeFields";
static const MQECHAR * textVal = 
			"The Owl and the Pussy Cat went to sea";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQBOOL   aBool;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
aBool  = 1;
MQeFieldsPutBoolean( hSess, hFlds, 
								"ibm", aBool, 
								&compcode, &reason); 

See Also

MQeFieldsPutFields

Description
Puts an MQeFields object into another MQeFields object. The MQeFields object that is being put into the other MQeFields object becomes invalid after the API call. An MQeFields object cannot be inserted into itself.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutFields( MQEHSESS hSess, MQEHFIELDS hFlds1, 
              MQECHAR * pName, MQEHFIELDS hFlds2, 
              MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds1 - input
The MQeFields object that is receiving hFlds2.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEHFIELDS hFlds2 - input
The MQeFields object that is being moved into hFlds1. This MQeFields object becomes invalid after this API returns.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT
Invalid pName or hFlds1 is the same as hFlds2 .

Return Value

MQEINT32
Returns '0' on success or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
const char * hello = "Hello World";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds1, hFlds2, hFlds3;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
				&compcode, &reason);
hFlds1 = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
hFlds2 = MQeFieldsAlloc( hSess, FieldsType, 
										&compcode, &reason);
 
/* Put hFlds1 into hFlds2 */
rc   = MQeFieldsPut( hSess, hFlds1, "ibm", 
								MQE_TYPE_ASCII, hello, 
            				strlen(hello), 
								&compcode, &reason); 
rc   = MQeFieldsPutFields( hSess, hFlds2, 
										"ibmFields", 
               					hFlds1, 
										&compcode, 
										&reason);
/* hFlds1 is no longer valid */
 
/* Retrieve hFlds1 as hFlds3 from hFlds2 */
hFlds3 = MQeFieldsGetFields( hSess, hFlds2, 
											"ibmFields", 
											&compcode, 
               						&reason);
 
/* Extract the "ibm" field */
datalen = MQeFieldsGet( hSess, hFlds3, 
									"ibm", 
									&datatype, 
									NULL, 0, NULL, 
            					&compcode, 
									&reason); 
pData  = malloc(datalen+1);
datalen = MQeFieldsGet( hSess, hFlds3, "ibm", 
								&datatype, 
								pData, 0, datalen, 
            				&compcode, &reason); 
pData[datalen] = '\0';
printf("Field is %s\n", pData);
 
/* Free the fields resources */
MQeFieldsFree( hSess, hFlds3, 
					&compcode, 
					&reason);
MQeFieldsFree( hSess, hFlds2, 
					&compcode, 
					&reason);

See Also
MQeFieldsGetFields

MQeFieldsPutByte, MQeFieldsPutShort, MQeFieldsPutInt, MQeFieldsPutLong, MQeFieldsPutFloat, MQeFieldsPutDouble

Description
Puts an 8, 16, 32, or 64 bit integer, float, or double into the MQeFields object.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutByte( MQEHSESS hSess, MQEHFIELDS hFlds, 
             MQECHAR * pName, MQEBYTE* aByte, 
             MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutShort( MQEHSESS hSess, MQEHFIELDS hFlds, 
              MQECHAR * pName, MQEINT16* int16Val, 
              MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutInt( MQEHSESS hSess, MQEHFIELDS hFlds, 
             MQECHAR * pName, MQEINT32* anInt, 
             MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutLong( MQEHSESS hSess, MQEHFIELDS hFlds, 
             MQECHAR * pName, MQEINT64 * pLong, 
             MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutFloat( MQEHSESS hSess, MQEHFIELDS hFlds, 
              MQECHAR * pName, MQEFLOAT* aFloat, 
              MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutDouble( MQEHSESS hSess, MQEHFIELDS hFlds, 
              MQECHAR * pName, MQEDOUBLE * pDouble, 
              MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEBYTE * aByte - input
A pointer to a byte value.

MQEINT16 * int16Val - input
A pointer to a 16 bit short integer value.

MQEINT32 *anInt - input
A pointer to a 32 bit integer value.

MQEINT64 * pLong - output
A pointer to a 64 bit integer value.

MQEFLOAT *aFloat - input
A pointer to a float value.

MQEDOUBLE * aDouble - input
A pointer to a double value.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_NOT_FOUND
Field name not found.

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
Returns '0' on success or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEBYTE  byteVal;
MQFLOAT  floatVal;
MQDOUBLE  doubleVal;
MQEINT16  int16Val;
MQEINT32  int32Val;
MQEINT64  int64Val;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
								&compcode, &reason);
 
byteVal = 0x45;
rc    = MQeFieldsPutByte( hSess, hFlds, "b", 
									&byteVal, 
               				&compcode, 
									&reason); 
floatVal  = 2.55;
rc    = MQeFieldsPutFloat( hSess, hFlds, "f", 
									&floatVal, 
               				&compcode, 
									&reason); 
doubleVal = 2.3413453231e-63;
rc    = MQeFieldsPutDouble( hSess, hFlds, "d", 
										&doubleVal, 
               					&compcode, 
										&reason); 
int16Val  = 32000;
rc    = MQeFieldsPutShort( hSess, hFlds, "sh", 
									&int16Val, 
               				&compcode, 
									&reason); 
int32Val  = 2000000000;
rc    = MQeFieldsPutInt( hSess, hFlds, "int", 
									&int32Val, 
              				&compcode, 
									&reason); 
int64Val.hi = 265;
int64Val.lo = 2000000000;
rc    = MQeFieldsPutLong( hSess, hFlds, "lg", 
									&int64Val, 
               				&compcode, 
									&reason); 

See Also

MQeFieldsPutAscii, MQeFieldsPutUnicode, MQeFieldsPutObject

Description
Put an array of MQECHAR, MQESHORT, or MQEBYTE into a single field of the MQeFields object.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutAscii( MQEHSESS hSess, 
					MQEHFIELDS hFlds, MQECHAR * pName, 
              MQECHAR * pData, MQEINT32 DataLen, 
              MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutUnicode( MQEHSESS hSess, 
					MQEHFIELDS hFlds, MQECHAR * pName, 
              MQESHORT * pData, MQEINT32 DataLen, 
              MQEINT32 * pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutObject( MQEHSESS hSess, 
					MQEHFIELDS hFlds, MQECHAR * pName, 
              MQEBYTE * pData, MQEINT32 DataLen, 
              MQEINT32 * pCompCode, MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string name of the field. A null or a zero length string is invalid.

MQECHAR * pStr - input
Field data.

MQESHORT * pStr - input
Field data.

MQEBYTE * pStr - input
Field data.

MQEINT32 DataLen - input
The maximum number of MQECHAR, MQESHORT, or MQEBYTE to copy.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
Returns '0' on success or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
static const MQECHAR * textVal = 
			"The Owl and the Pussy Cat went to sea";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEINT32  n;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
								&compcode, &reason);
rc   = MQeFieldsPutAscii( hSess, hFlds, "ibm", 
									strlen(textVal)), textVal, 
              				&compcode, &reason); 
 
/* Get the data length */
n    = MQeFieldsDataLen( hSess, hFlds, "ibm", 
								&compcode, &reason);
 
pData  = (MQEBYTE *) 
			calloc(n, , MQE_SIZEOF(datatype));
 
/* Copy out the data */
rc   = MQeFieldsGetAscii( hSess, hFlds, "ibm", 
									pData, n, 
              				&compcode, &reason);

See Also

MQeFieldsPutArrayOfByte, MQeFieldsPutArrayOfShort, MQeFieldsPutArrayOfInt, MQeFieldsPutArrayOfLong, MQeFieldsPutArrayOfFloat, MQeFieldsPutArrayOfDouble

Description
Puts an array of 8, 16, 32, or 64 bit integers, floats or doubles into a single field in an MQeFields object. Return '0' on success, '-1' on error.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutArrayOfByte( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEBYTE * pByte, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutArrayOfShort( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEINT16 * pShort, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutArrayOfInt( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
               	MQECHAR * pName, MQEINT32 * pInt, 
                	MQEINT32 n, MQEINT32 * pCompCode, 
               	MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutArrayOfLong( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEINT64 * pLong, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutArrayOfFloat( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEFLOAT * pFloat, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutArrayOfDouble( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEDOUBLE * pDouble, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEBYTE * pByte - input
An array of bytes.

MQEINT16 * pShort - input
An array of 2 byte integers.

MQEINT32 * pInt - input
An array of 4 byte integers.

MQEINT64 * pLong - output
An array of 8 byte integers.

MQEFLOAT * pFloat - input
An array of floats.

MQEDOUBLE * pDouble - input
An array of doubles.

MQEINT32 n - input
The number of elements to put. If '0', the number of elements in the field is returned.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

Return Value

MQEINT32
Returns '0' on success or '-1' on failure.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEBYTE  bytes[4];
MQEFLOAT  floats[2];
MQEDOUBLE doubles[2];
MQEINT16  shorts[2];
MQEINT32  ints[3];
MQEINT64  longs[2];
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
				&compcode, &reason);
 
*(MQEINT32 *)bytes = 0x30313233;
rc    = MQeFieldsPutByte( hSess, hFlds, 
									"b", 4, [0], 
               				&compcode, 
									&reason); 
floats[0]= 2.55;
floats[1]= 3.14;
rc    = MQeFieldsPutFloat( hSess, hFlds, 
										"f", 2, [0], 
               					&compcode, 
										&reason); 
doubles[0]= 2.3413453231e-63;
doubles[1]= 3.3413453231e-44;
rc    = MQeFieldsPut( hSess, hFlds, 
								"d", [0], 2, 
             				&compcode, 
								&reason); 
shorts[0]= 32000;
shorts[1]= 32020;
rc    = MQeFieldsPutArrayOfShort( hSess, hFlds, "sh", 
												[0], 2, 
                  						&compcode, 
												&reason); 
ints[0] = 2000100000;
ints[1] = 2000020000;
ints[2] = 2000003000;
rc    = MQeFieldsPutArrayOfInt( hSess, hFlds, 
												"int", 
												[0], 3, 
                 						&compcode, 
												&reason); 
longs[0].hi = 265;
longs[0].lo = 2000000000;
longs[1].hi = 2000000000;
longs[1].lo = 255;
rc    = MQeFieldsPutArrayOfLong( hSess, hFlds, "lg", [0], 2, 
                  &compcode, &reason); 

See Also

MQeFieldsPutShortArray, MQeFieldsPutIntArray, MQeFieldsPutLongArray, MQeFieldsPutFloatArray, MQeFieldsPutDoubleArray

Description
Puts an array of MQEINT16, MQEINT32, MQEINT64, MQEFLOAT, MQEDOUBLE, or MQEHFIELDS as an encoded array into an MQeFields object. The array elements are inserted in order as encoded fields followed by the array length. Returns the total number of fields put into the MQeFields object.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutShortArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEINT16 * pData, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutIntArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                	MQECHAR * pName, MQEINT32 * pData, 
                	MQEINT32 n, MQEINT32 * 
                	pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutLongArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                	MQECHAR * pName, MQEINT64 * pData, 
               	MQEINT32 n, MQEINT32 * 
               	pCompCode, MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutFloatArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEFLOAT * pData, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutDoubleArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEDOUBLE * pData, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutFieldsArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQEHFIELDS * pData, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT16 * pData - input
An input array.

MQEINT32 * pData - input
An input array.

MQEINT64 * pData - input
An input array.

MQEFLOAT * pData - input
An input array.

MQEDOUBLE * pData - input
An input array.

MQEHFIELDS * pData - input
An input array.

MQEINT32 n - input
The number of elements to put.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of fields successfully put.
  • On failure, returns a count of the number of fields processed including the failing field.
  • If an error occurs prior to any fields being processed, '-1' is returned.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEINT16  shorts[2];
MQEINT32  ints[3];
MQEINT64  longs[2];
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
								&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
								&compcode, &reason);
shorts[0]= 32000;
shorts[1]= 32020;
rc    = MQeFieldsPutShortArray( hSess, hFlds, 
											"boo", 2, [0], 
                 					&compcode, 
											&reason); 
ints[0] = 2000100000;
ints[1] = 2000020000;
ints[2] = 2000003000;
rc    = MQeFieldsPutIntArray( hSess, hFlds, 
											"foo", 3, [0], 
                						&compcode, 
											&reason); 
longs[0].hi = 265;
longs[0].lo = 2000000000;
longs[1].hi = 2000000000;
longs[1].lo = 255;
rc    = MQeFieldsPutLongArray( hSess, hFlds, 
											"poo", 2, [0], 
                 					&compcode, 
											&reason); 
 
memset(shorts, 0, sizeof(shorts);
memset(ints , 0, sizeof(ints);
memset(longs , 0, sizeof(longs);
 
/* Get individual data element */
MQeFieldsGetShort( hSess, hFlds, 
							"boo:0" , [0] , 
							&compcode, 
							&reason);
MQeFieldsGetShort( hSess, hFlds, 
							"boo:1" , [1] , 
							&compcode, &reason);
MQeFieldsGetInt ( hSess, hFlds, 
							"foo:0" , [0], 
							&compcode, &reason);
MQeFieldsGetInt ( hSess, hFlds, 
							"foo:1" , [1], 
							&compcode, &reason);
MQeFieldsGetInt ( hSess, hFlds, 
							"foo:2" , [2], 
							&compcode, &reason);
MQeFieldsGetLong ( hSess, hFlds, 
							"poo:0" , [0], 
							&compcode, &reason);
MQeFieldsGetLong ( hSess, hFlds, 
							"poo:1" , [1], 
							&compcode, &reason);

See Also

MQeFieldsPutAsciiArray, MQeFieldsPutUnicodeArray, MQeFieldsPutByteArray

Description
Puts a 2 dimensional array of MQEINT16, MQECHAR, or MQEBYTE as an encoded array into an MQeFields object. The array elements are inserted in order as encoded fields, followed by the array length. Returns the total number of fields added to the MQeFields object.

Syntax
#include <hmq.h> 
#include <hmqHelper.h> 
MQEINT32 MQeFieldsPutAsciiArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                 MQECHAR * pName, MQECHAR * ppData[], 
                 MQEINT32 pDataLen[], 
						MQEINT32 srcOff, 
                 MQEINT32 n, MQEINT32 * pCompCode, 
                 MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutUnicodeArray( MQEHSESS hSess, 
							MQEHFIELDS hFlds, 
                 	MQECHAR * pName, MQEINT16 * ppData[], 
                 	MQEINT32 pDataLen[], 
							MQEINT32 srcOff, 
                  	MQEINT32 n, MQEINT32 * pCompCode, 
                  	MQEINT32 * pReason) 
 
MQEINT32 MQeFieldsPutByteArray( MQEHSESS hSess, 
						MQEHFIELDS hFlds, 
                	MQECHAR * pName, MQEBYTE * ppData[], 
                	MQEINT32 pDataLen[], 
						MQEINT32 srcOff, 
                	MQEINT32 n, MQEINT32 * pCompCode, 
                	MQEINT32 * pReason)

Parameters

MQEHSESS hSess - input
The session handle, returned by MQeInitialize.

MQEHFIELDS hFlds - input
A handle to an MQeFields object.

MQECHAR * pName - input
A null terminated string containing the name of the field. A null or a zero length string is invalid.

MQEINT32 n - input
The number of elements to put. If '0', the number of elements in the field is returned.

MQECHAR * ppData[] - input
An array of MQECHAR arrays.

MQEINT16 * ppData[] - input
An array of MQESHORT arrays.

MQEBYTE * ppData[] - input
An array of MQEBYTE.

MQEINT32 pDataLen[] - input
An array of lengths of each data element, corresponding to each element of ppData[] .

MQEINT32 srcOff - input
The starting index from which to copy the array element.

MQEINT32 * pCompCode - output
MQECC_OK, MQECC_WARNING or MQECC_ERROR.

MQEINT32 * pReason - output
If the returned *pCompCode equals MQECC_ERROR, *pReason may have any of the following values:

MQE_EXCEPT_INVALID_HANDLE

MQE_EXCEPT_INVALID_ARGUMENT

MQE_EXCEPT_ALLOCATION_FAILED

Return Value

MQEINT32
  • On success, returns the number of fields successfully put.
  • On failure, returns a count of the number of fields processed including the failing field.
  • If an error occurs prior to any fields being processed, '-1' is returned.

Example
#include <hmq.h>
#include <hmqHelper.h>
static MQECHAR const * FieldsType = 
			"com.ibm.mqe.MQeFields";
static const char * textArray[] = 
        { "The Owl and the Pussy Cat went to sea",
         "Here we go round the Mulberry bush",
         "Jack and Jill went up the hill" };
MQEHSESS  hSess;
MQEINT32  compcode;
MQEINT32  reason;
MQEHFIELDS hFlds;
MQEINT32  pStrLen[3], n, *pStrLen2;
MQEBYTE * pData;
MQEINT32  rc;
 
hSess  = MQeInitialize("MyAppsName", 
									&compcode, &reason);
hFlds  = MQeFieldsAlloc( hSess, FieldsType, 
									&compcode, &reason);
 
pStrLen[0] = strlen(textArray[0]);
pStrLen[1] = strlen(textArray[1]);
pStrLen[2] = strlen(textArray[2]);
rc = MQeFieldsPutAsciiArray( hSess, hFlds, "ibm", 
										textArray, pStrLen, 3, 
              					&compcode, &reason); 
 
/* 1. Get number of elements */
n = MQeFieldsGetAsciiArray( hSess, hFlds, 
										"ibm", NULL,
										NULL, 0, 0, 
              					&compcode, &reason);
 
/* Get space for array of string length */
pStrLen2 = (MQEINT32 *) malloc(n * sizeof(MQEINT32));
memset(pStrLen2, 0, n * sizeof(MQEINT32));
 
/* 2. Get array of string length */
n = MQeFieldsGetAsciiArray( hSess, hFlds, 
										"ibm", NULL, 
										pStrLen2, 0, n, 
              					&compcode, &reason);
 
/* Get space for array of string */
for (i=0; i<n; i++) {
  pStr[i] = 
			(MQECHAR *) malloc(pStrLen[j]+1);
  memset(pStr[i], 0, 
				pStrLen[j]+1);
}
 
/* 3. Get array of strings */
n = MQeFieldsGetAsciiArray( hSess, hFlds, 
										"ibm", pStr, 
										pStrLen2, 0, n, 
              					&compcode, &reason);
 

See Also


© IBM Corporation 2002. All Rights Reserved