Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

ctSetCommProtocolOption

Set additional communication socket options.

Declaration

NINT ctDECL ctSetCommProtocolOption (NINT option,pVOID value)

Description

  • option - option to set - see list below
  • value - the value of the specified option

Unless otherwise noted, options must be set before making a database connection.

option is one of

  • ctCOMMOPT_SOCKET_TIMEOUT - The c-tree socket timeout limits how long a client socket will wait for a server response. It was added as a means to terminate hanging connections, for example, waiting on long-held blocking locks. While the socket timeout has been supported for many years it required modifying a c-tree global variable field structure directly. The socket timeout value, can now be set using ctSetCommProtocolOption() with the new ctCOMMOPT_SOCKET_TIMEOUT mode.
  • ctCOMMOPT_SOCKET_WAIT_INTERVAL - If a failover has occurred, the c-tree function call returns error SERVER_FAILOVER_ERR (1159). If no failover has occurred, the socket receive call waits again for the specified time interval with this option. This function can be called at any time to change the setting, but a c-tree instance must have already been initialized before calling this function. It affects the current c-tree instance.
  • ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE - By default, the ISAM and SQL client libraries use the file ctsrvr.pem in the client process' working directory when connecting. An ISAM client can change the file name of the client library with this option.
  • ctCOMMOPT_FSSLTCP_DEBUG_LOG - If an error occurs when connecting using SSL, the connection attempt returns error 1104 (SSLCONN_ERR). To get more additional detailed information enable SSL logging with this option.
  • ctCOMMOPT_FSSLTCP_CLIENT_CERTIFICATE - References a char * referencing the filename of a PEM formatted file with the full certificate chain the client will present for X.509-based authentication. This file name can be overridden by the environment variable CTSSL_CLIENT_CERTIFICATE
  • ctCOMMOPT_FSSLTCP_CLIENT_KEY - References a char * referencing the filename of a PEM formatted file containing the private key used to sign the client certificate for X.509- based authentication. This file name can be overridden by the environment variable CTSSL_CLIENT_KEY. The PEM may optionally be encrypted. Use ctCOMMOPT_FSSLTCP_CLIENT_PASSPHRASE to supply the passphrase.
  • ctCOMMOPT_FSSLTCP_CLIENT_PASSPHRASE - References a char * used to decrypt the client's private key if it is encrypted.
  • ctCOMMOPT_TCP_KEEPALIVE_INTERVAL - Provides a means of detecting broken TCP links in a configurable time interval. This sets a TCP level keepalive interval in seconds (value interpreted as a string). If the socket is idle, keepalive probes are generated at this interval. If the server does not acknowledge the probe, additional probes may be sent, and an error occurs after roughly 10 additional seconds of non-response. By default, a broken TCP link may be maintained by the OS for several hours, depending on OS defaults and activity on the socket.

Example

Set the socket timeout to 10 seconds.

retval = ctSetCommProtocolOption(ctCOMMOPT_SOCKET_TIMEOUT, "10");

Return

NO_ERROR on success. c-tree error on exception.

Socket wait interval can be used to check server failover status

The client library now supports setting a time interval in seconds after which a socket receive call checks the server failover status. If a failover has occurred, the c-tree function call returns error SERVER_FAILOVER_ERR (1159). If no failover has occurred, the socket receive call waits again for the specified time interval. To use this feature, call this function:

NINT retval;

retval = ctSetCommProtocolOption(ctCOMMOPT_SOCKET_WAIT_INTERVAL, socketWaitInterval);

where socketWaitInterval is a string that holds the desired time interval in seconds, for example, "5" to indicate 5 seconds.

This function can be called at any time to change the setting. A c-tree instance must have already been initialized before calling this function. It affects the current c-tree instance.

Note: The socket timeout value, which has been supported for a number of years, can now be set using this function instead of having to modify a field of the c-tree global variable structure directly. For example, to set the socket timeout to 10 seconds call:

retval = ctSetCommProtocolOption(ctCOMMOPT_SOCKET_TIMEOUT, "10");

Affected Components: c-tree client library

TOCIndex