1 /* Copyright 2018 University Corporation for Atmospheric
2 Research/Unidata. See COPYRIGHT file for more info. */
3 /*! \file
4 Functions for inquiring about variables.
5
6 */
7
8 #include "config.h"
9 #include "netcdf.h"
10 #include "netcdf_filter.h"
11 #include "ncdispatch.h"
12 #include "nc4internal.h"
13 #ifdef USE_HDF5
14 #include <vtk_hdf5.h>
15 #endif /* USE_HDF5 */
16
17 /** \name Learning about Variables
18
19 Functions to learn about the variables in a file. */
20 /*! \{ */ /* All these functions are part of this named group... */
21
22 /**
23 \ingroup variables
24 Find the ID of a variable, from the name.
25
26 The function nc_inq_varid returns the ID of a netCDF variable, given
27 its name.
28
29 \param ncid NetCDF or group ID, from a previous call to nc_open(),
30 nc_create(), nc_def_grp(), or associated inquiry functions such as
31 nc_inq_ncid().
32
33 \param name Name of the variable.
34
35 \param varidp Pointer to location for returned variable ID. \ref
36 ignored_if_null.
37
38 \returns ::NC_NOERR No error.
39 \returns ::NC_EBADID Bad ncid.
40 \returns ::NC_ENOTVAR Invalid variable ID.
41
42 \section nc_inq_varid_example4 Example
43
44 Here is an example using nc_inq_varid to find out the ID of a variable
45 named rh in an existing netCDF dataset named foo.nc:
46
47 \code
48 #include <netcdf.h>
49 ...
50 int status, ncid, rh_id;
51 ...
52 status = nc_open("foo.nc", NC_NOWRITE, &ncid);
53 if (status != NC_NOERR) handle_error(status);
54 ...
55 status = nc_inq_varid (ncid, "rh", &rh_id);
56 if (status != NC_NOERR) handle_error(status);
57 \endcode
58 */
59 int
nc_inq_varid(int ncid,const char * name,int * varidp)60 nc_inq_varid(int ncid, const char *name, int *varidp)
61 {
62 NC* ncp;
63 int stat = NC_check_id(ncid, &ncp);
64 if(stat != NC_NOERR) return stat;
65 return ncp->dispatch->inq_varid(ncid, name, varidp);
66 }
67
68 /**
69 \ingroup variables
70 Learn about a variable.
71
72 \param ncid NetCDF or group ID, from a previous call to nc_open(),
73 nc_create(), nc_def_grp(), or associated inquiry functions such as
74 nc_inq_ncid().
75
76 \param varid Variable ID
77
78 \param name Returned \ref object_name of variable. \ref
79 ignored_if_null.
80
81 \param xtypep Pointer where typeid will be stored. \ref ignored_if_null.
82
83 \param ndimsp Pointer where number of dimensions will be
84 stored. \ref ignored_if_null.
85
86 \param dimidsp Pointer where array of dimension IDs will be
87 stored. \ref ignored_if_null.
88
89 \param nattsp Pointer where number of attributes will be
90 stored. \ref ignored_if_null.
91
92 \returns ::NC_NOERR No error.
93 \returns ::NC_EBADID Bad ncid.
94 \returns ::NC_ENOTVAR Invalid variable ID.
95
96 \section nc_inq_var_example5 Example
97
98 Here is an example using nc_inq_var() to find out about a variable named
99 rh in an existing netCDF dataset named foo.nc:
100
101 \code
102 #include <netcdf.h>
103 ...
104 int status
105 int ncid;
106 int rh_id;
107 nc_type rh_type;
108 int rh_ndims;
109 int rh_dimids[NC_MAX_VAR_DIMS];
110 int rh_natts
111 ...
112 status = nc_open ("foo.nc", NC_NOWRITE, &ncid);
113 if (status != NC_NOERR) handle_error(status);
114 ...
115 status = nc_inq_varid (ncid, "rh", &rh_id);
116 if (status != NC_NOERR) handle_error(status);
117 status = nc_inq_var (ncid, rh_id, 0, &rh_type, &rh_ndims, rh_dimids,
118 &rh_natts);
119 if (status != NC_NOERR) handle_error(status);
120 \endcode
121
122 */
123 int
nc_inq_var(int ncid,int varid,char * name,nc_type * xtypep,int * ndimsp,int * dimidsp,int * nattsp)124 nc_inq_var(int ncid, int varid, char *name, nc_type *xtypep,
125 int *ndimsp, int *dimidsp, int *nattsp)
126 {
127 NC* ncp;
128 int stat = NC_check_id(ncid, &ncp);
129 if(stat != NC_NOERR) return stat;
130 TRACE(nc_inq_var);
131 return ncp->dispatch->inq_var_all(ncid, varid, name, xtypep, ndimsp,
132 dimidsp, nattsp, NULL, NULL, NULL,
133 NULL, NULL, NULL, NULL, NULL, NULL,
134 NULL,NULL,NULL);
135 }
136
137 /**
138 \ingroup variables
139 Learn the name of a variable.
140
141 \param ncid NetCDF or group ID, from a previous call to nc_open(),
142 nc_create(), nc_def_grp(), or associated inquiry functions such as
143 nc_inq_ncid().
144
145 \param varid Variable ID
146
147 \param name Returned variable name. The caller must allocate space for
148 the returned name. The maximum length is ::NC_MAX_NAME. Ignored if
149 NULL.
150
151 \returns ::NC_NOERR No error.
152 \returns ::NC_EBADID Bad ncid.
153 \returns ::NC_ENOTVAR Invalid variable ID.
154 */
155 int
nc_inq_varname(int ncid,int varid,char * name)156 nc_inq_varname(int ncid, int varid, char *name)
157 {
158 return nc_inq_var(ncid, varid, name, NULL, NULL,
159 NULL, NULL);
160 }
161
162 /** Learn the type of a variable.
163 \ingroup variables
164
165 \param ncid NetCDF or group ID, from a previous call to nc_open(),
166 nc_create(), nc_def_grp(), or associated inquiry functions such as
167 nc_inq_ncid().
168
169 \param varid Variable ID
170
171 \param typep Pointer where typeid will be stored. \ref ignored_if_null.
172
173 \returns ::NC_NOERR No error.
174 \returns ::NC_EBADID Bad ncid.
175 \returns ::NC_ENOTVAR Invalid variable ID.
176 */
177 int
nc_inq_vartype(int ncid,int varid,nc_type * typep)178 nc_inq_vartype(int ncid, int varid, nc_type *typep)
179 {
180 return nc_inq_var(ncid, varid, NULL, typep, NULL,
181 NULL, NULL);
182 }
183
184 /**
185 Learn how many dimensions are associated with a variable.
186 \ingroup variables
187
188 \param ncid NetCDF or group ID, from a previous call to nc_open(),
189 nc_create(), nc_def_grp(), or associated inquiry functions such as
190 nc_inq_ncid().
191
192 \param varid Variable ID
193
194 \param ndimsp Pointer where number of dimensions will be
195 stored. \ref ignored_if_null.
196
197 \returns ::NC_NOERR No error.
198 \returns ::NC_EBADID Bad ncid.
199 \returns ::NC_ENOTVAR Invalid variable ID.
200 */
201 int
nc_inq_varndims(int ncid,int varid,int * ndimsp)202 nc_inq_varndims(int ncid, int varid, int *ndimsp)
203 {
204 return nc_inq_var(ncid, varid, NULL, NULL, ndimsp, NULL, NULL);
205 }
206
207 /**
208 Learn the dimension IDs associated with a variable.
209 \ingroup variables
210
211 \param ncid NetCDF or group ID, from a previous call to nc_open(),
212 nc_create(), nc_def_grp(), or associated inquiry functions such as
213 nc_inq_ncid().
214
215 \param varid Variable ID
216
217 \param dimidsp Pointer where array of dimension IDs will be
218 stored. \ref ignored_if_null.
219
220 \returns ::NC_NOERR No error.
221 \returns ::NC_EBADID Bad ncid.
222 \returns ::NC_ENOTVAR Invalid variable ID.
223 */
224 int
nc_inq_vardimid(int ncid,int varid,int * dimidsp)225 nc_inq_vardimid(int ncid, int varid, int *dimidsp)
226 {
227 return nc_inq_var(ncid, varid, NULL, NULL, NULL,
228 dimidsp, NULL);
229 }
230
231 /**
232 Learn how many attributes are associated with a variable.
233 \ingroup variables
234
235 \param ncid NetCDF or group ID, from a previous call to nc_open(),
236 nc_create(), nc_def_grp(), or associated inquiry functions such as
237 nc_inq_ncid().
238
239 \param varid Variable ID
240
241 \param nattsp Pointer where number of attributes will be
242 stored. \ref ignored_if_null.
243
244 \returns ::NC_NOERR No error.
245 \returns ::NC_EBADID Bad ncid.
246 \returns ::NC_ENOTVAR Invalid variable ID.
247 */
248 int
nc_inq_varnatts(int ncid,int varid,int * nattsp)249 nc_inq_varnatts(int ncid, int varid, int *nattsp)
250 {
251 if (varid == NC_GLOBAL)
252 return nc_inq_natts(ncid,nattsp);
253 /*else*/
254 return nc_inq_var(ncid, varid, NULL, NULL, NULL, NULL,
255 nattsp);
256 }
257
258 /**
259 \ingroup variables
260
261 Learn the shuffle and deflate settings for a variable.
262
263 Deflation is compression with the zlib library. Shuffle re-orders the
264 data bytes to provide better compression (see nc_def_var_deflate()).
265
266 Deflation is only available for HDF5 files. For classic and other
267 files, this function will return setting that indicate that deflation
268 is not in use, and that the shuffle filter is not in use. That is:
269 shuffle off, deflate off, and a deflate level of 0.
270
271 \param ncid NetCDF or group ID, from a previous call to nc_open(),
272 nc_create(), nc_def_grp(), or associated inquiry functions such as
273 nc_inq_ncid().
274
275 \param varid Variable ID
276
277 \param shufflep A 1 will be written here if the shuffle filter is
278 turned on for this variable, and a 0 otherwise. \ref ignored_if_null.
279
280 \param deflatep If this pointer is non-NULL, the nc_inq_var_deflate
281 function will write a 1 if the deflate filter is turned on for this
282 variable, and a 0 otherwise. \ref ignored_if_null.
283
284 \param deflate_levelp If the deflate filter is in use for this
285 variable, the deflate_level will be written here. If deflate is not in
286 use, and deflate_levelp is provided, it will get a zero. (This
287 behavior is expected by the Fortran APIs). \ref ignored_if_null.
288
289 \returns ::NC_NOERR No error.
290 \returns ::NC_EBADID Bad ncid.
291 \returns ::NC_ENOTVAR Invalid variable ID.
292 \author Ed Hartnett, Dennis Heimbigner
293 */
294 int
nc_inq_var_deflate(int ncid,int varid,int * shufflep,int * deflatep,int * deflate_levelp)295 nc_inq_var_deflate(int ncid, int varid, int *shufflep, int *deflatep, int *deflate_levelp)
296 {
297 NC* ncp;
298 size_t nparams;
299 unsigned int params[4];
300 int deflating = 0;
301 int stat;
302
303 stat = NC_check_id(ncid,&ncp);
304 if(stat != NC_NOERR) return stat;
305 TRACE(nc_inq_var_deflate);
306
307 /* Verify id and nparams */
308 stat = nc_inq_var_filter_info(ncid,varid,H5Z_FILTER_DEFLATE,&nparams,params);
309 switch (stat) {
310 case NC_ENOFILTER: deflating = 0; stat = NC_NOERR; break;
311 case NC_NOERR: deflating = 1; break;
312 case NC_ENOTNC4:
313 /* As a special case, to support behavior already coded into user
314 * applications, handle classic format files by reporting no
315 * deflation. */
316 if (shufflep)
317 *shufflep = 0;
318 if (deflatep)
319 *deflatep = 0;
320 if (deflate_levelp)
321 *deflate_levelp = 0;
322 return NC_NOERR;
323 break;
324 default: return stat;
325 }
326 if(deflatep) *deflatep = deflating;
327 if(deflating) {
328 if(nparams != 1)
329 return NC_EFILTER; /* bad # params */
330 /* Param[0] should be level */
331 if(deflate_levelp) *deflate_levelp = (int)params[0];
332 } else if (deflate_levelp)
333 *deflate_levelp = 0;
334 /* also get the shuffle state */
335 if(!shufflep)
336 return NC_NOERR;
337 return ncp->dispatch->inq_var_all(
338 ncid, varid,
339 NULL, /*name*/
340 NULL, /*xtypep*/
341 NULL, /*ndimsp*/
342 NULL, /*dimidsp*/
343 NULL, /*nattsp*/
344 shufflep, /*shufflep*/
345 NULL, /*deflatep*/
346 NULL, /*deflatelevelp*/
347 NULL, /*fletcher32p*/
348 NULL, /*contiguousp*/
349 NULL, /*chunksizep*/
350 NULL, /*nofillp*/
351 NULL, /*fillvaluep*/
352 NULL, /*endianp*/
353 NULL, NULL, NULL
354 );
355 }
356
357 /** \ingroup variables
358 Learn the checksum settings for a variable.
359
360 This is a wrapper for nc_inq_var_all().
361
362 \param ncid NetCDF or group ID, from a previous call to nc_open(),
363 nc_create(), nc_def_grp(), or associated inquiry functions such as
364 nc_inq_ncid().
365
366 \param varid Variable ID
367
368 \param fletcher32p Will be set to ::NC_FLETCHER32 if the fletcher32
369 checksum filter is turned on for this variable, and ::NC_NOCHECKSUM if
370 it is not. \ref ignored_if_null.
371
372 \returns ::NC_NOERR No error.
373 \returns ::NC_EBADID Bad ncid.
374 \returns ::NC_ENOTNC4 Not a netCDF-4 file.
375 \returns ::NC_ENOTVAR Invalid variable ID.
376 */
377 int
nc_inq_var_fletcher32(int ncid,int varid,int * fletcher32p)378 nc_inq_var_fletcher32(int ncid, int varid, int *fletcher32p)
379 {
380 NC* ncp;
381 int stat = NC_check_id(ncid,&ncp);
382 if(stat != NC_NOERR) return stat;
383 TRACE(nc_inq_var_fletcher32);
384 return ncp->dispatch->inq_var_all(
385 ncid, varid,
386 NULL, /*name*/
387 NULL, /*xtypep*/
388 NULL, /*ndimsp*/
389 NULL, /*dimidsp*/
390 NULL, /*nattsp*/
391 NULL, /*shufflep*/
392 NULL, /*deflatep*/
393 NULL, /*deflatelevelp*/
394 fletcher32p, /*fletcher32p*/
395 NULL, /*contiguousp*/
396 NULL, /*chunksizep*/
397 NULL, /*nofillp*/
398 NULL, /*fillvaluep*/
399 NULL, /*endianp*/
400 NULL, NULL, NULL
401 );
402 }
403
404 /**
405 * @ingroup variables
406 *
407 * Get the storage and (for chunked variables) the chunksizes of a
408 * variable. See nc_def_var_chunking() for explanation of storage.
409 *
410 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
411 * nc_create(), nc_def_grp(), or associated inquiry functions such as
412 * nc_inq_ncid().
413 * @param varid Variable ID
414 * @param storagep Address of returned storage property, returned as
415 * ::NC_CONTIGUOUS if this variable uses contiguous storage,
416 * ::NC_CHUNKED if it uses chunked storage, or ::NC_COMPACT for
417 * compact storage. \ref ignored_if_null.
418 * @param chunksizesp The chunksizes will be copied here. \ref
419 * ignored_if_null.
420 *
421 * @return ::NC_NOERR No error.
422 * @return ::NC_EBADID Bad ncid.
423 * @return ::NC_ENOTNC4 Not a netCDF-4 file.
424 * @return ::NC_ENOTVAR Invalid variable ID.
425 *
426 * @author Ed Hartnett
427 *
428 * @section nc_inq_var_chunking_example Example
429 *
430 * @code
431 printf("**** testing contiguous storage...");
432 {
433 #define NDIMS6 1
434 #define DIM6_NAME "D5"
435 #define VAR_NAME6 "V5"
436 #define DIM6_LEN 100
437
438 int dimids[NDIMS6], dimids_in[NDIMS6];
439 int varid;
440 int ndims, nvars, natts, unlimdimid;
441 nc_type xtype_in;
442 char name_in[NC_MAX_NAME + 1];
443 int data[DIM6_LEN], data_in[DIM6_LEN];
444 size_t chunksize_in[NDIMS6];
445 int storage_in;
446 int i, d;
447
448 for (i = 0; i < DIM6_LEN; i++)
449 data[i] = i;
450
451
452 if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
453 if (nc_def_dim(ncid, DIM6_NAME, DIM6_LEN, &dimids[0])) ERR;
454 if (dimids[0] != 0) ERR;
455 if (nc_def_var(ncid, VAR_NAME6, NC_INT, NDIMS6, dimids, &varid)) ERR;
456 if (nc_def_var_chunking(ncid, varid, NC_CONTIGUOUS, NULL)) ERR;
457 if (nc_put_var_int(ncid, varid, data)) ERR;
458
459
460 if (nc_inq_var_chunking(ncid, 0, &storage_in, chunksize_in)) ERR;
461 if (storage_in != NC_CONTIGUOUS) ERR;
462 @endcode
463 *
464 */
465 int
nc_inq_var_chunking(int ncid,int varid,int * storagep,size_t * chunksizesp)466 nc_inq_var_chunking(int ncid, int varid, int *storagep, size_t *chunksizesp)
467 {
468 NC *ncp;
469 int stat = NC_check_id(ncid, &ncp);
470 if(stat != NC_NOERR) return stat;
471 TRACE(nc_inq_var_chunking);
472 return ncp->dispatch->inq_var_all(ncid, varid, NULL, NULL, NULL, NULL,
473 NULL, NULL, NULL, NULL, NULL, storagep,
474 chunksizesp, NULL, NULL, NULL,
475 NULL, NULL, NULL);
476 }
477
478 /** \ingroup variables
479 Learn the fill mode of a variable.
480
481 The fill mode of a variable is set by nc_def_var_fill().
482
483 This is a wrapper for nc_inq_var_all().
484
485 \param ncid NetCDF or group ID, from a previous call to nc_open(),
486 nc_create(), nc_def_grp(), or associated inquiry functions such as
487 nc_inq_ncid().
488
489 \param varid Variable ID
490
491 \param no_fill Pointer to an integer which will get a 1 if no_fill
492 mode is set for this variable. \ref ignored_if_null.
493
494 \param fill_valuep A pointer which will get the fill value for this
495 variable. \ref ignored_if_null.
496
497 \returns ::NC_NOERR No error.
498 \returns ::NC_EBADID Bad ncid.
499 \returns ::NC_ENOTVAR Invalid variable ID.
500 */
501 int
nc_inq_var_fill(int ncid,int varid,int * no_fill,void * fill_valuep)502 nc_inq_var_fill(int ncid, int varid, int *no_fill, void *fill_valuep)
503 {
504 NC* ncp;
505 int stat = NC_check_id(ncid,&ncp);
506
507 if(stat != NC_NOERR) return stat;
508 TRACE(nc_inq_var_fill);
509
510 return ncp->dispatch->inq_var_all(
511 ncid,varid,
512 NULL, /*name*/
513 NULL, /*xtypep*/
514 NULL, /*ndimsp*/
515 NULL, /*dimidsp*/
516 NULL, /*nattsp*/
517 NULL, /*shufflep*/
518 NULL, /*deflatep*/
519 NULL, /*deflatelevelp*/
520 NULL, /*fletcher32p*/
521 NULL, /*contiguousp*/
522 NULL, /*chunksizep*/
523 no_fill, /*nofillp*/
524 fill_valuep, /*fillvaluep*/
525 NULL, /*endianp*/
526 NULL, NULL, NULL
527 );
528 }
529
530 /** \ingroup variables
531 Find the endianness of a variable.
532
533 This is a wrapper for nc_inq_var_all().
534
535 \param ncid NetCDF or group ID, from a previous call to nc_open(),
536 nc_create(), nc_def_grp(), or associated inquiry functions such as
537 nc_inq_ncid().
538
539 \param varid Variable ID
540
541 \param endianp Storage which will get ::NC_ENDIAN_LITTLE if this
542 variable is stored in little-endian format, ::NC_ENDIAN_BIG if it is
543 stored in big-endian format, and ::NC_ENDIAN_NATIVE if the endianness
544 is not set, and the variable is not created yet.
545
546 \returns ::NC_NOERR No error.
547 \returns ::NC_ENOTNC4 Not a netCDF-4 file.
548 \returns ::NC_EBADID Bad ncid.
549 \returns ::NC_ENOTVAR Invalid variable ID.
550 */
551 int
nc_inq_var_endian(int ncid,int varid,int * endianp)552 nc_inq_var_endian(int ncid, int varid, int *endianp)
553 {
554 NC* ncp;
555 int stat = NC_check_id(ncid,&ncp);
556 if(stat != NC_NOERR) return stat;
557 TRACE(nc_inq_var_endian);
558 return ncp->dispatch->inq_var_all(
559 ncid, varid,
560 NULL, /*name*/
561 NULL, /*xtypep*/
562 NULL, /*ndimsp*/
563 NULL, /*dimidsp*/
564 NULL, /*nattsp*/
565 NULL, /*shufflep*/
566 NULL, /*deflatep*/
567 NULL, /*deflatelevelp*/
568 NULL, /*fletcher32p*/
569 NULL, /*contiguousp*/
570 NULL, /*chunksizep*/
571 NULL, /*nofillp*/
572 NULL, /*fillvaluep*/
573 endianp, /*endianp*/
574 NULL, NULL, NULL);
575 }
576
577 /**
578 Return number and list of unlimited dimensions.
579
580 In netCDF-4 files, it's possible to have multiple unlimited
581 dimensions. This function returns a list of the unlimited dimension
582 ids visible in a group.
583
584 Dimensions are visible in a group if they have been defined in that
585 group, or any ancestor group.
586
587 \param ncid NetCDF file and group ID, from a previous call to nc_open(),
588 nc_create(), nc_def_grp(), etc.
589
590 \param nunlimdimsp A pointer to an int which will get the number of
591 visible unlimited dimensions. Ignored if NULL.
592
593 \param unlimdimidsp A pointer to an already allocated array of int
594 which will get the ids of all visible unlimited dimensions. Ignored if
595 NULL. To allocate the correct length for this array, call
596 nc_inq_unlimdims with a NULL for this parameter and use the
597 nunlimdimsp parameter to get the number of visible unlimited
598 dimensions.
599
600 \section nc_inq_unlimdims_example Example
601
602 Here is an example from nc_test4/tst_dims.c. In this example we create
603 a file with two unlimited dimensions, and then call nc_inq_unlimdims()
604 to check that there are 2 unlimited dimensions, and that they have
605 dimids 0 and 1.
606
607 \code
608 #include <netcdf.h>
609 ...
610 #define ROMULUS "Romulus"
611 #define REMUS "Remus"
612 #define DIMS2 2
613 printf("*** Testing file with two unlimited dimensions...");
614 {
615 int ncid, dimid[DIMS2];
616 int unlimdimid_in[DIMS2];
617 int nunlimdims_in;
618
619 if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
620 if (nc_def_dim(ncid, REMUS, NC_UNLIMITED, &dimid[0])) ERR;
621 if (nc_def_dim(ncid, ROMULUS, NC_UNLIMITED, &dimid[1])) ERR;
622
623 ...
624 if (nc_inq_unlimdims(ncid, &nunlimdims_in, unlimdimid_in)) ERR;
625 if (nunlimdims_in != 2 || unlimdimid_in[0] != 0 || unlimdimid_in[1] != 1) ERR;
626 \endcode
627
628 This function will return one of the following values.
629
630 \returns ::NC_NOERR No error.
631 \returns ::NC_EBADID Bad group id.
632 \returns ::NC_ENOTNC4 Attempting a netCDF-4 operation on a netCDF-3
633 file. NetCDF-4 operations can only be performed on files defined with
634 a create mode which includes flag HDF5. (see nc_open).
635 \returns ::NC_ESTRICTNC3 This file was created with the strict
636 netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see
637 nc_open).
638 \returns ::NC_EHDFERR An error was reported by the HDF5 layer.
639 \author Ed Hartnett, Dennis Heimbigner
640 */
641 int
nc_inq_unlimdims(int ncid,int * nunlimdimsp,int * unlimdimidsp)642 nc_inq_unlimdims(int ncid, int *nunlimdimsp, int *unlimdimidsp)
643 {
644 #ifndef USE_NETCDF4
645 return NC_ENOTNC4;
646 #else
647 NC* ncp;
648 int stat = NC_check_id(ncid,&ncp);
649 if(stat != NC_NOERR) return stat;
650 TRACE(nc_inq_unlimdims);
651 return ncp->dispatch->inq_unlimdims(ncid, nunlimdimsp,
652 unlimdimidsp);
653 #endif
654 }
655
656 /**
657 \ingroup variables
658 Learn the szip settings of a variable.
659
660 This function returns the szip settings for a variable. To turn on
661 szip compression, use nc_def_var_szip(). Szip compression is only
662 available for netCDF/HDF5 files, and only if HDF5 was built with szip
663 support.
664
665 If a variable is not using szip, or if this function is called on a
666 file that is not a HDF5 file, then a zero will be passed back for both
667 options_maskp and pixels_per_blockp.
668
669 For more information on HDF5 and szip see
670 https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-SetSzip
671 and https://support.hdfgroup.org/doc_resource/SZIP/index.html.
672
673 The nc_def_var_filter function may also be used to set szip
674 compression.
675
676 \param ncid NetCDF or group ID, from a previous call to nc_open(),
677 nc_create(), nc_def_grp(), or associated inquiry functions such as
678 nc_inq_ncid().
679
680 \param varid Variable ID
681
682 \param options_maskp The szip options mask will be copied to this
683 pointer. Note that the HDF5 layer adds to the options_mask, so this
684 value may be different from the value used when setting szip
685 compression, however the bit set when setting szip compression will
686 still be set in the options_maskp and can be checked for. If zero is
687 returned, szip is not in use for this variable.\ref ignored_if_null.
688
689 \param pixels_per_blockp The szip pixels per block will be copied
690 here. The HDF5 layer may change this value, so this may not match the
691 value passed in when setting szip compression. If zero is returned,
692 szip is not in use for this variable. \ref ignored_if_null.
693
694 \returns ::NC_NOERR No error.
695 \returns ::NC_EBADID Bad ncid.
696 \returns ::NC_ENOTVAR Invalid variable ID.
697 \returns ::NC_EFILTER Filter error.
698
699 \author Ed Hartnett, Dennis Heimbigner
700 */
701 int
nc_inq_var_szip(int ncid,int varid,int * options_maskp,int * pixels_per_blockp)702 nc_inq_var_szip(int ncid, int varid, int *options_maskp, int *pixels_per_blockp)
703 {
704 NC* ncp;
705 size_t nparams;
706 unsigned int params[4];
707
708 int stat = NC_check_id(ncid,&ncp);
709 if(stat != NC_NOERR) return stat;
710 TRACE(nc_inq_var_szip);
711
712 /* Verify id and nparams */
713 stat = nc_inq_var_filter_info(ncid,varid,H5Z_FILTER_SZIP,&nparams,params);
714 switch (stat) {
715 case NC_NOERR:
716 if(nparams != 2)
717 return NC_EFILTER; /* bad # params */
718 break;
719 case NC_ENOFILTER:
720 case NC_ENOTNC4:
721 /* If the szip filter is not in use, or if this is not a HDF5
722 * file, return 0 for both parameters. */
723 params[0] = 0;
724 params[1] = 0;
725 stat = NC_NOERR;
726 break;
727 default:
728 return stat;
729 }
730
731 /* Param[0] should be options_mask
732 Param[1] should be pixels_per_block */
733 if(options_maskp) *options_maskp = (int)params[0];
734 if(pixels_per_blockp) *pixels_per_blockp = (int)params[1];
735 return stat;
736 }
737
738 /*! \} */ /* End of named group ...*/
739