Share via

3.1.4.20 rpc_ACSetCursorProperties (Opnum 23)

  • Article

A client calls the rpc_ACSetCursorProperties method to associate a remote cursor created via R_QMCreateRemoteCursor (section 3.1.4.4) with a local CursorProxy (section 3.1.1.6) created using rpc_ACCreateCursorEx (section 3.1.5.4).

Note This method is obsolete. The server SHOULD take no action and return MQ_ERROR_ILLEGAL_OPERATION (0xc00e0064).<55>

 HRESULT rpc_ACSetCursorProperties(
   [in] RPC_QUEUE_HANDLE hProxy,
   [in] DWORD hCursor,
   [in] DWORD hRemoteCursor
 );

hProxy: MUST contain the RPC_QUEUE_HANDLE (section 2.2.1.1.2) context handle passed to rpc_ACCreateCursorEx when the cursor specified by hCursor was created.

hCursor: MUST contain a CursorProxy.Handle obtained from the pcc.hCursor out-parameter of rpc_ACCreateCursorEx.

hRemoteCursor: MUST contain a Cursor.Handle for a remote cursor acquired from the phCursor out-parameter of R_QMCreateRemoteCursor invoked at a remote queue manager.

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.

This method is obsolete. Servers SHOULD take no action and return MQ_ERROR_ILLEGAL_OPERATION (0xc00e0064). Servers SHOULD contact the remote queue manager on behalf of the client when rpc_ACCreateCursorEx is called to create a remote cursor.

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

During the client cursor creation sequence, the supporting server MAY indicate that the client MUST contact a remote queue manager to proceed.<56> In response, the client MUST call R_QMGetRemoteQueueName (section 3.1.4.1) to determine the remote queue manager name and MUST then invoke R_QMCreateRemoteCursor at the remote queue manager. Next, the client MUST call this method to associate the Cursor.Handle obtained from R_QMCreateRemoteCursor with the original CursorProxy.Handle obtained from rpc_ACCreateCursorEx.

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

When processing this call, the server MUST:

  • Locate a RemoteQueueProxyHandle (section 3.1.1.5) in the server's RemoteQueueProxyHandleTable (section 3.1.1.4) where RemoteQueueProxyHandle.Handle equals hProxy.

  •  If no such RemoteQueueProxyHandle exists, take no further action and return a failure HRESULT.

  • Locate a CursorProxy in RemoteQueueProxyHandle.CursorProxyCollection where CursorProxy.Handle equals hCursor.

  •  If no such CursorProxy exists, take no further action and return a failure HRESULT.

  • Set CursorProxy.RemoteCursorHandle := hRemoteCursor.

  • Set CursorProxy.IsRemoteCursorHandleInitialized := True.

  • Return MQ_OK (0x00000000).