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
47 integer, intent(in) :: ncid
48 character (len = *), intent(in) :: name
49 integer, intent(out) :: grp_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.
122 integer, intent(in) :: ncid
123 integer, intent(out) :: numgrps
124 integer, intent(out) :: ncids
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.
191 integer, intent(in) :: ncid
192 integer, intent(out) :: nvars
193 integer, intent(out) :: 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
261 integer, intent(in) :: ncid
262 integer, intent(out) :: ndims
263 integer, intent(out) :: dimids
264 integer, intent(out) :: include_parents
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
338 integer, intent(in) :: ncid
339 integer, intent(out) :: 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:
411 integer, intent(in) :: ncid
412 character (len = *), intent(out) :: name
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:
482 integer, intent(in) :: ncid
483 integer, intent(out) :: len
484 character (len = *), intent(out) :: name
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.
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.)
568 integer, intent(in) :: ncid
569 integer, intent(out) :: parent_ncid
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.
633 integer, intent(in) :: ncid
634 character (len = *), intent(in) :: name
635 integer, intent(out) :: grpid
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.
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
731 integer, intent(in) :: ncid
732 integer, intent(out) :: len
733 character (len = *), intent(out) :: name
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
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.
828 integer, intent(in) :: parent_ncid
829 character (len = *), intent(in) :: name
830 integer, intent(out) :: new_ncid
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.
913 if (retval .ne. nf90_noerr) call handle_err(retval)
915 if (retval .ne. nf90_noerr) call handle_err(retval)
integer function nf_inq_grp_ncid(ncid, grp_name, parent_ncid)
integer function nf90_inq_dimids(ncid, ndims, dimids, include_parents)
integer function nf90_inq_grpname_full(ncid, len, name)
integer function nf90_inq_ncid(ncid, name, grp_ncid)
integer function nf90_create(path, cmode, ncid, initialsize, chunksize)
integer function nf90_inq_grpname_len(ncid, len)
integer function nf90_inq_grp_parent(ncid, parent_ncid)
integer function nf90_inq_grpname(ncid, name)
integer function nf90_inq_grp_full_ncid(ncid, full_name, grpid)
integer function nf90_inq_grp_ncid(ncid, name, grpid)
integer function nf_inq_grpname_full(ncid, nlen, name)
integer function nf90_inq_varids(ncid, nvars, varids)
integer function nf90_inq_grps(ncid, numgrps, ncids)
integer function nf90_def_grp(parent_ncid, name, new_ncid)