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


© IBM Corporation 2002. All Rights Reserved