ttAdmin

This utility specifies or changes database policies. It enables you to:
  • Get information about ttAdmin options, 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:

You need to set some environment variables. See Environment Variables in Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide for more details.

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

-h -help

-?

Prints usage information, syntax, and option descriptions.

-V | -version

Prints the TimesTen release number of ttAdmin and exits.

-query

Displays a summary of the policy settings for the specified database.

-connStr connection_string

For -query, an ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings.

DSN

For -query, an ODBC data source name of the database to be administered.

Examples

To get the version of ttAdmin:

% ttAdmin -version
TimesTen Release 22.1.1.18.0

To 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

-connStr connection_string

An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings.

DSN

An ODBC data source name of the database to be administered.

-autoreload | -noautoreload

If set to -autoreload (default), TimesTen reloads the database after an invalidation.

If set to -noautoreload, TimesTen does not automatically reload the database after an invalidation.

-ramGrace secs

Only effective if -ramPolicy is inUse. If nonzero, the database is kept in RAM for secs seconds before being unloaded after the last application disconnects from the database.

-ramLoad

Valid only when -ramPolicy is manual or enduring. Causes the database to be loaded into RAM. If there is an existing database shared memory segment -ramLoad destroys it before creating the new one. This enables -ramLoad to clean up if an error is returned by ttAdmin -shmAttach. The shared memory segment must be free first so that -ramLoad can destroy it.

-ramPolicy policy

Defines the policy used to determine when the database is loaded into system RAM.

manual - Specifies that the database is only to be loaded in system RAM when explicitly loaded by the user with the -ramLoad option. Using -ramUnload with -ramPolicy manual to unload the database, causes the daemon to destroy any remanent detached shared memory segment from a previous in memory database.

This is the recommended RAM policy because it avoids unnecessary database loading or unloading.

enduring - This RAM policy is like the RAM policy manual, except that it also enables you to use the -shmDetach and -shmAttach options to respectively stop and restart the database without destroying the shared memory segment that contains the database.

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.

inUse (default) - Specifies that the database is loaded in system RAM only when in use (when applications are connected). The -ramGrace option may be used to modify the behavior of this policy.

always - Specifies that the database should remain in system RAM all the time.

-ramUnload

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 ttAdmin -ramLoad option.

The -ramUnload option is valid only with -ramPolicy manual or -ramPolicy enduring.

-shmAttach

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 -shmDetach option.

-shmDetach [-ckpt | -noCkpt]

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 –ckpt option (which is the default) or to not perform a static checkpoint with the –noCkpt option.

To use -shmDetach, the database must be closed and there must be no connections to the database.

-shmFree

The -shmFree option destroys a preserved shared memory segment that remained in memory after a ttAdmin -shmDetach operation.

If you 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:
  1. Use -shmDetach to preserve the shared memory segment while stopping the database.
  2. Perform the fast upgrade.
  3. Use -shmAttach to attach to the preserved memory segment while starting the database.
For more details, see Specifying a RAM Policy and Detaching, Attaching and Freeing the Shared Memory Segment in the Oracle TimesTen In-Memory Database Operations Guide.
For more information About Performing a Fast Patch Upgrade see the Oracle TimesTen In-Memory Database Installation, Migration, and Upgrade Guide.

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

-close

Closes a database to user connections.

When a database is closed to user connections, new connection attempts will fail, but existing connections are unaffected.

-connStr connection_string

An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings.

DSN

An ODBC data source name of the database to be administered.

-open

Opens a database to user connections.

A database is open to user connections by default upon creation.

-ramLoad

Valid only when -ramPolicy is manual. Causes the database to be loaded into RAM.

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

-clientExportAll FILE

Outputs a ZIP file containing the client wallet, a sys.odbc.ini file that can be used in accessing the database, and other files (such as tnsnames.ora file) as applicable.

See Client Imports for TLS in TimesTen Classic in Oracle TimesTen In-Memory Database Security Guide for more information. Also see ttClientImport.

-certificateList [-json]

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

-connStr connection_string

An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings.

DSN

An ODBC data source name of the database to be administered.

-disconnect urgency [granularity]

Asynchronously disconnects connected applications from the database, optionally including those that are idle or unresponsive.

Acceptable values for urgency (required) are:

-transactional - Allows any open transactions to be committed or rolled back before disconnecting. Does not affect idle connections.

-immediate - Rolls back any open transactions before immediately disconnecting. This also disconnects idle connections.

-abort - Aborts all direct mode application processes and client/server processes (ttcserver) in order to disconnect them.

Note: A recommended best practice is to run -disconnect twice, as necessary. First run it in transactional urgency level. Then, after allowing some time, if not all connections have been closed yet, run it in immediate urgency level. Use ttStatus to confirm whether connections have been closed.

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 ttcserver process connected to the database to exit. This may result in lost transactions.

Acceptable values for granularity are:

-users (default) - Disconnects every user connection to the database. This is useful for administrators who want to perform database maintenance.

-unload - Disconnects every connection to the database, including the subdaemon. This cleanly unloads the database.

Note: RAM policy always, described in Perform RAM Operations, conflicts with forced disconnect granularity unload. Using both simultaneously results in an error and the disconnect request being ignored.

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

-connStr connection_string

An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings.

DSN

An ODBC data source name of the database to be administered.

-cachePolicy

Defines the policy used to determine when the cache agent for the database should run.

manual (default) - Specifies that the cache agent must be manually started and stopped.

always - Specifies that the cache agent should always be running for the database. This option immediately starts the cache agent and when the daemon restarts, the cache agent is restarted.

norestart - Specifies that the cache agent for the database is not to be restarted after a failure.

-cacheStart

Starts a cache agent for the database.

-cacheStop

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.

-cachePwd

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 Database Users in Oracle TimesTen In-Memory Database Cache Guide for more details.

-cacheUid

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 Database Users in the Oracle TimesTen In-Memory Database Cache Guide for more details.

-cacheUidGet

Gets the current cache administration user ID for the specified database.

-cacheUidPwdSet

Registers the cache administration user name and password for the specified database, using the -cacheUid and -cachePwd options. Note the following:

  • The CacheAdminWallet connection attribute specifies that credentials for the Oracle cache administration user that are set with the -cacheUidPwdSet option are stored in a system-managed Oracle Wallet. With the CacheAdminWallet connection attribute set to 0, the default value, TimesTen encrypts the credentials that you previously defined and stores them in memory. By setting the value to 1, TimesTen creates an Oracle Wallet to store the credentials. See CacheAdminWallet.
  • You only need to register the cache administration user ID and password once for each new database.

  • For all levels of DDLReplicationLevel, you can register the cache administration user name and password with the -cacheUidPwdSet option while the cache or replication agents are running. See Making DDL Changes in an Active Standby Pair in the Oracle TimesTen In-Memory Database Replication Guide.

  • The cache administration user ID cannot be reset while there are cache groups on the database. The cache administration password can be changed at any time.

-stopTimeout secs

Specifies that the TimesTen daemon should stop the cache agent if it does not stop within secs seconds.

If set to 0, the daemon potentially waits forever for the cache agent. The default value is 100 seconds.

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:

Option Description

-connStr connection_string

An ODBC connection string that specifies a database location, driver, and optionally other connection attribute settings.

DSN

An ODBC data source name of the database to be administered.

-repPolicy

Defines the policy used to determine when the replication agent starts.

manual (default) - Specifies that the replication agent must be manually started and stopped.

always - Specifies that the agent should always be running for the database. This option immediately starts the replication agent. When the daemon restarts, the replication agent is restarted.

norestart - Specifies that the replication agent for the database is not to be restarted after a failure.

-repQueryThresholdGet

Returns the number of seconds that a query can be run by the replication agent before TimesTen writes a warning to the daemon log. A value of 0 indicates that no warning is sent.

-repQueryThresholdSet secs

This option specifies the number of seconds that a query can be run by the replication agent before TimesTen writes a warning to the daemon log.

The specified value takes effect the next time the replication agent starts. The query threshold for the replication agent applies to SQL execution on detail tables of materialized views, ON DELETE CASCADE operations and some internal operations.

The value must be greater than or equal to 0.

Default is 0 and indicates that no warning is sent.

-repStart

Starts the replication agent.

-repStop

Stops the replication agent.

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