Executing Operations

ostc_Session::doOperation()

virtual ostc_ObjectList* doOperation(
      ostc_Operation *op, 
      oscs_Bool use_cache,
      oscs_Bool incremental = 0,
      oscs_Uint32 max_objs_returned = 0,
      void * userRouteData = 0,
      oscs_Uint32 userRouteDataLen = 0
) ;

Executes the operation op on a Component Server.

When you call this function for a given operation, the client does one of the following:

Contacts a router to locate a Server that matches the operation.
Finds a matching Server based on information cached during the current process on the client side.

If no client transaction (started with ostc_Session::beginTxn()) is in progress, a Server matches an operation if all the following hold:

The Server is running the service associated with this session.
The Server's transaction type matches the operation's transaction type. Any Server transaction type except none matches the operation transaction type ostc::any.
If the argument userRouteData is nonzero, the Server's route data matches userRouteData. Matches are identified with memcmp().

In this case, the Server starts (or, for a batch transaction, has already started) the transaction in which the operation is executed. The Server commits or aborts the transaction before doOperation() returns.

If a client transaction is in progress, a Server matches an operation if all the following hold:

The Server is running the service associated with this session.
The Server's transaction type is ostc::isolated_update.
If the argument userRouteData is nonzero, the Server's route data matches userRouteData. Matches are identified with memcmp().

In this case, the Server started this operation's transaction when the client called ostc_Session::beginTxn().

The client maintains a cache of object lists returned by doOperation() during the current session. doOperation() does not interact with the Server and instead returns a cached list if

use_cache is 1.
The same operation with the same arguments was executed earlier in the current session.
The returned list from that execution is still in the thin client's cache.

Note that use_cache does not affect whether an operation's result is added to the cache. An operation's result is added regardless of the value of use_cache.

Note that the cache does not reflect changes to persistent data made by other processes; cache-validity is not automatically maintained.

If incremental is nonzero, doOperation() returns a pointer to an incremental ostc_ObjectList, and max_objects_returned specifies the batch size of the returned set.

If the number of objects to be returned is large, the client can specify that the results be returned incrementally. The incremental nature of the results is transparent to the client, since the usual API functions for retrieving list elements automatically trigger a Server interaction whenever a new batch of results must be sent.

For isolated_update operations, each batch is sent in its own transaction. The Server creates a collection of references to the operation results, which can be used across transactions.