NCL Home > Documentation > Functions > File I/O

getfilevardimsizes

Returns the dimension sizes of a variable on a given file.

Prototype

	function getfilevardimsizes (
		thefile [1] : file,    
		varname [1] : string   
	)

	return_val [*] :  integer or long

Arguments

thefile

A reference to a file created from a call to addfile or addfiles. The file referenced must be one in the supported file format list.

varname

The string name of the variable whose dimension sizes are desired.

Return value

Returns a one dimensional array of dimension sizes for a file variable. In versions 5.x or earlier, this function always returns an integer array. In versions 6.0.0 or later, this function may return a long array. See below.

Description

This function works just like dimsizes, but for file variables. This function should be used rather than dimsizes when the variable is in a file. The dimsizes function is very inefficient to use on file variables because it reads in the entire variable. The getfilevardimsizes function should be used exclusively when querying the dimensionality of variables in files.

If the dimension names are also desired, then getfilevardimnames returns the names in the same order as the sizes returned from this function.

As of version 6.0.0, this function will return type "long" if any of the individual dimension sizes or the product of the dimension sizes is greater than or equal to 2 GB.

Examples

Example 1

Consider a netCDF file where "ncdump -h Tstorm.nc" yields:

netcdf Tstorm {
dimensions:
        timestep = 64 ;
        lat = 33 ;
        lon = 36 ;
        timelen = 20 ;
variables:
        float t(timestep, lat, lon) ;
                t:_FillValue = -9999.f ;
        int timestep(timestep) ;
        float lat(lat) ;
        float lon(lon) ;
        char reftime(timelen) ;
                reftime:units = "text_time" ;
                reftime:long_name = "reference time" ;
}

  a    = addfile("$NCARG_ROOT/lib/ncarg/data/cdf/Tstorm.cdf","r")

  dimt = getfilevardimsizes(a,"t")  
  print(dimt)

This produces the following output:

Variable: dimt
Type: integer
Total Size: 12 bytes
            3 values
Number of Dimensions: 1
Dimensions and sizes:   [3]
Coordinates: 

(0)     64
(1)     33
(2)     36

Example 2

To return the dimension names and sizes for a particular variable on a file:

   f      = addfile ("$NCARG_ROOT/lib/ncarg/data/cdf/Tstorm.cdf" , "r")
   dSizes = getfilevardimsizes(f,"t")  
   dNames = getfilevardims(f,"t")        ; NCL 6.4.0 and earlier
;  dNames = getfilevardimnames(f,"t")    ; NCL 6.5.0 and later
   print (dNames + " : " + dSizes)

Output:

(0)     timestep : 64
(1)     lat : 33
(2)     lon : 36

Example 3

For each variable on a file, print its type, attributes, dimension names, and dimension sizes. It's possible for a variable to not contain dimension names and/or attributes, so the any and ismissing functions are used to check for this:

  f = addfile("$NCARG_ROOT/lib/ncarg/data/cdf/Ustorm.cdf","r")

  vnames = getfilevarnames(f)           ; all variable names
  nvars  = dimsizes(vnames)

  do nv = 0,nvars-1
    vtype  = getfilevartypes(f,vnames(nv))
    vatts  := getfilevaratts(f,vnames(nv))       ; The := is important because these
    dnames := getfilevardimnames(f,vnames(nv))   ; variables may be a different size
    dsizes := getfilevardimsizes(f,vnames(nv))   ; the next time through the loop

;   print("==================================================")
    print("Variable '" + vnames(nv) + "'")
    print("  type            : " + vtype)
    if(.not.any(ismissing(dnames))) then
      print("  dimension names : " + str_join(dnames,","))
    else
      print("  dimension names : ")
    end if
    print("  dimension sizes : " + str_join(""+dsizes,","))
    if(.not.any(ismissing(vatts))) then
      print("  attributes      : " + str_join(vatts,","))
    else
      print("  attributes      : ")
    end if
 end do