Defines functions and typedefs for retrieving statistics from a Gateway daemon and controlling API tracing. More...
Go to the source code of this file.
Data Structures | |
struct | CTG_IdData_t |
CTG_IdData_t encapsulates a ResourceGroupId, ResourceID or StatId. More... | |
struct | CTG_StatData_t |
CTG_StatData_t encapsulates a single StatId and value pair. More... | |
Macros | |
#define | CTG_STAT_OK 0 |
The API call completed successfully. | |
#define | CTG_STAT_ERR_NULLGWTOK -100 |
A specified Gateway Token was found to be NULL. | |
#define | CTG_STAT_ERR_BADGWTOK -101 |
A Gateway Token was not recognised by the statistics API. | |
#define | CTG_STAT_ERR_LOSTGWCON -102 |
The connection to the Gateway has been lost. | |
#define | CTG_STAT_ERR_NULLPARM -103 |
One of the parameters passed to the method was NULL. | |
#define | CTG_STAT_ERR_TRACELEVEL -104 |
An invalid trace level was provided to setAPITraceLevel(). | |
#define | CTG_STAT_ERR_NULLVERSPTR -105 |
The pointer provided to store the protocol version from the API call was NULL. | |
#define | CTG_STAT_ERR_APIRESULTSET -106 |
An attempt was made to free a result set that belongs to the API rather than the user. | |
#define | CTG_STAT_ERR_BADPORT -107 |
The API was unable to communicate with the Gateway Daemon on the port provided. | |
#define | CTG_STAT_ERR_NULLGWTOKPTR -108 |
The specified Gateway Token pointer was found to be NULL. | |
#define | CTG_STAT_ERR_NULLPTR -109 |
The specified pointer was found to be NULL. | |
#define | CTG_STAT_ERR_NULLRSBUFFER -110 |
The specified result set buffer was found to be NULL. | |
#define | CTG_STAT_ERR_MALLOCFAIL -111 |
The API was unable to allocate sufficient memory to complete the operation. | |
#define | CTG_STAT_ERR_EMPTYRESULTSET -112 |
The result set does not contain any results. | |
#define | CTG_STAT_ERR_ENDOFRESULTSET -113 |
There are no more results in the result set. | |
#define | CTG_STAT_ERR_BADGWTOKLIST -115 |
The Gateway Token list has become corrupt. | |
#define | CTG_STAT_ERR_BADRSOWNER -116 |
An unknown result set owner type was used when trying to create a result set. | |
#define | CTG_STAT_ERR_BADRSTOKEN -117 |
The result set token was not recognised by the API. | |
#define | CTG_STAT_ERR_CONNECTFAILED -118 |
The API was unable to establish a connection with the Gateway daemon. | |
#define | CTG_STAT_ERR_BADRSTYPE -119 |
The result set did not contain results that are statistics or ids. | |
#define | CTG_STAT_ERR_ICONV -120 |
The API was unable to create conversion descriptors for the native code page. | |
#define | CTG_STAT_ERR_LOCKFAIL -121 |
The API was unable to create a lock during initialization. | |
#define | CTG_STAT_ERR_COMMSFAIL -122 |
An error occurred in the communications with the Gateway daemon. | |
#define | CTG_STAT_ERR_PIDMISMATCH -123 |
The process that has attempted to use the Gateway token or API owned result set is different to the one that created it. | |
#define | CTG_STAT_ERR_TIDMISMATCH -124 |
The thread that has attempted to use the Gateway token or API owned result set is different to the one that created it. | |
#define | CTG_STAT_ERR_NULLRSTOKPTR -125 |
The specified result set token pointer was found to be NULL. | |
#define | CTG_STAT_ERR_NULLQUERYSTRING -126 |
The specified query string was found to be NULL. | |
#define | CTG_STAT_ERR_NULLRSTOK -127 |
The specified result set token was found to be NULL. | |
#define | CTG_STAT_ERR_NULLIDDATAPTR -128 |
The specified CTG_IdData_t pointer was found to be NULL. | |
#define | CTG_STAT_ERR_NULLSTATDATAPTR -129 |
The specified CTG_StatData_t pointer was found to be NULL. | |
#define | CTG_STAT_ERR_TRACEFILE -130 |
The API was unable to create a trace file at the specified location. | |
#define | CTG_STAT_ERR_NOQUERYIDS -131 |
The result set does not contain any valid statistic ids or resource group ids. | |
#define | CTG_STAT_ERR_BADHOST -132 |
The hostname was not resolved to a valid IP address. | |
#define | CTG_STAT_ERR_NULLADDRESS -133 |
The specified hostname was found to be NULL. | |
#define | CTG_STAT_ERR_CONNECTTIMEOUT -134 |
The connection failed to complete within 60 seconds. | |
#define | CTG_STAT_ERR_CONNECTREFUSED -135 |
The connection attempt was refused. | |
#define | CTG_STAT_ERR_GATEWAYUNREACHABLE -136 |
The connection attempt was unable to reach the specified Gateway location. | |
#define | CTG_STAT_TRACE_LEVEL0 0 |
Trace level 0 disables all tracing. | |
#define | CTG_STAT_TRACE_LEVEL1 1 |
Trace level 1 includes exception trace points only. | |
#define | CTG_STAT_TRACE_LEVEL2 2 |
Trace level 2 includes event trace points and lower trace levels. | |
#define | CTG_STAT_TRACE_LEVEL3 3 |
Trace level 3 includes entry/exit trace points and lower trace levels. | |
#define | CTG_STAT_TRACE_LEVEL4 4 |
Trace level 4 includes debug trace points and lower trace levels. | |
#define | CTG_STAT_NULL_GWTOK NULL |
NULL Gateway daemon token. | |
#define | CTG_STAT_NULL_RSTOK NULL |
NULL result set token. | |
#define | CTG_STAT_API_VERSION "1_1_0_1" |
CICS TG Statistics API version. | |
#define | CTG_STAT_DLL_VERSION "9.0.0.0" |
CICS TG Statistics API library build version. | |
Typedefs | |
typedef struct _CTG_GatewayToken_t * | CTG_GatewayToken_t |
CTG_GatewayToken_t represents a connection to a specific Gateway daemon. | |
typedef struct _CTG_ResultSetToken_t * | CTG_ResultSetToken_t |
CTG_ResultSetToken_t represents the results of an API call to obtain id or statistic data. | |
Functions | |
int | openGatewayConnection (int port, CTG_GatewayToken_t *gwTokPtr, char **protocolVersPtr) |
Establishes a connection to a local Gateway daemon statistics protocol handler using the specified port number. | |
int | openRemoteGatewayConnection (char *address, int port, CTG_GatewayToken_t *gwTokPtr, char **protocolVersPtr) |
Establishes a connection to a Gateway daemon statistics protocol handler using the specified hostname and port number. | |
int | closeGatewayConnection (CTG_GatewayToken_t *gwTokPtr) |
Closes the connection to the Gateway daemon associated with the specified Gateway token. | |
int | closeAllGatewayConnections () |
Attempts to free all resources held by the API, including open Gateway daemon connections. | |
int | getResourceGroupIds (CTG_GatewayToken_t gwTok, CTG_ResultSetToken_t *resgrpIdRsTokPtr) |
Takes a gateway token and a result set token pointer. | |
int | getStatIds (CTG_GatewayToken_t gwTok, CTG_ResultSetToken_t *statIdRsTokPtr) |
Takes a gateway token and a result set token pointer. | |
int | getStatIdsByStatGroupId (CTG_GatewayToken_t gwTok, char *idQueryPtr, CTG_ResultSetToken_t *statIdRsTokPtr) |
Takes a gateway token, a query string of StatGroupIds and a result set token pointer. | |
int | getStats (CTG_GatewayToken_t gwTok, CTG_ResultSetToken_t *statRsTokPtr) |
Takes a gateway token, a query string of StatIds and a result set token pointer. | |
int | getStatsByStatId (CTG_GatewayToken_t gwTok, char *idQueryPtr, CTG_ResultSetToken_t *statRsTokPtr) |
Takes a gateway token, a query string of StatIds and a result set token pointer. | |
int | getStatsByStatGroupId (CTG_GatewayToken_t gwTok, char *idQueryPtr, CTG_ResultSetToken_t *statRsTokPtr) |
Takes a gateway token, a query string of StatGroupIds and a result set token. | |
int | getIdQuery (CTG_ResultSetToken_t anyRsTok, char **idQueryPtr) |
Takes a result set token and the address of a char pointer. | |
int | getFirstId (CTG_ResultSetToken_t idRsTok, CTG_IdData_t *idDataPtr) |
Takes an id result set token and populates a CTG_IdData_t variable with details of the first id in the set. | |
int | getNextId (CTG_ResultSetToken_t idRsTok, CTG_IdData_t *idDataPtr) |
Takes an id result set and populates an CTG_IdData_t variable with details of the next id in the set. | |
int | getFirstStat (CTG_ResultSetToken_t statRsTok, CTG_StatData_t *statDataPtr) |
Takes a Stat result set token and populates a CTG_StatData_t variable with details of the first statistic in the set. | |
int | getNextStat (CTG_ResultSetToken_t statRsTok, CTG_StatData_t *statDataPtr) |
Takes a Stat result set token and populates a CTG_StatData_t variable with details of the next StatId in the set. | |
int | copyResultSet (CTG_ResultSetToken_t srcRsTok, CTG_ResultSetToken_t *tarRsTokPtr) |
Takes a result set token as a source, and a result set token pointer as a target. | |
int | freeResultSet (CTG_ResultSetToken_t *rsTokPtr) |
Takes a result set token pointer for an application-owned result set, created by copyResultSet(), and frees the storage associated with that result set. | |
int | getStatsAPIVersion (char **apiVersPtr) |
Takes the address of a character pointer to be modified. | |
int | getAPITraceLevel (int *traceStatePtr) |
Takes a pointer to an int variable, and sets that variable to the current API trace level. | |
int | setAPITraceLevel (int traceState) |
Takes an int variable representing the desired trace level and sets the API trace level accordingly. | |
int | setAPITraceFile (char *traceFileNamePtr) |
Takes a character pointer to a null-terminated string representing the desired trace file destination. | |
int | dumpResultSet (CTG_ResultSetToken_t rsTok) |
Takes a result set token and writes a representation of that result set in printable characters to the current trace destination, irrespective of trace settings. | |
int | dumpState () |
Writes internal API debugging information to the trace destination, irrespective of trace settings. | |
Detailed Description
Defines functions and typedefs for retrieving statistics from a Gateway daemon and controlling API tracing.
Definition in file ctgstats.h.
Macro Definition Documentation
#define CTG_STAT_API_VERSION "1_1_0_1" |
CICS TG Statistics API version.
Definition at line 923 of file ctgstats.h.
#define CTG_STAT_DLL_VERSION "9.0.0.0" |
CICS TG Statistics API library build version.
Definition at line 928 of file ctgstats.h.
#define CTG_STAT_ERR_APIRESULTSET -106 |
An attempt was made to free a result set that belongs to the API rather than the user.
Definition at line 755 of file ctgstats.h.
#define CTG_STAT_ERR_BADGWTOK -101 |
A Gateway Token was not recognised by the statistics API.
The token is either invalid, or the connection to the gateway has been lost and the token deleted.
Definition at line 732 of file ctgstats.h.
#define CTG_STAT_ERR_BADGWTOKLIST -115 |
The Gateway Token list has become corrupt.
Definition at line 789 of file ctgstats.h.
#define CTG_STAT_ERR_BADHOST -132 |
The hostname was not resolved to a valid IP address.
Definition at line 867 of file ctgstats.h.
#define CTG_STAT_ERR_BADPORT -107 |
The API was unable to communicate with the Gateway Daemon on the port provided.
Definition at line 760 of file ctgstats.h.
#define CTG_STAT_ERR_BADRSOWNER -116 |
An unknown result set owner type was used when trying to create a result set.
If the problem persists, collect application trace and contact your IBM service representative.
Definition at line 795 of file ctgstats.h.
#define CTG_STAT_ERR_BADRSTOKEN -117 |
The result set token was not recognised by the API.
Definition at line 799 of file ctgstats.h.
#define CTG_STAT_ERR_BADRSTYPE -119 |
The result set did not contain results that are statistics or ids.
Definition at line 807 of file ctgstats.h.
#define CTG_STAT_ERR_COMMSFAIL -122 |
An error occurred in the communications with the Gateway daemon.
The Gateway Token will be deleted.
Definition at line 823 of file ctgstats.h.
#define CTG_STAT_ERR_CONNECTFAILED -118 |
The API was unable to establish a connection with the Gateway daemon.
Definition at line 803 of file ctgstats.h.
#define CTG_STAT_ERR_CONNECTREFUSED -135 |
The connection attempt was refused.
Definition at line 879 of file ctgstats.h.
#define CTG_STAT_ERR_CONNECTTIMEOUT -134 |
The connection failed to complete within 60 seconds.
Definition at line 875 of file ctgstats.h.
#define CTG_STAT_ERR_EMPTYRESULTSET -112 |
The result set does not contain any results.
Definition at line 781 of file ctgstats.h.
#define CTG_STAT_ERR_ENDOFRESULTSET -113 |
There are no more results in the result set.
Definition at line 785 of file ctgstats.h.
#define CTG_STAT_ERR_GATEWAYUNREACHABLE -136 |
The connection attempt was unable to reach the specified Gateway location.
Definition at line 884 of file ctgstats.h.
#define CTG_STAT_ERR_ICONV -120 |
The API was unable to create conversion descriptors for the native code page.
If the problem persists, collect application trace and contact your IBM service representative.
Definition at line 813 of file ctgstats.h.
#define CTG_STAT_ERR_LOCKFAIL -121 |
The API was unable to create a lock during initialization.
If the problem persists, contact your IBM service representative.
Definition at line 818 of file ctgstats.h.
#define CTG_STAT_ERR_LOSTGWCON -102 |
The connection to the Gateway has been lost.
Possibly because the Gateway daemon has been shut down.
Definition at line 737 of file ctgstats.h.
#define CTG_STAT_ERR_MALLOCFAIL -111 |
The API was unable to allocate sufficient memory to complete the operation.
Definition at line 777 of file ctgstats.h.
#define CTG_STAT_ERR_NOQUERYIDS -131 |
The result set does not contain any valid statistic ids or resource group ids.
Definition at line 863 of file ctgstats.h.
#define CTG_STAT_ERR_NULLADDRESS -133 |
The specified hostname was found to be NULL.
Definition at line 871 of file ctgstats.h.
#define CTG_STAT_ERR_NULLGWTOK -100 |
A specified Gateway Token was found to be NULL.
Definition at line 726 of file ctgstats.h.
#define CTG_STAT_ERR_NULLGWTOKPTR -108 |
The specified Gateway Token pointer was found to be NULL.
Definition at line 764 of file ctgstats.h.
#define CTG_STAT_ERR_NULLIDDATAPTR -128 |
The specified CTG_IdData_t pointer was found to be NULL.
Definition at line 849 of file ctgstats.h.
#define CTG_STAT_ERR_NULLPARM -103 |
One of the parameters passed to the method was NULL.
Definition at line 741 of file ctgstats.h.
#define CTG_STAT_ERR_NULLPTR -109 |
The specified pointer was found to be NULL.
Definition at line 768 of file ctgstats.h.
#define CTG_STAT_ERR_NULLQUERYSTRING -126 |
The specified query string was found to be NULL.
Definition at line 841 of file ctgstats.h.
#define CTG_STAT_ERR_NULLRSBUFFER -110 |
The specified result set buffer was found to be NULL.
Definition at line 772 of file ctgstats.h.
#define CTG_STAT_ERR_NULLRSTOK -127 |
The specified result set token was found to be NULL.
Definition at line 845 of file ctgstats.h.
#define CTG_STAT_ERR_NULLRSTOKPTR -125 |
The specified result set token pointer was found to be NULL.
Definition at line 837 of file ctgstats.h.
#define CTG_STAT_ERR_NULLSTATDATAPTR -129 |
The specified CTG_StatData_t pointer was found to be NULL.
Definition at line 853 of file ctgstats.h.
#define CTG_STAT_ERR_NULLVERSPTR -105 |
The pointer provided to store the protocol version from the API call was NULL.
Definition at line 750 of file ctgstats.h.
#define CTG_STAT_ERR_PIDMISMATCH -123 |
The process that has attempted to use the Gateway token or API owned result set is different to the one that created it.
Definition at line 828 of file ctgstats.h.
#define CTG_STAT_ERR_TIDMISMATCH -124 |
The thread that has attempted to use the Gateway token or API owned result set is different to the one that created it.
Definition at line 833 of file ctgstats.h.
#define CTG_STAT_ERR_TRACEFILE -130 |
The API was unable to create a trace file at the specified location.
Definition at line 858 of file ctgstats.h.
#define CTG_STAT_ERR_TRACELEVEL -104 |
An invalid trace level was provided to setAPITraceLevel().
Definition at line 745 of file ctgstats.h.
#define CTG_STAT_NULL_GWTOK NULL |
NULL Gateway daemon token.
Definition at line 915 of file ctgstats.h.
#define CTG_STAT_NULL_RSTOK NULL |
NULL result set token.
Definition at line 919 of file ctgstats.h.
#define CTG_STAT_OK 0 |
The API call completed successfully.
Definition at line 722 of file ctgstats.h.
#define CTG_STAT_TRACE_LEVEL0 0 |
Trace level 0 disables all tracing.
Definition at line 892 of file ctgstats.h.
#define CTG_STAT_TRACE_LEVEL1 1 |
Trace level 1 includes exception trace points only.
Definition at line 896 of file ctgstats.h.
#define CTG_STAT_TRACE_LEVEL2 2 |
Trace level 2 includes event trace points and lower trace levels.
Definition at line 901 of file ctgstats.h.
#define CTG_STAT_TRACE_LEVEL3 3 |
Trace level 3 includes entry/exit trace points and lower trace levels.
Definition at line 906 of file ctgstats.h.
#define CTG_STAT_TRACE_LEVEL4 4 |
Trace level 4 includes debug trace points and lower trace levels.
Definition at line 911 of file ctgstats.h.
Typedef Documentation
typedef struct _CTG_GatewayToken_t* CTG_GatewayToken_t |
CTG_GatewayToken_t represents a connection to a specific Gateway daemon.
Definition at line 42 of file ctgstats.h.
typedef struct _CTG_ResultSetToken_t* CTG_ResultSetToken_t |
CTG_ResultSetToken_t represents the results of an API call to obtain id or statistic data.
It also maintains position in the result position for getFirst/getNext use.
Definition at line 49 of file ctgstats.h.
Function Documentation
int closeAllGatewayConnections | ( | ) |
Attempts to free all resources held by the API, including open Gateway daemon connections.
This function may be used by the API program under normal shutdown circumstances, or in the event of a severe error, enabling some form of controlled shutdown even when references to gateway tokens have been lost. Note: Copied result sets will not be freed, since the API does not maintain a record of copied result sets.
- Returns
- Indication whether the call was successful or not.
Possible values include
int closeGatewayConnection | ( | CTG_GatewayToken_t * | gwTokPtr | ) |
Closes the connection to the Gateway daemon associated with the specified Gateway token.
Upon successful completion, resources associated with the Gateway daemon connection will be released. Note: Copied result sets will not be freed, since the API does not maintain a record of copied result sets.
- Parameters
-
gwTokPtr The reference to the open Gateway connection
- Returns
- Indication whether the call was successful or not.
Possible values include
int copyResultSet | ( | CTG_ResultSetToken_t | srcRsTok, |
CTG_ResultSetToken_t * | tarRsTokPtr | ||
) |
Takes a result set token as a source, and a result set token pointer as a target.
Duplicates a result set. Upon return, the target result set token will represent an "application-owned" copy of the source result set. This may be desirable if multiple API calls are to be performed before processing of the results. An application-owned result set may be parsed with the appropriate result set functions in exactly the same way as an API-owned result set. Note: It is the responsibility of the caller to free all duplicated result sets, using the freeResultSet function.
- Parameters
-
srcRsTok is a CTG_ResultSetToken_t variable, populated by one of the id or statistics API functions. tarRsTokPtr pointer to a CTG_ResultSetToken_t struct to populate.
- Returns
- Indication whether the call was successful or not.
Possible values include
int dumpResultSet | ( | CTG_ResultSetToken_t | rsTok | ) |
Takes a result set token and writes a representation of that result set in printable characters to the current trace destination, irrespective of trace settings.
For debug purposes only.
- Parameters
-
rsTok Token for result set to dump.
- Returns
- Indication whether the call was successful or not.
Possible values include
int dumpState | ( | ) |
Writes internal API debugging information to the trace destination, irrespective of trace settings.
For debug purposes only.
- Returns
- Indication whether the call was successful or not.
Possible values include
int freeResultSet | ( | CTG_ResultSetToken_t * | rsTokPtr | ) |
Takes a result set token pointer for an application-owned result set, created by copyResultSet(), and frees the storage associated with that result set.
Upon return, the result set token will be set to NULL. Note: Any attempt to free an API-owned result set will return an error.
- Parameters
-
rsTokPtr pointer to an application-owned result set.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getAPITraceLevel | ( | int * | traceStatePtr | ) |
Takes a pointer to an int variable, and sets that variable to the current API trace level.
Valid values are (defined in ctgstats.h), and are
- CTG_STAT_TRACE_LEVEL0 = Disable all trace,
- CTG_STAT_TRACE_LEVEL1 = Exception trace,
- CTG_STAT_TRACE_LEVEL2 = Event trace,
- CTG_STAT_TRACE_LEVEL3 = Entry/exit trace,
- CTG_STAT_TRACE_LEVEL4 = Debug trace
- Parameters
-
traceStatePtr pointer to the int to set with API trace status.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getFirstId | ( | CTG_ResultSetToken_t | idRsTok, |
CTG_IdData_t * | idDataPtr | ||
) |
Takes an id result set token and populates a CTG_IdData_t variable with details of the first id in the set.
If the result set is empty or unpopulated, the CTG_IdData_t variable will be unchanged.
- Parameters
-
idRsTok is a CTG_ResultSetToken_t variable, populated by one of the id API functions. idDataPtr pointer to the CTG_IdData_t variable to populate.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getFirstStat | ( | CTG_ResultSetToken_t | statRsTok, |
CTG_StatData_t * | statDataPtr | ||
) |
Takes a Stat result set token and populates a CTG_StatData_t variable with details of the first statistic in the set.
If the result set is empty or unpopulated, the CTG_StatData_t variable will be unchanged.
- Parameters
-
statRsTok is a CTG_ResultSetToken_t variable, populated by one of the statistics API functions. statDataPtr pointer to the CTG_StatData_t variable to populate.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getIdQuery | ( | CTG_ResultSetToken_t | anyRsTok, |
char ** | idQueryPtr | ||
) |
Takes a result set token and the address of a char pointer.
The pointer is set to point at a null-terminated string containing the set of valid StatIds in the given result set. The set of StatIds are in the format required for direct use as a query string. The string storage is owned by the API, and the pointer remains valid until the connection to the associated Gateway daemon has been closed (for API owned result sets) or the result set has been freed (for user owned result sets).
- Parameters
-
anyRsTok is a CTG_ResultSetToken_t variable, populated by one of the statistic or id API functions. idQueryPtr pointer to the IdType variable to populate.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getNextId | ( | CTG_ResultSetToken_t | idRsTok, |
CTG_IdData_t * | idDataPtr | ||
) |
Takes an id result set and populates an CTG_IdData_t variable with details of the next id in the set.
If there are no further ids in the result set, the CTG_IdData_t variable will be unchanged.
- Parameters
-
idRsTok is a CTG_ResultSetToken_t variable, populated by one of the id API functions. idDataPtr pointer to the CTG_IdData_t variable to populate.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getNextStat | ( | CTG_ResultSetToken_t | statRsTok, |
CTG_StatData_t * | statDataPtr | ||
) |
Takes a Stat result set token and populates a CTG_StatData_t variable with details of the next StatId in the set.
If there are no further StatIds in the result set, the CTG_StatData_t variable will be unchanged.
- Parameters
-
statRsTok is a CTG_ResultSetToken_t variable, populated by one of the statistics API functions. statDataPtr pointer to the CTG_StatData_t variable to populate.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getResourceGroupIds | ( | CTG_GatewayToken_t | gwTok, |
CTG_ResultSetToken_t * | resgrpIdRsTokPtr | ||
) |
Takes a gateway token and a result set token pointer.
Upon return, the result set token will represent the set of resource group ids currently available for the specified Gateway daemon. The result set may be parsed with functions getFirstId() and getNextId(), or used to generate a query string with getIdQuery(). Note: Depending upon when getResourceGroupIds() is called, dynamic resource groups for specific CICS server may or may not be returned in the list. The list of server resource group ids may be obtained directly via the appropriate resource group id. Note: The caller may decide to take a local copy of the result set, since it will be recycled on the next API call for the same gwTok.
- Parameters
-
gwTok The reference to the open Gateway connection. resgrpIdRsTokPtr A pointer to a CTG_ResultSetToken_t variable.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getStatIds | ( | CTG_GatewayToken_t | gwTok, |
CTG_ResultSetToken_t * | statIdRsTokPtr | ||
) |
Takes a gateway token and a result set token pointer.
Upon return, the result set token will represent the set of all available StatIds on the specified gateway. The result set may be parsed with functions getFirstId() and getNextId(), or used to generate a query string with getIdQuery(). Note: The caller may decide to take a local copy of the result set, since it will be recycled on the next API call for the same gwTok.
- Parameters
-
gwTok The reference to the open Gateway connection. statIdRsTokPtr pointer to a CTG_ResultSetToken_t struct, to be populated with details of the result.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getStatIdsByStatGroupId | ( | CTG_GatewayToken_t | gwTok, |
char * | idQueryPtr, | ||
CTG_ResultSetToken_t * | statIdRsTokPtr | ||
) |
Takes a gateway token, a query string of StatGroupIds and a result set token pointer.
Upon return, the result set token will represent the set of statistic ids associated with the given query string, for the specified Gateway daemon. The result set may be parsed with functions getFirstId() and getNextId(), or used to generate a query string with getIdQuery(). If the query string is the empty string, then StatIds for all available StatGroupIds will be returned. Note: The caller may decide to take a local copy of the result set, since it will be recycled on the next API call for the same gwTok.
- Parameters
-
gwTok The reference to the open Gateway connection. idQueryPtr pointer to a null-terminated string containing StatGroupIds. statIdRsTokPtr pointer to a CTG_ResultSetToken_t struct, to be populated with details of the result.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getStats | ( | CTG_GatewayToken_t | gwTok, |
CTG_ResultSetToken_t * | statRsTokPtr | ||
) |
Takes a gateway token, a query string of StatIds and a result set token pointer.
Upon return, the result set token will represent the set of Stat name/value pairs corresponding to the query string. Note: The caller may decide to take a local copy of the result set, since it will be recycled on the next API call for the same gwTok.
- Parameters
-
gwTok The reference to the open Gateway connection. statRsTokPtr pointer to a CTG_ResultSetToken_t variable to be populated with details of the result.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getStatsAPIVersion | ( | char ** | apiVersPtr | ) |
Takes the address of a character pointer to be modified.
Upon return, apiVersPtr will point to a null-terminated string representing the version (n_n_n_n) of the active ctgstats library. The string storage is owned by the API.
- Parameters
-
apiVersPtr The address of a character pointer to be modified. In the event of an error, apiVersPtr will be unchanged.
- Returns
- Indication whether the call was successful or not.
Possible values include
int getStatsByStatGroupId | ( | CTG_GatewayToken_t | gwTok, |
char * | idQueryPtr, | ||
CTG_ResultSetToken_t * | statRsTokPtr | ||
) |
Takes a gateway token, a query string of StatGroupIds and a result set token.
Upon return, the result set token will represent the set of statistic name/value pairs corresponding to the query string. If the query string is the empty string, then Stats for all available StatGroupIds will be returned. Note: The caller may decide to take a local copy of the result set, since it will be recycled on the next API call for the same gwTok.
- Parameters
-
gwTok The reference to the open Gateway connection. idQueryPtr pointer to a null-terminated string of comma separated StatGroupIds. statRsTokPtr pointer to a CTG_ResultSetToken_t struct, to be populated with details of the result
- Returns
- Indication whether the call was successful or not.
Possible values include
int getStatsByStatId | ( | CTG_GatewayToken_t | gwTok, |
char * | idQueryPtr, | ||
CTG_ResultSetToken_t * | statRsTokPtr | ||
) |
Takes a gateway token, a query string of StatIds and a result set token pointer.
Upon return, the result set token will represent the set of statistic name/value pairs corresponding to the query string. If the query string is the empty string, then Stats for all available StatIds will be returned. Note: The caller may decide to take a local copy of the result set, since it will be recycled on the next API call for the same gwTok.
- Parameters
-
gwTok The reference to the open Gateway connection. idQueryPtr pointer to a null-terminated string of comma separated StatGroupIds. statRsTokPtr pointer to a CTG_ResultSetToken_t struct, to be populated with details of the result.
- Returns
- Indication whether the call was successful or not.
Possible values include
int openGatewayConnection | ( | int | port, |
CTG_GatewayToken_t * | gwTokPtr, | ||
char ** | protocolVersPtr | ||
) |
Establishes a connection to a local Gateway daemon statistics protocol handler using the specified port number.
If successful, upon return the gateway token will represent the connection to the specified Gateway daemon and will be required to interact with that Gateway daemon on further API calls. protocolVersPtr will point to a null-terminated string representing the protocol version (n_n_n_n) of the statistics data supplied by the connected Gateway daemon. The string storage is owned by the API, and the pointer remains valid until the connection to the associated Gateway daemon has been closed.
- Parameters
-
port An int for the statistics port of the target Gateway daemon. gwTokPtr Pointer to an int for the new Gateway Token. protocolVersPtr The address of a character pointer to be modified.
- Returns
- Indication whether the call was successful or not.
Possible values include
int openRemoteGatewayConnection | ( | char * | address, |
int | port, | ||
CTG_GatewayToken_t * | gwTokPtr, | ||
char ** | protocolVersPtr | ||
) |
Establishes a connection to a Gateway daemon statistics protocol handler using the specified hostname and port number.
If successful, upon return the gateway token will represent the connection to the specified Gateway daemon and will be required to interact with that Gateway daemon on further API calls. protocolVersPtr will point to a null-terminated string representing the protocol version (n_n_n_n) of the statistics data supplied by the connected Gateway daemon. The string storage is owned by the API, and the pointer remains valid until the connection to the associated Gateway daemon has been closed.
- Parameters
-
address The character string containing the hostname or IP address of the target Gateway daemon. port An int for the statistics port of the target Gateway daemon. gwTokPtr Pointer to an int for the new Gateway Token. protocolVersPtr The address of a character pointer to be modified.
- Returns
- Indication whether the call was successful or not.
Possible values include- CTG_STAT_OK
- CTG_STAT_ERR_LOCKFAIL
- CTG_STAT_ERR_MALLOCFAIL
- CTG_STAT_ERR_ICONV
- CTG_STAT_ERR_BADPORT
- CTG_STAT_ERR_NULLVERSPTR
- CTG_STAT_ERR_BADRSOWNER
- CTG_STAT_ERR_CONNECTFAILED
- CTG_STAT_ERR_BADGWTOKLIST
- CTG_STAT_ERR_NULLGWTOKPTR
- CTG_STAT_ERR_NULLPARM
- CTG_STAT_ERR_LOSTGWCON
- CTG_STAT_ERR_COMMSFAIL
- CTG_STAT_ERR_BADHOST
- CTG_STAT_ERR_NULLADDRESS
int setAPITraceFile | ( | char * | traceFileNamePtr | ) |
Takes a character pointer to a null-terminated string representing the desired trace file destination.
If the specified file already exists, trace data will be appended. If the API is unable to open the specified filename for writing, then the trace destination will remain unchanged. Specifying a NULL pointer will cause the trace destination to revert to the default destination of stderr.
- Parameters
-
traceFileNamePtr char pointer to a null-terminated string representing the desired trace path and filename.
- Returns
- Indication whether the call was successful or not.
Possible values include
int setAPITraceLevel | ( | int | traceState | ) |
Takes an int variable representing the desired trace level and sets the API trace level accordingly.
The default trace destination will stderr, but this may be overridden by the API function setAPITraceFile(). Valid values are (defined in ctgstats.h), and are
- CTG_STAT_TRACE_LEVEL0 = Disable all trace,
- CTG_STAT_TRACE_LEVEL1 = Exception trace,
- CTG_STAT_TRACE_LEVEL2 = Event trace,
- CTG_STAT_TRACE_LEVEL3 = Entry/exit trace,
- CTG_STAT_TRACE_LEVEL4 = Debug trace
- Parameters
-
traceState int containing required API trace status.
- Returns
- Indication whether the call was successful or not. Possible values include