netcdf-c/libdispatch/dcompound.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 ...*/