-a

Specifies one or more application-specific esub or epsub executable files that you want LSF to associate with the job.

Categories

schedule

Synopsis

bsub -a "application_name [([argument[,argument...]])]..."

Description

The value of -a must correspond to the application name of an actual esub or epsub file. For example, to use bsub -a fluent, one or both of the esub.fluent or epsub.fluent files must exist in LSF_SERVERDIR.

For example, to submit a job that invokes the application-specific esub (or epsub) executables named esub.license (or epsub.license) and esub.fluent (or epsub.fluent), enter:
bsub -a "license fluent" my_job

The name of the application-specific esub or epsub program is passed to the parent esub. The parent esub program (LSF_SERVERDIR/mesub) handles job submission requirements of the application. Application-specific esub programs can specify their own job submission requirements. The value of -a is set in the LSB_SUB_ADDITIONAL environment variable.

mesub uses the method name license to invoke the esub named LSF_SERVERDIR/esub.license or the epsub named LSF_SERVERDIR/epsub.license, and the method name fluent to invoke the esub named LSF_SERVERDIR/esub.fluent or the epsub named LSF_SERVERDIR/epsub.fluent. Therefore, mesub is run twice: Before the job is submitted to mbatchd to run the esub scripts, and after the job is submitted to run the epsub scripts.

LSF first invokes the executable file named esub (without .application_name in the file name) if it exists in LSF_SERVERDIR, followed by any mandatory esub or epsub executable files that are defined using the parameter LSB_ESUB_METHOD in the lsf.conf file, and then any application-specific esub executable files (with .application_name in the file name) specified by -a. After the job is submitted, LSF invokes the executable file named epsub (without .application_name in the file name) if it exists in LSF_SERVERDIR, followed by any mandatory epsub executable files (as specified using the parameter LSB_ESUB_METHOD), and then any application-specific epsub executable files (with .application_name in the file name) specified by -a.

The name of the esub or epsub program must be a valid file name. It can contain only alphanumeric characters, underscore (_) and hyphen (-).

Restriction: If the value of -a corresponds to a value in LSB_ESUB_METHOD, this value must correspond to an actual esub or epsub file in LSF_SERVERDIR. For example, if fluent is defined in LSB_ESUB_METHOD, the esub.fluent or epsub.fluent file must exist in LSF_SERVERDIR to use bsub -a fluent.

If you have an esub or epsub that runs an interactive or X-window job and you have SSH enabled in lsf.conf, the communication between hosts is encrypted.

esub arguments provide flexibility for filtering and modifying job submissions by letting you specify options for esub executable files. epsub provides the flexibility to perform external logic using information about jobs that are just submitted, such as the assigned job ID and queue name.

The variables you define in the esub and epsub arguments can include environment variables and command output substitution.

Note: The same arguments that are passed to esub are also passed to epsub. You cannot pass different arguments to an esub file and an epsub file with the same application name.

Valid esub and epsub arguments can contain alphanumeric characters, spaces, special characters (`"\$!) and other characters (~@#%^&*()-=_+[]|{};':,./<>?). Special patterns like variables (for example, $PATH) and program output (for example, `ls` command output) in an esub or epsub argument will also be processed.

For example, if you use bsub -a “esub1 ($PATH, `ls`)” user_job, the first argument passed to esub1 would be the value of variable PATH, and the second argument passed to esub1 would be the output of command ls.

You can include a special character in an esub or epsub argument with an escape character or a pair of apostrophes (''). The usage may vary among different shells. You can specify an argument containing separators ('(', ')', ',') and space characters (' ').

You can also use an escape character (\) to specify arguments containing special characters, separators and space characters. For example:

bsub –a “application_name1(var1,var2 contain \(\)\,)” user_job

For fault tolerance, extra space characters are allowed between entities including esub/epsub, separators, and arguments. For example, the following is valid input:

bsub -a “ esub1 ( var1 , var2 ) ” user_job

The maximum length allowed for an esub/epsub argument is 1024 characters. The maximum number of arguments allowed for an esub/epsub is 128.

Jobs submitted with an esub (or epsub) will show all the esubs in bjobs -l output, first with the default and then user esubs.

Examples

  • To specify a single argument for a single esub/epsub executable file, use:

    bsub –a “application_name(var1)” user_job

  • To specify multiple arguments for a single esub/epsub executable file, use:

    bsub –a “application_name(var1,var2,...,varN)” user_job

  • To specify multiple arguments including a string argument for a single esub/epsub executable file, use:

    bsub –a “application_name(var1,var2 is a string,...,varN)” user_job

  • To specify arguments for multiple esub/epsub executable files, use:

    bsub –a “application_name1(var1,var2) application_name2(var1,var2)” user_job

  • To specify no argument to an esub/epsub executable file, use:

    bsub –a “application_name1” user_job