NCL Website header
NCL Home > Documentation > Functions > File I/O


Returns an array of file variable names in the specified supported file.

Available in version 6.1.1 and later.


	function getfilevarnames (
		the_file [1] : file   

	return_val [*] :  string



thefile references a file or files opened with addfile or addfiles. Thus, it must be a supported file format.

Return value

This function returns an array of strings with each element containing the name of a variable. The length of this array is equal to the number of variables in the file.

Starting from version 6.1.1, this function will return the variable names with group name(s) inserted at the beginning, if a user opens a NetCDF4 file. If it is at root (group), then a "/" is inserted. See example below for more details.


This function is useful when accessing file variables by string name. (See Files.)


The following example gets all the variables names from a netCDF file but it will also work for any file referenced by addfile. The dollar sign syntax used in this example is described at "NCL Variables".

    f = addfile ("" , "r")   ; could also have ccm, grb or hdf suffix
    vNames = getfilevarnames (f) ; get names of all variables on file
    nNames = dimsizes (vNames)   ; number of variables on the file
    print (vNames)               ; print all variable names on file
    do n=0,nNames-1              ; loop thru each variable
       v = f->$vNames(n)$        ; read the varible to memory
       dimv = dimsizes(v)        ; dimension size of the variable
       rank = dimsizes(dimv)     ; rank [ie: number of dimensions]
       delete (v)
       delete (rank)
   end do

When opening a NetCDF4 file, the variable names have group names inserted at the beginning. If it is a root (group), then a "/" is inserted (to represent the root group).

 fn = ""
 fi = addfile(fn, "r")

 vNames = getfilevarnames(fi) ; get variable names of all groups on file
 print (vNames)               ; print all variable names on file

The above script produces:

Variable: vNames
Type: string
Total Size: 112 bytes
            14 values
Number of Dimensions: 1
Dimensions and sizes:   [14]
(0)     /time
(1)     /lev
(2)     /lat
(3)     /lon
(4)     /T
(5)     /U
(6)     /V
(7)     /grp1/time
(8)     /grp1/lev
(9)     /grp1/lat
(10)    /grp1/lon
(11)    /grp1/T
(12)    /grp1/U
(13)    /grp1/V

Here, one can see that there are T, U, V, and other variables under the "/" (root) group and the group "grp1".