Go to the previous, next section.

Create an Attribute

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.

ncattput: C Interface

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. If the attribute is of type NC_CHAR, this is one more than the string length (since the terminating null character is stored).

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 */

NCAPT, NCAPTC: FORTRAN Interface

      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, returned from a previous call to NCVDEF or NCVID.

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.

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

Go to the previous, next section.