mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-21 03:13:42 +08:00
1e9f243f85
Initial split of Guide from rest of documentation. Using 'tagfiles' to cross-reference from one documentation set to the other works, but then it drags all of the 'external' related pages into the index of the other. Modified visability of the external groups and pages. Adding proper section names to 'Example' sections, to avoid Doxygen warnings. Initial split of Guide from rest of documentation. Using 'tagfiles' to cross-reference from one documentation set to the other works, but then it drags all of the 'external' related pages into the index of the other. Modified visability of the external groups and pages. Adding proper section names to 'Example' sections, to avoid Doxygen warnings. Reorganizing documentation into two separate doxygen projects. Moved .texi documents into an old directory. Pulled the tutorial document into a separate document, similar to the guide document. Turned on treeview
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 nc_def_compound_example 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 ...*/
|
|
|
|
|
|
|
|
|
|
|
|
|