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


© IBM Corporation 2002. All Rights Reserved