[409] | 1 | /*! \file |
---|
| 2 | Functions for netCDF-4 features. |
---|
| 3 | |
---|
| 4 | Copyright 2010 University Corporation for Atmospheric |
---|
| 5 | Research/Unidata. See \ref COPYRIGHT file for more info. */ |
---|
| 6 | |
---|
| 7 | #include "ncdispatch.h" |
---|
| 8 | |
---|
| 9 | /** \defgroup user_types User-Defined Types |
---|
| 10 | |
---|
| 11 | User defined types allow for more complex data structures. |
---|
| 12 | |
---|
| 13 | NetCDF-4 has added support for four different user defined data |
---|
| 14 | types. User defined type may only be used in files created with the |
---|
| 15 | ::NC_NETCDF4 and without ::NC_CLASSIC_MODEL. |
---|
| 16 | - compound type: like a C struct, a compound type is a collection of |
---|
| 17 | types, including other user defined types, in one package. |
---|
| 18 | - variable length array type: used to store ragged arrays. |
---|
| 19 | - opaque type: This type has only a size per element, and no other |
---|
| 20 | type information. |
---|
| 21 | - enum type: Like an enumeration in C, this type lets you assign text |
---|
| 22 | values to integer values, and store the integer values. |
---|
| 23 | |
---|
| 24 | Users may construct user defined type with the various nc_def_* |
---|
| 25 | functions described in this section. They may learn about user defined |
---|
| 26 | types by using the nc_inq_ functions defined in this section. |
---|
| 27 | |
---|
| 28 | Once types are constructed, define variables of the new type with |
---|
| 29 | nc_def_var (see nc_def_var). Write to them with nc_put_var1, |
---|
| 30 | nc_put_var, nc_put_vara, or nc_put_vars. Read data of user-defined |
---|
| 31 | type with nc_get_var1, nc_get_var, nc_get_vara, or nc_get_vars (see |
---|
| 32 | \ref variables). |
---|
| 33 | |
---|
| 34 | Create attributes of the new type with nc_put_att (see nc_put_att_ |
---|
| 35 | type). Read attributes of the new type with nc_get_att (see |
---|
| 36 | \ref attributes). |
---|
| 37 | */ |
---|
| 38 | /** \{ */ |
---|
| 39 | |
---|
| 40 | /** \} */ |
---|
| 41 | |
---|
| 42 | /** \defgroup groups Groups |
---|
| 43 | |
---|
| 44 | NetCDF-4 added support for hierarchical groups within netCDF datasets. |
---|
| 45 | |
---|
| 46 | Groups are identified with a ncid, which identifies both the open |
---|
| 47 | file, and the group within that file. When a file is opened with |
---|
| 48 | nc_open or nc_create, the ncid for the root group of that file is |
---|
| 49 | provided. Using that as a starting point, users can add new groups, or |
---|
| 50 | list and navigate existing groups. |
---|
| 51 | |
---|
| 52 | All netCDF calls take a ncid which determines where the call will take |
---|
| 53 | its action. For example, the nc_def_var function takes a ncid as its |
---|
| 54 | first parameter. It will create a variable in whichever group its ncid |
---|
| 55 | refers to. Use the root ncid provided by nc_create or nc_open to |
---|
| 56 | create a variable in the root group. Or use nc_def_grp to create a |
---|
| 57 | group and use its ncid to define a variable in the new group. |
---|
| 58 | |
---|
| 59 | Variable are only visible in the group in which they are defined. The |
---|
| 60 | same applies to attributes. âGlobalâ attributes are associated with |
---|
| 61 | the group whose ncid is used. |
---|
| 62 | |
---|
| 63 | Dimensions are visible in their groups, and all child groups. |
---|
| 64 | |
---|
| 65 | Group operations are only permitted on netCDF-4 files - that is, files |
---|
| 66 | created with the HDF5 flag in nc_create(). Groups are not compatible |
---|
| 67 | with the netCDF classic data model, so files created with the |
---|
| 68 | ::NC_CLASSIC_MODEL file cannot contain groups (except the root group). |
---|
| 69 | |
---|
| 70 | */ |
---|
| 71 | /** \{ */ |
---|
| 72 | int |
---|
| 73 | nc_inq_ncid(int ncid, const char *name, int *grp_ncid) |
---|
| 74 | { |
---|
| 75 | NC* ncp; |
---|
| 76 | int stat = NC_check_id(ncid,&ncp); |
---|
| 77 | if(stat != NC_NOERR) return stat; |
---|
| 78 | return ncp->dispatch->inq_ncid(ncid,name,grp_ncid); |
---|
| 79 | } |
---|
| 80 | |
---|
| 81 | int |
---|
| 82 | nc_inq_grps(int ncid, int *numgrps, int *ncids) |
---|
| 83 | { |
---|
| 84 | NC* ncp; |
---|
| 85 | int stat = NC_check_id(ncid,&ncp); |
---|
| 86 | if(stat != NC_NOERR) return stat; |
---|
| 87 | return ncp->dispatch->inq_grps(ncid,numgrps,ncids); |
---|
| 88 | } |
---|
| 89 | |
---|
| 90 | int |
---|
| 91 | nc_inq_grpname(int ncid, char *name) |
---|
| 92 | { |
---|
| 93 | NC* ncp; |
---|
| 94 | int stat = NC_check_id(ncid,&ncp); |
---|
| 95 | if(stat != NC_NOERR) return stat; |
---|
| 96 | return ncp->dispatch->inq_grpname(ncid,name); |
---|
| 97 | } |
---|
| 98 | |
---|
| 99 | int |
---|
| 100 | nc_inq_grpname_full(int ncid, size_t *lenp, char *full_name) |
---|
| 101 | { |
---|
| 102 | NC* ncp; |
---|
| 103 | int stat = NC_check_id(ncid,&ncp); |
---|
| 104 | if(stat != NC_NOERR) return stat; |
---|
| 105 | return ncp->dispatch->inq_grpname_full(ncid,lenp,full_name); |
---|
| 106 | } |
---|
| 107 | |
---|
| 108 | int |
---|
| 109 | nc_inq_grpname_len(int ncid, size_t *lenp) |
---|
| 110 | { |
---|
| 111 | int stat = nc_inq_grpname_full(ncid,lenp,NULL); |
---|
| 112 | return stat; |
---|
| 113 | } |
---|
| 114 | |
---|
| 115 | int |
---|
| 116 | nc_inq_grp_parent(int ncid, int *parent_ncid) |
---|
| 117 | { |
---|
| 118 | NC* ncp; |
---|
| 119 | int stat = NC_check_id(ncid,&ncp); |
---|
| 120 | if(stat != NC_NOERR) return stat; |
---|
| 121 | return ncp->dispatch->inq_grp_parent(ncid,parent_ncid); |
---|
| 122 | } |
---|
| 123 | |
---|
| 124 | /* This has same semantics as nc_inq_ncid */ |
---|
| 125 | int |
---|
| 126 | nc_inq_grp_ncid(int ncid, const char *grp_name, int *grp_ncid) |
---|
| 127 | { |
---|
| 128 | return nc_inq_ncid(ncid,grp_name,grp_ncid); |
---|
| 129 | } |
---|
| 130 | |
---|
| 131 | int |
---|
| 132 | nc_inq_grp_full_ncid(int ncid, const char *full_name, int *grp_ncid) |
---|
| 133 | { |
---|
| 134 | NC* ncp; |
---|
| 135 | int stat = NC_check_id(ncid,&ncp); |
---|
| 136 | if(stat != NC_NOERR) return stat; |
---|
| 137 | return ncp->dispatch->inq_grp_full_ncid(ncid,full_name,grp_ncid); |
---|
| 138 | } |
---|
| 139 | |
---|
| 140 | int |
---|
| 141 | nc_inq_varids(int ncid, int *nvars, int *varids) |
---|
| 142 | { |
---|
| 143 | NC* ncp; |
---|
| 144 | int stat = NC_check_id(ncid,&ncp); |
---|
| 145 | if(stat != NC_NOERR) return stat; |
---|
| 146 | return ncp->dispatch->inq_varids(ncid,nvars,varids); |
---|
| 147 | } |
---|
| 148 | |
---|
| 149 | int |
---|
| 150 | nc_inq_dimids(int ncid, int *ndims, int *dimids, int include_parents) |
---|
| 151 | { |
---|
| 152 | NC* ncp; |
---|
| 153 | int stat = NC_check_id(ncid,&ncp); |
---|
| 154 | if(stat != NC_NOERR) return stat; |
---|
| 155 | return ncp->dispatch->inq_dimids(ncid,ndims,dimids,include_parents); |
---|
| 156 | } |
---|
| 157 | |
---|
| 158 | int |
---|
| 159 | nc_inq_typeids(int ncid, int *ntypes, int *typeids) |
---|
| 160 | { |
---|
| 161 | NC* ncp; |
---|
| 162 | int stat = NC_check_id(ncid,&ncp); |
---|
| 163 | if(stat != NC_NOERR) return stat; |
---|
| 164 | return ncp->dispatch->inq_typeids(ncid,ntypes,typeids); |
---|
| 165 | } |
---|
| 166 | |
---|
| 167 | int |
---|
| 168 | nc_def_grp(int parent_ncid, const char *name, int *new_ncid) |
---|
| 169 | { |
---|
| 170 | NC* ncp; |
---|
| 171 | int stat = NC_check_id(parent_ncid,&ncp); |
---|
| 172 | if(stat != NC_NOERR) return stat; |
---|
| 173 | return ncp->dispatch->def_grp(parent_ncid,name,new_ncid); |
---|
| 174 | } |
---|
| 175 | |
---|
| 176 | |
---|
| 177 | |
---|
| 178 | int |
---|
| 179 | nc_show_metadata(int ncid) |
---|
| 180 | { |
---|
| 181 | NC* ncp; |
---|
| 182 | int stat = NC_check_id(ncid,&ncp); |
---|
| 183 | if(stat != NC_NOERR) return stat; |
---|
| 184 | return ncp->dispatch->show_metadata(ncid); |
---|
| 185 | } |
---|
| 186 | |
---|
| 187 | /** \} */ |
---|