ttAdmin
-
Get information about
ttAdminoptions, version, and settings. See Help, Version, and Query Options. -
Specify settings for database RAM policy, database start, and database stop. See Perform RAM Operations.
-
Open or close a database to user connections. See Open or Close a Database.
-
Run a forced disconnect operation for existing database connections. See Force Disconnect.
-
Start and stop TimesTen cache agents for caching data from Oracle Database tables. The cache agent is a process that handles Oracle Database access on behalf of a TimesTen database. It also handles the aging and autorefresh of the cache groups in the TimesTen database. See Set Cache Policies.
-
Specify settings to automatically or manually start and stop replication agents for specified databases. See Set Replication Policies.
Required Privilege
This utility requires no privileges to query the database.
Open and close options require the instance administrator privilege.
Replication options require the ADMIN privilege.
Cache options require the CACHE_MANAGER privilege.
All other options require the ADMIN privilege.
Usage in TimesTen Scaleout and TimesTen Classic
This utility is supported in TimesTen Classic but not supported in TimesTen Scaleout.
Syntax
ttAdmin {-h | -help | -?}
ttAdmin {-V | -version}
ttAdmin -query {-connStr connection_string | DSN}
ttAdmin [-ramUnload | -ramLoad [-open | -close]]
[-ramPolicy {always | manual | enduring | inUse [-ramGrace secs]}]
[-autoreload | -noautoreload]
[-shmAttach | -shmDetach [-ckpt | -noCkpt] | -shmFree]
[-disconnect urgency [granularity]] {-connStr connection_string | DSN}]
urgency: {-transactional | -immediate | -abort}
granularity: [-users | -unload]
ttAdmin -clientExportAll {FILE}{-connStr connection_string | DSN}
ttAdmin -certificateList [-json]
ttAdmin [-repPolicy always | manual | norestart]
[-repStart | -repStop]
[-repQueryThresholdSet secs]
[-repQueryThresholdGet]
[-cacheUidGet]
[-cacheUidPwdSet -cacheUid uid [-cachePwd pwd]]
[-cachePolicy {always | manual | norestart}]
[-cacheStart]
[-cacheStop [-stopTimeout secs]]
{-connStr connection_string | DSN}Notes
The following notes apply to all modes of ttAdmin usage:
The ttAdmin utility is supported only for TimesTen Data Manager DSNs. It is not supported for TimesTen Client DSNs.
Help, Version, and Query Options
Options
ttAdmin has these options for help, version, and settings information:
| Option | Description |
|---|---|
|
|
Prints usage information, syntax, and option descriptions. |
|
|
Prints the TimesTen release number of |
|
|
Displays a summary of the policy settings for the specified database. |
|
|
For |
|
|
For |
Examples
To get the version of ttAdmin:
% ttAdmin -version
TimesTen Release 22.1.1.21.0To get help for ttAdmin:
% ttAdmin -help
Usage:
ttAdmin [-h | -help | -?]
ttAdmin [-V | -version]
ttAdmin [-ramUnload | -ramLoad [-open | -close]]
[-ramPolicy {always | manual | enduring | inUse [-ramGrace secs]}]
[-autoreload | -noautoreload]
[-shmAttach | -shmDetach [-ckpt | -noCkpt] | -shmFree]
[-disconnect urgency [granularity]] {-connStr connection_string | DSN}]
urgency: {-transactional | -immediate | -abort}
granularity: [-users | -unload]
-clientExportAll {FILE}{-connStr connection_string | DSN}
-certificateList [-json]
[-repPolicy {always | manual | norestart}]
[-repStart | -repStop]
[-repQueryThresholdSet secs]
[-repQueryThresholdGet]
[-cacheUidGet]
[-cacheUidPwdSet -cacheUid uid [-cachePwd pwd]]
[-cachePolicy {always | manual | norestart}
[-cacheStart]
[-cacheStop [-stopTimeout secs]]
{-connStr connection_string | DSN}
[-query]
{DSN | [-connstr] connStr}
options:
[...Option descriptions not shown...]
Perform RAM Operations
Options
ttAdmin has these options to set the RAM policy, start the database and stop the database:
| Option | Description |
|---|---|
|
|
An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings. |
|
|
An ODBC data source name of the database to be administered. |
|
|
If set to If set to |
|
|
Only effective if |
|
|
Valid only when |
|
|
Defines the policy used to determine when the database is loaded into system RAM.
This is the recommended RAM policy because it avoids unnecessary database loading or unloading.
This feature enables you to perform a fast patch upgrade, as you can detach from the shared memory segment instead of unloading the database. Then after the upgrade, you can attach to this shared memory segment avoiding loading the database. The RAM policy enduring also enables you to use the-shmFree option.
|
|
|
Performs a clean shutdown of the database by disconnecting the subdaemon and destroying the shared memory segment. The checkpoint file written to disk allows you to reload the database using the The |
|
|
Enables you to reattach to a preserved shared memory segment while starting the database. The prerequisites are setting the RAM policy to enduring and having the shared memory segment previously detached with the |
|
|
Enables you to stop the database by detaching (instead of destroying) the shared memory segment. Before disconnecting from the shared memory segment, you can specify the subdaemon to perform a static checkpoint with the To use |
|
|
The -shmDetach option but decide you do not want to re-attach the segment, you can free the segment by using the -shmFree option. After doing so, you can still load the database from the checkpoint files using the -ramLoad option.
|
Note:
RAM policy enduring is helpful to perform fast patch upgrades, because you do not need to unload and reload the data which can be time-consuming. The-ramPolicy enduring enables you:
- Use
-shmDetachto preserve the shared memory segment while stopping the database. - Perform the fast upgrade.
- Use
-shmAttachto attach to the preserved memory segment while starting the database.
Examples
To manually control whether database1 is loaded into RAM and to load it now, use the following:
% ttAdmin -ramPolicy manual -ramLoad database1
The database1 database is typically always resident in RAM. However, it is not being used at a given time and should be loaded only when applications are connected to it. To change the RAM policy:
ttAdmin -ramPolicy inUse database1
To set the RAM policy of database1 to enduring:
$ ttAdmin -ramPolicy enduring database1 RAM Residence Policy : enduring Manually Loaded In RAM : False Replication Agent Policy : manual Replication Manually Started : False Cache Agent Policy : manual Cache Agent Manually Started : False Database state : open
Now assume database1 is not always in use. Permanently loading it into RAM would unnecessarily use memory. This database is idle for long periods, but when it is in use multiple users connect to it in rapid succession. To improve performance, it may be best to keep the database in RAM when applications are connected to it and to keep it in RAM for 5 minutes (300 seconds) after the last user disconnects. With this RAM policy, the database remains in RAM if applications are connected to the database. To set this policy:
% ttAdmin -ramPolicy inUse -ramGrace 300 History
Some performance-sensitive applications use a database referred to by DSN database1. So that applications do not have to wait for the database to be loaded from disk into RAM, this database must always remain in RAM. To accomplish this:
% ttAdmin -ramPolicy always database1
To display a summary of the policy settings for the database1 DSN:
% ttAdmin -query database1 RAM Residence Policy : inUse Replication Agent Policy : manual Replication Manually Started : False Cache Agent Policy : manual Cache Agent Manually Started : False Database State : Open
Notes
If you need to destroy a database, use the ttDestroy utility. If the database has a preserved shared memory segment (because it was detached with the -shmDetach utility) you must use the ttDestroy -force option. For more information on destroying a database, see ttDestroy.
Setting the RAM policy to inUse for production systems with large databases is not recommended as the database may unload or reload unexpectedly which can result in long delays and excessive overhead.
RAM policy always conflicts with forced disconnect granularity unload, described in Force Disconnect. Using both simultaneously results in an error and the disconnect request being ignored.
The always RAM policy should be used with caution. When failures occur, it may not be beneficial to have your database automatically reload. In addition, it may affect system startup performance if all databases load at the same time when your system boots.
If the shared memory segment is destroyed manually (for example by using ipcrm), -shmFree returns an error indicating that the shared memory segment is missing; however, the -shmFree command updates the database's DBI file and main daemon bookkeeping. The database can then be successfully loaded with -ramLoad, and the database RAM policy can be changed to another policy besides enduring by using ttAdmin -ramPolicy.
If you try to load a database using -ramLoad while a previously detached shared memory segment exists for that database, then the command returns an error and fails. You must either attach the segment with -shmAttach (instead of -ramLoad) or destroy it using -shmFree, and then reload the database using the -ramLoad option.
Open or Close a Database
Options
ttAdmin has these options for opening or closing a database:
| Option | Description |
|---|---|
|
|
Closes a database to user connections. When a database is closed to user connections, new connection attempts will fail, but existing connections are unaffected. |
|
|
An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings. |
|
|
An ODBC data source name of the database to be administered. |
|
|
Opens a database to user connections. A database is open to user connections by default upon creation. |
|
|
Valid only when |
Examples
To open the database1 DSN:
% ttAdmin -open database1
To load and open the database1 DSN from an unloaded and closed state:
% ttAdmin -ramLoad -open database1
To close the database1 DSN:
% ttAdmin -close database1
To load and close the database1 DSN from an unloaded and open state:
% ttAdmin -ramLoad -close database1
Notes
A database remains closed or open to user connections regardless of its loaded state or RAM policy, unless its closed or open state is modified through ttAdmin or other utilities like ttRestore or ttRepAdmin.
If the -open or -close options are used in conjunction with any option other than -ramLoad, ttAdmin returns an error.
Trying to close a closed database or open an open database returns an error.
Transport Layer Security
Options
ttAdmin has these options for exporting access information and certificates:
| Option | Description |
|---|---|
|
|
Outputs a ZIP file containing the client wallet, a See Task 5: Import Certificates and Configuration in TimesTen Classic in Oracle TimesTen In-Memory Database Security Guide for more information. Also see ttClientImport. |
|
|
Lists certificates that have been created on the server. See Listing Certificates in TimesTen Classic in Oracle TimesTen In-Memory Database Security Guide for more information. |
Force Disconnect
Options
ttAdmin has these options for forced disconnect:
| Option | Description |
|---|---|
|
|
An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings. |
|
|
An ODBC data source name of the database to be administered. |
|
|
Asynchronously disconnects connected applications from the database, optionally including those that are idle or unresponsive. Acceptable values for
Note: A recommended best practice is to run Use abort urgency level only as a last resort if transactional and immediate levels do not result in all connections being closed. Abort may result in loss of data. Abort abruptly causes every user and Acceptable values for
Note: RAM policy |
Examples
This sample script uses -disconnect to disconnect all connections to database1, first using transactional urgency level then immediate urgency level:
#!/bin/sh # close the databae ttAdmin -close database1 # disconnect users and unload the database ttAdmin -disconnect -transactional -unload database1 # wait 10 seconds for the disconnects to finish COUNT = 0 while [ ttStatus | grep "pending disconnection" ] || [ $COUNT -ne 10 ] do sleep 1 COUNT=$((COUNT+1)) done # increase urgency to immediate if [ ttStatus | grep "pending disconnection" ]; then ttAdmin -disconnect -immediate -unload database1 fi
Use ttStatus to check progress. During forced disconnect, output indicates the pending disconnections:
TimesTen status report as of Wed Jul 18 09:55:20 2018
Daemon pid 10457 port 6627 instance user1
TimesTen server pid 10464 started on port 6629
------------------------------------------------------------------------
------------------------------------------------------------------------
Closed to user connections
Data store /databases/database1
Daemon pid 10457 port 6627 instance user1
TimesTen server pid 10464 started on port 6629
There are 14 connections to the data store, ***14 pending disconnection***
Shared Memory KEY 0x0210679b ID 949092358
PL/SQL Memory KEY 0x0310679b ID 949125127 Address 0x5000000000
Type PID Context Connection Name ConnID
Process 10484 0x00007f3ddfeb4010 database1 1
...Notes
To enable the capability for forced disconnect, use the TimesTen connection attribute setting ForceDisconnectEnabled=1. See ForceDisconnectEnabled.
The -disconnect option is asynchronous. Control will quickly return to the command prompt, but the force disconnect operation may take multiple seconds or even minutes to complete. This is why the scripts above use ttStatus to monitor the status of the force disconnect operation.
The users granularity level includes all connections aside from the subdaemon. For example, in addition to user connections, this includes connections for ttcserver and ttstats.
Close the database before attempting a forced disconnect process. Any new connection request is rejected by the main daemon during the forced disconnect process. However, after completion of forced disconnect, connection requests are accepted again if the database is not in a closed state.
Set Cache Policies
Options
ttAdmin has these options for cache:
| Option | Description |
|---|---|
|
|
An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings. |
|
|
An ODBC data source name of the database to be administered. |
|
|
Defines the policy used to determine when the cache agent for the database should run.
|
|
|
Starts a cache agent for the database. |
|
|
Stops a cache agent for the database. You should not shut down the cache agent immediately after dropping or altering a cache group. Instead, wait for at least two minutes. Otherwise, the cache agent may not get a chance to clean up the Oracle Database objects that were used by the autorefresh feature. |
|
|
The password associated with the cache administration user ID that manages autorefresh cache groups and asynchronous writethrough cache groups. The cache administration user has extended privileges. See Grant Privileges to the Oracle Cache Administration User in Oracle TimesTen In-Memory Database Cache Guide for more details. |
|
|
The cache administration user ID. The cache administration user manages autorefresh cache groups and asynchronous writethrough cache groups. The cache administration user has extended privileges. See Grant Privileges to the Oracle Cache Administration User in the Oracle TimesTen In-Memory Database Cache Guide for more details. |
|
|
Gets the current cache administration user ID for the specified database. |
|
|
Registers the cache administration user name and password for the specified database, using the
|
|
|
Specifies that the TimesTen daemon should stop the cache agent if it does not stop within If set to |
Examples
A database referred to by DSN database1 contains data cached from an Oracle database. Use the following ttAdmin command to start the cache agent for database1:
% ttAdmin -cacheStart database1
You can also use the -cachePolicy option to ask the TimesTen data manager daemon to start the cache agent every time the data manager is started:
% ttAdmin -cachePolicy always database1
To turn off the automatic start of cache agent:
% ttAdmin -cachePolicy manual database1
To set the cache administration user ID and password, use -cacheUidPwdSet with -cacheUid and -cachePwd. For example:
% ttAdmin -cacheUidPwdSet -cacheUid cacheadmin -cachePwd orapwd database1
To get the current cache administration user ID for database1:
% ttAdmin -cacheUidGet database1
Notes
Before using any cache features, you must start the cache agent. Cache options require that you specify a value for the OracleNetServiceName in the DSN.
When using autorefresh or asynchronous writethrough cache groups, you must specify the cache administration user ID and password. This user account performs autorefresh and asynchronous writethrough operations.
To load data from an Oracle database, the TimesTen cache agent must be running. This requires that the ORACLE_HOME environment variable be set to the path of the Oracle installation. See Managing the Cache Agent in Oracle TimesTen In-Memory Database Cache
Guide for more details.
Set Replication Policies
Options
ttAdmin has these options for replication:
Examples
These examples show use of replication options:
% ttAdmin -repPolicy always rep1 RAM Residence Policy : inUse Replication Agent Policy : always Cache Agent Policy : manual Cache Agent Manually Started : False Database State : Open % ttAdmin -repPolicy manual rep1 RAM Residence Policy : inUse Replication Agent Policy : manual Replication Manually Started : True Cache Agent Policy : manual Cache Agent Manually Started : False Database State : Open % ttAdmin -repPolicy norestart rep1 RAM Residence Policy : inUse Replication Agent Policy : norestart Replication Manually Started : True Cache Agent Policy : manual Cache Agent Manually Started : False Database State : Open % ttAdmin -repQueryThresholdSet 100 rep1 RAM Residence Policy : inUse Replication Agent Policy : norestart Replication Manually Started : True Cache Agent Policy : manual Cache Agent Manually Started : False Database State : Open % ttAdmin -repQueryThresholdGet rep1 QueryThreshold in seconds : 100 RAM Residence Policy : inUse Replication Agent Policy : norestart Replication Manually Started : True Cache Agent Policy : manual Cache Agent Manually Started : False Database State : Open
Notes
If ttAdmin is used with -repStart and a replication definition is not found, the replication agent is not started and ttAdmin prints out an error message. For example:
% ttAdmin -repstart repl1
*** [TimesTen][TimesTen 22.1.1.21 ODBC Driver][TimesTen]TT8191:
This store (repl1 on my_host) is not involved in a replication scheme --
file "eeProc.c", lineno 11016, procedure "RepAdmin()"
*** ODBC Error = S1000, TimesTen Error = 8191
If ttAdmin is used with -repPolicy manual (the default) or -repPolicy always, then the -ramPolicy always option should also be used. This ensures that the replication agent begins recovery after a failure as quickly as possible.