2 Working with the TimesTen Client and Server

TCP/IP Communication

By default, the TimesTen Client communicates with the TimesTen Server daemon 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 set the server options in the ttendaemon.options file. See "Using shared memory for Client/Server IPC". You must also define the Network Address of the logical server as ttShmHost. See "Creating and configuring Client DSNs on Windows" or "Creating and configuring Client DSNs on UNIX".

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 "Creating and configuring Client DSNs on Windows" or "Creating and configuring Client DSNs on UNIX" for more information.

Configuring client/server of the same TimesTen release

Perform the following to configure TimesTen when the client and server are of the same TimesTen release:

1. Install the TimesTen Server on the machine on which the TimesTen data store resides. This machine is called the "server machine." For information on how to install the TimesTen Server, see the Oracle TimesTen In-Memory Database Installation Guide.

2. Install the TimesTen Client on the machine where the client application resides. This machine is called the "client machine." For information on how to install the TimesTen Client, see the Oracle TimesTen In-Memory Database Installation Guide.

3. If you are using JDBC to connect to the database, install the Java Developer's Kit (JDK) on the client machine, where the Java application will be running and set up the environment variables, such as CLASSPATH and LIBRARY PATH, on the client machine. See "Setting the Java environment variables" in the Oracle TimesTen In-Memory Database Java Developer's Guide for details.

4. On the server machine, create and configure a Server DSN corresponding to the TimesTen data store. See "Defining Server DSNs".

5. On the client machine, 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".

6. For OCI and Pro*C client/server connections, configure the application to use either tnsnames.ora or easy connect on the client as described in "Connecting to a TimesTen Datastore from OCI" in the Oracle TimesTen In-Memory Database C Developer's Guide.

7. Set TimesTen Client connection attributes. See "Data Store Attributes" in the Oracle TimesTen In-Memory Database Reference.

8. 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 applications in the same manner as any OCI or Pro*C direct mode applications are linked, which is described in "TimesTen Support for Oracle Call Interface" and "TimesTen Support for the Oracle Pro*C/C++ Precompiler" in the Oracle TimesTen In-Memory Database C Developer's Guide.

Configuring cross-release Client/Server

A TimesTen Client can connect to a TimesTen Server from a different release and of a different bit level.

• A TimesTen Client 6.0 release may connect to a TimesTen Server 6.0 or 7.0 release of any bit level.

  Note:

  For a TimesTen 6.0 Client to connect successfully to a TimesTen Server release 7.0, the -insecure-backwards-compat option must be set in the ttendaemon.options file for the TimesTen Server.

• A TimesTen Client 7.0 or later release may connect to a TimesTen Server 7.0 or later release of any bit level.

The TimesTen Server loads a driver and a TimesTen database of its own release and bit level when the TimesTen Client connects to the Server. The TimesTen Data Manager must be installed on the Server host.

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

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

Creating and configuring a logical server name

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:

   
   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.

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 "Data source names".

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

   
   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.

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

8. In the Server DSN field, enter the Server DSN corresponding to the data store 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.

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 data stores that have active standby pair replication schemes. This enables the client to fail over automatically to the server on which the standby data store resides.

See "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 Daemon 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".

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

   • 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

For a description of the Timeout, UID and PWD attributes, see "Data Store 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.

Deleting a 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.

Accessing a remote data store 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 name of the server is ttserver_logical.

1. On the server machine server.mycompany.com, use the ttStatus utility to verify that the TimesTen Server Daemon 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" 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 data stores:

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.

   
   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 Daemon 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 Daemon 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 TimesTen 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.

Searching for a DSN

When TimesTen looks for a specific DSN, it looks in the following locations in this order:

1. The file referenced by the ODBCINI environment variable, if it is set.

2. The .odbc.ini file in the user's home directory, if the ODBCINI environment variable is not set.

3. The file referenced by the SYSODBCINI environment variable, if it is set

4. The sys.odbc.ini file in the daemon home directory, if the SYSODBCINI environment variable is not set.

Creating and configuring a logical server name

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:

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

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

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

[ShmHost_tt1121]
Description= Local TimesTen Server TimesTen release 11.2.1 through shared memory
Network_Address=ttShmHost
TCP_PORT=53385

Creating a Client DSN

In the ODBC Data Sources section of the ODBC.INI file, add an entry for the Client DSN. Each entry in this section lists the data source and the name of the ODBC driver that the data source uses. Use the following format for data source entries.

[ODBC Data Sources]
data-source-name=name-of-ODBC-driver

For example, to add the RunDataCS_tt1121_32 data source and associate it with the TimesTen Client ODBC driver, 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, add an entry to specify the connection attributes for each data source you have defined. Each data source listed in the ODBC Data Sources section of the ODBC.INI file requires a data source specification section.

The following is an example specification of the TimesTen Client example DSN RunData_tt1121_32.

[RunDataCS_tt1121_32]
TTC_Server=ttserver_logical
TTC_Server_DSN=RunData_tt1121_32

For a description of the Client DSN attributes used in the ODBC.INI file, see "Data Store Attributes" in the Oracle TimesTen In-Memory Database Reference.

Configuring automatic client failover

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

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

For example:

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

Testing connections

To test client application connections to TimesTen data stores:

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 Daemon is running on the server machine.

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

     telnet server.mycompany.com 53385
     

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

     Connected to server.mycompany.com
     

   • If the server machine responds to a command, but TimesTen Server Daemon does not, the TimesTen Server Daemon 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 Daemon is started at installation time. If the TimesTen Server Daemon is not running, you must start it. For information on starting the TimesTen Server, see "Modifying the TimesTen Server daemon options".

4. Verify that the client application can connect to the data store. If you cannot establish a connection to the data store, 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 data store has been defined properly in the system ODBC.INI file on the machine where the data store resides and where the TimesTen Server Daemon is running.

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.

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