SQLReloadConfig function (CLI) - Reload a configuration property from the client configuration file

The SQLReloadConfig() function reloads a configuration property from the db2dsdriver.cfg client configuration file.

Specification:

CLI 9.7

Unicode equivalent: You can also use this function with the Unicode character set. The corresponding Unicode function is SQLReloadConfigW(). For more information about ANSI to Unicode function mappings, see Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLReloadConfig(SQLINTEGER        ConfigProperty,
                            SQLCHAR           *DiagInfoString,
                            SQLSMALLINT       BufferLength,
                            SQLSMALLINT       *StringLengthPtr);

Function arguments

Table 1. SQLReloadConfig function arguments
Data type	Argument	Use	Description
SQLINTEGER	ConfigProperty	Input	A predefined grouping of db2dsdriver.cfg file sections to reload. DSD_ACR_AFFINITY is the only supported value. DSD_ACR_AFFINITY value is defined in the usage section.
SQLCHAR *	DiagInfoString	Output	If the value is SQL_ERROR, CLI returns a detailed error description or information in the DiagInfoString output. If the value is SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, CLI does not return any information. In Db2® Version 9.7 Fix Pack 5 and later fix packs, warning messages are prefixed with a diagnostic string that consists of the database name, server name, and port number (`database`:`hostname`:`port`). Multiple warnings are separated with newline characters.
SQLINTEGER	BufferLength	Input	The length of the *DiagInfoString argument.
SQLINTEGER *	StringLengthPtr	Output	A pointer to a buffer in which to return the total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the number of bytes that are required for the null termination character, available to return in the DiagInfoString argument. If the number of bytes to return is greater than the value of the BufferLength argument, the text in the DiagInfoString argument is truncated to the value of the BufferLength argument minus the length of a null termination character. CLI then uses a null character to terminate the text in the *DiagInfoString argument.

Usage

After you modify the db2dsdriver.cfg file, you can issue the SQLReloadConfig() function to reload the entries for the section of the db2dsdriver.cfg file that you specify in the ConfigProperty argument.

Currently, you can reload only the DSD_ACR_AFFINITY configuration property. The DSD_ACR_AFFINITY configuration property consists of the following parameters, which you define in the automatic client reroute (<acr>) section in the db2dsdriver.cfg file:

<alternateserverlist>
<affinitylist>
<clientaffinitydefined>
<clientaffinityroundrobin>

Modifications to other parameters in the <acr> section are ignored.

When your application issues the SQLReloadConfig() function, the reload causes reevaluation of affinity members for all connections at the next transaction interval. The next transaction interval refers to the next transaction boundary, which is defined when a commit or rollback occurs. This reevaluation of affinity members involves validating entries for all alternate servers within the <acr> section. For each server, an attempt is made to open a socket by using the specified host name and port number. If all servers in the alternate server list of an active database connection are unreachable, an error message is returned in the DiagInfoString argument of the SQLReloadConfig() function. Affinity for an idle connection is evaluated only when the connection becomes active. When the connection becomes active, it is moved to an affinity member.

If you modify a section of the db2dsdriver.cfg file other than the <acr> section, the SQLReloadConfig() function returns a value of SQL_ERROR in the DiagInfoString argument. Also, if you remove or add a <acr> section for existing database entries in the db2dsdriver.cfg file, the SQLReloadConfig() function returns an error. If the SQLReloadConfig() function returns an error, applications continue to access the old db2dsdriver.cfg file contents.

The SQLReloadConfig() function updates in-memory versions of automatic client reroute (ACR) affinities with all the databases that are listed in the current db2dsdriver.cfg file. If the function finds that the <acr> section of any database entry is invalid, the next attempt to connect to that database results in an error. The detection of invalid <acr> sections also terminates connections for active databases at the next transaction interval. For possible causes for an invalid <acr> section, see the following list:

The <database> section is missing (results in SQL_ERROR being returned).
The <acr> section is missing (results in SQL_ERROR being returned).
A new alternate server list is empty.
The CLI driver encountered internal buffer boundary limit to hold new server list.

The SQLReloadConfig() function has no default timeout value for attempting to open a socket against an alternate server port. You can set a specific timeout value by using the SocketTimeOut parameter in the global section of the db2dsdriver.cfg file.

Restrictions

The DSD_ACR_AFFINITY configuration property of the db2dsdriver.cfg file is the only property that you can reload by using the SQLReloadConfig() function.

Example

Following example demonstrates the use of the SQLReloadConfig() function:

SQLCHAR szDiagInfoString[200] = {'\0'};
SQLINTEGER iDiagInfoStringLen = 0;
SQLRETURN cliRC = 0;

//After changing the db2dsdriver.cfg
cliRC = SQLReloadConfig( DSD_ACR_AFFINITY,
        szDiagInfoString,
        200,
        &iDiagInfoStringLen );