Configuring TimesTen Client and Server
You can connect an application to a TimesTen database using a client and server.
Note:
Before configuring the TimesTen client and server, see Connecting to TimesTen with ODBC and JDBC Drivers and Specifying Data Source Names to Identify TimesTen Databases.
The following sections describe how to connect an application to a TimesTen database using TimesTen client and server:
-
Installing and Configuring for Client/Server of the Same TimesTen Release
-
Installing and Configuring Cross-Release TimesTen Client/Server
-
Defining Server DSNs for TimesTen Server on a Linux or UNIX System
You can optionally configure and use TLS for encrypted communication between clients and the server. See Transport Layer Security for TimesTen Client/Server in Oracle TimesTen In-Memory Database Security Guide.
Overview of TimesTen Client/Server Configuration
Before the client application can connect to a TimesTen database, the user must configure the client DSN, optionally a logical server name, and a server DSN to uniquely identify the desired TimesTen database.
See Figure 3-2.
Figure 3-2 Configuring for a Client/Server Connection
Description of "Figure 3-2 Configuring for a Client/Server Connection"
The client application refers to the client DSN when initiating a connection. With the following details, the connection request is resolved to be able to connect to the intended TimesTen database:
-
The client DSN is configured in either the user odbc.ini file or the system
sys.odbc.ini
file with the server host name, either the logical server name or the actual server system name, and the server DSN that identifies the TimesTen database on the server. -
The logical server name is an optional configuration on the client. When used, it specifies the server host name where the TimesTen database is installed. This is used when you want to hide or simplify the server host name. You must use the logical server name when using shared memory IPC or UNIX domain sockets.
-
The server DSN is configured in the system
sys.odbc.ini
file with the TimesTen database name and its connection attributes. The connection attributes specify how the TimesTen database is loaded and configured, and how the connections to it are to be controlled or managed.
Thus, when these are configured correctly, the client application can use the client DSN to locate and connect to the TimesTen database. The client DSN defines the server system and the server DSN. The server DSN, in turn, specifies the TimesTen database on that server, how the database is to be loaded, and how connections are to be managed.
Installing and Configuring for Client/Server of the Same TimesTen Release
There are methods for installing and configuring TimesTen when the client and server are of the same TimesTen release.
Install and Configure the TimesTen Server
Perform the following tasks on the system on which the TimesTen database resides. This system is called the server system.
-
Install the TimesTen server.
For information on how to install the TimesTen server, see Overview of the Installation Process in TimesTen Classic in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide.
-
Create and configure a server DSN corresponding to the TimesTen database. See Defining Server DSNs for TimesTen Server on a Linux or UNIX System. Set TimesTen connection attributes in the Server DSN. See Connection Attributes in the Oracle TimesTen In-Memory Database Reference.
Install and Configure the TimesTen Client
Install and configure the TimesTen client on the system where the client application resides. This system is called the client system.
-
Install the TimesTen client.
For information on how to install the TimesTen client, see Overview of the Installation Process in TimesTen Classic in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide.
-
If you are using JDBC to connect to the database, install the Java Developer's Kit (JDK) and set up the environment variables, such as
CLASSPATH
and the shared library search path. See Setting the Environment for Java Development in the Oracle TimesTen In-Memory Database Java Developer's Guide. -
Create and configure a Client DSN corresponding to the Server DSN. See Creating and Configuring Client DSNs on Linux and UNIX and Creating and Configuring Client DSNs on Windows.
-
For OCI and Pro*C/C++ client/server connections, configure the application to use either
tnsnames.ora
or easy connect as described in Connecting to a TimesTen Database from OCI in the Oracle TimesTen In-Memory Database C Developer's Guide. -
Link client/server applications as follows:
-
Link C and C++ client/server applications as described in Linking Options in the Oracle TimesTen In-Memory Database C Developer's Guide.
-
Link OCI or Pro*C/C++ applications in the same manner as any OCI or Pro*C/C++ direct connect applications, which is described in TimesTen Support for OCI and TimesTen Support for Pro*C/C++ in the Oracle TimesTen In-Memory Database C Developer's Guide.
-
Installing and Configuring Cross-Release TimesTen Client/Server
Most TimesTen clients can connect to a TimesTen server from a different release.
A TimesTen client 11.2.2 or later release may connect to a TimesTen server 11.2.2 or later release. However, due to changes in ODBC 3.5 functionality, TimesTen clients of release 18.1 or later can no longer connect to older TimesTen servers in certain circumstances. For more information about client/server cross-release restrictions, see Client/Server Cross-Release Restrictions With ODBC 3.5 in the Oracle TimesTen In-Memory Database C Developer's Guide.
If you are configuring for a cross-release TimesTen client/server connection, install and configure as directed in Installing and Configuring for Client/Server of the Same TimesTen Release.
The TimesTen server loads a driver and a TimesTen database of its own release when a TimesTen client application connects to the TimesTen database. The TimesTen Data Manager driver is automatically installed on the TimesTen server system.
If you are using a local client/server connection using UNIX domain sockets
through ttLocalHost
, then the platforms for the client and the server
must be Linux or UNIX. The client must be running on the same host as the server and
thus must be on the same platform. The release level for the client and server hosts
must be the same.
Defining Server DSNs for TimesTen Server on a Linux or UNIX System
Server DSNs identify TimesTen databases that are accessed by a client/server connection.
Because a server DSN identifies databases that are accessed by a TimesTen server, a server DSN can be configured using the same connection attributes as a Data Manager DSN. In addition, there are connection attributes that are only allowed within the server DSN specification. These attributes enable you to specify multiple client/server connections to a single server.
Note:
Some connection attributes can be configured in the TimesTen daemon
options file (timesten.conf
). If you have set the same connection
attributes in both the server DSN and the daemon options file, the value of the
connection attributes in the server DSN takes precedence. For a description of the
TimesTen daemon options, see Managing TimesTen Client/Server Attributes. For a complete description of the
TimesTen Server connection attributes, see Connection Attributes in the Oracle TimesTen In-Memory Database
Reference.
A server DSN must be defined as a system DSN and has the same configuration format and attributes as a Data Manager DSN.
-
For TimesTen Scaleout: A DSN is defined within the appropriate database definition and connectable. A connectable enables all data instances to accept connection requests from other data instances in the grid.
However, to establish a client connection from a TimesTen client that is not part of the grid, create a client DSN in the user
odbc.ini
file or the systemsys.odbc.ini
file with thettGridAdmin
gridClientExport
command. This command exports every client/server connectable available for the grid into a file that is formatted to replace theodbc.ini
file used by the TimesTen client. See Connect to a Database Using ODBC and JDBC Drivers in the Oracle TimesTen In-Memory Database Scaleout User's Guide. -
With TimesTen Classic, you create each system DSN by creating or editing the user
odbc.ini
file or the systemsys.odbc.ini
file. You can add or configure a server DSN while the TimesTen server is running. See Creating a DSN on Linux and UNIX for TimesTen Classic.
By default, TimesTen creates only one connection to a server per child process.
However, you can specify multiple client/server connections to a single TimesTen server
with the connection attributes (described below) or by setting the TimesTen daemon
attributes in the timesten.conf
file as described in Specifying Multiple Connections to the TimesTen Server. If you have set both the server connection attributes and the
related timesten.conf
daemon attributes, the value of the server
connection attributes takes precedence.
Note:
These attributes are read at first connection. Changes to server settings do not occur until the server is restarted.
To restart the server, use the following command. With TimesTen Scaleout, run this
command within the ttGridAdmin
instanceExec
command.
ttDaemonAdmin -restartserver
-
Connections
attribute: Sets the upper limit of the number of concurrent connections to the database. TimesTen allocates one semaphore for each expected connection, therefore theSEMMNS
kernel parameter has to be set properly. Make sure the connections attribute is set large enough to accommodate the number of concurrent database connections expected.See Connections in the Oracle TimesTen In-Memory Database Reference or Set the Semaphore Values and Configure shmmax and shmall in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide.
-
ServerStackSize
: Set the stack size for each thread on the server.The
ServerStackSize
attribute is ignored unless theMaxConnsPerServer
attribute is greater than one. If there is only one connection per server, the server process uses the process' main stack. Consider setting theServerStackSize
attribute to 1024 KB or greater if you are running complex SQL queries on your client connections. -
MaxConnsPerServer
: Set the maximum number of client connections that are handled by a single server process. SettingMaxConnsPerServer
> 1 enables multithreaded mode for the database so that it can use threads instead of processes to handle client connections. This reduces the time required for applications to establish new connections and increases overall efficiency in configurations that use a large number of concurrent client/server connections.The server, referenced by the server DSN, may have multiple server processes, where each process can only have the maximum number of connections as specified by this attribute. A new server process is automatically started if the number of connections exceeds
MaxConnsPerServer
.Note:
If you are running a server in multithreaded mode and a server process fails, then all the client connections being handled by that process are terminated. Consider this when configuring the server for multithreaded mode and choose a value for
MaxConnsPerServer
that balances your requirements for reliability and availability versus the more efficient resource usage of multithreaded mode. -
ServersPerDSN
: You can have multiple server processes serving multiple incoming connections on the server. TheServersPerDSN
attribute specifies the number of server processes to spawn in connection with theMaxConnsPerServer
attribute for distribution of incoming connections.
The MaxConnsPerServer
and ServersPerDSN
attributes
are related in that they do not limit the number of connections, but control how
connections are distributed over server processes. If ServersPerDSN
is
set to N
where N
> 1
, then the first N
* MaxConnsPerServer
client connections to a server DSN are distributed
in round robin fashion over N
server processes. If additional
client connections beyond N
* MaxConnsPerServer
are opened to the same server DSN, then those
connections are assigned to new server processes sequentially. For example, if you have
12 connections and MaxConnsPerServer=3
, then there are four server
processes.
This results in the following behavior:
-
The first incoming connection spawns a new server process. Each additional incoming connection spawns a new server process up to the
ServersPerDSN
value. -
The next
ServersPerDSN
number of incoming connections are assigned to the existing server processes in a round-robin fashion up toMaxConnsPerServer
connections per server. -
Once the
MaxConnsPerServer
is reached for servers spawned up toServersPerDSN
, the next connection spawns another server process and repeats the process detailed in steps 1 and 2.
For example, if MaxConnsPerServer
is set to 2 and ServersPerDSN
is set to 5, then the following occurs:
-
Connection 1 arrives at the server, the first server process is started for this connection. Connections 2 through 5 arrive at the server, server processes 2 through 5 are initiated where each server process services a connection.
-
Connection 6 arrives at the server. Since
ServersPerDSN
is reached, andMaxConnsPerServer
is not, connection 6 is given to the first server process. Incoming connections 7 through 10 are given respectively as the second connection to server processes 2 through 5. -
Connection 11 arrives at the server. Both
ServersPerDSN
andMaxConnsPerServer
are reached, so server process 6 is started to handle connection 11.
See ServersPerDSN, ServerStackSize, and MaxConnsPerServer in the Oracle TimesTen In-Memory Database Reference.
Defining a Logical Server Name
A logical server name is a definition for a server system on the TimesTen client.
In some cases, such as when using a communication protocol other than TCP/IP for local client/server or the TimesTen server process is not listening on the default TCP/IP port, you must define a logical server name on the client system. In these cases, the client DSN must refer to the logical server name. However, in most cases when the communication protocol used is TCP/IP, the client DSN can refer directly to the server host name without having to define a logical server name.
The following sections demonstrate how to define a logical server name on Linux and UNIX platforms:
Creating and Configuring a Logical Server Name on Windows
You can create and configure a logical server name on Windows.
-
On the Windows Desktop from the Start menu, select Control Panel, Administrative Tools, and finally Data Sources (ODBC).
This opens the ODBC Data Source Administrator.
-
Click User DSN or System DSN.
-
Select a TimesTen Client DSN and click Configure.
Note:
If no Client DSN exists, click Add, select TimesTen Client 22.1 and click Finish. This opens the TimesTen Client DSN Setup dialog. See Creating and Configuring Client DSNs on Windows for directions on creating a Client DSN in the setup dialog.
-
Click Servers. This opens the TimesTen Logical Server List dialog.
-
Click Add. This opens the TimesTen Logical Server Name Setup dialog.
-
In the Server Name field, enter a logical server name.
-
In the Description field, enter an optional description for the server.
-
In the Network Address field, enter the host name or IP address of the server system. The network address must be the name of the system where the TimesTen server is running. For example,
example.com
-
In the Network Port field, TimesTen displays the port number on which the TimesTen Logical Server listens by default. If the TimesTen server is listening on a different port, enter that port number in the Network Port field.
For example:
-
Click OK, then click Close in the TimesTen Logical Server List dialog to finish creating the logical server name.
To delete a server name:
- On the Windows Desktop on the client system from the Start menu, select Control Panel.
- Double click ODBC. This opens the ODBC Data Source Administrator.
- Click either User DSN or System DSN.
- Select a TimesTen Client DSN and click Configure. This opens the TimesTen Client DSN Setup dialog.
- Click Servers. This opens the TimesTen Logical Server List dialog.
- Select a server name from the TimesTen Servers list.
- Click Delete.
Creating and Configuring a Logical Server Name on Linux and UNIX
Define logical server names in a file named by the
SYSTTCONNECTINI
environment variable.
This file is referred to as the ttconnect.ini
file.
The file contains a description, a network address and a port number.
TimesTen searches for the logical server in this order:
-
In the file specified by the
SYSTTCONNECTINI
environment variable, if it is set -
In the
timesten_home
/conf/sys.ttconnect.ini
file
TimesTen uses the ttconnect.ini
file to define the names and attributes for servers and the mappings between logical server names and their network addresses. This information is stored on the system where the TimesTen Client is installed. By default, the ttconnect.ini
file is timesten_home
/conf/sys.ttconnect.ini
.
To override the name and location of this file at runtime, set the SYSTTCONNECTINI
environment variable to the name and location of the ttconnect.ini
file before launching the TimesTen application.
You can define short-hand names for TimesTen Servers on Linux and UNIX in the
ttconnect.ini
file. The format of a TimesTen Server
specification in the ttconnect.ini
file is shown in Table 3-1.
Table 3-1 TimesTen Server Format in the ttconnect.ini File
Component | Description |
---|---|
[ |
Logical server name of the TimesTen server system |
|
Description of the TimesTen server |
|
The DNS name, host name or IP address of the system on which the TimesTen server is running. |
|
The TCP/IP port number where the TimesTen server is running. Default for TimesTen release 22.1 is 6625. |
The network address must be one of the following:
Type of connection | Network address |
---|---|
Remote client/server connection |
The name of the system where the TimesTen Server is running. For example, |
Local client/server connection that uses UNIX domain sockets |
|
The following example shows a ttconnect.ini
file that defines a
logical server name, LogicalServer
, for a TimesTen server
running on the system server.example.com
and listens on
port 6625
. The instance name of
the TimesTen installation is instance
.
[LogicalServer] Description=TimesTen server 22.1 Network_Address=server.example.com TCP_Port=6625
If both the client and server are on the same Linux or UNIX system, applications using the TimesTen client driver may improve performance by using UNIX domain sockets for communication.
The logical server name must also define the port number on which the TimesTen server
is listening so that multiple instances of the same version of TimesTen
server can be run on the same system. To achieve this, the logical server
name definition in ttconnect.ini
file might look like:
[LocalHost] Description=Local TimesTen Server 22.1 through domain sockets Network_Address=ttLocalHost TCP_Port=6625
Defining Client DSNs on a TimesTen Client System
A client DSN specifies a remote database and uses the TimesTen client.
The client DSN can be defined as a user or as a system DSN. A client DSN refers to a
TimesTen database indirectly by specifying a hostname, DSN
pair, where
the hostname represents the server system on which TimesTen server is running and the
DSN refers to a server DSN that is defined on that host. These are configured within the
client DSN connection attributes.
Note:
For a complete description of the TimesTen client connection attributes, see List of Connection Attributes in the Oracle TimesTen In-Memory Database Reference.
Alternatively, you can configure connection attributes at runtime in the connection
string that is passed to the ODBC SQLDriverConnect
function or the URL
string that is passed to the JDBC DriverManager.getConnection()
method.
For example, you could use the TTC_Server_DSN
attribute in either the
connection string or the client DSN for a client to specify which DSN it should use on
the server.
Note:
If you configure any of the server DSN data store or first connection attributes
within the definition of the client DSN, they are ignored. However, the TimesTen
client allows most of the server DSN attributes (except for the
DataStore
connection attribute) to be passed in as part of the
connection or URL string. These are transparently passed on to the server and
overrides what is configured in the server DSN.
The following sections describe how to create a client DSN and its attributes on either the Windows or Linux and UNIX platforms:
Creating and Configuring Client DSNs on Windows
On Windows, use the ODBC Data Source Administrator to configure logical server names and to define client DSNs.
This section includes the following topics:
Setting the Network Timeout Interval and Authentication
You can define the user name, password and network timeout interval for the
client/server connection in the client DSN with the UID
,
PWD
, and TTC_TIMEOUT
attributes.
However, configuring the authentication in the client DSN is optional since you can provide the user name and password when connecting. Also, supplying the password in the client DSN is strongly discouraged since the password is stored unencrypted.
Alternatively, TimesTen enables you to store user names and associated passwords in an Oracle Wallet. This is the most secure and preferred method of providing credentials for connecting to a TimesTen database. However, you would provide the location and name of the Oracle Wallet on the connect string. For more information on creating the wallet and managing Oracle cache administration user IDs and passwords, see Providing a User Name and Password in an Oracle Wallet in Oracle TimesTen In-Memory Database Security Guide.
For a description of the UID
, PWD
, and
TTC_TIMEOUT
connection attributes, see List of Connection Attributes in Oracle TimesTen In-Memory Database
Reference.
To set the network timeout interval and authentication:
-
In the User ID field of the Oracle TimesTen Client DSN Setup dialog box, enter a user name that is defined on the server system.
-
In the Password field, enter the password that corresponds to the user ID. Alternatively, you can enter a hashed password in the PwdCrypt field or use the
ttUser
utility to store the password in an Oracle Wallet and retrieve it from the wallet using the PwdWallet field. SeettUser
in the Oracle TimesTen In-Memory Database Reference.Provide the password in one of the following ways:- By storing the password in an Oracle Wallet and then entering the path to the wallet in the PwdWallet field.
- By entering the password that corresponds to the user ID in the Password field.
- By entering an encrypted password that corresponds to the user ID in the PwdCrypt field
-
In the Network Timeout field, enter the interval time in seconds. You can enter any non-negative integer. A value of 0 indicates that client/server operations should not time out. The default is 60 seconds. The maximum is 99,999 seconds.
The
TTC_Timeout
connection attribute sets a maximum time limit for a network operation that is completed by using the TimesTen client and server. TheTTC_Timeout
connection attribute also determines the maximum number of seconds a TimesTen client application waits for the result from the corresponding TimesTen server process before timing out. -
Click OK to save the setup.
Accessing a Remote Database on Windows
In this example, the TimesTen client system is client.example.com
.
The client application is accessing the server DSN on the remote server system,
server.example.com
. The logical server name is
LogicalServer
.
Note:
These examples reference the sample DSNs preconfigured in a fresh TimesTen installation.
-
On the server system
server.example.com
, use thettStatus
utility to verify that the TimesTen server is running and to verify the port number it is listening on. -
Using the procedure in Defining Server DSNs for TimesTen Server on a Linux or UNIX System, verify that the server DSN,
database1
, is defined as a system DSN onserver.example.com
. -
On the client system,
client.example.com
, create a Logical Server Name entry for the remote TimesTen server. In the TimesTen Logical Server Name Setup dialog:-
In the Server Name field, enter
LogicalServer
. -
In the Network Address field, enter
server.example.com
. -
In the Network Port field, enter
6625
. This is the default port number for the TimesTen server for TimesTen Release 22.1. This value should correspond to the value displayed byttStatus
in Step 1.
-
-
On the client system,
client.example.com
, create a client DSN that corresponds to the remote server DSN,database1CS
. In the TimesTen client DSN Setup dialog, enter the following values:-
In the Client DSN field, enter
database1CS
. -
In the Server Name or Network Address field, enter
LogicalServer
. -
In the Description field, enter a description for the server. Entering data into this field is optional.
-
In the Server DSN field, enter
database1
.
-
-
Run the client application from the system
client.example.com
using the client DSN,database1CS
. The example below uses thettIsql
program installed with TimesTen client.ttIsql -connStr "DSN=database1CS"
The next example describes how to access a TimesTen server that is listening on a port numbered other than the default port number.
Consider that the network address of the TimesTen server is
server.example.com
and the server is listening on port 6625. The following methods can be used to connect to a
server DS:
Creating and Configuring Client DSNs on Linux and UNIX
On Linux and UNIX, you define logical server names by editing the
ttconnect.ini
file; you define Client DSNs by editing the
user odbc.ini
file for user DSN or the system
sys.odbc.ini
file for system DSNs.
Note:
The syntax for defining the Client DSN in the
odbc.ini
file is described in odbc.ini File Entry Descriptions. See Defining a Logical Server Name for details on the
ttconnect.ini
file. See Specifying Data Source Names to Identify TimesTen Databases for a description
of user and system DSNs.
In the ODBC Data Sources section of the odbc.ini
file, add an entry for the client DSN. The client DSN specifies the location
of the TimesTen database with the following attributes:
-
TimesTen ODBC client driver to use for the connection.
-
The server (and the port number if you do not want to use the default port number) for the database is specified in the
TTC_Server
attribute. -
The server DSN that specifies the intended database is specified in the
TTC_Server_DSN
attribute.Note:
The server DSN is defined on the server system where the database resides.
See Connecting Using TimesTen ODBC Drivers for a list of all available ODBC client drivers.
For each TimesTen database with which the client connects needs to have two entries:
-
Define the client DSN name and provide the name of the TimesTen ODBC client driver to use in the ODBC Data Sources section.
-
Create an entry with the client DSN you defined in the ODBC Data Sources section. Within this section, specify the server system and the server DSN.
The following is the syntax for providing the client DSN name and the ODBC client driver to use:
[ODBC Data Sources] Client_DSN=Name-of-ODBC-driver
For example, to defined database1CS
as the client
DSN and associate it with the TimesTen client ODBC driver, you would make
the following entry in the ODBC Data Sources section of the
odbc.ini
file:
[ODBC Data Sources]
database1CS=TimesTen Client 22.1 Driver
After the ODBC Data Sources section, you would add an entry to
specify the server system and server DSN for each data source you defined.
Each client DSN listed in the ODBC Data Sources section of the
odbc.ini
file requires a its own specification
section.
The following is an example specification of the TimesTen client DSN
database1CS
where the server is configured with a
server name of server.example.com
with port of 6625 and the
server DSN is database1
.
[database1CS] TTC_Server=server.example.com/6625 TTC_Server_DSN=database1
If you want to use logical server names, then the following is an
example specification of the TimesTen client DSN
database1CS
where the server is configured with a
logical server name of LogicalServer
and the server DSN is
database1
:
[database1CS] TTC_Server=LogicalServer TTC_Server_DSN=database1
The TTC_Server
attributes are the main attributes
for a client DSN definition. There are only a few client connection
attributes, each of which are for identifying the server DSN. If you provide
any server connection attributes in the client definition, these attributes
are ignored. General connection attributes may be specified in the client
definition.
Note:
See UID and PWD and PwdWallet in the Oracle TimesTen In-Memory Database Reference for options on how to provide the user ID when connecting.
By default, connections wait 60 seconds for TimesTen client and
server to complete a network operation. The TTC_Timeout
attribute sets a maximum time limit for a network operation that is
completed by using the TimesTen client and server. The
TTC_Timeout
connection attribute also determines
the maximum number of seconds a TimesTen client application waits for the
result from the corresponding TimesTen server process before timing out.
[database1CS] TTC_Server=server.example.com/6625 TTC_Server_DSN=database1 TTC_Timeout=60
Once the TimesTen client DSN is configured, you can connect to the
server using the ttIsqlCS
utility. The following connects
to the server using the database1CS
DSN.
ttIsqlCS -connStr "DSN=database1CS"
For a description of all client and general connection attributes
available for use in the odbc.ini
file, see Connection Attributes in the Oracle TimesTen In-Memory Database
Reference.
Sizing the Client Result Set Buffer
Executing a SELECT
statement returns a result set (if there is one).
The server stores a maximum number of rows from the result set that fits into a client
result set buffer.
You can improve performance by changing the maximum size of the result set buffer or the maximum number of rows that can be stored into a client result set buffer with the following connection attributes:
-
TTC_NetMsgMaxBytes
: The size of a client result set buffer in bytes. The default is 2097152 bytes. -
TTC_NetMsgMaxRows
: The maximum number of rows that can be stored in a client result set buffer. The default is 8192 rows.
The SELECT
statement returns the maximum number of bytes or
rows into a client result set buffer, whichever limit is reached first. For queries that
return large result sets, you may want to increase the values of both parameters.
See Configuring the Result Set Buffer Size in Client/Server Using ODBC and Configuring the Result Set Buffer Size in Client/Server Using OCI in the Oracle TimesTen In-Memory Database C Developer's Guide and Configuring the Result Set Buffer Size in Client/Server Using JDBC in the Oracle TimesTen In-Memory Database Java Developer's Guide for details on setting these limits using ODBC, OCI and JDBC programmatic APIs.
Using Automatic Client Failover
Automatic client failover is for use in high availability client/server scenarios with TimesTen Scaleout or TimesTen Classic.
If there is a failure of the TimesTen database to which the client is connected, then failover (connection transfer) to an alternate TimesTen database occurs. Failover connections are created only as needed.
-
For TimesTen Scaleout, the connection is transferred to an available data instance from a list of available data instances in the grid (and is not dependent on the DSN configuration in your
odbc.ini
file). -
For TimesTen Classic, you can use automatic client failover in two scenarios:
-
Active standby pair replication scheme: If you have an active standby pair replication configuration, then the connection is transferred to the new active (original standby) master within an active standby pair replication configuration. Consider a scenario where failure of the active master has resulted in the original standby master becoming the new active master. With the automatic client failover feature, failover (transfer) to the new active (original standby) node occurs, and applications are automatically reconnected to the new active master.
Note:
Automatic client failover in TimesTen Classic (when using an active standby pair replication scheme) is complementary to Oracle Clusterware in situations where Oracle Clusterware is used, but the two features are not dependent on each other. For information about Oracle Clusterware, you can refer to Using Oracle Clusterware to Manage Active Standby Pairs in Oracle TimesTen In-Memory Database Replication Guide.
-
Generic automatic client failover: If you create more than one database and have a process to ensure that the data is consistent on both databases, then the client can automatically fail over from one database to another. For example, with a suitable cache configuration, TimesTen automatically synchronizes the data in all of the included TimesTen databases with the data in the Oracle database. In such a scenario, applications can safely failover between multiple caches without any concern about data consistency.
-
In each of these scenarios, applications are automatically connected to the failover TimesTen database. TimesTen provides features that enable applications to be alerted when this happens, enabling the application to take appropriate action.
Note:
If you issue an ALTER SESSION
statement anytime after the initial
connection, you must re-issue the statement after a failover. For information about
connection persistence after failover, see ODBC Support for Automatic Client Failover
in Oracle TimesTen In-Memory Database C Developer's
Guide.
The following sections describe how to use and enable automatic client failover:
Managing Automatic Client Failover in TimesTen Scaleout
By default, if a connection fails in TimesTen Scaleout, then the client automatically attempts to reconnect to another data instance (if possible).
See Client Connection Failover in the Oracle TimesTen In-Memory Database Scaleout User's Guide for full details on managing client connection failover in TimesTen Scaleout.
Managing Automatic Client Failover in TimesTen Classic Using an Active Standby Pair
No state from the original connection, other than the connection handle, is preserved. All client statement handles from the original connection are marked as invalid.
When failover completes, TimesTen makes a callback to a user-defined function that you register. This function takes care of any custom actions you want to occur in a failover situation.
The following items list the behavior of automatic client failover in particular failure scenarios:
-
If the client library loses the connection to the active master, it fails over and attempts to switch to the standby master.
-
If, for some reason, there is no active master (no failover has occurred at the server side and both servers are either standby or idle), applications cannot connect. But automatic client failover continues to alternate between both servers until it finds an active master or times out.
-
If a failover has already occurred and the client is already connected to the new active master, the next failover request results in an attempt to reconnect to the original active master. If that fails, alternating attempts are made to connect to the two servers until it times out.
-
If the active master fails before the client registration is successfully propagated by replication to the standby master, the client does not receive a failover message and the connection registration is lost. However, the client library eventually notices (through TCP) that its connection to the original active master is lost and initiates a failover attempt.
Note:
Using automatic client failover with an active standby pair replication scheme results in one additional database connection per server process. This should be considered when you choose a setting for the TimesTen Connections
attribute (the upper limit of the number of concurrent connections to the database). The number of server processes, in turn, is affected by the setting of the MaxConnsPerServer
attribute (maximum number of concurrent connections a server process can handle).
For example, if you have 12 connections and MaxConnsPerServer=3
, then there are four server processes. Therefore, if some of the connections use automatic client failover, then there are four additional connections.
For C developers, details of how to create the callback and to facilitate an automatic client failover are discussed in ODBC Support for Automatic Client Failover in the Oracle TimesTen In-Memory Database C Developer's Guide. For Java developers, details are discussed in JDBC Support for Automatic Client Failover in the Oracle TimesTen In-Memory Database Java Developer's Guide.
Managing Generic Automatic Client Failover in TimesTen Classic
You can configure generic automatic client failover across any set of TimesTen Classic databases.
You can configure a list of failover TimesTen databases in the user
or system odbc.ini
file. Once configured, the application
can try to connect to each of them until a successful connection is made.
This feature applies only to client/server connections, not direct
connections.
Note:
You must ensure that automatic client failover is meaningful in your environment. That is, there is no possibility of any data consistency issues when failing over between the included databases. In addition, the client can locate the necessary tables and data in any database to which it fails over.
Consider the following for each TimesTen Classic database included in the failover server list:
-
Participating databases must be TimesTen release 18.1.4.1.0 or later.
-
The same database user name and password must be used for client connections to all databases.
-
The failover databases should have the same table and/or cache group definitions. You must have a process to ensure that the data is consistent on all databases for all tables and/or cache group tables.
-
To facilitate a fast failover, all of the databases in the client failover list should be loaded in memory.
-
When using cache, the databases should have operational cache agents at all times.
-
The databases included in the generic automatic failover do not use an active standby pair replication scheme.
A typical use case for generic automatic failover is a set of databases using read-only caching, where each database has the same set of cached data. For example, if you have several read-only cache groups, then you would create the same read-only cache groups on all TimesTen Classic databases included in the list of failover servers. When the client connection fails over to an alternate TimesTen database, the cached data is consistent since cache operations automatically refresh the data (as needed) from the Oracle database. See Read-Only Cache Group in the Oracle TimesTen In-Memory Database Cache Guide for more details on read-only cache groups.
Note:
When failover happens, the application will need to re-prepare all statements.
For C developers, details of how to create the callback and to facilitate an automatic client failover are discussed in ODBC Support for Automatic Client Failover in the Oracle TimesTen In-Memory Database C Developer's Guide. For Java developers, details are discussed in JDBC Support for Automatic Client Failover in the Oracle TimesTen In-Memory Database Java Developer's Guide.
Configuring Automatic Client Failover for TimesTen Classic
A list of failover TimesTen databases can be configured on the client. Then, clients initiate a connection to each failover TimesTen database, until a successful connection is made.
Note:
The failover server information you provide depends on which type of automatic client failover you want to use. That is, the failover server should be either the standby database (when using an active standby pair replication scheme) or a second TimesTen database (when using read-only cache groups). See Using Automatic Client Failover for details on both types of automatic client failover.
The following sections describe how to configure for automatic client failover for TimesTen Classic:
Configuring Automatic Client Failover for TimesTen Classic on Windows
In the TimesTen client DSN Setup dialog, after you have configured the rest of the client DSN information as described in Creating and Configuring Client DSNs on Windows, complete the following fields:
Configuring TCP Keep-Alive Parameters
One of the ways that a client connection can fail is with a network failure, such as disconnecting a cable or a host that is suspending or crashing.
When the client connection is lost, then client connection failover is initiated. However, when a TCP connection is started, you can configure the TCP keep-alive parameters for the connection to ensure reliable and rapid detection of connection failures.
Note:
You can also detect that there is a problem with the connection by setting the TTC_Timeout
attribute, which sets a maximum time limit for a network operation that is completed by using the TimesTen client and server. The TTC_Timeout
attribute also determines the maximum number of seconds a TimesTen client application waits for the result from the corresponding TimesTen Server process before timing out.
TimesTen recommends configuring the TCP keep-alive parameters for determining a failed TCP connection in addition to the TTC_TIMEOUT
attribute, as some database operations may unexpectedly take longer than the value set for the TTC_TIMEOUT
attribute.
Refer to TTC_Timeout in Oracle TimesTen In-Memory Database Reference.
You can control the per connection keep-alive settings with the following parameters:
-
TTC_TCP_KEEPALIVE_TIME_MS
: The duration time (in milliseconds) between the last data packet sent and the first probe. The default is 10000 milliseconds.Note:
The Linux client platform converts this value to seconds by truncating the last three digits off of the value of
TTC_TCP_KEEPALIVE_TIME_MS
. Thus, a setting of 2500 milliseconds becomes 2 seconds, instead of 2.5 seconds. -
TTC_TCP_KEEPALIVE_INTVL_MS
: The time interval (in milliseconds) between subsequential probes. The default is 10000 milliseconds. -
TTC_TCP_KEEPALIVE_PROBES
: The number of unacknowledged probes to send before considering the connection as failed and notifying the client. The default is set to 2 unacknowledged probes.
If you keep the default settings, then TimesTen sends the first probe after 10 seconds (the TTC_TCP_KEEPALIVE_TIME_MS
setting).
-
If there is a response, then the connection is alive and the
TTC_TCP_KEEPALIVE_TIME_MS
timer is reset. -
If there is no response, then TimesTen sends another probe after this initial probe at 10 second intervals (the
TTC_TCP_KEEPALIVE_INTVL_MS
setting). If no response is received after 2 successive probes, then this connection is terminated and TimesTen redirects the connection to another data instance.
For example, you could modify the TCP keep alive settings to have a shorter wait time for the initial probe of 50000 milliseconds, and to check for a connection every 20000 milliseconds for a maximum number of 3 times as follows:
TTC_TCP_KEEPALIVE_TIME_MS=50000 TTC_TCP_KEEPALIVE_INTVL_MS=20000 TTC_TCP_KEEPALIVE_PROBES=3
See the TTC_TCP_KEEPALIVE_TIME_MS, TTC_TCP_KEEPALIVE_INTVL_MS, and TTC_TCP_KEEPALIVE_PROBES sections in the Oracle TimesTen In-Memory Database Reference.