1/** \file
2Attribute inquiry functions
3
4These functions find out about attributes.
5
6Copyright 2011 University Corporation for Atmospheric
7Research/Unidata. See \ref copyright file for more info.  */
8
9#include "ncdispatch.h"
10
11/** \name Learning about Attributes
12
13Functions to learn about the attributes in a file. */
14/*! \{ */ /* All these functions are part of this named group... */
15
16/**
17\ingroup attributes
18Return information about a netCDF attribute.
19
20The function nc_inq_att returns the attribute's type and length.
21
22\param ncid NetCDF or group ID, from a previous call to nc_open(),
23nc_create(), nc_def_grp(), or associated inquiry functions such as
24nc_inq_ncid().
25
26\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
27for a global attribute.
28
29\param name Pointer to the location for the returned attribute \ref
30object_name. \ref ignored_if_null.
31
32\param xtypep Pointer to location for returned attribute \ref
33data_type. \ref ignored_if_null.
34
35\param lenp Pointer to location for returned number of values
36currently stored in the attribute. For attributes of type ::NC_CHAR,
37you should not assume that this includes a trailing zero byte; it
38doesn't if the attribute was stored without a trailing zero byte, for
39example from a FORTRAN program. Before using the value as a C string,
40make sure it is null-terminated. \ref ignored_if_null.
41
42\section nc_inq_att_example Example
43
44Here is an example using nc_inq_att() to find out the type and length of
45a variable attribute named valid_range for a netCDF variable named rh
46and a global attribute named title in an existing netCDF dataset named
47foo.nc:
48
49\code
50     #include <netcdf.h>
51        ...
52     int  status;
53     int  ncid;
54     int  rh_id;
55     nc_type vr_type, t_type;
56     size_t  vr_len, t_len;
57
58        ...
59     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
60     if (status != NC_NOERR) handle_error(status);
61        ...
62     status = nc_inq_varid (ncid, "rh", &rh_id);
63     if (status != NC_NOERR) handle_error(status);
64        ...
65     status = nc_inq_att (ncid, rh_id, "valid_range", &vr_type, &vr_len);
66     if (status != NC_NOERR) handle_error(status);
67     status = nc_inq_att (ncid, NC_GLOBAL, "title", &t_type, &t_len);
68     if (status != NC_NOERR) handle_error(status);
69\endcode
70*/
71int
72nc_inq_att(int ncid, int varid, const char *namenc_type *xtypep,
73    size_t *lenp)
74{
75   NCncp;
76   int stat = NC_check_id(ncid, &ncp);
77   if(stat != NC_NOERR) return stat;
78   return ncp->dispatch->inq_att(ncidvaridnamextypeplenp);
79}
80
81/**
82\ingroup attributes
83Find an attribute ID.
84
85\param ncid NetCDF or group ID, from a previous call to nc_open(),
86nc_create(), nc_def_grp(), or associated inquiry functions such as
87nc_inq_ncid().
88
89\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL for
90a global attribute.
91
92\param name Attribute \ref object_name.
93
94\param idp Pointer to location for returned attribute number that
95specifies which attribute this is for this variable (or which global
96attribute). If you already know the attribute name, knowing its number
97is not very useful, because accessing information about an attribute
98requires its name.
99*/
100int
101nc_inq_attid(int ncid, int varid, const char *name, int *idp)
102{
103   NCncp;
104   int stat = NC_check_id(ncid, &ncp);
105   if(stat != NC_NOERR) return stat;
106   return ncp->dispatch->inq_attid(ncidvaridnameidp);
107}
108
109/**
110\ingroup attributes
111Find the name of an attribute.
112
113\param ncid NetCDF or group ID, from a previous call to nc_open(),
114nc_create(), nc_def_grp(), or associated inquiry functions such as
115nc_inq_ncid().
116
117\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
118for a global attribute.
119
120\param attnum Attribute number. The attributes for each variable are
121numbered from 0 (the first attribute) to natts-1, where natts is the
122number of attributes for the variable, as returned from a call to
123nc_inq_varnatts().
124
125\param name Pointer to the location for the returned attribute \ref
126object_name.
127*/
128int
129nc_inq_attname(int ncid, int varid, int attnum, char *name)
130{
131   NCncp;
132   int stat = NC_check_id(ncid, &ncp);
133   if(stat != NC_NOERR) return stat;
134   return ncp->dispatch->inq_attname(ncidvaridattnumname);
135}
136
137/**
138\ingroup attributes
139Find number of global or group attributes.
140
141\param ncid NetCDF or group ID, from a previous call to nc_open(),
142nc_create(), nc_def_grp(), or associated inquiry functions such as
143nc_inq_ncid().
144
145\param nattsp Pointer where number of global or group attributes will be
146written. \ref ignored_if_null.
147*/
148int
149nc_inq_natts(int ncid, int *nattsp)
150{
151   NCncp;
152   int stat = NC_check_id(ncid, &ncp);
153   if(stat != NC_NOERR) return stat;
154   if(nattsp == NULL) return NC_NOERR;
155   return ncp->dispatch->inq(ncidNULLNULLnattspNULL);
156}
157
158/**
159\ingroup attributes
160Find the type of an attribute.
161
162\param ncid NetCDF or group ID, from a previous call to nc_open(),
163nc_create(), nc_def_grp(), or associated inquiry functions such as
164nc_inq_ncid().
165
166\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
167for a global or group attribute.
168
169\param name Attribute \ref object_name.
170
171\param xtypep Pointer to location for returned attribute \ref data_type.
172*/
173int
174nc_inq_atttype(int ncid, int varid, const char *namenc_type *xtypep)
175{
176   NCncp;
177   int stat = NC_check_id(ncid, &ncp);
178   if(stat != NC_NOERR) return stat;
179   return ncp->dispatch->inq_att(ncidvaridnamextypepNULL);
180}
181
182/**
183\ingroup attributes
184Find the length of an attribute.
185
186\param ncid NetCDF or group ID, from a previous call to nc_open(),
187nc_create(), nc_def_grp(), or associated inquiry functions such as
188nc_inq_ncid().
189
190\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
191for a global or group attribute.
192
193\param name Attribute \ref object_name.
194
195\param lenp Pointer to location for returned number of values
196currently stored in the attribute. Before using the value as a C
197string, make sure it is null-terminated. \ref ignored_if_null.
198*/
199int
200nc_inq_attlen(int ncid, int varid, const char *name, size_t *lenp)
201{
202   NCncp;
203   int stat = NC_check_id(ncid, &ncp);
204   if(stat != NC_NOERR) return stat;
205   return ncp->dispatch->inq_att(ncidvaridnameNULLlenp);
206}
207
208/*! \} */  /* End of named group ...*/


HyperKWIC - Version 7.20DA executed at 11:37 on 27 Oct 2017 | Polyhedron Solutions - INTERNAL USE | COMMERCIAL (Any O/S) SN 4AKIed