stdlib_NetCDF Level-0 Interface Guide

The nc_* thin wrappers of netcdf-fortran 4.6.2

Contents

1 Use of the Level-0 Library
2 Datasets
3 Groups
4 Dimensions
5 User Defined Data Types
6 Variables
7 Attributes
8 Parallel I/O
9 Error States and Status Codes
- 9.1 The Error State: nc_state_type
- 9.2 Symbolic Name of a Status Code: nc_status_name
A Summary of the Level-0 Interface
B Constants

1 Use of the Level-0 Library

This guide describes level 0 of stdlib_NetCDF: the nc_* routines, one for each nf90_* procedure of netcdf-fortran 4.6.2 (plus nc_inq_unlimdims, which netcdf-fortran lacks), and the NC_* constants. Everything is available through

use stdlib_NetCDF

Each nc_<name> takes the arguments of nf90_<name>, in the same order, and is a subroutine with a trailing optional err argument instead of a function returning an integer status (see Error Handling). Data and attributes go through generic interfaces over the integer and real kinds of stdlib_kinds (int8, int16, int32, int64, sp, dp) and character data, at ranks 0 to 7.

You can use a small subset of the library for most tasks. The sections below show the usual sequences of calls, indented to show which calls happen between which. Level 1 of stdlib_NetCDF (netcdf_file, netcdf_variable) builds the same sequences into one-line calls; it is described in docs/API.md.

1.1 Creating a NetCDF Dataset

Here is a typical sequence of calls used to create a new netCDF dataset:

nc_create              ! create the dataset: enter define mode
    nc_def_dim         ! define dimensions: from name and length
    nc_def_var         ! define variables: from name, type, dimensions
    nc_put_att         ! assign attribute values
nc_enddef              ! end definitions: leave define mode
    nc_put_var         ! provide values for variables
nc_close               ! close: save the new dataset

Only one call is needed to create a dataset, and in define mode dimensions, variables and attributes may be defined in any order, as long as a dimension exists before a variable uses it. nc_def_dim and nc_def_var return the IDs that the following calls use.

Example

Create new.nc with a 2-D variable and its attributes:

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, x_dimid, y_dimid, varid
real(dp) :: data(6, 12)

call random_number(data)
! NC_CLOBBER: create, overwriting the file if it exists
call nc_create("new.nc", NC_CLOBBER, ncid)
call nc_def_dim(ncid, "x", 6, x_dimid)
call nc_def_dim(ncid, "y", 12, y_dimid)
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_def_var(ncid, "data", NC_DOUBLE, varid, dimids=[x_dimid, y_dimid])
call nc_put_att(ncid, varid, "units", "m")
! NC_GLOBAL: a global attribute, of the dataset rather than of a variable
call nc_put_att(ncid, NC_GLOBAL, "title", "a new dataset")
call nc_enddef(ncid)
call nc_put_var(ncid, varid, data)
call nc_close(ncid)

1.2 Reading a NetCDF Dataset with Known Names

When the names of the dimensions, variables and attributes are known, the usual sequence is:

nc_open                    ! open an existing dataset
    nc_inq_dimid           ! get dimension IDs
    nc_inq_varid           ! get variable IDs
    nc_get_att             ! get attribute values
    nc_get_var             ! get values of variables
nc_close                   ! close the dataset

A dataset is opened in data mode. Dimension lengths, needed to size the arrays read, come from nc_inquire_dimension.

Example

Read the variable rh of foo.nc and its units attribute:

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, varid, lon_dimid, nlon, lat_dimid, nlat, time_dimid, ntime
real(dp), allocatable :: rh(:, :, :)
character(len=32) :: units

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_dimid(ncid, "lon", lon_dimid)
call nc_inquire_dimension(ncid, lon_dimid, len=nlon)
call nc_inq_dimid(ncid, "lat", lat_dimid)
call nc_inquire_dimension(ncid, lat_dimid, len=nlat)
call nc_inq_dimid(ncid, "time", time_dimid)
call nc_inquire_dimension(ncid, time_dimid, len=ntime)
allocate(rh(nlon, nlat, ntime))
call nc_inq_varid(ncid, "rh", varid)
units = ""
call nc_get_att(ncid, varid, "units", units)
call nc_get_var(ncid, varid, rh)
call nc_close(ncid)

1.3 Reading a NetCDF Dataset with Unknown Names

A generic application (a dump tool, a converter) learns what a dataset contains from it:

nc_open                            ! open the dataset
    nc_inquire                     ! numbers of dimensions, variables, attributes; unlimited dimension
        nc_inq_dimids              ! the dimension IDs
        nc_inquire_dimension       ! name and length of each
        nc_inq_varids              ! the variable IDs
        nc_inquire_variable        ! name, type, dimensions, number of attributes of each
            nc_inq_attname         ! attribute names, by number
            nc_inquire_attribute   ! type and length of each attribute
            nc_get_att             ! attribute values
            nc_get_var             ! variable values
nc_close                           ! close the dataset

Dimension and variable IDs are 1, 2, 3, ... in definition order; attribute numbers are 1, 2, 3, ... for each variable (and for NC_GLOBAL).

Example

List the variables of foo.nc with their types and numbers of dimensions:

use stdlib_NetCDF
implicit none
integer :: ncid, nvars, i, xtype, ndims
! NC_MAX_VARS: the most variables a dataset may have, so the list fits
integer :: varids(NC_MAX_VARS)
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varids(ncid, nvars, varids)
do i = 1, nvars
    call nc_inquire_variable(ncid, varids(i), name=name, xtype=xtype, ndims=ndims)
    print "(a, ': type ', i0, ', ', i0, ' dimension(s)')", trim(name), xtype, ndims
end do
call nc_close(ncid)

1.4 Writing Data in an Existing NetCDF Dataset

With no new definitions, an existing dataset is opened for writing and written in data mode:

nc_open              ! open the dataset with NC_WRITE
    nc_inq_varid     ! get variable IDs
    nc_put_var       ! provide new values for variables, if any
    nc_put_att       ! provide new values for attributes, if any
nc_close             ! close the dataset

An attribute that grows needs define mode on a classic-format dataset (see the next section).

Example

Append a third record of rh to foo.nc:

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, varid
real(dp) :: field(10, 5)

field = 42.0_dp
call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_inq_varid(ncid, "rh", varid)
call nc_put_var(ncid, varid, field, start=[1, 1, 3], count=[10, 5, 1])
call nc_close(ncid)

1.5 Adding New Dimensions, Variables, Attributes

An existing dataset can be extended by reentering define mode:

nc_open              ! open the dataset with NC_WRITE
    nc_redef         ! put it into define mode
        nc_def_dim   ! define additional dimensions (if any)
        nc_def_var   ! define additional variables (if any)
        nc_put_att   ! define other attributes (if any)
    nc_enddef        ! check definitions, leave define mode
    nc_put_var       ! provide values for the new variables
nc_close             ! close the dataset

On a classic-format dataset, leaving define mode after changes may move the data of every variable; NetCDF-4 datasets are not affected, and accept new definitions even in data mode (the library switches by itself).

Example

Add a variable pressure(lon, lat) to foo.nc:

use stdlib_NetCDF
use stdlib_kinds, only: sp
implicit none
integer :: ncid, lon_dimid, lat_dimid, varid
real(sp) :: p(10, 5)

p = 1013.25_sp
call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon_dimid)
call nc_inq_dimid(ncid, "lat", lat_dimid)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "pressure", NC_FLOAT, varid, dimids=[lon_dimid, lat_dimid])
call nc_put_att(ncid, varid, "units", "hPa")
call nc_enddef(ncid)
call nc_put_var(ncid, varid, p)
call nc_close(ncid)

1.6 Error Handling

Every routine takes a trailing optional argument err of class state_type (from stdlib's stdlib_error), in place of the integer status that the nf90_* functions return.

err absent (the simplest use): a failure is first reported to the active report sink of stdlib_report (by default stdlib's global_logger, if it has log units; change it with set_report_sink), then the program stops with the NetCDF message, which ends with the symbolic status code: NetCDF: Variable not found (NC_ENOTVAR = -49).
err present: the outcome is returned in it and the program continues; nothing is reported. A type(state_type) gets stdlib's flag, message and location (state is STDLIB_IO_ERROR for any NetCDF failure; test it with err%ok() / err%error()).
type(nc_state_type) (extends state_type) also gets the NetCDF status in err%nc_status, NC_NOERR after a success, to branch on specific errors.

Pass err by keyword (err=err) when the routine has optional arguments before it (for example nc_create, nc_open, nc_inquire, nc_def_var, nc_put_var). The message of a status code is nc_strerror(status), its symbolic name nc_status_name(status).

Example

Look for a variable that may not exist, and react to that case only:

use stdlib_NetCDF
implicit none
integer :: ncid, varid
type(nc_state_type) :: err

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varid(ncid, "salinity", varid, err)
! NC_ENOTVAR: the status when no variable has that name
if (err%nc_status == NC_ENOTVAR) then
    print "(a)", "no salinity in this file: " // trim(err%message)
else if (err%error()) then
    error stop trim(err%message)
end if
call nc_close(ncid)

1.7 Compiling and Linking with the Library

stdlib_NetCDF is an fpm package; a project uses it as a dependency:

[dependencies]
stdlib_NetCDF = { git = "...", tag = "..." }   # or { path = "../stdlib_NetCDF" }

It links netcdff and netcdf, whose module and library directories fpm cannot find on its own. Pass them through the environment, for instance with Homebrew:

export FPM_FFLAGS="-I$(brew --prefix netcdf-fortran)/include -I$(brew --prefix netcdf)/include"
export FPM_LDFLAGS="-L$(brew --prefix netcdf-fortran)/lib -L$(brew --prefix netcdf)/lib"
fpm build

nf-config --fflags --flibs prints the right flags on other systems. What works depends on how netcdf-c and netcdf-fortran were built (nc-config --all): with Homebrew's netcdf 4.9.3 and netcdf-fortran 4.6.2, szip, quantization and HDF5 filters work, but Zstandard returns NC_ENOTBUILT and parallel I/O is unavailable. The routines still compile and report such failures through err.

1.8 Differences from the netcdf-fortran Interface

Names: nf90_<name> becomes nc_<name>, nf90_<constant> becomes NC_<CONSTANT>.
Subroutines with err instead of functions returning a status; see Error Handling.
Kinds: data and attributes use stdlib_kinds (int8 ... int64, sp, dp).
Rank-0 data (nc_put_var/nc_get_var of a scalar) accepts start but no count, stride or map, as netcdf-fortran's own scalar specifics.
nc_def_var takes every storage option of nf90_def_var and refuses them for a scalar variable (NC_EINVAL) instead of dropping them; nc_inquire_variable returns them all.
Routines calling netcdf-c directly, through bind(c): nc_inq_type, nc_create_mp and nc_open_mp (their netcdf-fortran 4.6.2 counterparts are broken), and nc_inq_unlimdims (absent from netcdf-fortran). They follow the Fortran conventions of the others (1-based IDs).
Not available (netcdf-fortran lacks them too): NC_STRING data (the type constant exists), in-memory datasets, per-variable chunk caches.

2 Datasets

2.1 Datasets Introduction

A netCDF dataset is a file (or, in NetCDF-4, a group hierarchy stored in one file) holding dimensions, variables and attributes. It is identified by its path when created or opened, and by a small integer, the NetCDF ID, afterwards.

A dataset is in one of two modes. In define mode dimensions, variables and attributes are created, renamed or deleted; in data mode variable values are read and written. A new dataset starts in define mode, an opened one in data mode; nc_redef and nc_enddef switch between them. NetCDF-4 datasets switch by themselves when needed, classic ones do not.

The formats, chosen at creation by the cmode flags:

classic (default): the original format, with a 2 GiB limit on some sizes;
64-bit offset (NC_64BIT_OFFSET) and 64-bit data / CDF5 (NC_64BIT_DATA): classic model with larger limits;
NetCDF-4 (NC_NETCDF4): HDF5-based, with groups, user-defined types, compression, chunking, filters and several unlimited dimensions;
NetCDF-4 classic model (NC_NETCDF4 + NC_CLASSIC_MODEL): HDF5 storage restricted to the classic data model.

The routines of this chapter are in module stdlib_netcdf_file, except nc_strerror (stdlib_netcdf_error).

2.2 Get Error Message from Status: nc_strerror

The function nc_strerror returns the message of a NetCDF status code. The messages that err receives are built from it; it is useful with err%nc_status or with the codes listed in Constants.

Usage

function nc_strerror(status) result(message)
    integer, intent(in)           :: status
    character(len=:), allocatable :: message

status: A NetCDF status code (NC_NOERR, NC_ENOTVAR, ...).
message: The message, e.g. NetCDF: Variable not found; No error for NC_NOERR.

Errors

None: an unknown code gives a generic message.

Example

use stdlib_NetCDF
implicit none

! NC_EBADDIM: the status when no dimension has that name
print "(a)", nc_strerror(NC_EBADDIM)

2.3 Get the Library Version: nc_inq_libvers

The function nc_inq_libvers returns the version of the netcdf-c library in use, as a string beginning with the version number (e.g. 4.9.3 of ...).

Usage

function nc_inq_libvers() result(version)
    character(len=:), allocatable :: version

version: The version string.

Errors

None.

Example

use stdlib_NetCDF
implicit none

print "(a)", "netcdf-c " // trim(nc_inq_libvers())

2.4 Create a Dataset: nc_create

nc_create creates a new netCDF dataset, returns its NetCDF ID, and leaves it open in define mode. The creation mode cmode combines flags with ior: NC_CLOBBER (the default: overwrite an existing file) or NC_NOCLOBBER (fail if it exists); the format, NC_64BIT_OFFSET, NC_64BIT_DATA, NC_NETCDF4, NC_NETCDF4 with NC_CLASSIC_MODEL; NC_SHARE for unbuffered access by concurrent readers; NC_DISKLESS to keep the dataset in memory only (it is not written to disk: netcdf-fortran has no NC_PERSIST, which netcdf-c needs for that).

The optional arguments tune the I/O; they are the same as nf90_create's.

Usage

subroutine nc_create(path, cmode, ncid, initialsize, chunksize, cache_size, cache_nelems, &
        cache_preemption, comm, info, err)
    character(len=*), intent(in)             :: path
    integer, intent(in)                      :: cmode
    integer, intent(out)                     :: ncid
    integer, intent(in), optional            :: initialsize
    integer, intent(inout), optional         :: chunksize
    integer, intent(in), optional            :: cache_size
    integer, intent(in), optional            :: cache_nelems
    integer, intent(in), optional            :: cache_preemption
    integer, intent(in), optional            :: comm
    integer, intent(in), optional            :: info
    class(state_type), intent(out), optional :: err

path: Name of the file to create.
cmode: Creation mode: NC_CLOBBER or NC_NOCLOBBER, combined with ior with format and other flags (see above).
ncid: Returned NetCDF ID of the dataset, used by every later call on it.
initialsize: Classic formats: initial size of the file in bytes.
chunksize: Classic formats: I/O buffer size hint in bytes; on return, the size actually used.
cache_size: NetCDF-4: size of the file's chunk cache, in bytes.
cache_nelems: NetCDF-4: number of slots of the chunk cache.
cache_preemption: NetCDF-4: preemption of the chunk cache, 0-100 (an integer here, a real in nc_open, as in netcdf-fortran).
comm: MPI communicator, for parallel I/O (needs a parallel build; see also nc_create_par).
info: MPI info object, for parallel I/O.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

On success err (if present) is cleared, and an nc_state_type gets nc_status = NC_NOERR. On failure err holds the NetCDF message and, for an nc_state_type, the status code; without err the program reports and stops. Possible causes of errors include:

The file exists and NC_NOCLOBBER was given (NC_EEXIST).
The directory does not exist or is not writable (NC_EPERM or a system error).
Incompatible flags, e.g. NC_CLASSIC_MODEL without NC_NETCDF4 (NC_EINVAL).
A feature the library was built without, e.g. parallel I/O (NC_ENOTBUILT, NC_ENOPAR).

Example

Create a NetCDF-4 dataset create.nc, failing if it already exists:

use stdlib_NetCDF
implicit none
integer :: ncid
type(nc_state_type) :: err

call nc_delete("create.nc", err)          ! start clean; the error if it is missing is ignored
! NC_NETCDF4: NetCDF-4 (HDF5-based) format; NC_NOCLOBBER: fail if the file already exists
call nc_create("create.nc", ior(NC_NETCDF4, NC_NOCLOBBER), ncid, err=err)
if (err%error()) error stop trim(err%message)
call nc_close(ncid)

2.5 Open a Dataset: nc_open

nc_open opens an existing dataset and returns its NetCDF ID. The dataset is in data mode. mode is NC_NOWRITE (read-only, the default) or NC_WRITE, optionally with NC_SHARE; the format is detected from the file.

Usage

subroutine nc_open(path, mode, ncid, chunksize, cache_size, cache_nelems, &
        cache_preemption, comm, info, err)
    character(len=*), intent(in)             :: path
    integer, intent(in)                      :: mode
    integer, intent(out)                     :: ncid
    integer, intent(inout), optional         :: chunksize
    integer, intent(in), optional            :: cache_size
    integer, intent(in), optional            :: cache_nelems
    real, intent(in), optional               :: cache_preemption
    integer, intent(in), optional            :: comm
    integer, intent(in), optional            :: info
    class(state_type), intent(out), optional :: err

path: Name of the file to open.
mode: NC_NOWRITE or NC_WRITE, optionally combined with NC_SHARE (or NC_DISKLESS, to read the whole file into memory).
ncid: Returned NetCDF ID of the dataset, used by every later call on it.
chunksize: Classic formats: I/O buffer size hint in bytes; on return, the size actually used.
cache_size: NetCDF-4: size of the file's chunk cache, in bytes.
cache_nelems: NetCDF-4: number of slots of the chunk cache.
cache_preemption: NetCDF-4: preemption of the chunk cache, 0-100 (a real here).
comm: MPI communicator, for parallel I/O (needs a parallel build).
info: MPI info object, for parallel I/O.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The file does not exist (ENOENT, system error 2: No such file or directory).
The file is not a netCDF file (NC_ENOTNC).
NC_WRITE on a file without write permission (NC_EPERM).

Example

Open foo.nc read-only:

use stdlib_NetCDF
implicit none
integer :: ncid

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_close(ncid)

2.6 Enter Define Mode: nc_redef

nc_redef puts an open dataset into define mode, so that dimensions, variables and attributes can be added, renamed or deleted. The dataset must have been opened with NC_WRITE.

Usage

subroutine nc_redef(ncid, err)
    integer, intent(in)                      :: ncid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is already in define mode (NC_EINDEFINE).
The dataset was opened read-only (NC_EPERM).
ncid does not refer to an open dataset (NC_EBADID).

Example

Open foo.nc and add a global attribute in define mode:

use stdlib_NetCDF
implicit none
integer :: ncid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
! NC_GLOBAL: a global attribute, of the dataset rather than of a variable
call nc_put_att(ncid, NC_GLOBAL, "source", "level-0 guide")
call nc_enddef(ncid)
call nc_close(ncid)

2.7 Leave Define Mode: nc_enddef

nc_enddef takes an open dataset out of define mode: the definitions are checked and committed, and variable values can be read and written. On a classic-format dataset, leaving define mode after the definitions changed may move data, and new fixed-size variables are filled with their fill values (unless the fill mode is NC_NOFILL).

Usage

subroutine nc_enddef(ncid, err)
    integer, intent(in)                      :: ncid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is not in define mode (NC_ENOTINDEFINE).
The definitions exceed a format limit, e.g. variables larger than the classic format allows (NC_EVARSIZE).
ncid does not refer to an open dataset (NC_EBADID).

Example

Define a dimension in a new dataset, then leave define mode:

use stdlib_NetCDF
implicit none
integer :: ncid, dimid

! NC_CLOBBER: create, overwriting the file if it exists
call nc_create("enddef.nc", NC_CLOBBER, ncid)
call nc_def_dim(ncid, "x", 3, dimid)
call nc_enddef(ncid)
call nc_close(ncid)

2.8 Close a Dataset: nc_close

nc_close closes an open dataset. A dataset in define mode is taken out of it first (as by nc_enddef), and buffered data is written to disk. The NetCDF ID is invalid afterwards. Datasets left open when a program ends may be incomplete: close every dataset you write.

Usage

subroutine nc_close(ncid, err)
    integer, intent(in)                      :: ncid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid does not refer to an open dataset (NC_EBADID).
Leaving define mode failed (see nc_enddef).

Example

Close foo.nc after reading it:

use stdlib_NetCDF
implicit none
integer :: ncid

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_close(ncid)

2.9 Inquire about a Dataset: nc_inquire, nc_inq_format, nc_inq_path

nc_inquire returns, for an open dataset or group, the numbers of dimensions, variables and global attributes, the ID of the (first) unlimited dimension, and the format; every output is optional. nc_inq_format returns the format alone, nc_inq_path the path the dataset was opened or created with. For every unlimited dimension of a NetCDF-4 dataset, use nc_inq_unlimdims.

Usage

subroutine nc_inquire(ncid, ndimensions, nvariables, nattributes, unlimiteddimid, &
        formatnum, err)
    integer, intent(in)                      :: ncid
    integer, intent(out), optional           :: ndimensions
    integer, intent(out), optional           :: nvariables
    integer, intent(out), optional           :: nattributes
    integer, intent(out), optional           :: unlimiteddimid
    integer, intent(out), optional           :: formatnum
    class(state_type), intent(out), optional :: err

subroutine nc_inq_format(ncid, formatnum, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: formatnum
    class(state_type), intent(out), optional :: err

subroutine nc_inq_path(ncid, pathlen, path, err)
    integer, intent(in)                      :: ncid
    integer, intent(inout)                   :: pathlen
    character(len=*), intent(inout)          :: path
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
ndimensions: Returned number of dimensions.
nvariables: Returned number of variables.
nattributes: Returned number of global attributes.
unlimiteddimid: Returned ID of the unlimited dimension; -1 if there is none.
formatnum: Returned format: NC_FORMAT_CLASSIC, NC_FORMAT_64BIT_OFFSET, NC_FORMAT_CDF5, NC_FORMAT_NETCDF4 or NC_FORMAT_NETCDF4_CLASSIC.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.
pathlen: On input, ignored; on return, the length of the path.
path: Returned path; must be long enough for it.

Errors

ncid does not refer to an open dataset (NC_EBADID).

Example

Print what foo.nc contains:

use stdlib_NetCDF
implicit none
integer :: ncid, ndims, nvars, ngatts, unlimdimid, formatnum, pathlen
character(len=256) :: path

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inquire(ncid, ndims, nvars, ngatts, unlimdimid, formatnum)
call nc_inq_path(ncid, pathlen, path)
print "(a, ': ', i0, ' dimensions, ', i0, ' variables, ', i0, ' global attributes')", &
    path(1:pathlen), ndims, nvars, ngatts
! NC_FORMAT_NETCDF4: the format code of NetCDF-4 files
if (formatnum == NC_FORMAT_NETCDF4) print "(a)", "NetCDF-4 format"
call nc_close(ncid)

2.10 Synchronize a Dataset to Disk: nc_sync

nc_sync writes buffered data and definitions of an open dataset to disk, so that other readers see them, without closing it. A dataset in define mode must leave it first.

Usage

subroutine nc_sync(ncid, err)
    integer, intent(in)                      :: ncid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is in define mode (NC_EINDEFINE).
ncid does not refer to an open dataset (NC_EBADID).

Example

Write a record of rh and make it visible to readers at once:

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, varid
real(dp) :: field(10, 5)

field = 1.0_dp
call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_inq_varid(ncid, "rh", varid)
call nc_put_var(ncid, varid, field, start=[1, 1, 3], count=[10, 5, 1])
call nc_sync(ncid)
call nc_close(ncid)

2.11 Back Out of Recent Definitions: nc_abort

nc_abort closes an open dataset, discarding the changes made in define mode since the last nc_enddef (or the creation: an aborted new dataset is deleted). It is meant for error recovery. Called in data mode, it simply closes the dataset.

Usage

subroutine nc_abort(ncid, err)
    integer, intent(in)                      :: ncid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid does not refer to an open dataset (NC_EBADID).

Example

Abandon a dataset whose definitions went wrong:

use stdlib_NetCDF
implicit none
integer :: ncid, dimid
type(nc_state_type) :: err

! NC_CLOBBER: create, overwriting the file if it exists
call nc_create("abort.nc", NC_CLOBBER, ncid)
call nc_def_dim(ncid, "x", 3, dimid)
call nc_def_dim(ncid, "x", 4, dimid, err)       ! fails: the name is in use
! NC_ENAMEINUSE: the status when the name is already in use
if (err%nc_status == NC_ENAMEINUSE) call nc_abort(ncid)   ! abort.nc is not kept

2.12 Set the Fill Mode for Writes: nc_set_fill

nc_set_fill sets the fill mode of an open, writable dataset: with NC_FILL (the default) the library writes the fill value into every value of a variable before its data, so unwritten values read as the fill value; with NC_NOFILL it does not, which is faster when every value is written anyway. The mode applies until it is changed or the dataset is closed; the previous mode is returned.

Usage

subroutine nc_set_fill(ncid, fillmode, old_mode, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: fillmode
    integer, intent(out), optional           :: old_mode
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
fillmode: NC_FILL or NC_NOFILL.
old_mode: Returned fill mode in effect before the call.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset was opened read-only (NC_EPERM).
fillmode is neither NC_FILL nor NC_NOFILL (NC_EINVAL).
ncid does not refer to an open dataset (NC_EBADID).

Example

Write foo.nc without pre-filling, then restore the previous mode:

use stdlib_NetCDF
implicit none
integer :: ncid, old_mode

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_set_fill(ncid, NC_NOFILL, old_mode)       ! NC_NOFILL: do not pre-fill new variables
! ... write every value of the new data ...
call nc_set_fill(ncid, old_mode)
call nc_close(ncid)

2.13 Delete a Dataset: nc_delete

nc_delete deletes a netCDF file, given its path. The file must not be open.

Usage

subroutine nc_delete(path, err)
    character(len=*), intent(in)             :: path
    class(state_type), intent(out), optional :: err

path: Name of the file to delete.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The file does not exist or cannot be removed (system error).

Example

Remove a scratch dataset:

use stdlib_NetCDF
implicit none
integer :: ncid

! NC_CLOBBER: create, overwriting the file if it exists
call nc_create("scratch.nc", NC_CLOBBER, ncid)
call nc_close(ncid)
call nc_delete("scratch.nc")

3 Groups

NetCDF-4 datasets can organise dimensions, variables, attributes and types in a tree of groups, like directories in a file system. The dataset itself is the root group, /; each group has a name, unique among its siblings, and a full name such as /forecast/ocean.

A group is identified by a group ID, which can be used wherever an nc_* routine takes ncid: a variable of group /forecast/ocean is defined, written and read through that group's ID. Dimensions are visible in the group that defines them and in all its descendants. Groups need a NetCDF-4 dataset created without NC_CLASSIC_MODEL.

The routines of this chapter are in module stdlib_netcdf_grp, except nc_inq_varids (stdlib_netcdf_var) and nc_inq_dimids (stdlib_netcdf_dim). The examples add groups to foo.nc, which is a NetCDF-4 dataset.

3.1 Find a Group ID: nc_inq_ncid

nc_inq_ncid returns the ID of the group name, a direct child of the group (or dataset) ncid.

Usage

subroutine nc_inq_ncid(ncid, name, grp_ncid, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: grp_ncid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Name of the child group.
grp_ncid: Returned ID of the child group.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

There is no child group of that name (NC_ENOGRP).
ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).
The dataset is not NetCDF-4 (NC_ENOTNC4).

Example

Find the group forecast in the root group:

use stdlib_NetCDF
implicit none
integer :: ncid, gid, found

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", gid)
call nc_inq_ncid(ncid, "forecast", found)       ! found == gid
call nc_close(ncid)

3.2 Get a List of Groups in a Group: nc_inq_grps

nc_inq_grps returns the number and the IDs of the direct child groups of a group.

Usage

subroutine nc_inq_grps(ncid, numgrps, ncids, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: numgrps
    integer, intent(out)                     :: ncids(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
numgrps: Returned number of child groups.
ncids: Returned IDs of the child groups; must be at least numgrps long.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).
The dataset is not NetCDF-4 (NC_ENOTNC4).

Example

List the groups of the root group:

use stdlib_NetCDF
implicit none
integer :: ncid, g1, g2, numgrps
integer :: ncids(10)

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", g1)
call nc_def_grp(ncid, "analysis", g2)
call nc_inq_grps(ncid, numgrps, ncids)          ! numgrps == 2
call nc_close(ncid)

3.3 Find all the Variables in a Group: nc_inq_varids

nc_inq_varids returns the number and the IDs of the variables of a group (or dataset). In a group, IDs are not necessarily 1, 2, 3, ...: use the list.

Usage

subroutine nc_inq_varids(ncid, nvars, varids, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: nvars
    integer, intent(out)                     :: varids(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
nvars: Returned number of variables.
varids: Returned variable IDs; must be at least nvars long (nc_inquire gives the number).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

Get the variable IDs of foo.nc:

use stdlib_NetCDF
implicit none
integer :: ncid, nvars
integer :: varids(10)

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varids(ncid, nvars, varids)         ! nvars == 5
call nc_close(ncid)

3.4 Find all Dimensions Visible in a Group: nc_inq_dimids

nc_inq_dimids returns the number and the IDs of the dimensions of a group (or dataset), and, on request, those of its ancestors, which are visible in it too.

Usage

subroutine nc_inq_dimids(ncid, ndims, dimids, include_parents, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: ndims
    integer, intent(out)                     :: dimids(:)
    integer, intent(in), optional            :: include_parents
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
ndims: Returned number of dimensions.
dimids: Returned dimension IDs; must be at least ndims long.
include_parents: 1 to include the dimensions of the parent groups; 0 (default) for this group's only.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

Dimensions visible in a new subgroup of foo.nc:

use stdlib_NetCDF
implicit none
integer :: ncid, gid, ndims
integer :: dimids(10)

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", gid)
call nc_inq_dimids(gid, ndims, dimids)                      ! ndims == 0
call nc_inq_dimids(gid, ndims, dimids, include_parents=1)   ! ndims == 3: lon, lat, time
call nc_close(ncid)

3.5 Find the Length of a Group's Full Name: nc_inq_grpname_len

nc_inq_grpname_len returns the length of the full name of a group (e.g. 15 for /forecast/ocean), to size the buffer of nc_inq_grpname_full.

Usage

subroutine nc_inq_grpname_len(ncid, len, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: len
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
len: Returned length of the full name.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, gid, n

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", gid)
call nc_inq_grpname_len(gid, n)                 ! n == 9, len("/forecast")
call nc_close(ncid)

3.6 Find a Group's Name: nc_inq_grpname

nc_inq_grpname returns the name of a group, without its ancestors (/ for the root group).

Usage

subroutine nc_inq_grpname(ncid, name, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(out)            :: name
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Returned name; NC_MAX_NAME characters always suffice.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, gid
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", gid)
call nc_inq_grpname(gid, name)                  ! "forecast"
call nc_close(ncid)

3.7 Find a Group's Full Name: nc_inq_grpname_full

nc_inq_grpname_full returns the full name of a group, from the root (/forecast/ocean), and its length.

Usage

subroutine nc_inq_grpname_full(ncid, len, name, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: len
    character(len=*), intent(out)            :: name
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
len: Returned length of the full name.
name: Returned full name; must be long enough (see nc_inq_grpname_len).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, g1, g2, n
character(len=256) :: full

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", g1)
call nc_def_grp(g1, "ocean", g2)
call nc_inq_grpname_full(g2, n, full)
print "(a)", full(1:n)                          ! /forecast/ocean
call nc_close(ncid)

3.8 Find a Group's Parent: nc_inq_grp_parent

nc_inq_grp_parent returns the ID of the parent of a group.

Usage

subroutine nc_inq_grp_parent(ncid, parent_ncid, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: parent_ncid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
parent_ncid: Returned ID of the parent group.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The group is the root group, which has no parent (NC_ENOGRP).
ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, gid, parent

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", gid)
call nc_inq_grp_parent(gid, parent)             ! parent == ncid
call nc_close(ncid)

3.9 Find a Group by Name: nc_inq_grp_ncid

nc_inq_grp_ncid returns the ID of the group name, a direct child of ncid; it behaves as nc_inq_ncid.

Usage

subroutine nc_inq_grp_ncid(ncid, name, grpid, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: grpid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Name of the child group.
grpid: Returned ID of the child group.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

There is no child group of that name (NC_ENOGRP).
ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, gid, found

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "analysis", gid)
call nc_inq_grp_ncid(ncid, "analysis", found)
call nc_close(ncid)

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

nc_inq_grp_full_ncid returns the ID of a group given its full name, from the root of the dataset ncid belongs to.

Usage

subroutine nc_inq_grp_full_ncid(ncid, full_name, grpid, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: full_name
    integer, intent(out)                     :: grpid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
full_name: Full name of the group, e.g. /forecast/ocean.
grpid: Returned ID of the group.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No group has that full name (NC_ENOGRP).
ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, g1, g2, found

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", g1)
call nc_def_grp(g1, "ocean", g2)
call nc_inq_grp_full_ncid(ncid, "/forecast/ocean", found)   ! found == g2
call nc_close(ncid)

3.11 Create a New Group: nc_def_grp

nc_def_grp creates a group, child of parent_ncid, and returns its ID. The dataset must be NetCDF-4 (not classic model); it is put into define mode if needed.

Usage

subroutine nc_def_grp(parent_ncid, name, new_ncid, err)
    integer, intent(in)                      :: parent_ncid
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: new_ncid
    class(state_type), intent(out), optional :: err

parent_ncid: ID of the parent group (the NetCDF ID for the root group).
name: Name of the new group.
new_ncid: Returned ID of the new group.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The name is already used by a group, variable or type of the parent (NC_ENAMEINUSE).
The name is not valid (NC_EBADNAME).
The dataset was opened read-only (NC_EPERM).
ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).
The dataset is not NetCDF-4 (NC_ENOTNC4).

Example

Create /forecast/ocean and a variable in it:

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, forecast, ocean, x_dimid, varid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", forecast)
call nc_def_grp(forecast, "ocean", ocean)
call nc_def_dim(ocean, "x", 3, x_dimid)
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_def_var(ocean, "sst", NC_DOUBLE, varid, dimids=[x_dimid])
call nc_put_var(ocean, varid, [10.0_dp, 11.0_dp, 12.0_dp])
call nc_close(ncid)

3.12 Rename a Group: nc_rename_grp

nc_rename_grp renames a group. The root group cannot be renamed.

Usage

subroutine nc_rename_grp(grpid, name, err)
    integer, intent(in)                      :: grpid
    character(len=*), intent(in)             :: name
    class(state_type), intent(out), optional :: err

grpid: ID of the group to rename.
name: New name.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The new name is already used in the parent group (NC_ENAMEINUSE).
The group is the root group (NC_EINVAL).
The dataset was opened read-only (NC_EPERM).
ncid is not a valid dataset or group ID (NC_EBADID, NC_EBADGRPID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, gid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_grp(ncid, "forecast", gid)
call nc_rename_grp(gid, "prediction")
call nc_close(ncid)

4 Dimensions

Dimensions are defined in define mode, before the variables that use them. A dimension has a name and a length; the length of an unlimited dimension (NC_UNLIMITED) grows as data is written along it, and is the number of records written so far. A classic-format dataset has at most one unlimited dimension, a NetCDF-4 dataset any number.

A dimension is referred to by its dimension ID: 1, 2, 3, ... in definition order. The name of a dimension can be changed later; its length cannot (other than by writing more records along an unlimited one).

In Fortran order, the first dimension of a variable varies fastest; the unlimited dimension, if any, must be the last (the slowest) in a classic dataset.

The routines of this chapter are in module stdlib_netcdf_dim. Listing the dimensions of a group is nc_inq_dimids, in Groups.

4.1 Create a Dimension: nc_def_dim

nc_def_dim adds a dimension to a dataset in define mode and returns its ID.

Usage

subroutine nc_def_dim(ncid, name, len, dimid, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: len
    integer, intent(out)                     :: dimid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Dimension name.
len: Length: a positive integer, or NC_UNLIMITED for an unlimited (record) dimension.
dimid: Returned dimension ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is not in define mode (NC_ENOTINDEFINE).
The name is already used by another dimension (NC_ENAMEINUSE), or is not valid (NC_EBADNAME).
The length is negative (NC_EDIMSIZE).
A second unlimited dimension in a classic-format dataset (NC_EUNLIMIT).
ncid does not refer to an open dataset (NC_EBADID).

Example

Create a dimension lat of length 18 and an unlimited dimension rec in a new dataset:

use stdlib_NetCDF
implicit none
integer :: ncid, lat_dimid, rec_dimid

! NC_CLOBBER: create, overwriting the file if it exists
call nc_create("dims.nc", NC_CLOBBER, ncid)
call nc_def_dim(ncid, "lat", 18, lat_dimid)
! NC_UNLIMITED: an unlimited (record) dimension: it grows as data is written
call nc_def_dim(ncid, "rec", NC_UNLIMITED, rec_dimid)
call nc_close(ncid)

4.2 Get a Dimension ID from Its Name: nc_inq_dimid

nc_inq_dimid returns the ID of a dimension, given its name. In a group, the dimensions of the ancestors are found too.

Usage

subroutine nc_inq_dimid(ncid, name, dimid, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: dimid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Dimension name.
dimid: Returned dimension ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No dimension of that name (NC_EBADDIM).
ncid does not refer to an open dataset (NC_EBADID).

Example

Get the ID of lat in foo.nc:

use stdlib_NetCDF
implicit none
integer :: ncid, lat_dimid

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_dimid(ncid, "lat", lat_dimid)
call nc_close(ncid)

4.3 Inquire about a Dimension: nc_inquire_dimension

nc_inquire_dimension returns the name and/or the length of a dimension, given its ID. The length of an unlimited dimension is the number of records written so far.

Usage

subroutine nc_inquire_dimension(ncid, dimid, name, len, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: dimid
    character(len=*), intent(out), optional  :: name
    integer, intent(out), optional           :: len
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
dimid: Dimension ID, from nc_def_dim or nc_inq_dimid (1, 2, 3, ... in definition order).
name: Returned dimension name; NC_MAX_NAME characters always suffice.
len: Returned length.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

dimid is not a valid dimension ID (NC_EBADDIM).
ncid does not refer to an open dataset (NC_EBADID).

Example

Name and length of the unlimited dimension of foo.nc:

use stdlib_NetCDF
implicit none
integer :: ncid, unlimdimid, nrecs
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inquire(ncid, unlimiteddimid=unlimdimid)
call nc_inquire_dimension(ncid, unlimdimid, name=name, len=nrecs)   ! "time", 2
call nc_close(ncid)

4.4 Rename a Dimension: nc_rename_dim

nc_rename_dim renames a dimension. On a classic-format dataset, a longer name needs define mode.

Usage

subroutine nc_rename_dim(ncid, dimid, newname, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: dimid
    character(len=*), intent(in)             :: newname
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
dimid: Dimension ID, from nc_def_dim or nc_inq_dimid (1, 2, 3, ... in definition order).
newname: New name.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The new name is already used by another dimension (NC_ENAMEINUSE).
A longer name on a classic dataset in data mode (NC_ENOTINDEFINE).
dimid is not a valid dimension ID (NC_EBADDIM).
The dataset was opened read-only (NC_EPERM).

Example

Rename lat to latitude:

use stdlib_NetCDF
implicit none
integer :: ncid, lat_dimid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lat", lat_dimid)
call nc_rename_dim(ncid, lat_dimid, "latitude")
call nc_enddef(ncid)
call nc_close(ncid)

4.5 Find all Unlimited Dimensions: nc_inq_unlimdims

nc_inq_unlimdims returns the number and the IDs of the unlimited dimensions of a dataset or group: in a group, those defined in that group, not in its ancestors. nc_inquire returns the first one only. Call it without unlimdimids to get the number, then with an array of that size.

netcdf-fortran has no nf90_inq_unlimdims: this routine calls netcdf-c's nc_inq_unlimdims directly and returns Fortran (1-based) dimension IDs.

Usage

subroutine nc_inq_unlimdims(ncid, nunlimdims, unlimdimids, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: nunlimdims
    integer, intent(out), optional           :: unlimdimids(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
nunlimdims: Returned number of unlimited dimensions.
unlimdimids: Returned IDs; must be at least nunlimdims long.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

unlimdimids shorter than nunlimdims (NC_EINVAL).
ncid does not refer to an open dataset (NC_EBADID).

Example

List the unlimited dimensions of a NetCDF-4 dataset with two of them:

use stdlib_NetCDF
implicit none
integer :: ncid, t1, t2, n
integer, allocatable :: ids(:)

call nc_create("unlim.nc", NC_NETCDF4, ncid)      ! NC_NETCDF4: NetCDF-4 (HDF5-based) format
! NC_UNLIMITED: an unlimited (record) dimension: it grows as data is written
call nc_def_dim(ncid, "t1", NC_UNLIMITED, t1)
call nc_def_dim(ncid, "t2", NC_UNLIMITED, t2)
call nc_inq_unlimdims(ncid, n)                  ! n == 2
allocate(ids(n))
call nc_inq_unlimdims(ncid, n, ids)             ! ids == [t1, t2]
call nc_close(ncid)

5 User Defined Data Types

NetCDF-4 datasets can define their own data types, in four classes:

compound: a record of named fields, each of a built-in or user-defined type, possibly an array (like a C struct or a Fortran derived type);
variable length (vlen): a ragged array, each element a sequence of any length of a base type;
opaque: a blob of a fixed number of bytes, which the library does not interpret;
enum: an integer base type whose values have names.

A user-defined type belongs to a group and is identified by a type ID, which can be used wherever a built-in type is (xtype of nc_def_var, of attributes, as a compound field type, ...). Types must be defined (and compound types completed) before use; once a variable or attribute uses a type, the type cannot be changed.

Data of user-defined types is moved as raw bytes by nc_put_var_any / nc_get_var_any and nc_put_att_any / nc_get_att_any: a character(len=*) buffer holding the values in the layout netCDF expects (for a compound, the field offsets given when it was defined, with the C alignment of each field). Build and decode such buffers with transfer.

Compound field IDs and enum member indices are 1-based, as in netcdf-fortran. nc_inq_type calls netcdf-c directly: netcdf-fortran 4.6.2's nf90_inq_type overflows its buffer and does not return the name. Writing vlen data needs the C layout of a vlen element (a length and a C pointer), which these wrappers do not provide; vlen types can be defined and inquired. The routines of this chapter are in module stdlib_netcdf_type.

5.1 Learn the IDs of All Types in a Group: nc_inq_typeids

nc_inq_typeids returns the number and IDs of the user-defined types of a group (not of its ancestors or descendants).

Usage

subroutine nc_inq_typeids(ncid, ntypes, typeids, err)
    integer, intent(in)                      :: ncid
    integer, intent(out), optional           :: ntypes
    integer, intent(out), optional           :: typeids(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
ntypes: Returned number of types.
typeids: Returned type IDs; must be at least ntypes long.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, tid, ntypes
integer :: typeids(10)

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_opaque(ncid, 16, "uuid", tid)
call nc_inq_typeids(ncid, ntypes, typeids)      ! ntypes == 1, typeids(1) == tid
call nc_close(ncid)

5.2 Learn About a Type: nc_inq_type

nc_inq_type returns the name and the size in bytes of any type, built-in (NC_DOUBLE: double, 8) or user-defined (for a vlen, the size of its C element).

This routine calls netcdf-c's nc_inq_type directly; see the chapter introduction.

Usage

subroutine nc_inq_type(ncid, xtype, name, size, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: size
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: Type ID: a built-in type (NC_INT, ...) or a user-defined one.
name: Returned type name.
size: Returned size in bytes.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, size
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_inq_type(ncid, NC_DOUBLE, name, size)   ! "double", 8
call nc_close(ncid)

5.3 Learn About a User Defined Type: nc_inq_user_type

nc_inq_user_type returns everything about a user-defined type: name, size, base type (vlen and enum), number of fields (compound) or members (enum), and its class.

Usage

subroutine nc_inq_user_type(ncid, xtype, name, size, base_typeid, nfields, class, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: size
    integer, intent(out)                     :: base_typeid
    integer, intent(out)                     :: nfields
    integer, intent(out)                     :: class
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: Type ID, from the routine that defined the type or from nc_inq_typeids.
name: Returned type name.
size: Returned size in bytes.
base_typeid: Returned base type, for vlen and enum types (0 otherwise).
nfields: Returned number of fields (compound) or members (enum).
class: Returned class: NC_COMPOUND, NC_VLEN, NC_OPAQUE or NC_ENUM.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, tid, size, base, nfields, class
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_enum(ncid, NC_INT, "color", tid)      ! NC_INT: the netCDF type of 32-bit integers
call nc_insert_enum(ncid, tid, "red", 0)
call nc_inq_user_type(ncid, tid, name, size, base, nfields, class)   ! class == NC_ENUM
call nc_close(ncid)

5.4 Create a Compound Type: nc_def_compound

nc_def_compound creates an empty compound type of a given total size in bytes; its fields are then added with nc_insert_compound and nc_insert_array_compound. The size includes any padding needed for alignment: {int32 a; double b} is 16 bytes, b at offset 8.

Usage

subroutine nc_def_compound(ncid, size, name, typeid, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: size
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: typeid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
size: Size of one record in bytes.
name: Type name.
typeid: Returned type ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The name is already used by a type, group or variable of the group (NC_ENAMEINUSE), or is not valid (NC_EBADNAME).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The dataset was opened read-only (NC_EPERM).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, rec_t

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_compound(ncid, 16, "record", rec_t)
call nc_insert_compound(ncid, rec_t, "a", 0, NC_INT)  ! NC_INT: the netCDF type of 32-bit integers
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_insert_compound(ncid, rec_t, "b", 8, NC_DOUBLE)
call nc_close(ncid)

5.5 Insert a Field into a Compound Type: nc_insert_compound

nc_insert_compound adds a scalar field to a compound type, at a byte offset from the start of the record.

Usage

subroutine nc_insert_compound(ncid, xtype, name, offset, field_typeid, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: offset
    integer, intent(in)                      :: field_typeid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the compound type.
name: Field name.
offset: Byte offset of the field in the record.
field_typeid: Type of the field: built-in or user-defined.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The field does not fit in the record, or overlaps another (NC_EBADFIELD).
A field of that name exists (NC_ENAMEINUSE).
xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

See the example of nc_def_compound.

5.6 Insert an Array Field into a Compound Type: nc_insert_array_compound

nc_insert_array_compound adds an array field to a compound type.

Usage

subroutine nc_insert_array_compound(ncid, xtype, name, offset, field_typeid, ndims, &
        dim_sizes, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: offset
    integer, intent(in)                      :: field_typeid
    integer, intent(in)                      :: ndims
    integer, intent(in)                      :: dim_sizes(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the compound type.
name: Field name.
offset: Byte offset of the field in the record.
field_typeid: Type of the array elements.
ndims: Number of dimensions of the array field.
dim_sizes: Their sizes.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The field does not fit in the record (NC_EBADFIELD).
A field of that name exists (NC_ENAMEINUSE).
xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, pair_t

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_compound(ncid, 8, "pair", pair_t)
! NC_INT: the netCDF type of 32-bit integers
call nc_insert_array_compound(ncid, pair_t, "v", 0, NC_INT, 1, [2])   ! int v[2]
call nc_close(ncid)

5.7 Learn About a Compound Type: nc_inq_compound Family

nc_inq_compound returns the name, size and number of fields of a compound type; the three others return one of them each.

Usage

subroutine nc_inq_compound(ncid, xtype, name, size, nfields, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: size
    integer, intent(out)                     :: nfields
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_name(ncid, xtype, name, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(out)            :: name
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_size(ncid, xtype, size, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(out)                     :: size
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_nfields(ncid, xtype, nfields, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(out)                     :: nfields
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the compound type.
name: Returned type name.
size: Returned size of a record in bytes.
nfields: Returned number of fields.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

xtype is not a compound type (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, rec_t, size, nfields
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_compound(ncid, 16, "record", rec_t)
call nc_insert_compound(ncid, rec_t, "a", 0, NC_INT)  ! NC_INT: the netCDF type of 32-bit integers
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_insert_compound(ncid, rec_t, "b", 8, NC_DOUBLE)
call nc_inq_compound(ncid, rec_t, name, size, nfields)   ! "record", 16, 2
call nc_close(ncid)

5.8 Learn About a Field of a Compound Type: nc_inq_compound_field Family

nc_inq_compound_field returns everything about one field of a compound type; the others return one property each. nc_inq_compound_fieldindex is the inverse lookup: the field ID from its name. Field IDs are 1, 2, 3, ... in insertion order.

Usage

subroutine nc_inq_compound_field(ncid, xtype, fieldid, name, offset, field_typeid, ndims, &
        dim_sizes, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: fieldid
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: offset
    integer, intent(out)                     :: field_typeid
    integer, intent(out)                     :: ndims
    integer, intent(out)                     :: dim_sizes(:)
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_fieldname(ncid, xtype, fieldid, name, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: fieldid
    character(len=*), intent(out)            :: name
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_fieldindex(ncid, xtype, name, fieldid, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: fieldid
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_fieldoffset(ncid, xtype, fieldid, offset, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: fieldid
    integer, intent(out)                     :: offset
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_fieldtype(ncid, xtype, fieldid, field_typeid, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: fieldid
    integer, intent(out)                     :: field_typeid
    class(state_type), intent(out), optional :: err

subroutine nc_inq_compound_fieldndims(ncid, xtype, fieldid, ndims, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: fieldid
    integer, intent(out)                     :: ndims
    class(state_type), intent(out), optional :: err

subroutine nc_inq_cmp_fielddim_sizes(ncid, xtype, fieldid, dim_sizes, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: fieldid
    integer, intent(out)                     :: dim_sizes(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the compound type.
fieldid: Field ID (1-based); returned by nc_inq_compound_fieldindex.
name: Field name: returned, or given to nc_inq_compound_fieldindex.
offset: Returned byte offset of the field.
field_typeid: Returned type of the field.
ndims: Returned number of dimensions (0 for a scalar field).
dim_sizes: Returned sizes of the array dimensions; must be at least ndims long.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No field of that ID or name (NC_EBADFIELD).
xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, rec_t, fieldid, offset, ftype, ndims
integer :: dim_sizes(1)
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_compound(ncid, 16, "record", rec_t)
call nc_insert_compound(ncid, rec_t, "a", 0, NC_INT)  ! NC_INT: the netCDF type of 32-bit integers
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_insert_compound(ncid, rec_t, "b", 8, NC_DOUBLE)
call nc_inq_compound_fieldindex(ncid, rec_t, "b", fieldid)                     ! 2
call nc_inq_compound_field(ncid, rec_t, fieldid, name, offset, ftype, ndims, dim_sizes)
call nc_inq_compound_fieldoffset(ncid, rec_t, fieldid, offset)                 ! 8
call nc_close(ncid)

5.9 Define a Variable Length Array (VLEN) Type: nc_def_vlen

nc_def_vlen creates a vlen type with a given base type: each value of a vlen variable is a sequence of any length of base-type values.

Usage

subroutine nc_def_vlen(ncid, name, base_typeid, xtypeid, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: base_typeid
    integer, intent(out)                     :: xtypeid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Type name.
base_typeid: Type of the elements of each sequence.
xtypeid: Returned type ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The name is already used by a type, group or variable of the group (NC_ENAMEINUSE), or is not valid (NC_EBADNAME).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The dataset was opened read-only (NC_EPERM).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, vlen_t

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_vlen(ncid, "ragged", NC_INT, vlen_t)  ! NC_INT: the netCDF type of 32-bit integers
call nc_close(ncid)

5.10 Learn About a VLEN Type: nc_inq_vlen

nc_inq_vlen returns the name, the size of one element (in the C layout) and the base type of a vlen type.

Usage

subroutine nc_inq_vlen(ncid, xtype, name, datum_size, base_nc_type, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: datum_size
    integer, intent(out)                     :: base_nc_type
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the vlen type.
name: Returned type name.
datum_size: Returned size of one vlen element in bytes.
base_nc_type: Returned base type.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

xtype is not a vlen type (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, vlen_t, datum_size, base
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_vlen(ncid, "ragged", NC_INT, vlen_t)  ! NC_INT: the netCDF type of 32-bit integers
call nc_inq_vlen(ncid, vlen_t, name, datum_size, base)   ! "ragged", ..., NC_INT
call nc_close(ncid)

5.11 Create an Opaque Type: nc_def_opaque

nc_def_opaque creates an opaque type: values of size bytes, stored and returned unchanged.

Usage

subroutine nc_def_opaque(ncid, size, name, xtype, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: size
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: xtype
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
size: Size of one value in bytes.
name: Type name.
xtype: Returned type ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The name is already used by a type, group or variable of the group (NC_ENAMEINUSE), or is not valid (NC_EBADNAME).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The dataset was opened read-only (NC_EPERM).

Example

An opaque global attribute (written with nc_put_att_any):

use stdlib_NetCDF
implicit none
integer :: ncid, blob_t

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_opaque(ncid, 4, "blob", blob_t)
! NC_GLOBAL: a global attribute, of the dataset rather than of a variable
call nc_put_att_any(ncid, NC_GLOBAL, "magic", blob_t, 1, "ABCD")
call nc_close(ncid)

5.12 Learn About an Opaque Type: nc_inq_opaque

nc_inq_opaque returns the name and size of an opaque type.

Usage

subroutine nc_inq_opaque(ncid, xtype, name, size, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: size
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the opaque type.
name: Returned type name.
size: Returned size of one value in bytes.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

xtype is not an opaque type (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, blob_t, size
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_opaque(ncid, 4, "blob", blob_t)
call nc_inq_opaque(ncid, blob_t, name, size)    ! "blob", 4
call nc_close(ncid)

5.13 Create an Enum Type: nc_def_enum

nc_def_enum creates an enum type over an integer base type; its members are then added with nc_insert_enum.

Usage

subroutine nc_def_enum(ncid, base_typeid, name, typeid, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: base_typeid
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: typeid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
base_typeid: Integer base type: NC_BYTE, NC_UBYTE, NC_SHORT, NC_USHORT, NC_INT, NC_UINT, NC_INT64 or NC_UINT64.
name: Type name.
typeid: Returned type ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The base type is not an integer type (NC_EBADTYPE).
The name is already used by a type, group or variable of the group (NC_ENAMEINUSE), or is not valid (NC_EBADNAME).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The dataset was opened read-only (NC_EPERM).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, color_t

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_enum(ncid, NC_INT, "color", color_t)  ! NC_INT: the netCDF type of 32-bit integers
call nc_insert_enum(ncid, color_t, "red", 0)
call nc_insert_enum(ncid, color_t, "green", 1)
call nc_insert_enum(ncid, color_t, "blue", 2)
call nc_close(ncid)

5.14 Insert a Member into an Enum Type: nc_insert_enum

nc_insert_enum adds a named value to an enum type.

Usage

subroutine nc_insert_enum(ncid, xtype, name, value, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: value
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the enum type.
name: Member name.
value: Its value.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

A member of that name or value exists (NC_ENAMEINUSE, NC_EINVAL).
xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

See the example of nc_def_enum.

5.15 Learn About an Enum Type: nc_inq_enum

nc_inq_enum returns the name, base type, base size and number of members of an enum type.

Usage

subroutine nc_inq_enum(ncid, xtype, name, base_nc_type, base_size, num_members, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: base_nc_type
    integer, intent(out)                     :: base_size
    integer, intent(out)                     :: num_members
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the enum type.
name: Returned type name.
base_nc_type: Returned base type.
base_size: Returned size of the base type in bytes.
num_members: Returned number of members.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

xtype is not an enum type (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, color_t, base, base_size, nmembers
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_enum(ncid, NC_INT, "color", color_t)  ! NC_INT: the netCDF type of 32-bit integers
call nc_insert_enum(ncid, color_t, "red", 0)
call nc_inq_enum(ncid, color_t, name, base, base_size, nmembers)   ! "color", NC_INT, 4, 1
call nc_close(ncid)

5.16 Learn About an Enum Member: nc_inq_enum_member

nc_inq_enum_member returns the name and value of a member of an enum type, given its index (1-based, in insertion order).

Usage

subroutine nc_inq_enum_member(ncid, xtype, idx, name, value, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: idx
    character(len=*), intent(out)            :: name
    integer, intent(out)                     :: value
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the enum type.
idx: Member index, 1-based.
name: Returned member name.
value: Returned member value.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No member of that index (NC_EINVAL).
xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, color_t, value
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_enum(ncid, NC_INT, "color", color_t)  ! NC_INT: the netCDF type of 32-bit integers
call nc_insert_enum(ncid, color_t, "red", 0)
call nc_insert_enum(ncid, color_t, "green", 1)
call nc_inq_enum_member(ncid, color_t, 2, name, value)   ! "green", 1
call nc_close(ncid)

5.17 Learn the Name of an Enum Value: nc_inq_enum_ident

nc_inq_enum_ident returns the name of the member of an enum type that has a given value.

Usage

subroutine nc_inq_enum_ident(ncid, xtype, value, identifier, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: xtype
    integer, intent(in)                      :: value
    character(len=*), intent(out)            :: identifier
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
xtype: ID of the enum type.
value: Member value.
identifier: Returned member name.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No member has that value (NC_EINVAL).
xtype is not a valid type ID (NC_EBADTYPE).
ncid does not refer to an open dataset or group (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, color_t
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: ident

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_enum(ncid, NC_INT, "color", color_t)  ! NC_INT: the netCDF type of 32-bit integers
call nc_insert_enum(ncid, color_t, "blue", 2)
call nc_inq_enum_ident(ncid, color_t, 2, ident)   ! "blue"
call nc_close(ncid)

5.18 Write and Read Data of Any Type: nc_put_var_any, nc_get_var_any

nc_put_var_any and nc_get_var_any write and read variable values of any type as raw bytes, held in a character(len=*) buffer: for a compound type, each record laid out as defined (offsets and padding included). start, count, stride and map select values as in nc_put_var, in units of values, not bytes.

Always pass count: without it, netcdf-fortran takes the length of the buffer in bytes as the number of values to transfer.

Usage

subroutine nc_put_var_any(ncid, varid, values, start, count, stride, map, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(in)             :: values
    integer, intent(in), optional            :: start(:)
    integer, intent(in), optional            :: count(:)
    integer, intent(in), optional            :: stride(:)
    integer, intent(in), optional            :: map(:)
    class(state_type), intent(out), optional :: err

subroutine nc_get_var_any(ncid, varid, values, start, count, stride, map, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(out)            :: values
    integer, intent(in), optional            :: start(:)
    integer, intent(in), optional            :: count(:)
    integer, intent(in), optional            :: stride(:)
    integer, intent(in), optional            :: map(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
values: Buffer of raw bytes: input for nc_put_var_any, output for nc_get_var_any; at least product(count) values long.
start: Index of the first value along each dimension, in Fortran order (default 1).
count: Number of values along each dimension. Required in practice (see above).
stride: Step along each dimension (default 1).
map: Distance in memory between successive values along each dimension, in values.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

start/count exceed the variable's dimensions (NC_EINVALCOORDS, NC_EEDGE).
The buffer is shorter than the data (undetected: memory is overrun; size it right).
varid is not a valid variable ID (NC_ENOTVAR).

Example

Two records of the compound {int32 a; double b} written and read back:

use stdlib_NetCDF
use stdlib_kinds, only: int32, dp
implicit none
integer :: ncid, rec_t, dimid, varid
character(len=32) :: buffer, back

! Record layout: int32 a at byte 0, 4 bytes of padding, real(dp) b at byte 8.
buffer = transfer(7_int32, repeat(" ", 4)) // repeat(achar(0), 4) // transfer(2.5_dp, repeat(" ", 8)) &
      // transfer(-3_int32, repeat(" ", 4)) // repeat(achar(0), 4) // transfer(1.0e10_dp, repeat(" ", 8))

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_compound(ncid, 16, "record", rec_t)
call nc_insert_compound(ncid, rec_t, "a", 0, NC_INT)  ! NC_INT: the netCDF type of 32-bit integers
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_insert_compound(ncid, rec_t, "b", 8, NC_DOUBLE)
call nc_def_dim(ncid, "n", 2, dimid)
call nc_def_var(ncid, "records", rec_t, varid, dimids=[dimid])
call nc_put_var_any(ncid, varid, buffer, start=[1], count=[2])
call nc_get_var_any(ncid, varid, back, start=[1], count=[2])
print "(i0, 1x, f0.1)", transfer(back(17:20), 0_int32), transfer(back(25:32), 0.0_dp)   ! -3 10000000000.0
call nc_close(ncid)

5.19 Write and Read Attributes of Any Type: nc_put_att_any, nc_get_att_any

nc_put_att_any and nc_get_att_any write and read attribute values of any type (typically user-defined) as raw bytes. Writing needs the type; reading takes it from the attribute.

Usage

subroutine nc_put_att_any(ncid, varid, name, typeid, length, values, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: typeid
    integer, intent(in)                      :: length
    character(len=*), intent(in)             :: values
    class(state_type), intent(out), optional :: err

subroutine nc_get_att_any(ncid, varid, name, length, values, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: length
    character(len=*), intent(inout)          :: values
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
name: Attribute name.
typeid: Type of the attribute values.
length: Number of values.
values: Buffer of raw bytes, at least length values long: input for nc_put_att_any, output for nc_get_att_any.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No attribute of that name, for nc_get_att_any (NC_ENOTATT).
typeid is not a valid type (NC_EBADTYPE).
varid is not a valid variable ID (NC_ENOTVAR).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, blob_t
character(len=4) :: blob

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_def_opaque(ncid, 4, "blob", blob_t)
! NC_GLOBAL: a global attribute, of the dataset rather than of a variable
call nc_put_att_any(ncid, NC_GLOBAL, "magic", blob_t, 1, "ABCD")
call nc_get_att_any(ncid, NC_GLOBAL, "magic", 1, blob)       ! "ABCD"
call nc_close(ncid)

6 Variables

Variables hold the data of a dataset. A variable has a name, a type, a shape given by its dimensions (none for a scalar), and attributes. It is defined in define mode, and its values are written and read in data mode.

A variable is referred to by its variable ID: 1, 2, 3, ... in definition order (in a group, list them with nc_inq_varids). In Fortran, the first dimension varies fastest: a variable defined on [lon, lat, time] is read into an array a(nlon, nlat, ntime) and its records are the slices a(:, :, it). (ncdump and C list the same dimensions in the reverse order: rh(time, lat, lon).)

The routines of this chapter are in module stdlib_netcdf_var; nc_var_par_access is in Parallel I/O.

6.1 Language Types Corresponding to NetCDF External Data Types

The data routines (nc_put_var, nc_get_var, nc_put_att, nc_get_att, the fill-value routines) are generic over these Fortran types, which correspond to the netCDF types below. Values are converted between the Fortran type of the data and the external type of the variable on writing and reading (an out-of-range value gives NC_ERANGE).

Fortran type        netCDF type     size    default fill value
integer(int8)       NC_BYTE         1       NC_FILL_BYTE
character(len=*)    NC_CHAR         1       NC_FILL_CHAR
integer(int16)      NC_SHORT        2       NC_FILL_SHORT
integer(int32)      NC_INT          4       NC_FILL_INT
integer(int64)      NC_INT64        8       (no named constant; NetCDF-4 and CDF5 only)
real(sp)            NC_FLOAT        4       NC_FILL_FLOAT
real(dp)            NC_DOUBLE       8       NC_FILL_DOUBLE

The kinds come from stdlib_kinds. NetCDF-4 adds the unsigned types NC_UBYTE, NC_USHORT, NC_UINT, NC_UINT64 (read and written from signed Fortran integers), NC_STRING, and the user-defined types of chapter 5.

6.2 Create a Variable: nc_def_var

nc_def_var adds a variable to a dataset in define mode and returns its ID. Without dimids the variable is a scalar. The optional storage arguments, NetCDF-4 only, set at once what the nc_def_var_* routines below set one by one; they are refused for a scalar variable (NC_EINVAL), not silently dropped. As in netcdf-fortran, shuffle acts only together with deflate_level > 0.

Usage

subroutine nc_def_var(ncid, name, xtype, varid, dimids, contiguous, chunksizes, &
        deflate_level, shuffle, fletcher32, endianness, cache_size, cache_nelems, &
        cache_preemption, quantize_mode, nsd, zstandard_level, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: xtype
    integer, intent(out)                     :: varid
    integer, intent(in), optional            :: dimids(:)
    logical, intent(in), optional            :: contiguous
    integer, intent(in), optional            :: chunksizes(:)
    integer, intent(in), optional            :: deflate_level
    logical, intent(in), optional            :: shuffle
    logical, intent(in), optional            :: fletcher32
    integer, intent(in), optional            :: endianness
    integer, intent(in), optional            :: cache_size
    integer, intent(in), optional            :: cache_nelems
    integer, intent(in), optional            :: cache_preemption
    integer, intent(in), optional            :: quantize_mode
    integer, intent(in), optional            :: nsd
    integer, intent(in), optional            :: zstandard_level
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Variable name.
xtype: External type: NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, NC_INT64, NC_FLOAT, NC_DOUBLE, an unsigned NetCDF-4 type, or a user-defined type ID.
varid: Returned variable ID.
dimids: Dimension IDs, in Fortran order (fastest first; a classic dataset's unlimited dimension last). Omit for a scalar.
contiguous: .true. for contiguous storage (no chunking, no compression).
chunksizes: Chunk length along each dimension.
deflate_level: zlib compression level, 0 (none) to 9.
shuffle: .true. to shuffle bytes before compression.
fletcher32: .true. to store a Fletcher-32 checksum of each chunk.
endianness: NC_ENDIAN_NATIVE, NC_ENDIAN_LITTLE or NC_ENDIAN_BIG.
cache_size: Chunk cache of this variable: size in bytes.
cache_nelems: Chunk cache: number of slots.
cache_preemption: Chunk cache: preemption, 0-100.
quantize_mode: Lossy quantization: NC_QUANTIZE_BITGROOM, NC_QUANTIZE_GRANULARBR or NC_QUANTIZE_BITROUND.
nsd: Number of significant digits (decimal digits for BitGroom/GranularBR, bits for BitRound).
zstandard_level: Zstandard compression level (needs a build with Zstandard).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is not in define mode (NC_ENOTINDEFINE; NetCDF-4 switches by itself).
The name is already used by another variable (NC_ENAMEINUSE), or is not valid (NC_EBADNAME).
A dimension ID is not valid (NC_EBADDIM), or xtype is not a valid type (NC_EBADTYPE).
Storage options on a classic dataset (NC_ENOTNC4) or for a scalar (NC_EINVAL).
The unlimited dimension is not the last one, in a classic dataset (NC_EUNLIMPOS).
ncid does not refer to an open dataset (NC_EBADID).

Example

Define a compressed, chunked variable pressure(lon, lat, time) in foo.nc:

use stdlib_NetCDF
implicit none
integer :: ncid, lon, lat, time, varid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
call nc_inq_dimid(ncid, "lat", lat)
call nc_inq_dimid(ncid, "time", time)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "pressure", NC_FLOAT, varid, dimids=[lon, lat, time], &
                chunksizes=[10, 5, 1], deflate_level=4, shuffle=.true.)
call nc_enddef(ncid)
call nc_close(ncid)

6.3 Define Fill Parameters for a Variable: nc_def_var_fill

nc_def_var_fill sets whether a variable is pre-filled and with which value (its _FillValue). It is generic over the numeric kinds; give the fill value in the variable's type. It must be called before the variable's data is written.

Usage

subroutine nc_def_var_fill(ncid, varid, no_fill, fill, err)     ! generic
    integer,           intent(in)            :: ncid, varid
    integer,           intent(in)            :: no_fill
    <type>,            intent(in)            :: fill
    class(state_type), intent(out), optional :: err

<type>: integer(int8), integer(int16), integer(int32), integer(int64), real(sp), real(dp)

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
no_fill: 1 to turn pre-filling off for this variable, 0 to keep it on.
fill: The fill value, of the variable's type (ignored if no_fill is 1).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The variable's data has already been written (NC_ELATEDEF).
The dataset was opened read-only (NC_EPERM).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

A variable whose unwritten values read as -999:

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, lon, varid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
! NC_DOUBLE: the netCDF type of 64-bit reals
call nc_def_var(ncid, "depth", NC_DOUBLE, varid, dimids=[lon])
call nc_def_var_fill(ncid, varid, 0, -999.0_dp)
call nc_enddef(ncid)
call nc_close(ncid)

6.4 Learn About Fill Parameters for a Variable: nc_inq_var_fill

nc_inq_var_fill returns whether a variable is pre-filled and its fill value: the _FillValue attribute if set, otherwise the default fill value of its type.

Usage

subroutine nc_inq_var_fill(ncid, varid, no_fill, fill, err)     ! generic
    integer,           intent(in)            :: ncid, varid
    integer,           intent(out)           :: no_fill
    <type>,            intent(out)           :: fill
    class(state_type), intent(out), optional :: err

<type>: integer(int8), integer(int16), integer(int32), integer(int64), real(sp), real(dp)

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
no_fill: Returned 1 if pre-filling is off, 0 if on.
fill: Returned fill value; pass a variable of the variable's type.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, varid, no_fill
real(dp) :: fill

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varid(ncid, "rh", varid)
call nc_inq_var_fill(ncid, varid, no_fill, fill)   ! 0, NC_FILL_DOUBLE
call nc_close(ncid)

6.5 Compression: nc_def_var_deflate, nc_inq_var_deflate

nc_def_var_deflate turns zlib compression (and byte shuffling) on or off for a variable; nc_inq_var_deflate returns the settings.

NetCDF-4 storage settings must be chosen before the variable's data is first written (in practice, between nc_def_var and the end of define mode); they can also be given directly to nc_def_var. They are refused on classic-format datasets.

Usage

subroutine nc_def_var_deflate(ncid, varid, shuffle, deflate, deflate_level, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: shuffle
    integer, intent(in)                      :: deflate
    integer, intent(in)                      :: deflate_level
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_deflate(ncid, varid, shuffle, deflate, deflate_level, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: shuffle
    integer, intent(out)                     :: deflate
    integer, intent(out)                     :: deflate_level
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
shuffle: 1 to shuffle bytes before compression, 0 not to (returned by the inquiry).
deflate: 1 to compress, 0 not to (returned by the inquiry).
deflate_level: Compression level 1-9 (returned by the inquiry; ignored if deflate is 0).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
The variable is a scalar, which has no storage options (NC_EINVAL).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, lon, lat, varid, shuffle, deflate, level

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
call nc_inq_dimid(ncid, "lat", lat)
! NC_INT: the netCDF type of 32-bit integers
call nc_def_var(ncid, "mask", NC_INT, varid, dimids=[lon, lat])
call nc_def_var_deflate(ncid, varid, 1, 1, 5)
call nc_inq_var_deflate(ncid, varid, shuffle, deflate, level)   ! 1, 1, 5
call nc_close(ncid)

6.6 Chunking: nc_def_var_chunking, nc_inq_var_chunking

nc_def_var_chunking chooses how a variable is laid out: in chunks of a given shape (NC_CHUNKED), which compression and unlimited dimensions need, or contiguously (NC_CONTIGUOUS). nc_inq_var_chunking returns the layout. Good chunk shapes follow the usual access pattern: for a time series of maps, one map per chunk.

Usage

subroutine nc_def_var_chunking(ncid, varid, contiguous, chunksizes, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: contiguous
    integer, intent(in)                      :: chunksizes(:)
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_chunking(ncid, varid, contiguous, chunksizes, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: contiguous
    integer, intent(out)                     :: chunksizes(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
contiguous: NC_CHUNKED or NC_CONTIGUOUS (returned by the inquiry; also NC_COMPACT).
chunksizes: Chunk length along each dimension, in Fortran order (returned by the inquiry; ignored for NC_CONTIGUOUS).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

A chunk size is zero or larger than a fixed dimension (NC_EBADCHUNK).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
The variable is a scalar, which has no storage options (NC_EINVAL).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, lon, lat, time, varid, storage
integer :: chunks(3)

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
call nc_inq_dimid(ncid, "lat", lat)
call nc_inq_dimid(ncid, "time", time)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "u", NC_FLOAT, varid, dimids=[lon, lat, time])
! NC_CHUNKED: store in chunks, of the shape given next
call nc_def_var_chunking(ncid, varid, NC_CHUNKED, [10, 5, 1])
call nc_inq_var_chunking(ncid, varid, storage, chunks)   ! NC_CHUNKED, [10, 5, 1]
call nc_close(ncid)

6.7 Byte Order: nc_def_var_endian, nc_inq_var_endian

nc_def_var_endian sets the byte order in which a variable is stored on disk; data is converted on reading and writing, so it only matters for other tools and for speed.

Usage

subroutine nc_def_var_endian(ncid, varid, endian, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: endian
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_endian(ncid, varid, endian, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: endian
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
endian: NC_ENDIAN_NATIVE, NC_ENDIAN_LITTLE or NC_ENDIAN_BIG (returned by the inquiry).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, lon, varid, endian

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "v", NC_FLOAT, varid, dimids=[lon])
call nc_def_var_endian(ncid, varid, NC_ENDIAN_BIG)  ! NC_ENDIAN_BIG: store big-endian on disk
call nc_inq_var_endian(ncid, varid, endian)      ! NC_ENDIAN_BIG
call nc_close(ncid)

6.8 Checksums: nc_def_var_fletcher32, nc_inq_var_fletcher32

nc_def_var_fletcher32 turns on a Fletcher-32 checksum of each chunk of a variable, checked on reading.

Usage

subroutine nc_def_var_fletcher32(ncid, varid, fletcher32, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: fletcher32
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_fletcher32(ncid, varid, fletcher32, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: fletcher32
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
fletcher32: NC_FLETCHER32 or NC_NOCHECKSUM (returned by the inquiry).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
The variable is a scalar, which has no storage options (NC_EINVAL).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, lon, varid, flag

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "v", NC_FLOAT, varid, dimids=[lon])
! NC_FLETCHER32: store a Fletcher-32 checksum of each chunk
call nc_def_var_fletcher32(ncid, varid, NC_FLETCHER32)
call nc_inq_var_fletcher32(ncid, varid, flag)    ! NC_FLETCHER32
call nc_close(ncid)

6.9 Lossy Quantization: nc_def_var_quantize, nc_inq_var_quantize

nc_def_var_quantize keeps only the significant digits (or bits) of a float or double variable, setting the others so that compression works better. The data then differs from what was written, within the precision asked for.

Usage

subroutine nc_def_var_quantize(ncid, varid, quantize_mode, nsd, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: quantize_mode
    integer, intent(in)                      :: nsd
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_quantize(ncid, varid, quantize_mode, nsd, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: quantize_mode
    integer, intent(out)                     :: nsd
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
quantize_mode: NC_NOQUANTIZE, NC_QUANTIZE_BITGROOM, NC_QUANTIZE_GRANULARBR or NC_QUANTIZE_BITROUND (returned by the inquiry).
nsd: Significant digits kept: decimal digits for BitGroom/GranularBR, bits for BitRound (returned by the inquiry).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The variable is not of a float or double type (NC_EINVAL).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, lon, lat, varid, mode, nsd

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
call nc_inq_dimid(ncid, "lat", lat)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "sst", NC_FLOAT, varid, dimids=[lon, lat], chunksizes=[10, 5], deflate_level=4)
! NC_QUANTIZE_BITROUND: BitRound quantization: keep the next argument's number of bits
call nc_def_var_quantize(ncid, varid, NC_QUANTIZE_BITROUND, 10)
call nc_inq_var_quantize(ncid, varid, mode, nsd)   ! NC_QUANTIZE_BITROUND, 10
call nc_close(ncid)

6.10 Szip Compression: nc_def_var_szip, nc_inq_var_szip

nc_def_var_szip compresses a chunked variable with szip (the libaec implementation), an alternative to zlib for some scientific data. It needs a netcdf built with szip.

Usage

subroutine nc_def_var_szip(ncid, varid, options_mask, pixels_per_block, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: options_mask
    integer, intent(in)                      :: pixels_per_block
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_szip(ncid, varid, options_mask, pixels_per_block, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: options_mask
    integer, intent(out)                     :: pixels_per_block
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
options_mask: NC_SZIP_NN_OPTION_MASK (nearest neighbour) or NC_SZIP_EC_OPTION_MASK (entropy coding); returned by the inquiry, possibly with other bits set.
pixels_per_block: Even number, at most 32 (returned by the inquiry).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The netcdf build lacks szip (NC_EFILTER).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
The variable is a scalar, which has no storage options (NC_EINVAL).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, lon, lat, varid, mask, ppb

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
call nc_inq_dimid(ncid, "lat", lat)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "z", NC_FLOAT, varid, dimids=[lon, lat], chunksizes=[10, 5])
! NC_SZIP_NN_OPTION_MASK: szip with nearest-neighbour preprocessing
call nc_def_var_szip(ncid, varid, NC_SZIP_NN_OPTION_MASK, 8)
call nc_inq_var_szip(ncid, varid, mask, ppb)     ! ..., 8
call nc_close(ncid)

6.11 Zstandard Compression: nc_def_var_zstandard, nc_inq_var_zstandard

nc_def_var_zstandard compresses a variable with Zstandard. It needs netcdf-c and netcdf-fortran built with Zstandard; otherwise the calls fail with NC_ENOTBUILT (the case of Homebrew's netcdf-fortran 4.6.2).

Usage

subroutine nc_def_var_zstandard(ncid, varid, zstandard_level, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: zstandard_level
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_zstandard(ncid, varid, zstandard, zstandard_level, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: zstandard
    integer, intent(out)                     :: zstandard_level
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
zstandard_level: Compression level, e.g. 1-22 (returned by the inquiry).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.
zstandard: Returned 1 if Zstandard is on, 0 if off.

Errors

The netcdf build lacks Zstandard (NC_ENOTBUILT).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
The variable is a scalar, which has no storage options (NC_EINVAL).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

Use Zstandard if available:

use stdlib_NetCDF
implicit none
integer :: ncid, lon, varid
type(nc_state_type) :: err

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "zz", NC_FLOAT, varid, dimids=[lon], chunksizes=[10])
call nc_def_var_zstandard(ncid, varid, 5, err)
! NC_ENOTBUILT: the status when netcdf was built without the feature
if (err%nc_status == NC_ENOTBUILT) call nc_def_var_deflate(ncid, varid, 1, 1, 5)   ! fall back to zlib
call nc_close(ncid)

6.12 Define Filter Parameters for a Variable: nc_def_var_filter, nc_inq_var_filter

nc_def_var_filter applies an HDF5 filter, given its registered ID and integer parameters, to a chunked variable. The filter must be available to HDF5 (built in, or as a plugin found through HDF5_PLUGIN_PATH). Filter 1 is zlib deflate, its parameter the level. nc_inq_var_filter returns the first filter of a variable.

Usage

subroutine nc_def_var_filter(ncid, varid, filterid, nparams, params, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: filterid
    integer, intent(in)                      :: nparams
    integer, intent(in)                      :: params(:)
    class(state_type), intent(out), optional :: err

subroutine nc_inq_var_filter(ncid, varid, filterid, nparams, params, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(out)                     :: filterid
    integer, intent(out)                     :: nparams
    integer, intent(out)                     :: params(:)
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
filterid: HDF5 filter ID (returned by the inquiry).
nparams: Number of parameters (returned by the inquiry).
params: Filter parameters (returned by the inquiry; must be long enough).
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The filter is not available (NC_ENOFILTER, NC_EFILTER).
The dataset is not NetCDF-4, or is classic model (NC_ENOTNC4, NC_ESTRICTNC3).
The variable's data has already been written, so its storage is fixed (NC_ELATEDEF).
The variable is a scalar, which has no storage options (NC_EINVAL).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, lon, varid, filterid, nparams
integer :: params(4)

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_dimid(ncid, "lon", lon)
! NC_FLOAT: the netCDF type of 32-bit reals
call nc_def_var(ncid, "g", NC_FLOAT, varid, dimids=[lon], chunksizes=[10])
call nc_def_var_filter(ncid, varid, 1, 1, [5])            ! deflate, level 5
call nc_inq_var_filter(ncid, varid, filterid, nparams, params)   ! 1, 1, [5, ...]
call nc_close(ncid)

6.13 Get Information about a Variable from Its ID: nc_inquire_variable

nc_inquire_variable returns information about a variable: name, type, dimensions, number of attributes, and every NetCDF-4 storage setting. Every output is optional; ask only for what you need (the storage settings cost extra calls, and some fail on classic datasets).

Usage

subroutine nc_inquire_variable(ncid, varid, name, xtype, ndims, dimids, natts, &
        contiguous, chunksizes, deflate_level, shuffle, fletcher32, endianness, &
        cache_size, cache_nelems, cache_preemption, quantize_mode, nsd, zstandard, &
        zstandard_level, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(out), optional  :: name
    integer, intent(out), optional           :: xtype
    integer, intent(out), optional           :: ndims
    integer, intent(out), optional           :: dimids(:)
    integer, intent(out), optional           :: natts
    logical, intent(out), optional           :: contiguous
    integer, intent(out), optional           :: chunksizes(:)
    integer, intent(out), optional           :: deflate_level
    logical, intent(out), optional           :: shuffle
    logical, intent(out), optional           :: fletcher32
    integer, intent(out), optional           :: endianness
    integer, intent(out), optional           :: cache_size
    integer, intent(out), optional           :: cache_nelems
    integer, intent(out), optional           :: cache_preemption
    integer, intent(out), optional           :: quantize_mode
    integer, intent(out), optional           :: nsd
    integer, intent(out), optional           :: zstandard
    integer, intent(out), optional           :: zstandard_level
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
name: Returned name; NC_MAX_NAME characters always suffice.
xtype: Returned external type.
ndims: Returned number of dimensions (0 for a scalar).
dimids: Returned dimension IDs, in Fortran order; at least ndims long.
natts: Returned number of attributes.
contiguous: Returned .true. if stored contiguously.
chunksizes: Returned chunk sizes; at least ndims long.
deflate_level: Returned zlib level, 0 if not compressed.
shuffle: Returned .true. if shuffled.
fletcher32: Returned .true. if checksummed.
endianness: Returned NC_ENDIAN_*.
cache_size: Returned chunk cache size in bytes.
cache_nelems: Returned chunk cache slots.
cache_preemption: Returned chunk cache preemption, 0-100.
quantize_mode: Returned quantization mode (NC_NOQUANTIZE if none).
nsd: Returned significant digits of the quantization.
zstandard: Returned 1 if Zstandard-compressed (fails without Zstandard support).
zstandard_level: Returned Zstandard level.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

Name, type and shape of variable 4 of foo.nc (rh):

use stdlib_NetCDF
implicit none
integer :: ncid, xtype, ndims, natts
! NC_MAX_VAR_DIMS: the most dimensions a variable may have, so the list fits
integer :: dimids(NC_MAX_VAR_DIMS)
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inquire_variable(ncid, 4, name=name, xtype=xtype, ndims=ndims, dimids=dimids, natts=natts)
print "(a, ': ', i0, ' dimensions, ', i0, ' attributes')", trim(name), ndims, natts
call nc_close(ncid)

6.14 Get the ID of a Variable from Its Name: nc_inq_varid

nc_inq_varid returns the ID of a variable, given its name.

Usage

subroutine nc_inq_varid(ncid, name, varid, err)
    integer, intent(in)                      :: ncid
    character(len=*), intent(in)             :: name
    integer, intent(out)                     :: varid
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
name: Variable name.
varid: Returned variable ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No variable of that name (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, rh_varid

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varid(ncid, "rh", rh_varid)
call nc_close(ncid)

6.15 Writing Data Values: nc_put_var

nc_put_var writes values into a variable of an open dataset in data mode (NetCDF-4 leaves define mode by itself). Without start and count the whole array is written from the first element; with them, a hyperslab: count(i) values along dimension i from index start(i), every stride(i)-th. Writing beyond the current length of an unlimited dimension extends it.

The data is converted to the variable's type. Strings are described in Reading and Writing Character String Values.

Usage

subroutine nc_put_var(ncid, varid, values, start, count, stride, map, err)     ! generic
    integer,           intent(in)            :: ncid, varid
    <type>,            intent(in)            :: values(...)       ! rank 0 to 7
    integer,           intent(in), optional  :: start(:), count(:), stride(:), map(:)
    class(state_type), intent(out), optional :: err

<type>:  integer(int8), integer(int16), integer(int32), integer(int64), real(sp), real(dp),
         character(len=*)
rank 0:  only start (no count, stride or map)

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
values: The data: a scalar or an array of rank 1 to 7 of one of the types above. Its shape must hold product(count) values (with map, see below).
start: Index (1-based) of the first value written along each dimension, in Fortran order. Default: 1 everywhere.
count: Number of values along each dimension. Default: the shape of values (for each dimension of the variable; 1 for those beyond the rank of values).
stride: Step between written values along each dimension. Default: 1.
map: Distance in memory, in values, between successive values along each dimension of the variable: an index map to write transposed or strided memory. Default: the contiguous layout of values.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

start is outside the variable (NC_EINVALCOORDS) or start + count beyond a fixed dimension (NC_EEDGE).
A non-positive stride (NC_ESTRIDE).
A value out of range for the variable's type (NC_ERANGE).
Character data for a numeric variable or the reverse (NC_ECHAR).
The dataset is in define mode (NC_EINDEFINE), or was opened read-only (NC_EPERM).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

Write the whole of temp, then one record and a single value of rh:

use stdlib_NetCDF
use stdlib_kinds, only: sp, dp
implicit none
integer :: ncid, temp_varid, rh_varid
real(sp) :: temp(10, 5)
real(dp) :: rh(10, 5)

temp = 15.0_sp
rh = 50.0_dp
call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_inq_varid(ncid, "temp", temp_varid)
call nc_put_var(ncid, temp_varid, temp)                                  ! whole variable
call nc_inq_varid(ncid, "rh", rh_varid)
call nc_put_var(ncid, rh_varid, rh, start=[1, 1, 3], count=[10, 5, 1])   ! record 3
call nc_put_var(ncid, rh_varid, 0.5_dp, start=[4, 3, 3])                 ! rh(4, 3, 3)
call nc_put_var(ncid, rh_varid, [1.0_dp, 2.0_dp], start=[1, 1, 1], count=[2, 1, 1], stride=[5, 1, 1])
call nc_close(ncid)

6.16 Reading Data Values: nc_get_var

nc_get_var reads values of a variable into an array (or a scalar). The arguments mirror those of nc_put_var: without start/count the array is filled from the start of the variable; with them, a hyperslab is read. values must be allocated or declared with the right shape: dimension lengths come from nc_inquire_dimension. Values are converted from the variable's type to that of values.

Usage

subroutine nc_get_var(ncid, varid, values, start, count, stride, map, err)     ! generic
    integer,           intent(in)            :: ncid, varid
    <type>,            intent(out)           :: values(...)       ! rank 0 to 7 (character: inout)
    integer,           intent(in), optional  :: start(:), count(:), stride(:), map(:)
    class(state_type), intent(out), optional :: err

<type>:  integer(int8), integer(int16), integer(int32), integer(int64), real(sp), real(dp),
         character(len=*)
rank 0:  only start (no count, stride or map)

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
values: Returned data; its shape must hold product(count) values.
start: Index (1-based) of the first value read along each dimension. Default: 1 everywhere.
count: Number of values along each dimension. Default: the shape of values.
stride: Step between read values along each dimension. Default: 1.
map: Distance in memory, in values, between successive values along each dimension.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

start is outside the variable (NC_EINVALCOORDS) or start + count beyond a dimension (NC_EEDGE).
A non-positive stride (NC_ESTRIDE).
A value out of range for the type of values (NC_ERANGE).
Character data for a numeric variable or the reverse (NC_ECHAR).
The dataset is in define mode (NC_EINDEFINE).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

Read all of rh, its second record, and every other longitude of temp:

use stdlib_NetCDF
use stdlib_kinds, only: sp, dp
implicit none
integer :: ncid, varid
real(dp) :: rh(10, 5, 2), rec2(10, 5)
real(sp) :: every_other(5, 5)

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varid(ncid, "rh", varid)
call nc_get_var(ncid, varid, rh)
call nc_get_var(ncid, varid, rec2, start=[1, 1, 2], count=[10, 5, 1])
call nc_inq_varid(ncid, "temp", varid)
call nc_get_var(ncid, varid, every_other, stride=[2, 1])
call nc_close(ncid)

6.17 Reading and Writing Character String Values

Classic netCDF has no string type: strings are stored in NC_CHAR variables, with the string length as an extra dimension, the first (fastest varying) in Fortran order. A rank-r array of character(len=n) values is an NC_CHAR variable with r+1 dimensions, the first of length n; a single string is a 1-D NC_CHAR variable. nc_put_var and nc_get_var accept character(len=*) data at ranks 0 to 7 and map it this way.

Strings shorter than the string dimension are padded on writing (with blanks from Fortran); read them into variables of the dimension's length and trim as needed. With start and count, the first element addresses characters within the strings.

The NetCDF-4 type NC_STRING (variable-length strings) is not supported by netcdf-fortran's data routines, nor by these wrappers.

Example

Store three station names in a variable station(strlen, nstation):

use stdlib_NetCDF
implicit none
integer :: ncid, strlen_dimid, n_dimid, varid
character(len=8) :: names(3), back(3)

names = [character(len=8) :: "north", "centre", "south"]
call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_def_dim(ncid, "strlen", 8, strlen_dimid)
call nc_def_dim(ncid, "nstation", 3, n_dimid)
! NC_CHAR: the netCDF type of characters (text)
call nc_def_var(ncid, "station", NC_CHAR, varid, dimids=[strlen_dimid, n_dimid])
call nc_enddef(ncid)
call nc_put_var(ncid, varid, names)
call nc_get_var(ncid, varid, back)               ! back(2) == "centre"
call nc_close(ncid)

6.18 Fill Values

Unwritten values of a variable read as its fill value: the value of its _FillValue attribute if it has one, otherwise the default of its type (NC_FILL_BYTE, NC_FILL_CHAR, NC_FILL_SHORT, NC_FILL_INT, NC_FILL_FLOAT, NC_FILL_DOUBLE, ...). Readers can test for it to find missing data.

Set _FillValue before writing any data: with nc_def_var_fill, or as an attribute of the variable's type with nc_put_att.
Pre-filling costs a write of every value; turn it off per dataset with nc_set_fill (or per variable with nc_def_var_fill's no_fill) when all values will be written anyway.
nc_inq_var_fill returns the fill value in use.

6.19 Rename a Variable: nc_rename_var

nc_rename_var renames a variable. On a classic-format dataset, a longer name needs define mode.

Usage

subroutine nc_rename_var(ncid, varid, newname, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(in)             :: newname
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
newname: New name.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The new name is already used by another variable (NC_ENAMEINUSE).
A longer name on a classic dataset in data mode (NC_ENOTINDEFINE).
The dataset was opened read-only (NC_EPERM).
varid is not a valid variable ID (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, varid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_varid(ncid, "rh", varid)
call nc_rename_var(ncid, varid, "rel_hum")
call nc_enddef(ncid)
call nc_close(ncid)

7 Attributes

Attributes hold metadata: the units of a variable, its valid range, the title of a dataset. An attribute belongs to a variable, or is global (varid = NC_GLOBAL), and has a name, a type, and a length (one value, or a 1-D array; for text, the number of characters).

Attributes are created and changed in define mode (on a classic dataset; NetCDF-4 switches by itself), and read in either mode. They are identified by name; their numbers (1, 2, 3, ... for each variable) serve to list them. Conventions such as CF give standard names (units, long_name, standard_name, _FillValue, valid_range, scale_factor, ...).

The routines of this chapter are in module stdlib_netcdf_att; attributes of user-defined types are written and read as raw bytes with nc_put_att_any / nc_get_att_any (chapter 5).

7.1 Create an Attribute: nc_put_att

nc_put_att creates an attribute, or replaces an existing one of the same name. Its type is that of the data: real(dp) values make an NC_DOUBLE attribute, a string an NC_CHAR one. To give _FillValue or valid_range the type of their variable, pass data of that type.

Usage

subroutine nc_put_att(ncid, varid, name, values, err)     ! generic
    integer,           intent(in)            :: ncid, varid
    character(len=*),  intent(in)            :: name
    <type>,            intent(in)            :: values      ! scalar or rank 1; text: scalar
    class(state_type), intent(out), optional :: err

<type>: integer(int8), integer(int16), integer(int32), integer(int64), real(sp), real(dp),
        character(len=*)

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, or NC_GLOBAL for a global attribute.
name: Attribute name.
values: The value(s): a scalar or rank-1 array of a numeric kind, or one string.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

Not in define mode, on a classic dataset, for a new or longer attribute (NC_ENOTINDEFINE).
The name is not valid (NC_EBADNAME); too many attributes (NC_EMAXATTS).
_FillValue of a type different from its variable's, or after data was written (NC_EBADTYPE, NC_ELATEFILL).
The dataset was opened read-only (NC_EPERM).
varid is neither a valid variable ID nor NC_GLOBAL (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

Add units, valid_range and a global title to foo.nc:

use stdlib_NetCDF
use stdlib_kinds, only: sp
implicit none
integer :: ncid, varid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_varid(ncid, "temp", varid)
call nc_put_att(ncid, varid, "units", "celsius")
call nc_put_att(ncid, varid, "valid_range", [-50.0_sp, 50.0_sp])
! NC_GLOBAL: a global attribute, of the dataset rather than of a variable
call nc_put_att(ncid, NC_GLOBAL, "title", "Temperature and humidity")
call nc_enddef(ncid)
call nc_close(ncid)

7.2 Get Information about an Attribute: nc_inquire_attribute, nc_inq_attname

nc_inquire_attribute returns the type, length and number of an attribute, given its name; nc_inq_attname returns the name of an attribute, given its number. Together they list the attributes of a variable: numbers run from 1 to the natts of nc_inquire_variable (or the nattributes of nc_inquire, for global ones).

Usage

subroutine nc_inquire_attribute(ncid, varid, name, xtype, len, attnum, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(in)             :: name
    integer, intent(out), optional           :: xtype
    integer, intent(out), optional           :: len
    integer, intent(out), optional           :: attnum
    class(state_type), intent(out), optional :: err

subroutine nc_inq_attname(ncid, varid, attnum, name, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: attnum
    character(len=*), intent(out)            :: name
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, or NC_GLOBAL for a global attribute.
name: Attribute name: given to nc_inquire_attribute, returned by nc_inq_attname (NC_MAX_NAME characters always suffice).
xtype: Returned external type.
len: Returned number of values (characters, for text).
attnum: Attribute number, 1-based: returned by nc_inquire_attribute, given to nc_inq_attname.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No attribute of that name or number (NC_ENOTATT).
varid is neither a valid variable ID nor NC_GLOBAL (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

List the attributes of rh with their lengths:

use stdlib_NetCDF
implicit none
integer :: ncid, varid, natts, i, xtype, n
! NC_MAX_NAME: the longest name netCDF allows, so any name fits
character(len=NC_MAX_NAME) :: name

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varid(ncid, "rh", varid)
call nc_inquire_variable(ncid, varid, natts=natts)
do i = 1, natts
    call nc_inq_attname(ncid, varid, i, name)
    call nc_inquire_attribute(ncid, varid, name, xtype=xtype, len=n)
    print "(a, ': type ', i0, ', length ', i0)", trim(name), xtype, n
end do
call nc_close(ncid)

7.3 Get an Attribute's Values: nc_get_att

nc_get_att reads the values of an attribute, converted to the type of values. Size values from the length given by nc_inquire_attribute; for text, a string at least that long (blank it first: only the attribute's characters are written).

Usage

subroutine nc_get_att(ncid, varid, name, values, err)     ! generic
    integer,           intent(in)            :: ncid, varid
    character(len=*),  intent(in)            :: name
    <type>,            intent(out)           :: values      ! scalar or rank 1; text: scalar, inout
    class(state_type), intent(out), optional :: err

<type>: integer(int8), integer(int16), integer(int32), integer(int64), real(sp), real(dp),
        character(len=*)

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, or NC_GLOBAL for a global attribute.
name: Attribute name.
values: Returned value(s): a scalar, a rank-1 array long enough, or a string.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No attribute of that name (NC_ENOTATT).
Text into numbers or the reverse (NC_ECHAR); a value out of range (NC_ERANGE).
varid is neither a valid variable ID nor NC_GLOBAL (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

Read valid_range and units of rh, and the global title:

use stdlib_NetCDF
use stdlib_kinds, only: dp
implicit none
integer :: ncid, varid, n
real(dp), allocatable :: valid_range(:)
character(len=:), allocatable :: units
character(len=80) :: title

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varid(ncid, "rh", varid)
call nc_inquire_attribute(ncid, varid, "valid_range", len=n)
allocate(valid_range(n))
call nc_get_att(ncid, varid, "valid_range", valid_range)
call nc_inquire_attribute(ncid, varid, "units", len=n)
units = repeat(" ", n)
call nc_get_att(ncid, varid, "units", units)
title = ""
! NC_GLOBAL: a global attribute, of the dataset rather than of a variable
call nc_get_att(ncid, NC_GLOBAL, "title", title)
call nc_close(ncid)

7.4 Copy an Attribute from One NetCDF to Another: nc_copy_att

nc_copy_att copies an attribute from a variable (or the globals) of one open dataset to a variable of the same or another open dataset, which must be writable (and in define mode, if classic). An attribute of that name at the destination is replaced.

Usage

subroutine nc_copy_att(ncid_in, varid_in, name, ncid_out, varid_out, err)
    integer, intent(in)                      :: ncid_in
    integer, intent(in)                      :: varid_in
    character(len=*), intent(in)             :: name
    integer, intent(in)                      :: ncid_out
    integer, intent(in)                      :: varid_out
    class(state_type), intent(out), optional :: err

ncid_in: NetCDF ID of the source dataset.
varid_in: Source variable ID, or NC_GLOBAL.
name: Name of the attribute.
ncid_out: NetCDF ID of the destination dataset (may be ncid_in).
varid_out: Destination variable ID, or NC_GLOBAL.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No attribute of that name at the source (NC_ENOTATT).
The destination is read-only (NC_EPERM) or, classic, not in define mode (NC_ENOTINDEFINE).
varid is neither a valid variable ID nor NC_GLOBAL (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

Give temp the same units attribute as rh:

use stdlib_NetCDF
implicit none
integer :: ncid, rh_varid, temp_varid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_varid(ncid, "rh", rh_varid)
call nc_inq_varid(ncid, "temp", temp_varid)
call nc_copy_att(ncid, rh_varid, "units", ncid, temp_varid)
call nc_enddef(ncid)
call nc_close(ncid)

7.5 Rename an Attribute: nc_rename_att

nc_rename_att renames an attribute. On a classic dataset, a longer name needs define mode.

Usage

subroutine nc_rename_att(ncid, varid, curname, newname, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(in)             :: curname
    character(len=*), intent(in)             :: newname
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, or NC_GLOBAL for a global attribute.
curname: Current name.
newname: New name.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No attribute of the current name (NC_ENOTATT).
The new name is already used by an attribute of the variable (NC_ENAMEINUSE).
A longer name on a classic dataset in data mode (NC_ENOTINDEFINE).
The dataset was opened read-only (NC_EPERM).
varid is neither a valid variable ID nor NC_GLOBAL (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, varid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
call nc_inq_varid(ncid, "rh", varid)
call nc_rename_att(ncid, varid, "units", "Units")
call nc_enddef(ncid)
call nc_close(ncid)

7.6 Delete an Attribute: nc_del_att

nc_del_att deletes an attribute. On a classic dataset it needs define mode.

Usage

subroutine nc_del_att(ncid, varid, name, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    character(len=*), intent(in)             :: name
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, or NC_GLOBAL for a global attribute.
name: Name of the attribute to delete.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

No attribute of that name (NC_ENOTATT).
Not in define mode, on a classic dataset (NC_ENOTINDEFINE).
The dataset was opened read-only (NC_EPERM).
varid is neither a valid variable ID nor NC_GLOBAL (NC_ENOTVAR).
ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid

call nc_open("foo.nc", NC_WRITE, ncid)            ! NC_WRITE: open for reading and writing
call nc_redef(ncid)
! NC_GLOBAL: a global attribute, of the dataset rather than of a variable
call nc_del_att(ncid, NC_GLOBAL, "history")
call nc_enddef(ncid)
call nc_close(ncid)

8 Parallel I/O

With a netcdf built for MPI (nc-config --has-parallel reports yes), several MPI processes can open one dataset together and write or read parts of each variable: NetCDF-4 datasets through parallel HDF5, classic formats through PnetCDF. All the processes of the communicator make the define-mode calls with the same arguments; data calls may differ per process (each writes its own hyperslab).

The MPI handles (comm, info) are plain default integers, as in the mpi module, so stdlib_NetCDF itself has no MPI dependency: in an MPI program pass MPI_COMM_WORLD, MPI_INFO_NULL, and so on. Without a parallel build, these routines fail and report through err (Homebrew's netcdf has no MPI support; the examples below handle that case).

The legacy routines nc_create_mp, nc_open_mp, nc_set_base_pe and nc_inq_base_pe date from the Cray multi-processing interface; they work on any build and are kept for completeness. nc_create_mp and nc_open_mp call netcdf-c directly: netcdf-fortran 4.6.2 passes the base PE by address, so netcdf-c always fails with NC_EINVAL.

The routines of this chapter are in module stdlib_netcdf_par.

8.1 Create a Dataset for Parallel I/O: nc_create_par

nc_create_par creates a dataset for parallel access by the processes of an MPI communicator, and returns its NetCDF ID on every process. The format must be NetCDF-4 (NC_NETCDF4, with NC_MPIIO) or a classic format through PnetCDF (NC_PNETCDF).

Usage

subroutine nc_create_par(path, cmode, comm, info, ncid, cache_size, cache_nelems, &
        cache_preemption, err)
    character(len=*), intent(in)             :: path
    integer, intent(in)                      :: cmode
    integer, intent(in)                      :: comm
    integer, intent(in)                      :: info
    integer, intent(out)                     :: ncid
    integer, intent(in), optional            :: cache_size
    integer, intent(in), optional            :: cache_nelems
    real, intent(in), optional               :: cache_preemption
    class(state_type), intent(out), optional :: err

path: Name of the file to create.
cmode: Creation mode, e.g. ior(NC_NETCDF4, NC_MPIIO), as for nc_create.
comm: MPI communicator of the processes that share the dataset (e.g. MPI_COMM_WORLD).
info: MPI info object with I/O hints (e.g. MPI_INFO_NULL).
ncid: Returned NetCDF ID.
cache_size: Chunk cache size in bytes.
cache_nelems: Chunk cache slots.
cache_preemption: Chunk cache preemption, 0-100.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

netcdf was built without parallel I/O (NC_ENOPAR, NC_ENOTBUILT).
An invalid MPI communicator or info object (NC_EMPI, NC_EPARINIT).
See also the errors of nc_create.

Example

Create a parallel dataset, or say why it cannot be done:

use stdlib_NetCDF
implicit none
integer :: ncid, comm, info
type(nc_state_type) :: err

comm = 0        ! in an MPI program: MPI_COMM_WORLD (use mpi)
info = 0        ! MPI_INFO_NULL
! NC_NETCDF4: NetCDF-4 (HDF5-based) format; NC_MPIIO: parallel access through MPI-IO
call nc_create_par("par.nc", ior(NC_NETCDF4, NC_MPIIO), comm, info, ncid, err=err)
if (err%error()) then
    print "(a)", "no parallel I/O here: " // trim(err%message)
else
    call nc_close(ncid)
end if

8.2 Open a Dataset for Parallel I/O: nc_open_par

nc_open_par opens an existing dataset for parallel access by the processes of an MPI communicator.

Usage

subroutine nc_open_par(path, cmode, comm, info, ncid, cache_size, cache_nelems, &
        cache_preemption, err)
    character(len=*), intent(in)             :: path
    integer, intent(in)                      :: cmode
    integer, intent(in)                      :: comm
    integer, intent(in)                      :: info
    integer, intent(out)                     :: ncid
    integer, intent(in), optional            :: cache_size
    integer, intent(in), optional            :: cache_nelems
    real, intent(in), optional               :: cache_preemption
    class(state_type), intent(out), optional :: err

path: Name of the file to open.
cmode: Access mode: NC_NOWRITE or NC_WRITE, combined with NC_MPIIO (or NC_PNETCDF).
comm: MPI communicator of the processes that share the dataset (e.g. MPI_COMM_WORLD).
info: MPI info object with I/O hints (e.g. MPI_INFO_NULL).
ncid: Returned NetCDF ID.
cache_size: Chunk cache size in bytes.
cache_nelems: Chunk cache slots.
cache_preemption: Chunk cache preemption, 0-100.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

netcdf was built without parallel I/O (NC_ENOPAR, NC_ENOTBUILT).
An invalid MPI communicator or info object (NC_EMPI, NC_EPARINIT).
See also the errors of nc_open.

Example

use stdlib_NetCDF
implicit none
integer :: ncid, comm, info
type(nc_state_type) :: err

comm = 0        ! MPI_COMM_WORLD
info = 0        ! MPI_INFO_NULL
! NC_NOWRITE: open read-only; NC_MPIIO: parallel access through MPI-IO
call nc_open_par("foo.nc", ior(NC_NOWRITE, NC_MPIIO), comm, info, ncid, err=err)
if (err%ok()) call nc_close(ncid)

8.3 Change between Collective and Independent Parallel Access: nc_var_par_access

nc_var_par_access chooses how the processes access a variable of a dataset opened for parallel I/O: collective (NC_COLLECTIVE: every process takes part in each read or write, which lets MPI-IO optimise; needed for writes along an unlimited dimension) or independent (NC_INDEPENDENT, the default for NetCDF-4: each process reads and writes on its own).

Usage

subroutine nc_var_par_access(ncid, varid, access, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: varid
    integer, intent(in)                      :: access
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
varid: Variable ID, from nc_def_var or nc_inq_varid (1, 2, 3, ... in definition order); NC_GLOBAL for the file's (or group's) global attributes where attributes are concerned.
access: NC_COLLECTIVE or NC_INDEPENDENT.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

The dataset was not opened for parallel I/O (NC_ENOPAR).
varid is not a valid variable ID (NC_ENOTVAR).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, varid
type(nc_state_type) :: err

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_varid(ncid, "rh", varid)
! NC_COLLECTIVE: every process takes part in each access
call nc_var_par_access(ncid, varid, NC_COLLECTIVE, err)   ! fails here: not a parallel open
call nc_close(ncid)

8.4 Legacy Multi-Processing Create and Open: nc_create_mp, nc_open_mp

nc_create_mp and nc_open_mp are nc_create and nc_open with a base processing element (PE) and an I/O buffer size hint, from the Cray multi-processing interface. On other systems use a base PE of 0. They call netcdf-c's nc__create_mp/nc__open_mp directly (see the chapter introduction).

Usage

subroutine nc_create_mp(path, cmode, initalsz, basepe, chunksizehint, ncid, err)
    character(len=*), intent(in)             :: path
    integer, intent(in)                      :: cmode
    integer, intent(in)                      :: initalsz
    integer, intent(in)                      :: basepe
    integer, intent(in)                      :: chunksizehint
    integer, intent(out)                     :: ncid
    class(state_type), intent(out), optional :: err

subroutine nc_open_mp(path, mode, basepe, chunksizeint, ncid, err)
    character(len=*), intent(in)             :: path
    integer, intent(in)                      :: mode
    integer, intent(in)                      :: basepe
    integer, intent(in)                      :: chunksizeint
    integer, intent(out)                     :: ncid
    class(state_type), intent(out), optional :: err

path: Name of the file.
cmode: Creation mode, as for nc_create.
initalsz: Initial size of the file in bytes (0: default).
basepe: Base processing element (0).
chunksizehint: I/O buffer size hint in bytes (0: default).
ncid: Returned NetCDF ID.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.
mode: Access mode, as for nc_open.
chunksizeint: I/O buffer size hint in bytes (0: default).

Errors

See the errors of nc_create and nc_open.

Example

use stdlib_NetCDF
implicit none
integer :: ncid

! NC_CLOBBER: create, overwriting the file if it exists
call nc_create_mp("mp.nc", NC_CLOBBER, 0, 0, 0, ncid)
call nc_close(ncid)
call nc_open_mp("mp.nc", NC_NOWRITE, 0, 0, ncid)  ! NC_NOWRITE: open read-only
call nc_close(ncid)

8.5 Legacy Base Processing Element: nc_set_base_pe, nc_inq_base_pe

nc_set_base_pe sets, and nc_inq_base_pe returns, the base processing element of an open dataset, for the Cray multi-processing interface. Elsewhere it is 0.

Usage

subroutine nc_set_base_pe(ncid, pe, err)
    integer, intent(in)                      :: ncid
    integer, intent(in)                      :: pe
    class(state_type), intent(out), optional :: err

subroutine nc_inq_base_pe(ncid, pe, err)
    integer, intent(in)                      :: ncid
    integer, intent(out)                     :: pe
    class(state_type), intent(out), optional :: err

ncid: NetCDF ID, from a previous call to nc_open or nc_create, or a group ID (from nc_def_grp, nc_inq_grp_ncid, ...).
pe: Base processing element: given to nc_set_base_pe, returned by nc_inq_base_pe.
err: Optional error state (class(state_type), e.g. type(nc_state_type)). If present, the outcome is returned in it and the program continues; if absent, a failure is reported to the active report sink and the program stops. Pass it by keyword (err=err) when the routine has other optional arguments.

Errors

ncid does not refer to an open dataset (NC_EBADID).

Example

use stdlib_NetCDF
implicit none
integer :: ncid, pe

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_set_base_pe(ncid, 0)
call nc_inq_base_pe(ncid, pe)                    ! 0
call nc_close(ncid)

9 Error States and Status Codes

Chapter 1 describes how errors reach the caller (Error Handling). This chapter documents the error type and the status-code helpers. The messages always end with the symbolic name and value of the status, e.g. NetCDF: Start+count exceeds dimension bound (NC_EEDGE = -57), whether returned in err or printed before a stop. The status codes themselves are listed in Constants, group "Error handling".

Module stdlib_netcdf_error (and stdlib_netcdf_constants for nc_status_name).

9.1 The Error State: nc_state_type

nc_state_type is the error state to pass as err when you need the NetCDF status code: it extends stdlib's state_type with nc_status, which every call sets, to NC_NOERR on success. A plain type(state_type) works too, with the stdlib fields only.

Usage

type, extends(state_type) :: nc_state_type
    integer :: nc_status = NC_NOERR
end type nc_state_type

! inherited from stdlib_error's state_type:
!   integer :: state                      STDLIB_SUCCESS, or STDLIB_IO_ERROR on any NetCDF failure
!   character(len=512) :: message         the NetCDF message with its symbolic code
!   character(len=...) :: where_at        the nc_* routine that failed
!   logical function ok(), error()        tests
!   function print()                      a one-line description

nc_status: NetCDF status of the last call made with this err: NC_NOERR or an NC_E* code.
state: stdlib's state: STDLIB_SUCCESS, or STDLIB_IO_ERROR for any NetCDF failure.
message: Message of the failure: the NetCDF text and the symbolic code.
where_at: Name of the nc_* routine that set the state.

Example

Handle a missing dimension, stop on anything else:

use stdlib_NetCDF
implicit none
integer :: ncid, dimid
type(nc_state_type) :: err

call nc_open("foo.nc", NC_NOWRITE, ncid)          ! NC_NOWRITE: open read-only
call nc_inq_dimid(ncid, "depth", dimid, err)
select case (err%nc_status)
case (NC_NOERR)                                   ! NC_NOERR: the status of a successful call
    print "(a)", "found depth"
! NC_EBADDIM: the status when no dimension has that name
case (NC_EBADDIM)
    print "(a)", "no depth dimension: 2-D data"
case default
    error stop trim(err%message)
end select
call nc_close(ncid)

9.2 Symbolic Name of a Status Code: nc_status_name

The function nc_status_name returns the name of the constant for a status code ("NC_ENOTVAR" for -49). An unknown code gives "NC_<unknown>".

Usage

function nc_status_name(status) result(name)
    integer, intent(in)           :: status
    character(len=:), allocatable :: name

status: A NetCDF status code.
name: The name of its constant.

Errors

None.

Example

use stdlib_NetCDF
implicit none

! NC_ENOTVAR: the status when no variable has that name
print "(a)", nc_status_name(NC_ENOTVAR) // " = " // nc_strerror(NC_ENOTVAR)

A Summary of the Level-0 Interface

The first line of every routine's Usage block, in alphabetical order, with a link to its section. The generic interfaces (nc_put_var, nc_get_var, nc_put_att, nc_get_att, nc_def_var_fill, nc_inq_var_fill) are listed in their sections only.

Routine	Section
`subroutine nc_abort(ncid, err)`	nc_abort
`subroutine nc_close(ncid, err)`	nc_close
`subroutine nc_copy_att(ncid_in, varid_in, name, ncid_out, varid_out, err)`	nc_copy_att
`subroutine nc_create(path, cmode, ncid, initialsize, chunksize, cache_size, cache_nelems, &`	nc_create
`subroutine nc_create_mp(path, cmode, initalsz, basepe, chunksizehint, ncid, err)`	nc_create_mp
`subroutine nc_create_par(path, cmode, comm, info, ncid, cache_size, cache_nelems, &`	nc_create_par
`subroutine nc_def_compound(ncid, size, name, typeid, err)`	nc_def_compound
`subroutine nc_def_dim(ncid, name, len, dimid, err)`	nc_def_dim
`subroutine nc_def_enum(ncid, base_typeid, name, typeid, err)`	nc_def_enum
`subroutine nc_def_grp(parent_ncid, name, new_ncid, err)`	nc_def_grp
`subroutine nc_def_opaque(ncid, size, name, xtype, err)`	nc_def_opaque
`subroutine nc_def_var(ncid, name, xtype, varid, dimids, contiguous, chunksizes, &`	nc_def_var
`subroutine nc_def_var_chunking(ncid, varid, contiguous, chunksizes, err)`	nc_def_var_chunking
`subroutine nc_def_var_deflate(ncid, varid, shuffle, deflate, deflate_level, err)`	nc_def_var_deflate
`subroutine nc_def_var_endian(ncid, varid, endian, err)`	nc_def_var_endian
`subroutine nc_def_var_filter(ncid, varid, filterid, nparams, params, err)`	nc_def_var_filter
`subroutine nc_def_var_fletcher32(ncid, varid, fletcher32, err)`	nc_def_var_fletcher32
`subroutine nc_def_var_quantize(ncid, varid, quantize_mode, nsd, err)`	nc_def_var_quantize
`subroutine nc_def_var_szip(ncid, varid, options_mask, pixels_per_block, err)`	nc_def_var_szip
`subroutine nc_def_var_zstandard(ncid, varid, zstandard_level, err)`	nc_def_var_zstandard
`subroutine nc_def_vlen(ncid, name, base_typeid, xtypeid, err)`	nc_def_vlen
`subroutine nc_del_att(ncid, varid, name, err)`	nc_del_att
`subroutine nc_delete(path, err)`	nc_delete
`subroutine nc_enddef(ncid, err)`	nc_enddef
`subroutine nc_get_att_any(ncid, varid, name, length, values, err)`	nc_get_att_any
`subroutine nc_get_var_any(ncid, varid, values, start, count, stride, map, err)`	nc_get_var_any
`subroutine nc_inq_attname(ncid, varid, attnum, name, err)`	nc_inq_attname
`subroutine nc_inq_base_pe(ncid, pe, err)`	nc_inq_base_pe
`subroutine nc_inq_cmp_fielddim_sizes(ncid, xtype, fieldid, dim_sizes, err)`	nc_inq_cmp_fielddim_sizes
`subroutine nc_inq_compound(ncid, xtype, name, size, nfields, err)`	nc_inq_compound
`subroutine nc_inq_compound_field(ncid, xtype, fieldid, name, offset, field_typeid, ndims, &`	nc_inq_compound_field
`subroutine nc_inq_compound_fieldindex(ncid, xtype, name, fieldid, err)`	nc_inq_compound_fieldindex
`subroutine nc_inq_compound_fieldname(ncid, xtype, fieldid, name, err)`	nc_inq_compound_fieldname
`subroutine nc_inq_compound_fieldndims(ncid, xtype, fieldid, ndims, err)`	nc_inq_compound_fieldndims
`subroutine nc_inq_compound_fieldoffset(ncid, xtype, fieldid, offset, err)`	nc_inq_compound_fieldoffset
`subroutine nc_inq_compound_fieldtype(ncid, xtype, fieldid, field_typeid, err)`	nc_inq_compound_fieldtype
`subroutine nc_inq_compound_name(ncid, xtype, name, err)`	nc_inq_compound_name
`subroutine nc_inq_compound_nfields(ncid, xtype, nfields, err)`	nc_inq_compound_nfields
`subroutine nc_inq_compound_size(ncid, xtype, size, err)`	nc_inq_compound_size
`subroutine nc_inq_dimid(ncid, name, dimid, err)`	nc_inq_dimid
`subroutine nc_inq_dimids(ncid, ndims, dimids, include_parents, err)`	nc_inq_dimids
`subroutine nc_inq_enum(ncid, xtype, name, base_nc_type, base_size, num_members, err)`	nc_inq_enum
`subroutine nc_inq_enum_ident(ncid, xtype, value, identifier, err)`	nc_inq_enum_ident
`subroutine nc_inq_enum_member(ncid, xtype, idx, name, value, err)`	nc_inq_enum_member
`subroutine nc_inq_format(ncid, formatnum, err)`	nc_inq_format
`subroutine nc_inq_grp_full_ncid(ncid, full_name, grpid, err)`	nc_inq_grp_full_ncid
`subroutine nc_inq_grp_ncid(ncid, name, grpid, err)`	nc_inq_grp_ncid
`subroutine nc_inq_grp_parent(ncid, parent_ncid, err)`	nc_inq_grp_parent
`subroutine nc_inq_grpname(ncid, name, err)`	nc_inq_grpname
`subroutine nc_inq_grpname_full(ncid, len, name, err)`	nc_inq_grpname_full
`subroutine nc_inq_grpname_len(ncid, len, err)`	nc_inq_grpname_len
`subroutine nc_inq_grps(ncid, numgrps, ncids, err)`	nc_inq_grps
`function nc_inq_libvers() result(version)`	nc_inq_libvers
`subroutine nc_inq_ncid(ncid, name, grp_ncid, err)`	nc_inq_ncid
`subroutine nc_inq_opaque(ncid, xtype, name, size, err)`	nc_inq_opaque
`subroutine nc_inq_path(ncid, pathlen, path, err)`	nc_inq_path
`subroutine nc_inq_type(ncid, xtype, name, size, err)`	nc_inq_type
`subroutine nc_inq_typeids(ncid, ntypes, typeids, err)`	nc_inq_typeids
`subroutine nc_inq_unlimdims(ncid, nunlimdims, unlimdimids, err)`	nc_inq_unlimdims
`subroutine nc_inq_user_type(ncid, xtype, name, size, base_typeid, nfields, class, err)`	nc_inq_user_type
`subroutine nc_inq_var_chunking(ncid, varid, contiguous, chunksizes, err)`	nc_inq_var_chunking
`subroutine nc_inq_var_deflate(ncid, varid, shuffle, deflate, deflate_level, err)`	nc_inq_var_deflate
`subroutine nc_inq_var_endian(ncid, varid, endian, err)`	nc_inq_var_endian
`subroutine nc_inq_var_filter(ncid, varid, filterid, nparams, params, err)`	nc_inq_var_filter
`subroutine nc_inq_var_fletcher32(ncid, varid, fletcher32, err)`	nc_inq_var_fletcher32
`subroutine nc_inq_var_quantize(ncid, varid, quantize_mode, nsd, err)`	nc_inq_var_quantize
`subroutine nc_inq_var_szip(ncid, varid, options_mask, pixels_per_block, err)`	nc_inq_var_szip
`subroutine nc_inq_var_zstandard(ncid, varid, zstandard, zstandard_level, err)`	nc_inq_var_zstandard
`subroutine nc_inq_varid(ncid, name, varid, err)`	nc_inq_varid
`subroutine nc_inq_varids(ncid, nvars, varids, err)`	nc_inq_varids
`subroutine nc_inq_vlen(ncid, xtype, name, datum_size, base_nc_type, err)`	nc_inq_vlen
`subroutine nc_inquire(ncid, ndimensions, nvariables, nattributes, unlimiteddimid, &`	nc_inquire
`subroutine nc_inquire_attribute(ncid, varid, name, xtype, len, attnum, err)`	nc_inquire_attribute
`subroutine nc_inquire_dimension(ncid, dimid, name, len, err)`	nc_inquire_dimension
`subroutine nc_inquire_variable(ncid, varid, name, xtype, ndims, dimids, natts, &`	nc_inquire_variable
`subroutine nc_insert_array_compound(ncid, xtype, name, offset, field_typeid, ndims, &`	nc_insert_array_compound
`subroutine nc_insert_compound(ncid, xtype, name, offset, field_typeid, err)`	nc_insert_compound
`subroutine nc_insert_enum(ncid, xtype, name, value, err)`	nc_insert_enum
`subroutine nc_open(path, mode, ncid, chunksize, cache_size, cache_nelems, &`	nc_open
`subroutine nc_open_mp(path, mode, basepe, chunksizeint, ncid, err)`	nc_open_mp
`subroutine nc_open_par(path, cmode, comm, info, ncid, cache_size, cache_nelems, &`	nc_open_par
`subroutine nc_put_att_any(ncid, varid, name, typeid, length, values, err)`	nc_put_att_any
`subroutine nc_put_var_any(ncid, varid, values, start, count, stride, map, err)`	nc_put_var_any
`subroutine nc_redef(ncid, err)`	nc_redef
`subroutine nc_rename_att(ncid, varid, curname, newname, err)`	nc_rename_att
`subroutine nc_rename_dim(ncid, dimid, newname, err)`	nc_rename_dim
`subroutine nc_rename_grp(grpid, name, err)`	nc_rename_grp
`subroutine nc_rename_var(ncid, varid, newname, err)`	nc_rename_var
`subroutine nc_set_base_pe(ncid, pe, err)`	nc_set_base_pe
`subroutine nc_set_fill(ncid, fillmode, old_mode, err)`	nc_set_fill
`function nc_status_name(status) result(name)`	nc_status_name
`function nc_strerror(status) result(message)`	nc_strerror
`subroutine nc_sync(ncid, err)`	nc_sync
`subroutine nc_var_par_access(ncid, varid, access, err)`	nc_var_par_access

B Constants

Every netcdf-fortran constant is available as NC_<NAME> (for nf90_<name>), with the same type, kind and value: they are renamed on use from the netcdf module, not copied. The groups below are those of the constants table (src/fypp/level0/stdlib_netcdf_constants.fypp).

Type and Value were printed by a program compiled against the library (netcdf-fortran 4.6.2, netcdf-c 4.9.3), so they are exact for that build; integer is the default kind. The usage of a status code is netcdf's own message for it (nc_strerror). First used links to the first section of this guide that uses the constant, in the text or an example; (+n) counts the other sections that use it.

External data types

Constant	Type	Value	Usage	First used
`NC_BYTE`	`integer`	`1`	8-bit signed integer type; Fortran data `integer(int8)`.	5.13 (+2)
`NC_CHAR`	`integer`	`2`	Character type, for text variables and attributes; Fortran data `character(len=*)`.	6.1 (+3)
`NC_COMPOUND`	`integer`	`16`	Class of compound types, returned in `class` by `nc_inq_user_type`.	5.3
`NC_DOUBLE`	`integer`	`6`	64-bit real type; Fortran data `real(dp)`.	1.1 (+10)
`NC_ENUM`	`integer`	`15`	Class of enum types, returned in `class` by `nc_inq_user_type`.	5.3
`NC_FLOAT`	`integer`	`5`	32-bit real type; Fortran data `real(sp)`.	1.5 (+9)
`NC_INT`	`integer`	`4`	32-bit signed integer type; Fortran data `integer(int32)`.	5.2 (+15)
`NC_INT1`	`integer`	`1`	Same as `NC_BYTE` (FORTRAN 77 name).	—
`NC_INT2`	`integer`	`3`	Same as `NC_SHORT` (FORTRAN 77 name).	—
`NC_INT4`	`integer`	`4`	Same as `NC_INT` (FORTRAN 77 name).	—
`NC_INT64`	`integer`	`10`	64-bit signed integer type (NetCDF-4 and CDF5); Fortran data `integer(int64)`.	5.13 (+2)
`NC_OPAQUE`	`integer`	`14`	Class of opaque types, returned in `class` by `nc_inq_user_type`.	5.3
`NC_REAL`	`integer`	`5`	Same as `NC_FLOAT` (FORTRAN 77 name).	—
`NC_REAL4`	`integer`	`5`	Same as `NC_FLOAT`.	—
`NC_REAL8`	`integer`	`6`	Same as `NC_DOUBLE`.	—
`NC_SHORT`	`integer`	`3`	16-bit signed integer type; Fortran data `integer(int16)`.	5.13 (+2)
`NC_STRING`	`integer`	`12`	Variable-length string type (NetCDF-4). Not supported by the data routines; listed by inquiries.	1.8 (+2)
`NC_UBYTE`	`integer`	`7`	8-bit unsigned integer type (NetCDF-4 and CDF5); read and written from signed Fortran integers.	5.13 (+1)
`NC_UINT`	`integer`	`9`	32-bit unsigned integer type (NetCDF-4 and CDF5).	5.13 (+1)
`NC_UINT64`	`integer`	`11`	64-bit unsigned integer type (NetCDF-4 and CDF5).	5.13 (+1)
`NC_USHORT`	`integer`	`8`	16-bit unsigned integer type (NetCDF-4 and CDF5).	5.13 (+1)
`NC_VLEN`	`integer`	`13`	Class of variable-length (vlen) types, returned in `class` by `nc_inq_user_type`.	5.3

Fill values and fill modes

Constant	Type	Value	Usage	First used
`NC_FILL`	`integer`	`0`	Fill mode of `nc_set_fill`: pre-fill new variables with their fill value (the default).	2.12
`NC_FILL_BYTE`	`integer(int8)`	`-127`	Default fill value of `NC_BYTE` variables.	6.1 (+1)
`NC_FILL_CHAR`	`character(len=1)`	`achar(0)`	Default fill value of `NC_CHAR` variables (the NUL character).	6.1 (+1)
`NC_FILL_DOUBLE`	`real(dp)`	`9.9692099683868690E+36`	Default fill value of `NC_DOUBLE` variables.	6.1 (+2)
`NC_FILL_FLOAT`	`real(sp)`	`9.9692100E+36`	Default fill value of `NC_FLOAT` variables.	6.1 (+1)
`NC_FILL_INT`	`integer`	`-2147483647`	Default fill value of `NC_INT` variables.	6.1 (+1)
`NC_FILL_INT1`	`integer(int8)`	`-127`	Same as `NC_FILL_BYTE`.	—
`NC_FILL_INT2`	`integer(int16)`	`-32767`	Same as `NC_FILL_SHORT`.	—
`NC_FILL_REAL`	`real(sp)`	`9.9692100E+36`	Same as `NC_FILL_FLOAT`.	—
`NC_FILL_REAL4`	`real(sp)`	`9.9692100E+36`	Same as `NC_FILL_FLOAT`.	—
`NC_FILL_REAL8`	`real(dp)`	`9.9692099683868690E+36`	Same as `NC_FILL_DOUBLE`.	—
`NC_FILL_SHORT`	`integer(int16)`	`-32767`	Default fill value of `NC_SHORT` variables.	6.1 (+1)
`NC_FILL_UBYTE`	`integer(int16)`	`255`	Default fill value of `NC_UBYTE` variables (in a wider signed kind: Fortran has no unsigned).	—
`NC_FILL_UINT`	`integer(int64)`	`4294967295`	Default fill value of `NC_UINT` variables.	—
`NC_FILL_UINT1`	`integer(int16)`	`255`	Same as `NC_FILL_UBYTE`.	—
`NC_FILL_UINT2`	`integer`	`65535`	Same as `NC_FILL_USHORT`.	—
`NC_FILL_USHORT`	`integer`	`65535`	Default fill value of `NC_USHORT` variables.	—
`NC_NOFILL`	`integer`	`256`	Fill mode of `nc_set_fill`: do not pre-fill (faster when every value is written).	2.7 (+1)

File creation and open modes

Constant	Type	Value	Usage	First used
`NC_64BIT_DATA`	`integer`	`32`	`nc_create`: 64-bit data format, CDF5 (classic model, very large variables, 64-bit and unsigned types).	2.1 (+1)
`NC_64BIT_OFFSET`	`integer`	`512`	`nc_create`: 64-bit offset format (classic model, larger variables).	2.1 (+1)
`NC_ALIGN_CHUNK`	`integer`	`-1`	Alignment value of netcdf-c's `nc__enddef` (align to the chunk size); not used by these wrappers.	—
`NC_CDF5`	`integer`	`32`	Same as `NC_64BIT_DATA`.	—
`NC_CLASSIC_MODEL`	`integer`	`256`	`nc_create`, with `NC_NETCDF4`: NetCDF-4 storage restricted to the classic data model.	2.1 (+2)
`NC_CLOBBER`	`integer`	`0`	`nc_create`: overwrite an existing file (the default).	1.1 (+6)
`NC_DISKLESS`	`integer`	`8`	`nc_create`/`nc_open`: keep the dataset in memory. A created dataset is not written to disk (netcdf-fortran has no `NC_PERSIST`).	2.4 (+1)
`NC_HDF5`	`integer`	`4096`	Same as `NC_NETCDF4` (older name).	—
`NC_LOCK`	`integer`	`1024`	Legacy flag, ignored by current netcdf.	—
`NC_MMAP`	`integer`	`16`	With `NC_DISKLESS`, map the file into memory (deprecated in netcdf-c).	—
`NC_MPIIO`	`integer`	`8192`	`nc_create_par`/`nc_open_par`: parallel access through MPI-IO (NetCDF-4).	8.1 (+1)
`NC_MPIPOSIX`	`integer`	`16384`	Obsolete parallel mode (MPI-POSIX), deprecated in netcdf-c; use `NC_MPIIO`.	—
`NC_NETCDF4`	`integer`	`4096`	`nc_create`: NetCDF-4 (HDF5-based) format, with groups, user types, compression, chunking.	2.1 (+3)
`NC_NOCLOBBER`	`integer`	`4`	`nc_create`: fail with `NC_EEXIST` if the file exists.	2.4
`NC_NOWRITE`	`integer`	`0`	`nc_open`: open read-only (the default).	1.2 (+20)
`NC_PNETCDF`	`integer`	`32768`	`nc_create_par`/`nc_open_par`: parallel access to classic formats through PnetCDF.	8.1 (+1)
`NC_SHARE`	`integer`	`2048`	`nc_create`/`nc_open`: unbuffered I/O, so that concurrent readers see writes at once (classic formats).	2.4 (+1)
`NC_SIZEHINT_DEFAULT`	`integer`	`0`	`chunksize` of `nc_create`/`nc_open`: let the library choose the I/O buffer size.	—
`NC_WRITE`	`integer`	`1`	`nc_open`: open for reading and writing.	1.4 (+51)

File formats (nc_inq_format, nc_inquire formatnum)

Constant	Type	Value	Usage	First used
`NC_FORMAT_64BIT`	`integer`	`2`	Same as `NC_FORMAT_64BIT_OFFSET`.	—
`NC_FORMAT_64BIT_DATA`	`integer`	`5`	Format code of CDF5 (64-bit data) files.	—
`NC_FORMAT_64BIT_OFFSET`	`integer`	`2`	Format code of 64-bit offset files.	2.9
`NC_FORMAT_CDF5`	`integer`	`5`	Same as `NC_FORMAT_64BIT_DATA`.	2.9
`NC_FORMAT_CLASSIC`	`integer`	`1`	Format code of classic files.	2.9
`NC_FORMAT_NETCDF4`	`integer`	`3`	Format code of NetCDF-4 files.	2.9
`NC_FORMAT_NETCDF4_CLASSIC`	`integer`	`4`	Format code of NetCDF-4 classic-model files.	2.9

Storage, filters and parallel access

Constant	Type	Value	Usage	First used
`NC_CHUNK_SEQ`	`integer`	`0`	Legacy chunking-strategy code; not used by current netcdf.	—
`NC_CHUNK_SIZES`	`integer`	`2`	Legacy chunking-strategy code; not used by current netcdf.	—
`NC_CHUNK_SUB`	`integer`	`1`	Legacy chunking-strategy code; not used by current netcdf.	—
`NC_CHUNKED`	`integer`	`0`	`nc_def_var_chunking`: store in chunks (the default for NetCDF-4 variables with an unlimited dimension).	6.6
`NC_COLLECTIVE`	`integer`	`1`	`nc_var_par_access`: every process takes part in each access.	8.3
`NC_COMPACT`	`integer`	`2`	`nc_def_var_chunking`: store the data in the file header (small fixed-size variables).	6.6
`NC_CONTIGUOUS`	`integer`	`1`	`nc_def_var_chunking`: store contiguously (no compression possible).	6.6
`NC_ENDIAN_BIG`	`integer`	`2`	`nc_def_var_endian`: big-endian on disk.	6.2 (+1)
`NC_ENDIAN_LITTLE`	`integer`	`1`	`nc_def_var_endian`: little-endian on disk.	6.2 (+1)
`NC_ENDIAN_NATIVE`	`integer`	`0`	`nc_def_var_endian`: the machine's byte order.	6.2 (+1)
`NC_FLETCHER32`	`integer`	`1`	`nc_def_var_fletcher32`: store a checksum of each chunk.	6.8
`NC_INDEPENDENT`	`integer`	`0`	`nc_var_par_access`: each process accesses on its own (the NetCDF-4 default).	8.3
`NC_NOCHECKSUM`	`integer`	`0`	`nc_def_var_fletcher32`: no checksum.	6.8
`NC_NOQUANTIZE`	`integer`	`0`	`nc_def_var_quantize`: no quantization.	6.9 (+1)
`NC_NOSHUFFLE`	`integer`	`0`	`shuffle` of `nc_def_var_deflate`: no shuffling.	—
`NC_NOTCONTIGUOUS`	`integer`	`0`	Same as `NC_CHUNKED`.	—
`NC_QUANTIZE_BITGROOM`	`integer`	`1`	`nc_def_var_quantize`: BitGroom, keeping `nsd` significant decimal digits.	6.2 (+1)
`NC_QUANTIZE_BITROUND`	`integer`	`3`	`nc_def_var_quantize`: BitRound, keeping `nsd` significant bits.	6.2 (+1)
`NC_QUANTIZE_GRANULARBR`	`integer`	`2`	`nc_def_var_quantize`: Granular BitRound, keeping `nsd` significant decimal digits.	6.2 (+1)
`NC_SHUFFLE`	`integer`	`1`	`shuffle` of `nc_def_var_deflate`: shuffle bytes before compressing.	—
`NC_SZIP_EC_OPTION_MASK`	`integer`	`4`	`nc_def_var_szip`: entropy coding (noisy data).	6.10
`NC_SZIP_NN_OPTION_MASK`	`integer`	`32`	`nc_def_var_szip`: nearest-neighbour preprocessing (smooth data).	6.10

Size limits and special IDs

Constant	Type	Value	Usage	First used
`NC_GLOBAL`	`integer`	`0`	`varid` of global attributes (of the dataset or group, not of a variable).	1.1 (+27)
`NC_MAX_ATTRS`	`integer`	`8192`	Advisory maximum number of attributes of a variable.	—
`NC_MAX_DIMS`	`integer`	`1024`	Advisory maximum number of dimensions of a dataset: size dimension-ID lists with it.	—
`NC_MAX_NAME`	`integer`	`256`	Longest name (dimension, variable, attribute, group, type), in bytes: size buffers with it.	1.3 (+13)
`NC_MAX_VAR_DIMS`	`integer`	`1024`	Maximum number of dimensions of one variable: size `dimids` buffers with it.	6.13
`NC_MAX_VARS`	`integer`	`8192`	Advisory maximum number of variables of a dataset.	1.3
`NC_UNLIMITED`	`integer`	`0`	`len` of `nc_def_dim` for an unlimited (record) dimension.	4 (+2)

Error handling: status codes and verbosity

Constant	Type	Value	Usage	First used
`NC_EATTEXISTS`	`integer`	`-110`	Status: NetCDF: Attempt to create attribute that already exists	—
`NC_EATTMETA`	`integer`	`-107`	Status: NetCDF: Can't open HDF5 attribute	—
`NC_EAXISTYPE`	`integer`	`-65`	Status: NetCDF: Illegal axis type	—
`NC_EBADCHUNK`	`integer`	`-127`	Status: NetCDF: Bad chunk sizes.	6.6
`NC_EBADCLASS`	`integer`	`-120`	Status: NetCDF: Bad class	—
`NC_EBADDIM`	`integer`	`-46`	Status: NetCDF: Invalid dimension ID or name	2.2 (+5)
`NC_EBADFIELD`	`integer`	`-119`	Status: NetCDF: Bad field ID	5.5 (+2)
`NC_EBADGRPID`	`integer`	`-116`	Status: NetCDF: Bad group ID	3.1 (+11)
`NC_EBADID`	`integer`	`-33`	Status: NetCDF: Not a valid ID	2.6 (+58)
`NC_EBADNAME`	`integer`	`-59`	Status: NetCDF: Name contains illegal characters	3.11 (+7)
`NC_EBADTYPE`	`integer`	`-45`	Status: NetCDF: Not a valid data type or _FillValue type mismatch	5.2 (+15)
`NC_EBADTYPID`	`integer`	`-117`	Status: NetCDF: Bad type ID	—
`NC_ECANTCREATE`	`integer`	`-104`	Status: NetCDF: Can't create file	—
`NC_ECANTEXTEND`	`integer`	`-130`	Status: NetCDF: Attempt to extend dataset during NC_INDEPENDENT I/O operation. Use nc_va	—
`NC_ECANTREAD`	`integer`	`-102`	Status: NetCDF: Can't read file	—
`NC_ECANTWRITE`	`integer`	`-103`	Status: NetCDF: Can't write file	—
`NC_ECHAR`	`integer`	`-56`	Status: NetCDF: Attempt to convert between text & numbers	6.15 (+2)
`NC_ECURL`	`integer`	`-67`	Status: NetCDF: libcurl failure	—
`NC_EDAP`	`integer`	`-66`	Status: NetCDF: DAP failure	—
`NC_EDAPCONSTRAINT`	`integer`	`-75`	Status: NetCDF: Malformed or unexpected Constraint	—
`NC_EDAPSVC`	`integer`	`-70`	Status: NetCDF: DAP server error	—
`NC_EDAPURL`	`integer`	`-74`	Status: NetCDF: Malformed URL	—
`NC_EDAS`	`integer`	`-71`	Status: NetCDF: Malformed or inaccessible DAP DAS	—
`NC_EDATADDS`	`integer`	`-73`	Status: NetCDF: Malformed or inaccessible DAP2 DATADDS or DAP4 DAP response	—
`NC_EDDS`	`integer`	`-72`	Status: NetCDF: Malformed or inaccessible DAP2 DDS or DAP4 DMR response	—
`NC_EDIMMETA`	`integer`	`-106`	Status: NetCDF: Can't define dimensional metadata	—
`NC_EDIMSCALE`	`integer`	`-124`	Status: NetCDF: Problem with HDF5 dimscales.	—
`NC_EDIMSIZE`	`integer`	`-63`	Status: NetCDF: Invalid dimension size	4.1
`NC_EDISKLESS`	`integer`	`-129`	Status: NetCDF: Error in using diskless access	—
`NC_EEDGE`	`integer`	`-57`	Status: NetCDF: Start+count exceeds dimension bound	5.18 (+3)
`NC_EEMPTY`	`integer`	`-139`	Status: NetCDF: Attempt to read empty NCZarr map key	—
`NC_EEXIST`	`integer`	`-35`	Status: NetCDF: File exists && NC_NOCLOBBER	2.4
`NC_EFILEMETA`	`integer`	`-105`	Status: NetCDF: Can't add HDF5 file metadata	—
`NC_EFILTER`	`integer`	`-132`	Status: NetCDF: Filter error: bad id or parameters or duplicate filter	6.10 (+1)
`NC_EGLOBAL`	`integer`	`-50`	Status: NetCDF: Action prohibited on NC_GLOBAL varid	—
`NC_EHDFERR`	`integer`	`-101`	Status: NetCDF: HDF error	—
`NC_EINDEFINE`	`integer`	`-39`	Status: NetCDF: Operation not allowed in define mode	2.6 (+3)
`NC_EINMEMORY`	`integer`	`-135`	Status: NetCDF: In-memory File operation failed.	—
`NC_EINVAL`	`integer`	`-36`	Status: NetCDF: Invalid argument	1.8 (+16)
`NC_EINVALCOORDS`	`integer`	`-40`	Status: NetCDF: Index exceeds dimension bound	5.18 (+2)
`NC_EIO`	`integer`	`-68`	Status: NetCDF: I/O failure	—
`NC_ELATEDEF`	`integer`	`-123`	Status: NetCDF: Attempt to define var properties, like deflate, after enddef.	6.3 (+8)
`NC_ELATEFILL`	`integer`	`-122`	Status: NetCDF: Attempt to define fill value when data already exists.	7.1
`NC_EMAPTYPE`	`integer`	`-121`	Status: NetCDF: Mapped access for atomic types only	—
`NC_EMAXATTS`	`integer`	`-44`	Status: NetCDF: NC_MAX_ATTRS exceeded	7.1
`NC_EMAXDIMS`	`integer`	`-41`	Status: NetCDF: NC_MAX_DIMS exceeded	—
`NC_EMAXNAME`	`integer`	`-53`	Status: NetCDF: NC_MAX_NAME exceeded	—
`NC_EMAXVARS`	`integer`	`-48`	Status: NetCDF: NC_MAX_VARS exceeded	—
`NC_EMPI`	`integer`	`-131`	Status: NetCDF: MPI operation failed.	8.1 (+1)
`NC_ENAMEINUSE`	`integer`	`-42`	Status: NetCDF: String match to name in use	2.11 (+14)
`NC_ENCZARR`	`integer`	`-137`	Status: NetCDF: NCZarr error	—
`NC_ENOCOMPOUND`	`integer`	`-109`	Status: NetCDF: Can't create HDF5 compound type	—
`NC_ENODATA`	`integer`	`-69`	Status: NetCDF: Variable has no data	—
`NC_ENOFILTER`	`integer`	`-136`	Status: NetCDF: Filter error: undefined filter encountered	6.12
`NC_ENOGRP`	`integer`	`-125`	Status: NetCDF: No group found.	3.1 (+3)
`NC_ENOMEM`	`integer`	`-61`	Status: NetCDF: Memory allocation (malloc) failure	—
`NC_ENOOBJECT`	`integer`	`-141`	Status: NetCDF: Some object not found	—
`NC_ENOPAR`	`integer`	`-114`	Status: NetCDF: Parallel operation on file opened for non-parallel access	2.4 (+3)
`NC_ENORECVARS`	`integer`	`-55`	Status: NetCDF: nc_rec op when there are no record vars	—
`NC_ENOTATT`	`integer`	`-43`	Status: NetCDF: Attribute not found	5.19 (+5)
`NC_ENOTBUILT`	`integer`	`-128`	Status: NetCDF: Attempt to use feature that was not turned on when netCDF was built.	1.7 (+4)
`NC_ENOTINDEFINE`	`integer`	`-38`	Status: NetCDF: Operation not allowed in data mode	2.7 (+8)
`NC_ENOTNC`	`integer`	`-51`	Status: NetCDF: Unknown file format	2.5
`NC_ENOTNC3`	`integer`	`-113`	Status: NetCDF: Attempting netcdf-3 operation on netcdf-4 file	—
`NC_ENOTNC4`	`integer`	`-111`	Status: NetCDF: Attempting netcdf-4 operation on netcdf-3 file	3.1 (+15)
`NC_ENOTVAR`	`integer`	`-49`	Status: NetCDF: Variable not found	1.6 (+26)
`NC_ENULLPAD`	`integer`	`-134`	Status: NetCDF: File fails strict Null-Byte Header check.	—
`NC_EOBJECT`	`integer`	`-140`	Status: NetCDF: Some object exists when it should not	—
`NC_EPARINIT`	`integer`	`-115`	Status: NetCDF: Error initializing for parallel access	8.1 (+1)
`NC_EPERM`	`integer`	`-37`	Status: NetCDF: Write to read only	2.4 (+17)
`NC_EPLUGIN`	`integer`	`-142`	Status: NetCDF: Unclassified failure in accessing a dynamically loaded plugin	—
`NC_ERANGE`	`integer`	`-60`	Status: NetCDF: Numeric conversion not representable	6.1 (+3)
`NC_ERCFILE`	`integer`	`-133`	Status: NetCDF: RC File Failure.	—
`NC_ES3`	`integer`	`-138`	Status: NetCDF: S3 error	—
`NC_ESTORAGE`	`integer`	`-126`	Status: NetCDF: Cannot specify both contiguous and chunking.	—
`NC_ESTRICTNC3`	`integer`	`-112`	Status: NetCDF: Attempting netcdf-4 operation on strict nc3 netcdf-4 file	5.4 (+11)
`NC_ESTRIDE`	`integer`	`-58`	Status: NetCDF: Illegal stride	6.15 (+1)
`NC_ESTS`	`integer`	`-52`	Status: NetCDF: In Fortran, string too short	—
`NC_ETRANSLATION`	`integer`	`-76`	Status: NetCDF: Untranslatable construct	—
`NC_ETRUNC`	`integer`	`-64`	Status: NetCDF: File likely truncated or possibly corrupted	—
`NC_ETYPDEFINED`	`integer`	`-118`	Status: NetCDF: Type has already been defined and may not be edited	—
`NC_EUNLIMIT`	`integer`	`-54`	Status: NetCDF: NC_UNLIMITED size already in use	4.1
`NC_EUNLIMPOS`	`integer`	`-47`	Status: NetCDF: NC_UNLIMITED in the wrong index	6.2
`NC_EVARMETA`	`integer`	`-108`	Status: NetCDF: Problem with variable metadata.	—
`NC_EVARSIZE`	`integer`	`-62`	Status: NetCDF: One or more variable sizes violate format constraints	2.7
`NC_FATAL`	`integer`	`1`	Option of the legacy `nf_set_opts` (stop on errors); not used by these wrappers.	—
`NC_NOERR`	`integer`	`0`	Status: No error	1.6 (+75)
`NC_VERBOSE`	`integer`	`2`	Option of the legacy `nf_set_opts` (print errors); not used by these wrappers.	—

netcdf

Constant	Type	Value	Usage	First used

Generated by scripts/level0_guide/build.py from the stdlib_NetCDF sources. Layout after Unidata's NetCDF Fortran 90 Interface Guide.