ctgclient.h File Reference
#include <stddef.h>

Go to the source code of this file.

Detailed Description

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

Definition in file ctgclient.h.

Macro Definition Documentation

Definition at line 57 of file ctgclient.h.

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.

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.

The connection failed because the Applid or Applid Qualifier is greater than 8 characters in length.

Definition at line 687 of file ctgclient.h.

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.

Deprecated:
No longer used.

Definition at line 634 of file ctgclient.h.

The hostname did not resolve to a valid IP address.

Definition at line 666 of file ctgclient.h.

The port number is not valid.

Port numbers must be in the range 1 through 65535.

Definition at line 616 of file ctgclient.h.

Deprecated:
No longer used.

Definition at line 650 of file ctgclient.h.

Failed to establish a connection with the Gateway daemon.

Definition at line 638 of file ctgclient.h.

The connection timed out.

Definition at line 674 of file ctgclient.h.

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.

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.

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.

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.

Deprecated:
No longer used.

Definition at line 642 of file ctgclient.h.

Deprecated:
No longer used.

Definition at line 575 of file ctgclient.h.

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.

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

Definition at line 682 of file ctgclient.h.

Deprecated:
No longer used.

Definition at line 646 of file ctgclient.h.

The connection to the Gateway daemon has been lost.

Definition at line 603 of file ctgclient.h.

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.

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.

There are no servers known to the Gateway daemon.

Definition at line 590 of file ctgclient.h.

Deprecated:
No longer used.

Definition at line 716 of file ctgclient.h.

The hostname is NULL.

Definition at line 670 of file ctgclient.h.

The ECI parameter block pointer is NULL.

Definition at line 678 of file ctgclient.h.

The Gateway token is NULL.

Definition at line 594 of file ctgclient.h.

The Gateway token pointer is NULL.

Definition at line 620 of file ctgclient.h.

One of the parameters is NULL.

Definition at line 607 of file ctgclient.h.

The pointer is NULL.

Definition at line 624 of file ctgclient.h.

Deprecated:
No longer used.

Definition at line 654 of file ctgclient.h.

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.

Deprecated:
No longer used.

Definition at line 658 of file ctgclient.h.

Unable to create a trace file at the specified location.

Definition at line 662 of file ctgclient.h.

The trace level is not valid.

Definition at line 611 of file ctgclient.h.

Deprecated:
No longer used.

Definition at line 696 of file ctgclient.h.

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.

Definition at line 520 of file ctgclient.h.

Definition at line 511 of file ctgclient.h.

The maximum length of a string returned by CTG_getRcString.

Definition at line 76 of file ctgclient.h.

Null Gateway daemon token.

Definition at line 79 of file ctgclient.h.

The API call completed successfully.

Definition at line 571 of file ctgclient.h.

Trace level 0 disables all tracing.

Definition at line 735 of file ctgclient.h.

Trace level 1 includes exception trace points only.

Definition at line 739 of file ctgclient.h.

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

Definition at line 744 of file ctgclient.h.

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

Definition at line 749 of file ctgclient.h.

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

Definition at line 754 of file ctgclient.h.

Typedef Documentation

CTG_ConnToken_t represents a connection to a specific Gateway daemon.

Definition at line 90 of file ctgclient.h.

Function Documentation

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

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
Returns
An integer value identifies whether the call was successful or not.
Possible values include

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

Get the current trace level.

Takes a pointer to an int variable, and sets that variable to the current API trace level.

Parameters
Returns
An integer value identifies whether the call was successful or not.
Possible values include

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
Returns
An integer value identifies whether the call was successful or not.
Possible values include

Gets the APPLID.

Parameters
Returns
An integer value identifies whether the call was successful or not.
Possible values include

Gets the APPLID qualifier.

Parameters
Returns
An integer value identifies whether the call was successful or not.
Possible values include

Gets the DLL version.

This will change when the build level changes.

Parameters
Returns
An integer value identifies whether the call was successful or not.
Possible values include

Gets the string representation of the return code.

Parameters
Returns
a pointer to rcString.

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
Returns
An integer value identifies whether the call was successful or not.
Possible values include

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
Returns
An integer value identifies whether the call was successful or not.
Possible values include

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
Returns
An integer value identifies whether the call was successful or not.
Possible values include

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
Returns
An integer value that identifies whether the call was successful.
Possible values include

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

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

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
Returns
An integer value identifies whether the call was successful or not.
Possible values include

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
Returns
An integer value identifies whether the call was successful or not.
Possible values include