diff --git a/Doxyfile b/Doxyfile index 89b4d2427..1ba6dd2db 100644 --- a/Doxyfile +++ b/Doxyfile @@ -74,7 +74,7 @@ BRIEF_MEMBER_DESC = YES # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. -REPEAT_BRIEF = NO +REPEAT_BRIEF = YES # This tag implements a quasi-intelligent brief description abbreviator # that is used to form the text in various listings. Each string @@ -578,8 +578,9 @@ libdispatch/dfile.c libdispatch/ddim.c \ libdispatch/dattget.c libdispatch/dattinq.c libdispatch/dattput.c \ libdispatch/datt.c libdispatch/dvar.c libdispatch/dvarinq.c \ libdispatch/dvarput.c libdispatch/dvarget.c libdispatch/derror.c \ -libdispatch/nc4.c libdispatch/dtype.c libdispatch/dv2i.c \ -libsrc4/nc4file.c \ +libdispatch/nc4.c libdispatch/dcompound.c libdispatch/dv2i.c \ +libdispatch/dvlen.c libdispatch/denum.c libdispatch/dopaque.c \ +libdispatch/dtype.c libsrc4/nc4file.c \ man4/mainpage.doc man4/tutorial.doc COPYRIGHT man4/install.doc man4/dispatch.doc \ man4/guide.doc man4/types.doc man4/notes.doc diff --git a/include/netcdf.h b/include/netcdf.h index 3c2cf7fdc..b8a61e83a 100644 --- a/include/netcdf.h +++ b/include/netcdf.h @@ -325,7 +325,9 @@ by the desired type. */ error codes < -100 so that errors can be added to netcdf-3 if needed. */ #define NC4_FIRST_ERROR (-100) -#define NC_EHDFERR (-101) /**< Error at HDF5 layer. */ + +/** Error at HDF5 layer. */ +#define NC_EHDFERR (-101) #define NC_ECANTREAD (-102) /**< Can't read. */ #define NC_ECANTWRITE (-103) /**< Can't write. */ #define NC_ECANTCREATE (-104) /**< Can't create. */ diff --git a/libdispatch/Makefile.am b/libdispatch/Makefile.am index 7e80f1446..095bcec28 100755 --- a/libdispatch/Makefile.am +++ b/libdispatch/Makefile.am @@ -22,7 +22,8 @@ dnclog.c nclog.h dstring.c # Add functions only found in netCDF-4. if USE_NETCDF4 -libdispatch_la_SOURCES += nc4.c dtype.c +libdispatch_la_SOURCES += dgroup.c dvlen.c dcompound.c dtype.c denum.c \ +dopaque.c endif # USE_NETCDF4 # Turn on pre-processor flag when building a DLL for windows. diff --git a/libdispatch/dcompound.c b/libdispatch/dcompound.c new file mode 100644 index 000000000..83385cd14 --- /dev/null +++ b/libdispatch/dcompound.c @@ -0,0 +1,489 @@ +/*! \file + Functions for Compound Types + + Copyright 2011 University Corporation for Atmospheric + Research/Unidata. See \ref copyright file for more info. */ + +#include "ncdispatch.h" + +/** \name Compound Types + Functions to create and learn about compound types. */ +/*! \{ */ /* All these functions are part of this named group... */ + + +/** \ingroup user_types + +Create a compound type. Provide an ncid, a name, and a total size (in +bytes) of one element of the completed compound type. + +After calling this function, fill out the type with repeated calls to +nc_insert_compound(). Call nc_insert_compound() once for each field +you wish to insert into the compound type. + +\param ncid \ref ncid +\param size The size, in bytes, of the compound type. +\param name \ref object_name of the created type. +\param typeidp The type ID of the new type is copied here. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENAMEINUSE That name is in use. +\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. +\returns ::NC_EBADNAME Name contains illegal characters. +\returns ::NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file. +\returns ::NC_ENOTNC4 This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see nc_open). +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_EPERM Attempt to write to a read-only file. +\returns ::NC_ENOTINDEFINE Not in define mode. + +\section Example + +\code +struct s1 +{ +int i1; +int i2; +}; +struct s1 data[DIM_LEN], data_in[DIM_LEN]; + +if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR; +if (nc_def_compound(ncid, sizeof(struct s1), SVC_REC, &typeid)) ERR; +if (nc_insert_compound(ncid, typeid, BATTLES_WITH_KLINGONS, +HOFFSET(struct s1, i1), NC_INT)) ERR; +if (nc_insert_compound(ncid, typeid, DATES_WITH_ALIENS, +HOFFSET(struct s1, i2), NC_INT)) ERR; +if (nc_def_dim(ncid, STARDATE, DIM_LEN, &dimid)) ERR; +if (nc_def_var(ncid, SERVICE_RECORD, typeid, 1, dimids, &varid)) ERR; +if (nc_put_var(ncid, varid, data)) ERR; +if (nc_close(ncid)) ERR; +\endcode +*/ +int +nc_def_compound(int ncid, size_t size, const char *name, + nc_type *typeidp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->def_compound(ncid,size,name,typeidp); +} + +/** \ingroup user_types +Insert a named field into a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param name The \ref object_name of the new field. + +\param offset Offset in byte from the beginning of the compound type +for this field. + +\param field_typeid The type of the field to be inserted. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENAMEINUSE That name is in use. +\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. +\returns ::NC_EBADNAME Name contains illegal characters. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_EPERM Attempt to write to a read-only file. +\returns ::NC_ENOTINDEFINE Not in define mode. +*/ +int +nc_insert_compound(int ncid, nc_type xtype, const char *name, + size_t offset, nc_type field_typeid) +{ + NC *ncp; + int stat = NC_check_id(ncid, &ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->insert_compound(ncid, xtype, name, + offset, field_typeid); +} + +/** \ingroup user_types +Insert a named array field into a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param name The \ref object_name of the new field. + +\param offset Offset in byte from the beginning of the compound type +for this field. + +\param field_typeid The type of the field to be inserted. + + \param ndims Number of dimensions in array. + + \param dim_sizes Array of dimension sizes. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENAMEINUSE That name is in use. +\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. +\returns ::NC_EBADNAME Name contains illegal characters. +\returns ::NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_EPERM Attempt to write to a read-only file. +\returns ::NC_ENOTINDEFINE Not in define mode. +*/ +int +nc_insert_array_compound(int ncid, nc_type xtype, const char *name, + size_t offset, nc_type field_typeid, + int ndims, const int *dim_sizes) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->insert_array_compound(ncid,xtype,name,offset,field_typeid,ndims,dim_sizes); +} + +/** \ingroup user_types +Learn about a compound type. Get the number of fields, len, and +name of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param name Returned \ref object_name of compound type. \ref +ignored_if_null. + +\param sizep Returned size of compound type in bytes. \ref ignored_if_null. + +\param nfieldsp The number of fields in the compound type will be +placed here. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound(int ncid, nc_type xtype, char *name, + size_t *sizep, size_t *nfieldsp) +{ + int class = 0; + int stat = nc_inq_user_type(ncid,xtype,name,sizep,NULL,nfieldsp,&class); + if(stat != NC_NOERR) return stat; + if(class != NC_COMPOUND) stat = NC_EBADTYPE; + return stat; +} + +/** \ingroup user_types +Learn the name of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param name Returned \ref object_name of compound type. \ref +ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_name(int ncid, nc_type xtype, char *name) +{ + return nc_inq_compound(ncid,xtype,name,NULL,NULL); +} + +/** \ingroup user_types +Learn the size of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param sizep Returned size of compound type in bytes. \ref +ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_size(int ncid, nc_type xtype, size_t *sizep) +{ + return nc_inq_compound(ncid,xtype,NULL,sizep,NULL); +} + +/** \ingroup user_types +Learn the number of fields in a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param nfieldsp The number of fields in the compound type will be +placed here. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_nfields(int ncid, nc_type xtype, size_t *nfieldsp) +{ + return nc_inq_compound(ncid,xtype,NULL,NULL,nfieldsp); +} + +/** \ingroup user_types +Get information about one of the fields of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param fieldid A zero-based index number specifying a field in the +compound type. + +\param name Returned \ref object_name of the field. \ref +ignored_if_null. + +\param offsetp A pointer which will get the offset of the field. \ref +ignored_if_null. + +\param field_typeidp A pointer which will get the typeid of the +field. \ref ignored_if_null. + +\param ndimsp A pointer which will get the number of dimensions of the +field. \ref ignored_if_null. + +\param dim_sizesp A pointer which will get the dimension sizes of the +field. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_field(int ncid, nc_type xtype, int fieldid, + char *name, size_t *offsetp, + nc_type *field_typeidp, int *ndimsp, + int *dim_sizesp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_compound_field(ncid, xtype, fieldid, + name, offsetp, field_typeidp, + ndimsp, dim_sizesp); +} + +/** \ingroup user_types +Get information about one of the fields of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param fieldid A zero-based index number specifying a field in the +compound type. + +\param name Returned \ref object_name of the field. \ref +ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_fieldname(int ncid, nc_type xtype, int fieldid, + char *name) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_compound_field(ncid, xtype, fieldid, + name, NULL, NULL, NULL, + NULL); +} + +/** \ingroup user_types +Get information about one of the fields of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param fieldid A zero-based index number specifying a field in the +compound type. + +\param offsetp A pointer which will get the offset of the field. \ref +ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_fieldoffset(int ncid, nc_type xtype, int fieldid, + size_t *offsetp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_compound_field(ncid,xtype,fieldid,NULL,offsetp,NULL,NULL,NULL); +} + +/** \ingroup user_types +Get information about one of the fields of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param fieldid A zero-based index number specifying a field in the +compound type. + +\param field_typeidp A pointer which will get the typeid of the +field. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_fieldtype(int ncid, nc_type xtype, int fieldid, + nc_type *field_typeidp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_compound_field(ncid,xtype,fieldid,NULL,NULL,field_typeidp,NULL,NULL); +} + +/** \ingroup user_types +Get information about one of the fields of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param fieldid A zero-based index number specifying a field in the +compound type. + +\param ndimsp A pointer which will get the number of dimensions of the +field. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_fieldndims(int ncid, nc_type xtype, int fieldid, + int *ndimsp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_compound_field(ncid,xtype,fieldid,NULL,NULL,NULL,ndimsp,NULL); +} + +/** \ingroup user_types +Get information about one of the fields of a compound type. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param fieldid A zero-based index number specifying a field in the +compound type. + +\param dim_sizesp A pointer which will get the dimension sizes of the +field. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_fielddim_sizes(int ncid, nc_type xtype, int fieldid, + int *dim_sizesp) +{ + NC *ncp; + int stat = NC_check_id(ncid, &ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_compound_field(ncid, xtype, fieldid, + NULL, NULL, NULL, NULL, + dim_sizesp); +} + +/** \ingroup user_types +Learn the Index of a Named Field in a Compound Type. Get the index + * of a field in a compound type from the name. + +\param ncid \ref ncid + +\param xtype The typeid for this compound type, as returned by +nc_def_compound(), or nc_inq_var(). + +\param name \ref object_name of the field. \ref ignored_if_null. + +\param fieldidp A pointer which will get the index of the named +field. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_compound_fieldindex(int ncid, nc_type xtype, const char *name, + int *fieldidp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_compound_fieldindex(ncid,xtype,name,fieldidp); +} +/*! \} */ /* End of named group ...*/ + + + + + + diff --git a/libdispatch/denum.c b/libdispatch/denum.c new file mode 100644 index 000000000..dc8a2b057 --- /dev/null +++ b/libdispatch/denum.c @@ -0,0 +1,176 @@ +/*! \file + Functions for Enum Types + + Copyright 2011 University Corporation for Atmospheric + Research/Unidata. See \ref copyright file for more info. */ + +#include "ncdispatch.h" + +/** \name Enum Types + Functions to create and learn about enum types. */ +/*! \{ */ /* All these functions are part of this named group... */ + +/** \ingroup user_types +Create an enum type. Provide an ncid, a name, and a base integer type. + +After calling this function, fill out the type with repeated calls to +nc_insert_enum(). Call nc_insert_enum() once for each value you wish +to make part of the enumeration. + +\param ncid \ref ncid + +\param base_typeid The base integer type for this enum. Must be one +of: ::NC_BYTE, ::NC_UBYTE, ::NC_SHORT, ::NC_USHORT, ::NC_INT, +::NC_UINT, ::NC_INT64, ::NC_UINT64. + +\param name \ref object_name of new type. + +\param typeidp A pointer to an nc_type. The typeid of the new type +will be placed there. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_ENAMEINUSE That name is in use. +\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. +\returns ::NC_EBADNAME Name contains illegal characters. +\returns ::NC_EPERM Attempt to write to a read-only file. +\returns ::NC_ENOTINDEFINE Not in define mode. + */ +int +nc_def_enum(int ncid, nc_type base_typeid, const char *name, nc_type *typeidp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->def_enum(ncid,base_typeid,name,typeidp); +} + +/** \ingroup user_types +Insert a named member into a enum type. + +\param ncid \ref ncid +\param xtype +\param name The identifier (\ref object_name) of the new member. +\param value The value that is to be associated with this member. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_ENAMEINUSE That name is in use. +\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. +\returns ::NC_EBADNAME Name contains illegal characters. +\returns ::NC_EPERM Attempt to write to a read-only file. +\returns ::NC_ENOTINDEFINE Not in define mode. + */ +int +nc_insert_enum(int ncid, nc_type xtype, const char *name, + const void *value) +{ + NC *ncp; + int stat = NC_check_id(ncid, &ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->insert_enum(ncid, xtype, name, + value); +} + +/** \ingroup user_types +Learn about a user-define enumeration type. + +\param ncid \ref ncid + +\param xtype Typeid to inquire about. + +\param name \ref object_name of type will be copied here. \ref +ignored_if_null. + +\param base_nc_typep Typeid if the base type of the enum.\ref +ignored_if_null. + +\param base_sizep Pointer that will get the size in bytes of the base +type. \ref ignored_if_null. + +\param num_membersp Pointer that will get the number of members +defined for this enum type. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_enum(int ncid, nc_type xtype, char *name, nc_type *base_nc_typep, + size_t *base_sizep, size_t *num_membersp) +{ + int class = 0; + int stat = nc_inq_user_type(ncid, xtype, name, base_sizep, + base_nc_typep, num_membersp, &class); + if(stat != NC_NOERR) return stat; + if(class != NC_ENUM) stat = NC_EBADTYPE; + return stat; +} + +/** \ingroup user_types +Learn about a about a member of an enum type. + +\param ncid \ref ncid + +\param xtype Typeid of the enum type. + +\param idx Index to the member to inquire about. + +\param name The identifier (\ref object_name) of this member will be +copied here. \ref ignored_if_null. + +\param value The value of this member will be copied here. \ref +ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_enum_member(int ncid, nc_type xtype, int idx, char *name, + void *value) +{ + NC *ncp; + int stat = NC_check_id(ncid, &ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_enum_member(ncid, xtype, idx, name, value); +} + +/** \ingroup user_types +Get the name which is associated with an enum member value. + +\param ncid \ref ncid + +\param xtype Typeid of the enum type. + +\param value Value of interest. + +\param identifier The identifier (\ref object_name) of this value will +be copied here. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_enum_ident(int ncid, nc_type xtype, long long value, + char *identifier) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_enum_ident(ncid,xtype,value,identifier); +} +/*! \} */ /* End of named group ...*/ diff --git a/libdispatch/dopaque.c b/libdispatch/dopaque.c new file mode 100644 index 000000000..b9065afe5 --- /dev/null +++ b/libdispatch/dopaque.c @@ -0,0 +1,70 @@ +/*! \file + Functions for Opaque Types + + Copyright 2011 University Corporation for Atmospheric + Research/Unidata. See \ref copyright file for more info. */ + +#include "ncdispatch.h" + +/** \name Opaque Types + Functions to create and learn about opaque types. */ +/*! \{ */ /* All these functions are part of this named group... */ + +/** \ingroup user_types +Create an opaque type. Provide a size and a name. + +\param ncid \ref ncid +\param size The size of each opaque object in bytes. +\param name \ref object_name of the new type. +\param xtypep Pointer where the new typeid for this type is returned. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_ENAMEINUSE That name is in use. +\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. +\returns ::NC_EBADNAME Name contains illegal characters. +\returns ::NC_EPERM Attempt to write to a read-only file. +\returns ::NC_ENOTINDEFINE Not in define mode. + */ +int +nc_def_opaque(int ncid, size_t size, const char *name, nc_type *xtypep) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->def_opaque(ncid,size,name,xtypep); +} + +/** \ingroup user_types +Learn about an opaque type. + +\param ncid \ref ncid + +\param xtype Typeid to inquire about. + +\param name The \ref object_name of this type will be +copied here. \ref ignored_if_null. + +\param sizep The size of the type will be copied here. \ref +ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_opaque(int ncid, nc_type xtype, char *name, size_t *sizep) +{ + int class = 0; + int stat = nc_inq_user_type(ncid,xtype,name,sizep,NULL,NULL,&class); + if(stat != NC_NOERR) return stat; + if(class != NC_OPAQUE) stat = NC_EBADTYPE; + return stat; +} + +/*! \} */ /* End of named group ...*/ diff --git a/libdispatch/dtype.c b/libdispatch/dtype.c new file mode 100644 index 000000000..3594867a3 --- /dev/null +++ b/libdispatch/dtype.c @@ -0,0 +1,111 @@ +/*! \file + Functions for User-Defined Types + + Copyright 2011 University Corporation for Atmospheric + Research/Unidata. See \ref copyright file for more info. */ + +#include "ncdispatch.h" + +/** \internal +\ingroup user_types +Learn if two types are equal + +\param ncid1 \ref ncid of first typeid. +\param typeid1 First typeid. +\param ncid2 \ref ncid of second typeid. +\param typeid2 Second typeid. +\param equal Pointer to int. A non-zero value will be copied here if +the two types are equal, a zero if they are not equal. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_type_equal(int ncid1, nc_type typeid1, int ncid2, + nc_type typeid2, int *equal) +{ + NC* ncp1; + int stat = NC_check_id(ncid1,&ncp1); + if(stat != NC_NOERR) return stat; + return ncp1->dispatch->inq_type_equal(ncid1,typeid1,ncid2,typeid2,equal); +} + +/** \name Learning about User-Defined Types + + Functions to learn about any kind of user-defined type. */ +/*! \{ */ /* All these functions are part of this named group... */ + +/** \ingroup user_types + +Find a type by name. Given a group ID and a type name, find the ID of +the type. If the type is not found in the group, then the parents are +searched. If still not found, the entire file is searched. + +\param ncid \ref ncid +\param name \ref object_name of type to search for. +\param typeidp Typeid of named type will be copied here, if it is +found. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_typeid(int ncid, const char *name, nc_type *typeidp) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_typeid(ncid,name,typeidp); +} + +/** \ingroup user_types +Learn about a user defined type. + +Given an ncid and a typeid, get the information about a user defined +type. This function will work on any user defined type, whether +compound, opaque, enumeration, or variable length array. + +\param ncid \ref ncid + +\param xtype The typeid + +\param name The \ref object_name will be copied here. \ref +ignored_if_null. + +\param size the (in-memory) size of the type in bytes will be copied +here. VLEN type size is the size of nc_vlen_t. String size is returned +as the size of a character pointer. The size may be used to malloc +space for the data, no matter what the type. \ref ignored_if_null. + +\param base_nc_typep The base type will be copied here for enum and +VLEN types. \ref ignored_if_null. + +\param nfieldsp The number of fields will be copied here for enum and +compound types. \ref ignored_if_null. + +\param classp Return the class of the user defined type, ::NC_VLEN, +::NC_OPAQUE, ::NC_ENUM, or ::NC_COMPOUND. \ref ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_user_type(int ncid, nc_type xtype, char *name, size_t *size, + nc_type *base_nc_typep, size_t *nfieldsp, int *classp) +{ + NC *ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->inq_user_type(ncid, xtype, name, size, + base_nc_typep, nfieldsp, classp); +} +/*! \} */ /* End of named group ...*/ diff --git a/libdispatch/dvlen.c b/libdispatch/dvlen.c new file mode 100644 index 000000000..13d3560f0 --- /dev/null +++ b/libdispatch/dvlen.c @@ -0,0 +1,192 @@ +/*! \file + Functions for VLEN Types + + Copyright 2011 University Corporation for Atmospheric + Research/Unidata. See \ref copyright file for more info. */ + +#include "ncdispatch.h" + +/** \name Variable Length Array Types + + Functions to create and learn about VLEN types. */ +/*! \{ */ /* All these functions are part of this named group... */ + +/** +\ingroup user_types +Free memory in a VLEN object. + +When you read VLEN type the library will actually allocate the storage +space for the data. This storage space must be freed, so pass the +pointer back to this function, when you're done with the data, and it +will free the vlen memory. + +The function nc_free_vlens() is more useful than this function, +because it can free an array of VLEN objects. + +\param vl pointer to the vlen object. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +*/ +int +nc_free_vlen(nc_vlen_t *vl) +{ + free(vl->p); + return NC_NOERR; +} + +/** +\ingroup user_types +Free an array of vlens given the number of elements and an array. + +When you read VLEN type the library will actually allocate the storage +space for the data. This storage space must be freed, so pass the +pointer back to this function, when you're done with the data, and it +will free the vlen memory. + +\param len number of elements in the array. +\param vlens pointer to the vlen object. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +*/ +int +nc_free_vlens(size_t len, nc_vlen_t vlens[]) +{ + int ret; + size_t i; + + for(i = 0; i < len; i++) + if ((ret = nc_free_vlen(&vlens[i]))) + return ret; + + return NC_NOERR; +} + +/** +\ingroup user_types +Use this function to define a variable length array type. + +\param ncid \ref ncid +\param name \ref object_name of new type. + +\param base_typeid The typeid of the base type of the VLEN. For +example, for a VLEN of shorts, the base type is ::NC_SHORT. This can be +a user defined type. + +\param xtypep A pointer to an nc_type variable. The typeid of the new +VLEN type will be set here. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_ENAMEINUSE That name is in use. +\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME. +\returns ::NC_EBADNAME Name contains illegal characters. +\returns ::NC_EPERM Attempt to write to a read-only file. +\returns ::NC_ENOTINDEFINE Not in define mode. + */ +int +nc_def_vlen(int ncid, const char *name, nc_type base_typeid, nc_type *xtypep) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->def_vlen(ncid,name,base_typeid,xtypep); +} + +/** \ingroup user_types +Learn about a VLEN type. + +\param ncid \ref ncid +\param xtype The type of the VLEN to inquire about. +\param name \ref object_name of the type. \ref ignored_if_null. + +\param datum_sizep A pointer to a size_t, this will get the size of +one element of this vlen. \ref ignored_if_null. + +\param base_nc_typep Pointer to get the base type of the VLEN. \ref +ignored_if_null. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_inq_vlen(int ncid, nc_type xtype, char *name, size_t *datum_sizep, nc_type *base_nc_typep) +{ + int class = 0; + int stat = nc_inq_user_type(ncid,xtype,name,datum_sizep,base_nc_typep,NULL,&class); + if(stat != NC_NOERR) return stat; + if(class != NC_VLEN) stat = NC_EBADTYPE; + return stat; +} +/*! \} */ /* End of named group ...*/ + +/** \internal +\ingroup user_types + +Put a VLEN element. This function writes an element of a VLEN for the +Fortran APIs. + +\param ncid \ref ncid +\param typeid1 Typeid of the VLEN. +\param vlen_element Pointer to the element of the VLEN. +\param len Lenth of the VLEN element. +\param data VLEN data. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. +\returns ::NC_EPERM Attempt to write to a read-only file. + */ +int +nc_put_vlen_element(int ncid, int typeid1, void *vlen_element, size_t len, const void *data) +{ + NC* ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->put_vlen_element(ncid,typeid1,vlen_element,len,data); +} + +/** +\internal +\ingroup user_types + +Get a VLEN element. This function reads an element of a VLEN for the +Fortran APIs. + +\param ncid \ref ncid +\param typeid1 Typeid of the VLEN. +\param vlen_element Pointer to the element of the VLEN. +\param len Lenth of the VLEN element. +\param data VLEN data. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad \ref ncid. +\returns ::NC_EBADTYPE Bad type id. +\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled. +\returns ::NC_EHDFERR An error was reported by the HDF5 layer. + */ +int +nc_get_vlen_element(int ncid, int typeid1, const void *vlen_element, + size_t *len, void *data) +{ + NC *ncp; + int stat = NC_check_id(ncid,&ncp); + if(stat != NC_NOERR) return stat; + return ncp->dispatch->get_vlen_element(ncid, typeid1, vlen_element, + len, data); +} diff --git a/libdispatch/nc4.c b/libdispatch/nc4.c index d6fd2209a..2e02a5cb9 100644 --- a/libdispatch/nc4.c +++ b/libdispatch/nc4.c @@ -37,181 +37,6 @@ type). Read attributes of the new type with nc_get_att (see */ /** \{ */ -/** Free memory in a VLEN object. - -When you read VLEN type the library will actually allocate the storage -space for the data. This storage space must be freed, so pass the -pointer back to this function, when you're done with the data, and it -will free the vlen memory. - -The function nc_free_vlens() is more useful than this function, -because it can free an array of VLEN objects. - -\param vl pointer to the vlen object. - -\returns ::NC_NOERR No error. -*/ -int -nc_free_vlen(nc_vlen_t *vl) -{ - free(vl->p); - return NC_NOERR; -} - -/** Free an array of vlens given the number of elements and an array. - -When you read VLEN type the library will actually allocate the storage -space for the data. This storage space must be freed, so pass the -pointer back to this function, when you're done with the data, and it -will free the vlen memory. - -\param len number of elements in the array. -\param vlens pointer to the vlen object. - -\returns ::NC_NOERR No error. -*/ -int -nc_free_vlens(size_t len, nc_vlen_t vlens[]) -{ - int ret; - size_t i; - - for(i = 0; i < len; i++) - if ((ret = nc_free_vlen(&vlens[i]))) - return ret; - - return NC_NOERR; -} - -int -nc_inq_type_equal(int ncid1, nc_type typeid1, int ncid2, - nc_type typeid2, int *equal) -{ - NC* ncp1; - int stat = NC_check_id(ncid1,&ncp1); - if(stat != NC_NOERR) return stat; - return ncp1->dispatch->inq_type_equal(ncid1,typeid1,ncid2,typeid2,equal); -} - -int -nc_inq_typeid(int ncid, const char *name, nc_type *typeidp) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->inq_typeid(ncid,name,typeidp); -} - -int -nc_def_vlen(int ncid, const char *name, nc_type base_typeid, nc_type *xtypep) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->def_vlen(ncid,name,base_typeid,xtypep); -} - -int -nc_inq_vlen(int ncid, nc_type xtype, char *name, size_t *datum_sizep, nc_type *base_nc_typep) -{ - int class = 0; - int stat = nc_inq_user_type(ncid,xtype,name,datum_sizep,base_nc_typep,NULL,&class); - if(stat != NC_NOERR) return stat; - if(class != NC_VLEN) stat = NC_EBADTYPE; - return stat; -} - -int -nc_put_vlen_element(int ncid, int typeid1, void *vlen_element, size_t len, const void *data) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->put_vlen_element(ncid,typeid1,vlen_element,len,data); -} - -int -nc_get_vlen_element(int ncid, int typeid1, const void *vlen_element, size_t *len, void *data) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->get_vlen_element(ncid,typeid1,vlen_element,len,data); -} - -int -nc_inq_user_type(int ncid, nc_type xtype, char *name, size_t *size, nc_type *base_nc_typep, size_t *nfieldsp, int *classp) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->inq_user_type(ncid,xtype,name,size,base_nc_typep,nfieldsp,classp); -} - -int -nc_def_enum(int ncid, nc_type base_typeid, const char *name, nc_type *typeidp) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->def_enum(ncid,base_typeid,name,typeidp); -} - -int -nc_insert_enum(int ncid, nc_type xtype, const char *name, const void *value) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->insert_enum(ncid,xtype,name,value); -} - -int -nc_inq_enum(int ncid, nc_type xtype, char *name, nc_type *base_nc_typep, size_t *base_sizep, size_t *num_membersp) -{ - int class = 0; - int stat = nc_inq_user_type(ncid,xtype,name,base_sizep,base_nc_typep,num_membersp,&class); - if(stat != NC_NOERR) return stat; - if(class != NC_ENUM) stat = NC_EBADTYPE; - return stat; -} - -int -nc_inq_enum_member(int ncid, nc_type xtype, int idx, char *name, void *value) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->inq_enum_member(ncid,xtype,idx,name,value); -} - -int -nc_inq_enum_ident(int ncid, nc_type xtype, long long value, char *identifier) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->inq_enum_ident(ncid,xtype,value,identifier); -} - -int -nc_def_opaque(int ncid, size_t size, const char *name, nc_type *xtypep) -{ - NC* ncp; - int stat = NC_check_id(ncid,&ncp); - if(stat != NC_NOERR) return stat; - return ncp->dispatch->def_opaque(ncid,size,name,xtypep); -} - -int -nc_inq_opaque(int ncid, nc_type xtype, char *name, size_t *sizep) -{ - int class = 0; - int stat = nc_inq_user_type(ncid,xtype,name,sizep,NULL,NULL,&class); - if(stat != NC_NOERR) return stat; - if(class != NC_OPAQUE) stat = NC_EBADTYPE; - return stat; -} /** \} */ /** \defgroup groups Groups