source/h/ctgclient.h File Reference

Go to the source code of this file.

Data Structures

Defines

Typedefs

Functions


Define Documentation

#define CICSCALL
 

Definition at line 46 of file ctgclient.h.

#define CTG_API_VERSION   "2.0.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 55 of file ctgclient.h.

#define CTG_DLL_VERSION   "7.2.0.2"
 

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 60 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 401 of file ctgclient.h.

#define CTG_ERR_BADGWTOKLIST   -115
 

Internal error with the Gateway token list.

Definition at line 435 of file ctgclient.h.

#define CTG_ERR_BADHOST   -132
 

The hostname did not resolve to a valid IP address.

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

#define CTG_ERR_CONNECTFAILED   -118
 

Failed to establish a connection with the Gateway daemon.

Definition at line 439 of file ctgclient.h.

#define CTG_ERR_CONNECTTIMEOUT   -134
 

The connection timed out.

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

#define CTG_ERR_GATEWAY_CLOSED   0xF004
 

The Gateway daemon is closing.

Definition at line 491 of file ctgclient.h.

#define CTG_ERR_GATEWAY_EXCEPTION   0xF006
 

An internal exception occurred in the Gateway daemon.

Definition at line 500 of file ctgclient.h.

#define CTG_ERR_INVALID_DATA_LENGTH   -1
 

The data length was not valid.

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

#define CTG_ERR_INVALIDTIMEOUTPARM   -138
 

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

Definition at line 483 of file ctgclient.h.

#define CTG_ERR_LOCKFAIL   -121
 

Internal error during lock creation.

Definition at line 447 of file ctgclient.h.

#define CTG_ERR_LOSTGWCON   -102
 

The connection to the Gateway daemon has been lost.

Definition at line 405 of file ctgclient.h.

#define CTG_ERR_MALLOCFAIL   -111
 

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

Definition at line 431 of file ctgclient.h.

#define CTG_ERR_MORE_SYSTEMS   -25
 

There are more systems to return than were requested.

Definition at line 387 of file ctgclient.h.

#define CTG_ERR_NO_SYSTEMS   -26
 

There are no servers known to the Gateway daemon.

Definition at line 390 of file ctgclient.h.

#define CTG_ERR_NULLADDRESS   -133
 

The hostname is NULL.

Definition at line 471 of file ctgclient.h.

#define CTG_ERR_NULLECIPOINTER   -137
 

The ECI parameter block pointer is NULL.

Definition at line 479 of file ctgclient.h.

#define CTG_ERR_NULLGWTOK   -100
 

The Gateway token is NULL.

Definition at line 395 of file ctgclient.h.

#define CTG_ERR_NULLGWTOKPTR   -108
 

The Gateway token pointer is NULL.

Definition at line 422 of file ctgclient.h.

#define CTG_ERR_NULLPARM   -103
 

One of the parameters is NULL.

Definition at line 409 of file ctgclient.h.

#define CTG_ERR_NULLPTR   -109
 

The pointer is NULL.

Definition at line 426 of file ctgclient.h.

#define CTG_ERR_PIDMISMATCH   -123
 

The Gateway token does not belong to this process.

Definition at line 455 of file ctgclient.h.

#define CTG_ERR_SYSTEM_ERROR   -9
 

An internal system error has occurred.

Definition at line 384 of file ctgclient.h.

#define CTG_ERR_TIDMISMATCH   -124
 

The Gateway token does not belong to this thread.

Definition at line 459 of file ctgclient.h.

#define CTG_ERR_TRACEFILE   -130
 

Unable to create a trace file at the specified location.

Definition at line 463 of file ctgclient.h.

#define CTG_ERR_TRACELEVEL   -104
 

The trace level is not valid.

Definition at line 413 of file ctgclient.h.

#define CTG_ERR_UNKNOWN_REQUEST_TYPE   0xF002
 

The request type is not recognized by the Gateway daemon.

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

#define CTG_LIST_DESCRIPTION_LENGTH   60
 

Definition at line 323 of file ctgclient.h.

#define CTG_LIST_SYSTEM_LENGTH   8
 

Definition at line 313 of file ctgclient.h.

#define CTG_MAX_RCSTRING   40
 

The maximum length of a string returned by CTG_getRcString.

Definition at line 65 of file ctgclient.h.

#define CTG_NULL_GWTOK   NULL
 

Null Gateway daemon token.

Definition at line 68 of file ctgclient.h.

#define CTG_OK   0
 

The API call completed successfully.

Definition at line 378 of file ctgclient.h.

#define CTG_TRACE_LEVEL0   0
 

Trace level 0 disables all tracing.

Definition at line 522 of file ctgclient.h.

#define CTG_TRACE_LEVEL1   1
 

Trace level 1 includes exception trace points only.

Definition at line 526 of file ctgclient.h.

#define CTG_TRACE_LEVEL2   2
 

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

Definition at line 531 of file ctgclient.h.

#define CTG_TRACE_LEVEL3   3
 

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

Definition at line 536 of file ctgclient.h.

#define CTG_TRACE_LEVEL4   4
 

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

Definition at line 541 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 79 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
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL
  • CTG_ERR_BADGWTOKLIST

int CTG_closeGatewayConnection CTG_ConnToken_t gwTokPtr  ) 
 

Attempts to free all resources held by the API, including open Gateway daemon connections.

This function maybe used by the API program under normal shutdown circumstances, or in the event of a severe error, enabling some form of controlled shutdown.

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
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL
  • CTG_ERR_NULLGWTOK
  • CTG_ERR_BADGWTOK
  • CTG_ERR_PIDMISMATCH
  • CTG_ERR_TIDMISMATCH
  • CTG_ERR_NULLGWTOKPTR

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 ECI version 2 problem determination.
Returns:
An integer value identifies whether the call was successful or not.
Possible values include
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL

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
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL
  • CTG_ERR_NULLPTR

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
  • CTG_OK
  • CTG_ERR_NULLPTR
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL

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
  • CTG_OK
  • CTG_ERR_NULLPTR
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL

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
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL
  • CTG_ERR_BADGWTOKLIST
  • CTG_ERR_NULLGWTOKPTR
  • CTG_ERR_NULLPARM
  • CTG_ERR_LOSTGWCON
  • CTG_ERR_NULLECIPOINTER
  • CTG_ERR_UNKNOWN_REQUEST_TYPE
  • CTG_ERR_GATEWAY_CLOSED
  • CTG_ERR_WORK_WAS_REFUSED
  • CTG_ERR_GATEWAY_EXCEPTION
  • CTG_ERR_INVALID_REQUEST_TYPE
  • CTG_ERR_MORE_SYSTEMS
  • CTG_ERR_NO_SYSTEMS
  • CTG_ERR_INVALID_DATA_LENGTH
  • CTG_ERR_SYSTEM_ERROR

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
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL
  • CTG_ERR_BADPORT
  • CTG_ERR_CONNECTFAILED
  • CTG_ERR_BADGWTOKLIST
  • CTG_ERR_NULLGWTOKPTR
  • CTG_ERR_NULLPARM
  • CTG_ERR_LOSTGWCON
  • CTG_ERR_BADHOST
  • CTG_ERR_NULLADDRESS

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.

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
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL
  • CTG_ERR_TRACEFILE

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.

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
  • CTG_OK
  • CTG_ERR_LOCKFAIL
  • CTG_ERR_MALLOCFAIL
  • CTG_ERR_TRACELEVEL


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