3 Working with the TimesTen Client and Server

You can open client/server connections across a network to the TimesTen database with the TimesTen Client and TimesTen Server.

The following sections describe the TimesTen Client/Server and how to connect using them:

Overview of the TimesTen Client/Server

The TimesTen Server is a process that runs on a server system that takes network requests from TimesTen Clients and translates them into operations on databases on the server system. This enables clients to connect to databases that are located on different systems, potentially running a different platform and operating system.

You can install the TimesTen Client on a separate or the same system as the TimesTen Server. If you install the TimesTen Client on the same system as the TimesTen Server, you can use it to access TimesTen databases on the local system.

Note:

You can create a client/server connection between any combination of platforms that TimesTen supports.

TimesTen does not support IP-level failover or load-balancing with Client/Server.

Figure 3-1 demonstrates how the TimesTen Client and TimesTen Server communicate using their respective drivers.

Figure 3-1 Diagram of TimesTen Client and TimesTen Server

Description of Figure 3-1 follows
Description of ''Figure 3-1 Diagram of TimesTen Client and TimesTen Server''

  • TimesTen Client: To access TimesTen databases on remote systems, link your application with the TimesTen Client ODBC driver. The application then communicates with the TimesTen Server process. Using the TimesTen Client ODBC driver, applications can connect transparently to TimesTen databases on a remote or local system that has TimesTen installed.

    You can link a client application directly with the TimesTen Client ODBC driver or with the Windows ODBC driver manager to access the TimesTen database. TimesTen supplies a driver manager for Linux, UNIX, and Windows with the Quick Start sample applications. Note that there are performance considerations in using a driver manager.

    Also, you can link a client application through a provided interface, like JDBC, OCI or Pro*C/C++, to access the TimesTen database.

    Note:

    For details on how the application can use different drivers and interfaces to access a TimesTen database, see "Connecting to TimesTen with ODBC and JDBC drivers"

  • TimesTen Server: On the server system, the TimesTen Server uses the TimesTen Data Manager driver. The server's responsibility is to listen for requests from a client application, process the request through the TimesTen Data Manager driver, and then send the results and any error information back to the client application.

Note:

For details on compiling and linking TimesTen applications, see "Compiling Java applications" in the Oracle TimesTen In-Memory Database Java Developer's Guide or "Compiling and linking applications" the Oracle TimesTen In-Memory Database C Developer's Guide.

The following sections describe the restrictions and the communication protocols for client/server communication:

Restrictions on client/server communication

The following are the restrictions on client/server communication:

  • On Linux and UNIX, some TimesTen utilities only work over direct connections, such as ttAdmin, ttRepAdmin, and ttBackup. The utilities that can be executed over a client/server connection on the Linux and UNIX platforms are named with a suffix of CS, such as ttIsqlCS, ttBulkCpCS, ttMigrateCS and ttSchemaCS. These utilities have been linked with the TimesTen Client driver and can be used to connect to Client DSNs when accessing a database over a client/server connection. Each utility listed in the Oracle TimesTen In-Memory Database Reference provides the name of the client/server version of that utility, if there is one.

  • XLA cannot be used over a client/server connection and is only supported within TimesTen Classic.

  • The ttCacheUidPwdSet built-in procedure cannot be used over a client/server connection.

  • You cannot connect with an external user defined on one host to a TimesTen data source on a remote host. There are no restrictions for connecting with internal users. See "Overview of TimesTen users" in the Oracle TimesTen In-Memory Database Security Guide for details on internal and external users.

  • You cannot create or alter internal users over a client/server connection. Thus, you can only issue the CREATE USER or ALTER USER statements using a direct connection to the TimesTen database. Once created, the user that connects from the client to the server must be granted the CREATE SESSION privilege or the connection fails. For more information on how to create the user on the TimesTen database and how the administrator grants the CREATE SESSION privilege, see "Creating or identifying a database user" and "Privileges to connect to the database" in the Oracle TimesTen In-Memory Database Security Guide.

  • On Linux and UNIX, TimesTen does not allow a child process to use a connection opened by its parent. Any attempt from a child process using fork() to use a connection opened by the parent process returns an error.

Communication protocols for Client/Server communication

The following sections describe the communication protocols that the TimesTen Client can use with the TimesTen Server:

TCP/IP Communication

By default, the TimesTen Client communicates with the TimesTen Server using TCP/IP sockets. This is the only form of communication available when the TimesTen Client and Server are installed on different systems.

Shared memory communication

If both the TimesTen Client and Server are installed on the same system, applications using the TimesTen Client ODBC driver may use a shared memory segment for inter-process communication (IPC). Using a shared memory segment provides better performance than TCP/IP communication. To use a shared memory segment as communication, you must:

  1. Configure the server attributes to use shared memory communication in the timesten.conf file. See "Using shared memory for Client/Server IPC".

  2. Define the Network Address as ttShmHost in the logical server name. See "Defining a logical server name" for details.

Note:

TimesTen supports a maximum of 16 different instances of the shared memory IPC-enabled server. If an application tries to connect to more than 16 different shared memory segments it receives an error.

UNIX domain socket communication

On Linux and UNIX platforms, if both the TimesTen Client and Server are installed on the same system, you can use UNIX domain sockets for communication. Using a shared memory segment allows for the best performance but slightly greater memory usage. Using UNIX domain sockets allows for improved performance over TCP/IP, but with less memory consumption than a shared memory segment connection. To use domain sockets, you must define the Network Address of the logical server as ttLocalHost. See "Defining a logical server name" for more information.

Configuring TimesTen Client and Server

Note:

Before configuring the TimesTen Client and Server, read "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:

Overview of TimesTen Client/Server configuration

Before the client application can connect to a TimesTen database, the user must configure, as shown in Figure 3-2, the Client DSN, optionally a logical server name, and a Server DSN to uniquely identify the desired TimesTen database.

Figure 3-2 Configuring for a client/server connection

Description of Figure 3-2 follows
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 connections

The following sections describe what you must install on which node for client/server connections:

Configuring Client/Server of the same TimesTen release

The following sections describe how to install and configure 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.

  1. Install the TimesTen Server.

    For information on how to install the TimesTen Server, see the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide.

  2. 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

Perform the following tasks on the system where the client application resides. This system is called the client system.

  1. Install the TimesTen Client.

    For information on how to install the TimesTen Client, see the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide.

  2. 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 for details.

  3. 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".

  4. 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.

  5. 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.

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 "Configuring 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.

  • If you are using a local client/server connection over a shared memory IPC using ttShmHost, then:

    • The client must be running on the same host as the server and thus must be on the same platform.

    • The platform must be UNIX or Linux; Windows and macOS are not supported for shmipc (since they are client-only platforms).

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 system sys.odbc.ini file with the ttGridAdmin gridClientExport command. This command exports every client/server connectable available for the grid into a file that is formatted to replace the odbc.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 for full details.

  • With TimesTen Classic, you create each system DSN by creating or editing the user odbc.ini file or the system sys.odbc.ini file. You can add or configure a Server DSN while the TimesTen Server is running. For details on how to create system DSNs for TimesTen Classic on Linux and UNIX, 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, execute this command within the ttGridAdmin instanceExec command.

% ttDaemonAdmin -restartserver

  • Connections attribute: Sets the upper limit of the number of concurrent connections to the database. The default value is the lesser of 2000 or the number of semaphores specified in the SEMMSL kernel parameter minus 155. TimesTen allocates one semaphore for each expected connection, therefore the SEMMSL 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 "Set the semaphore values" and "Configure shmmax and shmall" in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide or "Connections" in the Oracle TimesTen In-Memory Database Reference for more details.

  • ServerStackSize: Set the stack size for each thread on the server.

    The ServerStackSize attribute is ignored unless the MaxConnsPerServer attribute is greater than one. If there is only one connection per Server, the server process uses the process' main stack. Consider setting the ServerStackSize attribute to 1024 KB or greater if you are running complex SQL queries on your client connections.

    See "ServerStackSize" in the Oracle TimesTen In-Memory Database Reference for more details.

  • MaxConnsPerServer: Set the maximum number of client connections that are handled by a single server process. Setting MaxConnsPerServer > 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.

    See "MaxConnsPerServer" in the Oracle TimesTen In-Memory Database Reference for more details.

    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. The ServersPerDSN attribute specifies the number of server processes to spawn in connection with the MaxConnsPerServer attribute for distribution of incoming connections.

    See "ServersPerDSN" in the Oracle TimesTen In-Memory Database Reference for more details.

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:

  1. The first incoming connection spawns a new server process. Each additional incoming connection spawns a new server process up to the ServersPerDSN value.

  2. The next ServersPerDSN number of incoming connections are assigned to the existing server processes in a round-robin fashion up to MaxConnsPerServer connections per server.

  3. Once the MaxConnsPerServer is reached for servers spawned up to ServersPerDSN, 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, and MaxConnsPerServer 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 and MaxConnsPerServer are reached, so server process 6 is started to handle connection 11.

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

To create and configure a logical server name:

  1. 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.

  2. Click User DSN or System DSN.

  3. Select a TimesTen Client DSN and click Configure.

    Note:

    If no Client DSN exists, click Add, select TimesTen Client 18.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.

  4. Click Servers. This opens the TimesTen Logical Server List dialog.

  5. Click Add. This opens the TimesTen Logical Server Name Setup dialog.

  6. In the Server Name field, enter a logical server name.

  7. In the Description field, enter an optional description for the server.

  8. In the Network Address field, enter the host name or IP address of the server system. The Network Address must be one of:

    Type of connection Network Address
    Remote client/server connection The name of the system where the TimesTen Server is running. For example, example.com
    Local client/server connection that uses shared memory for inter-process communication (IPC) ttShmHost

    In order to use shared memory as IPC, verify that you have configured your system correctly. See "Shared memory communication".

  9. 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:

    Description of server.png follows
    Description of the illustration ''server.png''

  10. Click OK, then click Close in the TimesTen Logical Server List dialog to finish creating the logical server name.

To delete a server name:

  1. On the Windows Desktop on the client system from the Start menu, select Control Panel.

  2. Double click ODBC. This opens the ODBC Data Source Administrator.

  3. Click either User DSN or System DSN.

  4. Select a TimesTen Client DSN and click Configure. This opens the TimesTen Client DSN Setup dialog.

  5. Click Servers. This opens the TimesTen Logical Server List dialog.

  6. Select a server name from the TimesTen Servers list.

  7. 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:

  1. In the file specified by the SYSTTCONNECTINI environment variable, if it is set

  2. In the timesten_home/conf/sys.ttconnect.ini file

Working with the 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

[ServerName]

Logical server name of the TimesTen Server system

Description=description

Description of the TimesTen Server

Network_Address=network-address

The DNS name, host name or IP address of the system on which the TimesTen Server is running.

TCP_Port=port-number

The TCP/IP port number where the TimesTen Server is running. Default for TimesTen release 18.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, server.example.com
Local client/server connection that uses UNIX domain sockets ttLocalHost
Local client/server connection that uses shared memory for inter-process communication ttShmHost

Example 3-1 Defining a logical server name

This example from a ttconnect.ini file defines a logical server name, LogicalServer, for a TimesTen Server running on the system server.example.com and listening on port 6625. The instance name of the TimesTen installation is instance.

[LogicalServer]
Description=TimesTen Server 18.1
Network_Address=server.example.com
TCP_Port=6625

Example 3-2 Using UNIX domain sockets for communication

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 18.1 through domain sockets
Network_Address=ttLocalHost
TCP_Port=6625

Example 3-3 Configuring shared memory for inter-process communication

If both the client and server are on the same system, applications can use shared memory for inter-process communication. This may result in the best performance.

The logical server name must also define the port number on which the TimesTen Server is listening in order to make the initial connection. To achieve this, the logical server name definition in ttconnect.ini file might look like:

[ShmHost]
Description= Local TimesTen Server 18.1 through shared memory
Network_Address=ttShmHost
TCP_Port=6625

Creating 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 "TimesTen Client 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:

Creating a Client DSN on Windows

To define a TimesTen Client DSN:

  1. 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.

  2. Choose either User DSN or System DSN. For a description of user DSNs and system DSNs see "Specifying Data Source Names to identify TimesTen databases".

  3. Click Add. This opens the Create New Data Source dialog.

    Description of add_dsn.png follows
    Description of the illustration ''add_dsn.png''

  4. Choose TimesTen Client 18.1 to select the TimesTen Client driver. Click Finish. This opens the Oracle TimesTen Client DSN Setup dialog.

    Description of setup_adv.png follows
    Description of the illustration ''setup_adv.png''

  5. In the Client DSN field, enter a name for the Client DSN.

    The name must be unique to the current list of defined DSNs on the system where the client application resides and can contain up to 32 characters. To avoid potential conflicts, you may want to use a consistent naming scheme that combines the logical server name with the name of the Server DSN. For example, a corporation might have Client DSNs named Boston_Accounts and Chicago_Accounts where Boston and Chicago are logical server names and Accounts is a Server DSN.

  6. In the Description field, enter an optional description for the Client DSN.

  7. In the Server Name or Network Address field, specify the logical server or network address of the server system.

    • The name can be a host name, IP address or logical server name. The logical server names defined on the client system can be found in the drop-down list. To define logical server names, click Servers.

    • If you do not specify a logical server name in this field, the TimesTen Client assumes that the TimesTen Server is running on the default TCP/IP port number. Therefore, if your Server is running on a port other than the default port and you do not specify a logical server name in this field, you must specify the port number in the ODBC connection string, using the TCP_Port attribute.

      For more information on defining logical server names, see "Creating and configuring a logical server name on Windows".

  8. In the Server DSN field, enter the Server DSN corresponding to the database that the client application accesses.

    • If you do not know the name of the Server DSN, click Refresh to obtain a list of Server DSNs that are defined on the system specified in the Server Name or Network Address field. Select the Server DSN from the drop-down list.

    • You must have a network connection to the system where the TimesTen Server is running.

    See "ODBC Data Sources" for more information about customizing which Server DSNs show in this list.

  9. In the Connection Character Set field, choose a character set that matches your terminal settings or your data source. The default connection character set is AL32UTF8. For more information, see "ConnectionCharacterSet" in Oracle TimesTen In-Memory Database Reference.

  10. If you are using automatic client failover, you would configure the Failover Server Name, Failover Port Range, Failover DSN, and No Reconnect On Failover. See "Using automatic client failover" for more details.

  11. If you are using TimesTen Scaleout, you would configure the TCP KeepAlive Time, TCP KeepAlive Interval, and TCP KeepAlive Probes. For details, see "Configuring TCP keep-alive parameters" in this guide and "TTC_TCP_KEEPALIVE_TIME_MS", "TTC_TCP_KEEPALIVE_INTVL_MS", and "TTC_TCP_KEEPALIVE_PROBES" in the Oracle TimesTen In-Memory Database Reference.

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. It is strongly discouraged to supply the password in the Client DSN, since the password is stored unencrypted on the client.

For a description of the UID, PWD, and TTC_TIMEOUT attributes, see "Connection Attributes" in the Oracle TimesTen In-Memory Database Reference.

To set the network timeout interval and authentication:

  1. 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.

  2. In the Password field, enter the password that corresponds to the user ID. Alternatively, you can enter an encrypted password in the PwdCrypt field.

  3. 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. 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.

  4. 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.

  1. On the server system server.example.com, use the ttStatus utility to verify that the TimesTen Server is running and to verify the port number it is listening on.

  2. 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 on server.example.com.

  3. 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 18.1. This value should correspond to the value displayed by ttStatus in Step 1.

    See "Creating and configuring a logical server name on Windows" for the procedure to open the TimesTen Server Name dialog and for more details.

  4. 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.

  5. Run the client application from the system client.example.com using the Client DSN, database1CS. The example below uses the ttIsql 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:

  1. Define the logical server name LogicalServer with server.example.com as the Network Address and 6625 as the Network Port. Define Client_DSN as the Client DSN with LogicalServer as the Server name and Server_DSN as the Server DSN. Then, execute the command:

    % ttIsql -connStr "DSN=Client_DSN"

  2. Alternatively, define the logical server name LogicalServer_tt with server.example.com as the Network Address and the default port number as the Network Port. Define Client_DSN as the Client DSN with LogicalServer as the Server name and Server_DSN as the Server DSN. Overwrite the port number in the command:

    % ttIsql -connStr "DSN=Client_DSN;TCP_Port=6625"
Testing connections

To test client application connections to TimesTen databases:

  1. On the Windows Desktop from the Start menu, select Settings, and then select Control Panel.

  2. Double click ODBC. This opens the ODBC Data Source Administrator.

  3. Click User DSN or System DSN.

  4. Select the TimesTen Client DSN whose connection you want to test and click Configure. This opens the TimesTen Client DSN Setup dialog.

  5. Click Test TimesTen Server Connection to test the connection to TimesTen Server.

    The ODBC Data Source Administrator attempts to connect to TimesTen Server and displays messages to indicate if it was successful. During this test TimesTen Client verifies that:

    • ODBC, Windows sockets and TimesTen Client are installed on the client system.

    • The server specified in the Server Name or Network Address field of the TimesTen Client DSN Setup dialog is defined and the corresponding system exists.

    • The TimesTen Server is running on the server system.

  6. Click Test Data Source Connection to test the connection to the Server DSN. The ODBC Data Source Administrator attempts to connect to the Server DSN and displays messages to indicate whether it was successful.

    During this test, TimesTen Client verifies that:

    • The Server DSN specified in the Server DSN field is defined on the server system.

    • A client application can connect to the Server DSN.

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.

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.

    Note:

    See "Connecting using TimesTen ODBC drivers" for a list of all available ODBC client drivers.

  • 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 18.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" in the Oracle TimesTen In-Memory Database Reference for options on how to provide the user ID when connecting.

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.

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 the 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 TimesTen Cache configuration, TimesTen Cache 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 "Using automatic client failover in your application" 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

When you use an active standby pair replication scheme in TimesTen Classic and an application connects to the active master, then the connection is registered and this registration is replicated to the standby master. If the active master fails, the standby master becomes the active master and then notifies the client of the failover. At this point, the client has a new connection to the new active master. 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.

Notes:

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 "Using automatic client failover in your application" 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 username 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 TimesTen 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 TimesTen Cache automatically refreshes the data (as needed) from the Oracle database. See "Read-only cache group" in the Oracle TimesTen Application-Tier Database Cache User's 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 "Using automatic client failover in your application" 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 Oracle 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:

  1. In the Failover Server Name or Network Address field, specify the logical server or network address of the failover server.

    • The name can be a host name, IP address or logical server. The logical server names defined on the client system can be found in the drop-down list. To define logical server names, click Servers.

    • If you do not specify a logical server name in this field, the TimesTen Client assumes that the TimesTen Server is running on the default TCP/IP port number. Therefore, if the Server is running on a port other than the default port and you do not specify a logical server name in this field, you must specify the port number in the ODBC connection string, using the TCP_Port attribute.

      See "Creating and configuring a logical server name on Windows" for more information on defining logical server names.

  2. In the Failover Server DSN field, enter the Server DSN corresponding to the failover server.

    • If you do not know the name of the Server DSN, click Refresh to obtain a list of Server DSNs that are defined on the system specified in the Failover Server Name or Network Address field. Select the Server DSN from the drop-down list.

    • You must have a network connection to the system where the TimesTen database is running.

  3. If you are using an active standby pair replication scheme for automatic client failover, then you can optionally specify the Failover Port Range for the port or port range where TimesTen listens for failover notifications. Specifying a port range helps accommodate firewalls between client and server systems. With the active standby pair, the active and standby masters notify the clients to failover.

    By default, TimesTen uses a single port chosen by the operating system. A port range is set as a lower and upper value separated by hyphen.

    You only need to specify a port range if both of these conditions are true:

    • You need multiple ports on the firewall between the server and client hosts.

    • You use multiple client applications configured for automatic client failover on a single client host.

    Each client application configured for automatic client failover on a client host needs to listen on a distinct port for failover notifications.

  4. Optionally, select the No Reconnect On Failover check box to have TimesTen perform all the usual client failover processing except for the reconnect. For example, statement and connection handles are marked as invalid. This is useful if the application provides its own connection pooling or manages its own reconnection to the database after client failover.

Configuring automatic client failover for TimesTen Classic on Linux and UNIX

On the client, configure the following:

  1. In the odbc.ini file on the client, define the Client DSNs. Specify the failover servers with the TTC_ServerN connection attribute, where N >= 2. The TTC_ServerN connection attribute can specify the DNS name, host name or IP address of the system (with or without the port number).

    Set the TTC_Server_DSNn connection attribute to the name of this database, where n >= 2.

    Setting any of TTC_ServerN or TTC_Server_DSNn implies the following:

    • You intend to use automatic client failover.

    • You understand that a new client thread is created for your application to support the failover mechanism.

    If you are using automatic client failover for read-only cache groups, you can specify more than one failover server with the TTC_ServerN and TTC_Server_DSNn connection attributes, where N,n >= 2.

    You should specify your failover servers (identified by N) in a sequential order.

    For example:

    [MyDSN]
TTC_Server=server.example.com/6625
TTC_Server_DSN=MyDSN
TTC_Timeout=60
TTC_Server2=server2.example.com/6625
TTC_Server_DSN2=MyDSN_Failover1
TTC_Server3=server3.example.com/6625
TTC_Server_DSN3=MyDSN_Failover2

    Notes:

    • Optionally, you can define logical server names for your failover servers in the ttconnect.ini file on the client with the Network_Address and TCP_Port. See "Creating and configuring a logical server name on Linux and UNIX" for more information on defining logical server names.

    • Like other connection attributes, TTC_ServerN and TTC_Server_DSNn can be specified in the connection string, overriding any settings in the DSN. The default TCP/IP port number is assumed for TCP_Port and TCP_PortN unless you specify a value in the TTC_ServerN connection attribute, in the connection string, or in the logical server definition in ttconnect.ini.

    Refer to "TTC_Server or TTC_Server1", "TTC_Server2, TTC_ServerN", "TTC_Server_DSN2, TTC_Server_DSNn", and "TCP_Port2, TCP_PortN" in Oracle TimesTen In-Memory Database Reference for more information.

  2. If you are using automatic client failover with read-only cache groups and you have specified more than one alternate failover server, you can specify how the client selects the failover server. By default, the client selects from a randomly ordered list of servers provided by TTC_Server and TTC_ServerN attributes.

    However, if you set TTC_Random_Selection to 0, then the client selects the first server specified by the TTC_ServerN connection attributes. If the client cannot connect to the first server specified, the client proceeds to the next failover server in the order specified numerically.

    Note:

    If you are using an active standby pair for automatic client failover and the client library cannot connect to the active master specified by TTC_Server_DSN, then it tries the standby master specified by TTC_Server_DSN2.

    Refer to "TTC_Random_Selection" in Oracle TimesTen In-Memory Database Reference for more information.

  3. Optionally, set a timeout to specify a duration for all failover recovery attempts in the odbc.ini file on the client.

    When TimesTen attempts to recover from failure using automatic client failover, the TTC_TIMEOUT connection attribute specifies the duration for all attempts at failover recovery. The connection might be blocked while failover is attempted. For example:

    [MyDSN]
TTC_Server=server.example.com/6625
TTC_Server_DSN=MyDSN
TTC_Timeout=60
TTC_Server2=server2.example.com/6625
TTC_Server_DSN2=MyDSN_Failover1
TTC_Server3=server3.example.com/6625
TTC_Server_DSN3=MyDSN_Failover2

    Refer to "TTC_Timeout" in Oracle TimesTen In-Memory Database Reference for information.

  4. If you are using an active standby pair replication scheme for client failover, then you can optionally configure the TTC_FailoverPortRange attribute to specify a port or port range where the failover thread listens for failover notifications. Specifying a port range helps accommodate firewalls between client and server systems. With the active standby pair, the active and standby masters notify the clients to failover.

    By default, TimesTen uses a single port chosen by the operating system. A port range is set as a lower and upper value separated by hyphen.

    You only need to specify a port range if both of these conditions are true:

    • You need multiple ports on the firewall between the server and client hosts.

    • You use multiple client applications configured for automatic client failover on a single client host.

    Each client application configured for automatic client failover on a client host needs to listen on a distinct port for failover notifications.

  5. Optionally, enable the TTC_NoReconnectOnFailover attribute to have TimesTen perform typical client failover, but without reconnecting. This is useful where an application does its own connection pooling or attempts to reconnect to the database on its own after failover. The default value is 1 and indicates that TimesTen should attempt to reconnect.

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 hanging 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 for more information about that attribute.

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 aborted 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 for more information on these connection attributes.

Running the TimesTen Server

The TimesTen Server is a child process of the TimesTen daemon. If you installed the TimesTen Server, this process is automatically started and stopped when the TimesTen daemon is started or stopped. You can explicitly start or shut down the daemon or service with the ttDaemonAdmin utility (use ttGridAdmin instanceExec to execute this command on TimesTen Scaleout). The TimesTen Server is run as the instance administrator.

The TimesTen Server handles requests from applications linked with the TimesTen Client driver.

The default ports for TimesTen daemon and TimesTen Servers are described in the "The ttInstanceCreate utility" chapter in the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide. System administrators can change the port number during installation to avoid conflicts or for security reasons. The port range is from 1 - 65535. To connect to the TimesTen Server, Client DSNs are required to specify the port number as part of the logical server name definition or in the connection string.

For instructions on modifying TimesTen Server options, see "Modifying the TimesTen Server attributes".

Server informational messages

The TimesTen Server records "connect," "disconnect" and various warning, error and informational entries in log files.

On Linux and UNIX, the TimesTen Server logs messages to the timesten_home/diag/ttmesg.log and timesten_home/diag/tterrors.log files by default. Optionally, you can configure TimesTen to log messages to the syslog facility.

See "Error, warning, and informational messages".

Accessing a remote database on Linux and UNIX

In this example, the TimesTen Client application system is client.example.com. The client application is accessing the Server DSN database1 on the remote server system, server.example.com. The logical server name is LogicalServer. The instance name of the TimesTen installation is instance.

  1. On the server system server.example.com, use the ttStatus utility to verify that the TimesTen Server is running and to verify the port number on which it is listening.

  2. Verify that the Server DSN database1 exists in the system sys.odbc.ini file on server.example.com.

    There should be an entry in the sys.odbc.ini file as follows. Note that /disk1/timesten is the timesten_home.

    [database1]
DataStore=/disk1/timesten/server/database1

  3. Create a logical server name entry for the remote TimesTen Server in the ttconnect.ini file on client.example.com.

    [LogicalServer]
Network_Address=server.example.com
TCP_Port=6625

    See "Creating and configuring Client DSNs on Linux and UNIX" for information on the creating a ttconnect.ini file.

  4. On the client system, client.example.com, create a Client DSN corresponding to the remote Server DSN, database1.

    There should be an entry in the odbc.ini file as follows:

    [database1CS]
TTC_Server=LogicalServer
TTC_Server_DSN=database1

    See "Overview of user and system DSNs" for information on the location of the proper odbc.ini file.

  5. Run the client application from the system client.example.com using the Client DSN, database1CS. The example below uses the ttIsql program that is installed with TimesTen Client.

    % ttIsqlCS -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.

Let us consider 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:

  1. Define the logical server name LogicalServer with server.example.com as the Network Address and 6625 as the Network Port. Define Client_DSN as the Client DSN with LogicalServer as the server name and Server_DSN as the Server DSN. Execute the command:

    % ttIsqlCS -connStr "DSN=Client_DSN"

  2. Alternatively, define the logical server name logical_server with server.example.com as the Network Address and the default port number as the Network Port. Define a Client DSN with LogicalServer as the server name and Server_DSN as the Server DSN. Overwrite the port number in the command:

    % ttIsqlCS -connStr "DSN=Client_DSN;TCP_Port=6625"

  3. Alternatively, define the server in the connection string. In this case you do not need to define a Client DSN, nor a logical server name.

    % ttIsqlCS -connStr "TTC_Server=server.example.com;TTC_Server_DSN=Server_DSN;TCP_Port=6625"

Testing connections

To test client application connections to TimesTen databases:

  1. Verify that the client system can access the server system.

  2. Run ping from the client system to see if a response is received from the server system.

  3. Verify that the TimesTen Server is running on the server system.

    • Use telnet to connect to the port on which the TimesTen Server is listening. For example:

      % telnet server.example.com 6625

    • If you successfully connect to the TimesTen Server, you see a message similar to:

      Connected to server.example.com

    • If the server system responds to a command, but TimesTen Server does not, the TimesTen Server may not be running. In the case of a failed connection, you see a message similar to:

      telnet: Unable to connect to remote host: Connection refused

    • Use the ttStatus utility on the server system to determine the status and port number of the TimesTen Server. Generally, the TimesTen Server is started at installation time. If the TimesTen Server is not running, you must start it. For information on starting the TimesTen Server, see "Modifying the TimesTen Server attributes".

  4. Verify that the client application can connect to the database. If you cannot establish a connection to the database, check that the ttconnect.ini file contains the correct information.

  5. If the information in the ttconnect.ini file is correct, check that a Server DSN corresponding to the database has been defined properly in the system sys.odbc.ini file on the host where the database resides and where the TimesTen Server is running.