Working with multiple result sets

Working with multiple result sets requires special attention.

Calling a statistics C API function produces a result set token. This token identifies a result set owned by the statistics C API. The result set is also associated with the Gateway identified by the gateway token used during the function call. This means that each result set owned by the statistics C API is associated with a specific Gateway connection. It is helpful to think of the gateway token and the corresponding result set token as a pair.

Tokens referring to C API-owned result sets can only be used by the thread which created them. To create a result set token usable by any thread, call the copyResultSet function.

For example, an application using the same gateway token to make two separate C API function calls will be given two logically different result set tokens. Since the same gateway token was used for both calls, the different result set tokens will iterate over the same result set. The result set will be the one returned by the last C API function call.

This means that the result set identified by an result set token is only valid until another C API call is made, specifying the same gateway token. The most recent C API call overwrites the existing result set.

Use the copyResultSet function to make a copy of a result set before it is overwritten by another C API call. When the application finishes using the copied result set, free the storage using the freeResultSet function.

getStatsByStatGroupId(gwyTok, "", &rsTok1, "",);
/* Tasks after getStatsByStatGroupId function call. */
getStatsByStatId(gwyTok, "", &rsTok2, "",);
/* Tasks after getStatsByStatId function call. */