ttGridAdmin

Use the ttGridAdmin utility for all aspects of administering a grid, such as creating a grid, adding or removing data instances or management instances, creating databases, and redistributing data to new data instances. The grid and database configuration resulting from these operations is stored in the grid model, which is distributed to instances of the grid. (See Grid Model for an introduction to the model.)

Note:

In TimesTen Scaleout, do not update configuration files manually (such as timesten.conf, sys.odbc.ini, and tnsnames.ora).

Required Privilege

Instance administrator of the management instance from which ttGridAdmin is run. The user then becomes the instance administrator of all instances created with ttGridAdmin.

Usage in TimesTen Scaleout and TimesTen Classic

This utility is specifically for use with TimesTen Scaleout, with commands that perform any operations on a grid.

Syntax

For general syntax (help options and options that apply to all commands), see Help and General Options. For syntax for individual commands, see the relevant sections under ttGridAdmin Operations.

Grid Model

TimesTen Scaleout maintains a central configuration of the grid within a model that describes the desired structure of the grid. The model represents the desired logical topology of the grid and contains objects that represent components of the grid, such as installations, hosts, instances, and database definitions. Each time you use ttGridAdmin to add a grid component, a corresponding object is added to the model.

When you use ttGridAdmin to apply the model, TimesTen Scaleout attempts to implement it into the operational grid, such as by creating the desired physical installations and instances.

Grid Objects and Object Naming

Each entity in a grid—such as each host, instance, installation, and repository—is defined as a named object.

Each object type, representing these types of entities, has its own namespace. You can have a host named xyz and a repository named xyz without conflict. In addition, instance namespaces and installation namespaces are per host. You can have an instance named instance1 on host1 and an instance named instance1 on host2 without conflict.

Object-naming hierarchies such as this can be expressed in ttGridAdmin syntax using fully qualified names, toplevelobject.nextlevelobect. For example, host1.instance1 and host2.instance1. To specify an instance or installation in ttGridAdmin syntax, you need only specify hostname (instead of hostname.instancename or hostname.installname) if there is only one instance or installation (as applicable) on the host.

Operations on grid entities through ttGridAdmin, such as creating or removing an instance or installation, are managed through the corresponding objects in the model. The physical entities themselves are not created or removed until the model is applied through the ttGridAdmin modelApply command. For example, to remove an instance named host1.instance1, the instanceDelete command removes the object named host1.instance1 from the model, then the modelApply command removes the physical instance (the instance home directory and everything under it).

Be aware of these limitations in object naming in the grid model:

• Names must use only ASCII characters.

• Allowed characters are alphabetic, numeric, hyphen (-), and underscore (_).

• Database definition names and connectable names are limited to 32 characters (due to ODBC limitations).

• All other object names are limited to 256 characters.

• Object names are case-insensitive (so you cannot have an instance instance and an instance Instance on the same host), but are represented and shown as specified in ttGridAdmin commands. If you specify MyInstance in the instanceCreate command, that is how it will be shown.

• You cannot name anything All or Default, which are reserved names.

Address Formats

Some ttGridAdmin commands, such as gridCreate and hostCreate, have options to specify the address or addresses used for internal and external communications. You can specify addresses as DNS names or IP addresses, although use of DNS names is more typical. IP addresses can be in either IPv6 or IPv4 format. For example:

• DNS name: myhost.example.com

• IPv6 address: 2001:b400:2000:834:26:3eff:fe07:5b83

• IPv4 address: 192.0.2.1

Database Management Operations

In a Grid environment, database management operations—dbCreate/dbDestroy, dbLoad/dbUnload, dbOpen/dbClose—are performed asynchronously by default. This is generally advisable, as such operations are not atomic and may take a long time. In a large grid, loading a database may succeed immediately on many hosts, take a little longer on others, and much longer on others. Some hosts may, in fact, be down when the operation was run, so cannot perform the operation until they are back up.

By default, commands for these database operations return without waiting for completion, but they can optionally wait, with or without a timeout. With wait and a timeout, a command does not return until it has completed on all instances or reaches the timeout. With wait and no timeout, a command will never return if any instances are down. There are advantages and disadvantages to each approach, depending on factors such as how large the grid is. For a large grid, you may choose to proceed before the operation has completed on all instances, while on a small grid it may be more sensible to wait until it has completed on every instance.

TimesTen Scaleout tracks the state of a database, including each element of the database, and it is up to the user to check status of an operation (through the dbStatus command, optionally using the -all option for further details) to see how many instances have completed the operation. In particular, after loading the database, you can use the status information to determine if it has been loaded on enough instances for the database to be opened and users to start accessing it.

No command is provided to cancel an operation on any or all instances.

Command Timeouts and Waits

Note that as ttGridAdmin runs a command, it may run operating system commands as well. Using the top-level -timeout option, you can specify that ttGridAdmin will wait for the specified number of seconds for such operations to complete. If an operation does not complete within the specified number of seconds, the ttGridAdmin command being run fails.

In addition, the ttGridAdmin database management commands dbCreate, dbDestroy, dbload, dbUnload, dbOpen and dbClose have a –nowait/-wait option. Each of these commands initiates a state change that is recorded in the active management instance of the grid. With a setting of –nowait (the default), the commands return immediately without waiting for the state change to complete. If –wait with a timeout value n is specified, ttGridAdmin will wait for up to n seconds for the state change to complete. If –wait is specified without a timeout, ttGridAdmin will wait without limit for the state change to complete.

ttGridAdmin Operations

The listed sections provide detailed information about ttGridAdmin commands and functionality in these areas:

• Help and General Options

• Return Values

• Backup and Restore Operations

• Cache Operations

• Certificate Operations

• Connectable Operations

• Database Definition Operations

• Database Operations

• Grid Operations

• Host Operations

• Import and Export Operations

• Installation Operations

• Instance Operations

• Management Instance Operations

• Membership Operations

• Model Operations

• Oracle Database Operations

• Repository Operations

Help and General Options

These options work with any ttGridAdmin command or, for help, at the top level without any command.

ttGridAdmin [-h | -help | -?] [command] 

ttGridAdmin [-o json] [-timeout n] command [-command_option] ...

Options

ttGridAdmin has the general options:

Option	Description
-h -help -?	Display help information. If specified by itself, this option categorizes and lists ttGridAdmin commands. For example: ttGridAdmin -h if specified with a command, this option displays syntax and option descriptions for the given command. For example: ttGridAdmin -h dbCreate
-o json	Choose JSON output. Output for the command will be in JSON format. (Otherwise, output is in human-readable format.) Important: There is no guarantee of JSON output compatibility between TimesTen releases.
-timeout n	Maximum number of seconds to wait for a long-running operation to complete. The default is 600. Note that as ttGridAdmin runs a command, it may run operating system commands as well. It will wait for the specified number of seconds for such operations to complete. If an operation does not complete within the specified number of seconds, the ttGridAdmin command being run fails.

Return Values

This section describes error or status values and JSON data elements returned by ttGridAdmin commands.

Error and Status Return Codes

ttGridAdmin commands returns error codes to note success or failure, including these general codes:

Code	Description
0	Success
255	Internal error
254	Syntax error

JSON Data Elements Returned

When JSON output is specified, the stdout of the command includes at least these name/value pairs. (Refer to http://www.json.org/ for general information about JSON output.)

Return	Type	Description
"status"	number	Return code See the preceding section, "Error and Status Return Codes".
"errno"	number	Error number, if an error occurred
"errmsg"	string	Error message, if an error occurred

Note:

Additional, command-specific JSON data elements may also be returned.