"Fossies" - the Fresh Open Source Software Archive

Member "netcdf-fortran-4.5.2/docs/netcdf-f90-sec3-groups.md" (18 Sep 2019, 17804 Bytes) of package /linux/misc/netcdf-fortran-4.5.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

3 Groups

[TOC]

NetCDF-4 added support for hierarchical groups within netCDF datasets.

Groups are identified with a ncid, which identifies both the open file, and the group within that file. When a file is opened with NF90_OPEN or NF90_CREATE, the ncid for the root group of that file is provided. Using that as a starting point, users can add new groups, or list and navigate existing groups.

All netCDF calls take a ncid which determines where the call will take its action. For example, the NF90_DEF_VAR function takes a ncid as its first parameter. It will create a variable in whichever group its ncid refers to. Use the root ncid provided by NF90_CREATE or NF90_OPEN to create a variable in the root group. Or use NF90_DEF_GRP to create a group and use its ncid to define a variable in the new group.

Variable are only visible in the group in which they are defined. The same applies to attributes. “Global” attributes are defined in whichever group is refered to by the ncid.

Dimensions are visible in their groups, and all child groups.

Group operations are only permitted on netCDF-4 files - that is, files created with the HDF5 flag in nf90_create. (see section NF90_CREATE). Groups are not compatible with the netCDF classic data model, so files created with the NF90_CLASSIC_MODEL file cannot contain groups (except the root group).

3.1 Find a Group ID: NF90_INQ_NCID

Given an ncid and group name (NULL or "" gets root group), return ncid of the named group.

Usage



  function nf90_inq_ncid(ncid, name, grp_ncid)
    integer, intent(in) :: ncid
    character (len = *), intent(in) :: name
    integer, intent(out) :: grp_ncid
    integer :: nf90_inq_ncid

NCID

The group id for this operation.

NAME

A character array that holds the name of the desired group. Must be less then NF90_MAX_NAME.

GRPID

The ID of the group will go here.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

This example is from nf90_test/ftst_groups.F.

3.2 Get a List of Groups in a Group: NF90_INQ_GRPS

Given a location id, return the number of groups it contains, and an array of their ncids.

Usage




  function nf90_inq_grps(ncid, numgrps, ncids)
    integer, intent(in) :: ncid
    integer, intent(out) :: numgrps
    integer, intent(out) :: ncids
    integer :: nf90_inq_grps


NCID

The group id for this operation.

NUMGRPS

An integer which will get number of groups in this group.

NCIDS

An array of ints which will receive the IDs of all the groups in this group.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

3.3 Find all the Variables in a Group: NF90_INQ_VARIDS

Find all varids for a location.

Usage



  function nf90_inq_varids(ncid, nvars, varids)
    integer, intent(in) :: ncid
    integer, intent(out) :: nvars
    integer, intent(out) :: varids
    integer :: nf90_inq_varids

NCID

The group id for this operation.

VARIDS

An already allocated array to store the list of varids. Use nf90_inq_nvars to find out how many variables there are. (see section Get Information about a Variable from Its ID: NF90_INQUIRE_VARIABLE).

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

3.4 Find all Dimensions Visible in a Group: NF90_INQ_DIMIDS

Find all dimids for a location. This finds all dimensions in a group, or any of its parents.

Usage



  function nf90_inq_dimids(ncid, ndims, dimids, include_parents)
    integer, intent(in) :: ncid
    integer, intent(out) :: ndims
    integer, intent(out) :: dimids
    integer, intent(out) :: include_parents
    integer :: nf90_inq_dimids

NCID

The group id for this operation.

NDIMS

Returned number of dimensions for this location. If include_parents is non-zero, number of dimensions visible from this group, which includes dimensions in parent groups.

DIMIDS

An array of ints when the dimids of the visible dimensions will be stashed. Use nf90_inq_ndims to find out how many dims are visible from this group. (see section Get Information about a Variable from Its ID: NF90_INQUIRE_VARIABLE ).

INCLUDE_PARENTS

If zero, only the group specified by NCID will be searched for dimensions. Otherwise parent groups will be searched too.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

3.5 Find the Length of a Group’s Full Name: NF90_INQ_GRPNAME_LEN

Given ncid, find length of the full name. (Root group is named “/”, with length 1.)

Usage



  function nf90_inq_grpname_len(ncid, len)
    integer, intent(in) :: ncid
    integer, intent(out) :: len
    integer :: nf90_inq_grpname_len
  end function nf90_inq_grpname_len

NCID

The group id for this operation.

LEN

An integer where the length will be placed.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

3.6 Find a Group’s Name: NF90_INQ_GRPNAME

Given ncid, find relative name of group. (Root group is named “/”).

The name provided by this function is relative to the parent group. For a full path name for the group is, with all parent groups included, separated with a forward slash (as in Unix directory names) See section Find a Group’s Full Name: NF90_INQ_GRPNAME_FULL.

Usage


  function nf90_inq_grpname(ncid, name)
    integer, intent(in) :: ncid
    character (len = *), intent(out) :: name
    integer :: nf90_inq_grpname

NCID

The group id for this operation.

NAME

The name of the group will be copied to this character array. The name will be less than NF90_MAX_NAME in length.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

3.7 Find a Group’s Full Name: NF90_INQ_GRPNAME_FULL

Given ncid, find complete name of group. (Root group is named “/”).

The name provided by this function is a full path name for the group is, with all parent groups included, separated with a forward slash (as in Unix directory names). For a name relative to the parent group See section Find a Group’s Name: NF90_INQ_GRPNAME.

Usage



  function nf90_inq_grpname_full(ncid, len, name)
    integer, intent(in) :: ncid
    integer, intent(out) :: len
    character (len = *), intent(out) :: name
    integer :: nf90_inq_grpname_full

NCID

The group id for this operation.

LEN

The length of the full group name will go here.

NAME

The name of the group will be copied to this character array.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

This example is from test program nf_test/f90tst_grps.f90.



  call check(nf90_inq_grpname_full(grpid1, len, name_in))
  if (name_in .ne. grp1_full_name) stop 62

3.8 Find a Group’s Parent: NF90_INQ_GRP_PARENT

Given ncid, find the ncid of the parent group.

When used with the root group, this function returns the NF90_ENOGRP error (since the root group h has no parent.)

Usage




  function nf90_inq_grp_parent(ncid, parent_ncid)
    integer, intent(in) :: ncid
    integer, intent(out) :: parent_ncid
    integer :: nf90_inq_grp_parent

NCID

The group id.

PARENT_NCID

The ncid of the parent group will be copied here.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENOGRP

No parent group found (i.e. this is the root group).

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

3.9 Find a Group by Name: NF90_INQ_GRP_NCID

Given a group name an an ncid, find the ncid of the group id.

Usage



  function nf90_inq_grp_ncid(ncid, name, grpid)
    integer, intent(in) :: ncid
    character (len = *), intent(in) :: name
    integer, intent(out) :: grpid
    integer :: nf90_inq_grp_ncid

    nf90_inq_grp_ncid = nf_inq_grp_ncid(ncid, name, grpid)
  end function nf90_inq_grp_ncid
NCID

The group id to look in.

GRP_NAME

The name of the group that should be found.

GRP_NCID

This will get the group id, if it is found.

Return Codes

The following return codes may be returned by this function.

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_EINVAL

No name provided or name longer than NF90_MAX_NAME.

NF90_ENOGRP

Named group not found.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

This example is from test program nf_test/f90tst_grps.f90.



  ! Get the group ids for the newly reopened file.
  call check(nf90_inq_grp_ncid(ncid, GRP1_NAME, grpid1))
  call check(nf90_inq_grp_ncid(grpid1, GRP2_NAME, grpid2))
  call check(nf90_inq_grp_ncid(grpid2, GRP3_NAME, grpid3))
  call check(nf90_inq_grp_ncid(grpid3, GRP4_NAME, grpid4))

3.10 Find a Group by its Fully-qualified Name: NF90_INQ_GRP_FULL_NCID

Given a fully qualified group name an an ncid, find the ncid of the group id.

Usage



  function nf90_inq_grpname_full(ncid, len, name)
    integer, intent(in) :: ncid
    integer, intent(out) :: len
    character (len = *), intent(out) :: name
    integer :: nf90_inq_grpname_full

    nf90_inq_grpname_full = nf_inq_grpname_full(ncid, len, name)
  end function nf90_inq_grpname_full

NCID

The group id to look in.

FULL_NAME

The fully-qualified group name.

GRP_NCID

This will get the group id, if it is found.

Return Codes

The following return codes may be returned by this function.

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_EINVAL

No name provided or name longer than NF90_MAX_NAME.

NF90_ENOGRP

Named group not found.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

Example

This example is from test program nf_test/tstf90_grps.f90.



  ! Check for the groups with full group names.
  write(grp1_full_name, '(AA)') '/', GRP1_NAME
  call check(nf90_inq_grp_full_ncid(ncid, grp1_full_name, grpid1))

3.11 Create a New Group: NF90_DEF_GRP

Create a group. Its location id is returned in new_ncid.

Usage



  function nf90_def_grp(parent_ncid, name, new_ncid)
    integer, intent(in) :: parent_ncid
    character (len = *), intent(in) :: name
    integer, intent(out) :: new_ncid
    integer :: nf90_def_grp


PARENT_NCID

The group id of the parent group.

NAME

The name of the new group, which must be different from the name of any variable within the same parent group.

NEW_NCID

The ncid of the new group will be placed there.

Errors

NF90_NOERR

No error.

NF90_EBADID

Bad group id.

NF90_ENAMEINUSE

That name is in use. Group names must be unique within a group.

NF90_EMAXNAME

Name exceed max length NF90_MAX_NAME.

NF90_EBADNAME

Name contains illegal characters.

NF90_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see section NF90_OPEN).

NF90_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see section NF90_OPEN).

NF90_EHDFERR

An error was reported by the HDF5 layer.

NF90_EPERM

Attempt to write to a read-only file.

NF90_ENOTINDEFINE

Not in define mode.

Example



C     Create the netCDF file.
      retval = nf90_create(file_name, NF90_NETCDF4, ncid)
      if (retval .ne. nf90_noerr) call handle_err(retval)

C     Create a group and a subgroup.
      retval = nf90_def_grp(ncid, group_name, grpid)
      if (retval .ne. nf90_noerr) call handle_err(retval)
      retval = nf90_def_grp(grpid, sub_group_name, sub_grpid)
      if (retval .ne. nf90_noerr) call handle_err(retval)