INFO: Using Cursors with Microsoft Message Queue Server

ID: Q178516

The information in this article applies to:

Microsoft Message Queue Server version 1.0

SUMMARY

This article contains information about using cursors with Microsoft Message Queue Server (MSMQ).

Using C API calls you can create as many cursors on an MSMQ queue object as you want.

If you use ActiveX components, there is only one implicit cursor per MSMQ queue object. You can have multiple cursors from an ActiveX component by performing multiple OPENs of the queue with each OPEN queue instance having one implicit cursor. However, this increases the overall resource requirements for this component.

Cursors point to a specific message, not to a relative position in the queue.

For ActiveX components, the implicit cursor can advance through the queue as it does for MSMQQueue.PeekNext, MSMQQueue.PeekCurrent, and MSMQQueue.ReceiveCurrent. For ActiveX components that always reference the first message in the queue (MSMQQueue.Peek and MSMQQueue.Receive) the implicit cursor is a NULL cursor.

MORE INFORMATION

Cursors Are Per Application, not Per Queue

You can have many applications with different cursors pointing to different locations in a single queue. It is also possible to have more than one cursor on a queue from a single application. You may also have multiple cursors pointing to any combination of multiple queues that are subject to the one implicit cursor per MSMQ queue object imposed by use of the ActiveX components.

Cursor Behavior after an Error in Receive Operation

The cursor never resets but may advance (as you would want it to) when you use PeekNext.

When you use ReceiveCurrent and PeekCurrent, the cursor is not moved when an error occurs. With PeekNext, the cursor is moved even if there is an error.

NOTE: The cursor does not move when there is an invalid handle. For example, if you use peek next and get the error "buffer overflow", subsequent PeekCurrent operations return the same message and not the message pointed to before PeekNext.

Cursor Behavior in Synchronous and Asynchronous Receive

Cursors behave the same way in synchronous and asynchronous Receive operations. However, you should not use the same cursor in overlapping operations.

For example, you should not fire another Receive using the same cursor before the first Receive is completed because this may lead to unexpected behavior.

Cursor Behavior after a Message Is Removed

If an application cursor points to a specific message in a queue, when that message is removed from the queue by another means, (another application, or another thread in the same application, or deleted from MSMQ Explorer), the application's cursor continues to point to a shadow of the removed message. Subsequent Receive or PeekCurrent operations return an error with the information that the message has already been received:

(MQ_ERROR_MESSAGE_ALREADY_RECEIVED)

Cursor Behavior after a Queue Is Deleted

When an application has an open queue (regardless of cursor usage) and the queue is deleted, subsequent Receive or Peek operations return an error with the information that the queue has been deleted:

(MQ_ERROR_QUEUE_DELETED)

PeekNext Restrictions

First, you cannot use PeekNext immediately following a Receive operation. Instead, you must perform a PeekCurrent or another Receive. When you use C API calls this means after you pass an MQ_ACTION_RECEIVE with a valid cursor handle, the next call to MSMQReceiveMessage must not contain an action of MQ_ACTION_PEEK_NEXT.

Secondly, you cannot perform a PeekNext after creating a cursor. With ActiveX this restriction applies to attempting to PeekNext after opening a queue without first performing a PeekCurrent. When you use C API calls this means you cannot pass MQ_ACTION_PEEK_NEXT after performing a MQCreateCursor without first performing a MQ_ACTION_PEEK_CURRENT or MQ_ACTION_RECEIVE. If you use MQCreateCursor and then call an ActiveX component, the ActiveX components first action must be a PeekCurrent, Peek, or Receive.

REFERENCES

MSMQ SDK Online: MSMQ Guide/MSMQ Messages/Reading Messages; Reading Messages with Cursors; Message and Cursor Behavior

http://www.microsoft.com/msmq/

Additional query words:

Keywords : MQProg
Version : winnt:1.0
Platform : winnt
Issue type : kbinfo