Next: , Previous: , Up: Attributes   [Index]

5.3 Get Information about an Attribute: ncmpi_inq_att Family

This family of functions returns information about a netCDF attribute. All but one of these functions require the variable ID and attribute name; the exception is ncmpi_inq_attname. Information about an attribute includes its type, length, name, and number. See the ncmpi_get_att family for getting attribute values.

The function ncmpi_inq_attname 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.

The function ncmpi_inq_att returns the attribute’s type and length. The other functions each return just one item of information about an attribute.

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_inq_att     (int ncid, int varid, const char *name, nc_type *xtypep,
                       MPI_Offset *lenp);
int ncmpi_inq_atttype (int ncid, int varid, const char *name, nc_type *xtypep);
int ncmpi_inq_attlen  (int ncid, int varid, const char *name,
                       MPI_Offset *lenp);
int ncmpi_inq_attname (int ncid, int varid, int attnum, char *name);
int ncmpi_inq_attid   (int ncid, int varid, const char *name, int *idp);
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. For ncmpi_inq_attname, this is a pointer to the location for the returned attribute name.

xtypep

Pointer to location for returned attribute type, one of the set of predefined netCDF external data types. The type of this parameter, nc_type, is defined in the netCDF header file. The valid netCDF external data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, 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. For CDF-5 file format, the following data types are also supported: NC_UBYTE, NC _USHORT, NC_UINT, NC_INT64, and NC_UINT64.

lenp

Pointer to location for 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.

attnum

For ncmpi_inq_attname, attribute ID. The attributes for each variable are numbered from 0 (the first attribute) to natts-1, where natts is the number of attributes for the variable, as returned from a call to ncmpi_inq_varnatts.

idp

For ncmpi_inq_attid, pointer to location for returned attribute ID that specifies which attribute this is for this variable (or which global attribute). If you already know the attribute name, knowing its ID is not very useful, because accessing information about an attribute requires its name.

Return Error Codes

APIs in this group return the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

Here is an example using ncmpi_inq_att 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 <pnetcdf.h>
   ...
int  status;               /* error status */
int  ncid;                 /* netCDF ID */
int  rh_id;                /* variable ID */
nc_type vr_type, t_type;   /* attribute types */
MPI_Offset vr_len, t_len;  /* attribute lengths */

   ...
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);
   ...
status = ncmpi_inq_att(ncid, rh_id, "valid_range", &vr_type, &vr_len);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_att(ncid, NC_GLOBAL, "title", &t_type, &t_len);
if (status != NC_NOERR) handle_error(status);

Full example C program

Next: , Previous: , Up: Attributes   [Index]