NCL Home > Documentation > Functions > System tools

systemfunc

Executes a shell command and returns the output.

Prototype

	function systemfunc (
		command [1] : string   
	)

	return_val [1] :  string

Arguments

command

A singly dimensioned string containing a shell command to execute.

Return value

Returns a singly dimensioned string array containing the output from the executed shell command.

Description

This function passes the string command to the shell environment for execution. When the command completes, the output from the shell command is returned to NCL as a string, and control is returned to NCL.

The default shell used to execute command is /bin/sh (Bourne Shell). A different shell may be specified in command; to use a different shell, such as the C-Shell, commands are enclosed in single quotes (') to prevent the Bourne Shell from interpreting the commands. If the C-Shell command itself contains single quotes, they must be escaped with a '\'. See Example 5 below.

Using the systemfunc command, an NCL script can perform tasks often accomplished via a Linux/Unix shell script.

See Also

getenv system

Examples

Example 1

Retrieve the current time and date and return as a string:

  TimeDate = systemfunc("date")     

This returns a string of the form: TimeDate = "Tue Apr 11 14:30:44 MDT 2000".

Example 2

Use several Linux/Unix tools to create a UTC (Coordinated Universal Time) time. The Linux/Unix command date -u returns the time as GMT (Greenwich Mean Time).

   ; "date -u" returns a string of the form: "Tue Feb 18 16:48:31 GMT 2003"
   UTC = systemfunc("date -u '+%H%M UTC %e %b %Y'| awk '{print toupper($0)}'")

   print(UTC)   ; 1648 UTC 18 FEB 2003

Example 3

Retrieve a list of files from the current directory using wild cards:

  myFiles = systemfunc("ls *.nc")  ; return all netCDF files

myFiles will be a singly dimensioned array of strings.

Example 4

Retrieve a list of files from another directory:

  diri = "/ptmp/user/data/AnnualData/"
  fils = systemfunc("ls " + diri + "annual*")
  
  print(fils)   ; full path to files

Variable: fils
Type: string
Total Size: 40 bytes
            5 values
Number of Dimensions: 1
Dimensions and sizes:   [5]
Coordinates: 
(0)     /ptmp/user/data/AnnualData/annual.1974.nc
(1)     /ptmp/user/data/AnnualData/annual.1975.nc
(2)     /ptmp/user/data/AnnualData/annual.1976.nc
(3)     /ptmp/user/data/AnnualData/annual.1977.nc
(4)     /ptmp/user/data/AnnualData/annual.1978.nc

Example 5

Retrieve a list of files from another directory, but do not include the directory; use the C-Shell (csh) syntax. To prevent the Bourne Shell from attempting to interpret C-Shell syntax, commands are enclosed by single quotes ('). If the C-Shell command itself contains single quotes, they must be escaped with a '\'.

First, use the Linux/Unix command cd to change directory location to the desired directory, and then list the appropriate files:

  diri = "/ptmp/user/data/AnnualData/"
  fils = systemfunc ("csh -c 'cd " + diri + " ; ls annual*'")
  
  print(fils)   ; relative path to files

Variable: fils
Type: string
Total Size: 40 bytes
            5 values
Number of Dimensions: 1
Dimensions and sizes:   [5]

(0)     annual.1974.nc
(1)     annual.1975.nc
(2)     annual.1976.nc
(3)     annual.1977.nc
(4)     annual.1978.nc