netcdf.3

一个用来实现偏微分方程中网格的计算库

(\fBNC_INT\fR corresponds to \fBNC_LONG\fR in version 2, to specify a
32-bit integer).
.TP
int \fIdimids\fP[]
is a vector of dimension ID's and defines the shape of a netCDF variable.
The size of the vector shall be greater than or equal to the
rank (i.e. the number of dimensions) of the variable (\fIndims\fP).
The vector shall be ordered by the speed with which a dimension varies:
\fIdimids\fP[\fIndims\fP-1]
shall be the dimension ID of the most rapidly
varying dimension and
\fIdimids\fP[0]
shall be the dimension ID of the most slowly
varying dimension.
The maximum possible number of
dimensions for a variable is given by the symbolic constant
\fBNC_MAX_VAR_DIMS\fR.
.TP
int \fIdimid\fP
is the ID of a netCDF dimension.
netCDF dimension ID's are allocated sequentially from the 
non-negative
integers beginning with 0.
.TP
int \fIndims\fP
is either the total number of dimensions in a netCDF dataset or the rank
(i.e. the number of dimensions) of a netCDF variable.
The value shall not be negative or greater than the symbolic constant 
\fBNC_MAX_VAR_DIMS\fR.
.TP
int \fIvarid\fP
is the ID of a netCDF variable or (for the attribute-access functions) 
the symbolic constant
\fBNC_GLOBAL\fR,
which is used to reference global attributes.
netCDF variable ID's are allocated sequentially from the 
non-negative
integers beginning with 0.
.TP
int* \fInatts\fP
is the number of global attributes in a netCDF dataset  for the
\fBnc_inquire(\|)\fR
function or the number
of attributes associated with a netCDF variable for the
\fBnc_varinq(\|)\fR
function.
.TP
const size_t \fIindex\fP[]
specifies the indicial coordinates of the netCDF data value to be accessed.
The indices start at 0;
thus, for example, the first data value of a
two-dimensional variable is (0,0).
The size of the vector shall be at least the rank of the associated
netCDF variable and its elements shall correspond, in order, to the
variable's dimensions.
.TP
const size_t \fIstart\fP[]
specifies the starting point
for accessing a netCDF variable's data values
in terms of the indicial coordinates of 
the corner of the array section.
The indices start at 0;
thus, the first data
value of a variable is (0, 0, ..., 0).
The size of the vector shall be at least the rank of the associated
netCDF variable and its elements shall correspond, in order, to the
variable's dimensions.
.TP
const size_t \fIcount\fP[]
specifies the number of indices selected along each dimension of the
array section.
Thus, to access a single value, for example, specify \fIcount\fP as
(1, 1, ..., 1).
Note that, for strided I/O, this argument must be adjusted
to be compatible with the \fIstride\fP and \fIstart\fP arguments so that 
the interaction of the
three does not attempt to access an invalid data co-ordinate.
The elements of the
\fIcount\fP vector correspond, in order, to the variable's dimensions.
.TP
const size_t \fIstride\fP[]
specifies the sampling interval along each dimension of the netCDF
variable.   The elements of the stride vector correspond, in order,
to the netCDF variable's dimensions (\fIstride\fP[0])
gives the sampling interval along the most slowly 
varying dimension of the netCDF variable).  Sampling intervals are
specified in type-independent units of elements (a value of 1 selects
consecutive elements of the netCDF variable along the corresponding
dimension, a value of 2 selects every other element, etc.).
A \fBNULL\fR stride argument is treated as (1, 1, ... , 1).
.TP
\fIimap\fP
specifies the mapping between the dimensions of a netCDF variable and
the in-memory structure of the internal data array.  The elements of
the index mapping vector correspond, in order, to the netCDF variable's
dimensions (\fIimap\fP[0] gives the distance
between elements of the internal array corresponding to the most
slowly varying dimension of the netCDF variable).
Distances between elements are specified in type-independent units of
elements (the distance between internal elements that occupy adjacent
memory locations is 1 and not the element's byte-length as in netCDF 2).
A \fBNULL\fR pointer means the memory-resident values have
the same structure as the associated netCDF variable.
.SH "VARIABLE PREFILLING"
.LP
By default, the netCDF interface sets the values of
all newly-defined variables of finite length (i.e. those that do not have
an unlimited, dimension) to the type-dependent fill-value associated with each 
variable.  This is done when \fBnc_enddef(\|)\fR
is called.  The
fill-value for a variable may be changed from the default value by
defining the attribute `\fB_FillValue\fR' for the variable.  This
attribute must have the same type as the variable and be of length one.
.LP
Variables with an unlimited dimension are also prefilled, but on
an `as needed' basis.  For example, if the first write of such a
variable is to position 5, then
positions
0 through 4
(and no others)
would be set to the fill-value at the same time.
.LP
This default prefilling of data values may be disabled by
or'ing the
\fBNC_NOFILL\fR
flag into the mode parameter of \fBnc_open(\|)\fR or \fBnc_create(\|)\fR,
or, by calling the function \fBnc_set_fill(\|)\fR
with the argument \fBNC_NOFILL\fR.
For variables that do not use the unlimited dimension,
this call must
be made before
\fBnc_enddef(\|)\fR.
For variables that
use the unlimited dimension, this call
may be made at any time.
.LP
One can obtain increased performance of the netCDF interface by using 
this feature, but only at the expense of requiring the application to set
every single data value.  The performance
enhancing behavior of this function is dependent on the particulars of
the implementation and dataset format.
The flag value controlled by \fBnc_set_fill(\|)\fR
is per netCDF ID,
not per variable or per write. 
Allowing this to change affects the degree to which
a program can be effectively parallelized.
Given all of this, we state that the use
of this feature may not be available (or even needed) in future
releases. Programmers are cautioned against heavy reliance upon this
feature.
.HP
\fBint nc_setfill(int \fIncid\fP, int \fIfillmode\fP, int* \fIold_fillemode\fP)\fR
.sp
(Corresponds to \fBncsetfill(\|)\fR in version 2)
.sp
Determines whether or not variable prefilling will be done (see 
above).
The netCDF dataset shall be writable.
\fIfillmode\fP is either \fBNC_FILL\fR
to enable prefilling (the
default) or \fBNC_NOFILL\fR
to disable prefilling.
This function returns the previous setting in \fIold_fillmode\fP.
.SH "MPP FUNCTION DESCRIPTIONS"
.LP
Additional functions for use on SGI/Cray MPP machines (_CRAYMPP).
These are used to set and inquire which PE is the base for MPP
for a particular netCDF. These are only relevant when
using the SGI/Cray ``global''
Flexible File I/O layer and desire to have
only a subset of PEs to open the specific netCDF file.
For technical reasons, these functions are available on all platforms.
On a platform other than SGI/Cray MPP, it is as if
only processor available were processor 0.
.LP
To use this feature, you need to specify a communicator group and call
\fBglio_group_mpi(\|)\fR or \fBglio_group_shmem(\|)\fR prior to the netCDF
\fBnc_open(\|)\fR and \fBnc_create(\|)\fR calls.
.HP
\fBint nc__create_mp(const char \fIpath\fP[], int \fIcmode\fP, size_t \fIinitialsize\fP, int \fIpe\fP, size_t* \fIchunksize\fP, int* \fIncid\fP)\fR
.sp
Like \fBnc__create(\|)\fR but allows the base PE to be set.
.sp
The argument \fIpe\fP sets the base PE at creation time. In the MPP
environment, \fBnc__create(\|)\fR and \fBnc_create(\|)\fR set the base PE to processor
zero by default.
.HP
\fBint nc__open_mp(const char \fIpath\fP[], int \fImode\fP, int \fIpe\fP, size_t* \fIchunksize\fP, int* \fIncid\fP)\fR
.sp
Like \fBnc__open(\|)\fR but allows the base PE to be set.
The argument \fIpe\fP sets the base PE at creation time. In the MPP
environment, \fBnc__open(\|)\fR and \fBnc_open(\|)\fR set the base PE to processor
zero by default.
.HP
\fBint nc_inq_base_pe(int \fIncid\fP, int* \fIpe\fP)\fR
.sp
Inquires of the netCDF dataset which PE is being used as the base for MPP use.
This is safe to use at any time.
.HP
\fBint nc_set_base_pe(int \fIncid\fP, int \fIpe\fP)\fR
.sp
Resets the base PE for the netCDF dataset.
Only perform this operation when the affected communicator group
synchronizes before and after the call.
This operation is very risky and should only be contemplated
under only the most extreme cases.
.SH "ENVIRONMENT VARIABLES"
.TP 4
.B NETCDF_FFIOSPEC
Specifies the Flexible File I/O buffers for netCDF I/O when executing
under the UNICOS operating system (the variable is ignored on other
operating systems).
An appropriate specification can greatly increase the efficiency of 
netCDF I/O -- to the extent that it can actually surpass FORTRAN binary 
I/O.
This environment variable has been made a little more generalized,
such that other FFIO option specifications can now be added.
The default specification is \fBbufa:336:2\fP,
unless a current FFIO specification is in operation,
which will be honored.
See UNICOS Flexible File I/O for more information.
.SH "MAILING-LISTS"
.LP
Both a mailing list and a digest are available for
discussion of the netCDF interface and announcements about netCDF bugs,
fixes, and enhancements.
To begin or change your subscription to either the mailing-list or the
digest, send one of the following in the body (not
the subject line) of an email message to "[e-mail]".
Use your email address in place of \[e-mail]\fP.
.sp
To subscribe to the netCDF mailing list:
.RS
\fBsubscribe netcdfgroup \[e-mail]\fR
.RE
To unsubscribe from the netCDF mailing list:
.RS
\fBunsubscribe netcdfgroup \[e-mail]\fR
.RE
To subscribe to the netCDF digest:
.RS
\fBsubscribe netcdfdigest \[e-mail]\fR
.RE
To unsubscribe from the netCDF digest:
.RS
\fBunsubscribe netcdfdigest \[e-mail]\fR
.RE
To retrieve the general introductory information for the mailing list:
.RS
\fBinfo netcdfgroup\fR
.RE
To get a synopsis of other majordomo commands:
.RS
\fBhelp\fR
.RE
.SH "SEE ALSO"
.LP
.BR ncdump (1),
.BR ncgen (1),
.BR netcdf (3),
.BR netcdf_f77 (3),
.BR netcdf_f90 (3)).
.LP
\fInetCDF User's Guide\fP, published
by the Unidata Program Center, University Corporation for Atmospheric
Research, located in Boulder, Colorado.