netcdf-c/libdispatch/dattinq.c

/* Copyright 2018 University Corporation for Atmospheric
Research/Unidata. See \ref copyright file for more info.  */
/**
 * @file
 * Attribute inquiry functions
 *
 * These functions find out about attributes.
 */
#include "ncdispatch.h"

/**
 * @name Learning about Attributes
 *
 * Functions to learn about the attributes in a file. */
/** \{ */ /* All these functions are part of this named group... */

/**
 * @ingroup attributes
 * Return information about a netCDF attribute.
 *
 * The function nc_inq_att returns the attribute's type and length.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 *
 * @param varid Variable ID of the attribute's variable, or
 * ::NC_GLOBAL for a global attribute.
 *
 * @param name Pointer to the location for the returned attribute \ref
 * object_name. \ref ignored_if_null.
 *
 * @param xtypep Pointer to location for returned attribute \ref
 * data_type. \ref ignored_if_null.
 *
 * @param 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. \ref
 * ignored_if_null.
 *
 * @section nc_inq_att_example Example
 *
 * Here is an example using nc_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 dataset named foo.nc:
 *
@code
     #include <netcdf.h>
        ...
     int  status;
     int  ncid;
     int  rh_id;
     nc_type vr_type, t_type;
     size_t  vr_len, t_len;

        ...
     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_att (ncid, rh_id, "valid_range", &vr_type, &vr_len);
     if (status != NC_NOERR) handle_error(status);
     status = nc_inq_att (ncid, NC_GLOBAL, "title", &t_type, &t_len);
     if (status != NC_NOERR) handle_error(status);
@endcode
 *
 * @return ::NC_NOERR no error.
 * @return ::NC_EBADID bad ncid.
 * @return ::NC_ENOTVAR bad varid.
 * @return ::NC_EBADGRPID bad group ID.
 * @return ::NC_EBADNAME bad name.
 * @return ::NC_ENOTATT attribute not found.
 * @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
 * @return ::NC_ENOMEM out of memory.
 * @return ::NC_ERANGE range error when converting data.
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
*/
int
nc_inq_att(int ncid, int varid, const char *name, nc_type *xtypep,
	   size_t *lenp)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   return ncp->dispatch->inq_att(ncid, varid, name, xtypep, lenp);
}

/**
 * @ingroup attributes
 * Find an attribute ID.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 *
 * @param varid Variable ID of the attribute's variable, or
 * ::NC_GLOBAL for a global attribute.
 *
 * @param name Attribute \ref object_name.
 *
 * @param idp Pointer to location for returned attribute number that
 * specifies which attribute this is for this variable (or which
 * global attribute). If you already know the attribute name, knowing
 * its number is not very useful, because accessing information about
 * an attribute requires its name.
 *
 * @section nc_inq_attid_example Example
 *
 * Here is an example using nc_inq_attid() from
 * nc_test4/tst_vars2.c. In this example three attributes are created
 * in a file. Then it is re-opened, and their IDs are checked. They
 * will be 0, 1, and 2, in the order that the attributes were written
 * to the file.
 *
@code
     #include <netcdf.h>
     ...
     printf("**** testing fill value with three other attributes...");
     {
#define NUM_LEADERS 3
         char leader[NUM_LEADERS][NC_MAX_NAME + 1] = {"hair_length_of_strategoi",
                                                      "hair_length_of_Miltiades",
                                                      "hair_length_of_Darius_I"};
         short hair_length[NUM_LEADERS] = {3, 11, 4};
         short short_in;
         int a;

         if (nc_create(FILE_NAME, cmode, &ncid)) ERR;
         if (nc_def_dim(ncid, DIM1_NAME, DIM1_LEN, &dimids[0])) ERR;
         if (nc_def_var(ncid, VAR_NAME, NC_BYTE, NUM_DIMS, dimids, &varid)) ERR;
         for (a = 0; a < NUM_LEADERS; a++)
            if (nc_put_att_short(ncid, varid, leader[a], NC_SHORT, 1, &hair_length[a])) ERR;
         if (nc_put_att_schar(ncid, varid, _FillValue, NC_BYTE, 1, &fill_value)) ERR;
         if (nc_close(ncid)) ERR;

         if (nc_open(FILE_NAME, NC_NOWRITE, &ncid)) ERR;
         for (a = 0; a < NUM_LEADERS; a++)
         {
            ...
            if (nc_inq_attid(ncid, 0, leader[a], &attnum_in)) ERR;
            if (attnum_in != a) ERR;
         }

         if (nc_close(ncid)) ERR;
@endcode
 *
 * @return ::NC_NOERR no error.
 * @return ::NC_EBADID bad ncid.
 * @return ::NC_ENOTVAR bad varid.
 * @return ::NC_EBADGRPID bad group ID.
 * @return ::NC_EBADNAME bad name.
 * @return ::NC_ENOTATT attribute not found.
 * @return ::NC_ENOMEM out of memory.
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
*/
int
nc_inq_attid(int ncid, int varid, const char *name, int *idp)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   return ncp->dispatch->inq_attid(ncid, varid, name, idp);
}

/**
 * @ingroup attributes
 * Find the name of an attribute.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 *
 * @param varid Variable ID of the attribute's variable, or
 * ::NC_GLOBAL for a global attribute.
 *
 * @param attnum Attribute number. 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 nc_inq_varnatts().
 *
 * @param name Pointer to the location for the returned attribute \ref
 * object_name.
 *
 * @section nc_inq_attname_example Example
 *
 * Here is an example from nc_test4/tst_atts3.c a variable of every
 * type is added to a file, with names from the 'names' array. Then
 * the file is re-opened, and the names of the attributes are checked
 * in a for loop.
 *
@code
     #include <netcdf.h>
     ...
#define NUM_ATTS 8
#define ATT_MAX_NAME 25
int
tst_att_ordering(int cmode)
{
   int ncid;
   char name[NUM_ATTS][ATT_MAX_NAME + 1] = {"Gc", "Gb", "Gs", "Gi", "Gf",
					    "Gd", "Gatt-name-dashes", "Gatt.name.dots"};
   int len[NUM_ATTS] = {0, 2, 3, 3, 3, 3, 1, 1};
   signed char b[2] = {-128, 127};
   short s[3] = {-32768, 0, 32767};
   int i[3] = {42, 0, -42};
   float f[3] = {42.0, -42.0, 42.0};
   double d[3] = {420.0, -420.0, 420.0};
   int att_name_dashes = -1, att_name_dots = -2;
   char name_in[NC_MAX_NAME];
   int j;

   if (nc_create(FILE_NAME, cmode, &ncid)) ERR;
   ...
   if (nc_put_att_text(ncid, NC_GLOBAL, name[0], len[0], NULL)) ERR;
   if (nc_put_att_schar(ncid, NC_GLOBAL, name[1], NC_BYTE, len[1], b)) ERR;
   if (nc_put_att_short(ncid, NC_GLOBAL, name[2], NC_SHORT, len[2], s)) ERR;
   if (nc_put_att_int(ncid, NC_GLOBAL, name[3], NC_INT, len[3], i)) ERR;
   if (nc_put_att_float(ncid, NC_GLOBAL, name[4], NC_FLOAT, len[4], f)) ERR;
   if (nc_put_att_double(ncid, NC_GLOBAL, name[5], NC_DOUBLE, len[5], d)) ERR;
   if (nc_put_att_int(ncid, NC_GLOBAL, name[6], NC_INT, len[6], &att_name_dashes)) ERR;
   if (nc_put_att_int(ncid, NC_GLOBAL, name[7], NC_INT, len[7], &att_name_dots)) ERR;
   if (nc_close(ncid)) ERR;

   ...
   if (nc_open(FILE_NAME, 0, &ncid)) ERR;
   for (j = 0; j < NUM_ATTS; j++)
   {
      if (nc_inq_attname(ncid, NC_GLOBAL, j, name_in)) ERR;
      if (strcmp(name_in, name[j])) ERR;
   }

   if (nc_close(ncid)) ERR;

@endcode
 *
 * @return ::NC_NOERR no error.
 * @return ::NC_EBADID bad ncid.
 * @return ::NC_ENOTVAR bad varid.
 * @return ::NC_EBADGRPID bad group ID.
 * @return ::NC_EBADNAME bad name.
 * @return ::NC_ENOTATT attribute not found.
 * @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
 * @return ::NC_ENOMEM out of memory.
 * @return ::NC_ERANGE range error when converting data.
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
*/
int
nc_inq_attname(int ncid, int varid, int attnum, char *name)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   return ncp->dispatch->inq_attname(ncid, varid, attnum, name);
}

/**
 * @ingroup attributes
 * Find number of global or group attributes.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 *
 * @param nattsp Pointer where number of global or group attributes
 * will be written. \ref ignored_if_null.
 *
 * @section nc_inq_natts_example Example
 *
 * Here is an example from nc_test4/tst_vars.c:
 *
@code
     #include <netcdf.h>
     ...
int
check_4D_example(char *file_name, int expected_format)
{
   int ncid;
   int format, ndims_in, nvars_in, natts_in;
   ...

   if (nc_open(file_name, 0, &ncid)) ERR;
   ...
   if (nc_inq_natts(ncid, &natts_in)) ERR;
   if (natts_in != 0) ERR;
@endcode

 * @return ::NC_NOERR no error.
 * @return ::NC_EBADID bad ncid.
 * @return ::NC_EBADGRPID bad group ID.
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
*/
int
nc_inq_natts(int ncid, int *nattsp)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   if(nattsp == NULL) return NC_NOERR;
   return ncp->dispatch->inq(ncid, NULL, NULL, nattsp, NULL);
}

/**
 * @ingroup attributes
 * Find the type of an attribute.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 *
 * @param varid Variable ID of the attribute's variable, or
 * ::NC_GLOBAL for a global or group attribute.
 *
 * @param name Attribute \ref object_name.
 *
 * @param xtypep Pointer to location for returned attribute \ref
 * data_type.
 *
 * @section nc_inq_atttype_example Example
 *
 * Here is an example from nc_test4/tst_h_refs.c. In this example, a
 * file with an integer attribute is open. It's type is confirmed to
 * be NC_INT.
 *
@code
     #include <netcdf.h>
     ...
    printf("*** Checking accessing file through netCDF-4 API...");
    {
	int ncid, varid, attid;
	nc_type type;

	if (nc_open(FILE_NAME, NC_NOWRITE, &ncid)) ERR;
        ...
	if (nc_inq_atttype(ncid, NC_GLOBAL, INT_ATT_NAME, &type)) ERR;
	if (type != NC_INT) ERR;

@endcode
 *
 * @return ::NC_NOERR no error.
 * @return ::NC_EBADID bad ncid.
 * @return ::NC_ENOTVAR bad varid.
 * @return ::NC_EBADGRPID bad group ID.
 * @return ::NC_EBADNAME bad name.
 * @return ::NC_ENOTATT attribute not found.
 * @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
 * @return ::NC_ENOMEM out of memory.
 * @return ::NC_ERANGE range error when converting data.
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
*/
int
nc_inq_atttype(int ncid, int varid, const char *name, nc_type *xtypep)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   return ncp->dispatch->inq_att(ncid, varid, name, xtypep, NULL);
}

/**
 * @ingroup attributes
 * Find the length of an attribute.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 *
 * @param varid Variable ID of the attribute's variable, or
 * ::NC_GLOBAL for a global or group attribute.
 *
 * @param name Attribute \ref object_name.
 *
 * @param lenp Pointer to location for returned number of values
 * currently stored in the attribute. Before using the value as a C
 * string, make sure it is null-terminated. \ref ignored_if_null.
 *
 * @section nc_inq_attlen_example Example
 *
 * Here is an example from nc_test4/tst_h_scalar.c which checks the
 * attributes of an already-open netCDF file. In this code, the length
 * of two attributes are checked, and found to be 1.
 *
@code
     #include <netcdf.h>
     ...
int
check_attrs(int ncid, int obj)
{
    int attid;
    int natts = 0;
    size_t len;
    nc_type type;
    char *vlstr;
    char fixstr[10];
    int x;

    ...
    if (nc_inq_attlen(ncid, obj, VSTR_ATT1_NAME, &len)) ERR_GOTO;
    if (len != 1) ERR_GOTO;
    ...
    if (nc_inq_attlen(ncid, obj, VSTR_ATT2_NAME, &len)) ERR_GOTO;
    if (len != 1) ERR_GOTO;

@endcode

 * @return ::NC_NOERR no error.
 * @return ::NC_EBADID bad ncid.
 * @return ::NC_ENOTVAR bad varid.
 * @return ::NC_EBADGRPID bad group ID.
 * @return ::NC_EBADNAME bad name.
 * @return ::NC_ENOTATT attribute not found.
 * @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
 * @return ::NC_ENOMEM out of memory.
 * @return ::NC_ERANGE range error when converting data.
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
*/
int
nc_inq_attlen(int ncid, int varid, const char *name, size_t *lenp)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   return ncp->dispatch->inq_att(ncid, varid, name, NULL, lenp);
}

/*! \} */  /* End of named group ...*/