1. Reference
  2. TimesTen Scaleout Utilities
  3. ttGridAdmin
  4. Instance Operations

Instance Operations

Use ttGridAdmin commands in this section to define a TimesTen Scaleout instance in the model, modify an instance, delete an instance, list instances in the grid, display status of instances in the grid, import or export an instance configuration file, or run a command on instances in the grid.

Export Instance Configuration Attributes (instanceConfigExport)

The instanceConfigExport command exports configuration attribute settings, previously imported using instanceConfigImport, from the specified version of the model.

Options

The instanceConfigExport command has the options:

Option Description

-current

Export configuration attribute settings that were imported into the current model—the model currently applied to the grid.

-latest

Export configuration attribute settings that were imported into the latest model, which has not yet been applied to the grid. This is the default.

-version n

Export configuration attribute settings that were imported into the specified version of the model.

filepath

The path and name of the file to export configuration attribute settings into. If no file is specified, the information is written to stdout.

Examples

This example exports a configuration attribute setting from the current version of the model and from the latest (default) version of the model after the imports shown in the next section, Import Instance Configuration Attributes (instanceConfigImport). Contents of the export files are also shown. 

% ttGridAdmin instanceConfigExport -current /tmp/instanceconfigexp1
% more /tmp/instanceconfigexp1
max_conns_per_server=500
% ttGridAdmin instanceConfigExport /tmp/instanceconfigexp2
% more /tmp/instanceconfigexp2
max_conns_per_server=1000

Notes

This command exports only settings that were previously imported, not any other settings from the timesten.conf files.

Import Instance Configuration Attributes (instanceConfigImport)

The instanceConfigImport command imports configuration attribute settings into the latest version of the model, to be used by every instance in the grid. 

ttGridAdmin instanceConfigImport [filepath]

After you run modelApply, the configuration file for each instance is updated to include the imported attributes. You must restart the TimesTen daemon on each instance for the changes to take effect.

See Notes below for a list of attributes you cannot import.

Options

The instanceConfigImport command has the option:

Option Description

filepath

The path and name of the file to import configuration attribute settings from. If no file is specified, the information is read from stdin.

Examples

Import from this file.

% more /tmp/instanceconfigimp1
# Set maximum number of connections.
max_conns_per_server=500
% ttGridAdmin instanceConfigImport /tmp/instanceconfigimp1
Instance configuration file /tmp/instanceconfigimp1 imported

Apply the model (output is not shown):

% ttGridAdmin modelApply
...
ttGridAdmin modelApply complete

Now import from this file:

% more /tmp/instanceconfigimp2
# Set maximum number of connections.
max_conns_per_server=1000
% ttGridAdmin instanceConfigImport /tmp/instanceconfigimp2
Instance configuration file /tmp/instanceconfigimp2 imported

After these steps, the latest version of the model will have a maximum connections setting of 500 and the current version of the model will have a setting of 1000. This is shown in the examples in the previous section, Export Instance Configuration Attributes (instanceConfigExport).

Notes

  • As shown in the example, each entry that is imported is of the form name=value. You can also include comments, indicated by #.

  • The timesten.conf files are updated when you run modelApply.

  • The following attributes are set automatically when the modelApply command creates or configures instances and cannot be imported: 

    admin_uid
admin_user
client_only
daemon_port
grid_external_addr
grid_guid
grid_host
grid_instance
grid_internal_addr
grid_name
guid
hostname
instance_guid
instance_name
listen_addr
server_port
timesten_release
tns_admin

  • Refer to TimesTen Instance Configuration File for information about TimesTen configuration attributes.

Create an Instance (instanceCreate)

The instanceCreate command defines an instance in the model. 

ttGridAdmin instanceCreate  hostname[.instancename]
                            -location path
                            [-type management|data]
                            [-installation name]
                            [-daemonport n]
                            [-csport n]  
                            [-mgmtport n] 
                            [-comment comment]
                            [-walletDir path]

Options

The instanceCreate command has the options:

Option Description

hostname[.instancename]

The hostname is the name of the host where the instance is to be created, optionally with a specified instancename for the name of the instance in the model. The default is instance1.

-location path

Path, on the specified host, to the directory where the instance is to be created. The specified directory does not have to exist.

-type management|data

Specifies which type of instance is defined. The default is a data instance.

-installation name

Name of the installation that the instance will use. This option is not necessary if there is only one installation on the host.

-daemonport n

Port number where the TimesTen main daemon for the instance will listen. The default is 6624.

Important: If you create more than one instance on a system (such as a management instance and a data instance), you must specify unique port numbers.

-csport n

Port number where the server for TimesTen client/server will listen. The default is 6625.

Important: If you create more than one instance on a system (such as a management instance and a data instance), you must specify unique port numbers.

-mgmtport n

For management instances, the port number that will be used by replication when management data on the active management instance is replicated. The default is 3754.

-comment comment

Associates a comment with the instance object. Put the comment in quotes if there are any spaces. The comment is stored and included in output of the instanceList command.

-walletDir path

For the first management instance of the grid being created, path to the directory where the Oracle Wallets with cryptographic information will be stored. This cryptographic information includes the cache admin, client/server, and membership service credentials.

The default is timesten_home/info.

Wallets for multiple instances can be stored in the same directory, a directory which can be shared between the instances, such as through NFS.

Examples

% ttGridAdmin instanceCreate mysys3host.griddata1
-location /sw/tten/grid/ttinstances -daemonPort 20000 -csPort 21000
Instance griddata1 on Host mysys3host created in Model

Notes

  • This command does not create a physical instance. It defines an instance object in the model. The modelApply command creates the physical instance.

  • Be aware of these prerequisites:

    • The host must have an associated installation object. Use the installationCreate command.

    • For a data instance, the host must be in a data space group. If that is not the case, the physical instance cannot be created when you apply the model.

      You can use the hostList command to confirm whether a host is in a data space group, and the hostModify command to assign a data space group if needed.

  • The timesten_home directory will be location/name. In the example, where the location is /sw/tten/ttinstances and the instance name is griddata1, timesten_home will be /sw/tten/ttinstances/griddata1.

  • Some instance settings can be changed later through the instanceModify command, as desired.

Delete an Instance (instanceDelete)

The instanceDelete command deletes an instance from the model. 

ttGridAdmin instanceDelete hostname[.instancename]

Options

The instanceDelete command has the option:

Option Description

hostname[.instancename]

The hostname is the name of the host where the instance is to be deleted. The instancename is the name of the instance to be deleted and is required only if there is more than one instance on the host.

Examples

In this example, griddata1 is the only instance on the host. 

% ttGridAdmin instanceDelete mysys3host
Instance griddata1 on Host mysys3host deleted from Model

Notes

  • This command first stops the instance if it has not already been stopped.

  • The command removes the instance object from the model. It does not remove the physical instance. (The modelApply command removes the instance.)

  • You cannot remove an instance that is still used by other objects in the model.

  • You cannot remove an instance that contains a database element.

Execute a Command or Script on Grid Instances (instanceExec)

The instanceExec command executes a command (such as a system command or TimesTen command) or a script on instances in the grid, as specified. 

ttGridAdmin instanceExec [-only hostname[.instancename]]
                         [-exclude hostname[.instancename]]
                         [-parallel n]
                         [-type all|management|data]
                         [-up]
                          command | -script filepath

Options

The instanceExec command has the options:

Option Description

-only hostname[.instancename]

The command or script is run only on the specified instances. Specify just one instance with -only, but you can use -only multiple times on the command line.

Use host names and instance names as defined in the model. You do not have to include the instance name if it is the only instance on the host.

-exclude hostname[.instancename]

The command or script is run on all instances in the grid except for those specified. Specify just one instance with -exclude, but you can use -exclude multiple times on the command line.

Use host names and instance names as defined in the model. You do not have to include the instance name if it is the only instance on the host.

-parallel n

Specifies that the command or script runs on no more than n instances simultaneously. The default is 10. A value of 1 results in serial execution.

-type all|management|data

Specifies whether the command or script is run on all instances (the default), only management instances, or only data instances.

This can be used in combination with -only or -exclude.

-up

Specifies that the command or script is run only on instances that are part of the current membership. The default is to run commands on all instances (whether they are running or not).

command | -script filepath

command specifies a command to run.

Or:

-script filepath specifies the path and name of a shell script to run. The script must be on the local system, then is copied to each instance.

Examples

On each data instance, this example creates directories databases and logs under /data (with no error if the directories already exist). 

% ttGridAdmin instanceExec -type data mkdir -p /data/{databases,logs}
Overall return code: 0
Commands executed on:
  mysys6host.griddata4 rc 0
  mysys5host.griddata3 rc 0
  mysys3host.griddata1 rc 0
  mysys4host.griddata2 rc 0
Return code from mysys6host.griddata4: 0
Output from mysys6host.griddata4:
Return code from mysys5host.griddata3: 0
Output from mysys5host.griddata3:
Return code from mysys3host.griddata1: 0
Output from mysys3host.griddata1:
Return code from mysys4host.griddata2: 0
Output from mysys4host.griddata2:

This example starts the TimesTen daemon on mysys5host.griddata3 (useful, for example, if the element on that instance went down). 

% ttGridAdmin instanceExec -only mysys5host.griddata3 ttDaemonAdmin -start
Overall return code: 0
Commands executed on:
  mysys5host.griddata3 rc 0
Return code from mysys5host.griddata3: 0
Output from mysys5host.griddata3:
TimesTen Daemon (PID: 7586, port: 6624) startup OK.

For each data instance, this example runs the ttIsql monitor command then exits ttIsql. (Only selected portions of the ttIsql connection output and monitoring output are shown.) 

% ttGridAdmin instanceExec -type data 'ttIsql -e "monitor;quit" -dsn database1'
Overall return code: 0
Commands executed on:
  mysys4host.griddata2 rc 0
  mysys5host.griddata3 rc 0
  mysys6host.griddata4 rc 0
  mysys3host.griddata1 rc 0
Return code from mysys4host.griddata2: 0
Output from mysys4host.griddata2:
 
Copyright (c) 1996, 2018, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=database1";
Connection successful: DSN=database1;...
 
monitor;
 
  TIME_OF_1ST_CONNECT:         Fri Aug  3 13:47:42 2018
  ...
  PERM_ALLOCATED_SIZE:         262144
  PERM_IN_USE_SIZE:            29997
  PERM_IN_USE_HIGH_WATER:      29997
  TEMP_ALLOCATED_SIZE:         131072
  TEMP_IN_USE_SIZE:            19146
  TEMP_IN_USE_HIGH_WATER:      22352
  ...
 
quit;
Disconnecting...
Done.
Return code from mysys5host.griddata3: 0
Output from mysys5host.griddata3:
 
Copyright (c) 1996, 2018, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=database1";
Connection successful: DSN=database1;...
 
monitor;
 
  TIME_OF_1ST_CONNECT:         Fri Aug  3 13:47:41 2018
  ...
  PERM_ALLOCATED_SIZE:         262144
  PERM_IN_USE_SIZE:            29916
  PERM_IN_USE_HIGH_WATER:      29932
  TEMP_ALLOCATED_SIZE:         131072
  TEMP_IN_USE_SIZE:            19613
  TEMP_IN_USE_HIGH_WATER:      22819
  ...
 
quit;
Disconnecting...
Done.
Return code from mysys6host.griddata4: 0
Output from mysys6host.griddata4:
 
Copyright (c) 1996, 2018, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=database1";
Connection successful: DSN=database1;...
 
monitor;
 
  TIME_OF_1ST_CONNECT:         Fri Aug  3 13:47:41 2018
  ...
  PERM_ALLOCATED_SIZE:         262144
  PERM_IN_USE_SIZE:            29981
  PERM_IN_USE_HIGH_WATER:      29981
  TEMP_ALLOCATED_SIZE:         131072
  TEMP_IN_USE_SIZE:            19344
  TEMP_IN_USE_HIGH_WATER:      22550
  ...
 
quit;
Disconnecting...
Done.
Return code from mysys3host.griddata1: 0
Output from mysys3host.griddata1:
 
Copyright (c) 1996, 2018, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=database1";
Connection successful: DSN=database1;...
 
monitor;
 
  TIME_OF_1ST_CONNECT:         Fri Aug  3 13:47:40 2018
  ...
  PERM_ALLOCATED_SIZE:         262144
  PERM_IN_USE_SIZE:            29965
  PERM_IN_USE_HIGH_WATER:      29965
  TEMP_ALLOCATED_SIZE:         131072
  TEMP_IN_USE_SIZE:            19281
  TEMP_IN_USE_HIGH_WATER:      22486
  ...
 
quit;
Disconnecting...
Done.

Notes

  • The command or script is run as the instance administrator on each instance, through passwordless SSH.

  • Environment variables (such as TIMESTEN_HOME, CLASSPATH, PATH, and LD_LIBRARY_PATH) are set appropriately for each instance.

  • The command returns 2000 if execution did not complete prior to the timeout.

  • During execution, stdout and stderr output is displayed as part of the stdout and stderr output from the instanceExec command. Because output is buffered, the output from different commands is not intermingled.

List Instances (instanceList)

The instanceList command lists information about instances in the specified version of the model. 

ttGridAdmin instanceList [-latest|-current|-version n]
                         [-type all|management|data]
                         [-install]

Options

The instanceList command has the options:

Option Description

-latest

Lists instances in the latest model—the model being modified and not yet applied to the grid. This is the default.

-current

Lists instances in the current model—the model most recently applied to the grid.

-version n

Lists instances in the specified version number of the model.

-type all|management|data

Specifies whether all instances (the default), only management instances, or only data instances are listed.

-install

Shows the installation object associated with each instance.

Examples

This example is for a grid with two hosts on each of two systems. On each system, one host has a management instance and one has a data instance. By default, data instances as well as management instances are listed in the latest model (in the process of being modified and not yet applied).

% ttGridAdmin instanceList
Host        Instance  Type Instance Home                        Port  CSPort MgmtPort Comment
----------- --------- ---- -----------------------------------  ----- ------ -------- -------
mysys1host  gridmgmt1 Mgmt /sw/tten/grid/ttinstances/gridmgmt1/ 10000  11000    3754
mysys2host  gridmgmt1 Mgmt /sw/tten/grid/ttinstances/gridmgmt1/ 10000  11000    3754
mysys3host  griddata1 Data /sw/tten/grid/ttinstances/griddata1/ 20000  21000
mysys4host  griddata2 Data /sw/tten/grid/ttinstances/griddata2/ 20000  21000

This example also shows the associated installation objects (the Comment column is omitted):

% ttGridAdmin -instanceList -install
Host        Instance  Installation  Type  Instance Home                       Port  CSPort MgmtPort
----------- --------- ------------- ----  ----------------------------------- ----- ------ -------- 
mysys1host  gridmgmt1 installation1 Mgmt /sw/tten/grid/ttinstances/gridmgmt1/ 10000  11000    3754
mysys2host  gridmgmt1 installation1 Mgmt /sw/tten/grid/ttinstances/gridmgmt1/ 10000  11000    3754
mysys3host  griddata1 installation1 Data /sw/tten/grid/ttinstances/griddata1/ 20000  21000
mysys4host  griddata2 installation1 Data /sw/tten/grid/ttinstances/griddata2/ 20000  21000

Modify an Instance (instanceModify)

The instanceModify command modifies an existing instance object in the model. 

ttGridAdmin instanceModify hostname[.instancename]
                           [-installation name]
                           [-mgmtPort n]
                           [-comment comment]

Options

The instanceModify command has the options:

Option Description

hostname[.instancename.]

The hostname is the name of the host where the instance is to be modified. The instancename is the name of the instance to be modified and is required only if there is more than one instance on the host.

-installation name

Associates the instance with a different installation on the host, specified by the name of the installation in the model.

-mgmtPort n

For management instances, a new port number that will be used for replication when management data on the active management instance is replicated. Changing this is allowed only if there ie exactly one management instance at the time the command is issued, but is relevant only if you plan to have two management instances.

-comment comment

Associates a comment with the instance object or modifies an existing comment. Put the comment in quotes if there are any spaces. The comment is stored and included in output of the instanceList command.

Examples

In this example, griddata1 is the only instance on the host. 

% ttGridAdmin instanceModify mysys3host -installation altinstall -comment 
Change_from_installcreate1
Instance griddata1 on Host mysys3host modified in Model

(Note that if you have a multi-word comment, you can use underscores instead of spaces to avoid having to put the comment in quotes.)

Notes

  • This command is most typically used to patch or upgrade your version of TimesTen by pointing to an installation of the desired release.

  • When instanceModify updates are applied by a subsequent modelApply command, the instance is not stopped and reconfigured at that time. Instead, the next time the instance is started, TimesTen Scaleout will detect that the instance configuration does not match the model, and will reconfigure it appropriately.

Display Status of Instances (instanceStatus)

The instanceStatus command displays information about the status of instances in the grid, in JSON format. 

ttGridAdmin instanceStatus [-type all|management|data]

Options

The instanceStatus command has the option:

Option Description

-type all|management|data

Specifies whether all instances (the default), only management instances, or only data instances are displayed.