MEXNC has support for the NetCDF-3 API and is compatible with NetCDF versions 3.0 and above. Important changes from the previous release include:
There is a one to one correspondence between NetCDF-3 API calls and new mexfile functions. Any user should be able to determine exactly what the mexfile will do (no more, no less) by reading the man page for the NetCDF-3 API. All mexnc(netcdf-3) routines return error codes that are true to the NetCDF-3 API.
The one-to-one correspondence
allows for a somewhat more flexible data model to be used
from matlab. Previously, only double or
char attributes could be created from matlab,
and now one can create
float,
int,
short int,
uchar,
and
schar
attributes just as easily.
Mexcdf53 allowed for
double,
float,
int,
short int,
and
byte
variables could be written to, but the inputs to
variable I/O routines had to be
double
or
char.
Mexnc now allows variable I/O inputs of the classes
single,
int16,
int8,
and
uint8
as well as
double
or
char.
>> test_mexnc;
The m-file that specifically tests large file support
is test_lfs.m.
Compiling the mexfile against NetCDF versions 3.0.0
through 3.5.1 works just fine, you just won't be able
to create/read/write NetCDF files with Large File Support.
One big difference between mexnc and mexcdf53 is that mexnc(netcdf-3) function calls do not scale the data when either reading or writing. That little detail is left up to wrapper routines, such as SNCTOOLS. Why? Because it greatly increases the number of lines of C code necessary to support it . More lines of C code to support just one operation means much less readable C code and a greater chance of errors. It also kind of strays away from keeping a 1-1 correspondence between the NetCDF library and the matlab interface, as the matlab routines were doing much more than their corresponding NetCDF library routines. But the mexnc(netcdf-2) (formerly known as mexcdf53) codes that actually did scale the data have not been thrown out, so backwards compatibility is maintained.
Confused? Ok, suppose you have m-files that made use of such mexcdf(netcdf-2) function calls as
mexcdf ('varput', ...) ;
or
mexcdf ('varget', ...);
Those routines would autoscale the data,
meaning they relied upon the existence of the
scale_factor and add_offset
attributes for scaling information. These function calls
still available to you,
but now they are routed through a translation m-file called
mexcdf53.m that turns those function
calls into
mexnc ('varput', ...);
and
mexnc ('varget', ...);
and since the C code base for the netcdf-2 routines is the
same as before, the data is then scaled just as it
was before. But, if you use the netcdf-3 api, i.e.
mexnc ('var_get_double', ...);
or
mexnc ('var_put_double', ...);
or any of their variants, the data will NOT be scaled.
Trust me, it's better this way, as it retrieves the data
exactly as you would expect of the NetCDF library routine.
Please read the README for more details on changes.
An updated version of SNCTOOLS has been released to take advantage of the NetCDF-3 API. It will NOT work with previous versions of mexcdf.
As you will see below, there is a very close correspondence between mexnc calls and NetCDF C API function calls, so most questions about the mexnc API can be answered by consulting the NetCDF documentation.
From the MATLAB prompt, if you type
>> help mexnc
you will get
function [varargout] = mexnc ( varargin )
% MEXNC MATLAB gateway to NetCDF interface.
% MEXNC is a gateway to the NetCDF interface. To use this
% function, you should be familiar with the information about
% NetCDF contained in the User's Guide for NetCDF. This
% documentation may be obtained from Unidata at
% <http://my.unidata.ucar.edu/content/software/netcdf/docs.html>;.
%
% The general syntax for MEXNC is
% mexnc(funcstr,param1,param2,...). There is a one-to-one
% correspondence between functions in the NetCDF 4.0 and 3.0 API and
% valid values for funcstr. For example, mexnc('close',ncid)
% corresponds to the C library call nc_close (ncid). MEXNC was
% originally built on top of the NetCDF 2.4 API, however, and the
% correspondence between the NetCDF 2.4 API and values of funcstr
% is somewhat fuzzier. It's recommended that new code use the 3.0
% or higher API.
%
% Syntax conventions
% ------------------
% The return status of a NetCDF-3 MEXNC operation will correspond
% exactly to the return status of the corresponding NetCDF API
% function. You can use the 'STRERROR' function below to get a string
% description of return status. The return status values of NetCDF-2
% MEXCDF operations are not as well defined. Usually they are -1
% in case of an error.
%
% "ncid" refers to the NetCDF file ID, "dimid" refers to a NetCDF
% dimension ID, and "varid" refers to a NetCDF variable ID.
%
% NetCDF files use C-style ordering for multidimensional arrays,
% while MATLAB uses FORTRAN-style ordering. This means that the size
% of the MATLAB array must be flipped relative to the defined
% dimension sizes of the HDF data set. For example, if the NetCDF
% data set has dimensions 3-by-4-by-5, then the equivalent MATLAB
% array has size 5-by-4-by-3. The PERMUTE command is useful for
% making any necessary conversions when reading from or writing to
% NetCDF data sets.
%
% Dataset functions
% --------------
% error_message = mexnc ( 'strerror', error_code );
% Returns a reference to an error message string corresponding
% to an integer netCDF error status or to a system error
% number, presumably returned by a previous call to some other
% netCDF function.
%
% lib_version = mexnc ( 'inq_libvers' );
% Returns a string identifying the version of the netCDF library
% and when it was built.
%
% [ncid, status] = mexnc ( 'create', filename, access_mode );
% The access mode can be a string such as 'clobber' or
% 'noclobber', but it is preferable to use the helper functions
%
% nc_clobber_mode
% nc_noclobber_mode
% nc_share_mode
% nc_64bit_offset_mode (new in NetCDF 3.6)
%
% These correspond to named constants in the <netcdf.h> file.
% Check the NetCDF User's Guide for more information. You may
% also combine any of these with the bitor function, e.g.
% >> access_mode = bitor ( nc_write_mode, nc_share_mode );
%
% [ncid, status] = mexnc ( 'open', filename, access_mode );
% Opens an existing netCDF dataset for access. Access modes
% available are
%
% nc_nowrite_mode
% nc_write_mode
% nc_share_mode
%
% status = mexnc ( 'close', ncid );
% Closes a previously-opened NetCDF file.
%
% status = mexnc ( 'redef', ncid );
% Puts an open NetCDF dataset into define mode, so dimensions,
% variables, and attributes can be added or renamed and
% attributes can be deleted. This function is not needed if the
% file is opened in nc_hdf5_mode.
%
% status = mexnc ( 'end_def', ncid );
% Takes an open NetCDF file out of define mode.
%
% [ndims, nvars, ngatts, unlimdim, status] = mexnc ( 'inq', ncid );
% Inquires as to the number of dimensions, number of variables,
% number of global attributes, and the unlimited dimension (if
% any).
%
% [unlimdim, status] = mexnc ( 'inq_unlimdim', ncid );
% Inquire as to the unlimited dimension. As of NetCDF 4.0, this
% will return just the first unlimited dimension.
%
% [status] = mexnc ( 'sync', ncid );
% Offers a way to synchronize the disk copy of a netCDF dataset
% with in-memory buffers
%
% [status] = mexnc ( 'abort', ncid );
% One does not really need this function. Just ignore it.
%
% Dimension functions
% --------------
% [dimid, status] = mexnc ( 'def_dim', ncid, name, length );
% Adds a new dimension to an open netCDF dataset in define
% mode. It returns a dimension ID, given the netCDF ID, the
% dimension name, and the dimension length.
%
% [dimid, status] = mexnc ( 'inq_dimid', ncid, name );
% Returns (as an argument) the ID of a netCDF dimension,
% given the name of the dimension. If ndims is the number
% of dimensions defined for a netCDF dataset, each dimension
% has an ID between 0 and ndims-1.
%
% [name, length, status] = mexnc ( 'inq_dim', ncid, dimid );
% Returns information about a netCDF dimension including its
% name and its length. The length for the unlimited dimension,
% if any, is the number of records written so far.
%
% [status] = mexnc ( 'rename_dim', ncid, dimid, name );
% Renames an existing dimension in a netCDF dataset open for
% writing.
%
% General Variable functions
% --------------------------
% [varid, status] = mexnc ( 'def_var', ncid, name, datatype, ndims, dimids );
% Adds a new variable to a netCDF dataset. In order to define
% a singleton variable (one with one element and no defined
% dimensions, set ndims to 0 and dimids = [].
%
% [varid, status] = mexnc ( 'inq_varid', ncid, varname );
% Returns the ID of a netCDF variable, given its name.
%
% [varname, datatype, ndims, dimids, natts, status] = mexnc ( 'inq_var', ncid, varid );
% Returns other information about a NetCDF variable given its ID.
%
% status = mexnc ( 'rename_var', ncid, varid, new_varname );
% Changes the name of a netCDF variable.
%
% Variable I/O functions
% ----------------------
% Any routines marked "*XXX" constitute a suite of routines
% that are specialized for various datatypes. Possibilities
% for XXX include "text", "uchar", "schar", "short", "int",
% "float", and "double". The data is automatically converted
% to the external type of the specified variable. Since
% MATLAB's default datatype is double precision, most of the
% time you would want XXX to be "double"
%
% Because of the difference between row-major order (C) and
% column-major order (matlab), you should transpose or permute
% your data before passing it into or after receiving it from
% these I/O routines. See the User's Guide for examples.
%
% MAJOR DIFFERENCE BETWEEN THESE FUNCTIONS AND MexCDF(netcdf-2).
% These functions do not make use of the add_offset and
% scale_factor attributes. That job is left to any user
% routines written as a wrapper to MexCDF.
%
% The varid must be the actual varid, substituting the name
% of the variable is not allowed.
%
% status = mexnc ( 'put_var_XXX', ncid, varid, data );
% PUT_VAR_XXX writes an entire variable.
%
% [data, status] = mexnc ( 'get_var_XXX', ncid, varid );
% PUT_VAR_XXX's alter ego. Retrieves all the data from a
% variable and casts it into the requested datatype.
%
% status = mexnc ( 'put_vara_XXX', ncid, varid, start_coord,
% count_coord, data );
% Writes a hyperslab of data to a netcdf variable. The
% start_coord specifies the indices where the write operation
% is to begin, and the count_coord specifies the extent
% of the write along each dimension.
%
% [data, status] = mexnc ( 'get_vara_XXX', ncid, varid, start_coord, count_coord );
% Retrieves a hyperslab from a variable, starting at a specific
% index coordinate and with a count extent along each dimension.
%
% status = mexnc ( 'put_vars_XXX', ncid, varid,
% start_coord, count_coord, stride_coord, data );
% Writes a hyperslab of data to a netcdf variable. The "stride"
% or interval between accessed values) must be specified for
% each dimension.
%
% [data, status] = mexnc ( 'get_vars_XXX', ncid, varid, start_coord,
% count_coord, stride_coord );
% Retrieves a strided hyperslab from a variable, given a starting
% coordinate, a given count of elements to read along each dimension,
% and the stride between accessed elements along each dimension.
%
% status = mexnc ( 'put_var1_XXX', ncid, varid, start_coord, data );
% Only a single value is to be written. The coordinate of that
% value must be specified.
%
% [data, status] = mexnc ( 'get_var1_XXX', ncid, varid, start_coord );
% Only a single value is to be read. The coordinate of that
% value must be specified.
%
% status = mexnc ( 'put_varm_XXX', ncid, varid, start_coord,
% count_coord, stride_coord, imap_coord, data );
% Writes a hyperslab of data to a netcdf variable. Similar to
% stride I/O, except that an additional index mapping vector
% is provided to specify the in-memory arrangement of the
% data values.
%
% [data, status] = mexnc ( 'get_varm_XXX', ncid, varid, start_coord,
% count_coord, stride_coord, imap_coord );
% Retrieves a memory-mapped strided hyperslab from a variable,
% given a starting coordinate, a given count of elements to
% read along each dimension, the stride between accessed
% elements along each dimension, and the in-memory arrangement
% of the data values. This routine is severly complicated by
% the row-major-order-column-major-order problem. Please see
% the User Guide for examples, and then remember that the
% answer you get back is transposed.
%
% Attribute functions
% -------------------
% Any routines marked "*XXX" constitute a suite of routines
% that are specialized for various datatypes. Possibilities
% for XXX include "uchar", "schar", "short", "int", "float",
% and "double". The data is automatically converted to the
% external type of the specified attribute.
%
% status = mexnc ( 'copy_att', ncid_in, varid_in, attname, ncid_out, varid_out );
% Copies an attribute from one variable to another, possibly
% within the same netcdf file.
%
% status = mexnc ( 'del_att', ncid, varid, attname );
% Deletes an attribute.
%
% [att_value, status] = mexnc ( 'get_att_XXX', ncid, varid, attname );
% Retrieves an attribute value.
%
% [datatype, attlen, status] = mexnc ( 'inq_att', ncid, varid, attname );
% Retrieves the datatype and length of an attribute given its
% name.
%
% [attid, status] = mexnc ( 'inq_attid', ncid, varid, attname );
% Retrieves the numeric id of an attribute given its name.
%
% status = mexnc ( 'put_att_XXX', ncid, varid, attname, datatype, attlen, attvalue );
% Writes an attribute value. The "datatype" attribute can be
% either the numeric value of the external datatype (e.g. 6
% for nc_double), or just the string equivalent (e.g. "double").
%
% status = mexnc ( 'rename_att', ncid, varid, old_attname, new_attname );
% Renames an attribute.
%
%
% NetCDF 2.4 API
% --------------
%
% These functions constitute the time-tested mexcdf that was build on
% top of the NetCDF 2.4 API. They continue to work, but in some cases operate
% somewhat differently than the MexCDF(netcdf-3) functions.
%
% [cdfid, rcode] = mexnc('CREATE', 'path', cmode)
% cdfid = mexnc('OPEN', 'path', mode)
% status = mexnc('REDEF', cdfid)
% status = mexnc('ENDEF', cdfid)
% [ndims, nvars, natts, recdim, status] = mexnc('INQUIRE', cdfid)
% status = mexnc('SYNC', cdfid)
% status = mexnc('ABORT', cdfid)
% status = mexnc('CLOSE', cdfid)
%
% status = mexnc('DIMDEF', cdfid, 'name', length)
% [dimid, rcode] = mexnc('DIMID', cdfid, 'name')
% [name, length, status] = mexnc('DIMINQ', cdfid, dimid)
% status = mexnc('DIMRENAME', cdfid, 'name')
%
% status = mexnc('VARDEF', cdfid, 'name', datatype, ndims, [dim])
% [varid, rcode] = mexnc('VARID', cdfid, 'name')
% [name, datatype, ndims, dimids, natts, status] = mexnc('VARINQ', cdfid, varid)
% status = mexnc('VARPUT1', cdfid, varid, coords, value, autoscale)
% [value, status] = mexnc('VARGET1', cdfid, varid, coords, autoscale)
% status = mexnc('VARPUT', cdfid, varid, start, count, value, autoscale)
% [value, status] = mexnc('VARGET', cdfid, varid, start, count, autoscale)
% status = mexnc('VARPUTG', cdfid, varid, start, count, stride, [], value, autoscale)
% [value, status] = mexnc('VARGETG', cdfid, varid, start, count, stride, [], autoscale)
% status = mexnc('VARRENAME', cdfid, varid, 'name')
%
% status = mexnc('ATTPUT', cdfid, varid, 'name', datatype, len, value)
% [datatype, len, status] = mexnc('ATTINQ', cdfid, varid, 'name')
% [value, status] = mexnc('ATTGET', cdfid, varid, 'name')
% status = mexnc('ATTCOPY', incdf, invar, 'name', outcdf, outvar)
% [name, status] = mexnc('ATTNAME', cdfid, varid, attnum)
% status = mexnc('ATTRENAME', cdfid, varid, 'name', 'newname')
% status = mexnc('ATTDEL', cdfid, varid, 'name')
%
% status = mexnc('RECPUT', cdfid, recnum, [data], autoscale, recdim)
% [data, status] = mexnc('RECGET', cdfid, recnum, autoscale, recdim)
% [recvarids, recsizes, status] = mexnc('RECINQ', cdfid, recdim)
%
% len = mexnc('TYPELEN', datatype)
% old_fillmode = mexnc('SETFILL', cdfid, fillmode)
%
% old_ncopts = mexnc('SETOPTS', ncopts)
% ncerr = mexnc('ERR')
% code = mexnc('PARAMETER', 'NC_...')
%
%
% The general framework of this document was shamelessly lifted from
% the help information for the HDFSD interface. Many of the function
% descriptions were lifted nearly verbatim from the NetCDF online
% documentation.
%
% AUTHOR:
% John Evans wrote the MexNC(netcdf-3) portion.
% Chuck Denham wrote the original MexCDF(netcdf-2).
%
John Evans: IMCS Rutgers University
