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.


In the following example code, two statistics C API calls are made. The same Gateway token is used for both calls. Two separate addresses are supplied for the result set tokens.
getStatsByStatGroupId(gwyTok, "", &rsTok1, "",);
/* Tasks after getStatsByStatGroupId function call. */
getStatsByStatId(gwyTok, "", &rsTok2, "",);
/* Tasks after getStatsByStatId function call. */
Using the same Gateway token both calls means that the result set pointed to by &rsTok1 will be overwritten when the second C API call is made. The two separate result set tokens &rsTok1 and &rsTok2 will iterate over the same result set.

If the result set obtained from the first C API call is still required later in the application, take a copy of the result set by calling the copyResultSet function.