6 NetCDF-4 added support for hierarchical groups within netCDF datasets.
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.
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.
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.
25 Dimensions are visible in their groups, and all child groups.
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).
34 3.1 Find a Group ID: NF90_INQ_NCID {#f90-find-a-group-id-nf90_inq_ncid}
35 =========================
37 Given an ncid and group name (NULL or "" gets root group), return ncid
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
58 : The group id for this operation.
62 : A character array that holds the name of the desired group. Must be
63 less then NF90\_MAX\_NAME.
67 : The ID of the group will go here.
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)).
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)).
96 : An error was reported by the HDF5 layer.
102 This example is from nf90\_test/ftst\_groups.F.
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 =========================
110 Given a location id, return the number of groups it contains, and an
111 array of their ncids.
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
133 : The group id for this operation.
137 : An integer which will get number of groups in this group.
141 : An array of ints which will receive the IDs of all the groups in
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)).
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)).
171 : An error was reported by the HDF5 layer.
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 =========================
180 Find all varids for a location.
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
202 : The group id for this operation.
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)).
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)).
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)).
238 : An error was reported by the HDF5 layer.
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 =========================
249 Find all dimids for a location. This finds all dimensions in a group, or
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
273 : The group id for this operation.
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.
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) ).
289 : If zero, only the group specified by NCID will be searched
290 for dimensions. Otherwise parent groups will be searched too.
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)).
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)).
319 : An error was reported by the HDF5 layer.
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 =========================
328 Given ncid, find length of the full name. (Root group is named "/", with
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
349 : The group id for this operation.
353 : An integer where the length will be placed.
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)).
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)).
382 : An error was reported by the HDF5 layer.
389 3.6 Find a Group’s Name: NF90_INQ_GRPNAME {#f90-find-a-groups-name-nf90_inq_grpname}
390 =========================
394 Given ncid, find relative name of group. (Root group is named "/").
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).
410 function nf90_inq_grpname(ncid, name)
411 integer, intent(in) :: ncid
412 character (len = *), intent(out) :: name
413 integer :: nf90_inq_grpname
421 : The group id for this operation.
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.
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)).
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)).
455 : An error was reported by the HDF5 layer.
462 3.7 Find a Group’s Full Name: NF90_INQ_GRPNAME_FULL {#f90-find-a-groups-full-name-nf90_inq_grpname_full}
463 =========================
467 Given ncid, find complete name of group. (Root group is named "/").
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).
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
493 : The group id for this operation.
497 : The length of the full group name will go here.
501 : The name of the group will be copied to this character array.
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)).
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)).
530 : An error was reported by the HDF5 layer.
536 This example is from test program nf\_test/f90tst\_grps.f90.
542 call check(nf90_inq_grpname_full(grpid1, len, name_in))
543 if (name_in .ne. grp1_full_name) stop 62
549 3.8 Find a Group’s Parent: NF90_INQ_GRP_PARENT {#f90-find-a-groups-parent-nf90_inq_grp_parent}
550 =========================
554 Given ncid, find the ncid of the parent group.
556 When used with the root group, this function returns the NF90\_ENOGRP
557 error (since the root group h has no parent.)
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
582 : The ncid of the parent group will be copied here.
598 : No parent group found (i.e. this is the root group).
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)).
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)).
615 : An error was reported by the HDF5 layer.
621 3.9 Find a Group by Name: NF90_INQ_GRP_NCID {#f90-find-a-group-by-name-nf90_inq_grp_ncid}
622 =========================
624 Given a group name an an ncid, find the ncid of the group id.
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
638 nf90_inq_grp_ncid = nf_inq_grp_ncid(ncid, name, grpid)
639 end function nf90_inq_grp_ncid
647 : The group id to look in.
651 : The name of the group that should be found.
655 : This will get the group id, if it is found.
662 The following return codes may be returned by this function.
674 : No name provided or name longer than NF90\_MAX\_NAME.
678 : Named group not found.
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)).
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)).
695 : An error was reported by the HDF5 layer.
701 This example is from test program nf\_test/f90tst\_grps.f90.
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))
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
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
736 nf90_inq_grpname_full = nf_inq_grpname_full(ncid, len, name)
737 end function nf90_inq_grpname_full
745 : The group id to look in.
749 : The fully-qualified group name.
753 : This will get the group id, if it is found.
759 The following return codes may be returned by this function.
771 : No name provided or name longer than NF90\_MAX\_NAME.
775 : Named group not found.
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)).
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)).
792 : An error was reported by the HDF5 layer.
798 This example is from test program nf\_test/tstf90\_grps.f90.
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))
812 3.11 Create a New Group: NF90_DEF_GRP {#f90-create-a-new-group-nf90_def_grp}
813 =========================
817 Create a group. Its location id is returned in new\_ncid.
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
839 : The group id of the parent group.
843 : The name of the new group, which must be different from the name of
844 any variable within the same parent group.
848 : The ncid of the new group will be placed there.
864 : That name is in use. Group names must be unique within a group.
868 : Name exceed max length NF90\_MAX\_NAME.
872 : Name contains illegal characters.
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)).
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)).
889 : An error was reported by the HDF5 layer.
893 : Attempt to write to a read-only file.
897 : Not in define mode.
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)
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)