NetCDF User's Guide - ncattget and NCAGT(C)

Go to the previous, next section.

Get Attribute's Values

The function ncattget (or NCAGT or NCAGTC for FORTRAN) gets the value(s) of a netCDF attribute, given its variable ID and name.

In case of an error, ncattget returns -1; NCAGT returns a nonzero value in rcode. Possible causes of errors include:

The variable ID is invalid for the specified netCDF file.
The specified attribute does not exist.
The specified netCDF ID does not refer to an open netCDF file.

ncattget: C Interface

int ncattget(int ncid, int varid, const char* name, void* value);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
varid: Variable ID of the attribute's variable, or NC_GLOBAL for a global attribute.
name: Attribute name.
value: Returned attribute values. All elements of the vector of attribute values are returned, so you must allocate enough space to hold them. If you don't know how much space to reserve, call ncattinq first to find out the length of the attribute.

Here is an example using ncattget to determine the values of a variable attribute named valid_range for a netCDF variable named rh and a global attribute named title in an existing netCDF file named `foo.nc'. In this example, it is assumed that we don't know how many values will be returned, but that we do know the types of the attributes. Hence, to allocate enough space to store them, we must first inquire about the length of the attributes.

#include "netcdf.h"
   ...
int  ncid;                 /* netCDF ID */
int  rh_id;                /* variable ID */
nc_type vr_type, t_type;   /* attribute types */
int  vr_len, t_len;        /* attribute lengths */
double *vr_val;            /* ptr to attribute values */
char *title;               /* ptr to attribute values */
extern char *malloc();     /* memory allocator */

   ...
ncid = ncopen("foo.nc", NC_NOWRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
/* find out how much space is needed for attribute values */
ncattinq (ncid, rh_id, "valid_range", &vr_type, &vr_len);
ncattinq (ncid, NC_GLOBAL, "title", &t_type, &t_len);

/* allocate required space before retrieving values */
vr_val = (double *) malloc(vr_len * nctypelen(vr_type));
title = (char *) malloc(t_len * nctypelen(t_type));

/* get attribute values */
ncattget(ncid, rh_id, "valid_range", (void *)vr_val);
ncattget(ncid, NC_GLOBAL, "title", (void *)title);
   ...

NCAGT, NCAGTC: FORTRAN Interface

      SUBROUTINE NCAGT (INTEGER NCID, INTEGER VARID,
     +                  CHARACTER*(*) ATTNAM, type VALUES,
     +                  INTEGER RCODE)

      SUBROUTINE NCAGTC (INTEGER NCID, INTEGER VARID,
     +                  CHARACTER*(*) ATTNAM, CHARACTER*(*) STRING,
     +                  INTEGER LENSTR, INTEGER RCODE)

There are two FORTRAN subroutines, NCAGT and NCAGTC, for retrieving attribute values. The first is for attributes of numeric type, and the second is for attributes of character-string type.

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
VARID: Variable ID of the attribute's variable, or NCGLOBAL for a global attribute.
ATTNAM: Attribute name.
VALUES: Returned attribute values. All elements of the vector of attribute values are returned, so you must provide enough space to hold them. If you don't know how much space to reserve, call NCAINQ first to find out the length of the attribute. Warning: neither the compiler nor the netCDF software can detect if the wrong type of data is used.
STRING: In NCAGTC, the character-string value of the attribute.
LENSTR: In NCAGTC, the total declared length (in characters) of the STRING parameter in the caller. Note that this is not necessarily the same as the value returned by the FORTRAN LEN function, because an array argument may be provided. NCAGTC will check to make sure the requested data will fit in LENSTR characters.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCAGT to determine the values of an attribute named valid_range for a netCDF variable named rh and a global attribute named title in an existing netCDF file named `foo.nc'. In this example, it is assumed that we don't know how many values will be returned, so we first inquire about the length of the attributes to make sure we have enough space to store them:

      INCLUDE 'netcdf.inc'
         ...
      PARAMETER (MVRLEN=3) ! max number of "valid_range" values
      PARAMETER (MTLEN=80) ! max length of "title" attribute
      INTEGER  NCID, RCODE
      INTEGER  RHID               ! variable ID
      INTEGER  VRTYPE, TTYPE      ! attribute types
      INTEGER  VRLEN, TLEN        ! attribute lengths
      DOUBLE PRECISION VRVAL(MVRLEN) ! vr attribute values
      CHARACTER*80 TITLE          ! title attribute values
         ...
      NCID = NCOPN ('foo.nc', NCWRITE, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE) ! get ID
         ...
* find out attribute lengths, to make sure we have enough space
      CALL NCAINQ (NCID, RHID, 'valid_range', VRTYPE, VRLEN,
     +             RCODE)
      CALL NCAINQ (NCID, NCGLOBAL, 'title', TTYPE, TLEN,
     +             RCODE)
* get attribute values, if not too big
      IF (VRLEN > MVRLEN) THEN
          WRITE (*,*) 'valid_range attribute too big!'
          CALL EXIT
      ELSE
          CALL NCAGT (NCID, RHID, 'valid_range', VRVAL, RCODE)
      ENDIF
      IF (TLEN > MTLEN) THEN
          WRITE (*,*) 'title attribute too big!'
          CALL EXIT
      ELSE
          CALL NCAGTC (NCID, NCGLOBAL, 'title', TITLE, MTLEN, RCODE)
      ENDIF

Go to the previous, next section.