Details of a job

When you double-click a job icon, the Edit Job dialog is displayed. You use this dialog to specify any information that is required to define the job itself, such as the command it runs, and to specify any requirements that the job has, such as resources it needs to run.

The General tab

Name the job

Every job in a flow definition requires a unique name—it cannot be the same name as any other work item within the flow. The Flow Editor assigns a unique name to each job when you draw it on the workspace, so you are not required to change the name. However, if you want to change the name, you can.

In the Name field, specify a unique name using alphanumeric characters, periods (.), underscores (_) or dashes (-). You cannot use a colon (:), semicolon (;) or pound sign (#) in a job name.

Specify the command the job runs

The purpose of a job is to run a command, so a command name is mandatory. In the Command to run field, specify the name of the command this job runs, and any arguments required by the command, ensuring the syntax of the command is correct, or specify the script to run. Because the job will run under your user ID, ensure the path to the script is specified in your path environment variable, or specify the full path to the script.

Note: On Windows, if you specify a dependency on a job with the -w option to the bsub command, ensure you use single quotes (') if the job name contains special characters. For example, if your command is sleep 1 and you want to specify a dependency on job with the name a:b, then specify: -w "done('a:b')" sleep 1

If running this command or script requires access to a file or application, ensure the files are in a shared location that is accessible to the Process Manager Server. If applicable, specify any files that need to be transferred to where the job will run on the File Transfer tab.

If running this command requires access to specific resources, ensure you specify the appropriate resource requirements on the Resources tab.

Specify a login shell to initialize the execution environment

If the execution environment needs to be initialized using a specific login shell, in the Login shell to use field, select the login shell to be used from the list provided. This is not necessarily the shell under which the job runs.

The value specified for the login shell must be the absolute path to the login shell.

Run the job as part of a project

If you are using project codes to collect accounting information, and you want to associate this job with a project, in the Part of project field, select or specify the name of the project.

Specify a job working directory

Specify the directory where the job should run. Use an absolute path rather than a relative path. The working directory is also the job's submission directory(the directory from which the job is submitted). When no working directory is specified, the default working directory is used (this is the user's home directory, for example, C:\Documents and Settings\user_name on Windows or /home/user_name/ on Unix). When working directory does not exist, then the working directory used is %LSF_TOP%\tmp.

Submit the job with environment variables

You can submit a job that has environment variables that are used when the job runs. Environment variables can only contain alphanumeric characters, underscores, and user variable definitions. No semicolons can be part of the name or value.

User variables can be used in the environment variable name or value. A user variable definition must be in the form #{user_variable_name} and must be defined.

To add an environment variable, click New and then fill in the environment variable name and value, and click OK.

To modify an environment variable, select the one you want to modify and click Edit.

To remove an environment variable, select the one you want to remove and click Remove.

Specify non-zero success exit codes

Specify which numbers in addition to 0 represent success for the job. Specify a space-separated list of exit codes from 1 to 255.

Specify input, output and error files

You can use standard input, output and error files when submitting a job.

To get the standard input for the job from a file, in the Input file field, specify an absolute path to the file or a path relative to the current working directory.

To append the standard output of the job to a file, in the Output file field, specify a path to the file. If the current working directory is not accessible to the execution host, the standard output file is written to /tmp/.

To append the standard error output of the job to a file, in the Error file field, specify a path to the file. If the current working directory is not accessible to the execution host, the standard error output file is written to /tmp/.

Notify a user when the job …

You can instruct the system to send an email to you or another user when the job ends, when it starts, or once when it starts, and again when it ends. By default, you will not receive an email, except when the flow completes. To specify an email notification, check the notification box, and in the Notify when job field, select when you want the email sent. Then in the Email address field, specify the email address you want to notify.

Run the job under another user name

If you have administrator authority, you can specify a different user name under which to run the job. In the User name field, specify the user ID under which to run the job.

The Submit tab

Submit the job to a queue

Job queues represent different job scheduling and control policies. All jobs submitted to the same queue share the same scheduling and control policy. Process Manager administrators configure queues to control resource access by different users and application types. You can select the queues that best fit the job.

If you want to submit your job to a particular queue, in the Submit to queue(s) field, select or specify the queue name. If you want to specify a list of queues, specify the queue names separated by a space.

When you specify a list of queues, the most appropriate queue in the list is selected, based on any limitations or resource requirements you specify, and the job submitted to that queue.

This field is optional. If you do not specify a queue name, the configured default queue is used.

Application Profile

Use application profiles to map common execution requirements to application-specific job containers. For example, you can define different job types according to the properties of the applications that you use; your FLUENT jobs can have different execution requirements from your CATIA jobs, but they can all be submitted to the same queue.

In the Application Profile drop-down list, select an Application Profile name. The drop-down lists all the Application Profile names that are configured in LSF®.

Service Level Agreement

Goal-oriented Service Level Agreement (SLA) scheduling policies help you configure your workload so that your jobs are completed on time and reduce the risk of missed deadlines. They enable you to focus on the "what and when" of your projects, not the low-level details of "how" resources need to be allocated to satisfy various workloads.

In the Service level agreement drop-down list, select a goal. The drop-down lists all the SLAs that are configured in LSF.

Submit the job on hold

If you are creating a flow definition that contains a job whose definition you want to include in the flow, but you do not yet want the job to run for multiple iterations of this flow, you can submit the job on hold. At a later time, you can edit the flow definition, deselect this option, and resubmit the flow. At that time, the job will run as part of the flow.

You put a job on hold when you want to stop a flow at a specific point so that you can fix problems.

When you put a job in the flow on hold:

The job receives the status On Hold. The status of the flow is not affected.
The flow pauses at that specific job.
Only the branch of the flow that contains the job that is On Hold pauses. Other branches of the flow continue to run.

In the Flow Manager, when you look at a job that has been submitted on hold, the job is grayed out.

To submit a job on hold, check On hold.

For more details, see Stop a flow at a specific point by putting a job on hold.

The Processing tab

Run on a specific host

When you define a job, you can specify a host or series of hosts on which the job is to be run. If you specify a single host name, you force your job to wait until that host is available before it can run. Click Run on host(s), and select or specify the hosts on which to run this job.

Run with exclusive use of host

When you define a job, you can specify that the job must have exclusive use of the host while running—no other LSF jobs can run on that host at the same time. Check Must have exclusive use of host. The job is dispatched to a host that has no other jobs running, and no other jobs are dispatched to that host until this job is finished.

Rerun on another host if this one becomes unavailable

When you define a job, you can specify that if the host the job is running on becomes unavailable, the job should be dispatched to another host. Under the default behavior, the job exits, unless your Process Manager administrator specified automatic rerun at the queue level. Check Rerun if host becomes unavailable.

Run on the same host as another job

When you define a job, you can specify to run it on the same host that another job runs on. This is useful when a job generates a large amount of data—you do not need to transfer the data to run the next job. Click Same host as: and select the job on whose host this job should run. The other job must have at least started to run when this job is submitted, so the Process Manager can determine the correct host.

Specify number of processors for parallel jobs

If you are running a parallel job, you can specify a minimum and maximum number of processors that can be used to run the job. The maximum number is optional—if you specify only a minimum number, that is the number of processors used.

In the Minimum field, specify the minimum number of processors required to run the job. When this number of processors is available, and all of its other dependencies are met, the job can be dispatched.

Assign the job a priority

You can assign your jobs a priority, which allows you to order your jobs in a queue.

In the Priority field, specify a number from 1 to the maximum user priority value allowed at your site. See your Process Manager administrator for this value.

Run a command before running the job

You can run a command on the execution host prior to running the job. Typically, you use this to set up the execution environment.

In the Run command field, specify the command to be run on the execution host before running the actual job. If the command runs successfully, the job can run. Otherwise the command and job are rescheduled. Be sure the command is capable of being run multiple times on the target host.

Assign the job to a fairshare group

You can assign the job to a fairshare group. You must be a member of the group you specify.

In the Associate job with user group field, specify the name of the group.

The Resources tab

Specify resources required to run the job

You can specify a string that defines the resource requirements for a job. There are many types of resources you can specify. For complete information on specifying resource requirements, see the Administering IBM Spectrum LSF. However, some typical resource requirements are illustrated here. Some of the more common resource requirements are:

I want to run the job on a particular type of host
The job requires a specific number of software licenses
The job requires a certain amount of swap space and memory available

You can use user variables when specifying resource requirements.

Run on host type

The following example specifies that the job must be run on a Solaris 7, 32-bit host:

select[type==sol732]

Float software licenses

The following example specifies that the job requires 3 Verilog licenses. The rusage statement reserves the licenses for 10 minutes, which gives the job time to check out the licenses:

select[verilog==3] rusage[verilog=3:duration=10]

In the above example, verilog must first be defined as a shared resource in LSF.

Swap space and memory

The following example specifies that the job requires at least 50 MB of swap space and more than 500 MB of memory to run:

select[swp>=50 && mem>500]

The Limits tab

Specify host limits

You can specify criteria that ensure that the job is run on a particular host, or specific model of host. You can also limit the normalized CPU hours and minutes a job can use, or the number of hours and minutes a job can run. If the job exceeds these limits, it is killed automatically.

You can specify a host name or model in the Host name or model field.

To limit the job’s usage of CPU time, in the Maximum CPU time fields, specify the number of hours and minutes the job can use before it should be killed.

To limit the job’s run time, in the Maximum run time fields, specify the number of hours and minutes the job can run before it should be killed.

Specify job limitations

You can specify job limits, that restrict the following:

The file size per job process, in kilobytes
The core file size, in kilobytes
The memory size per job process, in kilobytes
The data size per job process, in kilobytes
The stack size per job process, in kilobytes

The File Transfer tab

You use this tab to transfer required files to the host where the job runs, and to transfer output files after the job has completed. You can transfer multiple files, and perform any or all of the operations available on this tab. Simply create a list of each required file transfer in the Expression(s) field.

Transfer a local file

If the job you are defining requires one or more applications or data files to run, and those files do not exist on the host on which the job runs, you need to transfer the files to the host when the job is dispatched.

Procedure

In the Local path including name field, specify the full path name of the file to be transferred.
If the location on the host where the job will run is different from the local path, in the File on execution host field, specify the full path where the file should be located when the job runs.
Select Copy file to remote host before running job.
Click Add to add this operation to the list of operations to perform.
Repeat as required.

Transfer an output file locally after the job runs

If the job you are defining produces output files that must be transferred to another location after the job completes, you need to copy the output files locally after the job runs.

Procedure

In the Local path including name field, specify the full path name where the output file is to be stored locally.
In the File on execution host field, specify the full path where the output file will be located when the job completes.
Select Copy file to local location after running job.
Click Add to add this operation to the list of operations to perform.
Repeat as required.

Append output to a local file after the job runs

If the job you are defining produces output files that must be transferred to another location after the job completes, and you want the output appended to a file that already exists, do the following:

Procedure

In the Local path including name field, specify the full path name where the output file is to be appended.
In the File on execution host field, specify the full path where the output file will be located when the job completes.
Select Append file to local location after running job.
Click Add to add this operation to the list of operations to perform.
Repeat as required.

The Advanced tab

You use this tab to specify additional bsub submission options that are not available from the Definition dialog, and to select jobs upon which this job depends.

Other Options

You can specify additional bsub submission options for a job.

This allows you to use options that are not available from the job definition dialog. The options you specify are added to the bsub command when you submit the job or job array.

You can also specify user variables in the Other Options field.

Note:

The following options are not supported in the Other Options field: -I, -Ip, -Is for interactive jobs, -K for submitting a job and waiting for it to complete, and -e and -o as these options are available in the General tab for error and output files.

Example: Specify License Scheduler options:

For example, if you use the esub feature and you want to display accounting statistics for jobs belonging to specific License Scheduler projects, specify in the Other Options field:

-a myesubapp -Lp mylsproject
Example: Specify complex job dependencies

If you have complex dependencies between jobs, you can use the Other Options field with the built-in user variable JS_FLOW_FULL_NAME.

Note that you are limited to what the LSF bsub -w option supports. For more details, refer to the LSF Command Reference.
- To specify jobB depends on the completion of jobA, regardless of its exit code:
  
  In jobB’s job definition dialog, Advanced tab, Other Options field, specify:
```
-w "ended(#{JS_FLOW_FULL_NAME}:jobA)"
```
  In this example, JS_FLOW_FULL_NAME is the full name of the subflow containing jobA and jobB.
- To specify jobB depends on a combination of dependencies, specify in Other Options:
  
  -w "ended(#{JS_FLOW_FULL_NAME}:JobA) && done(#{JS_FLOW_FULL_NAME}:JobC)"
- To specify dependencies for jobs in flow array elements:
  
  A job in a flow array element has a name in the format "11:usr1:F1:FA(1):J1".
  
  Make sure you single quote the name. For example:
```
-w "exit('11:usr1:F1:FA(1):J1', > 2)"
```
  Using the JS_FLOW_FULL_NAME variable:
```
-w "exit('#{JS_FLOW_FULL_NAME}(#{JS_FLOW_INDEX}):J1', > 2)"
```

Pre-submit

Select jobs upon the current job depends.

Only LSF jobs, job arrays, job scripts, job array scripts, and template jobs can be pre-submitted.
Only jobs, job scripts, job arrays, job array scripts, and template jobs can be preceding jobs to the dependent job to be pre-submitted.
The jobs to be pre-submitted must be direct links. They cannot be more than one link away.
The dependencies of all predecessors must be logically connected with AND.
In Flow Editor, the Event type in the Job Event Definition for the preceding jobs to the other job must be set to Starts or Is Submitted.
If you specify dependent jobs to be pre-submitted, and the condition is never met, it is possible for the flow to be “stuck”. To handle this, define an overrun exception handler to kill the last job if it runs or pends for more than a certain period of time.

The Exception Handling tab

You use this tab to specify what action to take if a specific exception occurs while running this job or job array.

Exceptions and applicable handlers

In a...	If this exception occurs...	You can use this handler...
Job	Overrun	Kill
	Underrun	Rerun
	Specified exit code	Rerun
Job array	Overrun	Kill
	Underrun	Rerun
	Sum of exit codes	Rerun
	Number of unsuccessful jobs	Kill

The Description tab

In the input field, add any descriptive text that may be used for managing this job or job array within the flow. For example, if this job requires special instructions for operations staff, place those instructions here.