2 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 machine that takes network requests from TimesTen Clients and translates them into operations on databases on the server machine. This enables clients to connect to databases that are located on different machines, potentially running a different platform and operating system bit level.

You can install the TimesTen Client on a separate or the same machine as the TimesTen Server. If you install the TimesTen Client on the same machine as the TimesTen Server, you can use them to access TimesTen databases on the local machine. For example, this is useful when you want a 32-bit application to access a 64-bit database on the same machine, for platforms that support both 32-bit and 64-bit applications.

Note:

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

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

Figure 2-1 Diagram of TimesTen Client and TimesTen Server

Diagram of TimesTen client and server
Description of "Figure 2-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 driver, applications can connect transparently to TimesTen databases on a remote or local system that has the TimesTen Server and Data Manager installed.

    You can link a client application either directly with the TimesTen Client driver or with the Windows ODBC driver manager. TimesTen supplies a driver manager for Windows with the Quick Start sample applications. Note that there are performance considerations in using a driver manager.

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

Note:

For details on compiling TimesTen applications, see the Oracle TimesTen In-Memory Database Java Developer's Guide or 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:

  • XLA cannot be used over a client/server connection.

  • On 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 UNIX platform 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.

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

  • Internal users can only be created or altered over a direct connection and not over a client/server connection to a TimesTen database. Thus, you can only execute 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 will fail. 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 users to the database" and "Granting privileges to connect to the database".

  • On 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

By default, a server process is spawned at the time a client requests a connection. By setting the -serverPool option in the ttendaemon.options file on the server machine, you can pre-spawn a reserve pool of server processes. See "Prespawning TimesTen Server processes" for details.

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

Shared memory communication

If both the TimesTen Client and Server are installed on the same machine, applications using the TimesTen Client ODBC driver may improve performance by using a shared memory segment for inter-process communication (IPC). Using a shared memory segment allows for the best performance, but consumes more memory. To use a shared memory segment as communication, you must

  1. Configure the server options to use shared memory communication in the ttendaemon.options 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 UNIX platforms, if both the TimesTen Client and Server are installed on the same machine, you can use UNIX domain sockets for communication. Using a shared memory segment allows for the best performance, but 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 a TimesTen 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 2-2, the Client DSN, optionally a logical server name, and a Server DSN to uniquely identify the desired TimesTen database.

Figure 2-2 Configuring for a client/server connection

Description of Figure 2-2 follows
Description of "Figure 2-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 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 Client DSN is configured in either the user or system ODBC.INI file with the server host name, either the logical server name or the actual server machine name, and the Server DSN that identifies the TimesTen database on the server.

  • The Server DSN is configured in the system 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 machine 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 machine on which the TimesTen database resides. This machine is called the server machine.

  1. Install the TimesTen Server. For information on how to install the TimesTen Server, see the Oracle TimesTen In-Memory Database Installation Guide.

  2. Create and configure a Server DSN corresponding to the TimesTen database. See "Defining Server DSNs". 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 machine where the client application resides. This machine is called the client machine.

  1. Install the TimesTen Client. For information on how to install the TimesTen Client, see the Oracle TimesTen In-Memory Database Installation Guide.

  2. If you are using JDBC to connect to the database, install the Java Developer's Kit (JDK), where the Java application will be running 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 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:

Configuring cross-release TimesTen Client/Server

A TimesTen Client can connect to a TimesTen Server from a different release and of a different bit level. A TimesTen Client 7.0 or later release may connect to a TimesTen Server 7.0 or later release of any bit level. 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 and bit level when a TimesTen Client application connects to the TimesTen database. The TimesTen Data Manager is automatically installed on the 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 UNIX. The bit level and 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 platforms for the client and server can be either Windows or UNIX. The bit level may be different on the client and server hosts.

Defining Server DSNs

Server DSNs identify TimesTen databases that are accessed by a client/server connection. A Server DSN must be defined as a system DSN and has the same configuration format and attributes as a TimesTen Data Manager DSN. For a description of DSNs and instructions on creating them, see "Creating a Data Manager DSN on Windows" or "Creating a Data Manager DSN on UNIX".

Note:

You can add or configure a Server DSN while the TimesTen Server is running.

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, including the ones described in the following sections, can be configured in the TimesTen daemon options file (ttendaemon.options). 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 options".

The following sections describe the Server DSN attributes in the context of the ODBC.INI file or the ODBC Data Source Administrator:

Note:

For a complete description of the TimesTen Server connection attributes, see "Connection Attributes" in the Oracle TimesTen In-Memory Database Reference.

Server DSN connection attributes defined in ODBC.INI file

By default, TimesTen creates only one connection to a server per child process. However, the following Server connection attributes enable you to specify multiple client/server connections to a single TimesTen Server:

Note:

These attributes are read at first connection. Changes to TimesTen Server settings do not occur until the TimesTen server is restarted. To restart the Server, use the following command: 
ttDaemonAdmin -restartserver

  • MaxConnsPerServer: Set the maximum number of client connections that are handled by a single server process. The server is referenced by the Server DSN. The server may have multiple server processes, where each process can only have the maximum number of connections as specified by this attribute.

  • ServersPerDSN: You can have multiple server processes serving multiple incoming connections on the server. The ServersPerDSN attribute specifies the number of server processes that are initially spawned on the server. Each new incoming connection spawns a new server process up to the ServersPerDSN. When ServersPerDSN is reached, the existing server processes handle multiple connections up to the number specified in MaxConnsPerServer.

  • ServerStackSize: Set the size of the stack on the Server for each connection.

The MaxConnsPerServer and ServersPerDSN attributes are related. Neither of these attributes limits the number of client connections to given DSN. Instead, they control how connections are distributed over server processes. 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.

Server DSN connection attributes defined in ODBC Data Source Administrator

If you anticipate having more than one connection using the Server DSN, specify appropriate values for the Server DSN attributes as needed. On Windows in the ODBC Data Source Administrator, these are specified on the Server tab.

Figure 2-3 Server tab in TimesTen ODBC Administrator

Server tab of TimesTen ODBC Setup
Description of "Figure 2-3 Server tab in TimesTen ODBC Administrator"

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 Windows or UNIX platforms:

Creating and configuring a logical server name on Windows

To create and configure a logical server name:

  1. On the Windows Desktop, choose Start > Settings > Control Panel > Administrative Tools > 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. If no Client DSN exists, click Add, select TimesTen Client 11.2.1 and click Finish. This opens the TimesTen Client DSN 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 machine. The Network Address must be one of:

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

  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:

    Displaying network port number
    Description of the illustration server.gif

  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 machine, choose Start > Settings > 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 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.

The Network Address must be one of the following:

Type of connection Network address
Local client/server connection that uses UNIX domain sockets ttLocalHost
Local client/server connection that uses shared memory for inter-process communication ttShmHost
Remote client/server connection The name of the machine where the TimesTen Server is running. For example, server. mycompany.com

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 daemon_home_dir/sys.ttconnect.ini file

Example 2-1 Defining a logical server name

This example from a TTCONNECT.INI file defines a logical server name, ttserver_logical, for a TimesTen Server running on the machine server.mycompany.com and listening on port 53385. The instance name of the TimesTen installation is tt1121.

[ttserver_logical]
Description=TimesTen Server 11.2.1
Network_Address=server.mycompany.com
TCP_Port=53385

Example 2-2 Using UNIX domain sockets for communication

If both the client and server are on the same UNIX machine, applications using the TimesTen Client ODBC 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 machine. To achieve this, the logical server name definition in TTCONNECT.INI file might look like:

[LocalHost_tt1121_32]
Description=Local TimesTen Server TimesTen release 11.2.1 through domain sockets
Network_Address=ttLocalHost
TCP_PORT=53385

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

If both the client and server are on the same machine, 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_tt1121]
Description= Local TimesTen Server TimesTen release 11.2.1 through shared memory
Network_Address=ttShmHost
TCP_PORT=53385

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 machine where the TimesTen Client is installed. By default, the TTCONNECT.INI file is install_dir/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.

Defining a server name on UNIX

You can define short-hand names for TimesTen Servers on UNIX in the TTCONNECT.INI file. The format of a TimesTen Server specification in the TTCONNECT.INI file is shown in Table 2-1.

Table 2-1 TimesTen Server format in the TTCONNECT.INI file

Component Description

[ServerName]

Logical server name of the TimesTen Server machine

Description=description

Description of the TimesTen Server

Network_Address=network-address

The DNS name, host name or IP address of the machine 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 11.2.1 is 53385 for 32-bit platforms and 53389 for 64-bit platforms.

For example, the server specification for a remote TimesTen Server might appear as:

[ttserver]
Description=TimesTen Client/Server
Network_Address=server.company.com
TCP_Port=53385

For a local TimesTen Client/Server application that is using UNIX domain sockets, the network address must be defined as ttLocalHost. The server specification might appear as:

[LocalHost1121]
Description=Shm TimesTen Client/Server
Network_Address=ttLocalHost
TCP_Port=53385

For a TimesTen Client/Server application that is using a shared memory segment for inter-process communication, the network address must be defined as ttShmHost. The server specification might appear as:

[ShmHost1121]
Description=Shm TimesTen Client/Server
Network_Address=ttShmHost
TCP_Port=53385

Creating Client DSNs

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 machine 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 "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 connection attributes within the definition of the Client DSN, they will be 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 the Client DSN and its attributes on either the Windows or 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, choose Start > Settings > Control Panel > Administrative Tools > 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.

    Create New Data Source dialog box
    Description of the illustration add_dsn.gif

  4. Choose TimesTen Client 11.2.1. Click Finish. This opens the Oracle TimesTen Client DSN Setup dialog.

    TimesTen Client DSN Setup
    Description of the illustration setup_adv.gif

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

    • The name can be a host name, IP address or logical server name. The logical server names defined on the client machine 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 will access.

    • 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 machine 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 machine where the TimesTen Server is running.

    For more information about customizing which Server DSNs show in this list, see "ODBC Data Sources".

  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 US7ASCII. For more information, see "ConnectionCharacterSet" in Oracle TimesTen In-Memory Database Reference.

Configuring automatic client failover

You can configure automatic client failover for databases that have active standby pair replication schemes. This enables the client to fail over automatically to the server on which the standby database resides.

Note:

See "Using automatic client failover" in Oracle TimesTen In-Memory Database C Developer's Guide for information about connection option persistence after failover.

In the Oracle TimesTen Client DSN Setup dialog, complete the following fields:

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

    • The name can be a host name, IP address or logical server. The logical server names defined on the client machine 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.

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

  2. In the Failover Server DSN field, enter the Server DSN corresponding to the standby database.

    • 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 machine 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 machine where the TimesTen Server is running.

  3. Optionally, specify the Failover Port Range for the port for failover notifications. By default, TimesTen uses a port chosen by the operating system. To accommodate firewalls between the client and server systems, you can specify one value for the port number or a range of port numbers.

Setting the timeout interval and authentication

You can define the user name, password and timeout interval for the client/server connection in the Client DSN with the UID, PWD, and Timeout attributes. However, configuring the authentication in the Client DSN is optional, since you can provide the user name and password when connecting. If you do supply the user name and password in the Client DSN, the password is stored unencrypted on the client.

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

To set the 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 machine.

  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 Timeout Interval 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.

  4. Click OK to save the setup.

Accessing a remote database on Windows

In this example, the TimesTen Client machine is client.mycompany.com. The client application is accessing the Server DSN on the remote server machine, server.mycompany.com. The logical server name is ttserver_logical.

Note:

These examples reference the 32-bit sample DSNs. This is indicated by the extension _32. On 64-bit platforms, the sample DSNs are appended with _64.

  1. On the server machine server.mycompany.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", verify that the Server DSN, RunData1121_32, is defined as a System DSN on server.mycompany.com.

  3. On the client machine, client.mycompany.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 ttserver_logical.

    • In the Network Address field, enter server.mycompany.com.

    • In the Network Port field, enter 53385. This is the default port number for the TimesTen Server on 32-bit platforms for TimesTen Release 11.2.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 machine, client.mycompany.com, create a Client DSN that corresponds to the remote Server DSN, RunData_tt1121_32. In the TimesTen Client DSN Setup dialog, enter the following values:

    • In the Client DSN field, enter RunDataCS_tt1121_32.

    • In the Server Name or Network Address field, enter ttserver_logical.

    • In the Description field, enter a description for the server. Entering data into this field is optional.

    • In the Server DSN field, enter RunData1121_32.

  5. Run the client application from the machine client.mycompany.com using the Client DSN, RunDataCS_tt1121. The example below uses the ttIsqlCS program installed with TimesTen Client.

    ttIsqlCS connStr "DSN=RunDataCS_tt1121_32"

This 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.mycompany.com and the Server is listening on Port 53385. The following methods can be used to connect to a Server DS:

  1. Define the logical server name logical_server with server.mycompany.com as the Network Address and 53385 as the Network Port. Define a Client DSN with logical_server as the Server name, Server_DSN as the Server DSN. And execute the command:

    ttIsqlCS -connStr "DSN=Client_DSN"

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

    ttIsqlCS -connStr "DSN=Client_DSN; TCP_Port=53385"

  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.mycompany.com;
TTC_Server_DSN=Server_DSN; TCP_Port=53385"
Testing connections

To test client application connections to TimesTen databases:

  1. On the Windows Desktop, choose Start > Settings > 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.

    Client DSN Setup dialog box
    Description of the illustration setup_adv.gif

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

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

    • The TimesTen Server is running on the server machine.

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

    • A client application can connect to the Server DSN.

Creating and configuring Client DSNs on UNIX

On UNIX, you define logical server names by editing the TTCONNECT.INI file and you define Client DSNs by editing the user ODBC.INI file for user DSN or the system ODBC.INI file for system DSNs. For a description of user and system DSNs, see "Specifying Data Source Names to identify TimesTen databases".

This section includes the following topics:

Creating a Client DSN

The syntax for defining the Client DSN in the ODBC.INI file is described in "ODBC.INI file entry descriptions".

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:

  • ODBC client driver to use for the connection.

  • The server machine on which the database resides on 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 machine where the database resides.

For each TimesTen database with which the client will connect needs to have two entries:

  • Define the Client DSN name and provide the name of the ODBC client driver to use in the ODBC Data Sources section.

    Note:

    All available ODBC client drivers are listed in "Connecting using TimesTen ODBC drivers".

  • Create an entry with the Client DSN you defined in the ODBC Data Sources section. Within this section, specify the server machine 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 RunDataCS_tt1121_32 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]
RunDataCS_tt1121_32=TimesTen Client 11.2.1

After the ODBC Data Sources section, you would add an entry to specify the server machine 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 RunData_tt1121_32 where the server is configured with a logical server name of ttserver_logical and the Server DSN is RunData_tt1121_32:

[RunDataCS_tt1121_32]
TTC_Server=ttserver_logical
TTC_Server_DSN=RunData_tt1121_32

The TTC_SERVER* attributes are the main attributes for a Client DSN definition. There are only a few client attributes, each of which are for identifying the server. If you provide any server attributes in the client definition, these attributes are ignored. For a description of all the Client DSN attributes used in the ODBC.INI file, see "Connection Attributes" in the Oracle TimesTen In-Memory Database Reference.

Configuring automatic client failover

You can configure automatic client failover for databases that have active standby pair replication schemes. This enables the client to fail over automatically to the server on which the standby database resides.

In the ODBC.INI file, set TTC_SERVER2 to the server on which the standby database resides. Set TTC_SERVER_DSN2 to the name of the standby database.

For example:

[MYDSN FAILOVER]
TTC_SERVER=localhost
TTC_SERVER_DSN=MYDSN
TTC_Timeout=60000
ConnectionCharacterSet=AL32UTF8
TTC_SERVER2=localhost
TTC_SERVER_DSN2=MYDSNSTANDBY

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 or Data Manager service is started or stopped. You can explicitly start or shut down the daemon or service with the ttDaemonAdmin utility.

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

The default ports for the 32-bit and 64-bit versions of TimesTen main and TimesTen Servers are described in the "TimesTen installation" chapter in the Oracle TimesTen In-Memory Database Installation 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.

On Windows, the TimesTen service is run as user SYSTEM. On UNIX, the TimesTen Server is run as the instance administrator.

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

Server informational messages

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

On Windows, these application messages can be accessed with the Event Viewer.

On UNIX, the TimesTen Server logs messages to the syslog facility.

See "Modifying informational messages".

Accessing a remote database on UNIX

In this example, the TimesTen Client application machine is a 32-bit Solaris machine, client.mycompany.com. The client application is accessing the Server DSN RunData_tt1121_32 on the remote server machine, another 32-bit Solaris machine, server.mycompany.com. The logical server name is ttserver_logical. The instance name of the TimesTen installation is tt1121_32.

  1. On the server machine server.mycompany.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 RunData_tt1121_32 exists in the system ODBC.INI file on server.mycompany.com.

    There should be an entry in the ODBC.INI file as follows:

    [RunData_tt1121_32]
Driver=install_dir/lib/libtten.so
DataStore=install_dir/server/RunData_tt1121_32

  3. Create a logical server name entry for the remote TimesTen Server in the TTCONNECT.INI file on client.mycompany.com.

    [ttserver_logical]
# This value for TCP_Port should correspond to the
# value reported by ttStatus when verifying that the
# server is running
Network_Address=server.mycompany.com
TCP_Port=53385

    See "Creating and configuring Client DSNs on UNIX" for information on the creating a TTCONNECT.INI file.

  4. On the client machine, client.mycompany.com, create a Client DSN corresponding to the remote Server DSN, RunData_tt1121_32.

    There should be an entry in the ODBC.INI file as follows:

    [RunDataCS_tt1121_32]
TTC_SERVER=ttserver_logical
TTC_SERVER_DSN=RunData_tt1121_32

    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 machine client.mycompany.com using the Client DSN, RunDataCS_tt1121_32. The example below uses the ttIsql program that is installed with TimesTen Client.

    ttIsqlCS -connStr "DSN=RunDataCS_tt1121_32"

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.mycompany.com and the Server is listening on Port 53385. The following methods can be used to connect to a Server DS:

  1. Define the logical server name logical_server with server.mycompany.com as the Network Address and 53385 as the Network Port. Define a Client DSN with logical_server as the server name, 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.mycompany.com as the Network Address and the default port number as the Network Port. Define a Client DSN with logical_server as the server name, Server_DSN as the Server DSN. Overwrite the port number in the command:

    ttIsqlCS -connStr "DSN=Client_DSN; TCP_Port=53385"

  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.mycompany.com;
TTC_Server_DSN=Server_DSN; TCP_Port=53385"

Testing connections

To test client application connections to TimesTen databases:

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

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

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

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

      telnet server.mycompany.com 53385

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

      Connected to server.mycompany.com

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

      telnet: Unable to connect to remote host: Connection refused

    • Use the ttStatus utility on the server machine 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 options".

  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 ODBC.INI file on the machine where the database resides and where the TimesTen Server is running.