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

MQe_QueueManager.h File Reference


Detailed Description

MQeQueueManager handle.

The queue manager is the focal point of the Websphere MQ Everyplace Native C Client system. It provides


Data Structures

struct  MQeQMgrQParms
 Configuration Structure for creating a QueueManager Queue. More...

struct  MQeQueueManagerParms
 Configuration Structure for processing a QueueManager. More...


Defines

#define QMGR_VERSION
 QueueManager structure version.

#define QMGR_INIT_VAL
 initial value for the Queue Manager parameter structure

#define SET_QMGR_INIT_VAL(qmParms)
#define QMGR_DESC_OP
 bit flag for the structure description field

#define QMGR_RULES_OP
 bit flag for the structure QMgr rules field

#define QMGR_TIMEOUT_OP
 bit flag for the structure timeout field

#define QMGR_Q_STORE_OP
 bit flag for the structure queue store field

#define QMGR_QUEUES_OP
 bit flag for the structure queues field

#define QMGR_CONNECTIONS_OP
 bit flag for the structure connections field

#define QMGR_BRIDGE_CAPABLE_OP
 bit flag for the structure bridge capable field

#define QMGR_ALIASES_OP
 bit flag for the structure aliases field

#define QMGR_CHANNEL_ATTRIBUTE_OP
 bit flag for the structure aliases field

#define QMGR_VERSION_OP
 bit flag for the structure version field

#define QMGR_ALL_OP
 mask for all bit flags for the structure


Typedefs

typedef enum MQeQueueType_enm MQeQueueType
 Used to identify the type of queue in admininstration operations.

typedef MQeQMgrQParms MQeQMgrQParms
 Configuration Structure for creating a QueueManager Queue.

typedef MQeQueueManagerParms MQeQueueManagerParms
 Configuration Structure for processing a QueueManager.


Enumerations

enum  MQeQueueType_enm {
  MQEQUEUETYPE_UNKNOWN,
  MQEQUEUETYPE_LOCAL,
  MQEQUEUETYPE_ADMIN,
  MQEQUEUETYPE_REMOTE_SYNC,
  MQEQUEUETYPE_REMOTE_ASYNC,
  MQEQUEUETYPE_HOME_SERVER,
  MQEQUEUETYPE_REMOTE_GENERIC,
  MQEQUEUETYPE_STORE_AND_FORWARD
}
 Used to identify the type of queue in admininstration operations. More...


Functions

MQERETURN mqeQueueManager_new (MQeExceptBlock *pExceptBlock, MQeQueueManagerHndl *phQMgr, MQeStringHndl hQmgrName, MQeQueueManagerParms *pQMParms, MQeRegistryParms *pRegParms)
 Creates a new QueueManager form an existing registry.

MQERETURN mqeQueueManager_free (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock)
 Frees the queue manager pointed to by pQMgr.

MQERETURN mqeQueueManager_start (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock)
 This starts the QueueManager running.

MQERETURN mqeQueueManager_browseMessages (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQeVectorHndl *phMsgs, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter, MQeFieldsAttrHndl hAttribute, MQEBOOL justUID)
 Returns a vector of the messages (or just their UIDs) available on a specified queue.

MQERETURN mqeQueueManager_browseMessagesAndLock (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQeVectorHndl *phMsgs, MQEINT64 *pLockID, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter, MQeFieldsAttrHndl hAttribute, MQEINT64 confirmId, MQEBOOL justUID)
 Returns a Vector of the messages (or just their UIDs) available on a specified queue.

MQERETURN mqeQueueManager_checkActive (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQEBOOL *pIsActive)
 Checks if queue manager is active.

MQERETURN mqeQueueManager_stop (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock)
 Stops a QueueManager.

MQERETURN mqeQueueManager_getCurrentQueueManager (MQeExceptBlock *pExceptBlock, MQeQueueManagerHndl *phQueueManager)
 Returns current QueueManager.

MQERETURN mqeQueueManager_confirmGetMessage (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter)
 Confirms the successful receipt of a message.

MQERETURN mqeQueueManager_confirmPutMessage (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter)
 Confirms a previous mqeQueueManager_putMessage_ operation.

MQERETURN mqeQueueManager_deleteMessage (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter)
 Deletes a message from a queue.

MQERETURN mqeQueueManager_getMessage (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQeFieldsHndl *phMsg, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter, MQeFieldsAttrHndl hAttribute, MQEINT64 confirmId)
 Returns an available message from the specified queue.

MQERETURN mqeQueueManager_getName (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQeStringHndl *phQMgrName)
 Returns Queue manager name.

MQERETURN mqeQueueManager_putMessage (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQeFieldsHndl hMsg, MQeFieldsAttrHndl hAttribute, MQEINT64 confirmId)
 Puts a message onto a queue.

MQERETURN mqeQueueManager_triggerTransmission (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock)
 This function causes an attempt to transmit any pending messages.

MQERETURN mqeQueueManager_channelTimeout (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock)
 This function causes a check to be made on all channels for timeout.

MQERETURN mqeQueueManager_undo (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQEINT64 confirmId)
 Undoes a put, get,or browseAndLock action during which an error occurs.

MQERETURN mqeQueueManager_unlockMessage (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter)
 Unlocks a message that has been previously locked.


Define Documentation

#define QMGR_INIT_VAL
 

initial value for the Queue Manager parameter structure

 
        {QMGR_VERSION, 0, NULL, NULL, 0, NULL, NULL, NULL, MQE_FALSE}
        
 

#define SET_QMGR_INIT_VAL qmParms   
 

Is this QueueManager bridge capable?


Typedef Documentation

typedef struct MQeQMgrQParms MQeQMgrQParms
 

Configuration Structure for creating a QueueManager Queue.

A structure which contains the information that is required to process a Queue Manager Queue.

typedef struct MQeQueueManagerParms MQeQueueManagerParms
 

Configuration Structure for processing a QueueManager.

A structure which contains the information that is required to process a Queue Manager. It needs to contain information on the registry and default QueueManager QueueStore.


Enumeration Type Documentation

enum MQeQueueType_enm
 

Used to identify the type of queue in admininstration operations.

Enumeration values:
MQEQUEUETYPE_UNKNOWN  Unknown type
MQEQUEUETYPE_LOCAL  Local Queue
MQEQUEUETYPE_ADMIN  Admin Queue
MQEQUEUETYPE_REMOTE_SYNC  Remote Synchronous Queue
MQEQUEUETYPE_REMOTE_ASYNC  Remote Asynchronous Queue
MQEQUEUETYPE_HOME_SERVER  Home Server Queue
MQEQUEUETYPE_REMOTE_GENERIC  Either a Sync or Async Remote Queue
MQEQUEUETYPE_STORE_AND_FORWARD  Store and Forward Queue


Function Documentation

MQERETURN mqeQueueManager_new MQeExceptBlock   pExceptBlock,
MQeQueueManagerHndl *    phQMgr,
MQeStringHndl    hQmgrName,
MQeQueueManagerParms   pQMParms,
MQeRegistryParms   pRegParms
 

Creates a new QueueManager form an existing registry.

This will create a new QueueManager based on the information in an existing registry (the information required to do this is supplied in the MQeRegistryParms). Once this has been created, it can be started using the mqeQueueManager_start() method.

If the registry does not exist, then an error will be generated. To create a brand new QueueManager use the mqeAdministrator_QueueManager_create() method.

Parameters:
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phQMgr  [out] Pointer to the output handle.
hQmgrName  [in] QueueManager name
pQMParms  [in] Pointer to the QueueManager parameter structure
pRegParms  [in] Pointer to the Registry parameter structure
Return values:
MQERETURN_OK  Completed Succesfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_REGISTRY_NOT_DEFINED_ALREADY Registry not defined already
Warning:
Users are expected to use mqeQueueManager_free() to free the handle returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeQueueManager_free MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

Frees the queue manager pointed to by pQMgr.

Parameters:
hQMgr  [in] the queue manager to be freed.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeQueueManager_start MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

This starts the QueueManager running.

Once this call has been made messaging operations can begin.

This call should be made either after creating a QueueManager from an existing registry or when re-establishing a QueueManager from an existing registry.

Parameters:
hQMgr  [in] QueueManager Handle
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeQueueManager_browseMessages MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeVectorHndl *    phMsgs,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter,
MQeFieldsAttrHndl    hAttribute,
MQEBOOL    justUID
 

Returns a vector of the messages (or just their UIDs) available on a specified queue.

Returns a vector of the messages available on a specified queue. The messages are not deleted from the queue. The queue can belong to a local or remote queue manager.

A filter can be specified, which consists of message fields, so that only messages that have matching fields are returned.

Returning a vector of messages in their entirety can be expensive in terms of system resources, so if the justUID parameter is set to true just the unique ids of the messages that match the filter are returned. These unique ids can then be used as filters to get/delete/browse the entire messages on the target queue.

Specifying an MQeAttribute handle allows browsing of messages that have message-level security defined with a matching attribute. When an attribute is specified in a get/browse message call, it is the caller's responsibilty to make sure that the specified attribute is appropriate for decoding the message/(ALL) messages. That includes the type of attribute, type of key, value of key seed, type of authenticator, type of cryptor, and type of compressor. Note that problems may arise if the attribute supplied is not appropriate for decoding all messages returned by the operation. However, if you omit compressor and cryptor when creating an MQeMsgAttr, the system will automatically load the appropriate ones for the operation.

The messages returned in the enumeration are still visible to other Websphere MQ Everyplace applications. Therefore, when performing subsequent operations on the messages contained in the array, the application should be aware that it is possible for another application to have processed these messages in the time since the array was returned. To lock the messages contained in the array, therefore preventing other applications from processing them, use the mqeQueueManager_browseMessagesAndLock() function.

As the Vector contains MQeFieldsHndl, freeing the Vector will automatically free any fields objects it contains at the point of freeing

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phMsgs  [out] Pointer to vector containing all the messages.
hQMgrName  [in] name of the queue manager from which a user wishes to receive messages.
hQName  [in] name of the queue from which a user wishes to receive messages.
hFilter  [in] a filter Fields handle containing message fields. A value of null means that a user wishes to receive all messages on the queue. Specifying an MQeFields handle containing message fields means that the the user is only interested in messages whose fields match those contained in the filter.
hAttribute  [in] an MQeAttribute used to provide message-level security.
justUID  [in] an MQEBOOL value denoting whether to return the entire message, or just unique id.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
Warning:
Any messages that are removed from the enumeratiom must be freed using the appropriate message free function. Remember also to use the message enumeration free function to free the actual enumeration.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_browseMessagesAndLock MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeVectorHndl *    phMsgs,
MQEINT64 *    pLockID,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter,
MQeFieldsAttrHndl    hAttribute,
MQEINT64    confirmId,
MQEBOOL    justUID
 

Returns a Vector of the messages (or just their UIDs) available on a specified queue.

The messages are not deleted from the queue. The queue may belong to a local or remote queue manager.

A filter can be specified, which consists of message fields, so that only messages that have matching fields are returned.

Any messages that are returned by this function are also locked on the queue. This means that these messages still exist on the queue, but they are not visible to any subsequent operations, until they are unlocked.

A lock id is returned as part of this the browse call. The lock ID allows operations to be performed on locked messages so long as it is specified as part of the message filter that is passed into that operation.

Lock ids are unique, so every browse and lock operation generates a different id. The lock id applies to all the messages that are returned by the browse operation.

The operations that can be performed on a locked message are: mqeQueueManager_getMessage(), mqeQueueManager_deleteMessage(), mqeQueueManager_unlockMessage()

Returning an enumeration of messages in their entirety can be expensive in terms of system resources, so if the justUID parameter is set to true just the unique ids of the messages that match the filter are returned. These unique ids can then be used as filters to get/delete/browse the entire messages on the target queue.

Specifying an MQeAttribute handle allows browsing of messages that have message-level security defined with a matching attribute. When an attribute is specified in a get/browse message call, it is the caller's responsibilty to make sure that the specified attribute is appropriate for decoding the message/(ALL) messages. That includes the type of attribute, type of key, value of key seed, type of authenticator, type of cryptor, and type of compressor. Note that problems may arise if the attribute supplied is not appropriate for decoding all messages returned by the operation. However, if you omit compressor and cryptor when creating an MQeMsgAttr, the system will automatically load the appropriate ones for the operation.

The confirmID is used in the event of an error while executing this command. The error could occur before the lock id is returned to the application and yet leave the messages in a locked state on the target queue. Passing the same confirm id used on this method to the undo method restores the messages to their previous state. It is recommended that a unique value be used for each browse and lock operation. A unique value can be generated using the MQe_uniqueValue().

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phMsgs  [out] Pointer to output Vector.
pLockID  ]out] Pointer to lock ID generated by the operation
hQMgrName  [in] name of the queue manager from which a user wishes to receive messages.
hQName  [in] name of the queue from which a user wishes to receive messages.
hFilter  [in] a filter Fields handle containing message fields. A value of null means that a user wishes to receive all messages on the queue. Specifying an MQeFields handle containing message fields means that the the user is only interested in messages whose fields match those contained in the filter.
hAttribute  [in] an MQeAttribute used to provide message-level security.
confirmId  [in] an MQEINT64 value that is used in the event of an error.
justUID  [in] an MQEBOOL value denoting whether to return the entire message, or just unique id.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
Warning:
Any messages that are removed from the vector must be freed using the appropriate message free function. Remember also to use the message enumeration free function to free the actual enumeration.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_checkActive MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQEBOOL *    pIsActive
 

Checks if queue manager is active.

Parameters:
hQMgr  [in] the MQeQMgr to be examined.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
pIsActive  [out] Pointer to output variable. MQE_TRUE if active, MQE_FALSE otherwise
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeQueueManager_stop MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

Stops a QueueManager.

This will stop a QueueManager - it will no longer be able to accept any messages

Parameters:
hQMgr  [in] Queue Manager Hndl
pExceptBlock  [in/out] Point to a pre-allocated MQeExceptBlock structure.
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeQueueManager_getCurrentQueueManager MQeExceptBlock   pExceptBlock,
MQeQueueManagerHndl *    phQueueManager
 

Returns current QueueManager.

Parameters:
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phQueueManager  [out] Pointer to the queueManager handle.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeQueueManager_confirmGetMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter
 

Confirms the successful receipt of a message.

Confirms the successful receipt of a message that was retrieved from a queue by a previous mqeQueueManager_getMessage operation. The message remains locked on the target queue until the confirm flow is received.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hQMgrName  [in] name of the queue manager from which a user wishes to confirm a message.
hQName  [in] name of the queue on which a user wishes to confirm a message.
hFilter  [in] a filter Fields handle containing the message's unique ID.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
hFilter must contain the message's unique ID.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_confirmPutMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter
 

Confirms a previous mqeQueueManager_putMessage_ operation.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hQMgrName  [in] Handle of the name of the queue manager on which a user wishes to confirm a message.
hQName  [in] Handle of the name of queue on which the message is held.
hFilter  [in] a filter Fields handle containing the message's unique ID.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
hFilter must contain the message's unique ID.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_deleteMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter
 

Deletes a message from a queue.

This function does not return the message to the application that called it.

Only one message can be deleted per operation and the unique id(timestamp and origin queue manager name) of the message must always be supplied. The queue may belong to a local or remote Websphere MQ Everyplace queue manager. Messages that have been locked by a previous operation (browse for example) can be deleted by including a valid lock id in the message filter. If the message is not available, an error is raised.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hQMgrName  [in] Handle of the name of the queue manager from which a user wishes to delete a message.
hQName  [in] Handle of the name of the queue from which a user wishes to delete a message.
hFilter  [in] a filter Fields handle containing the message's unique ID.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
hFilter must contain the message's unique ID.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_getMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeFieldsHndl *    phMsg,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter,
MQeFieldsAttrHndl    hAttribute,
MQEINT64    confirmId
 

Returns an available message from the specified queue.

Returns an available message from the specified queue and the message is removed from the queue.

The queue can belong to a local or a remote Websphere MQ Everyplace queue manager. If no message filter is specified, the first available message on the queue is returned. If a message filter is specified, the first available message that matches the filter is returned.

Messages that have been locked by a previous browse operation can be retrieved by including, in the message filter, the lock id that was used to lock the message.

If no message is available, an error is raised.

The use of assured message delivery is dependant upon the value of the confirmId parameter. Passing a nonzero confirm Id returns the message as normal, but the message is locked and is not removed from the target queue until a subsequent confirm is received. A confirm can be issued using the mqeQueueManager_confirmGetMessage() method. Passing a confirm Id of zero returns the message and removes it from the target queue - however, the message delivery is not assured in this case.

The confirmId parameter is also used in the event of an error when executing this command. A failure could occur before the message is returned to the application and yet leave the message in a locked state on the target queue. Passing the same confirm id used for the get operation to the undo call restores the message to its previous state. It is recommended that a unique value be used for each get operation. A unique value can be generated using the mqe_uniqueValue() method.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phMsg  [out] Pointer to output message.
hQMgrName  [int] Handle of the name of the queue manager from which a user wishes to receive a message.
hQName  [in] Pointer to the name of the queue from which a user wishes to receive a message.
hFilter  [in] a filter Fields handle containing message fields. A value of null means that a user wishes to receive any message on the queue. Specifying an MQeFields handle containing message fields means that the the user is only interested in messages whose fields match those contained in the filter.
hAttribute  [in] an MQeAttribute used to provide message-level security.
confirmId  [in] an MQEINT64 value that is used in the event of an error.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_getName MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeStringHndl *    phQMgrName
 

Returns Queue manager name.

Parameters:
hQMgr  [in] the MQeQMgr to be examined.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phQMgrName  [out] Pointer to the handle of name string.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeQueueManager_putMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQeFieldsHndl    hMsg,
MQeFieldsAttrHndl    hAttribute,
MQEINT64    confirmId
 

Puts a message onto a queue.

This function places the specified message onto the specified queue. This queue may belong to a local or a remote queue manager.

Puts to remote queues can occur immediately, or at some later time depending upon how the remote queue is defined on the local queue manager.

If a remote queue is defined as synchronous, the transmission of the message over the network occurs immediately. If a remote queue is defined as asynchronous, the message is stored within the local queue manager. The message remains there until the queue manager rules decide that it is time to transmit any pending messages or the queue manager is triggered through the mqeQueueManager_triggerTransmission() method.

The assured delivery of the message is dependent on the value of the confirmId parameter. Passing a nonzero value transmits the message as normal, but the message is locked on the target queue until a subsequent confirm is received. Passing a value of zero transmits the message without the need for a subsequent confirm, however the delivery of the message is not assured.

The confirmId is also used in the event of an error during the execution of this command. Passing the same confirm id used for the put operation to the undo method removes the unconfirmed message from the target queue. It is recommended that a unique value be used for each put operation. A unique value can be generated using the mqe_uniqueValue() method.

A message can be protected using message-level security. The security is defined by providing an MQeAttribute_ handle, or one of its descendants. The attribute can be attached to the message prior to any put message request, or the attribute parameter can be used to specify the message-level security to be used. If the attribute parameter is not null, the value overrides any attribute attached to the message prior to the put message request. If the attribute parameter is null, it has no effect on the sending of the message.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hQMgrName  [in] name of the queue manager to which a user wishes to put a message.
hQName  [in] name of the queue to which a user wishes to put a message.
hMsg  [in] the message to be put on to a queue.
hAttribute  [in] an MQeAttribute used to provide message-level security.
confirmId  [in] an MQEINT64 value that is used in the event of an error.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
Return values:
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_triggerTransmission MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

This function causes an attempt to transmit any pending messages.

Pending messages are messages awaiting transmission to remote queue managers. This method allows transmission of pending messages at a time convenient to the application. In addition, this method triggers any home server queues that are defined. These queues attempt to collect messages from their home servers.

Note:
If there is a failure to transmit on one queue, transmission will continue on other queues. Information on this failure will be put out to the trace file.
Only if a serious internal error occurs will this call fail.
Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).

MQERETURN mqeQueueManager_channelTimeout MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

This function causes a check to be made on all channels for timeout.

Each channel is checked to see if the time since the last write or read is greater than the timeout value. If it is, the channel is closed.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).

MQERETURN mqeQueueManager_undo MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQEINT64    confirmId
 

Undoes a put, get,or browseAndLock action during which an error occurs.

It is possible that an error could leave messages in an unconfirmed or locked state on the target queue. This method resets the messages to the state (either locked or unlocked) that they were in prior to the failed operation, or in the case of an unconfirmed put operation, the messages are deleted. To reset a message, it is necessary to supply the confirmId that was used in the failed operation. It is recommended that confirm ids are unique for each message operation. A unique value can be generated using the mqe_uniqueValue() method.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hQMgrName  [in] name of the queue manager on which a user wishes to undo an action.
hQName  [in] name of the queue on which a user wishes to undo an action.
confirmId  [in] an MQEINT64 value that is the same as the confirm id used on the failed operation.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES

MQERETURN mqeQueueManager_unlockMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter
 

Unlocks a message that has been previously locked.

This function makes a message visible once again to all applications. Only one message can be unlocked at a time and both the unique id (timestamp and origin queue manager name) and lock id of the message must be supplied. The queue may belong to a local or remote queue manager. If the message is not available, an exception is thrown. This method would typically be used in conjunction with the mqeQueueManager_browseMsgAndLock() method.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hQMgrName  [in] Pointer to the name of the queue manager on which a user wishes to unlock a message.
hQName  [in] Pointer to the name of the queue on which a user wishes to unlock a message.
hFilter  [in] a filter Fields containing the message's unique ID and lock ID.
Precondition:
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName and hQMgrName must not be NULL.
(*hFilter) must contain the message's unique ID and lock ID.
Return values:
MQERETURN_QUEUE_MANAGER_ERROR 
  • MQEREASON_UNKNOWN_QUEUE_MANAGER
  • MQEREASON_UNKNOWN_QUEUE
  • MQEREASON_NO_QMGR_ALIASES


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