Specifying job name, output files and notifications

In general, there are two ways to pass job properties to the queue manager:

  1. they can be specified on the command line when executing qsub command, or
  2. they can be put in the job script on lines that start with #PBS (so-called PBS directives).

In a job script, each line that is a PBS directive can contain one or more options written in exactly the same way as on the command line for qsub.

Warning

These lines have to come at the top of the job script, before the first Bash statement, but after the she-bang line telling the shell that this is a bash script.

Both strategies can be mixed at will: some options can be put in the job script, while others are specified on the command line.

This can be very useful, e.g., if you run a number of related jobs from different directories using the same script. The few things that have to change can then be specified at the command line. The options given at the command line always overrule those in the job script in case of conflict.

Naming jobs

The default name of a job is derived from the file name of the job script. This is not very useful if the same job script is used to launch multiple jobs, e.g., by launching jobs from multiple directories with different input files. It is possible to overwrite the default name of the job with -N <job_name>.

Naming output files

Most jobs on a cluster run in batch mode. This implies that they are not connected to a terminal, so the output sent to the Linux stdout (standard output) and stderr (standard error) devices cannot be displayed on screen.

Instead, it is captured in two files that are put in the directory where your job was started at the end of your job. The default names of those files are

  • <job_name>.o<jobid> and
  • <job_name>.e<jobid>.

Hence the file names are constructed from the name of the job (the one assigned using -N if any, or the default one) and the number of the job ID assigned when you submit the job to the queue.

You can however change those names using the options

  • -o <output file> and
  • -e <error file>.

Merging output and error

It is also possible to merge both output streams in a single output stream. The option -j oe will merge stderr into stdout (and hence the -e option does not make sense), the option -j eo will merge stdout into stderr.

Notification of job events

The scheduler can notify you when a job starts or ends by e-mail. Jobs can stay queued for hours or sometimes even days before actually starting, so it is useful to be notified so that you can monitor the progress of your job while it runs.

You can be notified on three events relating to your job.

event mnemonic description
b job beginning, i.e., job starts
e job end, i.e., the job finishes normally
a job abort, i.e., the job terminates abnormally

Two command line options are involved in this process:

-m <events>
Here, <events> is any combination of b, e and a. These are the events you will be notified about.
-M <mailaddress>
This defines the e-mail address to send the notifications to.
On most clusters the default will be the e-mail address with which you registered your VSC-account, but on some clusters this fails and the option is required to receive the e-mail.

Other options

This page describes the most used options in their most common use cases. There are however more parameters for resource specification and other options that can be used. For advanced users who want to know more, we refer to the documentation of the qsub command that mentions all options in the Torque manual on the Adaptive Computing documentation.