Main Page Modules

Typedefs | Functions
CODA Types

## Typedefs
typedef struct coda_type_struct | coda_type
typedef enum coda_native_type_enum | coda_native_type
typedef enum coda_type_class_enum | coda_type_class
typedef enum coda_special_type_enum | coda_special_type

## 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 refered 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.

## Typedef Documentation

coda_native_type

Machine specific data types

coda_special_type

The special data types

coda_type

CODA Type handle

coda_type_class

CODA Type classes

## Function Documentation

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).

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 occurence 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).

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).

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).

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).

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).

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".

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).

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).

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).

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".

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).

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".

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).

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).

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).

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).

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).

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).

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).

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).

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).

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).

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).

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).

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".

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).

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).

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).