Unidata - To provide the data services, tools, and cyberinfrastructure leadership that advance Earth system science, enhance educational opportunities, and broaden participation.

DataToolsCommunityDownloadsSupportProjectsAbout Us

•

Go to the first, previous, next, last section, table of contents.

Attributes

Attributes may be associated with each netCDF variable to specify such properties as units, special values, maximum and minimum valid values, scaling factors, and offsets. Attributes for a netCDF file are defined when the file is first created, while the netCDF file is in define mode. Additional attributes may be added later by reentering define mode. A netCDF attribute has a netCDF variable to which it is assigned, a name, a type, a length, and a sequence of one or more values. An attribute is designated by its variable ID and name, except in one case (ncattname or NCANAM in FORTRAN), where attributes are designated by variable ID and number because their names are unknown.

The attributes associated with a variable are typically defined right after the variable is created, while still in define mode. The data type, length, and value of an attribute may be changed even when in data mode, as long as the changed attribute requires no more space than the attribute as originally defined.

It is also possible to have attributes which are not associated with any variable. These are called global attributes and are identified by using NC_GLOBAL as a variable pseudo-ID. Global attributes are usually related to the netCDF file as a whole and may be used for purposes such as providing a title or processing history for a netCDF dataset.

Operations supported on attributes are:

Create an attribute, given its variable ID, name, data type, length, and value.
Get attribute's data type and length from its variable ID and name.
Get attribute's value from its variable ID and name.
Copy attribute from one netCDF variable to another.
Get name of attribute from its number.
Rename an attribute.
Delete an attribute.

Attribute Conventions

Names commencing with underscore (`_') are reserved for use by the netCDF library. Most generic applications that process netCDF files assume standard attribute conventions and it is strongly recommended that these be followed unless there are good reasons for not doing so. Below we list the names and meanings of recommended standard attributes that have proven useful. Note that some of these (e.g. units, valid_range, scale_factor) assume numeric data and should not be used with character data.

units: A character string that specifies the units used for the variable's data. Unidata has developed a freely-available library of routines to convert between character string and binary forms of unit specifications and to perform various useful operations on the binary forms. This library is used in some netCDF applications. Using the recommended units syntax permits data represented in conformable units to be automatically converted to common units for arithmetic operations. See section Units, for more information.
long_name: A long descriptive name. This could be used for labeling plots, for example. If a variable has no long_name attribute assigned, the variable name should be used as a default.
valid_min: A scalar specifying the minimum valid value for this variable.
valid_max: A scalar specifying the maximum valid value for this variable.
valid_range: A vector of two numbers specifying the minimum and maximum valid values for this variable, equivalent to specifying values for both valid_min and valid_max attributes. Any of these attributes define the valid range. The attribute valid_range must not be defined if either valid_min or valid_max is defined. Generic applications should treat values outside the valid range as missing. The type of each valid_range, valid_min and valid_max attribute should match the type of its variable (except that for byte data, these can be of a signed integral type to specify the intended range). If neither valid_min, valid_max nor valid_range is defined then generic applications should define a valid range as follows. If the data type is byte and _FillValue is not explicitly defined, then the valid range should include all possible values. Otherwise, the valid range should exclude the the _FillValue (whether defined explicitly or by default) as follows. If the _FillValue is positive then it defines a valid maximum, otherwise it defines a valid minimum. For integer types, there should be a difference of 1 between the _FillValue and this valid minimum or maximum. For floating point types, the difference should be twice the minimum possible (1 in the least significant bit) to allow for rounding error.
scale_factor: If present for a variable, the data are to be multiplied by this factor after the data are read by the application that accesses the data.
add_offset: If present for a variable, this number is to be added to the data after it is read by the application that accesses the data. If both scale_factor and add_offset attributes are present, the data are first scaled before the offset is added. The attributes scale_factor and add_offset can be used together to provide simple data compression to store low-resolution floating-point data as small integers in a netCDF file. When scaled data are written, the application should first subtract the offset and then divide by the scale factor. When scale_factor and add_offset are used for packing, the associated variable (containing the packed data) is typically of type byte or short, whereas the unpacked values are intended to be of type float or double. The attributes scale_factor and add_offset should both be of the type intended for the unpacked data, e.g. float or double.
_FillValue: The _FillValue attribute specifies the fill value used to pre-fill disk space allocated to the variable. Such pre-fill occurs unless nofill mode is set using ncsetfill (or NCSFIL for FORTRAN). See section Set Fill Mode for Writes: ncsetfill and NCSFIL, for details. The fill value is returned when reading values that were never written. If _FillValue is defined then it should be scalar and of the same type as the variable. It is not necessary to define your own _FillValue attribute for a variable if the default fill value for the type of the variable is adequate. However, use of the default fill value for data type byte is not recommended. Note that if you change the value of this attribute, the changed value applies only to subsequent writes; previously written data are not changed. Generic applications often need to write a value to represent undefined or missing values. The fill value provides an appropriate value for this purpose because it is normally outside the valid range and therefore treated as missing when read by generic applications. It is legal (but not recommended) for the fill value to be within the valid range. See section Fill Values, for more information.
missing_value: This attribute is not treated in any special way by the library or conforming generic applications, but is often useful documentation and may be used by specific applications. The missing_value attribute can be a scalar or vector containing values indicating missing data. These values should all be outside the valid range so that generic applications will treat them as missing.
signedness: Deprecated attribute, originally designed to indicate whether byte values should be treated as signed or unsigned. The attributes valid_min and valid_max may be used for this purpose. For example, if you intend that a byte variable store only non-negative values, you can use valid_min = 0 and valid_max = 255. This attribute is ignored by the netCDF library.
C_format: A character array providing the format that should be used by C applications to print values for this variable. For example, if you know a variable is only accurate to three significant digits, it would be appropriate to define the C_format attribute as "%.3g". The ncdump utility program uses this attribute for variables for which it is defined. The format applies to the scaled (internal) type and value, regardless of the presence of the scaling attributes scale_factor and add_offset.
FORTRAN_format: A character array providing the format that should be used by FORTRAN applications to print values for this variable. For example, if you know a variable is only accurate to three significant digits, it would be appropriate to define the FORTRAN_format attribute as "(G10.3)".
title: A global attribute that is a character array providing a succinct description of what is in the dataset.
history: A global attribute for an audit trail. This is a character array with a line for each invocation of a program that has modified the file. Well-behaved generic netCDF applications should append a line containing: date, time of day, user name, program name and command arguments.
Conventions: If present, `Conventions' is a global attribute that is a character array for the name of the conventions followed by the file, in the form of a string that is interpreted as a directory name relative to a directory that is a repository of documents describing sets of discipline-specific conventions. This permits a hierarchical structure for conventions and provides a place where descriptions and examples of the conventions may be maintained by the defining institutions and groups. The conventions directory name is currently interpreted relative to the directory pub/netcdf/Conventions/ on the host machine ftp.unidata.ucar.edu. Alternatively, a full URL specification may be used to name a WWW site where documents that describe the conventions are maintained. For example, if a group named NUWG agrees upon a set of conventions for dimension names, variable names, required attributes, and netCDF representations for certain discipline-specific data structures, they may store a document describing the agreed-upon conventions in a file in the NUWG/ subdirectory of the Conventions directory. Files that followed these conventions would contain a global Conventions attribute with value "NUWG". Later, if the group agrees upon some additional conventions for a specific subset of NUWG data, for example time series data, the description of the additional conventions might be stored in the NUWG/Time_series/ subdirectory, and files that adhered to these additional conventions would use the global Conventions attribute with value "NUWG/Time_series", implying that this file adheres to the NUWG conventions and also to the additional NUWG time-series conventions.

Create an Attribute: ncattput, NCAPT, and NCAPTC

The function ncattput (or NCAPT or NCAPTC for FORTRAN) adds or changes a variable attribute or global attribute of an open netCDF file. If this attribute is new, or if the space required to store the attribute is greater than before, the netCDF file must be in define mode.

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

The variable ID is invalid for the specified netCDF file.
The specified netCDF type is invalid.
The specified length is negative.
The specified open netCDF file is in data mode and the specified attribute would expand.
The specified open netCDF file is in data mode and the specified attribute does not already exist.
The specified netCDF ID does not refer to an open netCDF file.

C Interface: ncattput

int ncattput(int ncid, int varid, const char* name, nc_type datatype,
             int len, const void* values);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
varid: Variable ID of the variable to which the attribute will be assigned or NC_GLOBAL for a global attribute.
name: Attribute name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant. Attribute name conventions are assumed by some netCDF generic applications, e.g., units as the name for a string attribute that gives the units for a netCDF variable. See section Attribute Conventions, for examples of attribute conventions.
datatype: One of the set of predefined netCDF data types. The type of this parameter, nc_type, is defined in the netCDF header file. The valid netCDF data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_LONG, NC_FLOAT, and NC_DOUBLE.
len: Number of values provided for the attribute.
values: Pointer to one or more data values. The pointer is declared to be of the type void * because it can point to data of any of the basic netCDF types. The data should be of the appropriate type for the netCDF attribute. Warning: neither the compiler nor the netCDF software can detect whether the wrong type of data is used.

Here is an example using ncattput to add a variable attribute named valid_range for a netCDF variable named rh and a global attribute named title to an existing netCDF file named `foo.nc':

#include <netcdf.h>
   ...
int  ncid;                         /* netCDF ID */
int  rh_id;                        /* variable ID */
static double rh_range[] = {0.0, 100.0};  /* attribute vals */
static char title[] = "example netCDF file";
   ...
ncid = ncopen("foo.nc", NC_WRITE);
   ...
ncredef(ncid);                    /* enter define mode */
rh_id = ncvarid (ncid, "rh");
   ...
ncattput (ncid, rh_id, "valid_range", NC_DOUBLE, 2, rh_range);
ncattput (ncid, NC_GLOBAL, "title", NC_CHAR, strlen(title)+1,
          title);
   ...
ncendef(ncid);                    /* leave define mode */

FORTRAN Interface: NCAPT, NCAPTC

      SUBROUTINE NCAPT (INTEGER NCID, INTEGER VARID,
     +                  CHARACTER*(*) ATTNAM, INTEGER ATTYPE,
     +                  INTEGER ATTLEN, type VALUE,
     +                  INTEGER RCODE)

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

There are two FORTRAN subroutines, NCAPT and NCAPTC, for creating attributes. 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.
ATTNAM: Attribute name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant. Attribute name conventions are assumed by some netCDF generic applications, e.g., units as the name for a string attribute that gives the units for a netCDF variable. A table of conventional attribute names is presented in the earlier chapter on the netCDF interface.
ATTYPE: One of the set of predefined netCDF data types. The valid netCDF data types are NCBYTE, NCCHAR, NCSHORT, NCLONG, NCFLOAT, and NCDOUBLE. For NCAPTC, this should always be NCCHAR (a blemish in the interface, but required for backward compatibility).
ATTLEN: In NCAPT, the number of numeric values provided for the attribute.
VALUE: In NCAPT, an array of ATTLEN data values. The data should be of the appropriate type for the netCDF attribute. Warning: neither the compiler nor the netCDF software can detect if the wrong type of data is used.
STRING: In NCAPTC, the character-string value of the attribute.
LENSTR: In NCAPTC, the total declared length (in characters) of the STRING parameter. Note that this is not necessarily the same as the value returned by the FORTRAN LEN function, because an array argument may be provided.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCAPT to add a variable attribute named valid_range for a netCDF variable named rh and a global attribute named title to an existing netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID, RCODE
      INTEGER  RHID               ! variable ID
      DOUBLE RHRNGE(2)
      DATA RHRNGE /0.0D0, 100.0D0/
         ...
      NCID = NCOPN ('foo.nc', NCWRITE, RCODE)
         ...
      CALL NCREDF (NCID, RCODE)     ! enter define mode
      RHID = NCVID (NCID, 'rh', RCODE)! get ID
         ...
      CALL NCAPT (NCID, RHID, 'valid_range', NCDOUBLE, 2,
     +            RHRNGE, RCODE)
      CALL NCAPTC (NCID, NCGLOBAL, 'title', NCCHAR, 19,
     +            'example netCDF file', RCODE)
         ...
      CALL NCENDF (NCID, RCODE)     ! leave define mode

Get Information about an Attribute: ncattinq and NCAINQ

The function ncattinq (or NCAINQ for FORTRAN) returns information about a netCDF attribute, given its variable ID and name. The information returned is the type and length of the attribute.

In case of an error, ncattinq returns -1; NCAINQ 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.

C Interface: ncattinq

int ncattinq(int ncid, int varid, const char* name,
             nc_type* datatype, int* len);

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.
datatype: Returned attribute type, one of the set of predefined netCDF data types. The type of this parameter, nc_type, is defined in the netCDF header file. The valid netCDF data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_LONG, NC_FLOAT, and NC_DOUBLE. If this parameter is given as `0' (a null pointer), no type will be returned so no variable to hold the type needs to be declared.
len: Returned number of values currently stored in the attribute. For attributes of type NC_CHAR, you should not assume that this includes a trailing zero byte; it doesn'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 this parameter is given as `0' (a null pointer), no length will be returned so no variable to hold this information needs to be declared.

Here is an example using ncattinq to find out the type and length 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':

#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 *'

   ...
ncid = ncopen("foo.nc", NC_NOWRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
ncattinq (ncid, rh_id, "valid_range", &vr_type, &vr_len);
ncattinq (ncid, NC_GLOBAL, "title", &t_type, &t_len);
   ...

FORTRAN Interface: NCAINQ

      SUBROUTINE NCAINQ (INTEGER NCID, INTEGER VARID,
     +                   CHARACTER*(*) ATTNAM, INTEGER ATTYPE,
     +                   INTEGER ATTLEN,INTEGER RCODE)

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.
ATTYPE: Returned attribute type, one of the set of predefined netCDF data types. The valid netCDF data types are NCBYTE, NCCHAR, NCSHORT, NCLONG, NCFLOAT, and NCDOUBLE.
ATTLEN: Returned number of values currently stored in the attribute. For a string-valued attribute, this is the number of characters in the string.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCAINQ to add a variable attribute named valid_range for a netCDF variable named rh and a global attribute named title to an existing netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID, RCODE
      INTEGER  RHID               ! variable ID
      INTEGER  VRTYPE, TTYPE      ! attribute types
      INTEGER  VRLEN, TLEN        ! attribute lengths
         ...
      NCID = NCOPN ('foo.nc', NCNOWRIT, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)! get ID
         ...
      CALL NCAINQ (NCID, RHID, 'valid_range', VRTYPE, VRLEN,
     +             RCODE)
      CALL NCAINQ (NCID, NCGLOBAL, 'title', TTYPE, TLEN,
     +             RCODE)

Get Attribute's Values: ncattget and NCAGT(C)

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.

C Interface: ncattget

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. 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.

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 + 1); /* + 1 for trailing null byte */

/* get attribute values */
ncattget(ncid, rh_id, "valid_range", vr_val);
ncattget(ncid, NC_GLOBAL, "title", title);
title[t_len] = '\0';                /* null terminate */
   ...

FORTRAN Interface: NCAGT, NCAGTC

      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 .GT. MVRLEN) THEN
          WRITE (*,*) 'valid_range attribute too big!'
          CALL EXIT
      ELSE
          CALL NCAGT (NCID, RHID, 'valid_range', VRVAL, RCODE)
      ENDIF
      IF (TLEN .GT. MTLEN) THEN
          WRITE (*,*) 'title attribute too big!'
          CALL EXIT
      ELSE
          CALL NCAGTC (NCID, NCGLOBAL, 'title', TITLE, MTLEN, RCODE)
      ENDIF

Copy Attribute from One NetCDF to Another: ncattcopy and NCACPY

The function ncattcopy (or NCACPY for FORTRAN) copies an attribute from one open netCDF file to another. It can also be used to copy an attribute from one variable to another within the same netCDF.

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

The input or output variable ID is invalid for the specified netCDF file.
The specified attribute does not exist.
The output netCDF is not in define mode and the attribute is new for the output file is larger than the existing attribute.
The input or output netCDF ID does not refer to an open netCDF file.

C Interface: ncattcopy

int ncattcopy(int incdf, int invar, const char* name, int outcdf, int outvar);

incdf: The netCDF ID of an input netCDF file from which the attribute will be copied, returned from a previous call to ncopen or nccreate.
invar: ID of the variable in the input netCDF file from which the attribute will be copied, or NC_GLOBAL for a global attribute.
name: Name of the attribute in the input netCDF file to be copied.
outcdf: The netCDF ID of the output netCDF file to which the attribute will be copied, returned from a previous call to ncopen or nccreate. It is permissible for the input and output netCDF IDs to be the same. The output netCDF file should be in define mode if the attribute to be copied does not already exist for the target variable, or if it would cause an existing target attribute to grow.
outvar: ID of the variable in the output netCDF file to which the attribute will be copied, or NC_GLOBAL to copy to a global attribute.

Here is an example using ncattcopy to copy the variable attribute units from the variable rh in an existing netCDF file named `foo.nc' to the variable avgrh in another existing netCDF file named `bar.nc', assuming that the variable avgrh already exists, but does not yet have a units attribute:

#include <netcdf.h>
   ...
int  ncid1, ncid2;       /* netCDF IDs */
int  rh_id, avgrh_id;      /* variable IDs */
   ...
ncid1 = ncopen("foo.nc", NC_NOWRITE);
ncid2 = ncopen("bar.nc", NC_WRITE);
   ...
rh_id = ncvarid (ncid1, "rh");
avgrh_id = ncvarid (ncid2, "avgrh");
   ...
ncredef(ncid2);           /* enter define mode */
/* copy variable attribute from "rh" to "avgrh" */
ncattcopy(ncid1, rh_id, "units", ncid2, avgrh_id);
   ...
ncendef(ncid2);           /* leave define mode */

FORTRAN Interface: NCACPY

      SUBROUTINE NCACPY (INTEGER INCDF, INTEGER INVAR,
     +                   CHARACTER*(*) ATTNAM, INTEGER OUTCDF,
     +                   INTEGER OUTVAR, INTEGER RCODE)

INCDF: The netCDF ID of an input netCDF file from which the attribute will be copied, returned from a previous call to NCOPN or NCCRE.
INVAR: ID of the variable in the input netCDF file from which the attribute will be copied, or NCGLOBAL for a global attribute.
ATTNAM: Name of the attribute in the input netCDF file to be copied.
OUTCDF: The netCDF ID of the output netCDF file to which the attribute will be copied, returned from a previous call to NCOPN or NCCRE. It is permissible for the input and output netCDF IDs to be the same. The output netCDF file should be in define mode if the attribute to be copied does not already exist for the target variable, or if it would cause an existing target attribute to grow.
OUTVAR: ID of the variable in the output netCDF file to which the attribute will be copied, or NCGLOBAL to copy to a global attribute.

Here is an example using NCACPY to copy the variable attribute units from the variable rh in an existing netCDF file named `foo.nc' to the variable avgrh in another existing netCDF file named `bar.nc', assuming that the variable avgrh already exists, but does not yet have a units attribute:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID1, NCID2     ! netCDF IDs
      INTEGER  RHID, AVRHID       ! variable IDs
         ...
      NCID1 = NCOPN ('foo.nc', NCNOWRIT, RCODE)
      NCID2 = NCOPN ('bar.nc', NCWRITE, RCODE)
         ...
      RHID = NCVID (NCID1, 'rh', RCODE)
      AVRHID = NCVID (NCID2, 'avgrh', RCODE)
         ...
      CALL NCREDF (NCID2, RCODE)  ! enter define mode
* copy variable attribute from "rh" to "avgrh"
      CALL NCACPY (NCID1, RHID, 'units', NCID2, AVRHID, RCODE)
         ...
      CALL NCENDF (NCID2, RCODE)  ! leave define mode

Get Name of Attribute from Its Number: ncattname and NCANAM

The function ncattname (or NCANAM for FORTRAN) gets the name of an attribute, given its variable ID and number. This function is useful in generic applications that need to get the names of all the attributes associated with a variable, since attributes are accessed by name rather than number in all other attribute functions. The number of an attribute is more volatile than the name, since it can change when other attributes of the same variable are deleted. This is why an attribute number is not called an attribute ID.

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

The specified variable ID is not valid.
The specified attribute number is negative or more than the number of attributes defined for the specified variable.
The specified attribute does not exist.
The specified netCDF ID does not refer to an open netCDF file.

C Interface: ncattname

int ncattname (int ncid, int varid, int attnum, char* name);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
varid: ID of the attribute's variable, or NC_GLOBAL for a global attribute.
attnum: Number of the attribute. The attributes for each variable are numbered from 0 (the first attribute) to nvatts-1, where nvatts is the number of attributes for the variable, as returned from a call to ncvarinq.
name: Returned attribute name. The caller must allocate space for the returned name. The maximum possible length, in characters, of an attribute name is given by the predefined constant MAX_NC_NAME. If the name parameter is given as 0 (a null pointer), no name will be returned and no space needs to be allocated.

Here is an example using ncattname to determine the name of the first attribute of the variable rh in an existing netCDF file named `foo.nc':

#include <netcdf.h>
   ...
int  ncid;        /* netCDF ID */
int  rh_id;       /* variable ID */
char attname[MAX_NC_NAME];  /* maximum-size attribute name */
   ...
ncid = ncopen("foo.nc", NC_NOWRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
/* get name of first attribute (number 0) */
ncattname(ncid, rh_id, 0, attname);

FORTRAN Interface: NCANAM

      SUBROUTINE NCANAM (INTEGER NCID, INTEGER VARID,
     +                   INTEGER ATTNUM, CHARACTER*(*) ATTNAM,
     +                   INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
VARID: ID of the attribute's variable, or NCGLOBAL for a global attribute.
ATTNUM: Number of the attribute. The attributes for each variable are numbered from 1 (the first attribute) to NVATTS, where NVATTS is the number of attributes for the variable, as returned from a call to NCVINQ.
ATTNAM: Returned attribute name. The caller must allocate space for the returned name. The maximum possible length, in characters, of an attribute name is given by the predefined constant MAXNCNAM.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCANAM determine the name of the first attribute of the variable rh in an existing netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID     ! netCDF ID
      INTEGER  RHID      ! variable ID
* 31 in the following should be MAXNCNAM
      CHARACTER*31 ATTNAM
         ...
      NCID = NCOPN ('foo.nc', NCNOWRIT, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)
         ...
* get name of first attribute (number 1)
      CALL NCANAM (NCID, RHID, 1, ATTNAM, RCODE)

Rename an Attribute: ncattrename and NCAREN

The function ncattrename (or NCAREN for FORTRAN) changes the name of an attribute. If the new name is longer than the original name, the netCDF file must be in define mode. You cannot rename an attribute to have the same name as another attribute of the same variable.

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

The specified variable ID is not valid.
The new attribute name is already in use for another attribute of the specified variable.
The specified netCDF file is in data mode and the new name is longer than the old name.
The specified attribute does not exist.
The specified netCDF ID does not refer to an open netCDF file.

C Interface: ncattrename

int ncattrename (int ncid, int varid, const char* name, const char* newname);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate
varid: ID of the attribute's variable, or NC_GLOBAL for a global attribute
name: The original attribute name.
newname: The new name to be assigned to the specified attribute. If the new name is longer than the old name, the netCDF file must be in define mode.

Here is an example using ncattrename to rename the variable attribute units to Units for a variable rh in an existing netCDF file named `foo.nc':

#include <netcdf.h>
   ...
int  ncid;        /* netCDF ID */
int  rh_id;       /* variable id */
   ...
ncid = ncopen("foo.nc", NC_NOWRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
/* rename attribute */
ncattrename(ncid, rh_id, "units", "Units");

FORTRAN Interface: NCAREN

      SUBROUTINE NCAREN (INTEGER NCID, INTEGER VARID,
     +                   CHARACTER*(*) ATTNAM,
     +                   CHARACTER*(*) NEWNAM, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE
VARID: ID of the attribute's variable, or NCGLOBAL for a global attribute
ATTNAM: The original attribute name.
NEWNAM: The new name to be assigned to the specified attribute. If the new name is longer than the old name, the netCDF file must be in define mode.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCAREN to rename the variable attribute units to Units for a variable rh in an existing netCDF file named `foo.nc':

      INCLUDE "netcdf.inc"
         ...
      INTEGER  NCID     ! netCDF ID
      INTEGER  RHID      ! variable ID
         ...
      NCID = NCOPN ("foo.nc", NCNOWRIT, RCODE)
         ...
      RHID = NCVID (NCID, "rh", RCODE)
         ...
* rename attribute
      CALL NCAREN (NCID, RHID, "units", "Units", RCODE)

Delete an Attribute: ncattdel and NCADEL

The function ncattdel (or NCADEL for FORTRAN) deletes a netCDF attribute from an open netCDF file. The netCDF file must be in define mode.

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

The specified variable ID is not valid.
The specified netCDF file is in data mode.
The specified attribute does not exist.
The specified netCDF ID does not refer to an open netCDF file.

C Interface: ncattdel

int ncattdel (int ncid, int varid, const char* name);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
varid: ID of the attribute's variable, or NC_GLOBAL for a global attribute.
name: The name of the attribute to be deleted.

Here is an example using ncattdel to delete the variable attribute Units for a variable rh in an existing netCDF file named `foo.nc':

#include <netcdf.h>
   ...
int  ncid;        /* netCDF ID */
int  rh_id;       /* variable ID */
   ...
ncid = ncopen("foo.nc", NC_WRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
/* delete attribute */
ncredef(ncid);                  /* enter define mode */
ncattdel(ncid, rh_id, "Units");
ncendef(ncid);                  /* leave define mode */

FORTRAN Interface: NCADEL

      SUBROUTINE NCADEL (INTEGER NCID, INTEGER VARID,
     +                   CHARACTER*(*) ATTNAM, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
VARID: ID of the attribute's variable, or NCGLOBAL for a global attribute.
ATTNAM: The original attribute name.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCADEL to delete the variable attribute Units for a variable rh in an existing netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID     ! netCDF ID
      INTEGER  RHID      ! variable ID
         ...
      NCID = NCOPN ('foo.nc', NCWRITE, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)
         ...
* delete attribute
      CALL NCREDF (NCID, RCODE)  ! enter define mode
      CALL NCADEL (NCID, RHID, 'Units', RCODE)
      CALL NCENDF (NCID, RCODE)  ! leave define mode

Go to the first, previous, next, last section, table of contents.

				Unidata is a member of the UCAR Office of Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation.
				P.O. Box 3000 • Boulder, CO 80307-3000 USA • Tel: 303-497-8643 • Fax: 303-497-8690