Knowledge Center Contents Previous Next Index |
Job Starters
A
job starter
is a specified shell script or executable program that sets up the environment for a job and then runs the job. The job starter and the job share the same environment. This chapter discusses two ways of running job starters in LSF and how to set up and use them.Contents
- About Job Starters
- Command-Level Job Starters
- Queue-Level Job Starters
- Controlling Execution Environment Using Job Starters
About Job Starters
Some jobs have to run in a particular environment, or require some type of setup to be performed before they run. In a shell environment, job setup is often written into a wrapper shell script file that itself contains a call to start the desired job.
A job starter is a specified wrapper script or executable program that typically performs environment setup for the job, then calls the job itself, which inherits the execution environment created by the job starter. LSF controls the job starter process, rather than the job. One typical use of a job starter is to customize LSF for use with specific application environments, such as Alias Renderer or IBM Rational ClearCase.
Two ways to run job starters
You run job starters two ways in LSF. You can accomplish similar things with either job starter, but their functional details are slightly different.
Command-level
Are user-defined. They run interactive jobs submitted using
lsrun
,lsgrun
, orch
. Command-level job starters have no effect on batch jobs, including interactive batch jobs run withbsub -I
.Use the LSF_JOB_STARTER environment variable to specify a job starter for interactive jobs. See Controlling Execution Environment Using Job Starters for detailed information.
Queue-level
Defined by the LSF administrator, and run batch jobs submitted to a queue defined with the JOB_STARTER parameter set. Use
bsub
to submit jobs to queues with job-level job starters.A queue-level job starter is configured in the queue definition in
lsb.queues
. See Queue-Level Job Starters for detailed information.Pre-execution commands are not job starters
A job starter differs from a pre-execution command. A pre-execution command must run successfully and exit before the LSF job starts. It can signal LSF to dispatch the job, but because the pre-execution command is an unrelated process, it does not control the job or affect the execution environment of the job. A job starter, however, is the process that LSF controls. It is responsible for invoking LSF and controls the execution environment of the job.
See Chapter 38, "Pre-Execution and Post-Execution Commands" for more information.
Examples
The following are some examples of job starters:
- In UNIX, a job starter defined as
/bin/ksh -c
causes jobs to be run under a Korn shell environment.- In Windows, a job starter defined as
C:\cmd.exe /C
causes jobs to be run under a DOS shell environment.
note:
For job starters that execute on a Windows Server 2003, x64 Edition platform, users must have "Read" and "Execute" privileges forcmd.exe
.- Setting the JOB_STARTER parameter in
lsb.queues
to$USER_STARTER
enables users to define their own job starters by defining the environment variable USER_STARTER.- Setting a job starter to
make clean
causes the commandmake clean
to be run before the user job.Command-Level Job Starters
A command-level job starter allows you to specify an executable file that does any necessary setup for the job and runs the job when the setup is complete. You can select an existing command to be a job starter, or you can create a script containing a desired set of commands to serve as a job starter.
This section describes how to set up and use a command-level job starter to run interactive jobs.
Command-level job starters have no effect on batch jobs, including interactive batch jobs. See Chapter 42, "Interactive Jobs with bsub" for information on interactive batch jobs.
A job starter can also be defined at the queue level using the JOB_STARTER parameter. Only the LSF administrator can configure queue-level job starters. See Queue-Level Job Starters for more information.
LSF_JOB_STARTER environment variable
Use the LSF_JOB_STARTER environment variable to specify a command or script that is the job starter for the interactive job. When the environment variable LSF_JOB_STARTER is defined, RES invokes the job starter rather than running the job itself, and passes the job to the job starter as a command-line argument.
Using command-level job starters
UNIX
The job starter is invoked from within a Bourne shell, making the command-line equivalent:
/bin/sh -c "$LSF_JOB_STARTERcommand
[argument
...]"where
command
andargument
are the command-line arguments you specify inlsrun
,lsgrun
, orch
.Windows
RES runs the job starter, passing it your commands as arguments:
LSF_JOB_STARTERcommand
[argument
...]Examples
UNIX
If you define the LSF_JOB_STARTER environment variable using the following C-shell command:
%setenv LSF_JOB_STARTER "/bin/sh -c"
Then you run a simple C-shell job:
%
lsrun "'a.out; hostname'"
The command that actually runs is:
/bin/sh -c "/bin/sh -c 'a.out hostname'"The job starter can be a shell script. In the following example, the LSF_JOB_STARTER environment variable is set to the Bourne shell script named
job_starter
:$
LSF_JOB_STARTER=/usr/local/job_starter
The
job_starter
script contains the following:#!/bin/sh set term = xterm eval "$*"Windows
If you define the LSF_JOB_STARTER environment variable as follows:
set LSF_JOB_STARTER=C:\cmd.exe /C
Then you run a simple DOS shell job:
C:\>
lsrun dir /p
The command that actually runs is:
C:\cmd.exe /C dir /pQueue-Level Job Starters
LSF administrators can define a job starter for an individual queue to create a specific environment for jobs to run in. A queue-level job starter specifies an executable that performs any necessary setup, and then runs the job when the setup is complete. The JOB_STARTER parameter in
lsb.queues
specifies the command or script that is the job starter for the queue.This section describes how to set up and use a queue-level job starter.
Queue-level job starters have no effect on interactive jobs, unless the interactive job is submitted to a queue as an interactive batch job. See Chapter 42, "Interactive Jobs with bsub" for information on interactive batch jobs.
LSF users can also select an existing command or script to be a job starter for their interactive jobs using the LSF_JOB_STARTER environment variable. See Command-Level Job Starters for more information.
Configure a queue-level job starter
- Use the JOB_STARTER parameter in
lsb.queues
to specify a queue-level job starter in the queue definition. All jobs submitted to this queue are run using the job starter. The jobs are called by the specified job starter process rather than initiated by the batch daemon process.For example:
Begin Queue . JOB_STARTER = xterm -e . End QueueAll jobs submitted to this queue are run under an
xterm
terminal emulator.JOB_STARTER parameter (lsb.queues)
The JOB_STARTER parameter in the queue definition (
lsb.queues
) has the following format:
JOB_STARTER=
starter
[starter
] ["%USRCMD"
] [starter
]The string
starter
is the command or script that is used to start the job. It can be any executable that can accept a job as an input argument. Optionally, additional strings can be specified.When starting a job, LSF runs the JOB_STARTER command, and passes the shell script containing the job commands as the argument to the job starter. The job starter is expected to do some processing and then run the shell script containing the job commands. The command is run under
/bin/sh -c
and can contain any valid Bourne shell syntax.%USRCMD string
The special string
%USRCMD
indicates the position of the job starter command in the job command line. By default, the user commands run after the job starter, so the%USRCMD
string is not usually required. For example, these two job starters both give the same results:JOB_STARTER = /bin/csh -c JOB_STARTER = /bin/csh -c "%USRCMD"You must enclose the
%USRCMD
string in quotes. The%USRCMD
string can be followed by additional commands. For example:JOB_STARTER = /bin/csh -c "%USRCMD;sleep 10"If a user submits the following job to the queue with this job starter:
bsub myjob arguments
the command that actually runs is:
/bin/csh -c "myjobarguments
; sleep 10"For more information
See the
Platform LSF Configuration Reference
for information about the JOB_STARTER parameter in thelsb.queues
file.Controlling Execution Environment Using Job Starters
In some cases, using
bsub -L
does not result in correct environment settings on the execution host. LSF provides the following two job starters:
preservestarter
- preserves the default environment of the execution host. It does not include any submission host settings.augmentstarter
- augments the default user environment of the execution host by adding settings from the submission host that are not already defined on the execution host
bsub -L
cannot be used for a Windows execution host.Where the job starter executables are located
By default, the job starter executables are installed in LSF_BINDIR. If you prefer to store them elsewhere, make sure they are in a directory that is included in the default PATH on the execution host.
For example:
- On Windows, put the job starter under %WINDIR%.
- On UNIX, put the job starter under
$HOME/bin
.Source code for the job starters
The source code for the job starters is installed in
LSF_MISC/examples
.Adding to the initial login environment
By default, the
preservestarter
job starter preserves the environment that RES establishes on the execution host, and establishes an initial login environment for the user with the following variables from the user's login environment on the execution host:
- HOME
- USER
- SHELL
- LOGNAME
Any additional environment variables that exist in the user's login environment on the submission host must be added to the job starter source code.
Example
A user's
.login
script on the submission host contains the following setting:if ($TERM != "xterm") then set TERM=`tset - -Q -m 'switch:?vt100' .... else stty -tabs endifThe TERM environment variable must also be included in the environment on the execution host for login to succeed. If it is missing in the job starter, the login fails, the job starter may fail as well. If the job starter can continue with only the initial environment settings, the job may execute correctly, but this is not likely.
Platform Computing Inc.
www.platform.com |
Knowledge Center Contents Previous Next Index |