mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-21 03:13:42 +08:00
490 lines
14 KiB
C
490 lines
14 KiB
C
/*! \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 ...*/
|
|
|
|
|
|
|
|
|
|
|
|
|