Navigating with Cursors
Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista
Cursors are defined by the receiving application or, when using COM components, by Message Queuing. Unlike lookup identifiers, which are associated with specific messages, cursors are associated with specific queues.
When a receiving application uses a cursor to navigate through the messages in a queue, it starts at the front of the queue and moves sequentially toward the end. Without cursors or lookup identifiers, applications can read only the message that is at the front of the queue.
Receiving applications can use cursors to peek at messages and examine specific properties before deciding to receive them. This way, applications can navigate queues to filter out messages that have a specific characteristic, for example, all messages that have the same message label or correlation identifier. Receiving applications can use cursors for reading messages both synchronously and asynchronously.
Note
Do not use the same cursor when firing receive calls in overlapping operations. Firing a second receive call (using the same cursor) before the first one is completed leads to unexpected behavior.
Differences Between Development Platforms
Receiving applications using function calls can create and use any number of cursors to navigate through a queue. Each cursor is independent of all other cursors, including cursors created by other applications, so moving one cursor has no effect on where another cursor is pointing.
Receiving applications using COM components can only use a single cursor for each queue object. However, the receiving application can open the queue several times, with each instance of the queue object providing its own cursor.
Maximum Number of Cursors
There is no limit to the number of applications or the number of cursors that can be used to navigate through a specific queue. You can have several applications with different cursors pointing to a single queue; you can have one application using several cursors on a single queue (with applications using COM methods, you can do this by using multiple instances of the queue); or you can have multiple applications as well as multiple cursors pointing to any combination of queues.
Cursors Movement Within Transactions
When retrieving messages within a transaction, Message Queuing does not roll back cursor movement if the transaction is aborted. For example, given a queue with two messages A and B, if you remove message A while in a transaction, Message Queuing will move the cursor to the next message B. However, if the transaction is aborted for any reason, message A is inserted back into the queue, yet the cursor will remain pointing at message B.
| For information on | See |
|---|---|
| How a cursor is moved to the first message when the cursor is created. | Cursor Behavior when Creating a Cursor |
| How the cursor is moved when peeking at messages | Cursor Behavior when Peeking at Messages |
| How the cursor is moved when retrieving messages | Cursor Behavior when Retrieving Messages |
| How the cursor is moved when reaching the end of the queue | Cursor Behavior when Reaching the End of the Queue |
| How multiple cursors interact | Cursor Behavior when Using Multiple Cursors |
| How the cursor behaves when waiting for new messages at the end of the queue. | Cursor Behavior when Waiting for New Messages |
| How the cursor behaves when trying to read a message that was removed by someone else. | Cursor Behavior When Messages are Not Available |
| How the behaves when errors occur. | Cursor Behavior Due to Errors |
| How the cursor behaves when trying to read messages from a deleted queue | Cursor Behavior and Deleted Queues |
| How the cursor moves when the queue contains messages with different message priority levels. | Cursor Behavior and Message Priority |
| Summary of COM methods that use cursors for synchronous and asynchronous operations | Cursors and COM Components |
| Example code that navigates a queue based on cursors. | Navigating Queue Examples |