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


© IBM Corporation 2002. All Rights Reserved