| • |
|
|
|
|||
|
||||
This chapter presents the interfaces of the netCDF routines that deal with a netCDF file as a whole.
A netCDF file that has not yet been opened can only be referred to by its file name. Once a netCDF file is opened, it is referred to by a netCDF ID, which is a small nonnegative integer returned when you create or open the file. A netCDF ID is much like a file descriptor in C or a logical unit number in FORTRAN. In any single program, the netCDF IDs of distinct open netCDF files are distinct. A single netCDF file may be opened multiple times and will then have multiple distinct netCDF IDs; however at most one of the open instances of a single netCDF file should permit writing. When an open netCDF file is closed, the ID is no longer associated with a netCDF file.
The operations supported on a netCDF file as a single object are:
After a summary of conventions used in describing the netCDF C and FORTRAN interfaces, the rest of this chapter presents the interfaces for these operations.
Each interface description for a particular netCDF function in this and later chapters contains:
The C function prototypes specify the order and type of each formal parameter and conform to the ANSI C standard. For FORTRAN a similar syntax is used to concisely present the order and types of FORTRAN formal parameters. In the few cases in which a single C function corresponds to two FORTRAN functions, the FORTRAN functions prototypes are presented together.
The function nccreate (or NCCRE for FORTRAN) creates
a new netCDF file, returning a netCDF ID that can subsequently be used to refer
to the netCDF file. The new netCDF file is placed in define mode.
In case of an error, nccreate returns -1; NCCRE returns
a nonzero value in rcode. Possible causes of errors include::
NC_NOCLOBBER
(or NCNOCLOB).int nccreate (const char* filename, int cmode);
filenamecmodeNC_CLOBBER or NC_NOCLOBBER.
These constants are defined in the include file named `netcdf.h'.
NC_CLOBBER means that even if the file already exists, you want
to create a new file with the same name, erasing the old file's contents.
NC_NOCLOBBER means you want to create a new netCDF file only
if the given file name does not refer to a file that already exists.In this example we create a netCDF file named `foo.nc'; we want the file to be created in the current directory only if a file with that name does not already exist:
#include <netcdf.h>
...
int ncid;
...
ncid = nccreate("foo.nc", NC_NOCLOBBER);
INTEGER FUNCTION NCCRE (CHARACTER*(*) FILENAME, INTEGER CMODE,
INTEGER RCODE)
FILENAMECMODENCCLOB or NCNOCLOB.
These constants are defined in the include file `netcdf.inc'.
NCCLOB means that even if the file already exists, you want to
create a new file with the same name, erasing the old file's contents.
NCNOCLOB means you want to create a new netCDF file only if the
given file name does not refer to a file that already exists.RCODEIn this example we create a netCDF file named `foo.nc', assuming we want the file to be created in the current directory only if a file with that name does not already exist:
INCLUDE 'netcdf.inc'
...
INTEGER NCID
...
NCID = NCCRE('foo.nc', NCNOCLOB, RCODE)
The function ncopen
(or NCOPN for FORTRAN) opens an existing netCDF file for access.
In case of an error, ncopen returns -1; NCOPN returns
a nonzero value in rcode. Possible causes of errors include::
NC_WRITE or NC_NOWRITE.int ncopen(const char* filename,int mode);
filenamemodeNC_WRITE, to open the file for writing, or NC_NOWRITE,
to open the file read-only. "Writing" means any kind of change to
the file, including appending or changing data, adding or renaming dimensions,
variables, and attributes, or deleting attributes. Here is an example using ncopen to open an existing
netCDF file named `foo.nc' for reading:
#include <netcdf.h>
...
int ncid;
...
ncid = ncopen("foo.nc", NC_NOWRITE);
INTEGER FUNCTION NCOPN(CHARACTER*(*) FILENAME,
+ INTEGER RWMODE,
+ INTEGER RCODE)
FILENAMERWMODENCWRITE, to open the file for writing, or NCNOWRIT,
to open the file read-only. "Writing" means any kind of change to
the file, including appending or changing data, adding or renaming dimensions,
variables, and attributes, or deleting attributes.RCODE Here is an example of using NCOPN
to open an existing netCDF file named `foo.nc' for reading:
INCLUDE 'netcdf.inc'
...
INTEGER NCID
...
NCID = NCOPN('foo.nc', NCNOWRIT, RCODE)
The function ncredef (or NCREDF for
FORTRAN) puts an open netCDF file into define mode, so dimensions, variables,
and attributes can be added or renamed and attributes can be deleted.
In case of an error, ncredef returns -1; NCREDF returns
a nonzero value in rcode. Possible causes of errors include::
C Interface: ncredef
int ncredef(int ncid);
ncidncopen or nccreate. Here is an example using ncredef
to open an existing NetCDF file named `foo.nc' and put it into
define mode:
#include <netcdf.h>
...
int ncid;
...
ncid = ncopen("foo.nc", NC_WRITE); /* open file */
...
ncredef(ncid); /* put in define mode */
SUBROUTINE NCREDF(INTEGER NCID, INTEGER RCODE)
NCIDNCOPN or NCCRE.RCODE Here is an example of using NCREDF
to open an existing netCDF file named `foo.nc' and put it into
define mode:
INCLUDE 'netcdf.inc'
...
INTEGER NCID
...
NCID = NCOPN('foo.nc', NCWRITE, RCODE)
...
CALL NCREDF(NCID, RCODE)
The function ncendef (or NCENDF for
FORTRAN) takes an open netCDF file out of define mode. The changes made to the
netCDF file while it was in define mode are checked and committed to disk if
no problems occurred. The netCDF file is then placed in data mode, so variable
data can be read or written.
This call can be expensive, since it involves initializing non-record variables and copying data under some circumstances. See section NetCDF File Structure and Performance, for a more extensive discussion.
In case of an error, ncendef returns -1; NCENDF returns
a nonzero value in rcode. Possible causes of errors include:
int ncendef(int ncid);
ncidncopen or nccreate. Here is an example using ncendef to finish the
definitions of a new netCDF file named `foo.nc' and put it into
data mode:
#include <netcdf.h>
...
int ncid;
...
ncid = nccreate("foo.nc", NC_NOCLOBBER);
... /* create dimensions, variables, attributes */
ncendef(ncid); /*leave define mode*/
SUBROUTINE NCENDF(INTEGER NCID, INTEGER RCODE)
NCIDNCOPN or NCCRE.RCODE Here is an example using NCENDF
to finish the definitions of a new netCDF file named `foo.nc' and
put it into data mode:
INCLUDE 'netcdf.inc'
...
INTEGER NCID
...
NCID = NCCRE('foo.nc', NCNOCLOB, RCODE)
... ! create dimensions, variables, attributes
CALL NCENDF(NCID, RCODE)
The function ncclose (or NCCLOS for
FORTRAN) closes an open netCDF file. If the file is in define mode, ncendef
(or NCENDF) will be called before closing. (In this case, if ncendef
[or NCENDF] returns an error, ncabort [or NCABOR]
will automatically be called to restore the file to the consistent state before
define mode was last entered.) After an open netCDF file is closed, its netCDF
ID will be reassigned to the next netCDF file that is opened or created.
In case of an error, ncclose returns -1; NCCLOS returns
a nonzero value in rcode. Possible causes of errors include:
ncendef
(or NCENDF) failed.int ncclose(int ncid);
ncidncopen or nccreate. Here is an example using ncclose
to finish the definitions of a new netCDF file named `foo.nc' and
release its netCDF ID:
#include <netcdf.h>
...
int ncid;
...
ncid = nccreate("foo.nc", NC_NOCLOBBER);
... /* create dimensions, variables, attributes */
ncclose(ncid); /* close netCDF file */
SUBROUTINE NCCLOS(INTEGER NCID, INTEGER RCODE)
NCIDNCOPN or NCCRE.RCODE Here is an example using NCCLOS
to finish the definitions of a new netCDF file named `foo.nc' and
release its netCDF ID:
INCLUDE 'netcdf.inc'
...
INTEGER NCID, RCODE
...
NCID = NCCRE('foo.nc', NCNOCLOB, RCODE)
... ! create dimensions, variables, attributes
CALL NCCLOS(NCID, RCODE)
The function ncinquire
(NCINQ for FORTRAN) returns information about an open netCDF file,
given its netCDF ID. It can be called from either define mode or data mode.
It returns values for the number of dimensions, the number of variables, the
number of global attributes, and the dimension ID of the dimension defined with
unlimited size, if any. No I/O is required when this or any other `inquire'
function in the netCDF interface is called, since the functions merely return
information that is stored in a table for each open netCDF file.
In case of an error, ncinquire returns -1; NCINQ
returns a nonzero value in rcode. Possible cause of errors includes:
int ncinquire(int ncid, int* ndims, int* nvars, int* ngatts,
int* recdim);
ncidncopen or nccreate.
ndimsnvarsngattsrecdimrecdim. If this parameter is given as `0'
(a null pointer), the record dimension ID will not be returned so no variable
to hold this information needs to be declared. Here is an example using ncinquire
to find out about a netCDF file named `foo.nc':
#include <netcdf.h>
...
int ncid, ndims, nvars, ngatts, recdim;
...
ncid = ncopen("foo.nc", NC_NOWRITE);
...
ncinquire(ncid, &ndims, &nvars, &ngatts, &recdim);
SUBROUTINE NCINQ(INTEGER NCID, INTEGER NDIMS, INTEGER NVARS,
* INTEGER NGATTS, INTEGER RECDIM, INTEGER RCODE)
NCIDNCOPN or NCCRE.NDIMSNVARSNGATTSRECDIMRECDIM.RCODE Here is an example using NCINQ
to find out about a netCDF file named `foo.nc':
INCLUDE 'netcdf.inc'
...
INTEGER NCID, NDIMS, NVARS, NATTS, RECDIM, RCODE
...
NCID = NCOPN('foo.nc', NCNOWRIT, RCODE)
...
CALL NCINQ(NCID, NDIMS, NVARS, NATTS, RECDIM, RCODE)
The function ncsync
(or NCSNC for FORTRAN) makes sure that the disk copy of a netCDF
file open for writing is current. The netCDF file must be in data mode. A netCDF
file in define mode is synchronized to disk only when ncendef (or
NCENDF) is called. A process that is reading a netCDF file that
another process is writing can also call ncsync (or NCSNC
for FORTRAN) to get updated with the changes made by the writing process (e.g.
the number of records written), without having to close and reopen the file.
It can be expensive in computer resources to always synchronize to disk after every write of variable data or change of an attribute value. There are two reasons you might want to synchronize after writes:
ncsync; to accomplish this, the reading process must call
ncsync.Data is automatically synchronized to disk when a netCDF file is closed, or whenever you leave define mode.
In case of an error, ncsync returns -1; NCSNC returns
a nonzero value in rcode. Possible causes of errors include:
int ncsync(int ncid);
ncidncopen or nccreate. Here is an example using ncsync
to synchronize the disk writes of a netCDF file named `foo.nc':
#include <netcdf.h>
...
int ncid;
...
ncid = ncopen("foo.nc", NC_WRITE); /* open for writing */
... /* write data or change attributes */
ncsync(ncid); /* synchronize to disk */
SUBROUTINE NCSNC(INTEGER NCID, INTEGER RCODE)
NCIDNCOPN or NCCRE.RCODE Here is an example using NCSNC
to synchronize the disk writes of a netCDF file named `foo.nc':
INCLUDE 'netcdf.inc'
...
INTEGER NCID, RCODE
...
NCID = NCOPN('foo.nc', NCWRITE, RCODE)
...
* write data or change attributes
...
CALL NCSNC(NCID, RCODE)
The function ncabort (or NCABOR for
FORTRAN), if not in define mode, closes the netCDF file. If the file is being
created and is still in define mode, the file is deleted. If define mode was
entered by a call to ncredef (or NCREDF), the netCDF
file is restored to its state before definition mode was entered and the file
is closed. The main reason for calling ncabort (or NCABOR)
is to restore the netCDF file to a known consistent state in case anything goes
wrong during the definition of new dimensions, variables, or attributes.
This function is called automatically if ncclose (or NCCLOS)
is called from define mode and the call to leave define mode before closing
fails.
In case of an error, ncabort returns -1; NCABOR returns
a nonzero value in rcode. Possible causes of errors include:
int ncabort(int ncid);
ncidncopen or nccreate. Here is an example using ncabort
to back out of redefinitions of a file named `foo.nc':
#include <netcdf.h>
...
int ncid;
...
ncid = ncopen("foo.nc", NC_WRITE); /* open for writing */
...
ncredef(ncid); /* enter define mode */
...
if (ncdimdef(ncid, "lat", 18L) == -1)
ncabort(ncid); /* define failed, abort */
SUBROUTINE NCABOR(INTEGER NCID, INTEGER RCODE)
NCIDNCOPN or NCCRE.RCODE Here is an example using NCABOR
to back out of redefinitions of a file named `foo.nc':
INCLUDE 'netcdf.inc'
...
INTEGER NCID, RCODE, LATID
...
NCID = NCOPN('foo.nc', NCWRITE, RCODE)
...
CALL NCREDF(NCID, RCODE)
...
LATID = NCDDEF(NCID, 'LAT', 18, RCODE)
IF (RCODE .EQ. -1) THEN ! dimension definition failed
CALL NCABOR(NCID, RCODE) ! abort redefinitions
ENDIF
...
These calls are intended
for advanced usage, to optimize writes under some circumstances described below.
The function ncsetfill (or NCSFIL for FORTRAN) sets
the fill mode for an netCDF file open for writing and returns
the current fill mode. The fill mode can be specified as either NC_FILL
or NC_NOFILL (NCFILL or NCNOFILL for
FORTRAN). The default behavior corresponding to NC_FILL is that
data is pre-filled with fill values, that is fill values are written when you
create non-record variables or when you write a value beyond data that hasn't
been written yet. This makes it possible to detect attempts to read data before
it was written. See section Fill Values, for more information on the use of
fill values. See section Attribute Conventions, for information about how
to define your own fill values.
The behavior corresponding to NC_NOFILL overrides the default
behavior of prefilling data with fill values. This can be used to enhance performance,
because it avoids the duplicate writes that occur when the netCDF library writes
fill values that are immediately overwritten with data.
A value indicating which mode the netCDF file was already in is returned. You can use this value to temporarily change the fill mode of an open netCDF file and then restore it to the previous mode.
After you turn on NC_NOFILL mode for an open netCDF file, you
must be certain to write valid data in all the positions that will later be
read. Note that NC_NOFILL mode is only a transient property of
a netCDF file open for writing: if you close and reopen the file, it will revert
to the default behavior. You can also revert to the default behavior by calling
ncsetfill (or NCSFIL for FORTRAN) again to explicitly
set the fill mode to NC_FILL.
There are three situations where it is advantageous to set nofill mode:
ncendef (NCENDF for FORTRAN),
and then write completely all non-record variables and the initial
records of all the record variables you want to initialize.ncendef (NCENDF
for FORTRAN), then write all the new variables completely.If the netCDF file has an unlimited dimension and the last record was written
while in NC_NOFILL mode, then the file will be 4 bytes longer than
if NC_NOFILL mode wasn't set, but this will be completely transparent
if you access the data only through the netCDF interfaces.
In case of an error, ncsetfill returns -1; NCSFIL
returns a nonzero value in rcode. Possible causes of errors include:
NC_NOFILL nor NC_FILL
(neither NCNOFILL nor NCFILL for FORTRAN).int ncsetfill(int ncid, int fillmode);
ncidncopen or nccreate.fillmodeNC_NOFILL or NC_FILL.ncsetfillNC_NOFILL
or NC_FILL. Here is an example using ncsetfill
to set nofill mode for subsequent writes of a netCDF file named `foo.nc':
#include <netcdf.h>
...
int ncid;
...
ncid = ncopen("foo.nc", NC_WRITE); /* open for writing */
... /* write data with default prefilling behavior */
ncsetfill(ncid, NC_NOFILL); /* set nofill mode */
... /* write data with no prefilling */
INTEGER FUNCTION NCSFIL(INTEGER NCID, INTEGER FILLMODE,
+ INTEGER RCODE)
NCIDNCOPN or NCCRE.FILLMODENCNOFILL or NCFILL.RCODENCSFILNCNOFILL
or NCFILL. Here is an example using NCSFIL
to set nofill mode for a netCDF file named `foo.nc':
INCLUDE 'netcdf.inc'
...
INTEGER NCID, RCODE, OMODE
...
NCID = NCOPN('foo.nc', NCWRITE, RCODE)
...
* write data with default prefilling behavior
...
OMODE = NCSFIL(NCID, NCNOFILL, RCODE)
...
* write data with no prefilling
...
| Contact Us • Site Map • Search • Terms and Conditions • Privacy Policy • Participation Policy | ||||||
|
||||||
