lstcsh

Load sharing tcsh for LSF

Synopsis

lstcsh [tcsh_options] [-L] [argument ...]

Description

The lstcsh command is an enhanced version of the tcsh command. The lstcsh command behaves exactly like tcsh, except that it includes a load sharing capability with remote job execution for LSF.

By default, an lstcsh script is executed as a normal tcsh script with load sharing disabled.

If a command is eligible for remote execution, LSF selects a suitable host, and sends the command to that host. The selected host is typically a powerful or lightly loaded host that can run the command correctly.

You can restrict who can use @ for host redirection in the lstcsh command with the parameter LSF_SHELL_AT_USERS in the lsf.conf file.

Remote Hosts

The lstcsh command provides a high degree of network transparency. Commands that are run on remote hosts behave the same as they do on the local host. The remote execution environment mirrors the local environment as closely as possible by using the same values for environment variables, terminal setup, current working directory, file creation mask, and other properties. Each modification to the local set of environment variables is automatically reflected on remote hosts.

Shell variables, nice values, and resource limits are not automatically propagated to remote hosts.

Job Control

Job control in the lstcsh command is the same as in the tcsh command except for remote background jobs. The lstcsh command numbers background jobs separately for each of the hosts that are used to execute them. The output of the built-in command job lists background jobs together with their execution hosts.

To bring a remote background job to the foreground, the host name must be specified together with an at sign (@), as in the following example:
fg %2 @hostA
Similarly, the host name must be specified when you kill a remote job. For example:
kill %2 @hostA

Options

tcsh_options
The lstcsh command accepts all the options that are used by the tcsh command. See the tcsh man page for the meaning of specific options.
-L
Runs a script with load sharing enabled.
Run an lstcsh script with load sharing enabled the following ways:
  • Run the script with the -L option.
  • Use the built-in command source to run the script.
  • Insert #!/local/bin/lstcsh -L as the first line of the script (assuming you install lstcsh in /local/bin).

Using @ or thelsmode command in a script does not enable load sharing if the script was not run by using one of these three ways.

Usage

In addition to the built-in commands in the tcsh command, the lstcsh command provides the following built-in commands:

lsmode [on | off] [local | remote] [@] [v | -v] [e | -e] [t | -t] [connect [host_name ...]] [lsrtasks [lsrtasks_options]] [lsltasks [lsltasks_options]] [jobs]

on | off
Turns load sharing on or off. When off, you can specify @ to send a command to a remote host.
local | remote
Sets operation mode of lstcsh.

The mode of operation of the lstcsh command (local or remote) determines how the lstcsh command handles tasks that are not present in the remote task list nor in the local task list.

The default mode is local.
local
Local operation mode.

In local mode, a command is eligible for remote execution only if all the specified tasks are present in the remote task list in the user’s tasks file $HOME/.lsftask, or if @ is specified on the command to force specified tasks to be eligible for remote execution.

Tasks in the local task list must be ran locally.

The local mode of operation is conservative, and can fail to take advantage of the performance benefits and load balancing advantages of LSF.

remote
Remote operation mode.

In this mode, a command is considered eligible for remote execution only if none of the specified tasks are present in the local task list in the user’s tasks file $HOME/.lsftask.

Tasks in the remote list can be run remotely.

The remote mode of operation is aggressive, and promotes extensive use of LSF.

@
Specify @ to explicitly specify the eligibility of a command for remote execution.

The @ can be anywhere in the command line except in the first position, which is used to set the value of shell variables.

Use @ one of the following ways:
@
Specify @ followed by nothing to indicate that the command is eligible for remote execution.
@ host_name
Specify @ followed by a host name to force the command to be run on that host.

Host names and the reserved word local following @ can all be abbreviated if they do not cause ambiguity.

@ local
Specify @ followed by the reserved word local to force the command to run on the local host.
@ /res_req
Specify @ followed by a slash (/) and a resource requirement string to indicate that the command is eligible for remote execution, and that the specified resource requirements must be used instead of the requirements in the remote task list.

When you specify resource requirements after the @, you can use / only if the first requirement characters you specified are the first characters of a host name.

e | -e
Turns on verbose eligibility mode (e) or off (-e).

When eligibility verbose mode is on, the lstcsh command shows whether the command is eligible for remote execution, and displays the resource requirement that is used if the command is eligible.

The default is off.

v | -v
Turns on task placement verbose mode (v) or off (-v). When verbose mode is on, the lstcsh command displays the name of the host on which the command runs if the command does not run on the local host.

The default is on.

t | -t
Turns on wall clock timing (t) or off (-t).

When timing is on, the actual response time of the command is displayed. The response time is the total elapsed time in seconds from the time you submit the command to the time the prompt comes back.

This time includes all remote execution usage. The csh time built-in does not include the remote execution usage.

Wall clock timing is an impartial way of comparing the response time of jobs that are submitted locally or remotely because all the load sharing usage is included in the displayed elapsed time.

The default is off.

connect [host_name ...]
Establishes connections with specified remote hosts. If no hosts are specified, lists all the remote hosts to which an lstcsh connection was established.

A plus sign (+) with a remote host indicates that a server-shell was also started on it.

lsrtasks [+ task_name[/res_req ...] | - task_name[/res_req ...]]
Displays or update a user’s remote task list in the user’s task list $HOME/.lsftask.

The lsrtasks command under the lstcsh command has the same function as the external command lsrtasks, except that the modified remote task list takes effect immediately for the current lstcsh session.

See the lsrtasks command for more details.

lsltasks [+ task_name ... | - task_name ...]

Displays or update a user’s local task list in the user’s task list $HOME/.lsftask.

The lsltasks command under the lstcsh command has the same function as the external command lsltasks, except that the modified local task list takes effect immediately for the current lstcsh session.

See the lsltasks command for more details.

jobs
Lists background jobs together with the execution hosts to give you more control over your background jobs.

Files

The lstcsh command uses three optional configuration files:
  • .shrc is used by lstcsh alone.
  • .hostrc is used by lstcsh alone.
  • .lsftask determines general task eligibility.
~/.shrc
Use this file when you want an execution environment on remote hosts that is different from the environment on the local host. This file is sourced automatically on a remote host when a connection is established. For example, if the remote host is of different type, you might need to run a version of the executable file for that particular host type. It might be necessary to set a different path on the remote host.
~/.hostrc
Use this file to indicate a list of host names to which the user wants to be connected (asynchronously in the background) at lstcsh startup time. This file saves the time that is spent in establishing the connections dynamically during execution of shell commands. After a connection is set up, you can run further remote commands on those connected hosts with little processing load.
~/.lsftask
Use this file to specify lists of remote and local tasks that you want to be added to the respective system default lists. Each line of this file is of the form task_name/res_req, where task_name is the name of a task, and res_req is a string that specifies the resource requirements of the task. If res_req is not specified, the command runs on hosts of the same type as the local host.

Limitations

Type ahead for the next command is discarded when a job is running in the foreground on a remote host.

You cannot provide input data to load sharing shell scripts (that is, shell scripts with load-shared content).

The lstcsh command is fully compatible with tcsh version 6.03 7-bit mode. Any feature that is not included in tcsh 6.03 is not supported.

See also

csh, tcsh, lsrtasks, lsltasks, lseligible, lsinfo, lsload