User defined types allow for more complex data structures.
More...
|
int | nc_get_vlen_element (int ncid, int typeid1, const void *vlen_element, size_t *len, void *data) |
|
int | nc_inq_type_equal (int ncid1, nc_type typeid1, int ncid2, nc_type typeid2, int *equal) |
|
int | nc_put_vlen_element (int ncid, int typeid1, void *vlen_element, size_t len, const void *data) |
|
|
Functions to create and learn about compound types.
|
int | nc_def_compound (int ncid, size_t size, const char *name, nc_type *typeidp) |
|
int | nc_insert_compound (int ncid, nc_type xtype, const char *name, size_t offset, nc_type field_typeid) |
|
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) |
|
int | nc_inq_compound (int ncid, nc_type xtype, char *name, size_t *sizep, size_t *nfieldsp) |
|
int | nc_inq_compound_name (int ncid, nc_type xtype, char *name) |
|
int | nc_inq_compound_size (int ncid, nc_type xtype, size_t *sizep) |
|
int | nc_inq_compound_nfields (int ncid, nc_type xtype, size_t *nfieldsp) |
|
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) |
|
int | nc_inq_compound_fieldname (int ncid, nc_type xtype, int fieldid, char *name) |
|
int | nc_inq_compound_fieldoffset (int ncid, nc_type xtype, int fieldid, size_t *offsetp) |
|
int | nc_inq_compound_fieldtype (int ncid, nc_type xtype, int fieldid, nc_type *field_typeidp) |
|
int | nc_inq_compound_fieldndims (int ncid, nc_type xtype, int fieldid, int *ndimsp) |
|
int | nc_inq_compound_fielddim_sizes (int ncid, nc_type xtype, int fieldid, int *dim_sizesp) |
|
int | nc_inq_compound_fieldindex (int ncid, nc_type xtype, const char *name, int *fieldidp) |
|
|
Functions to create and learn about enum types.
|
int | nc_def_enum (int ncid, nc_type base_typeid, const char *name, nc_type *typeidp) |
|
int | nc_insert_enum (int ncid, nc_type xtype, const char *name, const void *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 | nc_inq_enum_member (int ncid, nc_type xtype, int idx, char *name, void *value) |
|
int | nc_inq_enum_ident (int ncid, nc_type xtype, long long value, char *identifier) |
|
User defined types allow for more complex data structures.
NetCDF-4 has added support for four different user defined data types. User defined type may only be used in files created with the NC_NETCDF4 and without NC_CLASSIC_MODEL.
- compound type: like a C struct, a compound type is a collection of types, including other user defined types, in one package.
- variable length array type: used to store ragged arrays.
- opaque type: This type has only a size per element, and no other type information.
- enum type: Like an enumeration in C, this type lets you assign text values to integer values, and store the integer values.
Users may construct user defined type with the various nc_def_* functions described in this section. They may learn about user defined types by using the nc_inq_ functions defined in this section.
Once types are constructed, define variables of the new type with nc_def_var (see nc_def_var). Write to them with nc_put_var1, nc_put_var, nc_put_vara, or nc_put_vars. Read data of user-defined type with nc_get_var1, nc_get_var, nc_get_vara, or nc_get_vars (see Variables).
Create attributes of the new type with nc_put_att (see nc_put_att_ type). Read attributes of the new type with nc_get_att (see Attributes).
◆ nc_def_compound()
int nc_def_compound |
( |
int |
ncid, |
|
|
size_t |
size, |
|
|
const char * |
name, |
|
|
nc_type * |
typeidp |
|
) |
| |
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.
- Parameters
-
ncid | NetCDF ID |
size | The size, in bytes, of the compound type. |
name | object_name of the created type. |
typeidp | The type ID of the new type is copied here. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENAMEINUSE That name is in use.
-
NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
-
NC_EBADNAME Name contains illegal characters.
-
NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file.
-
NC_ENOTNC4 This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see nc_open).
-
NC_EHDFERR An error was reported by the HDF5 layer.
-
NC_EPERM Attempt to write to a read-only file.
-
NC_ENOTINDEFINE Not in define mode.
Example
struct s1
{
int i1;
int i2;
};
struct s1 data[DIM_LEN], data_in[DIM_LEN];
HOFFSET(
struct s1, i1),
NC_INT)) ERR;
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;
Definition at line 63 of file dcompound.c.
◆ nc_def_enum()
int nc_def_enum |
( |
int |
ncid, |
|
|
nc_type |
base_typeid, |
|
|
const char * |
name, |
|
|
nc_type * |
typeidp |
|
) |
| |
◆ nc_def_opaque()
int nc_def_opaque |
( |
int |
ncid, |
|
|
size_t |
size, |
|
|
const char * |
name, |
|
|
nc_type * |
xtypep |
|
) |
| |
◆ nc_def_vlen()
int nc_def_vlen |
( |
int |
ncid, |
|
|
const char * |
name, |
|
|
nc_type |
base_typeid, |
|
|
nc_type * |
xtypep |
|
) |
| |
Use this function to define a variable length array type.
- Parameters
-
ncid | NetCDF ID |
name | object_name of new type. |
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. |
xtypep | A pointer to an nc_type variable. The typeid of the new VLEN type will be set here. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer.
-
NC_ENAMEINUSE That name is in use.
-
NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
-
NC_EBADNAME Name contains illegal characters.
-
NC_EPERM Attempt to write to a read-only file.
-
NC_ENOTINDEFINE Not in define mode.
Definition at line 110 of file dvlen.c.
◆ nc_free_vlen()
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.
WARNING: this code is incorrect because it will only work if the basetype of the vlen is
- atomic
- + enum
- + opaque
- excluding string basetype,
The reason is that to operate properly, it needs to recurse when the basetype is a complex object such as another vlen or compound.
- Parameters
-
vl | pointer to the vlen object. |
- Returns
- NC_NOERR No error.
Definition at line 41 of file dvlen.c.
◆ nc_free_vlens()
int nc_free_vlens |
( |
size_t |
len, |
|
|
nc_vlen_t |
vlens[] |
|
) |
| |
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.
WARNING: this code is incorrect because it will only work if the basetype of the vlen is
- atomic
- + enum
- + opaque
- excluding string basetype,
The reason is that to operate properly, it needs to recurse when the basetype is a complex object such as another vlen or compound.
- Parameters
-
len | number of elements in the array. |
vlens | pointer to the vlen object. |
- Returns
- NC_NOERR No error.
Definition at line 72 of file dvlen.c.
◆ nc_get_vlen_element()
int nc_get_vlen_element |
( |
int |
ncid, |
|
|
int |
typeid1, |
|
|
const void * |
vlen_element, |
|
|
size_t * |
len, |
|
|
void * |
data |
|
) |
| |
Get a VLEN element. This function reads an element of a VLEN for the Fortran APIs.
- Parameters
-
ncid | NetCDF ID |
typeid1 | Typeid of the VLEN. |
vlen_element | Pointer to the element of the VLEN. |
len | Length of the VLEN element. |
data | VLEN data. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer.
Definition at line 196 of file dvlen.c.
◆ nc_inq_compound()
int nc_inq_compound |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
char * |
name, |
|
|
size_t * |
sizep, |
|
|
size_t * |
nfieldsp |
|
) |
| |
◆ nc_inq_compound_field()
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_inq_compound_fielddim_sizes()
int nc_inq_compound_fielddim_sizes |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
int |
fieldid, |
|
|
int * |
dim_sizesp |
|
) |
| |
◆ nc_inq_compound_fieldindex()
int nc_inq_compound_fieldindex |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
const char * |
name, |
|
|
int * |
fieldidp |
|
) |
| |
◆ nc_inq_compound_fieldname()
int nc_inq_compound_fieldname |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
int |
fieldid, |
|
|
char * |
name |
|
) |
| |
◆ nc_inq_compound_fieldndims()
int nc_inq_compound_fieldndims |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
int |
fieldid, |
|
|
int * |
ndimsp |
|
) |
| |
◆ nc_inq_compound_fieldoffset()
int nc_inq_compound_fieldoffset |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
int |
fieldid, |
|
|
size_t * |
offsetp |
|
) |
| |
◆ nc_inq_compound_fieldtype()
int nc_inq_compound_fieldtype |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
int |
fieldid, |
|
|
nc_type * |
field_typeidp |
|
) |
| |
◆ nc_inq_compound_name()
int nc_inq_compound_name |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
char * |
name |
|
) |
| |
◆ nc_inq_compound_nfields()
int nc_inq_compound_nfields |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
size_t * |
nfieldsp |
|
) |
| |
◆ nc_inq_compound_size()
int nc_inq_compound_size |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
size_t * |
sizep |
|
) |
| |
◆ nc_inq_enum()
int nc_inq_enum |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
char * |
name, |
|
|
nc_type * |
base_nc_typep, |
|
|
size_t * |
base_sizep, |
|
|
size_t * |
num_membersp |
|
) |
| |
◆ nc_inq_enum_ident()
int nc_inq_enum_ident |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
long long |
value, |
|
|
char * |
identifier |
|
) |
| |
Get the name which is associated with an enum member value.
- Parameters
-
ncid | NetCDF ID |
xtype | Typeid of the enum type. |
value | Value of interest. |
identifier | The identifier (object_name) of this value will be copied here. Ignored if NULL. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer.
Definition at line 168 of file denum.c.
◆ nc_inq_enum_member()
int nc_inq_enum_member |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
int |
idx, |
|
|
char * |
name, |
|
|
void * |
value |
|
) |
| |
◆ nc_inq_opaque()
int nc_inq_opaque |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
char * |
name, |
|
|
size_t * |
sizep |
|
) |
| |
◆ nc_inq_type_equal()
int nc_inq_type_equal |
( |
int |
ncid1, |
|
|
nc_type |
typeid1, |
|
|
int |
ncid2, |
|
|
nc_type |
typeid2, |
|
|
int * |
equal |
|
) |
| |
Learn if two types are equal.
- Note
- User-defined types in netCDF-4/HDF5 files must be committed to the file before nc_inq_type_equal() will work on the type. For uncommitted user-defined types, nc_inq_type_equal() will return NC_EHDFERR. Commit types to the file with a call to nc_enddef().
- Parameters
-
ncid1 | NetCDF ID of first typeid. |
typeid1 | First typeid. |
ncid2 | NetCDF ID of second typeid. |
typeid2 | Second typeid. |
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.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer. This will occur if either of the types have not been committed to the file (with an nc_enddef()).
- Author
- Dennis Heimbigner, Ward Fisher, Ed Hartnett
Definition at line 69 of file dtype.c.
◆ nc_inq_typeid()
int nc_inq_typeid |
( |
int |
ncid, |
|
|
const char * |
name, |
|
|
nc_type * |
typeidp |
|
) |
| |
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.
- Parameters
-
ncid | NetCDF ID |
name | object_name of type to search for. |
typeidp | Typeid of named type will be copied here, if it is found. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer.
- Author
- Ed Hartnett, Dennis Heimbigner
Definition at line 102 of file dtype.c.
◆ nc_inq_user_type()
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 |
|
) |
| |
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.
- Parameters
-
ncid | NetCDF ID |
xtype | The typeid |
name | The object_name will be copied here. Ignored if NULL. |
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. Ignored if NULL. |
base_nc_typep | The base type will be copied here for enum and VLEN types. Ignored if NULL. |
nfieldsp | The number of fields will be copied here for enum and compound types. Ignored if NULL. |
classp | Return the class of the user defined type, NC_VLEN, NC_OPAQUE, NC_ENUM, or NC_COMPOUND. Ignored if NULL. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer.
- Author
- Ed Hartnett, Dennis Heimbigner
Definition at line 146 of file dtype.c.
◆ nc_inq_vlen()
int nc_inq_vlen |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
char * |
name, |
|
|
size_t * |
datum_sizep, |
|
|
nc_type * |
base_nc_typep |
|
) |
| |
◆ nc_insert_array_compound()
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 |
|
) |
| |
Insert a named array field into a compound type.
- Parameters
-
ncid | NetCDF ID |
xtype | The typeid for this compound type, as returned by nc_def_compound(), or nc_inq_var(). |
name | The object_name of the new field. |
offset | Offset in byte from the beginning of the compound type for this field. |
field_typeid | The type of the field to be inserted. |
ndims | Number of dimensions in array. |
dim_sizes | Array of dimension sizes. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENAMEINUSE That name is in use.
-
NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
-
NC_EBADNAME Name contains illegal characters.
-
NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer.
-
NC_EPERM Attempt to write to a read-only file.
-
NC_ENOTINDEFINE Not in define mode.
Definition at line 141 of file dcompound.c.
◆ nc_insert_compound()
int nc_insert_compound |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
const char * |
name, |
|
|
size_t |
offset, |
|
|
nc_type |
field_typeid |
|
) |
| |
◆ nc_insert_enum()
int nc_insert_enum |
( |
int |
ncid, |
|
|
nc_type |
xtype, |
|
|
const char * |
name, |
|
|
const void * |
value |
|
) |
| |
◆ nc_put_vlen_element()
int nc_put_vlen_element |
( |
int |
ncid, |
|
|
int |
typeid1, |
|
|
void * |
vlen_element, |
|
|
size_t |
len, |
|
|
const void * |
data |
|
) |
| |
Put a VLEN element. This function writes an element of a VLEN for the Fortran APIs.
- Parameters
-
ncid | NetCDF ID |
typeid1 | Typeid of the VLEN. |
vlen_element | Pointer to the element of the VLEN. |
len | Length of the VLEN element. |
data | VLEN data. |
- Returns
- NC_NOERR No error.
-
NC_EBADID Bad NetCDF ID.
-
NC_EBADTYPE Bad type id.
-
NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
-
NC_EHDFERR An error was reported by the HDF5 layer.
-
NC_EPERM Attempt to write to a read-only file.
Definition at line 168 of file dvlen.c.