1 Overview of the Installation Process in TimesTen Classic

This chapter provides an overview of the topics you should be familiar with prior to installing TimesTen Classic. For information on TimesTen Scaleout, see "Prerequisites and Installation of TimesTen Scaleout" in the Oracle TimesTen In-Memory Database Scaleout User's Guide.

Topics include:

Overview of installations and instances

This section discusses these topics:

Note:

TimesTen release numbers are reflected in items such as TimesTen utility output, file names, and directory names. These change with every minor or patch release, and the documentation cannot always be up to date. The documentation seeks primarily to show the basic form of output, file names, directory names, and other code that may include release numbers. You can confirm the current release number by reviewing the Release Notes or by running the ttVersion utility.

Distribution media and the distribution

The TimesTen product is packaged into distribution media that you download. For each supported platform, TimesTen is packaged into one distribution. A distribution consists of a single ZIP file.

The distribution differs depending on the platform:

  • On a Linux/UNIX 64-bit host: The distribution file name indicates the release number, the type of distribution, and the platform. For example, for release 18.1.3.1.0 on a Linux 64-bit host, the distribution file name is timesten181310.server.linux8664.zip. Use this file for installing either the full product or for installing just the client.

  • On a Linux 32-bit host:

    • The distribution file name indicates the release number, the type of distribution, and the platform. For example, for release 18.1.3.1.0, the distribution file name is timesten.181310.client.linux86.zip.

    • There is one distribution that contains the TimesTen client. Only the TimesTen client is supported on a Linux 32-bit host.

  • On a macOS host:

    • The distribution file name indicates the release number, the type of distribution, and the platform. For example, for release 18.1.3.1.0, the distribution file name is timesten.181310.client.macos64.zip.

    • There is one distribution that contains the TimesTen client. Only the TimesTen client is supported on a macOS host.

  • On a Windows host:

    • The distribution file name indicates the release number and platform. For example, timesten181310.win64.zip.

    • There is one distribution that contains the TimesTen client. Only the TimesTen client is supported on Windows.

Instance administrator

On a Linux, UNIX or macOS host, the instance administrator is the operating system user who extracts the distribution. When the instance administrator extracts the distribution, a TimesTen installation is created. See "TimesTen installations" for information on TimesTen installations. The instance administrator also plays a role in instances. See "TimesTen instances" for information.

On a Windows host, the instance administrator is the operating system user who extracts the distribution and runs the installer.

Note that the instance administrator:

  • Cannot be the root user

  • Has the operating system permissions to read all files and to execute all executable files in the installation

  • Must be a member of the TimesTen users group. (See "Understanding the TimesTen users group" for information.)

TimesTen installations

An installation is the set of files installed on the host from the distribution. The installation directory is the directory under which the installation is created.

The instance administrator is the only user who can delete the installation.

Notes:

  • Installations are read-only. Do not add, alter, or remove files or directories within the installation.

  • TimesTen does not maintain any inventory of installations.

  • File path names containing multibyte characters are not supported.

These sections provide additional information:

Installations on Linux or UNIX

For installations on a Linux/UNIX 64-bit host:

  • On a Linux host, a full installation or a client installation is supported for TimesTen Scaleout and for TimesTen Classic.

  • On a UNIX host, a full installation or a client installation is supported for TimesTen Classic only.

  • Multiple instances may share a single installation.

See "Creating an installation on Linux/UNIX" for information.

For installations on a Linux 32-bit host: A client-only installation is supported. The TimesTen client can connect to a database in either TimesTen Scaleout or in TimesTen Classic. See "Creating a TimesTen client installation" for information.

Installations on macOS

A client-only installation is supported on a macOS host. The TimesTen client can connect to a database in either TimesTen Scaleout or in TimesTen Classic.

See "Creating a TimesTen client installation" for information.

Installations on Windows

On Windows, after you extract the ZIP file, the instance administrator must run the setup.exe installer from the WIN64 subdirectory. This process creates a single installation and a single instance. No additional instances can be created.

The TimesTen client can connect to databases in either TimesTen Scaleout or in TimesTen Classic running on a separate Linux or UNIX server.

See "Creating an installation on Windows" for information.

TimesTen instances

An instance refers to either:

  • A running TimesTen daemon (timestend) and its children and associated processes, along with the configuration files and other supporting files required for its operation (full instance)

  • A set of configuration files and other supporting files required for the use of TimesTen clients (client-only instance)

Each instance has an instance home. This is the top level of the directory structure associated with the instance and represented in this document as timesten_home. See "Instance home" for information. A full instance can manage one or more databases. A client instance cannot have a database itself. Multiple instances can run from a single installation. TimesTen does not maintain an inventory of instances on a host and does not maintain an inventory of all instances associated with a particular installation.

On a Windows host, there is one instance in an installation that is created automatically during installation. The instance name is instance.

The role of the instance administrator for instances is as follows:

  • The instance administrator for a full instance creates and manages databases, loads databases into memory and from memory, modifies and destroys the instance, performs all management activities, and performs backup and restore operations.

  • The instance administrator for a client instance creates, modifies and destroys the instance.

  • On a Linux, UNIX, or macOS host:

    • The instance administrator is also the only user who can create the instance (by running the ttInstanceCreate utility) and is the instance administrator for all instances created from this installation. See "TimesTen instances" for information on TimesTen instances.

    • You cannot change the instance administrator after that administrator creates the installation or the instance.

    • The ttInstanceCreate utility enforces that the instance administrator cannot create the instance within the TimesTen installation tree. See "The ttInstanceCreate utility" for information on the ttInstanceCreate utility.

  • On a Windows host:

    • The instance administrator is the operating system user who extracts the distribution and runs the installer. There is no ttInstanceCreate utility on Windows. This instance administrator is the instance administrator for the instance.

    • The one installation and the single instance must have the same owner (the instance administrator).

    • An instance has a single instance administrator, who is the user who created the instance.

    • You cannot change the instance administrator after that administrator runs the installer.

Instance home

On a Linux, UNIX, or macOS host: The instance home is a directory that is created when the instance administrator runs the ttInstanceCreate utility.

On a Windows host: The instance home is a directory that is created as a result of the instance administrator running the installer.

This directory is owned by the instance administrator.

The instance home contains all the files that are configured specifically for the instance. It is indicated by timesten_home in the TimesTen documentation.

There are two types of instance home directories.

Either:

  • Full instance home: Supports the full use of TimesTen, including the server and direct mode. It must be a local directory to the host on which the instance runs.

  • Client-only instance home: Provides the files required to run TimesTen clients and is created when TimesTen is configured for client-only use. It must be a local directory to the host on which the instance runs.

On a Linux, UNIX, or macOS host: Users of a particular TimesTen instance must set their environment by sourcing ttenv.sh or ttenv.csh (where which you use depends on your shell) provided in each instance. See "Environment variables" for more information.

On a Windows host: You can either register the environment variables during the installation process for a persistent setting or you can execute the ttenv.bat file. See "Create an installation on Windows" and "Environment variables" for details.

Notes:

  • A single instance home cannot be shared by more than one instance.

  • The instance home includes symbolic links to the associated installation.

Instance configuration file (timesten.conf)

The instance configuration file defines the attributes of the TimesTen instance. It resides in the timesten_home/conf directory and is named timesten.conf. The file is an ASCII text file, consisting of name=value pairs, one pair per line.

Here is a sample configuration file for a full instance. Comments are indicated by "#".

# TimesTen Instance Configuration File
# Created by ttInstanceCreate
hostname=host1
timesten_release=18.1
instance_name=instance1
daemon_port=6624
server_port=6625
tns_admin=
admin_user=myadmin
admin_uid=12345
group_name=ttgroup
instance_guid=39734D8C-E59A-4164-A77D-FC4327FF9496
verbose=1

Some of these values are known or provided by TimesTen, others are according to your choices or specifications during installation or instance creation or modification.

For complete information about this file, see "TimesTen Instance Configuration File" in the Oracle TimesTen In-Memory Database Reference.

Understanding the TimesTen users group

On a Linux, UNIX, or macOS host:

  • TimesTen restricts access to the installation and the instances created from that installation to members of a single operating system group. This group, called the TimesTen users group, owns the installation and the instances created from the installation. The TimesTen users group must be the primary group for the instance administrator. Create this group (for example, timesten) and add the desired operating system users prior to installation. Once you create the TimesTen users group, you cannot change the name of the group or the group ID.

  • Users who wish to access databases through TimesTen utilities or direct mode applications must be members of the TimesTen users group. This group can be the user's primary or secondary group.

  • Users who connect to a database through a client connection do not have to be members of the TimesTen users group.

On a Windows host:

  • TimesTen is installed by the instance administrator. This instance administrator must be a member of the TimesTen users group.

  • Information about the TimesTen installation is contained in the Windows operating system registry.

Installation and instance management on Linux, UNIX or macOS

These topics provide an overview of installation and instance management on a Linux, UNIX or macOS host:

Installation management:

Instance management

Installation creation on Linux, UNIX, or macOS

The instance administrator creates the installation by extracting the distribution. See "Distribution media and the distribution" for information on the distribution. For a Linux/UNIX 64-bit host, see "Creating an installation on Linux/UNIX" for information. For a macOS or a Linux 32-bit host, see "Creating a TimesTen client installation" for information.

The instance administrator can run the ttInstallationCheck utility after installation to verify the installation has the expected contents and permissions. For a Linux/UNIX 64-bit host, see "Verify an installation on Linux/UNIX" for more information. For a macOS or a Linux 32-bit host, see "Verify a client installation" for information.

Installation deletion on Linux, UNIX, or macOS

The instance administrator who created the installation is the only user who can delete the installation. Deleting the installation involves manually deleting the installation tree (the files and the directories within the installation).

For a Linux/UNIX 64-bit host, see "Deleting an installation on Linux/UNIX" for information.

For a macOS or a Linux 32-bit host, see "Deleting a TimesTen client installation" for information.

Installation copying on Linux or UNIX

Since installations are read only and immutable, you can pack the installation (using a tool like ZIP), copy it to another host, and unpack it. As long as the file permissions are maintained and the files are copied, the copied installation is valid. You can use the ttInstallationCheck utility to verify the installation. See "Copying an installation on Linux/UNIX" for information.

Instance creation on Linux, UNIX, or macOS

The instance administrator who created the installation (by extracting the distribution) is the only user who can create the instance. The instance administrator creates the instance by running the ttInstanceCreate utility located in the /bin area of the installation directory tree (installation_dir/tt18.1.3.1.0/bin).

The instance administrator creates a client-only instance by running ttInstanceCreate with the -clientonly option. (On a macOS or a Linux 32-bit host, the -clientonly option is not required.) See "TimesTen instances" for information on TimesTen instances.

The ttInstanceCreate utility creates the instance, creates the instance home directory, sets the permissions on the instance home directory, and populates the directory with the appropriate files. See "Instance home" for information on the instance home directory.

For a Linux/UNIX 64-bit host, see "Creating an instance on Linux/UNIX: Basics" for more information on the ttInstanceCreate utility and the procedure for creating an instance.

For a macOS or a Linux 32-bit host, see "Creating a TimesTen client instance" for information.

Instance modification on Linux, UNIX, or macOS

The instance administrator who created the installation and the instance is the only user who can modify the instance. The instance administrator modifies the instance by running the ttInstanceModify utility located in the /bin area of the timesten_home directory. See "Instance home" for information on this directory.

The instance administrator can run the ttInstanceModify utility either interactively or by specifying a supported option. For a Linux/UNIX 64-bit host, see "Modifying an instance on Linux/UNIX" for information on the ttInstanceModify utility and the procedure for modifying an instance. For a macOS or a Linux 32-bit host, see "Modifying a TimesTen client instance" for information.

The instance administrator can also change the attributes of the instance by modifying the instance configuration file. See "Instance configuration file (timesten.conf)" for information on this file. Also see "TimesTen Instance Configuration File" in the Oracle TimesTen In-Memory Database Reference.

Instance patching on Linux, UNIX, or macOS

Instance patching involves either upgrading or downgrading the instance. An instance can be upgraded from one patch release of TimesTen to a later patch release. Instances can also be downgraded from one patch release to an earlier one. Upgrades and downgrades are only possible within a single major release (for example, from 18.1.w.x.0 to 18.1.y.z.0, but not from 11.2.2.x.y to 18.1.a.b.0).

The instance administrator who created the installation and the instance is the only user who can upgrade or downgrade the instance. The instance administrator upgrades or downgrades the instance by running the ttInstanceModify utility located in the /bin area of the timesten_home directory. See "Instance home" for information on this directory.

The procedure for upgrading or downgrading the instance involves associating the instance with a different installation. The instance administrator runs the ttInstanceModify utility with the -install option to accomplish this.

For a Linux/UNIX 64-bit host, see "Modifying an instance on Linux/UNIX" for information on the ttInstanceModify utility and see "Associate an instance with a different installation (upgrade or downgrade)" for the procedure to associate an instance with a different installation.

For a macOS or a Linux 32-bit host, see "Modifying a TimesTen client instance" for information.

Instance removal on Linux, UNIX, or macOS

The instance administrator who created the installation and the instance is the only user who can remove (destroy) the instance. The instance administrator destroys the instance by running the ttInstanceDestroy utility located in the /bin area of the installation directory tree (installation_dir/tt18.1.3.1.0/bin).

The instance to be destroyed is determined by the setting of the TIMESTEN_HOME environment variable. See "Environment variables" for information on this environment variable and how to set it.

For a Linux/UNIX 64-bit host, see "Destroying an instance on Linux/UNIX" for information on the ttInstanceDestroy utility and the procedure for destroying an instance.

For a macOS or Linux 32-bit host, see "Destroying a TimesTen client instance" for information.

Installation and instance management on Windows

These topics provide an overview of installation and instance management on Windows:

Installation and instance management:

Installation and instance creation on Windows

The instance administrator extracts the distribution and then runs the TimesTen installer to create the installation and the instance. See "Distribution media and the distribution" for information on the distribution.

The TimesTen installer creates a single TimesTen client-only installation (and instance). No additional installations (or instances) can be created without first uninstalling the existing one. Thus, there can be only one single 18.1 installation at a time. See "Overview of the installation process on Windows" for details of the installation process.

Installation patching on Windows

A Windows host does not support multiple installations from the same TimesTen major release, such as 18.1. For example, the host cannot have both an 18.1.1.x.0 installation and an 18.1.2.x.0 installation.

If there is an 18.1 release of Windows installed and you wish to install a different patch release of 18.1:

  • The instance administrator runs the installer to install the new release.

  • The installer asks if the previous installation can be overwritten with the new one.

    If the instance administrator answers yes, the one provided instance can make use of the new installation.

Installation and instance deletion on Windows

The instance administrator deletes the installation by using the Control Panel or System Settings (depending on your version of Windows). Deleting the installation also deletes the instance. See "Deleting an installation on Windows" for information on the procedure for deleting an installation. Also see "Verify the uninstallation is successful on Windows" for the procedure to verify the success of the uninstallation.

Operating system prerequisites

Ensure you review (and perform) these operating system prerequisites before you install TimesTen Classic.

Linux prerequisites

Perform these prerequisites on Linux:

On SUSE Linux Enterprise Server, you need to install libncurses5. To do this, run:

zypper -n install libncurses

Create the TimesTen users group

This section summarizes the steps for creating the TimesTen users group:

  • Create a TimesTen users group and add desired users.

  • Determine the operating system user that will be the instance administrator. That user must be a member of the TimesTen users group. This user creates the installation.

    Note:

    Do not create a TimesTen installation as an operating system user whose name matches any of the TimesTen predefined internal users: GRID, PUBLIC, SYS, SYSTEM, or TTREP.

As an example, instanceadmin is the name of the operating system user and timesten is the name of the TimesTen users group.

  1. Create the TimesTen users group. Name the group timesten with group ID 10000. This information is needed when configuring HugePages. See "Configure HugePages" for more information.

    % sudo groupadd -g 10000 timesten
    
  2. Create the instanceadmin user with UID 55000 and assign this user to the timesten primary group. Then, create a password for the instanceadmin user.

    % sudo useradd -u 55000 -g timesten instanceadmin
    % sudo passwd instanceadmin
    

Configure shmmax and shmall

You must configure Linux shared memory so that the maximum size of a shared memory segment (the shmmax memory kernel parameter) is large enough to contain the size of the total shared memory segment for the database. In TimesTen Classic, the entire database resides in a single shared memory segment. There is also a second memory segment used for PL/SQL.

On Linux, a shared memory segment consists of pages, where the default page size is normally 4 KB (4096 bytes). You can verify the default page size by running the getconf PAGESIZE command:

% getconf PAGESIZE
4096

Configure these shared memory kernel parameters to control the size of the shared memory segment:

  • shmmax: The maximum size of a single shared memory segment expressed in bytes. The value must be large enough to accommodate the size of the total shared memory segment for the database.

  • shmall: The total size of all shared memory segments system wide. The value is expressed in multiples of the page size (4 KB) and must be greater or equal to the value of shmmax. It is recommended that you set the value of shmall to less than or equal to the total amount of physical RAM. To display the total amount of physical memory, run the Linux cat /proc/meminfo command.

The size of the database is based on the values of the PermSize, TempSize, LogBufMB and Connections connection attributes (The 1 value is TimesTen system overhead).

The sizing formula (in 18.1.3.1.0 and subject to change in future releases) is:

PermSize+TempSize+LogBufMB+1+(0.042 * Connections)

The PermSize, TempSize, and LogBufMB values are expressed in MB (megabytes).

The PermSize, TempSize, LogBufMB, and Connections are connection attributes that you define in your sys.odbc.ini or odbc.ini file.

If you do not define values for these attributes, TimesTen uses the default values. See "PermSize," "TempSize," and "LogBufMB" in the Oracle TimesTen In-Memory Database Reference for details on each connection attribute.

As an example, assume the database has a PermSize value of 32GB (32768 MB), a TempSize value of 4 GB (4096 MB), a LogBufMB value of 1 GB (1024 MB) and a Connections value of 2048. Applying the sizing formula, the size of the database is:

37975 MB (=32768 MB + 4096 MB + 1024 MB +1 + (0.042 MB *2048))

In this example, to size shmmax and shmall:

  1. As the root user, edit the /etc/sysctl.conf file, modifying kernel.shmmax and kernel.shmall. Assuming the size of the database is 37,975 MB and the shmmax and shmall values must be greater than this size, for this example, set shmmax to 48 GB (= 51,539,607,552 bytes) and shmall to 56GB (= 60129542144 bytes= 58,720,256 KB/4 KB page size= 14,680,064 KB pages).

    # sudo vi /etc/sysctl.conf
    ...
    ...
    kernel.shmmax=51539607552
    kernel.shmall=14680064
    
  2. To reload the settings from the modified /etc/sysctl.conf file:

    # sudo /sbin/sysctl -p
    
  3. Run the Linux ipcs lm command to display the current shmmax and shmall settings. The max seg size (kbytes) is the shmmax value and the max total shared memory (kbytes) is the shmall value. The shmmax value expressed in kbytes is 50331658 (= 51,539,607,552 bytes) and the shmall value expressed in kbytes is 58720256 (= 60129542144 bytes).

    % ipcs -lm
     
    ------ Shared Memory Limits --------
    max number of segments = 4096
    max seg size (kbytes) = 50331648
    max total shared memory (kbytes) = 58720256
    min seg size (bytes) = 1
    

Notes:

  • The settings for shmmax and shmall in these examples can be increased if there are other applications that require them to be greater.

  • If you are unsure of the size of your database, you can set shmmax and shmall to correspond to a percentage of the size of physical memory (such as 80%).

Configure HugePages

You can configure HugePages for more efficient memory management.

If the shared memory segment for the database is greater than 256 GB, you must configure HugePages.

Once configured, the memory allocated for HugePages is taken from the total RAM on the Linux host and is not available for any other use. In addition, the HugePages memory segment is automatically locked and cannot be swapped to disk.

To configure HugePages, you need to know:

  • The maximum size of the shared memory segment for the database

  • The HugePages page size on your Linux host

  • The group ID of the instance administrator

Using the examples in the "Configure shmmax and shmall" section, where the database size is 37,975 MB and the shmmax value is 48 GB and the "Create the TimesTen users group" section, where the group ID of the instanceadmin user is 10000:

  • The size of the total shared memory segment is 48 GB.

  • The HugePages page size is 2048 KB. (This value is fixed for each platform and is not configurable.)

    To determine the HugePages page size, run the Linux cat /proc/meminfo|grep Hugepagesize command:

    % cat /proc/meminfo | grep Hugepagesize
    Hugepagesize:       2048 kB
    
  • The group ID is 10000.

    To determine the group ID of the instance administrator, log in as the instanceadmin user, and run the Linux id command:

    % id
    uid=55000(instanceadmin) gid=10000(g10000)groups=10000(g10000)
    

To configure HugePages:

  1. Determine the number of HugePages by dividing the size of the total shared memory segment (expressed in MB) by the value of Hugepagesize (expressed in MB). In this example, the total shared memory segment is 48 GB (=49152 MB) and the Hugepagesize value is 2048 KB (= 2 MB):

    49152 MB/ 2 MB = 24576 
    
  2. As the root user, edit the /etc/sysctl.conf file, and set vm.nr_hugepages to the number of HugePages (24576 in the example) and set vm.hugetlb_shm_group to the group ID of the instance administrator (10000 in the example). The latter setting restricts access to HugePages to members of the group.

    # sudo vi /etc/sysctl.conf
    ...
    ...
    vm.nr_hugepages=24576
    vm.hugetlb_shm_group=10000
    
  3. Reload the settings from the modified /etc/sysctl.conf file:

    # sudo /sbin/sysctl -p
    
  4. To verify that you have configured HugePages correctly, run the Linux cat/proc/meminfo|grep HugePages command and verify the value for HugePages_Total is 24576 and the value for HugePages_Free is 24576.

    % cat /proc/meminfo|grep HugePages
    HugePages_Total:   24576
    HugePages_Free:    24576
    ...
    

Notes:

  • Because HugePages must be allocated in contiguous available memory space, the requested allocation may not be granted, or may be only partially granted, until after the host is restarted. Check the HugePages_Total and HugePages_Free values from /proc/meminfo. Restarting grants the full allocation, assuming enough memory is available in the host.

  • If a database less than or equal to 256 GB does not fit into the available HugePages space, regular pages are used. If a database greater than 256 GB does not fit into the HugePages space, the database cannot be loaded into memory.

  • The TimesTen PL/SQL shared memory segment consumes some of the configured HugePages allocation, determined by the value of the PLSQL_MEMORY_SIZE connection attribute. See "PLSQL_MEMORY_SIZE" in the Oracle TimesTen In-Memory Database Reference for more information.

  • The HugePages segment is automatically locked such that the memory segment is not a candidate to be swapped to disk. Therefore, if you configure HugePages, you do not need to set the MemoryLock connection attribute.

Modify the memlock settings

The memlock entries in the /etc/security/limits.conf file control the amount of memory a user can lock. These entries are set at the system level and are different than the MemoryLock connection attribute setting.

If HugePages are configured, the memlock values must be large enough to accommodate the size of the shared memory segment or the database will not be loaded into memory.

For example, for the instanceadmin user, assuming a total shared memory segment size of 48 GB (=49152 MB), set the memlock entries to 50331648 KB (49152*1024):

  1. As the root user, edit the /etc/security/limits.conf file, and set the memlock entries to 50331648 KB for the instanceadmin user. This value indicates the total amount of memory the instanceadmin user can lock.

    # sudo vi /etc/security/limits.conf
    ...
    ...
    instanceadmin soft   memlock 50331648
    instanceadmin hard   memlock 50331648
    
  2. As the instanceadmin user, log out and log in again for the changes to take effect.

Set the semaphore values

TimesTen has an upper bound on the maximum number of connections to the database. The database connections consist of:

  • User connections: established by user applications

  • System connections: established internally by TimesTen (set at 48 connections)

  • Other required connections (set at 107 connections)

Each of these connections is assigned one semaphore, such that the total semaphores for a database are:

Total semaphores = user connections (N) + system connections (48) + 
                   other required connections (107)

Total semaphores = N + 155

The semaphore settings are located in the kernel.sem configuration directive in /etc/sysctl.conf:

kernel.sem = SEMMSL SEMMNS SEMOPM SEMMNI

where:

  • SEMMSL is the maximum number of semaphores per array. This value is related to the maximum number of connections and is the most significant parameter for this discussion. Configure this value to 155 plus the number of user connections.

  • SEMMNS is the maximum number of semaphores system wide. Use the formula SEMMNS = (SEMMNI * SEMMSL) as a guideline. However, in practice, SEMMNS can be much less than SEMMNI * SEMMSL.

  • SEMOPM is the maximum number of operations for each semop call.

  • SEMMNI is the maximum number of arrays.

Follow these steps to configure the SEMMSL and SEMMNS settings (Ensure that the user is root):

  1. View the existing kernel parameter settings:

    # /sbin/sysctl -a | grep kernel.sem
    kernel.sem = 2500 320000 1000 1280
    
  2. Edit the /etc/sysctl.conf file, changing semmsl (the first value in kernel.sem) to 155 plus the number of connections.

    In this example, to support up to 3845 connections (opened at the same time), set the semmsl value to 4000 (=155 + 3845).

    In this example, the remaining parameters have been increased. Consult your kernel documentation for details.

    # sudo vi /etc/sysctl.conf
    ...
    ...
    kernel.sem = 4000 400000 2000 2560
    
  3. Reload the settings from the modified /etc/sysctl.conf file:

    # sudo /sbin/sysctl -p
    

Note:

If you are using replication, the Linux platform for each host on which the master databases reside must have the same kernel settings for shared memory and semaphores. Specifically, SEMMSL must be identical on all hosts that participate in an active standby replication scheme before the duplication is performed.

AIX prerequisites

On UNIX, large pages is the only consideration. Semaphores are configured dynamically by the kernel.

On UNIX hosts with the required patch levels, TimesTen Classic can use large pages. Using large pages locks the shared segment into memory so it cannot be paged. Users must have the CAP_BYPASS_RAC_VMM and CAP_PROPAGATE capabilities. The capabilities are granted by a root user by editing the /etc/security/user file or for locally authenticated users with:

# chuser capabilities=CAP_BYPASS_RAC_VMM,CAP_PROPAGATE user_id

The system default is to not have any memory allocated to the large page physical memory pool. Use the vmo command to configure the size of the large page physical memory pool. This example allocates 4 GB to the large page physical memory pool:

# vmo -r -o lgpg_regions=256 -o lgpg_size=16777216

Note:

There is some benefit in using vmo to set vmm_mpsize_support to a value of 3 (if available) or 2 to optimize memory page usage.

Solaris prerequisites

Before installation, use information in the sections that follow to improve the performance of TimesTen Classic on your system.

File system options (Solaris)

On a Solaris UFS file host, mount the file system with the -forcedirectio option if you plan to have applications that use DurableCommits=1.

Create a project (Solaris)

Create a project to manage system resources, such as shared memory, file descriptors and semaphores.

You can create a group project or a user project.

Note:

If you create a users group, the instance administrator must run the newtask command each time the TimesTen daemons must be restarted. If the TimesTen daemons start at system start time, add the newtask command to the system startup scripts.

For example, to create a project timestenproj for the group timesten (the TimesTen users group) with 500 GB of shared memory, 4096 semaphores and 65,535 file descriptors:

  1. Log in as user root.

  2. Add the group project.

    # projadd -G timesten timestenproj
    
  3. Modify the shared memory for the group to 500 GB.

    # projmod -a -K "project.max-shm-memory=(priv,500GB,deny)" timestenproj
    
  4. Modify the maximum number of semaphores to 4096.

    # projmod -a -K "process.max-sem-nsems=(priv,4096,deny)" timestenproj
    

    Note:

    For each active database, TimesTen Classic consumes a minimum of 155 SEMMSL plus one SEMMSL for each connection.
  5. Modify the maximum number of file descriptors to 65,535.

    # projmod -a -K "process.max-file-descriptor=(priv,65535,deny)" timestenproj
    
  6. Run the newtask command before restarting the TimesTen daemons.

    # newtask -p timestenproj -c $$
    

Or, for example, to create a user project for the user timestenuser, with 500 GB of shared memory, 4096 semaphores and 65,535 file descriptors:

  1. Log in as user root.

  2. Add the user project.

    # projadd -U timestenproj user.timestenuser
    
  3. Modify the shared memory for the group to 500 GB.

    # projmod -a -K "project.max-shm-memory=(priv,500GB,deny)" user.timestenuser
    
  4. Modify the maximum number of semaphores to 4096.

    # projmod -a -K "process.max-sem-nsems=(priv,4096,deny)" user.timestenuser
    

    Note:

    For each active database, TimesTen Classic consumes 155 SEMMSL, plus one SEMMSL for each connection.
  5. Modify the maximum number of file descriptors to 65,535.

    # projmod -a -K "process.max-file-descriptor=(priv,65535,deny)" user.timestenuser
    

Every user and every group are associated to a default project, which is the project under which their processes are run. The project or process settings used by a user are those that occur first in the /etc/project file. If you have not modified the project file, the system default project settings occur first.

Note:

Do not remove the default project settings from the project file. Instead, place project settings at the top of the project file above the default settings.

For either the user project method or group project method, you can choose between these two options for associating your project settings with the specified user or group:

  • Edit the /etc/project file to move the timestenproj project entry so that it precedes the default entry.

  • Execute the following before restarting daemons. This is required if the project was created with -G only.

    # newtask -p timestenproj -c $$
    

Note:

On a Solaris host, use MemoryLock with a setting of 3 or 4. A MemoryLock setting of 1 or 2 requires TimesTen to have been installed as root, which is not advisable.

Planning the installation and its deployment

This section is applicable for full installations and full instances. Client-only installations and instances are irrelevant. For planning purposes, consider the information in these sections:

Locations of database files and user files

These are the TimesTen requirements and recommendations regarding locations of databases and other user files:

  • Storing database files (checkpoint and log files) or any other user files anywhere under the TimesTen installation path is not supported. The installation is immutable—do not add, change, or remove anything.

  • It is strongly advised to not store database files or other user files under the instance home. Anything in or under the instance home will be removed if the instance is destroyed.

  • For performance reasons, it is advisable to store TimesTen checkpoint files (the DataStore location in the database definition) on a different device from TimesTen transaction log files (the LogDir location).

Once you have a TimesTen installation, you can estimate the size of your database and the disk space required. Refer to "Ensuring sufficient disk space" in Oracle TimesTen In-Memory Database Operations Guide.

Locations of the databases and the applications

Consider:

  • Unless there are concerns about resource contention between your application and TimesTen Classic, it is best to have your application on the same host as the databases in TimesTen Classic. This allows the application to use direct connections, which offer much better response time and throughput than client/server connections, due primarily to avoidance of network round trips.

  • To use TimesTen Cache, it is best to have the TimesTen Classic and Oracle databases on different hosts, to avoid resource contention between them.

Note:

These are general guidelines only, not necessarily suitable for every particular situation.

Environment variables

These sections discuss environment variables and are specific to TimesTen Classic. For specifics on environment variables in TimesTen Scaleout, see "Environment variables" in the Oracle TimesTen In-Memory Database Scaleout User's Guide.

Setting environment variables for TimesTen

You set environment variables for a terminal window, which enables the window to run commands for a particular instance. Here is a list of situations where you should set your environment variables:

  • After you create the instance

  • Before using any TimesTen utility

  • Before executing a direct mode application on a host running an instance

  • Before executing a client server application on a host running a client

On a Linux, UNIX, or macOS host, you set the environment variables by sourcing ttenv.sh or ttenv.csh (where which you use depends on your shell). On a Windows host, you set the environment variables by running the ttenv.bat batch file. TimesTen creates the scripts after you create an instance.

In TimesTen Classic, these scripts are located in the /bin directory of the instance home.

After sourcing these scripts, the environment variables required to use an instance are set.

The environment variables include TIMESTEN_HOME, PATH, LD_LIBRARY_PATH (or equivalent) and TNS_ADMIN.

For example:

For a Bourne-type shell, such as sh, bash, zsh, or ksh:

% cd timesten_home/bin
% . ttenv.sh

For a csh or tcsh shell:

% cd timesten_home/bin
% source ttenv.csh

Once the TIMESTEN_HOME variable is set so that the instance home is known, TimesTen makes additional settings, such as the daemon port, according to the timesten_home/conf/timesten.conf instance configuration file. See "Instance configuration file (timesten.conf)" for information on the instance configuration file.

Note:

The output after sourcing indicates the path and the TIMESTEN_HOME settings, but may not indicate all settings.

Alternatively, you can use ttenv in command-line mode to fork a new shell, to set the environment, and to execute the specified command. For example, to execute ttIsql to connect to database1:

% cd timesten_home/bin
% ./ttenv ttIsql database1

Environment variables are set inside your ttIsql session and the ttIsql prompt displays. When you exit ttIsql, your shell will have its original environment variable settings.

On Windows, execute the ttenv.bat batch file from a DOS window, which changes the environment for your DOS session. For example:

C:\TimesTen\tt181_64\instance\bin>ttenv

Notes:

  • On Windows, the instance home, path, classpath, library path, and path are set persistently during installation if "Register environment variables" is enabled, which is the case by default. These settings are reflected in the System control panel and persist between sessions. It is not necessary to run ttenv.bat.

  • The ttenv command-line mode does not apply to Windows.

Environment variable descriptions

These sections provide more details on the environment variables:

TIMESTEN_HOME environment variable

The TIMESTEN_HOME environment variable specifies the home directory of the instance. You explicitly set this variable when sourcing either ttenv.sh or ttenv.csh (where which you use depends on your shell).

On Windows, the TIMESTEN_HOME environment variable is set persistently if you register the environment variables during installation (the default), or is set for your session if you execute ttenv.bat.

NLS_LANG environment variable

This environment variable is relevant for OCI, Pro*C/C++, and ODP.NET. It is ignored for ODBC and JDBC. The character set specified in the sys.odbc.ini or user odbc.ini is used by default for the connection, if not overridden by NLS_LANG. While setting the character set explicitly is recommended, the default is normally AMERICAN_AMERICA.US7ASCII. To use the environment variable to set the character set, do the following:

NLS_LANG=.WE8ISO8859P1

On Windows, the NLS_LANG setting is searched for in the registry, HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\NLS_LANG, if it is not in the environment. If your program has trouble connecting to the database, confirm the NLS_LANG setting is valid and that it indicates a character set supported by TimesTen.

For more information, see:

Shared library path environment variable

The shared library path environment variable is set when sourcing ttenv.sh or ttenv.csh (where which you use depends on your shell). This environment variable specifies the path for shared libraries.

The shared library path environment variable is set as follows:

  • On Linux, ttenv.sh or ttenv.csh (where which you use depends on your shell) adds $TIMESTEN_HOME/install/lib to LD_LIBRARY_PATH.

  • On UNIX, ttenv.sh or ttenv.csh (where which you use depends on your shell) adds $TIMESTEN_HOME/install/lib to LIBPATH.

  • On macOS, ttenv.sh or ttenv.csh (where which you use depends on your shell) adds $TIMESTEN_HOME/install/lib:$TIMESTEN_HOME/install/ttoracle_home/instantclient_11_2 to DYLD_LIBRARY_PATH.

  • On Windows, ttenv.sh (or ttenv.csh) adds tt181_64\lib to LIB (or the lib directory under the top level of the installation, if some other directory name was chosen).

  • On Solaris systems, timesten_home/install/lib in LD_LIBRARY_PATH or LD_LIBRARY_PATH_64, as appropriate.

PATH environment variable

TimesTen provides utilities for managing and debugging your applications. For these utilities to be available, the path for executables in $TIMESTEN_HOME/bin and $TIMESTEN_HOME/install/bin must be designated in the PATH setting. The path is updated to include these directories when you source ttenv.sh or ttenv.csh (where which you use depends on your shell).

In addition, to compile programs, be sure the location of the compiler for your programming language is in the PATH setting.

Temporary directory environment variable

The temporary directory environment variable specifies the location of the temporary directory. TimesTen uses this directory during recovery and other operations. The ttenv.sh or the ttenv.csh script does not set this environment variable. You must explicitly set it to avoid the operating system default.

  • On a Linux, UNIX, or macOS host, TMPDIR is the environment variable.

  • On a Windows host, TMP is the environment variable.

TNS_ADMIN environment variable

The TNS_ADMIN environment variable specifies the full path to the directory where the tnsnames.ora file is located.

  • For TimesTen OCI, Pro*C/C++, or ODP.NET, set the TNS_ADMIN environment variable to indicate the full path to the directory where the tnsnames.ora file is located.

  • For TimesTen Cache in TimesTen Classic, set the TNS_ADMIN environment variable to indicate the full path to the directory where the tnsnames.ora file is located. This is for access to Oracle Database data.

  • On a Linux or a UNIX host, also specify the -tnsadmin option for ttInstanceCreate or for ttInstanceModify to ensure that both TimesTen and user applications read the TNS_ADMIN setting.

Java environment variables

For Java applications, there are additional environment variables of interest. These sections provide information about additional environment variables or considerations that affect Java applications:

CLASSPATH environment variable

Java classes and class libraries are found in the class path, as specified by the CLASSPATH environment variable. Before executing a Java program that loads any of the TimesTen JDBC drivers, the CLASSPATH setting must include the class library file and path:

$TIMESTEN_HOME/install/lib/ttjdbcjdk_ver.jar

where jdk_ver indicates the JDK version. For JDK8, jdk_ver is 8 and the file name is ttjdbc8.jar.

Notes:

  • This variable is set for your session by sourcing ttenv.sh or ttenv.csh (where which you use depends on your shell) or, on Windows, is set persistently during installation if environment variables are registered (default).

  • If multiple JAR files are listed in the CLASSPATH, ensure the TimesTen JAR file is listed first.

To check the JDK version:

% java -version

To use the JMS/XLA interface, these entries must also be in your CLASSPATH:

timesten_home/install/lib/timestenjmsxla.jar
timesten_home/install/3rdparty/jms1.1/lib/jms.jar
timesten_home/install/lib/orai18n.jar

For example, the CLASSPATH would look like this example (replacing timesten_home/install as appropriate):

.:timesten_home/install/lib/ttjdbc7.jar:timesten_home/install
/lib/timestenjmsxla.jar:timesten_home/install/3rdparty/jms1.1/lib
/jms.jar:timesten_home/install/lib/orai18n.jar

By default, JMS/XLA looks for a configuration file called jmsxla.xml in the current working directory. To use another name or location for the file, specify it as part of the environment variable in the InitialContext class and add the location to the CLASSPATH setting. See "JMS/XLA configuration file and topics" in Oracle TimesTen In-Memory Database Java Developer's Guide for more information.

PATH environment variable settings for Java

For Java applications, ensure that the locations of the java and javac executables are in the PATH setting.

SYSODBCINI environment variable

On a Linux or UNIX host, system DSNs and their connection attributes are defined in the sys.odbc.ini file. The default location, $TIMESTEN_HOME/conf is usually sufficient.

To override the name and location of this file at runtime, set the SYSODBCINI environment variable to the path name of a sys.odbc.ini file before starting the TimesTen daemon. Any user can use a system data source.

TimesTen first looks for a DSN in the user odbc.ini file. If the DSN is not found in this file, TimesTen looks in the sys.odbc.ini file.

Use of this environment variable is discouraged. For more information, see "Overview of user and system DSNs" in the Oracle TimesTen In-Memory Database Operations Guide.

ODBCINI environment variable

On a Linux or UNIX host, applications can use the odbc.ini file to define DSNs and their connection attribute settings. By default, TimesTen first looks for the user odbc.ini file in the home directory of the user running the application. To override the name and location of this file at run-time, set the ODBCINI environment variable to indicate a desired path and file name before launching the application.

If TimesTen cannot locate a user DSN file, on a Linux or UNIX host, it looks for the sys.odbc.ini file in $TIMESTEN_HOME/conf.

Use of this environment variable is discouraged. For more information, see "Overview of user and system DSNs" in the Oracle TimesTen In-Memory Database Operations Guide.

SYSTTCONNECTINI environment variable

On a Linux, UNIX, or macOS host, client applications can use the sys.ttconnect.ini file to define logical server names. For a description of logical server names, see "Working with the TimesTen Client and Server" in Oracle TimesTen In-Memory Database Operations Guide.

The default location, $TIMESTEN_HOME/conf/sys.ttconnect.ini, is usually sufficient. To override the name and location of this file at runtime, set the SYSTTCONNECTINI environment variable appropriately before starting the TimesTen daemon.

On a Windows host, configure logical server names using the ODBC Data Source Administrator.

Use of this environment variable is discouraged.