5.4 Get Attribute’s Values:ncmpi_get_att_<type>

Members of the ncmpi_get_att_<type> family of functions get the value(s) of a netCDF attribute, given its variable ID and name.

Data types

Operational Mode

These APIs are independent subroutines.

These APIs can be called while the file is in either define or data mode (collective or independent).

Usage

int ncmpi_get_att        (int         ncid,
                          int         varid,
                          const char *name,
                          void       *buf);

int ncmpi_get_att_<type>(int         ncid,
                          int         varid,
                          const char *name,
                          <C type>  *buf);

ncid

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.

varid

Variable ID of the attribute’s variable, or NC_GLOBAL for a global attribute.

name

Attribute name.

buf

Pointer to location for returned attribute value(s). All elements of the vector of attribute values are returned, so you must allocate enough space to hold them. For attributes of type NC_CHAR, you should not assume that the returned values include a trailing zero byte; they won’t if the attribute was stored without a trailing zero byte, for example from a FORTRAN program. Before using the value as a C string, make sure it is null-terminated. If you don’t know how much space to reserve, call ncmpi_inq_attlen first to find out the length of the attribute.

Return Error Codes

ncmpi_get_att_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• NC_EBADID: The specified netCDF ID does not refer to an opened netCDF file.
• NC_ENOTVAR: The input or output variable ID is invalid for the specified netCDF file.
• NC_EBADNAME: Name contains illegal characters.
• NC_EMAXNAME: NC_MAX_NAME exceeded.
• NC_ENOMEM: Out of memory.
• NC_ENOTATT: The specified attribute does not exist in ncid.
• NC_ECHAR: Attempt to convert numerical values to or from text data.
• NC_EINVAL: buf is NULL.
• NC_ERANGE: One or more elements of the external attribute are out of the range of values representable by the internal data type of read buffer, buf.

Example

Here is an example using ncmpi_get_att_double 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 <pnetcdf.h>
   ... 
int  status;               /* error status */
int  ncid;                 /* netCDF ID */
int  rh_id;                /* variable ID */
MPI_Offset  vr_len, t_len; /* attribute lengths */
double *vr_val;            /* pointer to attribute values */
char *title;               /* pointer to attribute values */
extern char *malloc();     /* memory allocator */

   ... 
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL, &ncid);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_inq_varid(ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
   ... 
/* find out how much space is needed for attribute values */
status = ncmpi_inq_attlen(ncid, rh_id, "valid_range", &vr_len);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_attlen(ncid, NC_GLOBAL, "title", &t_len);
if (status != NC_NOERR) handle_error(status);

/* allocate required space before retrieving values */
vr_val = (double *) malloc(vr_len * sizeof(double));
title = (char *) malloc(t_len + 1);  /* + 1 for trailing null */

/* get attribute values */
status = ncmpi_get_att_double(ncid, rh_id, "valid_range", vr_val);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_get_att_text(ncid, NC_GLOBAL, "title", title);
if (status != NC_NOERR) handle_error(status);
title[t_len] = '\0';       /* null terminate */
   ... 

Full example C program

• global_attributes.c
• put_vara.c
• The above programs are available in all PnetCDF releases under directory examples/C.