NetCDF-Fortran  4.4.4
netcdf-f90-sec3-groups.md
Go to the documentation of this file.
1 3 Groups {#f90_groups}
2 ========
3 
4 [TOC]
5 
6 NetCDF-4 added support for hierarchical groups within netCDF datasets.
7 
8 Groups are identified with a ncid, which identifies both the open file,
9 and the group within that file. When a file is opened with NF90\_OPEN or
10 NF90\_CREATE, the ncid for the root group of that file is provided.
11 Using that as a starting point, users can add new groups, or list and
12 navigate existing groups.
13 
14 All netCDF calls take a ncid which determines where the call will take
15 its action. For example, the NF90\_DEF\_VAR function takes a ncid as its
16 first parameter. It will create a variable in whichever group its ncid
17 refers to. Use the root ncid provided by NF90\_CREATE or NF90\_OPEN to
18 create a variable in the root group. Or use NF90\_DEF\_GRP to create a
19 group and use its ncid to define a variable in the new group.
20 
21 Variable are only visible in the group in which they are defined. The
22 same applies to attributes. “Global” attributes are defined in whichever
23 group is refered to by the ncid.
24 
25 Dimensions are visible in their groups, and all child groups.
26 
27 Group operations are only permitted on netCDF-4 files - that is, files
28 created with the HDF5 flag in nf90\_create. (see section
29 [NF90_CREATE](#NF90_005fCREATE)). Groups are not compatible with the
30 netCDF classic data model, so files created with the
31 NF90\_CLASSIC\_MODEL file cannot contain groups (except the root group).
32 
33 
34 3.1 Find a Group ID: NF90_INQ_NCID {#f90-find-a-group-id-nf90_inq_ncid}
35 =========================
36 
37 Given an ncid and group name (NULL or "" gets root group), return ncid
38 of the named group.
39 
40 ## Usage
41 
42 
43 ~~~~.fortran
44 
45 
46  function nf90_inq_ncid(ncid, name, grp_ncid)
47  integer, intent(in) :: ncid
48  character (len = *), intent(in) :: name
49  integer, intent(out) :: grp_ncid
50  integer :: nf90_inq_ncid
51 
52 
53 ~~~~
54 
55 
56 `NCID`
57 
58 : The group id for this operation.
59 
60 `NAME`
61 
62 : A character array that holds the name of the desired group. Must be
63  less then NF90\_MAX\_NAME.
64 
65 `GRPID`
66 
67 : The ID of the group will go here.
68 
69 
70 
71 ## Errors
72 
73 `NF90_NOERR`
74 
75 : No error.
76 
77 `NF90_EBADID`
78 
79 : Bad group id.
80 
81 `NF90_ENOTNC4`
82 
83 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
84  operations can only be performed on files defined with a create mode
85  which includes flag HDF5. (see section
86  [NF90_OPEN](#NF90_005fOPEN)).
87 
88 `NF90_ESTRICTNC3`
89 
90 : This file was created with the strict netcdf-3 flag, therefore
91  netcdf-4 operations are not allowed. (see section
92  [NF90_OPEN](#NF90_005fOPEN)).
93 
94 `NF90_EHDFERR`
95 
96 : An error was reported by the HDF5 layer.
97 
98 
99 
100 ## Example
101 
102 This example is from nf90\_test/ftst\_groups.F.
103 
104 
105 3.2 Get a List of Groups in a Group: NF90_INQ_GRPS {#f90-get-a-list-of-groups-in-a-group-nf90_inq_grps}
106 =========================
107 
108 
109 
110 Given a location id, return the number of groups it contains, and an
111 array of their ncids.
112 
113 
114 
115 ## Usage
116 
117 ~~~~.fortran
118 
119 
120 
121  function nf90_inq_grps(ncid, numgrps, ncids)
122  integer, intent(in) :: ncid
123  integer, intent(out) :: numgrps
124  integer, intent(out) :: ncids
125  integer :: nf90_inq_grps
126 
127 
128 
129 ~~~~
130 
131 `NCID`
132 
133 : The group id for this operation.
134 
135 `NUMGRPS`
136 
137 : An integer which will get number of groups in this group.
138 
139 `NCIDS`
140 
141 : An array of ints which will receive the IDs of all the groups in
142  this group.
143 
144 
145 
146 ## Errors
147 
148 `NF90_NOERR`
149 
150 : No error.
151 
152 `NF90_EBADID`
153 
154 : Bad group id.
155 
156 `NF90_ENOTNC4`
157 
158 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
159  operations can only be performed on files defined with a create mode
160  which includes flag HDF5. (see section
161  [NF90_OPEN](#NF90_005fOPEN)).
162 
163 `NF90_ESTRICTNC3`
164 
165 : This file was created with the strict netcdf-3 flag, therefore
166  netcdf-4 operations are not allowed. (see section
167  [NF90_OPEN](#NF90_005fOPEN)).
168 
169 `NF90_EHDFERR`
170 
171 : An error was reported by the HDF5 layer.
172 
173 
174 
175 ## Example
176 
177 3.3 Find all the Variables in a Group: NF90_INQ_VARIDS {#f90-find-all-the-variables-in-a-group-nf90_inq_varids}
178 =========================
179 
180 Find all varids for a location.
181 
182 
183 
184 ## Usage
185 
186 
187 ~~~~.fortran
188 
189 
190  function nf90_inq_varids(ncid, nvars, varids)
191  integer, intent(in) :: ncid
192  integer, intent(out) :: nvars
193  integer, intent(out) :: varids
194  integer :: nf90_inq_varids
195 
196 
197 ~~~~
198 
199 
200 `NCID`
201 
202 : The group id for this operation.
203 
204 `VARIDS`
205 
206 : An already allocated array to store the list of varids. Use
207  nf90\_inq\_nvars to find out how many variables there are. (see
208  section [Get Information about a Variable from Its ID:
209  NF90_INQUIRE_VARIABLE](#NF90_005fINQUIRE_005fVARIABLE)).
210 
211 
212 
213 ## Errors
214 
215 `NF90_NOERR`
216 
217 : No error.
218 
219 `NF90_EBADID`
220 
221 : Bad group id.
222 
223 `NF90_ENOTNC4`
224 
225 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
226  operations can only be performed on files defined with a create mode
227  which includes flag HDF5. (see section
228  [NF90_OPEN](#NF90_005fOPEN)).
229 
230 `NF90_ESTRICTNC3`
231 
232 : This file was created with the strict netcdf-3 flag, therefore
233  netcdf-4 operations are not allowed. (see section
234  [NF90_OPEN](#NF90_005fOPEN)).
235 
236 `NF90_EHDFERR`
237 
238 : An error was reported by the HDF5 layer.
239 
240 
241 
242 ## Example
243 
244 3.4 Find all Dimensions Visible in a Group: NF90_INQ_DIMIDS {#f90-find-all-dimensions-visible-in-a-group-nf90_inq_dimids}
245 =========================
246 
247 
248 
249 Find all dimids for a location. This finds all dimensions in a group, or
250 any of its parents.
251 
252 
253 
254 ## Usage
255 
256 
257 ~~~~.fortran
258 
259 
260  function nf90_inq_dimids(ncid, ndims, dimids, include_parents)
261  integer, intent(in) :: ncid
262  integer, intent(out) :: ndims
263  integer, intent(out) :: dimids
264  integer, intent(out) :: include_parents
265  integer :: nf90_inq_dimids
266 
267 
268 ~~~~
269 
270 
271 `NCID`
272 
273 : The group id for this operation.
274 
275 `NDIMS`
276 
277 : Returned number of dimensions for this location. If include\_parents
278  is non-zero, number of dimensions visible from this group, which
279  includes dimensions in parent groups.
280 
281 `DIMIDS`
282 
283 : An array of ints when the dimids of the visible dimensions will
284  be stashed. Use nf90\_inq\_ndims to find out how many dims are
285  visible from this group. (see section [Get Information about a Variable from Its ID: NF90_INQUIRE_VARIABLE](#f90-get-information-about-a-variable-from-its-id-nf90_inquire_variable) ).
286 
287 `INCLUDE_PARENTS`
288 
289 : If zero, only the group specified by NCID will be searched
290  for dimensions. Otherwise parent groups will be searched too.
291 
292 
293 
294 ## Errors
295 
296 `NF90_NOERR`
297 
298 : No error.
299 
300 `NF90_EBADID`
301 
302 : Bad group id.
303 
304 `NF90_ENOTNC4`
305 
306 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
307  operations can only be performed on files defined with a create mode
308  which includes flag HDF5. (see section
309  [NF90_OPEN](#NF90_005fOPEN)).
310 
311 `NF90_ESTRICTNC3`
312 
313 : This file was created with the strict netcdf-3 flag, therefore
314  netcdf-4 operations are not allowed. (see section
315  [NF90_OPEN](#NF90_005fOPEN)).
316 
317 `NF90_EHDFERR`
318 
319 : An error was reported by the HDF5 layer.
320 
321 
322 
323 ## Example
324 
325 3.5 Find the Length of a Group’s Full Name: NF90_INQ_GRPNAME_LEN {#f90-find-the-length-of-a-groups-full-name-nf90_inq_grpname_len}
326 =========================
327 
328 Given ncid, find length of the full name. (Root group is named "/", with
329 length 1.)
330 
331 ## Usage
332 
333 
334 ~~~~.fortran
335 
336 
337  function nf90_inq_grpname_len(ncid, len)
338  integer, intent(in) :: ncid
339  integer, intent(out) :: len
340  integer :: nf90_inq_grpname_len
341  end function nf90_inq_grpname_len
342 
343 
344 ~~~~
345 
346 
347 `NCID`
348 
349 : The group id for this operation.
350 
351 `LEN`
352 
353 : An integer where the length will be placed.
354 
355 
356 
357 ## Errors
358 
359 `NF90_NOERR`
360 
361 : No error.
362 
363 `NF90_EBADID`
364 
365 : Bad group id.
366 
367 `NF90_ENOTNC4`
368 
369 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
370  operations can only be performed on files defined with a create mode
371  which includes flag HDF5. (see section
372  [NF90_OPEN](#NF90_005fOPEN)).
373 
374 `NF90_ESTRICTNC3`
375 
376 : This file was created with the strict netcdf-3 flag, therefore
377  netcdf-4 operations are not allowed. (see section
378  [NF90_OPEN](#NF90_005fOPEN)).
379 
380 `NF90_EHDFERR`
381 
382 : An error was reported by the HDF5 layer.
383 
384 
385 
386 ## Example
387 
388 
389 3.6 Find a Group’s Name: NF90_INQ_GRPNAME {#f90-find-a-groups-name-nf90_inq_grpname}
390 =========================
391 
392 
393 
394 Given ncid, find relative name of group. (Root group is named "/").
395 
396 The name provided by this function is relative to the parent group. For
397 a full path name for the group is, with all parent groups included,
398 separated with a forward slash (as in Unix directory names) See section
399 [Find a Group’s Full Name:
400 NF90_INQ_GRPNAME_FULL](#f90-find-a-groups-full-name-nf90_inq_grpname_full).
401 
402 
403 
404 ## Usage
405 
406 
407 
408 ~~~~.fortran
409 
410  function nf90_inq_grpname(ncid, name)
411  integer, intent(in) :: ncid
412  character (len = *), intent(out) :: name
413  integer :: nf90_inq_grpname
414 
415 
416 ~~~~
417 
418 
419 `NCID`
420 
421 : The group id for this operation.
422 
423 `NAME`
424 
425 : The name of the group will be copied to this character array. The
426  name will be less than NF90\_MAX\_NAME in length.
427 
428 
429 
430 ## Errors
431 
432 `NF90_NOERR`
433 
434 : No error.
435 
436 `NF90_EBADID`
437 
438 : Bad group id.
439 
440 `NF90_ENOTNC4`
441 
442 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
443  operations can only be performed on files defined with a create mode
444  which includes flag HDF5. (see section
445  [NF90_OPEN](#NF90_005fOPEN)).
446 
447 `NF90_ESTRICTNC3`
448 
449 : This file was created with the strict netcdf-3 flag, therefore
450  netcdf-4 operations are not allowed. (see section
451  [NF90_OPEN](#NF90_005fOPEN)).
452 
453 `NF90_EHDFERR`
454 
455 : An error was reported by the HDF5 layer.
456 
457 
458 
459 ## Example
460 
461 
462 3.7 Find a Group’s Full Name: NF90_INQ_GRPNAME_FULL {#f90-find-a-groups-full-name-nf90_inq_grpname_full}
463 =========================
464 
465 
466 
467 Given ncid, find complete name of group. (Root group is named "/").
468 
469 The name provided by this function is a full path name for the group is,
470 with all parent groups included, separated with a forward slash (as in
471 Unix directory names). For a name relative to the parent group See
472 section [Find a Group’s Name:
473 NF90_INQ_GRPNAME](#f90-find-a-groups-name-nf90_inq_grpname).
474 
475 ## Usage
476 
477 
478 ~~~~.fortran
479 
480 
481  function nf90_inq_grpname_full(ncid, len, name)
482  integer, intent(in) :: ncid
483  integer, intent(out) :: len
484  character (len = *), intent(out) :: name
485  integer :: nf90_inq_grpname_full
486 
487 
488 ~~~~
489 
490 
491 `NCID`
492 
493 : The group id for this operation.
494 
495 `LEN`
496 
497 : The length of the full group name will go here.
498 
499 `NAME`
500 
501 : The name of the group will be copied to this character array.
502 
503 
504 
505 ## Errors
506 
507 `NF90_NOERR`
508 
509 : No error.
510 
511 `NF90_EBADID`
512 
513 : Bad group id.
514 
515 `NF90_ENOTNC4`
516 
517 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
518  operations can only be performed on files defined with a create mode
519  which includes flag HDF5. (see section
520  [NF90_OPEN](#NF90_005fOPEN)).
521 
522 `NF90_ESTRICTNC3`
523 
524 : This file was created with the strict netcdf-3 flag, therefore
525  netcdf-4 operations are not allowed. (see section
526  [NF90_OPEN](#NF90_005fOPEN)).
527 
528 `NF90_EHDFERR`
529 
530 : An error was reported by the HDF5 layer.
531 
532 
533 
534 ## Example
535 
536 This example is from test program nf\_test/f90tst\_grps.f90.
537 
538 
539 ~~~~.fortran
540 
541 
542  call check(nf90_inq_grpname_full(grpid1, len, name_in))
543  if (name_in .ne. grp1_full_name) stop 62
544 
545 ~~~~
546 
547 
548 
549 3.8 Find a Group’s Parent: NF90_INQ_GRP_PARENT {#f90-find-a-groups-parent-nf90_inq_grp_parent}
550 =========================
551 
552 
553 
554 Given ncid, find the ncid of the parent group.
555 
556 When used with the root group, this function returns the NF90\_ENOGRP
557 error (since the root group h has no parent.)
558 
559 
560 
561 ## Usage
562 
563 ~~~~.fortran
564 
565 
566 
567  function nf90_inq_grp_parent(ncid, parent_ncid)
568  integer, intent(in) :: ncid
569  integer, intent(out) :: parent_ncid
570  integer :: nf90_inq_grp_parent
571 
572 
573 ~~~~
574 
575 
576 `NCID`
577 
578 : The group id.
579 
580 `PARENT_NCID`
581 
582 : The ncid of the parent group will be copied here.
583 
584 
585 
586 ## Errors
587 
588 `NF90_NOERR`
589 
590 : No error.
591 
592 `NF90_EBADID`
593 
594 : Bad group id.
595 
596 `NF90_ENOGRP`
597 
598 : No parent group found (i.e. this is the root group).
599 
600 `NF90_ENOTNC4`
601 
602 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
603  operations can only be performed on files defined with a create mode
604  which includes flag HDF5. (see section
605  [NF90_OPEN](#NF90_005fOPEN)).
606 
607 `NF90_ESTRICTNC3`
608 
609 : This file was created with the strict netcdf-3 flag, therefore
610  netcdf-4 operations are not allowed. (see section
611  [NF90_OPEN](#NF90_005fOPEN)).
612 
613 `NF90_EHDFERR`
614 
615 : An error was reported by the HDF5 layer.
616 
617 
618 
619 ## Example
620 
621 3.9 Find a Group by Name: NF90_INQ_GRP_NCID {#f90-find-a-group-by-name-nf90_inq_grp_ncid}
622 =========================
623 
624 Given a group name an an ncid, find the ncid of the group id.
625 
626 ## Usage
627 
628 
629 ~~~~.fortran
630 
631 
632  function nf90_inq_grp_ncid(ncid, name, grpid)
633  integer, intent(in) :: ncid
634  character (len = *), intent(in) :: name
635  integer, intent(out) :: grpid
636  integer :: nf90_inq_grp_ncid
637 
638  nf90_inq_grp_ncid = nf_inq_grp_ncid(ncid, name, grpid)
639  end function nf90_inq_grp_ncid
640 
641 ~~~~
642 
643 
644 
645 `NCID`
646 
647 : The group id to look in.
648 
649 `GRP_NAME`
650 
651 : The name of the group that should be found.
652 
653 `GRP_NCID`
654 
655 : This will get the group id, if it is found.
656 
657 
658 
659 ## Return Codes
660 
661 
662 The following return codes may be returned by this function.
663 
664 `NF90_NOERR`
665 
666 : No error.
667 
668 `NF90_EBADID`
669 
670 : Bad group id.
671 
672 `NF90_EINVAL`
673 
674 : No name provided or name longer than NF90\_MAX\_NAME.
675 
676 `NF90_ENOGRP`
677 
678 : Named group not found.
679 
680 `NF90_ENOTNC4`
681 
682 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
683  operations can only be performed on files defined with a create mode
684  which includes flag HDF5. (see section
685  [NF90_OPEN](#NF90_005fOPEN)).
686 
687 `NF90_ESTRICTNC3`
688 
689 : This file was created with the strict netcdf-3 flag, therefore
690  netcdf-4 operations are not allowed. (see section
691  [NF90_OPEN](#NF90_005fOPEN)).
692 
693 `NF90_EHDFERR`
694 
695 : An error was reported by the HDF5 layer.
696 
697 
698 
699 ## Example
700 
701 This example is from test program nf\_test/f90tst\_grps.f90.
702 
703 
704 ~~~~.fortran
705 
706 
707  ! Get the group ids for the newly reopened file.
708  call check(nf90_inq_grp_ncid(ncid, GRP1_NAME, grpid1))
709  call check(nf90_inq_grp_ncid(grpid1, GRP2_NAME, grpid2))
710  call check(nf90_inq_grp_ncid(grpid2, GRP3_NAME, grpid3))
711  call check(nf90_inq_grp_ncid(grpid3, GRP4_NAME, grpid4))
712 
713 
714 ~~~~
715 
716 
717 3.10 Find a Group by its Fully-qualified Name: NF90_INQ_GRP_FULL_NCID {#f90-find-a-group-by-its-fully-qualified-name-nf90_inq_grp_full_ncid}
718 =========================
719 Given a fully qualified group name an an ncid, find the ncid of the
720 group id.
721 
722 
723 
724 ## Usage
725 
726 
727 ~~~~.fortran
728 
729 
730  function nf90_inq_grpname_full(ncid, len, name)
731  integer, intent(in) :: ncid
732  integer, intent(out) :: len
733  character (len = *), intent(out) :: name
734  integer :: nf90_inq_grpname_full
735 
736  nf90_inq_grpname_full = nf_inq_grpname_full(ncid, len, name)
737  end function nf90_inq_grpname_full
738 
739 
740 ~~~~
741 
742 
743 `NCID`
744 
745 : The group id to look in.
746 
747 `FULL_NAME`
748 
749 : The fully-qualified group name.
750 
751 `GRP_NCID`
752 
753 : This will get the group id, if it is found.
754 
755 
756 
757 ## Return Codes
758 
759 The following return codes may be returned by this function.
760 
761 `NF90_NOERR`
762 
763 : No error.
764 
765 `NF90_EBADID`
766 
767 : Bad group id.
768 
769 `NF90_EINVAL`
770 
771 : No name provided or name longer than NF90\_MAX\_NAME.
772 
773 `NF90_ENOGRP`
774 
775 : Named group not found.
776 
777 `NF90_ENOTNC4`
778 
779 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
780  operations can only be performed on files defined with a create mode
781  which includes flag HDF5. (see section
782  [NF90_OPEN](#NF90_005fOPEN)).
783 
784 `NF90_ESTRICTNC3`
785 
786 : This file was created with the strict netcdf-3 flag, therefore
787  netcdf-4 operations are not allowed. (see section
788  [NF90_OPEN](#NF90_005fOPEN)).
789 
790 `NF90_EHDFERR`
791 
792 : An error was reported by the HDF5 layer.
793 
794 
795 
796 ## Example
797 
798 This example is from test program nf\_test/tstf90\_grps.f90.
799 
800 
801 ~~~~.fortran
802 
803 
804  ! Check for the groups with full group names.
805  write(grp1_full_name, '(AA)') '/', GRP1_NAME
806  call check(nf90_inq_grp_full_ncid(ncid, grp1_full_name, grpid1))
807 
808 
809 ~~~~
810 
811 
812 3.11 Create a New Group: NF90_DEF_GRP {#f90-create-a-new-group-nf90_def_grp}
813 =========================
814 
815 
816 
817 Create a group. Its location id is returned in new\_ncid.
818 
819 
820 
821 ## Usage
822 
823 
824 ~~~~.fortran
825 
826 
827  function nf90_def_grp(parent_ncid, name, new_ncid)
828  integer, intent(in) :: parent_ncid
829  character (len = *), intent(in) :: name
830  integer, intent(out) :: new_ncid
831  integer :: nf90_def_grp
832 
833 
834 
835 ~~~~
836 
837 `PARENT_NCID`
838 
839 : The group id of the parent group.
840 
841 `NAME`
842 
843 : The name of the new group, which must be different from the name of
844  any variable within the same parent group.
845 
846 `NEW_NCID`
847 
848 : The ncid of the new group will be placed there.
849 
850 
851 
852 ## Errors
853 
854 `NF90_NOERR`
855 
856 : No error.
857 
858 `NF90_EBADID`
859 
860 : Bad group id.
861 
862 `NF90_ENAMEINUSE`
863 
864 : That name is in use. Group names must be unique within a group.
865 
866 `NF90_EMAXNAME`
867 
868 : Name exceed max length NF90\_MAX\_NAME.
869 
870 `NF90_EBADNAME`
871 
872 : Name contains illegal characters.
873 
874 `NF90_ENOTNC4`
875 
876 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
877  operations can only be performed on files defined with a create mode
878  which includes flag HDF5. (see section
879  [NF90_OPEN](#NF90_005fOPEN)).
880 
881 `NF90_ESTRICTNC3`
882 
883 : This file was created with the strict netcdf-3 flag, therefore
884  netcdf-4 operations are not allowed. (see section
885  [NF90_OPEN](#NF90_005fOPEN)).
886 
887 `NF90_EHDFERR`
888 
889 : An error was reported by the HDF5 layer.
890 
891 `NF90_EPERM`
892 
893 : Attempt to write to a read-only file.
894 
895 `NF90_ENOTINDEFINE`
896 
897 : Not in define mode.
898 
899 
900 
901 ## Example
902 
903 
904 ~~~~.fortran
905 
906 
907 C Create the netCDF file.
908  retval = nf90_create(file_name, NF90_NETCDF4, ncid)
909  if (retval .ne. nf90_noerr) call handle_err(retval)
910 
911 C Create a group and a subgroup.
912  retval = nf90_def_grp(ncid, group_name, grpid)
913  if (retval .ne. nf90_noerr) call handle_err(retval)
914  retval = nf90_def_grp(grpid, sub_group_name, sub_grpid)
915  if (retval .ne. nf90_noerr) call handle_err(retval)
916 
917 ~~~~

Return to the Main Unidata NetCDF page.
Generated on Thu Nov 9 2017 06:56:52 for NetCDF-Fortran. NetCDF is a Unidata library.