Passing Args to your Job Scripts¶

In this section we will look at a way to pass arguments from the command line into your PBS job submission script. This can be very useful if you wish to set some variable outside the script, and pass it into the script at submission time.

Command Line Arguments¶

What is “passing arguments”? It’s when we provide a script or program with one or more additional pieces of information on the command line. For example, here we are passing one command line argument to the script myScript.sh. The value of the argument is mygenome.fasta.

$ myScript.sh mygenome.fasta

But we can’t directly pass such command line args when our script is itself an arg to the qsub command. (args is short for arguments, Linux/UNIX users like abbreviations.)

$ qsub myScript.sh mygenome.fasta   <== This won't work.

However there is a way to do this. Pass the args as environment variables to your job script using the -v option to qsub.

$ qsub -v parameter_name=parameter_value[,par_name=par_value...] script.sh

Then $parameter_name can be used as variable in your script.

Passing in a Single Variable¶

Here is an example for passing in one environment variable and using it in your script.

Your script myScript.sh could look something like this:

#!/bin/bash
#PBS -N Test
#PBS -l ncpus=4
#PBS -l walltime=0:02:00
#PBS -l mem=5G

# Run python program, make sure you pass in $input as an env variable.
echo "Processing $input"
some_program.py $input

Submit it like this:

$ qsub -v input=mygenome.fasta myScript.sh

The output after it has finished running will be:
Processing mygenome.fasta

Passing in Multiple Variables¶

If you need to pass more than one variable then you use a comma-separated list of strings.

#!/bin/bash
#PBS -N Test
#PBS -l ncpus=4
#PBS -l walltime=0:02:00
#PBS -l mem=5G

# Run python program, make sure you pass in the required env variables!
echo "Processing $input with args $foo and $bar"
some_program.py $input $foo $bar

Submit it as below. The multiple variables need to be a comma-separated list. You can’t have spaces in this list.

$ qsub -v input=mygenome.fasta,foo=A,bar=20  myScript.sh

The output after it has finished running will be:
Processing mygenome.fasta with args A and 20

Quirks¶

It’s unlikely you will be using commas in your variable but if you do you there are a few quirks that you need to be aware of. The man page correctly explains that the value must be enclosed in single or double quotes, and the <variable>=<value> pair must be enclosed in the kind of quotes not used to enclose the value.

Here is an example:

$ qsub -v input=mygenome.fasta,"foo='A,B'",bar=20  myScript.sh

However I have found that the following will also work. You can also use spaces in this format.

$ qsub -v "input=mygenome.fasta,foo='A,B',bar=20"  myScript.sh
$ qsub -v "input=mygenome.fasta, foo='A,B', bar=20"  myScript.sh

References¶

Download the PBS User Guide from here: /shared/eresearch/pbs_manuals/PBSUserGuide2021.1.pdf
Then look at the following two sections:
Section 2.3.3.4 “Passing Arguments to Jobs”, Page UG-21
Section 2.3.4 “Submitting Jobs by Specifying Executable on Command Line”, Page UG-22

Also you can get the info from the manual page for qsub. Type “man qsub” and search for “variable list” or “-v”.

Note

There are mistakes in the PBS UserGuide documentation and the man page for qsub!
The man pages gives this example: qsub -v a=10, "var2='A,B'", c=20, HOME=/home/zzz job.sh
It’s wrong. It should be this: qsub -v a=10,"var2='A,B'",c=20,HOME=/home/zzz job.sh
You can’t have spaces between the variables.

I raised a bug report with Altair on this issue earlier this year and they will be fixing their documentation.