API and protocol version control

The API version represents the programming interface available from the ctgstats runtime library. The protocol version represents the set of responses that may be returned by a connected Gateway daemon in response to a statistics API function call. Comparison of compile time versus runtime values can be made to establish compatibility.

A statistics API application, and the Gateway daemon providing the statistics, might be from different versions of the CICS® Transaction Gateway. API and protocol version control helps ensure that a statistics API application can issue meaningful requests to a CICS Transaction Gateway daemon, and get meaningful responses in return. API and protocol versions have a format of four digits, separated by the underscore character. For example: 1_0_0_0
Note: The API and protocol versions might look like the product version, but they are not related. The statistics API can only be used to collect statistical data from Gateway daemons at version 7.0 or higher.
A statistics API application can:
  • Find the API version that it was compiled with by using the compile-time string CTG_STAT_API_VERSION, defined in ctgstats.h.
  • Find which API version is used at run time by a CICS Transaction Gateway daemon, or Java™ statistics API by using the getStatsAPIVersion function.
  • Find the protocol version that it was compiled with by using the compile-time string CTG_STAT_PROTOCOL_VER, defined in ctgstdat.h.
  • Find which protocol version is used at run time by a CICS Transaction Gateway daemon, by using the openGatewayConnection or openRemoteGatewayConnection function.

API version

The major version number, first digit, of the statistics API version must match between the application at compile time and ctgstats runtime library.

For example; if CTG_STAT_API_VERSION is 1_0_0_0 and the runtime function getStatsAPIVersion returns 1_1_0_0 then the major version (1_x_x_x) matches. Therefore the application is guaranteed to be runtime compatible with at least those functions available for version 1_1_0_0.

If the major version numbers differ, runtime compatibility is not guaranteed and API calls might fail.

Assuming that the major version number matches, then the minor version number (second digit) of the statistics API version at application compile time must be the lower than or equal to the ctgstats runtime library.

For example; if CTG_STAT_API_VERSION is 1_0_0_0 and the runtime function getStatsAPIVersion returns 1_1_0_0 then the major version (1_x_x_x) matches, and the minor version (x_0_x_x) used by the application is lower than the runtime library. Therefore, the application is guaranteed to be runtime compatible because it can only use those functions that are available at runtime version 1_0_0_0.

If the minor version number. second digit, of the statistics API version at application compile time is greater than the ctgstats runtime library, then some functions available at compile time will not be available at run time. The 3rd and 4th digits are reserved for IBM® service and maintenance usage.

Protocol version

The protocol version adheres to similar rules between compile time and run time as the API Version. However, the protocol version represents the interface between the compiled statistics application and the Gateway daemon connected at run time.

The major version number, first digit, of the protocol version must match between the application at compile time and the connected Gateway daemon.

Assuming that the major version number matches, then the minor version number, second digit, of the statistics API application at application compile time, must be the greater than or equal to the minor version number returned by the connected CICS Transaction Gateway daemon upon connection. If the minor version number is lower than that of the connected Gateway daemon, then the statistics API application might be unable to interpret all responses from function calls.