Result set tokens

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: 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.
An ID data type is populated by the getFirstId and getNextId functions. A Statistical data type is populated by the getFirstStat and getNextStat functions. The data types are used to access the data in the result sets, as described in Correlating results and error checking.
Note: All ID data and statistical data is in character format, using the default native string encoding.
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.