MQCreateCursor

The MQCreateCursor function creates a cursor for a specific queue and returns its handle. The cursor is used to maintain a specific location in a queue when reading the queue's messages.

HRESULT APIENTRY MQCreateCursor(
 QUEUEHANDLE hQueue,  
  PHANDLE phCursor     
);
 

Parameters

hQueue

[in] Handle to the queue where you want to create a cursor.

phCursor

[out] Pointer to a variable that receives the resulting cursor handle.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_INVALID_HANDLE

The queue handle specified in hQueue is not valid.

MQ_ERROR_STALE_HANDLE

The specified queue handle was obtained in a previous session of the Queue Manager service. Close the queue and open it again to obtain a fresh handle.

Remarks

The MQCreateCursor function is used with MQReceiveMessage when you need to read messages that are not at the front of the queue. You do not need to create a cursor if you only want to read the first message in a queue.

For an example of how cursors are used when reading messages, see Reading Messages in a Queue.

For a description of how MSMQ uses cursors to navigate a queue, see Peeking at the next Message in a Queue or Retrieving a Message in a Queue

To close the cursor, call MQCloseCursor.

Examples

For examples of using MQCreateCursor, see Reading Messages Using a Cursor.

See Also

MQCloseCursor, MQReceiveMessage

© 1997 by Microsoft Corporation. All rights reserved.