NCL Home> Application examples> Data Analysis || Data files for some examples

Example pages containing: tips | resources | functions/procedures

NCL system and shell interactions

Setting NCL variables via command line arguments

NCL command line arguments allow you to set NCL variables and execute simple NCL code snipplets from the UNIX command line or a shell script.

As a simple example, assume you have a 3-line ncl script called myscript.ncl:

  print("year: " + year) print("month: " + month) print("title: " +
This script would fail on its own, because month, year and title are undefined.

However, using command line arguments, you can set these variables when you run NCL from the UNIX command line:

   ncl year=2014 month=5 'title="This is a title"' myscript.ncl
Writing shell scripts to set NCL variables via command line arguments and execute the NCL script

This is similar to the above example, but now you are writing a shell script to set the NCL variables and execute the NCL script: (bash/ksh):


ncl year=2014 month=10 'title="This is a title"' myscript.ncl

test_csh_script.csh (bash/ksh):

#!/bin/csh -f

ncl year=2014 month=10 'title="This is a title"' myscript.ncl

To run either shell script, make it executable first:

chmod gou+x

chmod gou+x test_csh_script.csh

For full details, see the Command Line Options section in the NCL Reference Manual.

Writing shell scripts to set NCL variables via environment variables and execute the NCL script

You can use UNIX environment variables to set values inside a shell script, that you can then retrieve from within an NCL script using NCL's getenv function.

Note: command line arguments (see above section) are the preferred method for doing this sort of thing.

Starting with the same 3-line script from above, You would need to add three lines to it to retrieve these environment variable settings:


  year  = toint(getenv("YEAR"))
  month = toint(getenv("MONTH"))
  title = getenv("TITLE")
  print("year:  " + year) 
  print("month: " + month) 
  print("title: " + title)

You would then set these environment variables from within a csh/tcsh script or a bash/ksh script, before executing the script: (bash/ksh):


export YEAR=2014
export MONTH=10
export TITLE="This is a title"

ncl myscript_env.ncl

test_csh_script_env.csh (csh/tcsh):

#!/bin/csh -f

setenv YEAR 2014
setenv MONTH 10
setenv TITLE "This is a title"

ncl myscript_env.ncl
To run either shell script, make it executable first:

chmod gou+x

chmod gou+x test_csh_script_env.csh

Using NCL to execute UNIX system commands

Executing UNIX commands from NCL can be done via NCL's systemfunc function, and/or the system procedure. These provide users with the ability to execute shell commands or other software tools, like netCDF operators (NCO) , Climate Data Operators (CDO), convert (ImageMagick), wgrib, wget. See below for some examples.

Passing a string to NCL from within a C-shell script.

Loop over netCDF files beginning with f40 and pass each file name onto NCL:

foreach i (f40*.nc)
   echo $i
   ncl fname=\"{$i}\" foo.ncl

Using a shell script to call NCL with some string-based command line arguments

% cat test.ncl

Then, in the shell script:

  • To escape the shell's interpretation of the double-quote ("), use the backslash prior to (")
  • Use the curly brackets ({... }) to delineate the text associated with the environment variable name.

% set outFile = "test-out"
% echo $outFile

% ncl inFile=\"{$outFile}\" outFile=\"{$outFile}.nc\" test.ncl


Variable: inFile
Type: string



Variable: outFile
Type: string


Using NCL with environment variables to set variables from within a shell script

This is an older way of setting variables in a shell script, to be used by an NCL script. The shell script would need to use setenv or export to set one or more environment variable(s), and the NCL script would then use getenv to retrieve the value of the environment viarlables.

  nyrStrt = 300                         
  nyrLast = 999 

  mssi= getenv("MSS_PATH") ; retrieve MSS environment variable

  fili= "b20.007.pop.h.0"               ; first part of file name
  diri= "/ptmp/foo/"                    ; where to put msrcp  data (input)
  diro= "/ptmp/foo/output/"             ; where to put ncrcat data (outout)
  filo= "b20.TEMP."                     ; rename output files (root name)

  do nyear=nyrStrt,nyrLast ; each year has 12 files 
      wallClock = systemfunc("date") ; retrieve wall clock time
      print("year="+nyear+"   "+wallClock)

                                             ; create string for MSS comman
      msscmd= "msrcp -n 'mss:" + mssi + fili + nyear + "-[0-1][0-9].nc' "+ diri+"."
      print (" msscmd= "+ msscmd)
      system (msscmd)

                                             ; netCDF operatoer to extract and concatenate
      ncocmd= "ncrcat -v TEMP " + diri + fili + "*.nc "+diro+filo+nyear+".nc"
      print ("ncocmd = "+ncocmd)
      system (ncocmd)
                                             ; remove the temporary files
      rmcmd = "/bin/rm -f "+diri+fili+nyear+"*.nc"
      print ("rmcmd ="+ rmcmd)
      system (rmcmd)

  end do


system_1.ncl: This invokes the netCDF operators (ncra and ncea) to create individual monthly, seasonal and annual files for all variables on a source year-month file. The 12 monthly files are used to create the seasonal and annual files.
system_2.ncl: This accesses a number of tar files containing GRIB. It creates the following string

wgrib -s anl_p25.1990010100 | \
     egrep "(:UGRD:200 mb|:VGRD:200 mb|:UGRD:850 mb|:VGRD:850 mb)" | \
     wgrib -i -grib anl_p25.1990010100 -o FOO.grb

This requires that a double quote character be passed to the system. Special care must be taken when doing this. (See the NCL FAQ: including the double quote (") character in an NCL string.) The final step is to remove unwanted files.
system_3.ncl: A large number of GrADS files are converted to netCDF via the Climate Data Operator: cdo -f nc import_binary ...
system_4.ncl: A large number of netCDF files are detrended via the Climate Data Operator: cdo detrend ...
system_5.ncl: Ascii (.gz) files are accessed and downloaded from the World Ocean Atlas 2009 (WOA09) ftp area using wget. They are made into netCDF files.
system_6.ncl: Use NCL to generate a netCDF Operator 'ncap2' command that will be sent to the system for execution. The purpose was to convert all type 'double' variables of rank 2 or greater to type float. There were many variables on the source file that fit these criteria.