1 Getting Started with TimesTen Classic

This chapter provides overview and instruction on 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 looking at the Release Notes or 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.

On Linux, the distribution file name indicates the release number, the type of distribution, and the platform. For example, for release 18.1.2.1.0, the distribution file name is timesten181210.server.linux8664.zip. Use this file for installing the full product or for installing just the client. There is not a separate client distribution file.

On Windows, the distribution file name indicates the release number and platform. For example, timesten181210.win64.zip.

For Linux and UNIX hosts: There is one distribution that contains the full product, including the client, server, direct mode, daemons, etc.

For Windows: There is one distribution that contains the TimesTen client.

Instance administrator: Installation

On Linux/UNIX, the first step in the installation process is to designate the operating system user who will extract the distribution. This operating system user is called the instance administrator. When the instance administrator extracts the distribution, the TimesTen installation is created. See "TimesTen installations" for information on TimesTen installations. The instance administrator also plays a role in instances. See "Instance administrator: Instance" for information.

On Windows, the instance administrator is the operating system user who extracts the distribution and runs the installer. See "Instance administrator: Instance" for more information on the role of the instance administrator after the instance administrator extracts the distribution.

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

  • Is a member of the TimesTen users group (See "Understanding the TimesTen users group" for information)

TimesTen installations

When the operating system user (who is designated as the instance administrator) extracts the TimesTen distribution (the ZIP file) on a host, an installation is created. Thus, 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 operating system user who unzips the distribution (thereby creating the installation) 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 and UNIX

For installations on Linux and UNIX hosts:

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

  • An installation may be shared across multiple hosts if it is installed on a shared file server, such as through NFS. See "Share an installation from a network-attached storage device" for information.

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

The instance administrator can run the ttInstallationCheck utility to verify the installation has the expected contents and permissions. See "Verify an installation on Linux/UNIX" for information.

Installations on Windows

On Windows, after you extract the ZIP file, the instance administrator runs 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

The second step in the installation process is creating an instance. Recall the first step is creating the installation. See "TimesTen installations" for details.

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

Additional information:

  • An instance has a single instance administrator, who is the user who created the instance. See "Instance administrator: Instance" for information.

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

  • An 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 Linux/UNIX:

  • The instance administrator is the only user that can run the ttInstanceCreate utility (the utility that creates the instance). See "Instance administrator: Instance" for information.

  • In most environments, one installation and one instance per host is sufficient, but multiple instances on the same host can use a single installation if desired. If the installation is on network-attached storage such as NFS, a single installation can support multiple instances on multiple hosts.

  • 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. See "Instance administrator: Instance" for information on the instance administrator.

On Windows: There is one instance in an installation that is created automatically during installation. The instance name is instance.

Instance administrator: Instance

On Linux/UNIX, recall that the operating system user who created the installation by extracting the distribution is called the instance administrator. (See "Instance administrator: Installation" for details.) This 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. See "TimesTen instances" for information on TimesTen instances.

On Windows, the instance administrator is the operating system user who extracts the distribution and runs the installer. (There is no ttInstanceCreate utility on Windows.)

The instance administrator for a full instance creates and manages databases, loads the database 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 modifies and destroys the instance. On Windows, only client instances are supported.

On Linux and UNIX hosts:

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

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

On Windows:

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

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

Instance home

On Linux/UNIX, the instance home is a directory that is created when the instance administrator runs the ttInstanceCreate utility.

On Windows, 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. See "Instance administrator: Instance" for information on 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.

On Linux/UNIX: Users of a particular TimesTen instance must set their environment using the ttenv scripts provided in each instance. See "Environment variables" for more information.

On Windows: 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 a symbolic link to the top-level directory of the associated installation.

Instance configuration file (timesten.conf)

The instance configuration file defines the attributes of the TimesTen daemon. 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. 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.

Installation and instance management on Linux/UNIX

These topics provide an overview of installation and instance management on Linux/UNIX:

Installation management:

Instance management

Installation creation on Linux/UNIX

The instance administrator creates the installation by extracting the distribution. See "Distribution media and the distribution" for information on the distribution and "Creating an installation on Linux/UNIX" for information on creating an installation on Linux/UNIX.

The instance administrator can run the ttInstallationCheck utility after installation to verify the installation has the expected contents and permissions. See "Verify an installation on Linux/UNIX" for more information.

Installation deletion on Linux/UNIX

The instance administrator who created the installation is the only user who can delete the installation. See "Instance administrator: Installation" for information on the instance administrator. Deleting the installation involves manually deleting the installation tree (the files and the directories within the installation). See "Deleting an installation on Linux/UNIX" for information.

Installation sharing on Linux/UNIX

Installations are read only and can be easily shared or cloned. You can:

  • Share an installation across multiple hosts: TimesTen can be installed on a shared Network Attached Storage (NAS), such as NFS or the equivalent. Instances can be created on multiple hosts and can make use of the single shared installation. See "Share an installation from a network-attached storage device" for information.

  • Push clones of an installation to multiple hosts: Since installations are 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 "Copy an installation to another host" for information.

Instance creation on Linux/UNIX

The instance administrator who created the installation (by extracting the distribution) is the only user who can create the instance. See "Instance administrator: Installation" for information on the instance administrator. 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.2.1.0/bin).

The instance administrator creates a client-only instance by running ttInstanceCreate with the -clientonly option. If the instance administrator runs ttInstanceCreate without specifying the -clientonly option, TimesTen creates a full instance. 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. See "Creating an instance on Linux/UNIX: Basics" for more information on the ttInstanceCreate utility and the procedure for creating an instance.

Instance modification on Linux/UNIX

The instance administrator who created the installation and the instance is the only user who can modify the instance. See "Instance administrator: Installation" for information on the instance administrator. 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. See "Modifying an instance on Linux/UNIX" for information on the ttInstanceModify utility and the procedure for modifying an instance.

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

Instance patching involved 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.x.y.0).

The instance administrator who created the installation and the instance is the only user who can upgrade or downgrade the instance. See "Instance administrator: Installation" for information on the instance administrator. 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.

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.

Instance removal on Linux/UNIX

The instance administrator who created the installation and the instance is the only user who can remove (destroy) the instance. See "Instance administrator: Installation" for information on the instance administrator. 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.2.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.

See "Destroying an instance on Linux/UNIX" for information on the ttInstanceDestroy utility and the procedure for destroying an instance.

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 process is:

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

Understanding the TimesTen users group

On Linux/UNIX:

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

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

Operating system prerequisites

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

Linux prerequisites

Perform these prerequisites on Linux:

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.

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

Planning the installation and its deployment

For planning purposes, this section discusses these considerations:

Locations of database files and user files

Be aware of these 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 allowed. 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 any particular situation.

Environment variables

These sections discuss environment variables:

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 Linux and UNIX, you set the environment variables by sourcing the ttenv shell script (ttenv.sh or ttenv.csh) or on Windows 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.

By 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 daemon port, according to the instance configuration file, timesten_home/conf/timesten.conf.

Note:

Output from ttenv indicates path and TIMESTEN_HOME settings but may not indicate all settings.

Alternatively, use ttenv in command-line mode to fork a new shell, set the environment there, and execute the specified command there. 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 you will be at the ttIsql prompt. Once you exit ttIsql, your shell will have its original environment variable settings.

For 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 in this case.

  • 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 the ttenv script.

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

NLS_LANG environment variable

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 indicates a character set supported by TimesTen. TimesTen uses the Oracle Instant Client to make these connections.

For more information, see:

Shared library path environment variable

The shared library path environment variable is set when sourcing ttenv. This environment variable specifies the path for shared libraries.

The shared library path environment variable must be set as follows:

  • On Linux, the ttenv script adds $TIMESTEN_HOME/install/lib to LD_LIBRARY_PATH.

  • On UNIX, the ttenv script adds $TIMESTEN_HOME/install/lib to LIBPATH.

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

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.

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

On Linux and UNIX hosts, the TMPDIR environment variable or on Windows the TMP environment variable, specifies the location of the temporary directory. TimesTen uses this directory during recovery and other operations. The ttenv script does not set this environment variable. You must explicitly set it if you do not want the operating system default.

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 (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 Linux and UNIX hosts, also set the -tnsadmin option for ttInstanceCreate or ttInstanceModify to ensure that TimesTen as well as user applications read the TNS_ADMIN setting.

  • The tnsnames and related information for additional entries, such as for Oracle database connections (as applicable), are brought in and distributed through the ttGridAdmin TNSNamesImport and SQLNetImport commands. See "Import TNS names (TNSNamesImport)" and "Import a sqlnet file (SQLNetImport)" in Oracle TimesTen In-Memory Database Reference for more information.

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 on 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 ttenv 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 (discussed in the next section about the ODBCINI environment variable). If it is not found there, TimesTen looks in the sys.odbc.ini file.

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 and 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. (Also see the preceding section about the SYSODBCINI environment variable.)

For more information, see "Overview of user and system DSNs" in the Oracle TimesTen In-Memory Database Operations Guide.

SYSTTCONNECTINI environment variable

On Linux and UNIX hosts, 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 Windows systems, configure logical server names using the ODBC Data Source Administrator.