Result set tokens

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:

• Statistical data

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.

Result set tokens returned by a statistics C API function are 'owned' by the C API. The token is freed when either:

• The associated Gateway daemon connection is closed using the closeGatewayConnection function.

or

• The function closeAllGatewayConnections is called.

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.