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


© IBM Corporation 2002. All Rights Reserved