3.1.4.4 R_QMCreateRemoteCursor (Opnum 4)

  • Article

The R_QMCreateRemoteCursor method creates a cursor at the server for use during remote read.

 HRESULT R_QMCreateRemoteCursor(
   [in] handle_t hBind,
   [in] struct CACTransferBufferV1* ptb1,
   [in] DWORD hQueue,
   [out] DWORD* phCursor
 );

hBind:  MUST be set to an RPC binding handle, as specified in [MS-RPCE] section 2.

ptb1:  MUST be ignored. Clients SHOULD pass NULL.<29>

hQueue: A DWORD that contains the value of the Handle attribute of an OpenQueueDescriptor ([MS-MQDMPR] section 3.1.1.16) ADM element instance. The client obtains this value from either the pcc.srv_hACQueue out-parameter of rpc_ACCreateCursorEx or the phQueue out-parameter of R_QMOpenRemoteQueue.

phCursor: A pointer to a DWORD to receive the value of the Handle attribute of the Cursor ([MS-MQDMPR] section 3.2) ADM element instance that references the created cursor. It MUST NOT be NULL on input.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically. Additionally, if a failure HRESULT is returned, the client MUST disregard all out-parameter values.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

This method is invoked at the dynamically assigned endpoint returned by the R_QMGetRTQMServerPort method when IP_HANDSHAKE (0x00000000) or IPX_HANDSHAKE (0x00000002) is the interface specified by the fIP parameter.

When processing this call, the server MUST:

  • Search the OpenQueueDescriptorCollection attribute of each Queue ([MS-MQDMPR] section 3.1.1.2) ADM element instance that is contained in the server's LocalQueueManager.QueueCollection attribute for an OpenQueueDescriptor ADM element instance where the value of the Handle attribute of the OpenQueueDescriptor ADM element instance equals hQueue.

  • If no such OpenQueueDescriptor ADM element instance exists, take no further action and return a failure HRESULT.

  • Generate an Open Cursor ([MS-MQDMPR] section 3.1.7.1.1) event with the following argument value:

    • iQueueDesc := The OpenQueueDescriptor ADM element instance found preceding.

  • The Open Cursor event returns a reference to the Cursor ADM element instance, rCursor.

  • Set the phCursor parameter to rCursor.Handle.

  • Return MQ_OK (0x00000000).