symexec

The symexec command supports the running of remote execution tasks using the IBM® Spectrum Symphony infrastructure. An execution task is a child process executed by an IBM Spectrum Symphony service instance using a command line specified by an IBM Spectrum Symphony client.

Synopsis

symexec create [-a application_name] [-e env1=value1[,env2=value2,...]] [-p preexecution_command] [-q postexecution_command] [-u user_name] [-x password]
symexec send -s session_ID [-a application_name] [-e env1=value1[,env2 =value2,...] [-p preexecution_command] [-q postexecution_command] [-u user_name] [-x password] command
symexec fetch -s session_ID -n counter [-a application_name] [-t timeout_in_seconds_for_fetch] [-u user_name] [-x password]
symexec close -s session_ID [-a application_name] [-u user_name] [-x password]
symexec run [-a application_name] [-e env1=value1[,env2=value2,...]] [-p preexecution_command] [-q postexecution_command] [-t timeout_in_seconds_for_fetch] [-u user_name] [-x password] command
symexec -h| -V

Description

Use symexec as an IBM Spectrum Symphony client application to run executables, such as scripts, applications, or system calls. You cannot use symexec to run interactive graphical user interface programs. The symexec command requires an application and a service. The default, application is symexec732.
  • Use symexec create to create an execution session in which to run execution tasks. The session stays open until it is explicitly closed.
  • Use symexec send to send an execution task command in the execution session.
  • Use symexec fetch to retrieve the statuses of finished execution tasks in the execution session. The statuses are retrieved as return codes or exception description and error codes.
  • Use symexec close to close the execution session.
  • Use symexec run to create an execution session, run a command, retrieve the results and close the session.
Notes:
  1. To run an execution command on Windows, specify the full name including the file extension.
  2. Do not set the reclaimed grace period to zero seconds. This can be defined in the symexec application profile or symexec consumer's properties. When reclaim period is set to any value greater than zero, symexec successfully receives notifications, can abort child process groups, can run post commands, can stop service level commands, and can exit gracefully.
  3. Do not terminate the client (for example, by using Ctrl+C). This could result in loss of tasks. If interrupts are required, specify a short timeout for fetch value.
  4. If a symexec fetch command is in progress while a fetch or send command is issued for the same session from another command prompt window, the original fetch operation will abort and the session will detach from the original client
-h
Prints command usage to stdout and exits.
-V
Prints product version to stdout and exits.

Options

-a application=name
Specifies the name of the application to use. If you do not specify an application name, the application defaults to symexec732. If you specify an application name, it must match the application name in the corresponding application profile, and the application must be registered.
-e env=value
Sets the environment variables to be passed to the execution session. Specify as many environment variable/value pairs as required to define the environment.

To specify multiple environment variable/value pairs, separate the pairs with a comma.

-p preexecution_command
Specify a pre-execution command to run before running the executable command. If the pre-execution command is successful, the executable command is run. The command you specify must exist in the same location on every compute host on which it may run, or be accessible from the compute host. Specify an absolute path, or set the path in the PATH environment variable.

The pre-execution command context depends on command association. The create command is in context of session-level pre-execution; the send command is in context of task-level pre-executrion.

-q postexecution_command
Specify a post-execution command to run. The execution service ensures that if the pre-execution command completes successfully, the post-execution command will always be executed, even if errors occur in the user's command during the session. The command you specify must exist in the same location on every compute host on which it may run, or be accessible from the compute host. Specify an absolute path, or set the path in the PATH environment variable.

The post-execution command context depends on command association. The create command is in context of session-level pre-execution; the send command is in context of task-level pre-executrion.

-u user_name
Specify the user ID under which to run the execution session.

If you do not specify the -u and -x options when running the symexec command, you will be prompted for those user credentials.

-x password
Specify the password to authenticate the user ID.

If you do not specify the -u and -x options when running the symexec command, you will be prompted for those user credentials.

-s session_ID
Specifies the unique ID of the session to operate upon.
-n counter
Specifies the number of tasks for which to fetch results.

If there are less than n task results available to be retrieved, symexec fetch waits until it can fetch all n tasks, or until the value set for timeout_in_seconds_for_fetch is reached.

If another symexec send or symexec fetch command is issued for the same session ID, the existing symexec fetch client is terminated, because only one client connection can be made to the session at a time.

Note: Any task can only be fetched just once.
-t timeout_in_seconds_for_fetch
Specifies the number of seconds to wait for the session results.

If you do not specify a timeout, symexec waits indefinitely until all requested task outputs are received. If you specify 0 seconds, symexec returns immediately with or without the task output.

If the timeout expires and all of the results have still not been received, one of the following happens, depending on the subcommand for which the timeout is specified:
  • symexec fetch: Keeps the session open and continue to run the task.
  • symexec run: Closes the session and terminate the task.
command
Specifies the execution command to run. The executable you specify must exist in the same location on every compute host on which it may run, or be accessible from the compute host. Specify an absolute path, or set the path in the PATH environment variable.
Restriction: You cannot run a Windows internal command or a Linux® shell built-in command unless it is contained in a script.

Create an execution session to run a single command

symexec run -u user01 -x 12345 mycmd.exe

Creates an execution session using the default application symexec732, runs mycmd.exe, retrieves the results, and closes the session.

Create an execution session to run multiple commands

symexec create -u user01 -x 12345
symexec send -s 123 -u user01 -x 12345 mycmd.exe
symexec fetch -s 123 -n 1 -u user01 -x 12345
symexec send -s 123 -u user01 -x 12345 mycmd1.exe
  • Creates an execution session using the default application symexec732, and returns a session ID.
  • Sends mycmd.exe to the session.
  • Retrieves the results of the command.
  • Sends another command, mycmd1.exe, to the session. The session remains open to receive other commands.

Retrieving stdout and stderr from execution tasks

The results from an execution task can be in the form of an exit code with optional stdout and stderr data files from the execution task's command. To retrieve the stdout and stderr data from a completed execution task, you must change its command to run under a shell so the command can redirect the stdout and stderr data to files. The files can then be retrieved by either copying the file from the remote host (for example, with an FTP command) or by using a shared file system location.

The following examples demonstrate how to retrieve the stdout and stderr data from Windows and Linux hosts.
  • Windows:
    In this example, the command will take the output of the "dir c:\" command and place it in the dir_content.txt file. The command can be entered in the Start > Run field. The cmd /c opens a command shell and closes it after processing the string: 
    cmd /c dir c:\ > c:\temp\dir_content.txt
  • Linux:
    In this example, the command will take the output of the "ls /" command and place it in the root_content.txt file. The sh -c opens a command shell, which reads the commands from the string:
    sh -c 'ls / > /tmp/root_content.txt'