source/h/ctgclient.h File Reference

Defines functions and typedefs for connecting to a Gateway daemon and controlling API tracing. More...

#include <stddef.h>

Go to the source code of this file.

Data Structures

Defines

Typedefs

Functions


Detailed Description

Defines functions and typedefs for connecting to a Gateway daemon and controlling API tracing.

Definition in file ctgclient.h.


Define Documentation

#define CICSCALL
 

Definition at line 55 of file ctgclient.h.

#define CTG_API_VERSION   "2.1.0.0"
 

CICS TG ECI V2 the API version identifier.

This is the version of the API and should not be confused with the ECI Version that is included in the ECI parameter block field eci_version.

Definition at line 64 of file ctgclient.h.

#define CTG_DLL_VERSION   "8.0.0.1"
 

CICS TG ECI V2 the DLL version identifier.

This is the build version of the DLL and should not be confused with the API Version.

Definition at line 69 of file ctgclient.h.

#define CTG_ERR_BADGWTOK   -101
 

The Gateway token was not recognized by the Client API.

The token is either not valid, or the connection to the Gateway daemon has been lost and the token deleted.

Definition at line 447 of file ctgclient.h.

#define CTG_ERR_BADGWTOKLIST   -115
 

Internal error with the Gateway token list.

Definition at line 481 of file ctgclient.h.

#define CTG_ERR_BADHOST   -132
 

The hostname did not resolve to a valid IP address.

Definition at line 513 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 464 of file ctgclient.h.

#define CTG_ERR_CONNECTFAILED   -118
 

Failed to establish a connection with the Gateway daemon.

Definition at line 485 of file ctgclient.h.

#define CTG_ERR_CONNECTTIMEOUT   -134
 

The connection timed out.

Definition at line 521 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 555 of file ctgclient.h.

#define CTG_ERR_GATEWAY_CLOSED   0xF004
 

The Gateway daemon is closing.

Definition at line 537 of file ctgclient.h.

#define CTG_ERR_GATEWAY_EXCEPTION   0xF006
 

An internal exception occurred in the Gateway daemon.

Definition at line 546 of file ctgclient.h.

#define CTG_ERR_INVALID_DATA_LENGTH   -1
 

The data length was not valid.

Definition at line 427 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.

Definition at line 560 of file ctgclient.h.

#define CTG_ERR_INVALIDTIMEOUTPARM   -138
 

The timeout parameter is not in the range 0 through 3000.

Definition at line 529 of file ctgclient.h.

#define CTG_ERR_LOCKFAIL   -121
 

Internal error during lock creation.

Definition at line 493 of file ctgclient.h.

#define CTG_ERR_LOSTGWCON   -102
 

The connection to the Gateway daemon has been lost.

Definition at line 451 of file ctgclient.h.

#define CTG_ERR_MALLOCFAIL   -111
 

The API was unable to allocate sufficient memory to complete the operation.

Definition at line 477 of file ctgclient.h.

#define CTG_ERR_MORE_SYSTEMS   -25
 

There are more systems to return than were requested.

Definition at line 433 of file ctgclient.h.

#define CTG_ERR_NO_SYSTEMS   -26
 

There are no servers known to the Gateway daemon.

Definition at line 436 of file ctgclient.h.

#define CTG_ERR_NULLADDRESS   -133
 

The hostname is NULL.

Definition at line 517 of file ctgclient.h.

#define CTG_ERR_NULLECIPOINTER   -137
 

The ECI parameter block pointer is NULL.

Definition at line 525 of file ctgclient.h.

#define CTG_ERR_NULLGWTOK   -100
 

The Gateway token is NULL.

Definition at line 441 of file ctgclient.h.

#define CTG_ERR_NULLGWTOKPTR   -108
 

The Gateway token pointer is NULL.

Definition at line 468 of file ctgclient.h.

#define CTG_ERR_NULLPARM   -103
 

One of the parameters is NULL.

Definition at line 455 of file ctgclient.h.

#define CTG_ERR_NULLPTR   -109
 

The pointer is NULL.

Definition at line 472 of file ctgclient.h.

#define CTG_ERR_PIDMISMATCH   -123
 

The Gateway token does not belong to this process.

Definition at line 501 of file ctgclient.h.

#define CTG_ERR_SYSTEM_ERROR   -9
 

An internal system error has occurred.

Definition at line 430 of file ctgclient.h.

#define CTG_ERR_TIDMISMATCH   -124
 

The Gateway token does not belong to this thread.

Definition at line 505 of file ctgclient.h.

#define CTG_ERR_TRACEFILE   -130
 

Unable to create a trace file at the specified location.

Definition at line 509 of file ctgclient.h.

#define CTG_ERR_TRACELEVEL   -104
 

The trace level is not valid.

Definition at line 459 of file ctgclient.h.

#define CTG_ERR_UNKNOWN_REQUEST_TYPE   0xF002
 

The request type is not recognized by the Gateway daemon.

Definition at line 533 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 542 of file ctgclient.h.

#define CTG_LIST_DESCRIPTION_LENGTH   60
 

Definition at line 369 of file ctgclient.h.

#define CTG_LIST_SYSTEM_LENGTH   8
 

Definition at line 359 of file ctgclient.h.

#define CTG_MAX_RCSTRING   40
 

The maximum length of a string returned by CTG_getRcString.

Definition at line 74 of file ctgclient.h.

#define CTG_NULL_GWTOK   NULL
 

Null Gateway daemon token.

Definition at line 77 of file ctgclient.h.

#define CTG_OK   0
 

The API call completed successfully.

Definition at line 424 of file ctgclient.h.

#define CTG_TRACE_LEVEL0   0
 

Trace level 0 disables all tracing.

Definition at line 568 of file ctgclient.h.

#define CTG_TRACE_LEVEL1   1
 

Trace level 1 includes exception trace points only.

Definition at line 572 of file ctgclient.h.

#define CTG_TRACE_LEVEL2   2
 

Trace level 2 includes event trace points + lower trace levels.

Definition at line 577 of file ctgclient.h.

#define CTG_TRACE_LEVEL3   3
 

Trace level 3 includes entry/exit trace points + lower trace levels.

Definition at line 582 of file ctgclient.h.

#define CTG_TRACE_LEVEL4   4
 

Trace level 4 includes debug trace points + lower trace levels.

Definition at line 587 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 88 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.

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.

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:
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 will only change when the API changes.

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 free'd 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 free'd 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).

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 ECI version 2 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.

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

void CTG_setAPITraceDataLength size_t  dataLength  ) 
 

Sets the maximum length of data that is displayed in ECI 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 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 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:
Returns:
An integer value identifies whether the call was successful or not.
Possible values include


© Copyright IBM Corporation 2006, 2010. All rights reserved.
For legal information, see http://www.ibm.com/legal/copytrade.shtml