[1022] | 1 | /*! \file |
---|
| 2 | Functions for VLEN Types |
---|
| 3 | |
---|
| 4 | Copyright 2011 University Corporation for Atmospheric |
---|
| 5 | Research/Unidata. See \ref copyright file for more info. */ |
---|
| 6 | |
---|
| 7 | #include "ncdispatch.h" |
---|
| 8 | |
---|
| 9 | /** \name Variable Length Array Types |
---|
| 10 | |
---|
| 11 | Functions to create and learn about VLEN types. */ |
---|
| 12 | /*! \{ */ /* All these functions are part of this named group... */ |
---|
| 13 | |
---|
| 14 | /** |
---|
| 15 | \ingroup user_types |
---|
| 16 | Free memory in a VLEN object. |
---|
| 17 | |
---|
| 18 | When you read VLEN type the library will actually allocate the storage |
---|
| 19 | space for the data. This storage space must be freed, so pass the |
---|
| 20 | pointer back to this function, when you're done with the data, and it |
---|
| 21 | will free the vlen memory. |
---|
| 22 | |
---|
| 23 | The function nc_free_vlens() is more useful than this function, |
---|
| 24 | because it can free an array of VLEN objects. |
---|
| 25 | |
---|
| 26 | \param vl pointer to the vlen object. |
---|
| 27 | |
---|
| 28 | \returns ::NC_NOERR No error. |
---|
| 29 | \returns ::NC_EBADID Bad \ref ncid. |
---|
| 30 | \returns ::NC_EBADTYPE Bad type id. |
---|
| 31 | \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. |
---|
| 32 | \returns ::NC_EHDFERR An error was reported by the HDF5 layer. |
---|
| 33 | */ |
---|
| 34 | int |
---|
| 35 | nc_free_vlen(nc_vlen_t *vl) |
---|
| 36 | { |
---|
| 37 | free(vl->p); |
---|
| 38 | return NC_NOERR; |
---|
| 39 | } |
---|
| 40 | |
---|
| 41 | /** |
---|
| 42 | \ingroup user_types |
---|
| 43 | Free an array of vlens given the number of elements and an array. |
---|
| 44 | |
---|
| 45 | When you read VLEN type the library will actually allocate the storage |
---|
| 46 | space for the data. This storage space must be freed, so pass the |
---|
| 47 | pointer back to this function, when you're done with the data, and it |
---|
| 48 | will free the vlen memory. |
---|
| 49 | |
---|
| 50 | \param len number of elements in the array. |
---|
| 51 | \param vlens pointer to the vlen object. |
---|
| 52 | |
---|
| 53 | \returns ::NC_NOERR No error. |
---|
| 54 | \returns ::NC_EBADID Bad \ref ncid. |
---|
| 55 | \returns ::NC_EBADTYPE Bad type id. |
---|
| 56 | \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. |
---|
| 57 | \returns ::NC_EHDFERR An error was reported by the HDF5 layer. |
---|
| 58 | */ |
---|
| 59 | int |
---|
| 60 | nc_free_vlens(size_t len, nc_vlen_t vlens[]) |
---|
| 61 | { |
---|
| 62 | int ret; |
---|
| 63 | size_t i; |
---|
| 64 | |
---|
| 65 | for(i = 0; i < len; i++) |
---|
| 66 | if ((ret = nc_free_vlen(&vlens[i]))) |
---|
| 67 | return ret; |
---|
| 68 | |
---|
| 69 | return NC_NOERR; |
---|
| 70 | } |
---|
| 71 | |
---|
| 72 | /** |
---|
| 73 | \ingroup user_types |
---|
| 74 | Use this function to define a variable length array type. |
---|
| 75 | |
---|
| 76 | \param ncid \ref ncid |
---|
| 77 | \param name \ref object_name of new type. |
---|
| 78 | |
---|
| 79 | \param base_typeid The typeid of the base type of the VLEN. For |
---|
| 80 | example, for a VLEN of shorts, the base type is ::NC_SHORT. This can be |
---|
| 81 | a user defined type. |
---|
| 82 | |
---|
| 83 | \param xtypep A pointer to an nc_type variable. The typeid of the new |
---|
| 84 | VLEN type will be set here. |
---|
| 85 | |
---|
| 86 | \returns ::NC_NOERR No error. |
---|
| 87 | \returns ::NC_EBADID Bad \ref ncid. |
---|
| 88 | \returns ::NC_EBADTYPE Bad type id. |
---|
| 89 | \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. |
---|
| 90 | \returns ::NC_EHDFERR An error was reported by the HDF5 layer. |
---|
| 91 | \returns ::NC_ENAMEINUSE That name is in use. |
---|
| 92 | \returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. |
---|
| 93 | \returns ::NC_EBADNAME Name contains illegal characters. |
---|
| 94 | \returns ::NC_EPERM Attempt to write to a read-only file. |
---|
| 95 | \returns ::NC_ENOTINDEFINE Not in define mode. |
---|
| 96 | */ |
---|
| 97 | int |
---|
| 98 | nc_def_vlen(int ncid, const char *name, nc_type base_typeid, nc_type *xtypep) |
---|
| 99 | { |
---|
| 100 | NC* ncp; |
---|
| 101 | int stat = NC_check_id(ncid,&ncp); |
---|
| 102 | if(stat != NC_NOERR) return stat; |
---|
| 103 | return ncp->dispatch->def_vlen(ncid,name,base_typeid,xtypep); |
---|
| 104 | } |
---|
| 105 | |
---|
| 106 | /** \ingroup user_types |
---|
| 107 | Learn about a VLEN type. |
---|
| 108 | |
---|
| 109 | \param ncid \ref ncid |
---|
| 110 | \param xtype The type of the VLEN to inquire about. |
---|
| 111 | \param name \ref object_name of the type. \ref ignored_if_null. |
---|
| 112 | |
---|
| 113 | \param datum_sizep A pointer to a size_t, this will get the size of |
---|
| 114 | one element of this vlen. \ref ignored_if_null. |
---|
| 115 | |
---|
| 116 | \param base_nc_typep Pointer to get the base type of the VLEN. \ref |
---|
| 117 | ignored_if_null. |
---|
| 118 | |
---|
| 119 | \returns ::NC_NOERR No error. |
---|
| 120 | \returns ::NC_EBADID Bad \ref ncid. |
---|
| 121 | \returns ::NC_EBADTYPE Bad type id. |
---|
| 122 | \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. |
---|
| 123 | \returns ::NC_EHDFERR An error was reported by the HDF5 layer. |
---|
| 124 | */ |
---|
| 125 | int |
---|
| 126 | nc_inq_vlen(int ncid, nc_type xtype, char *name, size_t *datum_sizep, nc_type *base_nc_typep) |
---|
| 127 | { |
---|
| 128 | int class = 0; |
---|
| 129 | int stat = nc_inq_user_type(ncid,xtype,name,datum_sizep,base_nc_typep,NULL,&class); |
---|
| 130 | if(stat != NC_NOERR) return stat; |
---|
| 131 | if(class != NC_VLEN) stat = NC_EBADTYPE; |
---|
| 132 | return stat; |
---|
| 133 | } |
---|
| 134 | /*! \} */ /* End of named group ...*/ |
---|
| 135 | |
---|
| 136 | /** \internal |
---|
| 137 | \ingroup user_types |
---|
| 138 | |
---|
| 139 | Put a VLEN element. This function writes an element of a VLEN for the |
---|
| 140 | Fortran APIs. |
---|
| 141 | |
---|
| 142 | \param ncid \ref ncid |
---|
| 143 | \param typeid1 Typeid of the VLEN. |
---|
| 144 | \param vlen_element Pointer to the element of the VLEN. |
---|
| 145 | \param len Lenth of the VLEN element. |
---|
| 146 | \param data VLEN data. |
---|
| 147 | |
---|
| 148 | \returns ::NC_NOERR No error. |
---|
| 149 | \returns ::NC_EBADID Bad \ref ncid. |
---|
| 150 | \returns ::NC_EBADTYPE Bad type id. |
---|
| 151 | \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. |
---|
| 152 | \returns ::NC_EHDFERR An error was reported by the HDF5 layer. |
---|
| 153 | \returns ::NC_EPERM Attempt to write to a read-only file. |
---|
| 154 | */ |
---|
| 155 | int |
---|
| 156 | nc_put_vlen_element(int ncid, int typeid1, void *vlen_element, size_t len, const void *data) |
---|
| 157 | { |
---|
| 158 | NC* ncp; |
---|
| 159 | int stat = NC_check_id(ncid,&ncp); |
---|
| 160 | if(stat != NC_NOERR) return stat; |
---|
| 161 | return ncp->dispatch->put_vlen_element(ncid,typeid1,vlen_element,len,data); |
---|
| 162 | } |
---|
| 163 | |
---|
| 164 | /** |
---|
| 165 | \internal |
---|
| 166 | \ingroup user_types |
---|
| 167 | |
---|
| 168 | Get a VLEN element. This function reads an element of a VLEN for the |
---|
| 169 | Fortran APIs. |
---|
| 170 | |
---|
| 171 | \param ncid \ref ncid |
---|
| 172 | \param typeid1 Typeid of the VLEN. |
---|
| 173 | \param vlen_element Pointer to the element of the VLEN. |
---|
| 174 | \param len Lenth of the VLEN element. |
---|
| 175 | \param data VLEN data. |
---|
| 176 | |
---|
| 177 | \returns ::NC_NOERR No error. |
---|
| 178 | \returns ::NC_EBADID Bad \ref ncid. |
---|
| 179 | \returns ::NC_EBADTYPE Bad type id. |
---|
| 180 | \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. |
---|
| 181 | \returns ::NC_EHDFERR An error was reported by the HDF5 layer. |
---|
| 182 | */ |
---|
| 183 | int |
---|
| 184 | nc_get_vlen_element(int ncid, int typeid1, const void *vlen_element, |
---|
| 185 | size_t *len, void *data) |
---|
| 186 | { |
---|
| 187 | NC *ncp; |
---|
| 188 | int stat = NC_check_id(ncid,&ncp); |
---|
| 189 | if(stat != NC_NOERR) return stat; |
---|
| 190 | return ncp->dispatch->get_vlen_element(ncid, typeid1, vlen_element, |
---|
| 191 | len, data); |
---|
| 192 | } |
---|