NetCDF Toolbox User's Guide

Note: This User's Guide may be slightly out-of-date. Always consult "help netcdf" for the latest NetCDF Toolbox syntax.

NetCDF Toolbox Interface Descriptions

Each interface description for a particular NetCDF Toolbox function contains:

Purpose
NetCDF Toolbox Language -- The NetCDF Toolbox provides a high-level language that uses objects and Matlab operators for almost all of its activities. The principal usage, recommended for all ages, is illustrated here. The NetCDF Toolbox language takes full advantage of concepts introduced in Matlab-5.
- [a, b, ...] = func(x, y, ...) -- The Matlab instruction.
Arguments -- Calling arguments for the instruction.
Errors -- Possible error conditions.
Example -- Example using NetCDF Toolbox language.
Origins -- Low-level interfaces (direct usage not recommended) that illustrate the origins of the high-level NetCDF Toolbox functionality.
- ncmex() -- M-file gateway for Matlab-5 arrays.
- mexcdf() -- M-File gateway for Matlab-4 arrays.
- mexcdf53() -- Mex-file gateway for Matlab-5 and NetCDF-3.
- C-Language prototype -- See NetCDF User's Guide.
- FORTRAN prototype -- See NetCDF User's Guide.

NetCDF File Operations

Create a NetCDF file

Create a new, empty NetCDF file, suitable for defining, accessing, and deleting NetCDF dimensions, variables, attributes, and records. The file is placed in "define" mode.

NetCDF Language
- nc = netcdf('path', 'cmode')

Arguments
- nc -- The output "netcdf" object, or [] if error.
- path -- The path (filename) as a string.
- cmode -- The string 'noclobber' or 'clobber'.
Errors
- Directory does not exist.
- File already exists when cmode is 'noclobber'.
- Directory is read-only.

Example

This example creates the NetCDF file named 'foo.nc', but only if
the file does not already exist.  The returned value is a "netcdf"
object, which represents the file in all subsequent transactions.
If an error occurs, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'noclobber')
if isempty(nc), error('## Bad netcdf operation.'), end

Origins
- ncid = ncmex('create', path, cmode)
- ncid = mexcdf('create', path, cmode)
- ncid = mexcdf53('create', path, cmode)
- int nccreate(char * path, int cmode)
- integer function nccre(character*(*) path, integer cmode, integer rcode)

Open a NetCDF File for Access

Open an existing NetCDF file for access.

NetCDF Language
- nc = netcdf('path', 'mode')

Arguments
- nc -- The output "netcdf" object, or [] if error.
- path -- The path (filename) as a string.
- mode -- The string 'nowrite' or 'write'.
Errors
- File does not exist.
- Not an open NetCDF file.
- File is read-only when mode is 'write'.

Example

This example opens the NetCDF file named 'foo.nc' for read-only access.
The returned value is a "netcdf" object, which represents the file in
all subsequent transactions.  If an error occurs, the empty-matrix []
is returned.

nc = netcdf('foo.nc', 'nowrite')
if isempty(nc), error('## Bad netcdf operation.'), end

Origins
- ncid = ncmex('open', 'path', 'mode')
- ncid = mexcdf('open', 'path', 'mode')
- ncid = mexcdf53('open', 'path', 'mode')
- int ncopen(char * path, int mode)
- integer function ncopn(character*(*) path, integer mode, integer rcode)

Put an Open NetCDF File into Define-Mode

Place an open NetCDF file in "define" mode, so that NetCDF entities can be added, renamed, modified, or deleted. With the NetCDF Toolbox interface, the "define" mode is entered automatically as needed.

NetCDF Language
- result = redef(nc)

Arguments
- result -- The "netcdf" object, or [] if error.
- nc -- The "netcdf" object.
Errors
- File is read-only.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc' for read/write
access, then puts it into "define" mode.  If an error occurs, the
empty-matrix [] is returned.  Otherwise, the same "netcdf" object
is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error(' ## Bad netcdf operation.'), end
result = redef(nc)
if isempty(result), error('## Bad redef operation.'), end

Origins
- result = ncmex('redef', ncid)
- result = mexcdf('redef', ncid)
- result = mexcdf53('redef', ncid)
- int ncredef(int ncid)
- subroutine ncredf(integer ncid, integer rcode)

Put an Open NetCDF File into Data-Mode

Take an open NetCDF file out of "define" mode. The resulting state is called "data" mode. With the NetCDF Toolbox interface, the "data" mode is entered automatically as needed.

NetCDF Language
- result = endef(nc)

Arguments
- result -- The "netcdf" object, or [] if error.
- nc -- The "netcdf" object.
Errors
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc' for read/write
access, puts it into "define" mode, then takes it out of "define" mode.
If an error occurs, the empty-matrix [] is returned.  Otherwise, the
same "netcdf" object is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error(' ## Bad netcdf operation.'), end
result = redef(nc)
result = endef(nc)
if isempty(result), error('## Bad endef operation.'), end

Origins
- result = ncmex('endef', ncid)
- result = mexcdf('endef', ncid)
- result = mexcdf53('endef', ncid)
- int ncendef(int ncid)
- subroutine ncendf(integer ncid, integer rcode)

Close an Open NetCDF File

Close an open NetCDF file.

NetCDF Language
- result = close(nc)

Arguments
- result -- The "netcdf" object, or [] if error.
- nc -- The "netcdf" object.
Errors
- File was in "define" mode and automatic "endef" failed.
- Not an open NetCDF file.

Example

This example opens, then closes, the NetCDF file named 'foo.nc'.
If an error occurs, the "netcdf" object is returned.  Otherwise, the
empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error(' ## Bad netcdf operation.'), end
result = close(nc)
if ~isempty(result), error('## Bad close operation.'), end

Origins
- result = ncmex('close', ncid)
- result = mexcdf('close', ncid)
- result = mexcdf53('close', ncid)
- int ncclose(int ncid)
- subroutine ncclos(integer ncid, integer rcode)

Inquire about an Open NetCDF File

Get information about an open NetCDF file.

NetCDF Language
- theDims = dim(nc)
- theVars = var(nc)
- theGAtts = att(nc)
- theRecdim = recdim(nc)

Arguments
- theDims -- List of "ncdim" dimension objects.
- theVars -- List of "ncvar" variable objects.
- theGAtts -- List of "ncatt" global attribute objects.
- theRecdim -- The "ncdim" record-dimension object.
- nc -- The "netcdf" object.
Errors
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc', then inquires
about the objects in it.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error(' ## Bad netcdf operation.'), end
theDims = dim(nc)        % List of "ncdim" dimension objects.
theVars = var(nc)        % List of "ncvar" variable objects.
theGAtts = att(nc)       % List of "ncatt" global attribute objects.
theRecdim = recdim(nc)   % The "ncdim" record-dimension object.

Origins
- [ndims, nvars, ngatts, recdim] = ncmex('inquire', ncid)
- [ndims, nvars, ngatts, recdim] = mexcdf('inquire', ncid)
- [ndims, nvars, ngatts, recdim] = mexcdf53('inquire', ncid)
- int ncinquire(int ncid, &ndims, &nvars, &ngatts, &recdim)
- subroutine ncinq(integer ncid, integer ndims, integer nvars, integer ngatts, integer recdim, integer rcode)

Synchronize an Open NetCDF File to Disk

Make disk copy of a writeable open NetCDF file current.

NetCDF Language
- result = sync(nc)

Arguments
- result -- The "netcdf" object, or [] if error.
- nc -- The "netcdf" object.
Errors
- Not an open NetCDF file.

Example

This example opens, synchronizes, then closes, the NetCDF file named 'foo.nc'.
If an error occurs, the "netcdf" object is returned.  Otherwise, the
empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
result = sync(nc)
if ~isempty(result), error('## Bad sync operation.'), end

Origins
- result = ncmex('sync', ncid)
- result = mexcdf('sync', ncid)
- result = mexcdf53('sync', ncid)
- int ncsync(int ncid)
- subroutine ncsnc(integer ncid, integer rcode)

Back Out of Recent Definitions

Abort recent definitions. If not in "define" mode, closes the file. If being created and still in "define" mode, deletes the file. If "define" mode was entered by calling "redef", restores the file to its former state, then closes it.

NetCDF Language
- result = abort(nc)
- result = ncmex('abort', ncid)
- result = mexcdf('abort', ncid)
- result = mexcdf53('abort', ncid)
- int ncabort(int ncid)
- subroutine ncabor(integer ncid, integer rcode)

Arguments
- result -- The "netcdf" object, or [] if error.
- nc -- The "netcdf" object.
Errors
- File was in "define" mode and deletion failed.
- Not an open NetCDF file.

Example

This example opens, enters "define" mode, then aborts, the NetCDF file named 'foo.nc'.  If an error occurs, the "netcdf" object is returned.  Otherwise, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
result = redef(nc)
result = abort(nc)
if ~isempty(result), error('## Bad abort operation.'), end

Origins
- result = abort(nc)
- result = ncmex('abort', ncid)
- result = mexcdf('abort', ncid)
- result = mexcdf53('abort', ncid)
- int ncabort(int ncid)
- subroutine ncabor(integer ncid, integer rcode)

Set Fill Mode for Writes

Set and/or return the fill mode for writing to the NetCDF file.

NetCDF Language
- result = setfill(nc, fillmode)

Arguments
- result -- The "netcdf" object, or [] if error.
- nc -- The "netcdf" object.
- fillmode -- 1 (fill) or 0 (nofill).
Errors
- File is open for read-only access.
- Incorrect fillmode value.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc', then sets the
fillmode for "nofill".  If an error occurs, the empty-matrix []
is returned.  Otherwise, the same "netcdf" object is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
result = setfill(nc, 0)
if isempty(result), error('## Bad setfill operation.'), end

Origins
- result = ncmex('setfill', ncid, fillmode)
- result = mexcdf('setfill', ncid, fillmode)
- result = mexcdf53('setfill', ncid, fillmode)
- int ncsetfill(int ncid, int fillmode)
- integer function ncsfil(integer ncid, integer fillmode, integer rcode)

NetCDF Dimension Operations

Create a Dimension

Add a new dimension to an open NetCDF file in "define" mode.

NetCDF Language
- nc('theDimname') = theDimsize, or
- theDim = ncdim(nc, theDimname, theDimsize)
- ncid = ncmex('dimdef', dimname, dimsize)
- ncid = mexcdf('dimdef', dimname, dimsize)
- ncid = mexcdf53('dimdef', dimname, dimsize)
- int ncdimdef(int ncid, char * name, int dimsize)
- subroutine ncddef(integer ncid, character*(*) dimname, integer dimsize, integer rcode)

Arguments
- theDim -- The output "ncdim" dimension object.
- nc -- The "netcdf" object.
- theDimname -- String-name of the dimension.
- theDimsize -- Size of the dimension; 0 if "unlimited".
Errors
- Not an open netCDF file.
- Dimension of same name already exists.
- Attempt to define more than one "unlimited" dimension.

Example

This example opens the NetCDF file named 'foo.nc', then adds
an "unlimited" dimension named 'time'.  If an error occurs, the
empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
nc('time') = 0
if isempty(nc('time')), error(' ## Bad dimdef operation.'), end

Origins
- nc('theDimname') = theDimsize, or
- theDim = ncdim(nc, theDimname, theDimsize)
- ncid = ncmex('dimdef', dimname, dimsize)
- ncid = mexcdf('dimdef', dimname, dimsize)
- ncid = mexcdf53('dimdef', dimname, dimsize)
- int ncdimdef(int ncid, char * name, int dimsize)
- subroutine ncddef(integer ncid, character*(*) dimname, integer dimsize, integer rcode)

Get a Dimension from its Name

Get a NetCDF dimension object from its name.

NetCDF Language
- theDim = nc('theDimname'), or
- theDim = ncdim('theDimname', nc)

Arguments
- theDim -- The "ncdim" dimension object.
- nc -- The parent "netcdf" object.
- theDimname -- The string-name of the dimension.
Errors
- Not the name of a NetCDF dimension.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc',
then gets its 'time' dimension.  If an error occurs,
the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theDim = nc('time')
if isempty(theDim), error(' ## No such dimension.'), end

Origins
- dimid = ncmex('dimid', ncid, 'dimname')
- dimid = mexcdf('dimid', ncid, 'dimname')
- dimid = mexcdf53('dimid', ncid, 'dimname')
- int ncdimid(int ncid, char * name)
- integer function ncdid(integer ncid, character*(*) dimname, integer rcode)

Inquire about a Dimension

Get information about a dimension.

NetCDF Language
- 'theDimname' = name(theDim)
- theDimsize = size(theDim), or
- theDimsize = theDim(:)
- nc = parent(theDim)

Arguments
- theDim -- The "ncdim" dimension object.
- 'theDimname' -- The string-name of the dimension.
- theDimsize -- The size (value) of the dimension.
- nc -- The "netcdf" parent object of the dimension.
Errors
- Not a NetCDF dimension.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc', then
gets information about its 'time' dimension.  If an error
occurs, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theDim = nc('time');
if isempty(theDimid), error(' ## Bad ncdim operation.'), end
theDimname = name(theDim)
theDimsize = size(theDim)
theDimsize = theDim(:)
nc = parent(theDim)

Origins
- ['dimname', dimsize] = ncmex('diminq', ncid, 'dimname')
- ['dimname', dimsize] = mexcdf('diminq', ncid, 'dimname')
- ['dimname', dimsize] = mexcdf53('diminq', ncid 'dimname')
- int ncdiminq(int ncid, char * name)
- integer function ncdinq(integer ncid, character*(*) dimname, integer rcode)

Rename a Dimension

Rename a dimension.

NetCDF Language
- result = name(theDim, 'theNewname')

Arguments
- result -- The "ncdim" dimension object, or empty-matrix [] if error.
- theDim -- The "ncdim" dimension object.
- 'theNewname' -- The new string-name of the dimension.
Errors
- New name already used by another dimension.
- Not a NetCDF dimension.
- Not an open NetCDF file.
- File is read-only.

Example

This example opens the NetCDF file named 'foo.nc', then
renames its 'time' dimension to 'newtime'.  If an error
occurs, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
result = name(nc('time'), 'newtime') 
if isempty(result), error(' ## Bad name operation.'), end

Origins
- status = ncmex('dimrename', ncid, dimid, 'newname')
- status = mexcdf('dimrename', ncid, dimid, 'newname')
- status = mexcdf53('dimrename', ncid, dimid, 'newname')
- int ncdimrename(int ncid, int dimid, char * newname)
- subroutine ncdren(integer ncid, integer dimid, character*(*) newname, integer rcode)

NetCDF Variable Operations

Create a Variable

Add a new variable to an open NetCDF file.

NetCDF Language
- nc{'theVarname'} = nctype(dim1, dim2, ...), or
- nc{'theVarname'} = {dim1, dim2, ...}, or
- theVar = ncvar(nc, 'theVarname', 'theVartype', {dim1, dim2, ...})

Arguments
- theVar -- The output "ncdim" dimension object.
- nc -- The "netcdf" object.
- 'theVarname' -- String-name of the variable.
- nctype -- One of "ncbyte", "ncchar", "ncshort", "ncint", "nclong", "ncfloat", or "ncdouble"; "ncint" is coerced to "nclong". The default is "ncdouble".
- 'theVartype' -- One of 'byte', 'char', 'short', 'int', 'long', 'float', or 'double'. 'int' is coerced to 'long'.
- {dim1, ...} -- List of dimension objects or names. Brackets not required if just one or none (scalar-variable).
Errors
- Not an open netCDF file.
- File is read-only.
- Variable of same name already exists.
- Not a valid dimension.
- Not a valid type.
- Too many dimensions.
- The "unlimited" dimension not leftmost in the list.

Example

This example opens the NetCDF file named 'foo.nc', then creates
the single-precision variable "elevation(latitude, longitude)", where
latitude and longitude are dimensions, as well as coordinate-variables.
If an error occurs, the empty-matrix [] is returned.  The variables
are populated using colon-syntax (:), which denotes all the elements
in an array.  The alternative is to use regular array indexing.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
nc('latitude') = 19
nc('longitude') = 36
nc{latitude'} = ncfloat('latitude')
nc{longitude'} = ncfloat('longitude')
nc{'elevation'} = ncfloat('latitude', 'longitude') 
if isempty(nc{'elevation'}), error(' ## Bad vardef operation.'), end
nc{'latitude'}(:) = -90:10:90
nc{'longitude'}(:) = 0:10:350
nc{'elevation'}(:) = 0   % All zeros.
close(nc)

Origins
- ncid = ncmex('vardef', dimname, dimsize)
- ncid = mexcdf('vardef', dimname, dimsize)
- ncid = mexcdf53('vardef', dimname, dimsize)
- int ncvardef(int ncid, char * name, nc_type datatype, int ndims, int dimids[])
- integer function ncvdef(integer ncid, character*(*) varname, integer datatype, integer ndims, integer dims(*), integer rcode)

Get a Variable from its Name

Get a NetCDF variable object from its name.

NetCDF Language
- theVar = nc{'theVarname'}, or
- theVar = ncvar('theVarname', nc)

Arguments
- theVar -- The "ncvar" variable object.
- nc -- The parent "netcdf" object.
- theVarname -- The string-name of the variable.
Errors
- Not the name of a NetCDF variable.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc',
then gets its 'elevation' variable.  If an error occurs,
the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theVar = nc{'elevation'}
if isempty(theVar), error(' ## No such variable.'), end

Origins
- varid = ncmex('varid', ncid, 'varname')
- varid = mexcdf('varid', ncid, 'varname')
- varid = mexcdf53('varid', ncid, 'varname')
- int ncvarid(int ncid, char * name)
- integer function ncvid(integer ncid, character*(*) varname, integer rcode)

Inquire about a Variable

Get information about a variable.

NetCDF Language
- 'theVarname' = name(theVar)
- theVarsize = size(theVar), or
- theVarsize = theVar(:)
- nc = parent(theVar)

Arguments
- theVar -- The "ncvar" variable object.
- 'theVarname' -- The string-name of the variable.
- theVarsize -- The size of the variable.
- nc -- The "netcdf" parent object of the variable.
Errors
- Not a NetCDF variable.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc', then
gets information about its 'elevation' variable.  If an error
occurs, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theVar = nc{'elevation'};
if isempty(theVar), error(' ## Bad ncvar operation.'), end
theVarname = name(theVar)
theVarsize = size(theVar)
theVarsize = theVar(:)
nc = parent(theVar)

Origins
- ['varname', vartype, ndims, dimids, natts] = ncmex('varinq', ncid, 'varname')
- ['varname', vartype, ndims, dimids, natts] = mexcdf('varinq', ncid, 'varname')
- ['varname', vartype, ndims, dimids, natts] = mexcdf53('varinq', ncid, 'varname')
- int ncvarinq(int ncid, int varid, char * name, nc_type * dayatype, int * dims, int dimids[], int * natts)
- subroutine ncvinq(integer ncid, integer varid, character*(*) varname, integer vartype, integer ndims, integer dimids(*), integer natts, integer rcode)

Write to a Variable

Write values to a variable.

NetCDF Language
- theVar(theIndices, ...) = theValues

Arguments
- theVar -- The "ncdim" variable object.
- theIndices -- Comma-list of base-1 Matlab indices. Use (:) for all elements along a dimension. Not all indices need to be specified. If (:) is the right-most symbol, then all remaining dimensions further to the right default to (:). Otherwise, the remainder default to 1.
- theValues -- Array of values to be written.
Errors
- Not a NetCDF variable.
- Indices not valid.
- Not an open NetCDF file.
- File is read-only.

Example

This example opens the NetCDF file named 'foo.nc', then
writes some random values to its "elevation(latitude, longitude)"
variable in several different ways.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theVar = nc{'elevation'};
if isempty(theVar), error(' ## Bad ncvar operation.'), end
theVar(1:10, 1:20) = rand(10, 20);
theVar(1:10, :) = rand(10, size(nc('longitude')));
theVar(:) = rand(size(theVar));

Origins
- status = ncmex('varputg', ncid, varid, starts, counts, strides, ignore_map, values)
- status = mexcdf('varputg', ncid, varid, starts, counts, strides, ignore_map, values)
- status = mexcdf53('varputg', ncid, varid, starts, counts, strides, ignore_map, values)
- int ncvarputg(int ncid, int varid, int starts[], int counts[], int strides[], ignore_map, void * values)
- subroutine ncvptg(integer ncid, integer varid, integer starts(*), integer counts(*), integer(*) strides, ignore_map, "type" values, integer rcode)

Read from a Variable

Read values from a variable. The values are returned in their stored multi-dimensional shape.

NetCDF Language
- theValues = theVar(theIndices, ...)

Arguments
- theValues -- The returned values.
- theVar -- The "ncdim" variable object.
- theIndices -- Comma-list of base-1 Matlab indices. Use (:) for all elements along a dimension. Not all indices need to be specified. If (:) is the right-most symbol, then all remaining dimensions further to the right default to (:). Otherwise, the remainder default to 1.
- theValues -- Array of values to be written.
Errors
- Not a NetCDF variable.
- Indices not valid.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc', then
reads some random values from its "elevation(latitude, longitude)"
variable in several different ways.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theVar = nc{'elevation'};
if isempty(theVar), error(' ## Bad ncvar operation.'), end
theValues = theVar(1:10, 1:20);
theValues = theVar(1:10, :);
theValues = theVar(:);

Origins
- values = ncmex('vargetg', ncid, varid, starts, counts, strides, ignore_map)
- values = mexcdf('vargetg', ncid, varid, starts, counts, strides, ignore_map)
- values = mexcdf53('vargetg', ncid, varid, starts, counts, strides, ignore_map)
- int ncvargetg(int ncid, int varid, int starts[], int counts[], int strides[], ignore_map, void * values)
- subroutine ncvgtg(integer ncid, integer varid, integer starts(*), integer counts(*), integer(*) strides, ignore_map, "type" values, integer rcode)

Rename a Variable

Rename a variable.

NetCDF Language
- result = name(theVar, 'theNewname')
  rcode)

Arguments
- result -- The "ncvar" variable object, or empty-matrix [] if error.
- theDim -- The "ncvar" variable object.
- 'theNewname' -- The new string-name of the variable.
Errors
- New name already used by another variable.
- Not a NetCDF variable.
- Not an open NetCDF file.
- Not a writeable NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc', then
renames its 'elevation' variable to 'height'.  If an error
occurs, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
result = name(nc{'elevation'}, 'height') 
if isempty(result), error(' ## Bad name operation.'), end

Origins
- status = ncmex('varrename', ncid, varid, 'newname')
- status = mexcdf('varrename', ncid, varid, 'newname')
- status = mexcdf53('varrename', ncid, varid, 'newname')
- int ncvarrename(int ncid, int varid, char * newname)
- subroutine ncvren(integer ncid, integer varid, character*(*) newname, integer rcode)

NetCDF Attribute Operations

Create an Attribute

Add a new attribute to an open NetCDF file. When the data type is not specified, it defaults to the data type of the Matlab value, either 'char' or 'double'. The "ncatt" syntax must be used for names that would not be valid Matlab names, such as '_FillValue'.

NetCDF Language
- theParent.theAttname = nctype(theAttdata), or
- theParent.theAttname = theAttdata, or
- theAtt = ncatt('theAttname', 'theAtttype', theAttdata, theParent), or
- theAtt = ncatt('theAttname', theAttdata, theParent)

Arguments
- theParent -- The "netcdf" or "ncvar" parent object.
- theAtt -- The output "ncatt" attribute object.
- nc -- The "netcdf" object.
- 'theAttname' -- String-name of the attribute.
- nctype -- One of "ncbyte", "ncchar", "ncshort", "ncint", "nclong", "ncfloat", or "ncdouble"; "ncint" is coerced to "nclong". The default is "ncdouble".
- 'theAtttype' -- One of 'byte', 'char', 'short', 'int', 'long', 'float', or 'double'. 'int' is coerced to 'long'.
- theAttdata -- The attribute data.
Errors
- Not an open netCDF file.
- File is read-only.
- Not a valid type.

Example

This example opens the NetCDF file named 'foo.nc', then adds
a "description" attributes to the file and some "units" to the 'elevation'
variable. 

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
nc.description = ncchar('This file is an example.')
nc.description = 'This file is an example.'
nc{'elevation'}.units = ncchar('meters')
nc{'elevation'}.units = 'meters'

Origins
- status = ncmex('attput', ncid, varid, attname, atttype, attlen, attvalue)
- status = mexcdf('attput', ncid, varid, attname, atttype, attlen, attvalue)
- status = mexcdf53('attput', ncid, varid, attname, atttype, attlen, attvalue)
- int ncattput(int ncid, int varid, char * name, nc_type datatype, int attlen, void * value)
- subroutine ncapt(integer ncid, integer varid, character*(*) attname, integer datatype, integer attlen, "type" value, integer rcode)

Get Attribute Value

Read the value of an attrribute from an open NetCDF file.

NetCDF Language
- theAttvalue = theAtt(:)

Arguments
- theAttvalue -- The returned value of the attribute.
- theAtt -- The "ncatt" attribute object.
Errors
- Not an open netCDF file.
- Not a valid attribute.

Example

This example opens the NetCDF file named 'foo.nc', then reads
the "description" global attribute and the "units" attribute of the 'elevation'
variable. 

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theDescription = nc.description(:)
theUnits =nc{'elevation'}.units(:)

Origins
- attvalue = ncmex('attget', dimname, dimsize)
- attvalue = mexcdf('attget', dimname, dimsize)
- attvalue = mexcdf53('attget', dimname, dimsize)
- int ncattget(int ncid, int varid, char * name, void * value)
- subroutine ncagt(integer ncid, integer varid, character*(*) attname, "type" value, integer rcode)

Inquire about an Attribute

Get information about an attribute.

NetCDF Language
- 'theAttname' = name(theVar)
- theAttsize = size(theVar), or
- theAtttype = datatype(theAtt)
- theParent = parent(theVar)

Arguments
- theAtt -- The "ncatt" attribute object.
- 'theAttname' -- The string-name of the attribute.
- theAttsize -- The size of the attribute.
- theParent -- The "netcdf" or "ncvar" parent object.
Errors
- Not a NetCDF attribute.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc', then
gets information about its 'description' global attribute.  If an error
occurs, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
theAtt = nc.description;
if isempty(theAtt), error(' ## Bad ncatt operation.'), end
theAttname = name(theAtt)
theAttsize = size(theAtt)
'theAtttype' = datatype(theAtt)
theParent = parent(theAtt)

Origins
- [atttype, attlen] = ncmex('attinq', ncid, varid, 'attname')
- [atttype, attlen] = mexcdf('attinq', ncid, varid, 'attname')
- [atttype, attlen] = mexcdf53('attinq', ncid, varid, 'attname')
- int ncattinq(int ncid, int varid, char * name, nc_type * datatype, int * attlen)
- subroutine ncainq(integer ncid, integer varid, character*(*) attname, integer atttype, integer len, integer rcode)

Copy an Attribute from One NetCDF to Another

Copy an attribute from one NetCDF file or variable to another.

NetCDF Language
- copy(theAtt, theDestination)
- theDestination < theAtt

Arguments
- theAtt -- The "ncatt" attribute object.
- theDestination -- The "netcdf" or "ncvar" destination object.
Errors
- File is read-only.
- Not a NetCDF attribute.
- Not a valid NetCDF destination.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc' and copies
the "units" attribute of the "latitude" variable to the "longitude"
variable.  If an error occurs, the empty-matrix [] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
nc{'longitude'} < nc{'latitude'}.units

Origins
- status = ncmex('attcopy', ncid, varid, 'attname', ncout, varout)
- status = mexcdf('attcopy', ncid, varid, 'attname', ncout, varout)
- status = mexcdf53('attcopy', ncid, varid, 'attname', ncout, varout)
- int ncattcopy(int ncid, int varid, char * name, int ncout, int varout)
- subroutine ncacpy(integer ncid, integer varid, character*(*) attname, integer ncout, integer varout, integer rcode)

Delete an Attribute

Delete an attribute from a NetCDF file or variable.

NetCDF Language
- theAtt = [];

Arguments
- theAtt -- The "ncatt" attribute object.
Errors
- File is read-only.
- Not a NetCDF attribute.
- Not an open NetCDF file.

Example

This example opens the NetCDF file named 'foo.nc' and deletes
the "description" global attribute. If an error occurs, the empty-matrix
[] is returned.

nc = netcdf('foo.nc', 'write')
if isempty(nc), error('## Bad netcdf operation.'), end
nc.description = [];

Origins
- status = ncmex('attdel', ncid, varid, 'attname')
- status = mexcdf('attdel', ncid, varid, 'attname')
- status = mexcdf53('attdel', ncid, varid, 'attname')
- int ncattdel(int ncid, int varid, char * name)
- subroutine ncadel(integer ncid, integer varid, character*(*) attname, integer rcode)

NetCDF Toolbox Interface Descriptions

NetCDF File Operations

Create a NetCDF file

NetCDF Language

Arguments

Errors

Example

Origins

Open a NetCDF File for Access

NetCDF Language

Arguments

Errors

Example

Origins

Put an Open NetCDF File into Define-Mode

NetCDF Language

Arguments

Errors

Example

Origins

Put an Open NetCDF File into Data-Mode

NetCDF Language

Arguments

Errors

Example

Origins

Close an Open NetCDF File

NetCDF Language

Arguments

Errors

Example

Origins

Inquire about an Open NetCDF File

NetCDF Language

Arguments

Errors

Example

Origins

Synchronize an Open NetCDF File to Disk

NetCDF Language

Arguments

Errors

Example

Origins

Back Out of Recent Definitions

NetCDF Language

Arguments

Errors

Example

Origins

Set Fill Mode for Writes

NetCDF Language

Arguments

Errors

Example

Origins

NetCDF Dimension Operations

Create a Dimension

NetCDF Language

Arguments

Errors

Example

Origins

Get a Dimension from its Name

NetCDF Language

Arguments

Errors

Example

Origins

Inquire about a Dimension

NetCDF Language

Arguments

Errors

Example

Origins

Rename a Dimension

NetCDF Language

Arguments

Errors

Example