This chapter discusses how to create and manage client installations and client instances. After you complete the necessary steps, you can use the TimesTen client to connect to either a database in TimesTen Scaleout or a database in TimesTen Classic. This chapter does not cover the Windows platform. See Chapter 3, "Installation and Management of TimesTen on Windows" for information on the Windows platform.
Ensure you have reviewed the terminology and completed the prerequisites. See Chapter 1, "Overview of the Installation Process in TimesTen Classic" for more information.
For information on TimesTen Scaleout, see "Overview of TimesTen Scaleout" in the Oracle TimesTen In-Memory Database Scaleout User's Guide.
The examples in this chapter are performed on a macOS host, but are applicable to the platforms that support client-only installations and client-only instances.
Topics include:
The instance administrator installs the client installation by unzipping the distribution. See "Distribution media and the distribution" and see "Instance administrator" for details.
Topics include:
To create the TimesTen client installation that is accessible by the instance administrator's primary group:
Place the appropriate distribution file in some desired, accessible location.
Create the desired directory for the installation.
Change directories to the desired directory for the installation.
Extract the distribution into that directory.
In the following example on a macOS host, ttuser1, with primary group timesten, creates a client installation into the directory macclientinstall (a subdirectory of the current directory) from a distribution file in /swdir/TimesTen/ttinstallers. This installation is accessible to members of timesten.
% mkdir macclientinstall
% cd macclientinstall
% unzip /swdir/TimesTen/ttinstallers/timesten181410.client.macos64.zip
[...UNZIP OUTPUT...]
The top level directory of the installed files is of the form tt18.1.4.1.0.
For example, this directory is created under macclientinstall:
dr-xr-x--- 19 ttuser1 timesten 4096 Aug 2 22:07 tt18.1.4.1.0
The tt18.1.4.1.0 directory includes such files as (Not all files are listed):
dr-xr-x--- 2 ttuser1 timesten 4096 Aug 2 22:07 bin dr-xr-x--- 3 ttuser1 timesten 4096 Aug 2 22:07 include dr-xr-x--- 2 ttuser1 timesten 4096 Aug 2 22:07 info dr-xr-x--- 2 ttuser1 timesten 4096 Aug 2 22:07 lib dr-xr-x--- 8 ttuser1 timesten 4096 Aug 2 22:07 plsql dr-xr-x--- 3 ttuser1 timesten 4096 Aug 2 22:07 ttoracle_home
To verify the installation, run the ttInstallationCheck utility. In addition, you can review the installation directory and subdirectories.
In this example, the installation is verified and is successful:
% installation_dir/tt18.1.4.1.0/bin/ttInstallationCheck
This installation has been verified.
See "The ttInstallationCheck utility" in this book for information on the ttInstallationCheck utility. Also, see "ttInstallationCheck" in the Oracle TimesTen In-Memory Database Reference.
A TimesTen client-only installation includes these subdirectories located under the top-level installation_dir/tt18.1.4.1.0 directory (Not all of the subdirectories are included in this list).
bin: TimesTen utilities and executables
include: TimesTen include files, among them timesten.h (for TimesTen ODBC features) and tt_errCode.h (for information about TimesTen error codes)
lib: TimesTen libraries
plsql: Files and resources for TimesTen PL/SQL
ttoracle_home: Oracle Database Instant Client files and resources, for OCI, Pro*C/C++, and ODP.NET
After the instance administrator unzips the distribution, thereby creating an installation, the next step is to create a TimesTen client instance.To do this, you run the ttInstanceCreate utility, located in the installation_dir/tt18.1.4.1.0/bin directory.
Note:
Only the user who unpacked the distribution (the creator of the installation) can create an instance from the installation.
This user must be a member of the TimesTen users group.
This user is the only user that can be the instance administrator of this instance and all other instances associated with the installation.
Topics include:
You can specify options for the ttInstanceCreate utility:
On the command line
In a file
Interactively as the utility runs
You can also run ttInstanceCreate with the -help option to list the available options. See "ttInstanceCreate" in the Oracle TimesTen In-Memory Database Reference for detailed descriptions.
Note:
ThettInstanceCreate -clientonly option is optional for a client-only installation on a macOS or a Linux 32-bit host.A TimesTen client instance can be used to connect either to a database in TimesTen Scaleout or a database in TimesTen Classic.
To create a client instance, navigate to the installation_dir/tt18.1.4.1.0/bin area and run the ttInstanceCreate utility.
After you create the client instance, you can set up your DSN and then follow the steps to connect to the server from the client. See "Working with the TimesTen Client and Server" in the Oracle TimesTen In-Memory Database Operations Guide for details.
Examples of creating a client instance include:
Example 4-1, "ttInstanceCreate: Create a client instance interactively"
Example 4-2, "ttInstanceCreate: Specify options on the command line"
Example 4-1 ttInstanceCreate: Create a client instance interactively
This example runs the ttInstanceCreate utility interactively to create a client instance. You run the utility from the installation directory. User input is shown in bold.
% installation_dir/tt18.1.4.1.0/bin/ttInstanceCreate * Client installation detected. NOTE: Each TimesTen instance is identified by a unique name. The instance name must be a non-null alphanumeric string, not longer than 255 characters. Please choose an instance name for this installation? [ tt181 ] clientmac Instance name will be 'clientmac'. Is this correct? [ yes ] Where would you like to install the clientmac instance of TimesTen? [/home/ttuser ] /scratch/ttuser Creating instance in /scratch/ttuser/clientmac ... INFO: Mapping files from the installation to /scratch/ttuser/clientmac/install The 18.1 Release Notes are located here : '/installation_dir/tt18.1.4.1.0/README.html'
Example 4-2 ttInstanceCreate: Specify options on the command line
This example runs the ttInstanceCreate utility and specifies the name and the location on the command line. (The name of the directory specified in the -location option must exist prior to running the ttInstanceCreate utility.) See "ttInstanceCreate" in the Oracle TimesTen In-Memory Database Reference for the supported options.
Ensure you run the ttInstanceCreate utility from the installation directory
% installation_dir/tt18.1.4.1.0/bin/ttInstanceCreate -name clientmac -location /scratch/ttuser * Client installation detected. Creating instance in /scratch/ttuser/clientmac ... INFO: Mapping files from the installation to /scratch/ttuser/clientmac/install The 18.1 Release Notes are located here : '/installation_dir/tt18.1.4.1.0/README.html'
You can review the instance home directory and subdirectories for informational purposes. When you create an instance, each instance includes these subdirectories under $TIMESTEN_HOME (Not all of the subdirectories are included in this list):
bin: TimesTen utilities and executables tailored and specific to the instance
This includes ttenv.sh (or ttenv.csh), which sets environment variables appropriately for the TimesTen environment for your session, and setuproot.sh, which can be run as root to cause data instances to be automatically started whenever the operating system reboots.
Note that ttenv also puts the bin directory in your path.
conf: Contains the timesten.conf file, which is the TimesTen instance configuration file
diag: Diagnostic output, including the daemon log and error log
info: Working directory of the TimesTen daemon, containing persistent state about the TimesTen instance
install: Symbolic link referencing the installation associated with this instance.
plsql: Contains this subdirectory:
utl_file_dir: The only directory that can be read from or written to by PL/SQL blocks using the UTL_FILE package
The instance configuration file defines the attributes of the TimesTen instance. See "Instance configuration file (timesten.conf)" for more information.
A sample file follows. Comments are indicated "#".
# TimesTen Instance Configuration File # Created by ttInstanceCreate # Commented values are default values hostname=host1 client_only=yes timesten_release=18.1 instance_name=clientmac daemon_port=- admin_user=myadmin admin_uid=12345 group_name=ttgroup instance_guid=FE8D9351-E749-41B4-AEC9-6E27BCA882A5 verbose=1
The ttInstanceModify utility modifies the attributes of the instance. The relevant ttInstanceModify options for a client instance are the -install and the -tnsadmin options.
The client instance that is modified is the instance that the $TIMESTEN_HOME environment variable references. Ensure you run the ttInstanceModify utility from the $TIMESTEN_HOME/bin directory.
See "ttInstanceModify" in the Oracle TimesTen In-Memory Database Reference for more information.
Examples include:
Example 4-3 ttInstanceModify: Run interactively
This example runs ttInstanceModify interactively. The utility asks if you want to change the installation that the instance points to. This is equivalent to running ttInstanceModify with the -install option.
This example upgrades from the ttinstall installation to the ttinstalllatest installation. The current directory is timesten_home for the clientmac instance.
Specify the full path to the desired installation_dir/tt18.1.4.1.0 directory.
% $TIMESTEN_HOME/bin/ttInstanceModify
Instance Info
-------------
Name: clientmac
Version: 18.1.3.5.0
Location: /scratch/ttuser/clientmac
Installation: /swdir/TimesTen/ttinstallations/ttinstall/tt18.1.3.5.0
* Client-Only Installation
Would you like to change the installation that this instance points to? [ no ] yes
Please provide the path to the new installation? [ ]
/swdir/TimesTen/ttinstallations/ttinstalllatest/tt18.1.4.1.0
Are you sure you want to point this instance to the installation in
/swdir/TimesTen/ttinstallations/ttinstalllatest/tt18.1.4.1.0? [ no ] yes
Instance Info (UPDATED)
-----------------------
Name: clientmac
Version: 18.1.4.1.0
Location: /scratch/ttuser/clientmac
Installation: /swdir/TimesTen/ttinstallations/ttinstalllatest/tt18.1.4.1.0
* Client-Only Installation
The instance clientmac now points to the installation in
/swdir/TimesTen/ttinstallations/ttinstalllatest/tt18.1.4.1.0
Example 4-4 ttInstanceModify: Specify -install
The example runs the ttInstanceModify utility with the -install option to upgrade from the ttinstall installation to the ttinstalllatest installation. The current directory is timesten_home for the clientmac instance.
% $TIMESTEN_HOME/bin/ttInstanceModify -install
/swdir/TimesTen/ttinstallations/ttinstalllatest/tt18.1.4.1.0
Instance Info (UPDATED)
-----------------------
Name: clientmac
Version: 18.1.4.1.0
Location: /scratch/ttuser/clientmac
Installation: /swdir/TimesTen/ttinstallations/ttinstalllatest/tt18.1.4.1.0
* Client-Only Installation
The instance clientmac now points to the installation in
/swdir/TimesTen/ttinstallations/ttinstalllatest/tt18.1.4.1.0
The ttInstanceDestroy utility destroys an existing instance. The instance that will be destroyed is based on the current setting of the TIMESTEN_HOME environment variable, which indicates the instance home directory. Run the ttInstanceDestroy utility that is located in the bin directory of the associated installation. (For example, installation_dir/tt18.1.4.1.0/bin.)
Only the instance administrator (the user who created the instance) can destroy the instance.
Note:
There can be no existing connections to databases associated with the instance you are destroying.Run the ttInstanceDestroy utility with the -help option to list the available options. See "ttInstanceDestroy" in Oracle TimesTen In-Memory Database Reference for detailed descriptions.
Note:
The-force option completes the operation without prompting for confirmation.Example 4-5 ttInstanceDestroy: Destroy a client instance
This example runs the ttInstanceDestroy utility interactively to destroy the client. instance. The utility runs from the installation_dir/tt18.1.4.1.0/bin directory (the installation directory for the instance). Recall that the instance home directory (timesten_home) contains a subdirectory (/install) that is a symbolic link to the top-level directory of the instance's associated installation. See "Instance home" for information.
% installation_dir/tt18.1.4.1.0/bin/ttInstanceDestroy
** WARNING **
The uninstallation has been executed by a non-root user.
If the TimesTen daemon startup scripts were installed,
you must run $TIMESTEN_HOME/bin/setuproot -uninstall
to remove them. If you proceed with this uninstallation, you
will have to remove the startup scripts manually.
** WARNING **
All files in the directory:
/scratch/ttuser/clientmac
will be removed, including any file that you or other users may have created.
Are you sure you want to completely remove this instance? [ yes ] yes
Installation will remove all the files from
/scratch/ttuser/clientmac.
Do you want to continue? [ yes ] yes
NOTE: /scratch/ttuser/clientmac/info contains information related to the
data stores that have been created with this release. If you remove
/scratch/ttuser/clientmac/info
you will no longer be able to access your data stores,
nor would you be able to restore nor migrate your data.
NOTE: /scratch/ttuser/clientmac/conf contains information related to the instance
configuration.
/scratch/ttuser/clientmac Removed
The TimesTen instance clientmac has been destroyed.
To delete (uninstall) the client installation, the instance administrator performs these steps:
Ensures that there are no Timesten instances, databases or important files located under the TimesTen installation.
Ensures that no TimesTen instances use the installation. (There is no automated way to do this, as TimesTen does not maintain any inventory of TimesTen installations or instances.)
If there are instances that use the installation, then before the installation is deleted, the instances must be either modified to point to a different installation or deleted. See "Modifying a TimesTen client instance" for details.
Grants write permission to the installation, such as through the chmod -R command. For example, from the installation directory where a TimesTen 18.1.4.1.0 installation was extracted:
% chmod -R 750 installation_dir/tt18.1.4.1.0
Deletes the tt18.1.4.1.0 directory and all files and subdirectories that it contains, such as through the rm -rf command. From the installation directory:
% rm -rf installation_dir/tt18.1.4.1.0
If the installation directory is empty, optionally deletes it.