#include <stddef.h>
Go to the source code of this file.
Data Structures | |
struct | CTG_listSystem_t |
The data for a server as returned from calling CTG_listSystems. More... | |
Typedefs | |
typedef struct _CTG_ConnToken_t * | CTG_ConnToken_t |
Functions | |
int | CTG_openRemoteGatewayConnection (char *address, int port, CTG_ConnToken_t *gwTokPtr, int connTimeout) |
int | CTG_openRemoteGatewayConnectionApplid (char *address, int port, CTG_ConnToken_t *gwTokPtr, int connTimeout, char *applid, char *applidQualifier) |
int | CTG_closeGatewayConnection (CTG_ConnToken_t *gwTokPtr) |
int | CTG_purgeGatewayConnection (CTG_ConnToken_t *gwTokPtr, int closeTimeout) |
int | CTG_closeAllGatewayConnections () |
int | CTG_getAPITraceLevel (int *traceStatePtr) |
int | CTG_setAPITraceLevel (int traceState) |
int | CTG_setAPITraceFile (char *traceFileNamePtr) |
void | CTG_setAPITraceDataLength (size_t dataLength) |
void | CTG_setAPITraceDataOffset (size_t dataOffset) |
int | CTG_dumpState () |
char * | CTG_getRcString (int returnCode, char *rcString) |
int | CTG_getAPIVersion (char **apiVersPtr) |
int | CTG_getDLLVersion (char **dllVersPtr) |
int | CTG_getApplid (CTG_ConnToken_t gwTok, char **applid) |
int | CTG_getApplidQualifier (CTG_ConnToken_t gwTok, char **applidQualifier) |
int | CTG_listSystems (CTG_ConnToken_t gwTok, unsigned short *Systems, CTG_listSystem_t *List) |
Detailed Description
Defines functions and typedefs for connecting to a Gateway daemon and controlling API tracing.
Definition in file ctgclient.h.
Macro Definition Documentation
#define CICSCALL |
Definition at line 57 of file ctgclient.h.
#define CTG_API_VERSION "2.3.0.0" |
CICS TG ECI and ESI V2 API version identifier.
This is the version of the API. An application can query the API version at run time to check that it has been deployed with a compatible CICS TG API library.
Definition at line 66 of file ctgclient.h.
#define CTG_DLL_VERSION "9.0.0.0" |
CICS TG ECI and ESI V2 DLL version identifier.
This is the build version of the DLL. An application can query the DLL version at run time and record the version for maintenance or problem determination.
Definition at line 72 of file ctgclient.h.
#define CTG_ERR_APPLIDTOOLONG -139 |
The connection failed because the Applid or Applid Qualifier is greater than 8 characters in length.
Definition at line 687 of file ctgclient.h.
#define CTG_ERR_BADGWTOK -101 |
The Gateway token is not valid.
This might be because the connection to the Gateway daemon has been lost and the token deleted.
Definition at line 599 of file ctgclient.h.
#define CTG_ERR_BADGWTOKLIST -115 |
- Deprecated:
- No longer used.
Definition at line 634 of file ctgclient.h.
#define CTG_ERR_BADHOST -132 |
The hostname did not resolve to a valid IP address.
Definition at line 666 of file ctgclient.h.
#define CTG_ERR_BADPORT -107 |
The port number is not valid.
Port numbers must be in the range 1 through 65535.
Definition at line 616 of file ctgclient.h.
#define CTG_ERR_COMMSFAIL -122 |
- Deprecated:
- No longer used.
Definition at line 650 of file ctgclient.h.
#define CTG_ERR_CONNECTFAILED -118 |
Failed to establish a connection with the Gateway daemon.
Definition at line 638 of file ctgclient.h.
#define CTG_ERR_CONNECTTIMEOUT -134 |
The connection timed out.
Definition at line 674 of file ctgclient.h.
#define CTG_ERR_GATEWAY_BACK_LEVEL 0xF00A |
The connection failed because the Gateway daemon is at an earlier product release than the Client application.
Definition at line 721 of file ctgclient.h.
#define CTG_ERR_GATEWAY_CLOSED 0xF004 |
The connection to the Gateway daemon is closed.
This occurs when the Gateway daemon is shut down.
Definition at line 701 of file ctgclient.h.
#define CTG_ERR_GATEWAY_EXCEPTION 0xF006 |
An internal exception occurred in the Gateway daemon.
If the problem persists, collect Gateway daemon trace and contact your IBM service representative.
Definition at line 712 of file ctgclient.h.
#define CTG_ERR_GWTOK_CLOSED -140 |
The Gateway token has been closed and no new work can be sent to the Gateway daemon.
Definition at line 692 of file ctgclient.h.
#define CTG_ERR_ICONV -120 |
- Deprecated:
- No longer used.
Definition at line 642 of file ctgclient.h.
#define CTG_ERR_INVALID_DATA_LENGTH -1 |
- Deprecated:
- No longer used.
Definition at line 575 of file ctgclient.h.
#define CTG_ERR_INVALID_REQUEST_TYPE 0xF00B |
The protocol handler for the port that the Client application is connected to does not accept the request type sent.
This can occur if your application connects to the Gateway daemon statistics port instead of the TCP/IP port.
Definition at line 727 of file ctgclient.h.
#define CTG_ERR_INVALIDTIMEOUTPARM -138 |
The timeout parameter is not in the range 0 through 3600.
Definition at line 682 of file ctgclient.h.
#define CTG_ERR_LOCKFAIL -121 |
- Deprecated:
- No longer used.
Definition at line 646 of file ctgclient.h.
#define CTG_ERR_LOSTGWCON -102 |
The connection to the Gateway daemon has been lost.
Definition at line 603 of file ctgclient.h.
#define CTG_ERR_MALLOCFAIL -111 |
The API was unable to allocate sufficient memory to complete the operation.
If the problem persists, contact your IBM service representative.
Definition at line 630 of file ctgclient.h.
#define CTG_ERR_MORE_SYSTEMS -25 |
There are more systems to return than were requested.
The total number of systems is returned in the Systems parameter.
Definition at line 586 of file ctgclient.h.
#define CTG_ERR_NO_SYSTEMS -26 |
There are no servers known to the Gateway daemon.
Definition at line 590 of file ctgclient.h.
#define CTG_ERR_NOT_AUTHORIZED 0xF007 |
- Deprecated:
- No longer used.
Definition at line 716 of file ctgclient.h.
#define CTG_ERR_NULLADDRESS -133 |
The hostname is NULL.
Definition at line 670 of file ctgclient.h.
#define CTG_ERR_NULLECIPOINTER -137 |
The ECI parameter block pointer is NULL.
Definition at line 678 of file ctgclient.h.
#define CTG_ERR_NULLGWTOK -100 |
The Gateway token is NULL.
Definition at line 594 of file ctgclient.h.
#define CTG_ERR_NULLGWTOKPTR -108 |
The Gateway token pointer is NULL.
Definition at line 620 of file ctgclient.h.
#define CTG_ERR_NULLPARM -103 |
One of the parameters is NULL.
Definition at line 607 of file ctgclient.h.
#define CTG_ERR_NULLPTR -109 |
The pointer is NULL.
Definition at line 624 of file ctgclient.h.
#define CTG_ERR_PIDMISMATCH -123 |
- Deprecated:
- No longer used.
Definition at line 654 of file ctgclient.h.
#define CTG_ERR_SYSTEM_ERROR -9 |
An internal system error has occurred.
If the problem persists, collect application and Gateway daemon trace and contact your IBM service representative.
Definition at line 581 of file ctgclient.h.
#define CTG_ERR_TIDMISMATCH -124 |
- Deprecated:
- No longer used.
Definition at line 658 of file ctgclient.h.
#define CTG_ERR_TRACEFILE -130 |
Unable to create a trace file at the specified location.
Definition at line 662 of file ctgclient.h.
#define CTG_ERR_TRACELEVEL -104 |
The trace level is not valid.
Definition at line 611 of file ctgclient.h.
#define CTG_ERR_UNKNOWN_REQUEST_TYPE 0xF002 |
- Deprecated:
- No longer used.
Definition at line 696 of file ctgclient.h.
#define CTG_ERR_WORK_WAS_REFUSED 0xF005 |
The Gateway daemon refused the request because no worker threads were available or the Gateway daemon is closing.
Definition at line 706 of file ctgclient.h.
#define CTG_LIST_DESCRIPTION_LENGTH 60 |
Definition at line 520 of file ctgclient.h.
#define CTG_LIST_SYSTEM_LENGTH 8 |
Definition at line 511 of file ctgclient.h.
#define CTG_MAX_RCSTRING 40 |
The maximum length of a string returned by CTG_getRcString.
Definition at line 76 of file ctgclient.h.
#define CTG_NULL_GWTOK NULL |
Null Gateway daemon token.
Definition at line 79 of file ctgclient.h.
#define CTG_OK 0 |
The API call completed successfully.
Definition at line 571 of file ctgclient.h.
#define CTG_TRACE_LEVEL0 0 |
Trace level 0 disables all tracing.
Definition at line 735 of file ctgclient.h.
#define CTG_TRACE_LEVEL1 1 |
Trace level 1 includes exception trace points only.
Definition at line 739 of file ctgclient.h.
#define CTG_TRACE_LEVEL2 2 |
Trace level 2 includes event trace points + lower trace levels.
Definition at line 744 of file ctgclient.h.
#define CTG_TRACE_LEVEL3 3 |
Trace level 3 includes entry/exit trace points + lower trace levels.
Definition at line 749 of file ctgclient.h.
#define CTG_TRACE_LEVEL4 4 |
Trace level 4 includes debug trace points + lower trace levels.
Definition at line 754 of file ctgclient.h.
Typedef Documentation
typedef struct _CTG_ConnToken_t* CTG_ConnToken_t |
CTG_ConnToken_t represents a connection to a specific Gateway daemon.
Definition at line 90 of file ctgclient.h.
Function Documentation
int CTG_closeAllGatewayConnections | ( | ) |
Attempts to free all resources held by the API, including open Gateway connections.
This function is provided to be called in the event of a severe application error, enabling some form of controlled shutdown even if all Gateway tokens have been lost.
Any outstanding ECI_GET_REPLY_WAIT and ECI_GET_SPECIFIC_REPLY_WAIT calls end with CTG_ERR_GWTOK_CLOSED. No new calls can be issued on any Gateway token after the close process has started.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_closeGatewayConnection | ( | CTG_ConnToken_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.
When the Gateway token is closed, synchronous requests that are in progress can complete and replies for outstanding asynchronous requests can be retrieved using any of the get reply calls. No new ECI_SYNC, ECI_ASYNC or ESI calls can be issued after the close process has started.
When a Gateway token is closing, and all outstanding replies have been retrieved, any outstanding ECI_GET_REPLY_WAIT calls end with CTG_ERR_GWTOK_CLOSED.
This function waits until all synchronous requests are complete and all replies have been retrieved.
- Parameters
-
[in] gwTokPtr The reference to the open Gateway connection
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_dumpState | ( | ) |
Writes CICS TG internal debugging information to the trace destination.
The debug information is written irrespective of trace settings.
- Note
- The IBM service organization may request that this function is used to aid problem determination.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_getAPITraceLevel | ( | int * | traceStatePtr | ) |
Get the current trace level.
Takes a pointer to an int variable, and sets that variable to the current API trace level.
- Parameters
-
[out] traceStatePtr output value, a pointer to an int variable that is set with API trace status.
Valid values are defined in ctgclient.h they are:- CTG_TRACE_LEVEL0 = Disable all trace
- CTG_TRACE_LEVEL1 = Exception trace
- CTG_TRACE_LEVEL2 = Event trace
- CTG_TRACE_LEVEL3 = Entry/exit trace
- CTG_TRACE_LEVEL4 = Debug trace
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_getAPIVersion | ( | char ** | apiVersPtr | ) |
Gets the API version.
This can be used to determine the capabilities of the API:
- Version 2.0 is provided with CICS TG V7.2 and supports synchronous ECI requests with a COMMAREA.
- Version 2.1 is provided with CICS TG V8.0 and introduces support for synchronous ECI requests with a channel.
- Version 2.2 is provided with CICS TG V8.1 and introduces support for password phrases and synchronous ESI verify and change requests.
- Version 2.3 is provided with CICS TG V9.0 and introduces support for asynchronous ECI requests with a COMMAREA or a channel.
- Parameters
-
[out] *apiVersPtr a pointer to the api version string. The returned string (returned in the pointer) is owned by the API, and should not be freed by the application.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_getApplid | ( | CTG_ConnToken_t | gwTok, |
char ** | applid | ||
) |
Gets the APPLID.
- Parameters
-
[in] gwTok The reference to the open Gateway connection [out] *applid a pointer to the APPLID string. The returned string (returned in the pointer) is owned by the API, and should not be freed by the application.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_getApplidQualifier | ( | CTG_ConnToken_t | gwTok, |
char ** | applidQualifier | ||
) |
Gets the APPLID qualifier.
- Parameters
-
[in] gwTok The reference to the open Gateway connection [out] *applidQualifier a pointer to the APPLID qualifier string. The returned string (returned in the pointer) is owned by the API, and should not be freed by the application.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_getDLLVersion | ( | char ** | dllVersPtr | ) |
Gets the DLL version.
This will change when the build level changes.
- Parameters
-
[out] *dllVersPtr a pointer to the dll version string. The returned string (returned in the pointer) is owned by the API, and should not be freed by the application.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
char* CTG_getRcString | ( | int | returnCode, |
char * | rcString | ||
) |
Gets the string representation of the return code.
- Parameters
-
[in] returnCode an integer value for naming. [out] rcString a string identifier naming the return code.
- Returns
- a pointer to rcString.
int CTG_listSystems | ( | CTG_ConnToken_t | gwTok, |
unsigned short * | Systems, | ||
CTG_listSystem_t * | List | ||
) |
CTG_listSystems returns a list of all the systems known to the Gateway, including IPIC and logical CICS servers (only available on z/OS).
Logical servers can be identified by a prefix of (LS) in the Description field. Although the list of systems are known to the Gateway there is no guarantee that a communications link exists or that any of the servers is available to process requests.
- Parameters
-
[in] gwTok The reference to the open Gateway connection. Systems Used for input and output, on input the maximum number of systems allowed for in List, on return the actual number of systems found. [out] List on return, the reference to an array of CTG_ListSystem_t structures containing the system names and descriptions.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_openRemoteGatewayConnection | ( | char * | address, |
int | port, | ||
CTG_ConnToken_t * | gwTokPtr, | ||
int | connTimeout | ||
) |
Establish a remote connection to a Gateway daemon.
This function takes a character pointer for the hostname, an integer for the target port number and a pointer to a Gateway token and an integer for the connection timeout. It establishes a connection to a Gateway daemon Client protocol handler using the specified hostname and port number. If the return code is successful the Gateway token represents the connection to the specified Gateway daemon, this Gateway token is required as an input parameter for the other API calls.
This API supports CICS TG remote mode operation. The CICS TG "local" protocol for local mode operation is not supported.
The environment variables CTG_APPLID and CTG_APPLIDQUALIFIER can be used to set the APPLID and APPLID qualifier of the application. The application APPLID and APPLID qualifier can be used for transaction tracking in the Gateway daemon and in CICS.
- Parameters
-
[in] address The character string containing the hostname or IP address of the target Gateway daemon. [in] port An int for the port of the target Gateway daemon. [out] gwTokPtr Pointer to the new Gateway token. [in] connTimeout The connection timeout in seconds, enter 0 for no timeout
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_openRemoteGatewayConnectionApplid | ( | char * | address, |
int | port, | ||
CTG_ConnToken_t * | gwTokPtr, | ||
int | connTimeout, | ||
char * | applid, | ||
char * | applidQualifier | ||
) |
Establish a remote connection to a Gateway daemon.
This function takes a character pointer for the hostname, an integer for the target port number and a pointer to a Gateway token, an integer for the connection timeout and a null terminated string for both the APPLID and APPLID qualifier. It establishes a connection to a Gateway daemon Client protocol handler using the specified hostname and port number. If the return code is successful the Gateway token represents the connection to the specified Gateway daemon, this Gateway token is required as an input parameter for the other API calls.
This API supports CICS TG remote mode operation. The CICS TG "local" protocol for local mode operation is not supported.
If the environment variables CTG_APPLID or CTG_APPLIDQUALIFIER are set, their values override the values of the applid and applidQualifier parameters. The application APPLID and APPLID qualifier can be used for transaction tracking in the Gateway daemon and in CICS.
- Parameters
-
[in] address The character string containing the hostname or IP address of the target Gateway daemon. [in] port An int for the port of the target Gateway daemon. [out] gwTokPtr Pointer to the new Gateway token. [in] connTimeout The connection timeout in seconds, enter 0 for no timeout [in] applid A null terminated character string containing the client APPLID (maximum 8 characters). This parameter is ignored if the CTG_APPLID environment variable is set. [in] applidQualifier A null terminated character string containing the client APPLID qualifier (maximum 8 characters). This parameter is ignored if the CTG_APPLIDQUALIFIER environment variable is set.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_purgeGatewayConnection | ( | CTG_ConnToken_t * | gwTokPtr, |
int | closeTimeout | ||
) |
Forcefully closes the connection to the Gateway daemon associated with the specified Gateway token, optionally allowing time for in progress requests to complete and replies for asynchronous requests to be retrieved.
Upon successful completion, resources associated with the Gateway daemon connection will be released.
The closeTimeout parameter specifies the maximum time, in seconds, to allow for in progress requests to complete and replies for asynchronous requests to be retrieved. During this time, requests that are in progress can complete and replies for asynchronous requests can be retrieved using any of the get reply calls. No further ECI_SYNC, ECI_ASYNC or ESI calls can be issued after the close process has started. The timeout must be between zero and 3600 seconds. If a timeout of zero is specified, the connection is closed immediately.
Once the close timeout period has elapsed or all requests have completed and all asynchronous replies have been retrieved, the connection to the Gateway daemon is closed. Any outstanding ECI_GET_REPLY_WAIT and ECI_GET_SPECIFIC_REPLY_WAIT calls end with CTG_ERR_GWTOK_CLOSED.
- Parameters
-
[in] gwTokPtr The reference to the open Gateway connection [in] closeTimeout The time, in seconds, to allow for in progress requests to complete and replies for asynchronous requests to be retrieved.
- Returns
- An integer value that identifies whether the call was successful.
Possible values include
void CTG_setAPITraceDataLength | ( | size_t | dataLength | ) |
Sets the maximum length of data that is displayed in ECI and ESI version 2 API trace.
The function takes a size_t parameter which specifies the maximum amount of data to trace.
The trace data length can also be specified by setting the environment variable CTG_CLIENT_DATA_LENGTH to a positive numeric value. The environment variable must be set before the application is started. Use of this function overrides any value obtained from the environment variable.
- Note
- The IBM service organization may request that this function is used to aid problem determination.
- Parameters
-
[in] dataLength Maximum length of data to display in trace.
void CTG_setAPITraceDataOffset | ( | size_t | dataOffset | ) |
Sets the offset into data that is displayed in ECI and ESI version 2 API trace.
The function takes a size_t parameter which specifies the offset into the data.
The trace data offset can also be specified by setting the environment variable CTG_CLIENT_DATA_OFFSET to a positive numeric value. The environment variable must be set before the application is started. Use of this function overrides any value obtained from the environment variable.
- Note
- The IBM service organization may request that this function is used to aid problem determination.
- Parameters
-
[in] dataOffset Offset into data to begin tracing.
int CTG_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 is appended. If the API is unable to open the specified file for writing, then the trace destination remains unchanged. Specifying a null pointer causes the trace destination to revert to the default destination of stderr.
The trace file can also be specified by setting the environment variable CTG_CLIENT_TRACE_FILE to a filename. Any path/filename that is valid for the operating system is an acceptable value. The environment variable must be set before the application is started. Use of this function overrides any value obtained from the environment variable.
- Parameters
-
[in] traceFileNamePtr char pointer to a null terminated string representing the desired trace destination, path+filename.
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include
int CTG_setAPITraceLevel | ( | int | traceState | ) |
Set the ECI and ESI version 2 API trace level.
Takes an int variable representing the desired trace level and sets the API trace level accordingly. The default trace destination is stderr, but this can be overridden by the API function CTG_setAPITraceFile().
The API trace level can also be specified by setting the environment variable CTG_CLIENT_TRACE_LEVEL to the trace level required. Valid values are 0 to 4. The environment variable must be set before the application is started. Use of this function overrides any value obtained from the environment variable.
- Parameters
-
[in] traceState an input value, an int variable set to the required trace level.
Valid values are defined in ctgclient.h they are:- CTG_TRACE_LEVEL0 = Disable all trace
- CTG_TRACE_LEVEL1 = Exception trace
- CTG_TRACE_LEVEL2 = Event trace
- CTG_TRACE_LEVEL3 = Entry/exit trace
- CTG_TRACE_LEVEL4 = Debug trace
- Returns
- An integer value identifies whether the call was successful or not.
Possible values include