00001 /*
00002  *      Copyright 1996, University Corporation for Atmospheric Research
00003  *      See netcdf/COPYRIGHT file for copying and redistribution conditions.
00004  */
00005 #ifndef _NC_H_
00006 #define _NC_H_
00007 
00008 /*
00009  *      netcdf library 'private' data structures, objects and interfaces
00010  */
00011 
00012 #include        "ncconfig.h"
00013 #include        <stddef.h>      /* size_t */
00014 #include        <sys/types.h>   /* off_t */
00015 #include        "netcdf.h"
00016 #include        "ncio.h"        /* ncio */
00017 #include        "fbits.h"
00018 
00019 
00020 #ifndef NC_ARRAY_GROWBY
00021 #define NC_ARRAY_GROWBY 4
00022 #endif
00023 
00024 /*
00025  * The extern size of an empty
00026  * netcdf version 1 file.
00027  * The initial value of ncp->xsz.
00028  */
00029 #define MIN_NC_XSZ 32
00030 
00031 typedef struct NC NC; /* forward reference */
00032 
00033 /*
00034  *  The internal data types
00035  */
00036 typedef enum {
00037         NC_UNSPECIFIED = 0,
00038 /* future       NC_BITFIELD = 7, */
00039 /*      NC_STRING =     8,      */
00040         NC_DIMENSION =  10,
00041         NC_VARIABLE =   11,
00042         NC_ATTRIBUTE =  12
00043 } NCtype;
00044 
00045 
00046 /*
00047  * Counted string for names and such
00048  */
00049 typedef struct {
00050         /* all xdr'd */
00051         size_t nchars;
00052         char *cp;
00053 } NC_string;
00054 
00055 /* Begin defined in string.c */
00056 extern void
00057 free_NC_string(NC_string *ncstrp);
00058 
00059 extern int
00060 NC_check_name(const char *name);
00061 
00062 extern NC_string *
00063 new_NC_string(size_t slen, const char *str);
00064 
00065 extern int
00066 set_NC_string(NC_string *ncstrp, const char *str);
00067 
00068 /* End defined in string.c */
00069 
00070 /*
00071  * NC dimension stucture
00072  */
00073 typedef struct {
00074         /* all xdr'd */
00075         NC_string *name;
00076         size_t size;
00077 } NC_dim;
00078 
00079 typedef struct NC_dimarray {
00080         size_t nalloc;          /* number allocated >= nelems */
00081         /* below gets xdr'd */
00082         /* NCtype type = NC_DIMENSION */
00083         size_t nelems;          /* length of the array */
00084         NC_dim **value;
00085 } NC_dimarray;
00086 
00087 /* Begin defined in dim.c */
00088 
00089 extern void
00090 free_NC_dim(NC_dim *dimp);
00091 
00092 extern NC_dim *
00093 new_x_NC_dim(NC_string *name);
00094 
00095 extern int
00096 find_NC_Udim(const NC_dimarray *ncap, NC_dim **dimpp);
00097 
00098 /* dimarray */
00099 
00100 extern void
00101 free_NC_dimarrayV0(NC_dimarray *ncap);
00102 
00103 extern void
00104 free_NC_dimarrayV(NC_dimarray *ncap);
00105 
00106 extern int
00107 dup_NC_dimarrayV(NC_dimarray *ncap, const NC_dimarray *ref);
00108 
00109 extern NC_dim *
00110 elem_NC_dimarray(const NC_dimarray *ncap, size_t elem);
00111 
00112 /* End defined in dim.c */
00113 
00114 /*
00115  * NC attribute
00116  */
00117 typedef struct {
00118         size_t xsz;             /* amount of space at xvalue */
00119         /* below gets xdr'd */
00120         NC_string *name;
00121         nc_type type;           /* the discriminant */
00122         size_t nelems;          /* length of the array */
00123         void *xvalue;           /* the actual data, in external representation */
00124 } NC_attr;
00125 
00126 typedef struct NC_attrarray {
00127         size_t nalloc;          /* number allocated >= nelems */
00128         /* below gets xdr'd */
00129         /* NCtype type = NC_ATTRIBUTE */
00130         size_t nelems;          /* length of the array */
00131         NC_attr **value;
00132 } NC_attrarray;
00133 
00134 /* Begin defined in attr.c */
00135 
00136 extern void
00137 free_NC_attr(NC_attr *attrp);
00138 
00139 extern NC_attr *
00140 new_x_NC_attr(
00141         NC_string *strp,
00142         nc_type type,
00143         size_t nelems);
00144 
00145 extern NC_attr **
00146 NC_findattr(const NC_attrarray *ncap, const char *name);
00147 
00148 /* attrarray */
00149 
00150 extern void
00151 free_NC_attrarrayV0(NC_attrarray *ncap);
00152 
00153 extern void
00154 free_NC_attrarrayV(NC_attrarray *ncap);
00155 
00156 extern int
00157 dup_NC_attrarrayV(NC_attrarray *ncap, const NC_attrarray *ref);
00158 
00159 extern NC_attr *
00160 elem_NC_attrarray(const NC_attrarray *ncap, size_t elem);
00161 
00162 /* End defined in attr.c */
00163 
00164 
00165 /*
00166  * NC variable: description and data
00167  */
00168 typedef struct {
00169         size_t xsz;             /* xszof 1 element */
00170         size_t *shape; /* compiled info: dim->size of each dim */
00171         size_t *dsizes; /* compiled info: the right to left product of shape */
00172         /* below gets xdr'd */
00173         NC_string *name;
00174         /* next two: formerly NC_iarray *assoc */ /* user definition */
00175         size_t ndims;   /* assoc->count */
00176         int *dimids;    /* assoc->value */
00177         NC_attrarray attrs;
00178         nc_type type;           /* the discriminant */
00179         size_t len;             /* the total length originally allocated */
00180         off_t begin;
00181 } NC_var;
00182 
00183 typedef struct NC_vararray {
00184         size_t nalloc;          /* number allocated >= nelems */
00185         /* below gets xdr'd */
00186         /* NCtype type = NC_VARIABLE */
00187         size_t nelems;          /* length of the array */
00188         NC_var **value;
00189 } NC_vararray;
00190 
00191 /* Begin defined in var.c */
00192 
00193 extern void
00194 free_NC_var(NC_var *varp);
00195 
00196 extern NC_var *
00197 new_x_NC_var(
00198         NC_string *strp,
00199         size_t ndims);
00200 
00201 /* vararray */
00202 
00203 extern void
00204 free_NC_vararrayV0(NC_vararray *ncap);
00205 
00206 extern void
00207 free_NC_vararrayV(NC_vararray *ncap);
00208 
00209 extern int
00210 dup_NC_vararrayV(NC_vararray *ncap, const NC_vararray *ref);
00211 
00212 extern int
00213 NC_var_shape(NC_var *varp, const NC_dimarray *dims);
00214 
00215 extern int
00216 NC_findvar(const NC_vararray *ncap, const char *name, NC_var **varpp);
00217 
00218 extern NC_var *
00219 NC_lookupvar(NC *ncp, int varid);
00220 
00221 /* End defined in var.c */
00222 
00223 #define IS_RECVAR(vp) \
00224         ((vp)->shape != NULL ? (*(vp)->shape == NC_UNLIMITED) : 0 )
00225 
00226 #ifdef LOCKNUMREC
00227 /*
00228  * typedef SHMEM type
00229  * for whenever the SHMEM functions can handle other than shorts
00230  */
00231 typedef unsigned short int      ushmem_t;
00232 typedef short int                shmem_t;
00233 #endif
00234 
00235 struct NC {
00236         /* links to make list of open netcdf's */
00237         struct NC *next;
00238         struct NC *prev;
00239         /* contains the previous NC during redef. */
00240         struct NC *old;
00241         /* flags */
00242 #define NC_CREAT 2      /* in create phase, cleared by ncendef */
00243 #define NC_INDEF 8      /* in define mode, cleared by ncendef */
00244 #define NC_NSYNC 0x10   /* synchronise numrecs on change */
00245 #define NC_HSYNC 0x20   /* synchronise whole header on change */
00246 #define NC_NDIRTY 0x40  /* numrecs has changed */
00247 #define NC_HDIRTY 0x80  /* header info has changed */
00248 /*      NC_NOFILL in netcdf.h, historical interface */
00249         int flags;
00250         ncio *nciop;
00251         size_t chunk;   /* largest extent this layer will request from ncio->get() */
00252         size_t xsz;     /* external size of this header, == var[0].begin */
00253         off_t begin_var; /* postion of the first (non-record) var */
00254         off_t begin_rec; /* postion of the first 'record' */
00255         size_t recsize; /* length of 'record' */
00256         /* below gets xdr'd */
00257         size_t numrecs; /* number of 'records' allocated */
00258         NC_dimarray dims;
00259         NC_attrarray attrs;
00260         NC_vararray vars;
00261 #ifdef LOCKNUMREC
00262 /* size and named indexes for the lock array protecting NC.numrecs */
00263 #  define LOCKNUMREC_DIM        4
00264 #  define LOCKNUMREC_VALUE      0
00265 #  define LOCKNUMREC_LOCK       1
00266 #  define LOCKNUMREC_SERVING    2
00267 #  define LOCKNUMREC_BASEPE     3
00268         /* Used on Cray T3E MPP to maintain the
00269          * integrity of numrecs for an unlimited dimension
00270          */
00271         ushmem_t lock[LOCKNUMREC_DIM];
00272 #endif
00273 };
00274 
00275 #define NC_readonly(ncp) \
00276         (!fIsSet(ncp->nciop->ioflags, NC_WRITE))
00277 
00278 #define NC_IsNew(ncp) \
00279         fIsSet((ncp)->flags, NC_CREAT)
00280 
00281 #define NC_indef(ncp) \
00282         (NC_IsNew(ncp) || fIsSet((ncp)->flags, NC_INDEF)) 
00283 
00284 #define set_NC_ndirty(ncp) \
00285         fSet((ncp)->flags, NC_NDIRTY)
00286 
00287 #define NC_ndirty(ncp) \
00288         fIsSet((ncp)->flags, NC_NDIRTY)
00289 
00290 #define set_NC_hdirty(ncp) \
00291         fSet((ncp)->flags, NC_HDIRTY)
00292 
00293 #define NC_hdirty(ncp) \
00294         fIsSet((ncp)->flags, NC_HDIRTY)
00295 
00296 #define NC_dofill(ncp) \
00297         (!fIsSet((ncp)->flags, NC_NOFILL))
00298 
00299 #define NC_doHsync(ncp) \
00300         fIsSet((ncp)->flags, NC_HSYNC)
00301 
00302 #define NC_doNsync(ncp) \
00303         fIsSet((ncp)->flags, NC_NSYNC)
00304 
00305 #ifndef LOCKNUMREC
00306 #  define NC_get_numrecs(ncp) \
00307         ((ncp)->numrecs)
00308 
00309 #  define NC_set_numrecs(ncp, nrecs) \
00310         {((ncp)->numrecs = (nrecs));}
00311 
00312 #  define NC_increase_numrecs(ncp, nrecs) \
00313         {if((nrecs) > (ncp)->numrecs) ((ncp)->numrecs = (nrecs));}
00314 #else
00315         size_t NC_get_numrecs(const NC *ncp);
00316         void   NC_set_numrecs(NC *ncp, size_t nrecs);
00317         void   NC_increase_numrecs(NC *ncp, size_t nrecs);
00318 #endif
00319 
00320 /* Begin defined in nc.c */
00321 
00322 extern int
00323 NC_check_id(int ncid, NC **ncpp);
00324 
00325 extern int
00326 nc_cktype(nc_type datatype);
00327 
00328 extern size_t
00329 ncx_howmany(nc_type type, size_t xbufsize);
00330 
00331 extern int
00332 read_numrecs(NC *ncp);
00333 
00334 extern int
00335 write_numrecs(NC *ncp);
00336 
00337 extern int
00338 NC_sync(NC *ncp);
00339 
00340 /* End defined in nc.c */
00341 /* Begin defined in v1hpg.c */
00342 
00343 extern size_t
00344 ncx_len_NC(const NC *ncp);
00345 
00346 extern int
00347 ncx_put_NC(const NC *ncp, void **xpp, off_t offset, size_t extent);
00348 
00349 extern int
00350 nc_get_NC( NC *ncp);
00351 
00352 /* End defined in v1hpg.c */
00353 /* Begin defined in putget.c */
00354 
00355 extern int
00356 fill_NC_var(NC *ncp, const NC_var *varp, size_t recno);
00357 
00358 extern int
00359 nc_inq_rec(int ncid, size_t *nrecvars, int *recvarids, size_t *recsizes);
00360 
00361 extern int
00362 nc_get_rec(int ncid, size_t recnum, void **datap);
00363 
00364 extern int
00365 nc_put_rec(int ncid, size_t recnum, void *const *datap);
00366 
00367 /* End defined in putget.c */
00368 
00369 /*
00370  * These functions are used to support
00371  * interface version 2 backward compatiblity.
00372  * N.B. these are tested in ../nc_test even though they are
00373  * not public. So, be careful to change the declarations in
00374  * ../nc_test/tests.h if you change these.
00375  */
00376 
00377 extern int
00378 nc_put_att(int ncid, int varid, const char *name, nc_type datatype,
00379         size_t len, const void *value);
00380 
00381 extern int
00382 nc_get_att(int ncid, int varid, const char *name, void *value);
00383 
00384 extern int
00385 nc_put_var1(int ncid, int varid, const size_t *index, const void *value);
00386 
00387 extern int
00388 nc_get_var1(int ncid, int varid, const size_t *index, void *value);
00389 
00390 extern int
00391 nc_put_vara(int ncid, int varid,
00392          const size_t *start, const size_t *count, const void *value);
00393 
00394 extern int
00395 nc_get_vara(int ncid, int varid,
00396          const size_t *start, const size_t *count, void *value);
00397 
00398 extern int
00399 nc_put_vars(int ncid, int varid,
00400          const size_t *start, const size_t *count, const ptrdiff_t *stride,
00401          const void * value);
00402 
00403 extern int
00404 nc_get_vars(int ncid, int varid,
00405          const size_t *start, const size_t *count, const ptrdiff_t *stride,
00406          void * value);
00407 
00408 extern int
00409 nc_put_varm(int ncid, int varid,
00410          const size_t *start, const size_t *count, const ptrdiff_t *stride,
00411          const ptrdiff_t * map, const void *value);
00412 
00413 extern int
00414 nc_get_varm(int ncid, int varid,
00415          const size_t *start, const size_t *count, const ptrdiff_t *stride,
00416          const ptrdiff_t * map, void *value);
00417 
00418 #endif /* _NC_H_ */