A result set token is a reference to a set of results from a single
statistics C API function call.
If a statistics C 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 can 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 C API function are 'owned' by the C API. The token is freed when
either:
or
The result set token returned by the
copyResultSet function
is
not 'owned' by the C API. The token can only be freed using the
freeResultSet function.
Result set tokens 'owned' by the C API cannot be 'freed' using the freeResultSet function. The tokens must be freed using
the closeGatewayConnection or closeAllGatewayConnections functions.
Result sets which are C API-owned can only be manipulated on the thread
which obtained them. Result sets that were not created by C API calls can
be manipulated by any thread.