ssched

Submit tasks through the IBM® Spectrum LSF Session Scheduler.

Synopsis

ssched [options] command

ssched [options] -tasks task_definition_file

ssched [options] -tasks task_definition_file command

ssched [-h | -V]

Description

Options can be specified on the ssched command line or on a line in a task definition file. If the option is specified on the command line, it applies to all tasks, whether they are specified on the command line or in a file. Options that are specified in a file apply only to the command on that line. Options in the task definition file override the same option that is specified on the command line.

ssched exit codes

0: All tasks completed normally.

1: An unspecified error occurred.

3: All tasks completed, but some tasks have a nonzero exit code.

4: Error parsing ssched command line parameters or tasks definition file. No tasks were run.

5: Exceeded the limit that is specified by the SSCHED_MAX_TASKS parameter.

Task definition file format

The task definition file is an ASCII file. Each line represents one task, or an array of tasks. Each line has the following format:

[task_options] command [arguments]

Options

-1 | -2 | -3: Enables increasing amounts of debug output.
-C: Check all parameters and the task definition file. Exit immediately after the check is complete. An exit code of 0 indicates that no errors were found. Any nonzero exit code indicates an error. The ssched -C command can be run outside of LSF.
-p: Do not delete the temporary working directory. This option is useful when you diagnose errors.

Task options

-E "pre_exec_command [arguments ...]"

Runs the specified job-based pre-execution command on the execution host before running the task.

The task pre-execution behavior mimics the behavior of LSF job pre-execution. However, the task pre-execution command cannot run as root.

The standard input and output for the pre-execution command are directed to the same files as the job. The pre-execution command runs under the same user ID, environment, home, and working directory as the job. If the pre-execution command is not in the user's usual execution path (the $PATH variable), the full path name of the command must be specified.

-Ep "post_exec_command [arguments ...]"

Runs the specified job-based post-execution command on the execution host after the task finishes.

The task post-execution behavior mimics the behavior of LSF job post-execution. However, the task post-execution command cannot run as root.

If the post-execution command is not in the user's usual execution path (the $PATH variable), the full path name of the command must be specified.

-e error_file

Specify a file path. Appends the standard error output of the job to the specified file.

If the parameter LSB_STDOUT_DIRECT in the lsf.conf file is set to Y or y, the standard error output of a task is written to the file you specify as the task runs. If the LSB_STDOUT_DIRECT parameter is not set, standard error output of a task is written to a temporary file and copied to the specified file after the task finishes.

You can use the special characters %J, %I, %T, and %X in the name of the output file.

%J: Replaced by the job ID.
%I: Replaced by the job array index.
%T: Replaced with the task ID.
%X: Replaced by the task array index.

If the current working directory is not accessible on the execution host after the job starts, LSF Session Scheduler writes the standard error output file to /tmp/.

Note: The file path can contain up to 4094 characters, including the directory, file name, and expanded values for%J, %I, %T, and %X.

-i input_file

Gets the standard input for the job from specified file. Specify an absolute or relative path. The input file can be any type of file, though it is typically a shell script text file.

If -i is not specified, standard input defaults to /dev/null.

You can use the special characters %J, %I, %T, and %X in the name of the input file.

%J: Replaced by the job ID.
%I: Replaced by the job array index.
%T: Replaced with the task ID.
%X: Replaced by the task array index.

Note: The file path can contain up to 4094 characters, including the directory, file name, and expanded values for%J, %I, %T, and %X.

-J task_name[ index_list]

Specifies the indices of the task array. The index list must be enclosed in square brackets. The index list is a comma-separated list whose elements have the syntax start[-end[:step]], where start, end and step are positive integers. If the step is omitted, a step of one is assumed. The task array index starts at one.

All tasks in the array have the same option parameters. Each element of the array is distinguished by its array index.

-j "starter [starter] ['%USRCMD'] [starter]"

Task job starter. Creates a specific environment for submitted tasks before execution.

The job starter is any executable file that can be used to start the task (that is, it can accept the task as an input argument). Optionally, more strings can be specified.

By default, the user commands run after the job starter. A special string, %USRCMD, can be used to represent the position of the user's task in the job starter command line. The %USRCMD string can be followed by more commands.

-o output_file

Specify a file path. Appends the standard output of the task to the specified file. The default is to output to the same stdout as the ssched command.

If only a file name is specified, LSF writes the output file to the current working directory. If the current working directory is not accessible on the execution host after the task starts, LSF writes the standard output file to /tmp/.

If the parameter LSB_STDOUT_DIRECT in the lsf.conf file is set to Y or y, the standard output of a task is written to the file you specify as the task runs. If the LSB_STDOUT_DIRECT parameter is not set, standard output is written to a temporary file and copied to the specified file after the task finishes.

You can use the special characters %J, %I, %T, and %X in the name of the output file.

%J: Replaced by the job ID.
%I: Replaced by the job array index.
%T: Replaced with the task ID.
%X: Replaced by the task array index.

Note: The file path can contain up to 4094 characters, including the directory, file name, and expanded values for %J, %I, %T, and %X.

-M mem_limit

Sets a per-process memory limit for all the processes that belong to the task:

By default, the limit is specified in KB. Use the LSF_UNIT_FOR_LIMITS parameter in the lsf.conf file to specify a larger unit for the limit (MB, GB, TB, PB, or EB).

Set a task level memory limit only if it less than the job limit.

Set the LSF_CREATE_SS_TASK_MEMLIMIT environment variable to make sure that this task level memory limit takes effect. You can either export this environment variable before running the bsub command to submit jobs, or you can run the bsub command to submit jobs with the -env "LSF_CREATE_SS_TASK_MEMLIMIT=Y" option.

-Q "exit_code ..."

Enables automatic task re-queuing for failed tasks, and sets the LSB_EXIT_REQUEUE environment variable. use spaces to separate multiple exit codes. For example, ssched -Q "3 15 99" tells the ssched command to automatically re-queue failed tasks with exit codes of 3, 15, and 99. The output from the failed run is not saved, and the user is not notified by LSF.

-W [minutes:]seconds

Sets the runtime limit of the task. If a task runs longer than the specified run limit, the task is sent a SIGKILL signal.

The run limit is in the form [minutes:]seconds. The seconds can be specified as a number greater than 59. For example, three and a half minutes can either be specified as 3:30, or 210. The run limit you specify is the absolute run time.

-tasks task_definition_file

Specify tasks through a task definition file.

command [argument]

The command can be anything that is provided to a UNIX Bourne shell. The command is assumed to begin with the first word that is not part of an option. All arguments that follow command are provided as the arguments to the command.

The job command can be up to 4094 characters long.

-h

Prints command usage to stderr and exits.

-V

Prints the LSF Session Scheduler release version to stderr and exits.