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

MQe_QueueManager.h File Reference

MQeQueueManager handle. More...


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.


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)
 This function constructs/activates a queue manager.

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

MQERETURN mqeQueueManager_activate (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeFieldsHndl hStartUpParams)
 This function activates a WMQe queue manager.

MQERETURN mqeQueueManager_addMessageListener (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeMessageListenerHndl hListener, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter)
 Adds a subscription to MQSeries Everyplace Message Events.

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

MQERETURN mqeQueueManager_browseMessagesAndLock (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQeMessageEnumerationHndl *phMsgs, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter, MQeAttributeHndl hAttribute, MQEINT64 confirmId, MQEBOOL justUID)
 Returns an enumeration 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_close (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock)
 Closes down the queue manager pointed by pQMgr.

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, MQeMsgHndl *phMsgs, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter, MQeAttributeHndl 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_getReference (MQeExceptBlock *pExceptBlock, MQeQueueManagerHndl *phQMgrRef, MQECONST MQeStringHndl hQMgrName)
 Reference to a named queue Manager.

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

MQERETURN mqeQueueManager_removeMessageListener (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQECONST MQeMessageListenerHndl hListener, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter)
 Removes a message listener.

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.

MQERETURN mqeQueueManager_waitForMessage (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQeMsgHndl *phMsgs, MQECONST MQeStringHndl hQMgrName, MQECONST MQeStringHndl hQName, MQECONST MQeFieldsHndl hFilter, MQeAttributeHndl hAttribute, MQEINT64 confirmId, MQEINT32 millisecs)
 Waits for message arriving on queue.

MQERETURN mqeQueueManager_setGlobalHashtable (MQeQueueManagerHndl hQMgr, MQeExceptBlock *pExceptBlock, MQeHashtableHndl hHashTable)
 Set Channelmanager GlobalHashTable reference.


Detailed Description

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


Typedef Documentation

typedef struct MQeQMgrQParms MQeQMgrQParms
 

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

typedef struct MQeQueueManagerParms MQeQueueManagerParms
 

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
 

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
 

If hStartUpParams (handle for the queue manager startup parameters) is not NULL, (*hStartUpParams) is used to activate the created queue manager. by calling mqeQueueManager_activate() internally. Otherwise, it just creates a default queue manager. The mqeQueueManager_activate() function must be called later to initialize and start the queue manager.

Before starting a queue manager all required MQSeries Everyplace aliases must have been added. Refer to the Programming Guide for details of how to do this.

Parameters:
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phQMgr  [out] Pointer to the output handle.
Precondition:
phQMgr must not be NULL.
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
Returns :
Constructs a new MQeQueueManager handle and returns this via phQMgr
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_QMGR_ACTIVATED  Queue manager already activate
MQERETURN_J_QMGR_ALREADY_EXISTS  Queue manager already exists
MQERETURN_J_QMGR_INVALID_Q_NAME  Invalid queue manager name
MQERETURN_J_QMGR_NOT_CONFIGURED  Queue manager not configured
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
 

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_activate MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeFieldsHndl    hStartUpParams
 

Before starting a queue manager, all required WMQE aliases must have already been added.

Parameters
The startup parameters must contain two sections. MQE_QUEUE_MANAGER_SECTION that sets up the queue Manager, and MQE_REGISTRY_SECTION that sets up the registry.
MQE_QUEUE_MANAGER_SECTION This section contains the following

MQE_QUEUE_MANAGER_NAME An ascii string containing the queue Manager's unique name. This name must:

  • Be at least 1 character long.
  • Conform to the Ascii character set, i.e. characters with values between 20 & 128.
  • Must not include { } [ ] # ( ) : ; , ' " #
  • The first and last character of the queue manager name should not be a period
However to maintain compatibility with MQSeries it is recommended that queue manager names are limited to a maximum length of 48 characters. The characters can be any of the following:

Uppercase A-Z, lowercase a-z, Numerics 0-9, Periods, Underscores, Percent Sign

MQE_REGISTRY_SECTION

  • MQE_REGISTRY_LOCAL_REG_TYPE An ascii string containing the type of registry to use. Currently the only recognized types are MQE_REGISTRY_FILE_REGISTRY and MQE_REGISTRY_PRIVATE_REGISTRY
  • MQE_REGISTRY_MQE_REGISTRY_DIR_NAME An ascii string containing a path name to the queue Manager's registry.
  • MQE_REGISTRY_PIN Ascii value for the PIN of the Private registry, if used.
  • MQE_REGISTRY_KEY_RING_PASSWORD Ascii value for the password used to protect the registry's private key (if used).
For security reasons, the Pin and KeyRingPassword are deleted from the startup parameters as soon as the queue manager has been activated.
Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hStartUpParams  [in] a Fields handle containing startup parameters.
Precondition:
hQMgr must not be NULL.
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hStartUpParams must not be NULL.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_QMGR_ACTIVATED  Queue manager already activate
MQERETURN_J_QMGR_ALREADY_EXISTS  Queue manager already exists
MQERETURN_J_QMGR_INVALID_Q_NAME  Invalid queue manager name
MQERETURN_J_QMGR_NOT_CONFIGURED  Queue manager not configured

MQERETURN mqeQueueManager_addMessageListener MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeMessageListenerHndl    hListener,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter
 

Registers an handle as a listener to any MQeMessage events generated by the queue specified in the hQName parameter. It is only possible to add listeners to local queues.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hListener  [in] the listener to be installed.
hQName  [in] name of the queue from which the listener wishes to receive events.
hFilter  [in] a filter Fields containing handle containing message fields. A value of null means that the listener wishes to receive events for all messages on the queue. Specifying an MQeFields handle containing message fields means that the listener is only interested in events concerning messages whose fields match those contained in the filter.
Precondition:
hQMgr must not be NULL.
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName must not be NULL.
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
Note:
The listening handle must implement the MQeMessageListener. Events are processed by the event handler methods specified in this interface. A message filter consisting of message fields (for example MessageId or Priority) may be specified so that the listening handle only receives events concerning messages that include the same fields as those specified. If no fields are specified, events are triggered for all messages on the queue.

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

Returns an Enumeration 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 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/waitFor 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.

Please see the documentation for MQeMessageEnumeration for information on how it can be used.

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. Needs to be completely freed
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_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_QMGR_INVALID_QMGR_NAME  Invalid queue manager name

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

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()

and mqeQueueManager_waitForMessage().

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

/waitFor 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 message enumeration.
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 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_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_QMGR_INVALID_QMGR_NAME  Invalid queue manager name

MQERETURN mqeQueueManager_checkActive MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQEBOOL *    pIsActive
 

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_close MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

This function should be called by WMQe applications when they have finished using the queue manager.

Parameters:
hQMgr  [in] the queue manager to be closed.
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_J_QMGR_NOT_ACTIVE  Queue manager not active
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 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_J_NOT_FOUND  Returned when attempting to confirm a message that has already been confirmed If an application has reissued a confirm get message request then this exception can b e treated as a successful return code.

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

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_J_NOT_FOUND  Returned when attempting to confirm a message that has already been confirmed If an application has reissued a confirm get message request then this exception can b e treated as a successful return code.

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

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_J_QMGR_INVALID_Q_NAME  Invalid queue Name
MQERETURN_J_QMGR_WRONG_Q_TYPE  Wrong queue Type
MQERETURN_J_NOT_FOUND  Not found
MQERETURN_J_NOT_ALLOWED  Not allowed
MQERETURN_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_QMGR_INVALID_QMGR_NAME  Invalid queue manager name

MQERETURN mqeQueueManager_getMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeMsgHndl *    phMsgs,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter,
MQeAttributeHndl    hAttribute,
MQEINT64    confirmId
 

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_J_QMGR_INVALID_Q_NAME  Invalid queue Name
MQERETURN_J_QMGR_WRONG_Q_TYPE  Wrong queue Type
MQERETURN_J_NOT_FOUND  Not found
MQERETURN_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_QMGR_INVALID_QMGR_NAME  Invalid queue manager name
MQERETURN_J_Q_NO_MATCHING_MSG  No matching message

MQERETURN mqeQueueManager_getName MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeStringHndl *    phQMgrName
 

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_getReference MQeExceptBlock   pExceptBlock,
MQeQueueManagerHndl *    phQMgrRef,
MQECONST MQeStringHndl    hQMgrName
 

If hQMgrName is null then the Default queue manager for is returned.

Parameters:
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phQMgrRef  [out] Pointer to the output handle.
hQMgrName  [in] name of the queue manager to obtain reference.
Precondition:
phQMgrRef must point to an existing MQeQMgr handle.
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_QMGR_INVALID_Q_NAME  Invalid queue manager name
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_putMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQeMsgHndl    hMsg,
MQeAttributeHndl    hAttribute,
MQEINT64    confirmId
 

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. If the local queue manager does not hold a definition of the remote queue then it attempts to contact the queue synchronously.

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_J_QMGR_INVALID_Q_NAME  Invalid queue name
MQERETURN_OK  Completed Successfully
MQERETURN_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_DUPLICATE  Duplicate entry

MQERETURN mqeQueueManager_removeMessageListener MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQECONST MQeMessageListenerHndl    hListener,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter
 

This function removes an handles subscription to Websphere MQ Everyplace message events generated by the queue specified in queueName.

It is only possible to have listeners on local queues.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hListener  [in] the listener to be removed.
hQName  [in] Pointer to the name of the queue from which the listener wishes to receive events.
hFilter  [in] a filter Fields containing handle containing message fields. A value of null means that the listener wishes to receive events for all messages on the queue. Specifying an MQeFields handle containing message fields means that the listener is only interested in events concerning messages whose fields match those contained in the filter.
Precondition:
hQMgr must not be NULL.
pExceptBlock points to a pre-allocated MQeExceptBlock structure (no error information is returned if pExceptBlock is null).
hQName must not be NULL.
Note:
The listening handle must implement the MQeMessageListenerInterface. If an optional message filter is specified, the handle’s subscription is only removed for events concerning messages that include the same fields as those specified in the filter. If the filter is null, the handle’s subscription for events concerning all messages is removed..
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_INVALID_Q_NAME  Invalid queue name
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist

MQERETURN mqeQueueManager_triggerTransmission MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

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).
Return values:
MQERETURN_J_BAD_REQUEST  Bad request of operation
MQERETURN_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist

MQERETURN mqeQueueManager_channelTimeout MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock
 

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
 

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_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_INVALID_Q_NAME  Invalid queue name
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_Q_NO_MATCHING_MSG  No matching message
MQERETURN_J_NOT_ALLOWED  Action not allowed

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

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_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_INVALID_Q_NAME  Invalid queue name
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_Q_NO_MATCHING_MSG  No matching message
MQERETURN_J_NOT_ALLOWED  Action not allowed

MQERETURN mqeQueueManager_waitForMessage MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeMsgHndl *    phMsgs,
MQECONST MQeStringHndl    hQMgrName,
MQECONST MQeStringHndl    hQName,
MQECONST MQeFieldsHndl    hFilter,
MQeAttributeHndl    hAttribute,
MQEINT64    confirmId,
MQEINT32    millisecs
 

This function works in an identical manner to mqeQueueManager_getMessage(). However, if no message is available, the method waits for the period of time specified by millisecs milliseconds. If no message is available at the end of this period, an error is raised.

Parameters:
hQMgr  [in] the queue manager to be operated on.
pExceptBlock  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phMsgs  [in/out] Pointer to output message array.
hQMgrName  [in] name of the queue manager from which a user wishes to receive a message.
hQName  [in] 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.
millisecs  [in] number of milliseconds to wait.
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_J_QMGR_NOT_ACTIVE  Queue manager not active
MQERETURN_J_QMGR_INVALID_Q_NAME  Invalid queue name
MQERETURN_J_QMGR_Q_DOES_NOT_EXIST  Queue does not exist
MQERETURN_J_Q_NO_MATCHING_MSG  No matching message
MQERETURN_J_Q_NO_MSG_AVAILABLE  No message available

MQERETURN mqeQueueManager_setGlobalHashtable MQeQueueManagerHndl    hQMgr,
MQeExceptBlock   pExceptBlock,
MQeHashtableHndl    hHashTable
 

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


Generated Thu Aug 11 23:41:22 2005 for Websphere MQ Everyplace for Multiplatforms C Bindings Reference