3.2.4.8 Creating a Cursor

The client MUST execute the following steps:

  • Invoke the rpc_ACCreateCursorEx method with the following parameter values:

    • hQueue := iOpenQueueContext.Handle

    • pcc := In/Out structure. The member input values are ignored by the server. Retrieve the output values from the server.

  • If the rpc_ACCreateCursorEx method returns a failure HRESULT, the cursor cannot be created. Take no further action.

  • Else, if the rpc_ACCreateCursorEx method returns MQ_OK (0x00000000):

    • Store the CursorIdentifier (section 3.2.1.3) ADM element instance returned by pcc.hCursor for subsequent operations on the cursor.

    • Take no further action. The cursor was created successfully.

  • Else, if the rpc_ACCreateCursorEx method returns MQ_INFORMATION_REMOTE_OPERATION (0x400E03E8):

    • Invoke the R_QMGetRemoteQueueName method with the following parameter values:

      • pQueue := pcc.cli_pQMQueue (out-parameter value from the rpc_ACCreateCursorEx method)

      • lplpRemoteQueueName := in/out parameter:

        • In: NULL.

        • Out: Retrieve this value from the server.

    • Using the RPC binding procedure as specified in section 3.2.4, bind to the remote server indicated by the path name contained in lplpRemoteQueueName.

    • At the remote server, invoke the R_QMCreateRemoteCursor method, supplying the following parameter values:

      • hQueue := pcc.srv_hACQueue (out-parameter value from the rpc_ACCreateCursorEx method)

      • phCursor := Retrieve this out-parameter value from the server.

    • At the original server (where the rpc_ACCreateCursorEx method was invoked), invoke the rpc_ACSetCursorProperties method with the following parameter values:

      • hProxy := iOpenQueueContext.Handle

      • hCursor := pcc.hCursor (out-parameter value from the rpc_ACCreateCursorEx method)

      • hRemoteCursor := phCursor (out-parameter value from the R_QMCreateRemoteCursor method)

      • If any of the R_QMGetRemoteQueueName, R_QMCreateRemoteCursor, or rpc_ACSetCursorProperties method invocations fails for any reason:

        • Invoke the rpc_ACCloseCursor method with the following parameter values:

          • hQueue := iOpenQueueContext.Handle

          • hCursor := pcc.hCursor (out-parameter value from the rpc_ACCreateCursorEx method)

        • Take no further action. The cursor cannot be created.

      • Else:

        • Store the CursorIdentifier ADM element instance returned by pcc.hCursor for subsequent operations on the cursor.

        • The cursor was created successfully.