Enumerations
enum	coda_type_class_enum { coda_record_class , coda_array_class , coda_integer_class , coda_real_class , coda_text_class , coda_raw_class , coda_special_class }

enum	coda_special_type_enum { coda_special_no_data , coda_special_vsf_integer , coda_special_time , coda_special_complex }

enum	coda_native_type_enum { coda_native_type_not_available = -1 , coda_native_type_int8 , coda_native_type_uint8 , coda_native_type_int16 , coda_native_type_uint16 , coda_native_type_int32 , coda_native_type_uint32 , coda_native_type_int64 , coda_native_type_uint64 , coda_native_type_float , coda_native_type_double , coda_native_type_char , coda_native_type_string , coda_native_type_bytes }

Functions
const char *	coda_type_get_format_name (coda_format format)

const char *	coda_type_get_class_name (coda_type_class type_class)

const char *	coda_type_get_native_type_name (coda_native_type native_type)

const char *	coda_type_get_special_type_name (coda_special_type special_type)

int	coda_type_has_attributes (const coda_type type, int has_attributes)

int	coda_type_get_format (const coda_type type, coda_format format)

int	coda_type_get_class (const coda_type type, coda_type_class type_class)

int	coda_type_get_read_type (const coda_type type, coda_native_type read_type)

int	coda_type_get_string_length (const coda_type type, long length)

int	coda_type_get_bit_size (const coda_type type, int64_t bit_size)

int	coda_type_get_name (const coda_type type, const char *name)

int	coda_type_get_description (const coda_type type, const char *description)

int	coda_type_get_unit (const coda_type type, const char *unit)

int	coda_type_get_fixed_value (const coda_type type, const char fixed_value, long length)

int	coda_type_get_attributes (const coda_type type, coda_type *attributes)

int	coda_type_get_num_record_fields (const coda_type type, long num_fields)

int	coda_type_get_record_field_index_from_name (const coda_type type, const char name, long *index)

int	coda_type_get_record_field_index_from_real_name (const coda_type type, const char real_name, long *index)

int	coda_type_get_record_field_type (const coda_type type, long index, coda_type *field_type)

int	coda_type_get_record_field_name (const coda_type type, long index, const char *name)

int	coda_type_get_record_field_real_name (const coda_type type, long index, const char *real_name)

int	coda_type_get_record_field_hidden_status (const coda_type type, long index, int hidden)

int	coda_type_get_record_field_available_status (const coda_type type, long index, int available)

int	coda_type_get_record_union_status (const coda_type type, int is_union)

int	coda_type_get_array_num_dims (const coda_type type, int num_dims)

int	coda_type_get_array_dim (const coda_type type, int num_dims, long dim[])

int	coda_type_get_array_base_type (const coda_type type, coda_type *base_type)

int	coda_type_get_special_type (const coda_type type, coda_special_type special_type)

int	coda_type_get_special_base_type (const coda_type type, coda_type *base_type)

Detailed Description

Each data element or group of data elements (such as an array or record) in a product file has a unique description, in CODA. This description is independent of the file format of the product (e.g. ascii, binary, XML, netCDF, etc.) Each of those descriptions is referred to as a CODA type (which is of type coda_type). For self describing formats such as netCDF, HDF4, and HDF5 files the type definition is taken from the products themselves. For other formats, such as ascii and binary products the type definition is fixed and is provided by .codadef files. For some file formats CODA can use a predefined format stored in a .codadef file to further restricit the format of a self describing file. For XML files, for instance, CODA will treat all 'leaf elements' as ascii text if no definition for the product is available in a .codadef. However, with a definition, CODA will know how to interpret the 'leaf elements' (i.e. whether the content of an XML element should be a string, an integer, a time value, etc.).

As an example, there is a type that describes the MPH of an ENVISAT product (which is a record). This record contains a name, a textual description, the number of fields, and for each of the fields the field name and (again) a CODA type describing that field.

CODA types are grouped into several classes (coda_type_class). The available classes are:

record (coda_record_class)
array (coda_array_class)
integer (coda_integer_class)
real (coda_real_class)
text (coda_text_class)
raw (coda_raw_class)
special (coda_special_class)

The record and array types are the compound types that structurally define the product. It is possible to have records which fields are again records or arrays and arrays may have again arrays or records as elements. At the deepest level of a product tree (i.e. the 'leaf elements') you will allways find a basic type. These basic types are represented by the classes integer, real, text, and raw for respectively integer numbers, floating point numbers, text strings, and series of uninterpreted bytes.

For each of the basic type classes you can use the coda_type_get_read_type() function to determine the best native type (coda_native_type) in which to store the data as it is read from file into memory. The native types contain signed and unsigned integers ranging from 8 to 64 bits, the float and double types, char and string for textual information, and a special bytes type for raw data.

Finally, CODA also supports several special data types (coda_special_class, coda_special_type). These are types that provide a mapping from the data in a product to a more convenient type for you as user. For example, there is a special time type that converts the many time formats that are used in products to a double value representing the amount of seconds since 2000-01-01T00:00:00.000000, which is the default time format in CODA. When you encounter a special type you can always use the coda_type_get_special_base_type() function to bypass the special interpretation of the data and look at the data in its actual form (e.g. for an ASCII time string you will get a coda_text_class type).

CODA is able to deal with many dynamic properties that can be encountered in product files. Some of these dynamic properties are: the size of arrays, the availabillity of optional record fields, the bit/byte offset of record fields, and the size of string data or raw data. For data types where these properties are dynamic, you will only be able to retrieve the actual size/availabillity/etc. by moving a cursor to the data element and use the CODA Cursor functions to retrieve the requested property (e.g. if the size of an array is not fixed, coda_type_get_array_dim() will return a dimension value of -1 and coda_cursor_get_array_dim() will return the real dimension value).

More information about the CODA types and descriptions of the mappings of self describing formats to CODA types can be found in other parts of the CODA documentation that is included with the CODA package.

Enumeration Type Documentation

◆ coda_native_type_enum

enum coda_native_type_enum

Enumerator
coda_native_type_not_available	native type value for compound entities that can not be read directly
coda_native_type_int8	8 bit signed integer (coda_integer_class)
coda_native_type_uint8	8 bit unsigned integer (coda_integer_class)
coda_native_type_int16	16 bit signed integer (coda_integer_class)
coda_native_type_uint16	16 bit unsigned integer (coda_integer_class)
coda_native_type_int32	32 bit signed integer (coda_integer_class)
coda_native_type_uint32	32 bit unsigned integer (coda_integer_class)
coda_native_type_int64	64 bit signed integer (coda_integer_class)
coda_native_type_uint64	64 bit unsigned integer (coda_integer_class)
coda_native_type_float	32 bit IEEE floating point type (coda_real_class)
coda_native_type_double	64 bit IEEE floating point type (coda_real_class)
coda_native_type_char	single character (coda_text_class)
coda_native_type_string	string (coda_text_class)
coda_native_type_bytes	series of uninterpreted bytes (coda_raw_class)

◆ coda_special_type_enum

enum coda_special_type_enum

Enumerator
coda_special_no_data	No data (data object is not available)
coda_special_vsf_integer	A compound containing a variable scale factor and an integer. The returned double value equals: integer_value x 10^(-scale_factor)
coda_special_time	Data specifying a date/time value
coda_special_complex	Data consisting of a real and imaginary value

◆ coda_type_class_enum

enum coda_type_class_enum

Enumerator
coda_record_class	Class of all record types
coda_array_class	Class of all array types
coda_integer_class	Class of all integer types
coda_real_class	Class of all real (floating point) types
coda_text_class	Class of all text types
coda_raw_class	Class of all unformatted types (data that is not interpreted)
coda_special_class	Class of all special data types (such as time and complex)

Function Documentation

◆ coda_type_get_array_base_type()

int coda_type_get_array_base_type	(	const coda_type *	type,
		coda_type **	base_type )

Get the CODA type for the elements of an array. If the type is not an array class the function will return an error.

Parameters

type	CODA type.
base_type	Pointer to the variable where the base type will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_array_dim()

int coda_type_get_array_dim	(	const coda_type *	type,
		int *	num_dims,
		long	dim[] )

Retrieve the dimensions with a constant value for an array. The function returns both the number of dimensions num_dims and the size for each of the dimensions dim that have a constant/fixed size.

Note: If the size of a dimension is variable (it differs per product or differs per occurrence inside one product) then this function will set the value for that dimension to -1. Otherwise it will set the dimension entry in dim to the constant value for that dimension as defined by the CODA product format definition. Variable dimension sizes can only occur when a CODA product format definition is used. If the type is not an array class the function will return an error.

Parameters

type	CODA type.
num_dims	Pointer to the variable where the number of dimensions will be stored.
dim	Pointer to the variable where the dimensions will be stored. Dimensions that will vary per product or within a product will have value `-1`. The caller needs to make sure that the variable has enough room to store the dimensions array. It is guaranteed that the number of dimensions will never exceed CODA_MAX_NUM_DIMS.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_array_num_dims()

int coda_type_get_array_num_dims	(	const coda_type *	type,
		int *	num_dims )

Get the number of dimensions for an array. If the type is not an array class the function will return an error.

Parameters

type	CODA type.
num_dims	Pointer to the variable where the number of dimensions will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_attributes()

int coda_type_get_attributes	(	const coda_type *	type,
		coda_type **	attributes )

Get the type for the associated attribute record. Note that this record may not have any fields if there are no attributes for this type.

Parameters

type	CODA type.
attributes	Pointer to the variable where the pointer to the type defining the attribute record will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_bit_size()

int coda_type_get_bit_size	(	const coda_type *	type,
		int64_t *	bit_size )

Get the bit size for the data type. Depending on the type of data and its format this function will return the following: For data in ascii or binary format all data types will return the amount of bits the data occupies in the product file. This means that e.g. ascii floats and ascii integers will return 8 times the byte size of the ascii representation, records and arrays return the sum of the bit sizes of their fields/array-elements. For XML data you will be able to retrieve bit sizes for all data except arrays and attribute records. You will not be able to retrieve bit/byte sizes for data in netCDF, HDF4, or HDF5 format. If the size is not fixed and can only be determined from information inside a product then bit_size will be set to -1.

Parameters

type	CODA type.
bit_size	Pointer to a variable where the bit size will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_class()

int coda_type_get_class	(	const coda_type *	type,
		coda_type_class *	type_class )

Get the class of a type.

Parameters

type	CODA type.
type_class	Pointer to a variable where the type class will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_class_name()

const char * coda_type_get_class_name ( coda_type_class type_class )

Returns the name of a type class. In case the type class is not recognised the string "unknown" is returned.

Parameters

type_class CODA type class

Returns: if the type class is known a string containing the name of the class, otherwise the string "unknown".

◆ coda_type_get_description()

int coda_type_get_description	(	const coda_type *	type,
		const char **	description )

Get the description of a type. If the type does not have a description a NULL pointer will be returned. The description parameter will either be a NULL pointer or a 0 terminated string.

Parameters

type	CODA type.
description	Pointer to the variable where the description of the type will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_fixed_value()

int coda_type_get_fixed_value	(	const coda_type *	type,
		const char **	fixed_value,
		long *	length )

Get the associated fixed value string of a type if it has one. Fixed values will only occur for coda_text_class and coda_raw_class types and only for ascii, binary, or xml formatted data (in all other cases a NULL pointer will be returned). It is possible to pass a NULL pointer for the length parameter to omit the retrieval of the length. If the type does not have a fixed value a NULL pointer will be returned and the length parameter (if it is not a NULL pointer) will be set to 0. For ascii and xml data the fixed_value will be a 0 terminated string. For binary data there will not be a 0 termination character. Since fixed values for raw data can contain \0 values you should use the returned length parameter to determine the size of the fixed value. The length parameter will contain the length of the fixed value without taking a terminating '\0' into account.

Parameters

type	CODA type.
fixed_value	Pointer to the variable where the pointer to the fixed value for the type will be stored.
length	Pointer to the variable where the string length of the fixed value will be stored (can be NULL).

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_format()

int coda_type_get_format	(	const coda_type *	type,
		coda_format *	format )

Get the storage format of a type.

Parameters

type	CODA type.
format	Pointer to a variable where the format will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_format_name()

const char * coda_type_get_format_name ( coda_format format )

Returns the name of a storage format.

Parameters

format CODA storage format

Returns: if the format is known a string containing the name of the format, otherwise the string "unknown".

◆ coda_type_get_name()

int coda_type_get_name	(	const coda_type *	type,
		const char **	name )

Get the name of a type. A type can have an optional name that uniquely defines it within a product class. This is something that is used internally within CODA to allow reuse of type definitions. If a type has a name, only a single instance of the definition will be used for all places where the type is used (i.e. a single coda_type object will be used for all cases where this type is used). For this reason type names are unique within the scope of a product class. You should never rely in your code on types having a specific name, or having a name at all. The internal type reuse approach within a product class may change unannounced. If the type is unnamed a NULL pointer will be returned. The name parameter will either be a NULL pointer or a 0 terminated string.

Parameters

type	CODA type.
name	Pointer to the variable where the name of the type will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_native_type_name()

const char * coda_type_get_native_type_name ( coda_native_type native_type )

Returns the name of a native type. In case the native type is not recognised the string "unknown" is returned.

Note: Mind that there is also a special native type coda_native_type_not_available which will result in the string 'N/A'.

Parameters

native_type CODA native type

Returns: if the native type is known a string containing the name of the native type, otherwise the string "unknown".

◆ coda_type_get_num_record_fields()

int coda_type_get_num_record_fields	(	const coda_type *	type,
		long *	num_fields )

Get the number of fields of a record type. If the type is not a record class the function will return an error.

Parameters

type	CODA type.
num_fields	Pointer to a variable where the number of fields will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_read_type()

int coda_type_get_read_type	(	const coda_type *	type,
		coda_native_type *	read_type )

Get the best native type for reading data of a CODA type. The native type that is returned indicates which storage type can best be used when reading data of this CODA type to memory. Compound types (arrays and records) that can be read directly (using a raw byte array) will return a read type coda_native_type_bytes. If a type can not be read directly (e.g. compound types in XML, netCDF, HDF4, and HDF5 products) the special native type value coda_native_type_not_available will be returned.

Note: Be aware that types of class coda_integer_class can return a native type coda_native_type_double if the integer type has a conversion associated with it and conversions are enabled.

See also: coda_set_option_perform_conversions()

Parameters

type	CODA type.
read_type	Pointer to a variable where the native type for reading will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_field_available_status()

int coda_type_get_record_field_available_status	(	const coda_type *	type,
		long	index,
		int *	available )

Get the available status of a record field. If the type is not a record class the function will return an error. The available status is only applicable for data in ascii, binary, or XML format (fields are always available for netCDF, HDF4, and HDF5 data). The available status is a dynamic property and can thus only really be determined using the function coda_cursor_get_record_field_available_status(). The coda_type_get_record_field_hidden_status() function, however, indicates whether the availability of a field is dynamic or not. If it is not dynamic (i.e. it is always available) available will be 1, if not (i.e. it has to be determined dynamically) available will be -1.

Parameters

type	CODA type.
index	Field index (0 <= index < number of fields).
available	Pointer to the variable where the available status of the record field will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_field_hidden_status()

int coda_type_get_record_field_hidden_status	(	const coda_type *	type,
		long	index,
		int *	hidden )

Get the hidden status of a record field. If the type is not a record class the function will return an error. The hidden property is only applicable for ascii, binary, and xml data (fields can not be hidden for other formats). If the record field has the hidden property hidden will be set to 1, otherwise it will be set to 0.

Note: The C API of CODA does not hide record fields itself. This property is used by interfaces on top of the CODA C interface (such as the MATLAB and IDL interfaces) to eliminate hidden fields when retrieving complete records.

Parameters

type	CODA type.
index	Field index (0 <= index < number of fields).
hidden	Pointer to the variable where the hidden status of the record field will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_field_index_from_name()

int coda_type_get_record_field_index_from_name	(	const coda_type *	type,
		const char *	name,
		long *	index )

Get the field index from a field name for a record type. If the type is not a record class the function will return an error.

Parameters

type	CODA type.
name	Name of the record field.
index	Pointer to a variable where the field index will be stored (0 <= index < number of fields).

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_field_index_from_real_name()

int coda_type_get_record_field_index_from_real_name	(	const coda_type *	type,
		const char *	real_name,
		long *	index )

Get the field index based on the 'real name' of the field for a record type. If the type is not a record class the function will return an error. If a field has no explicit 'real name' set, a match against the regular field name will be performed.

Parameters

type	CODA type.
real_name	Real name of the record field.
index	Pointer to a variable where the field index will be stored (0 <= index < number of fields).

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_field_name()

int coda_type_get_record_field_name	(	const coda_type *	type,
		long	index,
		const char **	name )

Get the name of a record field. If the type is not a record class the function will return an error. The name parameter will be 0 terminated.

Parameters

type	CODA type.
index	Field index (0 <= index < number of fields).
name	Pointer to the variable where the name of the record field will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_field_real_name()

int coda_type_get_record_field_real_name	(	const coda_type *	type,
		long	index,
		const char **	real_name )

Get the unaltered name of a record field. The real name of a field is the name of the field without the identifier restriction. For (partially) self-describing formats such as XML, HDF, and netCDF, the name of a field as used by CODA will actually be a conversion of the name of the stored element to something that conforms to the rules of an identifier (i.e. only allowing a-z, A-Z, 0-9 and underscores characters and names have to start with an alpha character). The real name property of a field represents the original name of the element (e.g. XML element name, HDF5 DataSet name, netCDF variable name, etc.). If the concept of a real name does not apply, this function will return the same result as coda_type_get_record_field_name().

If the type is not a record class the function will return an error. The real_name parameter will be 0 terminated.

Parameters

type	CODA type.
index	Field index (0 <= index < number of fields).
real_name	Pointer to the variable where the real name of the record field will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_field_type()

int coda_type_get_record_field_type	(	const coda_type *	type,
		long	index,
		coda_type **	field_type )

Get the CODA type for a record field. If the type is not a record class the function will return an error.

Parameters

type	CODA type.
index	Field index (0 <= index < number of fields).
field_type	Pointer to the variable where the type of the record field will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_record_union_status()

int coda_type_get_record_union_status	(	const coda_type *	type,
		int *	is_union )

Get the union status of a record. If the record is a union (i.e. all fields are dynamically available and only one field can be available at any time) is_union will be set to 1, otherwise it will be set to 0. If the type is not a record class the function will return an error.

Parameters

type	CODA type.
is_union	Pointer to a variable where the union status will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_special_base_type()

int coda_type_get_special_base_type	(	const coda_type *	type,
		coda_type **	base_type )

Get the base type for a special type. If the type is not a special type the function will return an error.

Parameters

type	CODA type.
base_type	Pointer to the variable where the base type will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_special_type()

int coda_type_get_special_type	(	const coda_type *	type,
		coda_special_type *	special_type )

Get the special type for a type. This function will return the specific special type for types of class coda_special_class. If the type is not a special type the function will return an error.

Parameters

type	CODA type.
special_type	Pointer to a variable where the special type will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_special_type_name()

const char * coda_type_get_special_type_name ( coda_special_type special_type )

Returns the name of a special type. In case the special type is not recognised the string "unknown" is returned.

Parameters

special_type CODA special type

Returns: if the special type is known a string containing the name of the special type, otherwise the string "unknown".

◆ coda_type_get_string_length()

int coda_type_get_string_length	(	const coda_type *	type,
		long *	length )

Get the length in bytes of a string data type. If the type does not refer to text data the function will return an error. If the size is not fixed and can only be determined from information inside a product then length will be set to -1.

Parameters

type	CODA type.
length	Pointer to a variable where the string length (not including terminating 0) will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_get_unit()

int coda_type_get_unit	(	const coda_type *	type,
		const char **	unit )

Get the unit of a type. You will only receive unit information for ascii, binary, and xml data (for other formats a NULL pointer will be returned). The unit information is a string with the same text as can be found in the unit column of the CODA Product Format Definition documentation for this type. If you try to retrieve the unit for an array type then the unit of its base type will be returned. The unit parameter will either be a NULL pointer or a 0 terminated string.

Parameters

type	CODA type.
unit	Pointer to the variable where the unit information of the type will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

◆ coda_type_has_attributes()

int coda_type_has_attributes	(	const coda_type *	type,
		int *	has_attributes )

Determine whether the type has any attributes. If the record returned by coda_type_get_attributes() has one or more fields then has_attributes will be set to 1, otherwise it will be set to 0.

Parameters

type	CODA type.
has_attributes	Pointer to the variable where attribute availability status will be stored.

Returns

0, Success.
-1, Error occurred (check coda_errno).

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ coda_native_type_enum

◆ coda_special_type_enum

◆ coda_type_class_enum

Function Documentation

◆ coda_type_get_array_base_type()

◆ coda_type_get_array_dim()

◆ coda_type_get_array_num_dims()

◆ coda_type_get_attributes()

◆ coda_type_get_bit_size()

◆ coda_type_get_class()

◆ coda_type_get_class_name()

◆ coda_type_get_description()

◆ coda_type_get_fixed_value()

◆ coda_type_get_format()

◆ coda_type_get_format_name()

◆ coda_type_get_name()

◆ coda_type_get_native_type_name()

◆ coda_type_get_num_record_fields()

◆ coda_type_get_read_type()

◆ coda_type_get_record_field_available_status()

◆ coda_type_get_record_field_hidden_status()

◆ coda_type_get_record_field_index_from_name()

◆ coda_type_get_record_field_index_from_real_name()

◆ coda_type_get_record_field_name()

◆ coda_type_get_record_field_real_name()

◆ coda_type_get_record_field_type()

◆ coda_type_get_record_union_status()

◆ coda_type_get_special_base_type()

◆ coda_type_get_special_type()

◆ coda_type_get_special_type_name()

◆ coda_type_get_string_length()

◆ coda_type_get_unit()

◆ coda_type_has_attributes()