A result set token is a reference to a set of results from a single
statistics API function call.
If a statistics API function calculates a set of data, the function provides
a reference to the result set. This reference is called a result set token.
The result set may contain either:
- ID data, including statistical group IDs or statistical IDs
or:
A result set token is used to work with result set data. For example,
a result set token enables a user application to browse through the result
set, or extract specific details. The application can use functions such as
getFirstId or
getNextStat to
manipulate the result set data.
Result set tokens returned by a
statistics API function are 'owned' by the API. The token is freed when either:
or
The result set token returned by the
copyResultSet function
is
not 'owned' by the API. The token can only be freed using the
freeResultSet function.
Result set tokens 'owned' by the API cannot be 'freed' using the freeResultSet function. The tokens must be freed using
the closeGatewayConnection or closeAllGatewayConnections functions.
Result sets which are API-owned can only be manipulated on the thread which
obtained them. Result sets that were not created by API calls can be manipulated
by any thread.