Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_Vector.h File Reference


Detailed Description

The implementation of a simple vector (ordered collection).

This item represents a simple implementation of a vector (ordered collection). The vector can store only void* data or data of type MQEHANDLE.

If the vector is returned from mqeVector_newFields() or mqeVector_newStrings() and contains MQeFieldsHndl or MQeStringHndl items then upon freeing the vector (with mqeVector_free()) all the contents are removed and freed. This is also the case with vectors returned from most other APIs e.g. mqeFields_fields().

However, if the user invokes mqeVector_new() to instantiate a vector, the system does NOT attempt to manage the memory indicated by the vector pointers - in this case, it is the responsibility of the USER to remove and free the vector elements prior to calling mqeVector_free().

Reference to elements can be made by 'index' This is the position in the (logical) list. Indexes are zero based (-1 < index < size).


Functions

MQERETURN mqeVector_newStrings (MQeExceptBlock *pExceptBlock, MQeVectorHndl *phVector, MQEINT32 initialSize)
 create a new vector to contain elements of type MQeStringHndl.

MQERETURN mqeVector_newFields (MQeExceptBlock *pExceptBlock, MQeVectorHndl *phVector, MQEINT32 initialSize)
 create a new vector to contain elements of type MQeFieldsHndl.

MQERETURN mqeVector_new (MQeExceptBlock *pExceptBlock, MQeVectorHndl *phVector, MQEINT32 initialSize)
 create a new vector.

MQERETURN mqeVector_free (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock)
 free a vector.

MQERETURN mqeVector_append (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock, MQEVOID *pObject)
 append an entry to the vector.

MQERETURN mqeVector_insertAt (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock, MQEVOID *pObject, MQEINT32 insertAt)
 insert an entry into the vector.

MQERETURN mqeVector_removeAt (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock, MQEVOID **ppObject, MQEINT32 removeAt)
 remove an entry from the vector and return the data pointer at the location.

MQERETURN mqeVector_indexOf (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock, MQEVOID *pObject, MQeVector_CompareFunc pFunction, MQEINT32 *pIndex)
 find index of entry.

MQERETURN mqeVector_find (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock, MQEVOID *pFind, MQeVector_CompareFunc pFunction, MQEVOID **ppObject)
 find an entry. This method returns a pointer to the first element in the array that tests equal.

MQERETURN mqeVector_entryAt (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock, MQEVOID **ppObject, MQEINT32 index)
 find entry at given index.

MQERETURN mqeVector_size (MQeVectorHndl hVector, MQeExceptBlock *pExceptBlock, MQEINT32 *pSize)
 return size of vector.


Function Documentation

MQERETURN mqeVector_newStrings MQeExceptBlock   pExceptBlock,
MQeVectorHndl *    phVector,
MQEINT32    initialSize
 

create a new vector to contain elements of type MQeStringHndl.

Parameters:
pExceptBlock  [in/out] Exception block to be filled in case of error
phVector  [out] Pointer to a location to place the handle to the new vector
initialSize  [in] Number of elements initially allocated
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_ALLOCATION_FAIL  memory allocation failed internally
Note:
All items in the vector are removed and freed by the system when mqeVector_free() is invoked

MQERETURN mqeVector_newFields MQeExceptBlock   pExceptBlock,
MQeVectorHndl *    phVector,
MQEINT32    initialSize
 

create a new vector to contain elements of type MQeFieldsHndl.

Parameters:
pExceptBlock  [in/out] Exception block to be filled in case of error
phVector  [out] Pointer to a location to place the handle to the new vector
initialSize  [in] Number of elements initially allocated
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_ALLOCATION_FAIL  memory allocation failed internally
Note:
All items in the vector are removed and freed by the system when mqeVector_free() is invoked

MQERETURN mqeVector_new MQeExceptBlock   pExceptBlock,
MQeVectorHndl *    phVector,
MQEINT32    initialSize
 

create a new vector.

Parameters:
pExceptBlock  [in/out] Exception block to be filled in case of error
phVector  [out] Pointer to a location to place the handle to the new vector
initialSize  [in] Number of elements initially allocated
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_ALLOCATION_FAIL  memory allocation failed internally
Warning:
It is the responsibility of the user to remove the elements of any vector created using this function and to free memory associated with them prior to calling mqeVector_free()

MQERETURN mqeVector_free MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock
 

free a vector.

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied
Warning:
Does NOT remove, or free memory for, items in the vector if the vector was created with mqeVector_new()

MQERETURN mqeVector_append MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock,
MQEVOID *    pObject
 

append an entry to the vector.

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
pObject  [in] Pointer to append to the vector
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied
MQERETURN_ALLOCATION_FAIL 
  • memory allocation failed internally

MQERETURN mqeVector_insertAt MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock,
MQEVOID *    pObject,
MQEINT32    insertAt
 

insert an entry into the vector.

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
pObject  [in] Pointer to item to be inserted into the vector
insertAt  [in] Integer value of position to insert at. This value must be greater than -1 and less than or equal to the size of the vector. If the value is not in the specified range then the call fails with reason code MQEREASON_VALUE_OUT_OF_RANGE
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied
  • MQEREASON_VALUE_OUT_OF_RANGE the supplied array index was greater than the number of elements or less than zero
MQERETURN_ALLOCATION_FAIL 
  • memory allocation failed internally

MQERETURN mqeVector_removeAt MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock,
MQEVOID **    ppObject,
MQEINT32    removeAt
 

remove an entry from the vector and return the data pointer at the location.

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
ppObject  [out] Pointer to location to store the pointer being removed (NULL If this is not required).
removeAt  [in] Integer value of position to remove from. This value must be greater than -1 and less than the size of the vector. If the value is not in the specified range then the call fails with reason code MQEREASON_VALUE_OUT_OF_RANGE
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied
  • MQEREASON_VALUE_OUT_OF_RANGE the supplied array index was greater than or equal to the number of elements or less than zero

MQERETURN mqeVector_indexOf MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock,
MQEVOID *    pObject,
MQeVector_CompareFunc    pFunction,
MQEINT32 *    pIndex
 

find index of entry.

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
pObject  [in] Pointer to find in vector
pFunction  [in] Pointer to a function that takes two void pointers and returns an int. The first void pointer is the user's data (pObject) and the second is a pointer to an array element. If the function returns 0 then the element is considered 'found'. If this parameter is NULL the default comparison is used. The default comparison simply compares the address of the element with the user-supplied pointer (pObject).
pIndex  [out] Pointer to location to store the integer index of pObject. The index value is set to the constant VECTOR_ENTRY_NOT_FOUND if pObject is not found in the vector
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied

MQERETURN mqeVector_find MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock,
MQEVOID *    pFind,
MQeVector_CompareFunc    pFunction,
MQEVOID **    ppObject
 

find an entry. This method returns a pointer to the first element in the array that tests equal.

The equality test is the invocation of the supplied function with the user's data (pFind) as the first parameter, and each element in the array as the second parameter. Equality is defined as the return of zero from this function.

If the element is not found then the pointer returned is null

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
pFind  [in] Pointer to find in dynamic array
pFunction  [in] Pointer to a function that takes two void pointers and returns an int. The first void pointer is the users data (pObject) and the second is a pointer to an array element. If the function returns 0 then the element is considered 'found'. If this parameter is NULL the default comparison is used. The default comparison simply compares the address of the element with the user-supplied pointer (pFind).
ppObject  [out] Pointer to location at which to store pointer to found object
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied

MQERETURN mqeVector_entryAt MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock,
MQEVOID **    ppObject,
MQEINT32    index
 

find entry at given index.

If index is out of range then no change is made to the output parameter.

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
ppObject  [out] Pointer to location at which to store the pointer being found at index.
index  [in] Integer value of position of data. This value must be greater than -1 and less than the size of the vector. If the value is not in the specified range then the call fails with reason code MQEREASON_VALUE_OUT_OF_RANGE
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied
  • MQEREASON_VALUE_OUT_OF_RANGE the supplied array index was greater than or equal to the number of elements or less than zero

MQERETURN mqeVector_size MQeVectorHndl    hVector,
MQeExceptBlock   pExceptBlock,
MQEINT32 *    pSize
 

return size of vector.

Parameters:
hVector  [in] Handle of vector addressed
pExceptBlock  [in/out] Exception block to be filled in case of error
pSize  [out] Pointer to location at which to store the integer size
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_NULL_POINTER a null pointer was passed as a parameter
  • MQEREASON_INVALID_SIGNATURE the wrong type (of handle) was supplied


Generated Thu Aug 11 23:27:14 2005 for Websphere MQ Everyplace for Multiplatforms C Programming Reference