Knowledge Center         Contents    Previous  Next    Index  
Platform Computing Corp.

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

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, or ch. Command-level job starters have no effect on batch jobs, including interactive batch jobs run with bsub -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:

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_STARTER command [argument ...]" 

where command and argument are the command-line arguments you specify in lsrun, lsgrun, or ch.

Windows

RES runs the job starter, passing it your commands as arguments:

LSF_JOB_STARTER command [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 /p 

Queue-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

  1. 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.
  2. For example:

    Begin Queue
    .
    JOB_STARTER = xterm -e 
    .
    End Queue 
     

    All 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 "myjob arguments; sleep 10" 
For more information

See the Platform LSF Configuration Reference for information about the JOB_STARTER parameter in the lsb.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:

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:

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:

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
endif 

The 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