source: XIOS/dev/branch_openmp/extern/src_netcdf4/ddim.c @ 1501

Last change on this file since 1501 was 409, checked in by ymipsl, 11 years ago

Add improved nectdf internal library src

YM

  • Property svn:eol-style set to native
File size: 14.5 KB
Line 
1/** \file
2Dimension functions
3
4These functions define and inquire about dimensions.
5
6Copyright 2010 University Corporation for Atmospheric
7Research/Unidata. See COPYRIGHT file for more info.
8*/
9
10#include "ncdispatch.h"
11
12/*! \defgroup dimensions Dimensions
13
14Dimensions are used to define the shape of data in netCDF.
15
16Dimensions for a netCDF dataset are defined when it is created, while
17the netCDF dataset is in define mode. Additional dimensions may be
18added later by reentering define mode. A netCDF dimension has a name
19and a length. In a netCDF classic or 64-bit offset file, at most one
20dimension can have the unlimited length, which means variables using
21this dimension can grow along this dimension. In a netCDF-4 file
22multiple unlimited dimensions are supported.
23
24There is a suggested limit (100) to the number of dimensions that can
25be defined in a single netCDF dataset. The limit is the value of the
26predefined macro NC_MAX_DIMS. The purpose of the limit is to make
27writing generic applications simpler. They need only provide an array
28of NC_MAX_DIMS dimensions to handle any netCDF dataset. The
29implementation of the netCDF library does not enforce this advisory
30maximum, so it is possible to use more dimensions, if necessary, but
31netCDF utilities that assume the advisory maximums may not be able to
32handle the resulting netCDF datasets.
33
34Ordinarily, the name and length of a dimension are fixed when the
35dimension is first defined. The name may be changed later, but the
36length of a dimension (other than the unlimited dimension) cannot be
37changed without copying all the data to a new netCDF dataset with a
38redefined dimension length.
39
40Dimension lengths in the C interface are type size_t rather than type
41int to make it possible to access all the data in a netCDF dataset on
42a platform that only supports a 16-bit int data type, for example
43MSDOS. If dimension lengths were type int instead, it would not be
44possible to access data from variables with a dimension length greater
45than a 16-bit int can accommodate.
46
47A netCDF dimension in an open netCDF dataset is referred to by a small
48integer called a dimension ID. In the C interface, dimension IDs are
490, 1, 2, ..., in the order in which the dimensions were defined.
50
51Operations supported on dimensions are:
52- Create a dimension, given its name and length.
53- Get a dimension ID from its name.
54- Get a dimension's name and length from its ID.
55- Rename a dimension.
56*/
57/**@{*/
58
59/*!  Define a new dimension. The function nc_def_dim adds a new
60dimension to an open netCDF dataset in define mode. It returns (as an
61argument) a dimension ID, given the netCDF ID, the dimension name, and
62the dimension length. At most one unlimited length dimension, called
63the record dimension, may be defined for each classic or 64-bit offset
64netCDF dataset. NetCDF-4 datasets may have multiple unlimited
65dimensions.
66
67\param ncid NetCDF or group ID, from a previous call to nc_open(),
68nc_create(), nc_def_grp(), or associated inquiry functions such as
69nc_inq_ncid().
70
71\param name Name of the dimension to be created.
72
73\param len Length of the dimension to be created. Use NC_UNLIMITED for
74unlimited dimensions.
75
76\param idp Pointer where dimension ID will be stored.
77
78\retval ::NC_NOERR No error.
79\returns ::NC_EBADID Not a valid ID.
80\returns ::NC_ENOTINDEFINE Not in define mode.
81\returns ::NC_EDIMSIZE Invalid dimension size.
82\returns ::NC_EUNLIMIT NC_UNLIMITED size already in use
83\returns ::NC_EMAXDIMS NC_MAX_DIMS exceeded
84\returns ::NC_ENAMEINUSE String match to name in use
85\returns ::NC_ENOMEM Memory allocation (malloc) failure
86\returns ::NC_EPERM Write to read only
87
88\section Example
89
90Here is an example using nc_def_dim() to create a dimension named lat of
91length 18 and a unlimited dimension named rec in a new netCDF dataset
92named foo.nc:
93
94\code
95     #include <netcdf.h>
96        ...
97     int status, ncid, latid, recid;
98        ...
99     status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
100     if (status != NC_NOERR) handle_error(status);
101        ...
102     status = nc_def_dim(ncid, "lat", 18L, &latid);
103     if (status != NC_NOERR) handle_error(status);
104     status = nc_def_dim(ncid, "rec", NC_UNLIMITED, &recid);
105     if (status != NC_NOERR) handle_error(status);
106\endcode
107
108 */
109int
110nc_def_dim(int ncid, const char *name, size_t len, int *idp)
111{
112    NC* ncp;
113    int stat = NC_check_id(ncid, &ncp);
114    if(stat != NC_NOERR) return stat;
115    return ncp->dispatch->def_dim(ncid, name, len, idp);
116}
117
118/*!
119Find the ID of a dimension from the name.
120
121The function nc_inq_dimid returns (as an argument) the ID of a netCDF
122dimension, given the name of the dimension. If ndims is the number of
123dimensions defined for a netCDF dataset, each dimension has an ID
124between 0 and ndims-1.
125
126\param ncid NetCDF or group ID, from a previous call to nc_open(),
127nc_create(), nc_def_grp(), or associated inquiry functions such as
128nc_inq_ncid().
129
130\param name Name of the dimension.
131
132\param idp Pointer where dimension ID will be stored.
133
134\returns ::NC_NOERR   No error.
135\returns ::NC_EBADID  Not a valid ID.
136\returns ::NC_EBADDIM Invalid dimension ID or name.
137 */
138int
139nc_inq_dimid(int ncid, const char *name, int *idp)
140{
141    NC* ncp;
142    int stat = NC_check_id(ncid, &ncp);
143    if(stat != NC_NOERR) return stat;
144    return ncp->dispatch->inq_dimid(ncid,name,idp);
145}
146
147/*!
148Find the name and length of a dimension.
149
150The length for the unlimited dimension, if any, is the number of
151records written so far.
152
153\param ncid NetCDF or group ID, from a previous call to nc_open(),
154nc_create(), nc_def_grp(), or associated inquiry functions such as
155nc_inq_ncid().
156
157\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
158nc_def_dim().
159
160\param name Returned dimension name. The caller must allocate space
161for the returned name. The maximum possible length, in characters, of
162a dimension name is given by the predefined constant
163NC_MAX_NAME. (This doesn't include the null terminator, so declare
164your array to be size NC_MAX_NAME+1). The returned character array
165will be null-terminated.
166
167\param lenp Pointer to location for returned length of dimension. For
168the unlimited dimension, this is the number of records written so far.
169
170\returns ::NC_NOERR   No error.
171\returns ::NC_EBADID  Not a valid ID.
172\returns ::NC_EBADDIM Invalid dimension ID or name.
173
174\section Example
175
176Here is an example using nc_inq_dim() to determine the length of a
177dimension named lat, and the name and current maximum length of the
178unlimited dimension for an existing netCDF dataset named foo.nc:
179
180\code
181     #include <netcdf.h>
182        ...
183     int status, ncid, latid, recid;
184     size_t latlength, recs;
185     char recname[NC_MAX_NAME+1];
186        ...
187     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
188     if (status != NC_NOERR) handle_error(status);
189     status = nc_inq_unlimdim(ncid, &recid);
190     if (status != NC_NOERR) handle_error(status);
191        ...
192     status = nc_inq_dimid(ncid, "lat", &latid);
193     if (status != NC_NOERR) handle_error(status);
194     status = nc_inq_dimlen(ncid, latid, &latlength);
195     if (status != NC_NOERR) handle_error(status);
196
197     status = nc_inq_dim(ncid, recid, recname, &recs);
198     if (status != NC_NOERR) handle_error(status);
199\endcode
200 */
201int
202nc_inq_dim(int ncid, int dimid, char *name, size_t *lenp)
203{
204    NC* ncp;
205    int stat = NC_check_id(ncid, &ncp);
206    if(stat != NC_NOERR) return stat;
207    return ncp->dispatch->inq_dim(ncid,dimid,name,lenp);
208}
209
210/*!
211Rename a dimension.
212
213This function renames an existing dimension in a netCDF dataset open
214for writing. You cannot rename a dimension to have the same name as
215another dimension.
216
217For netCDF classic and 64-bit offset files, if the new name is longer
218than the old name, the netCDF dataset must be in define mode.
219
220For netCDF-4 files the dataset is switched to define more for the
221rename, regardless of the name length.
222
223\param ncid NetCDF or group ID, from a previous call to nc_open(),
224nc_create(), nc_def_grp(), or associated inquiry functions such as
225nc_inq_ncid().
226
227\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
228nc_def_dim().
229
230\param name New name for dimension. Must be a null-terminated string
231with length less than NC_MAX_NAME.
232
233\returns ::NC_NOERR      No error.
234\returns ::NC_EBADID     Not a valid ID.
235\returns ::NC_EBADDIM    Invalid dimension ID or name.
236\returns ::NC_ENAMEINUSE String match to name in use
237\returns ::NC_ENOMEM     Memory allocation (malloc) failure
238\returns ::NC_EPERM      Write to read only
239\section Example
240
241Here is an example using nc_rename_dim to rename the dimension lat to
242latitude in an existing netCDF dataset named foo.nc:
243
244\code
245     #include <netcdf.h>
246        ...
247     int status, ncid, latid;
248        ...
249     status = nc_open("foo.nc", NC_WRITE, &ncid);
250     if (status != NC_NOERR) handle_error(status);
251        ...
252     status = nc_redef(ncid);
253     if (status != NC_NOERR) handle_error(status);
254     status = nc_inq_dimid(ncid, "lat", &latid);
255     if (status != NC_NOERR) handle_error(status);
256     status = nc_rename_dim(ncid, latid, "latitude");
257     if (status != NC_NOERR) handle_error(status);
258     status = nc_enddef(ncid);
259     if (status != NC_NOERR) handle_error(status);
260\endcode
261 */
262int
263nc_rename_dim(int ncid, int dimid, const char *name)
264{
265    NC* ncp;
266    int stat = NC_check_id(ncid, &ncp);
267    if(stat != NC_NOERR) return stat;
268    return ncp->dispatch->rename_dim(ncid,dimid,name);
269}
270
271/*!
272Find the number of dimensions.
273
274In a classic model netCDF file, this funtion returns the number of
275defined dimensions. In a netCDF-4/HDF5 file, this function returns the
276number of dimensions available in the group specified by ncid, which
277may be less than the total number of dimensions in a file. In a
278netCDF-4/HDF5 file, dimensions are in all sub-groups, sub-sub-groups,
279etc.
280
281\param ncid NetCDF or group ID, from a previous call to nc_open(),
282nc_create(), nc_def_grp(), or associated inquiry functions such as
283nc_inq_ncid().
284
285\param ndimsp Pointer where number of dimensions will be
286written. Ignored if NULL.
287
288\returns ::NC_NOERR  No error.
289\returns ::NC_EBADID Not a valid ID.
290
291 */
292int
293nc_inq_ndims(int ncid, int *ndimsp)
294{
295    NC* ncp;
296    int stat = NC_check_id(ncid, &ncp);
297    if(stat != NC_NOERR) return stat;
298    if(ndimsp == NULL) return NC_NOERR;
299    return ncp->dispatch->inq(ncid,ndimsp,NULL,NULL,NULL);
300}
301
302/*!
303Find the ID of the unlimited dimension.
304
305This function finds the ID of the unlimited dimension. For
306netCDF-4/HDF5 files (which may have more than one unlimited
307dimension), the ID of the first unlimited dimesnion is returned. For
308these files, nc_inq_unlimdims() will return all the unlimited dimension IDs.
309
310\param ncid NetCDF or group ID, from a previous call to nc_open(),
311nc_create(), nc_def_grp(), or associated inquiry functions such as
312nc_inq_ncid().
313
314\param unlimdimidp Pointer where unlimited dimension ID will be
315stored. If there is no unlimited dimension, -1 will be stored
316here. Ignored if NULL.
317
318\returns ::NC_NOERR  No error.
319\returns ::NC_EBADID Not a valid ID.
320
321 */
322int
323nc_inq_unlimdim(int ncid, int *unlimdimidp)
324{
325    NC* ncp;
326    int stat = NC_check_id(ncid, &ncp);
327    if(stat != NC_NOERR) return stat;
328    return ncp->dispatch->inq_unlimdim(ncid,unlimdimidp);
329}
330
331/*!
332Find out the name of a dimension.
333
334\param ncid NetCDF or group ID, from a previous call to nc_open(),
335nc_create(), nc_def_grp(), or associated inquiry functions such as
336nc_inq_ncid().
337
338\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
339nc_def_dim().
340
341\param name Returned dimension name. The caller must allocate space
342for the returned name. The maximum possible length, in characters, of
343a dimension name is given by the predefined constant
344NC_MAX_NAME. (This doesn't include the null terminator, so declare
345your array to be size NC_MAX_NAME+1). The returned character array
346will be null-terminated. Ignored if NULL.
347
348\returns ::NC_NOERR   No error.
349\returns ::NC_EBADID  Not a valid ID.
350\returns ::NC_EBADDIM Invalid dimension ID or name.
351
352\section Example
353
354Here is an example using nc_inq_dim() to determine the length of a
355dimension named lat, and the name and current maximum length of the
356unlimited dimension for an existing netCDF dataset named foo.nc:
357
358\code
359     #include <netcdf.h>
360        ...
361     int status, ncid, latid, recid;
362     size_t latlength, recs;
363     char recname[NC_MAX_NAME+1];
364        ...
365     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
366     if (status != NC_NOERR) handle_error(status);
367     status = nc_inq_unlimdim(ncid, &recid);
368     if (status != NC_NOERR) handle_error(status);
369        ...
370     status = nc_inq_dimid(ncid, "lat", &latid);
371     if (status != NC_NOERR) handle_error(status);
372     status = nc_inq_dimlen(ncid, latid, &latlength);
373     if (status != NC_NOERR) handle_error(status);
374
375     status = nc_inq_dim(ncid, recid, recname, &recs);
376     if (status != NC_NOERR) handle_error(status);
377\endcode
378
379 */
380int
381nc_inq_dimname(int ncid, int dimid, char *name)
382{
383    NC* ncp;
384    int stat = NC_check_id(ncid, &ncp);
385    if(stat != NC_NOERR) return stat;
386    if(name == NULL) return NC_NOERR;
387    return ncp->dispatch->inq_dim(ncid,dimid,name,NULL);
388}
389
390/*!
391Find the length of a dimension.
392
393The length for the unlimited dimension, if any, is the number of
394records written so far.
395
396\param ncid NetCDF or group ID, from a previous call to nc_open(),
397nc_create(), nc_def_grp(), or associated inquiry functions such as
398nc_inq_ncid().
399
400\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
401nc_def_dim().
402
403\param lenp Pointer where the length will be stored.
404
405\returns ::NC_NOERR   No error.
406\returns ::NC_EBADID  Not a valid ID.
407\returns ::NC_EBADDIM Invalid dimension ID or name.
408
409\section Example
410
411Here is an example using nc_inq_dim() to determine the length of a
412dimension named lat, and the name and current maximum length of the
413unlimited dimension for an existing netCDF dataset named foo.nc:
414
415\code
416     #include <netcdf.h>
417        ...
418     int status, ncid, latid, recid;
419     size_t latlength, recs;
420     char recname[NC_MAX_NAME+1];
421        ...
422     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
423     if (status != NC_NOERR) handle_error(status);
424     status = nc_inq_unlimdim(ncid, &recid);
425     if (status != NC_NOERR) handle_error(status);
426        ...
427     status = nc_inq_dimid(ncid, "lat", &latid); 
428     if (status != NC_NOERR) handle_error(status);
429     status = nc_inq_dimlen(ncid, latid, &latlength);
430     if (status != NC_NOERR) handle_error(status);
431
432     status = nc_inq_dim(ncid, recid, recname, &recs);
433     if (status != NC_NOERR) handle_error(status);
434\endcode
435 */
436int
437nc_inq_dimlen(int ncid, int dimid, size_t *lenp)
438{
439    NC* ncp;
440    int stat = NC_check_id(ncid, &ncp);
441    if(stat != NC_NOERR) return stat;
442    if(lenp == NULL) return NC_NOERR;
443    return ncp->dispatch->inq_dim(ncid,dimid,NULL,lenp);
444}
445/**@}*/
Note: See TracBrowser for help on using the repository browser.