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

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

#define CTG_DLL_VERSION   "1.0.0.0"
 

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 54 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 434 of file ctgclient.h.

#define CTG_ERR_BADGWTOKLIST   -115
 

Internal error with the Gateway token list.

Definition at line 468 of file ctgclient.h.

#define CTG_ERR_BADHOST   -132
 

The hostname did not resolve to a valid IP address.

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

#define CTG_ERR_CONNECTFAILED   -118
 

Failed to establish a connection with the Gateway daemon.

Definition at line 472 of file ctgclient.h.

#define CTG_ERR_CONNECTTIMEOUT   -134
 

The connection timed out.

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

#define CTG_ERR_GATEWAY_CLOSED   0xF004
 

The Gateway daemon is closing.

Definition at line 529 of file ctgclient.h.

#define CTG_ERR_GATEWAY_EXCEPTION   0xF006
 

An internal exception occurred in the Gateway daemon.

Definition at line 538 of file ctgclient.h.

#define CTG_ERR_GWTOK_CLOSED   -139
 

The Gateway token has been closed and no new work can be sent to the Gateway daemon.

Definition at line 521 of file ctgclient.h.

#define CTG_ERR_INVALID_DATA_LENGTH   -1
 

The data length was not valid.

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

#define CTG_ERR_INVALIDTIMEOUTPARM   -138
 

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

Definition at line 516 of file ctgclient.h.

#define CTG_ERR_LOCKFAIL   -121
 

Deprecated.

No longer used.

Definition at line 480 of file ctgclient.h.

#define CTG_ERR_LOSTGWCON   -102
 

The connection to the Gateway daemon has been lost.

Definition at line 438 of file ctgclient.h.

#define CTG_ERR_MALLOCFAIL   -111
 

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

Definition at line 464 of file ctgclient.h.

#define CTG_ERR_MORE_SYSTEMS   -25
 

There are more systems to return than were requested.

Definition at line 420 of file ctgclient.h.

#define CTG_ERR_NO_SYSTEMS   -26
 

There are no servers known to the Gateway daemon.

Definition at line 423 of file ctgclient.h.

#define CTG_ERR_NULLADDRESS   -133
 

The hostname is NULL.

Definition at line 504 of file ctgclient.h.

#define CTG_ERR_NULLECIPOINTER   -137
 

The ECI parameter block pointer is NULL.

Definition at line 512 of file ctgclient.h.

#define CTG_ERR_NULLGWTOK   -100
 

The Gateway token is NULL.

Definition at line 428 of file ctgclient.h.

#define CTG_ERR_NULLGWTOKPTR   -108
 

The Gateway token pointer is NULL.

Definition at line 455 of file ctgclient.h.

#define CTG_ERR_NULLPARM   -103
 

One of the parameters is NULL.

Definition at line 442 of file ctgclient.h.

#define CTG_ERR_NULLPTR   -109
 

The pointer is NULL.

Definition at line 459 of file ctgclient.h.

#define CTG_ERR_PIDMISMATCH   -123
 

The Gateway token does not belong to this process.

Definition at line 488 of file ctgclient.h.

#define CTG_ERR_SYSTEM_ERROR   -9
 

An internal system error has occurred.

Definition at line 417 of file ctgclient.h.

#define CTG_ERR_TIDMISMATCH   -124
 

The Gateway token does not belong to this thread.

Definition at line 492 of file ctgclient.h.

#define CTG_ERR_TRACEFILE   -130
 

Unable to create a trace file at the specified location.

Definition at line 496 of file ctgclient.h.

#define CTG_ERR_TRACELEVEL   -104
 

The trace level is not valid.

Definition at line 446 of file ctgclient.h.

#define CTG_ERR_UNKNOWN_REQUEST_TYPE   0xF002
 

The request type is not recognized by the Gateway daemon.

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

#define CTG_LIST_DESCRIPTION_LENGTH   60
 

Definition at line 356 of file ctgclient.h.

#define CTG_LIST_SYSTEM_LENGTH   8
 

Definition at line 347 of file ctgclient.h.

#define CTG_MAX_RCSTRING   40
 

The maximum length of a string returned by CTG_getRcString.

Definition at line 59 of file ctgclient.h.

#define CTG_NULL_GWTOK   NULL
 

Null Gateway daemon token.

Definition at line 62 of file ctgclient.h.

#define CTG_OK   0
 

The API call completed successfully.

Definition at line 411 of file ctgclient.h.

#define CTG_TRACE_LEVEL0   0
 

Trace level 0 disables all tracing.

Definition at line 560 of file ctgclient.h.

#define CTG_TRACE_LEVEL1   1
 

Trace level 1 includes exception trace points only.

Definition at line 564 of file ctgclient.h.

#define CTG_TRACE_LEVEL2   2
 

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

Definition at line 569 of file ctgclient.h.

#define CTG_TRACE_LEVEL3   3
 

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

Definition at line 574 of file ctgclient.h.

#define CTG_TRACE_LEVEL4   4
 

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

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


Function Documentation

int CTG_closeAllGatewayConnections  ) 
 

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

This function can be called in the event of a severe application error, enabling a 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.

After successful completion, resources associated with the Gateway daemon connection are 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 or ECI_ASYNC 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:
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 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 zero 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 2011, 2012. All rights reserved.
For legal information, see http://www.ibm.com/legal/copytrade.shtml