symexec

Symexec supports the running of remote execution tasks using the Symphony infrastructure. An execution task is a child process executed by a Symphony service instance using a command line specified by a 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 a Symphony client application to run executables, such as scripts, applications, or system calls. You cannot use symexec to run interactive graphical user interface programs. symexec requires an application and a service. The default, out-of-box application is symexec5.1.
  • 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.

To run an execution conmand on Windows, specify the full name including the file extension.

Note:

It is recommended that you do not terminate the client (for example, using Ctrl + C). This could result in loss of tasks. If interrupts are required, specify a short timeout for fetch value.

Important:

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 symexec5.1. 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, as follows:


Command

Pre-execution command context

create

session level

send

task level


-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, as follows:


Command

Post-execution command context

create

session level

send

task level


-u user_name

Specify the user ID under which to run the execution session.

-x password

Specify the password to authenticate the user ID.

-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 the timeout is specified for:

  • symexec fetch

    Keep the session open and continue to run the task.

  • symexec run

    Close 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 UNIX 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 symexec5.1, 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 symexec5.1, and returns a session ID

  • Sends mycmd.exe to the session

  • Retrieve 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 file(s). The file(s) 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 followingexamples 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 textbox. 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’