soamcontrol

The command to control applications and sessions.

Synopsis

soamcontrol subcommand [options]
soamcontrol -h
soamcontrol subcommand -h
soamcontrol -V

Description

Use the soamcontrol command with a subcommand to control applications, sessions, and tasks.

IBM® Spectrum Symphony Developer Edition does not verify the optional user name and password. IBM Spectrum Symphony Developer Edition users can control all sessions, applications, and tasks in their environment.

In grid, the user must have the appropriate permissions to control an application, task, or session, as follows:

  • Consumer administrators have permission to use this command to control applications, sessions, and tasks in the consumers they manage
  • Cluster administrators have permission to use this command to control applications, sessions, and tasks for all consumers
  • Consumer users can use this command only to control sessions they submit
-h
Prints command usage to stdout and exits.
-V
Prints product version to stdout and exits.

Subcommand synopsis

app enable application_name -u user_name] [-x password]
app disable application_name | all [-f] [-s] [-t timeout] [-u user_name] [-x password]
service restart application_name | all-u user_name] [-x password] [-t timeout] [-r host1[, host2, ...]]
service unblock application_name[:service_name] -r host1[, host2, ...] [-a] [-u user_name] [-x password]
session kill application_name [:session_ID[,session_ID]...] [-m comment] [-u user_name] [-x password]
session kill application_name [-t session_tag] [-m comment] [-u user_name] [-x password]
session suspend application_name[:session_ID[,session_ID]...] [-m comment] [-u user_name] [-x password]
session suspend application_name [-t session_tag] [-m comment] [-u user_name] [-x password]
session resume application_name [:session_ID[,session_ID]...] [-m comment] [-u user_name] [-x password]
session resume application_name [-t session_tag] [-m comment] [-u user_name] [-x password]
task kill application_name :session_ID:task_ID[,task_ID...] [-m comment] [-u user_name] [-x password]

app enable application_name [-u user_name] [-x password]

Enables an application for a consumer with no other enabled applications.

There can only be one enabled application per consumer.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.
-u user _name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only, the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you have already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password you specify here overrides the password you entered in soamlogon.

Enable sampleApp application

soamcontrol app enable sampleApp

app disable application_name | all [-f] [-s] [-t timeout] [-u user_name] [-x password]

Disables a specific application or with the all option, disables all applications to which the specified user has access.

When issued by a cluster administrator, can disable all applications under all consumers in the cluster.

When issued by a consumer administrator, can disable all applications under the consumer this administrator administers.

When an application that has running workload is disabled, all active sessions are immediately terminated (unless the -t option is used), and all system resources assigned to the application are released.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.
all
Disables all applications and kills all workload.
-f
Disables the application and kills application workload without warning if there is active workload for the application.
-s
Disables the application and saves recoverable application workload. Prompts for confirmation to disable the workload. Saved workload is recovered when the application is enabled again.

Note that if the client disconnected from the cluster because it exceeded the retry time limit or if the client was killed when the application was disabled, the recovered workload will wait for the client to reconnect and get task results even if abortSessionIfClientDisconnect is enabled in the sessionType section of the application profile. If you do not want the recovered workload, you must manually kill the sessions.

-t timeout
Specifies the maximum time to wait, in seconds, before the command disables applications. Valid values are any positive integer greater than zero. This duration allows for the system to wait for all active workload to complete before disabling the application. If not provided, the system disables the application immediately and terminates all submitted workload, and all system resources assigned to the application are released.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you have already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name you specify here overrides the user name you entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Disable all applications

Disable all applications to which the consumer administrator has access.
soamcontrol app disable all -u consumer_admin -x passwd

Disable application and shutdown workload

Disable the sampleApp application and shut down any existing workload.
soamcontrol app disable sampleApp -f

Disable application and shutdown workload

Wait for 60 seconds, to allow submitted workload to complete, before disabling the sampleApp application:
soamcontrol app disable sampleApp -f -t 60

service restart application_name | all [-u user_name] [-x password] [-t timeout] [-r host1[,host2,...]]

Restart SIMs and their service instances without stopping active workload and losing workload results. For scheduled tasks, SSM stops these tasks for the specified application and hosts, and after tasks results are received, restarts the applications.
Note: You cannot restart service instances enabled in global standby mode; terminate these standby service instances first, by running the egosh globalstandby kill command (see Terminating standby service instances for details) before running this soamcontrol service restart command.
application_name
Specifies the name of the application, or specify all for all applications. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.
-t timeout
Specifies the maximum time to wait, in seconds, before the command restarts SIMs and their service instances. Valid values are any positive integer greater than zero. This duration allows for running workload to complete before restarting services. After this timeout expires, task results can be lost. If timeout is not provided, no force restart timeout is set and services restart when workload finishes.
-r host
Specifies the name of one or more hosts to restart. If not provided, services will be restarted for all hosts for the application.

Restart all SIMs and their service instances for all applications on all hosts

soamcontrol service restart all

Restart all SIMs and their service instances for a specific application on all hosts

Restart all SIMs and their SIs for the sampleApp application.
soamcontrol service restart sampleApp

Restart all SIMs and their service instances for a specific application on a specific host

Restart all SIMs and their SIs for the sampleApp application on hostA.
soamcontrol service restart SampleApp -r hostA

service unblock application_name[:service_name] -r host1[,host2,...] [-a] [-u user_name] [-x password]

Unblocks the host for a service type of an application.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.
service_name
Specifies the name of the service that is blocked on the specified host. If the service name is not specified, the host will be unblocked for all service types of the application.
-r host
Specifies the name of one or more blocked hosts.
-a
Specifies to unblock the host for the application at the EGO level.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Unblock a host for a specific service of an application

soamcontrol service unblock SampleApp:SampleAppService -r hostA

session kill application_name [:session_ID[,session_ID]...] [-m comment] [-u user_name] [-x password]

Terminates all sessions of an application or terminates a specific session of an application. The session runtime data and its tasks (such as output data and current state) are no longer available. However, historical data can be retrieved through the soamview or the IBM Spectrum Symphony cluster management console if session and task history is saved.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.
session_ID
Specifies the IBM Spectrum Symphony-assigned ID of the session as reported by soamview session.
-m comment
Specifies a reason why this action was requested. The reason can comprise up to 64 alphanumeric or special characters, with the exception of control (Ctrl + key) and multi-byte characters. The description must be enclosed in double quotation marks (" ") if it contains spaces.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Kill all sessions

Kill all sessions of the sampleApp application.
soamcontrol session kill sampleApp

Kill specific sessions

Kill sessions 101 and 102 of the sampleApp application.
soamcontrol session kill sampleApp:101,102

session kill application_name [-t session_tag] [-m comment] [-u user_name] [-x password]

Terminates all sessions of an application or terminates sessions that match the specified session tag of an application. The session run-time data and its tasks (such as output data and current state) are no longer available. However, historical data can be retrieved through the soamview or the IBM Spectrum Symphony cluster management console if session and task history is saved.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.
-t session_tag
Specifies the string that is used for identification purposes to control the session.
-m comment
Specifies a reason why this action was requested. The reason can comprise up to 64 alphanumeric or special characters, with the exception of control (Ctrl + key) and multi-byte characters. The description must be enclosed in double quotation marks (" ") if it contains spaces.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Kill all sessions that match the session tag

Kill all sessions of the sampleApp application that share the myTag session tag.
soamcontrol session kill sampleApp -t myTag

session suspend application_name [:session_ID[,session_ID]...] [-m comment] [-u user_name] [-x password]

Suspends a session. When a session is suspended, running tasks are killed and rescheduled for rerun when the session is resumed. Pending tasks remain pending. CPU slots used by the session are freed.

Clients can continue to create sessions, send tasks, retrieve task output, and query session and task information.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.

If specified without one or more session IDs, all sessions of the application are suspended.

session_ID
Specifies the IBM Spectrum Symphony-assigned ID of the session as reported by soamview session.
-m comment
Specifies a reason why this action was requested. The reason can comprise up to 64 alphanumeric or special characters, with the exception of control (Ctrl + key) and multi-byte characters. The description must be enclosed in double quotation marks (" ") if it contains spaces.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Suspend all sessions

Suspend all sessions of the sampleApp application. 
soamcontrol session suspend sampleApp

Suspend specific sessions

Suspend sessions 101 and 102 of the sampleApp application, giving a reason for the suspension.
soamcontrol session suspend sampleApp:101,102 -m "network congestion"

session suspend application_name [-t session_tag] [-m comment] [-u user_name] [-x password]

Suspends all sessions of an application or suspends sessions that match the specified session tag of an application. When a session is suspended, running tasks are killed and rescheduled for rerun when the session is resumed. Pending tasks remain pending. CPU slots used by the session are freed.

Clients can continue to create sessions, send tasks, retrieve task output, and query session and task information.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.

If specified without one or more session IDs, all sessions of the application are suspended.

-t session_tag
Specifies the string that is used for identification purposes to control the session.
-m comment
Specifies a reason why this action was requested. The reason can comprise up to 64 alphanumeric or special characters, with the exception of control (Ctrl + key) and multi-byte characters. The description must be enclosed in double quotation marks (" ") if it contains spaces.
-u user _name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Suspend all sessions that match the session tag

Suspend all sessions of the sampleApp application that share the myTag session tag. 
soamcontrol session suspend sampleApp -t myTag -m "network congestion"

session resume application_name [:session_ID[,session_ID...]] [-m comment] [-u user_name] [-x password]

Resumes task processing for a specific suspended session or for multiple sessions.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.

If specified without one or more session IDs, all sessions of the application are resumed.

session_ID
Specifies the IBM Spectrum Symphony -assigned ID of the session as reported by soamview session.
-m comment
Specifies a reason why this action was requested. The reason can comprise up to 64 alphanumeric or special characters, with the exception of control (Ctrl + key) and multi-byte characters. The description must be enclosed in double quotation marks (" ") if it contains spaces.
-u user _name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Resume all sessions

Resume all sessions of the sampleApp application.

soamcontrol session resume sampleApp

Resume a specific session

Resume sessions 101 and 102 of the sampleApp application, giving a reason for the resumption.
soamcontrol session resume sampleApp:101,102 -m "network problem resolved"

session resume application_name [-t session_tag] [-m comment] [-u user_name] [-x password]

Resumes all sessions of an application or resumes sessions that match the specified session tag of an application.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.

If specified without one or more session IDs, all sessions of the application are resumed.

-t session_tag
Specifies the string that is used for identification purposes to control the session.
-m comment
Specifies a reason why this action was requested. The reason can comprise up to 64 alphanumeric or special characters, with the exception of control (Ctrl + key) and multi-byte characters. The description must be enclosed in double quotation marks (" ") if it contains spaces.
-u user _name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Resume sessions that match the session tag

Resume all sessions of the sampleApp application that match the myTag session tag.
soamcontrol session resume sampleApp -t myTag -m "network problem resolved"

task kill application_name:session_ID:task_ID[,task_ID...] [-m comment] [-u user_name] [-x password]

Kills one or more specific tasks in a running or pending session.

application_name
Specifies the name of the application. The application name is the same as it appears in the application profile. Enclose the application name in double quotation marks (" ") if it contains spaces. Precede the application name with two dashes (--) if it starts with a dash.
session_ID
Specifies the IBM Spectrum Symphony-assigned ID of the session as reported by soamview session.
task_ID
Specifies the IBM Spectrum Symphony-assigned ID of the task as reported by soamview task.
-m comment
Specifies a reason why this action was requested. The reason can comprise up to 64 alphanumeric or special characters, with the exception of control (Ctrl + key) and multi-byte characters. The description must be enclosed in double quotation marks (" ") if it contains spaces.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Kill specified tasks in a session

Kill tasks 201 and 202 of the sampleApp application in session 101.
task kill sampleApp:101:201,202 -m "tasks hanging"