CODA Cursor

Functions
int	coda_cursor_read_int8 (const coda_cursor *cursor, int8_t *dst)
int	coda_cursor_read_uint8 (const coda_cursor *cursor, uint8_t *dst)
int	coda_cursor_read_int16 (const coda_cursor *cursor, int16_t *dst)
int	coda_cursor_read_uint16 (const coda_cursor *cursor, uint16_t *dst)
int	coda_cursor_read_int32 (const coda_cursor *cursor, int32_t *dst)
int	coda_cursor_read_uint32 (const coda_cursor *cursor, uint32_t *dst)
int	coda_cursor_read_int64 (const coda_cursor *cursor, int64_t *dst)
int	coda_cursor_read_uint64 (const coda_cursor *cursor, uint64_t *dst)
int	coda_cursor_read_float (const coda_cursor *cursor, float *dst)
int	coda_cursor_read_double (const coda_cursor *cursor, double *dst)
int	coda_cursor_read_char (const coda_cursor *cursor, char *dst)
int	coda_cursor_read_string (const coda_cursor *cursor, char *dst, long dst_size)
int	coda_cursor_read_bits (const coda_cursor *cursor, uint8_t *dst, int64_t bit_offset, int64_t bit_length)
int	coda_cursor_read_bytes (const coda_cursor *cursor, uint8_t *dst, int64_t offset, int64_t length)
int	coda_cursor_read_int8_array (const coda_cursor *cursor, int8_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_uint8_array (const coda_cursor *cursor, uint8_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_int16_array (const coda_cursor *cursor, int16_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_uint16_array (const coda_cursor *cursor, uint16_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_int32_array (const coda_cursor *cursor, int32_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_uint32_array (const coda_cursor *cursor, uint32_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_int64_array (const coda_cursor *cursor, int64_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_uint64_array (const coda_cursor *cursor, uint64_t *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_float_array (const coda_cursor *cursor, float *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_double_array (const coda_cursor *cursor, double *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_char_array (const coda_cursor *cursor, char *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_int8_partial_array (const coda_cursor *cursor, long offset, long length, int8_t *dst)
int	coda_cursor_read_uint8_partial_array (const coda_cursor *cursor, long offset, long length, uint8_t *dst)
int	coda_cursor_read_int16_partial_array (const coda_cursor *cursor, long offset, long length, int16_t *dst)
int	coda_cursor_read_uint16_partial_array (const coda_cursor *cursor, long offset, long length, uint16_t *dst)
int	coda_cursor_read_int32_partial_array (const coda_cursor *cursor, long offset, long length, int32_t *dst)
int	coda_cursor_read_uint32_partial_array (const coda_cursor *cursor, long offset, long length, uint32_t *dst)
int	coda_cursor_read_int64_partial_array (const coda_cursor *cursor, long offset, long length, int64_t *dst)
int	coda_cursor_read_uint64_partial_array (const coda_cursor *cursor, long offset, long length, uint64_t *dst)
int	coda_cursor_read_float_partial_array (const coda_cursor *cursor, long offset, long length, float *dst)
int	coda_cursor_read_double_partial_array (const coda_cursor *cursor, long offset, long length, double *dst)
int	coda_cursor_read_char_partial_array (const coda_cursor *cursor, long offset, long length, char *dst)
int	coda_cursor_read_complex_double_pair (const coda_cursor *cursor, double *dst)
int	coda_cursor_read_complex_double_pairs_array (const coda_cursor *cursor, double *dst, coda_array_ordering array_ordering)
int	coda_cursor_read_complex_double_split (const coda_cursor *cursor, double *dst_re, double *dst_im)
int	coda_cursor_read_complex_double_split_array (const coda_cursor *cursor, double *dst_re, double *dst_im, coda_array_ordering array_ordering)
int	coda_cursor_print_path (const coda_cursor *cursor, int(*print)(const char *,...))
int	coda_cursor_set_product (coda_cursor *cursor, coda_product *product)
int	coda_cursor_goto (coda_cursor *cursor, const char *path)
int	coda_cursor_goto_first_record_field (coda_cursor *cursor)
int	coda_cursor_goto_record_field_by_index (coda_cursor *cursor, long index)
int	coda_cursor_goto_record_field_by_name (coda_cursor *cursor, const char *name)
int	coda_cursor_goto_next_record_field (coda_cursor *cursor)
int	coda_cursor_goto_available_union_field (coda_cursor *cursor)
int	coda_cursor_goto_first_array_element (coda_cursor *cursor)
int	coda_cursor_goto_array_element (coda_cursor *cursor, int num_subs, const long subs[])
int	coda_cursor_goto_array_element_by_index (coda_cursor *cursor, long index)
int	coda_cursor_goto_next_array_element (coda_cursor *cursor)
int	coda_cursor_goto_attributes (coda_cursor *cursor)
int	coda_cursor_goto_parent (coda_cursor *cursor)
int	coda_cursor_goto_root (coda_cursor *cursor)
int	coda_cursor_use_base_type_of_special_type (coda_cursor *cursor)
int	coda_cursor_has_ascii_content (const coda_cursor *cursor, int *has_ascii_content)
int	coda_cursor_has_attributes (const coda_cursor *cursor, int *has_attributes)
int	coda_cursor_get_string_length (const coda_cursor *cursor, long *length)
int	coda_cursor_get_bit_size (const coda_cursor *cursor, int64_t *bit_size)
int	coda_cursor_get_byte_size (const coda_cursor *cursor, int64_t *byte_size)
int	coda_cursor_get_num_elements (const coda_cursor *cursor, long *num_elements)
int	coda_cursor_get_product_file (const coda_cursor *cursor, coda_product **product)
int	coda_cursor_get_depth (const coda_cursor *cursor, int *depth)
int	coda_cursor_get_index (const coda_cursor *cursor, long *index)
int	coda_cursor_get_file_bit_offset (const coda_cursor *cursor, int64_t *bit_offset)
int	coda_cursor_get_file_byte_offset (const coda_cursor *cursor, int64_t *byte_offset)
int	coda_cursor_get_format (const coda_cursor *cursor, coda_format *format)
int	coda_cursor_get_type_class (const coda_cursor *cursor, coda_type_class *type_class)
int	coda_cursor_get_read_type (const coda_cursor *cursor, coda_native_type *read_type)
int	coda_cursor_get_special_type (const coda_cursor *cursor, coda_special_type *special_type)
int	coda_cursor_get_type (const coda_cursor *cursor, coda_type **type)
int	coda_cursor_get_record_field_index_from_name (const coda_cursor *cursor, const char *name, long *index)
int	coda_cursor_get_record_field_available_status (const coda_cursor *cursor, long index, int *available)
int	coda_cursor_get_available_union_field_index (const coda_cursor *cursor, long *index)
int	coda_cursor_get_array_dim (const coda_cursor *cursor, int *num_dims, long dim[])

Detailed Description

After you have opened a product file with coda_open() (see CODA Product) you will want to access data from this product and retrieve metadata for the data elements (see CODA Types). In order to do this, CODA provides the concept of a 'cursor'. A cursor can be thought of as something that keeps track of a position in the product file and it also stores some extra (type) information about the data element it is currently pointing to. Cursors will start their useful life at the 'root' of a product, i.e., pointing to the entire product, with a type that accurately describes the entire product. From there you can navigate the cursor to the specific data element(s) you want to access. Note that cursors are used for all products that can be opened with CODA. This includes files in ascii, binary, XML, netCDF, HDF4, or HDF5 format.

You can initialize a cursor to point to the product root via the following function:

• coda_cursor_set_product()

Suppose that we want to read the absolute orbit number value from the MPH of an ESA ENVISAT product file. In order to do this, we first have to use the coda_cursor_set_product() function to initialize a cursor to point to the complete product. As explained in the CODA Types section (see CODA Types) all data elements of a product file can be categorized in arrays, records, and basic types (int16, double, complex float, etc.). The product root of an ENVISAT file is a record, which means that we are able to call the coda_cursor_goto_record_field_by_name() to navigate to the MPH. The MPH to which the cursor is then pointing is again a record, so we can call the coda_cursor_goto_record_field_by_name() function again to move the cursor to a certain MPH field. We are interested in the absolute orbit, so if we call this function with the fieldname "abs_orbit". Our cursor will now point to the location in the product file that contains the value we want.

Once we have moved the cursor to the right location we have to read the data that it is pointing to. In order to do that, we first want to find out the best native type to read the absolute orbit value. You can either determine this by looking it up in the CODA Product Format Definition documentation for the product or you can use the coda_cursor_get_read_type() on the cursor. Both methods will show you that the absolute orbit is stored as a int32 value.

Since the value is a signed 32-bit integer, we will call coda_cursor_read_int32() to read the absolute orbit value (Notice that this function returns the value as an int32_t type. CODA use these bit-specific types because not every platform that CODA runs on uses the same amount of bits for the C types short, int, and long). It is however also possible to read the 32-bit integer using a CODA read function that returns a native type that is larger than an int32. For instance, you can also read the 32-bit integer value using coda_cursor_read_int64() or coda_cursor_read_double(), which would return the value as an int64_t or double value (you can't however read the signed 32 bit integer using an unsigned integer type (e.g. uint32) or using a shorter type (e.g. int16)).

A small example that performs all these steps and prints the retrieved orbit number is given below. Note that, for the sake of clarity, we omit error checking:

coda_product *product;
coda_cursor cursor;
int32_t abs_orbit_val;
coda_init();
product = coda_open("... path to envisat product file ...");
coda_cursor_set_product(&cursor, product);
coda_cursor_goto_record_field_by_name(&cursor, "mph");
coda_cursor_goto_record_field_by_name(&cursor, "abs_orbit");
coda_cursor_read_int32(&cursor, &abs_orbit_val);
printf("absolute orbit: %ld\n", (long)abs_orbit_val);
coda_close(product);
coda_done();

After you have moved a cursor to a specific data element, it is possible to reuse the cursor and move it to other data elements. Suppose that, after reading the absolute orbit, we now want to read the relative orbit. In order to do that we first we have to go back to the MPH record. To have the cursor move to its encapsulating record or array you can use the coda_cursor_goto_parent() function. After that, we can call coda_cursor_goto_record_field_by_name() again but now with the string "rel_orbit" as fieldname parameter.

An important aspect of using cursors is that you do not have to clean up a cursor. Memory can be reserved for a cursor simply by declaring it; the initialization of the cursor with a coda_cursor_set_product() function does not require any memory allocation. Another advantage of this kind of implementation is that you can easily make a copy of a cursor. Suppose we have a cursor record_cursor that points to a record and we want to have an extra cursor field_cursor that points to the 'dsr_time' field of this record. This can be done as follows:

coda_cursor field_cursor;
field_cursor = record_cursor;
coda_cursor_goto_record_field_by_name(&field_cursor, "dsr_time");

First we copy the record cursor's contents into the field cursor through a simple assignment. The field_cursor now also points to the full record. Then we move field_cursor to the dsr_time field (after this, record_cursor still points to the whole record).

Function Documentation

coda_cursor_get_array_dim()

int coda_cursor_get_array_dim	(	const coda_cursor *	cursor,
		int *	num_dims,
		long	dim[] )

Retrieve the dimensions of the data array that the cursor points to. The function returns both the number of dimensions num_dims and the size of the dimensions dim.

Note

If the size of the dimensions is variable (it differs per product or differs per data element inside one product) then this function will calculate the dimensions from the necessary properties inside the product. Depending on the complexity of this calculation the determination of variable sized dimensions could impact performance.

Parameters

cursor	Pointer to a CODA cursor.
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. 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_cursor_get_available_union_field_index()

int coda_cursor_get_available_union_field_index	(	const coda_cursor *	cursor,
		long *	index )

Determines which union record field is available in the product.

Note

It is allowed to move a cursor to an unavailable union record field. In that case the data type for the field will be set to the special coda_special_no_data data type (with type class coda_special_class), which has a bit/byte length of 0.

Parameters

cursor	Pointer to a CODA cursor.
index	Pointer to the variable where the index of the available record field will be stored.

Returns

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

coda_cursor_get_bit_size()

int coda_cursor_get_bit_size	(	const coda_cursor *	cursor,
		int64_t *	bit_size )

Get the bit size for the data at the current cursor position. 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 a bit size is not available bit_size will be set to -1.

Parameters

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

Returns

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

coda_cursor_get_byte_size()

int coda_cursor_get_byte_size	(	const coda_cursor *	cursor,
		int64_t *	byte_size )

Get the byte size for the data at the current cursor position. This function will retrieve the bit_size using coda_cursor_get_bit_size(), convert it to a byte size by rounding it up to the nearest byte, and return this byte size. If the bit size is -1, then this function will also return -1 for byte_size.

Parameters

cursor	Pointer to a valid CODA cursor.
byte_size	Pointer to the variable where the byte size will be stored.

Returns

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

coda_cursor_get_depth()

int coda_cursor_get_depth	(	const coda_cursor *	cursor,
		int *	depth )

Retrieve the current hierarchical depth of the cursor. The depth indicates how deep one has traversed into a product file and equals the amount of calls to coda_cursor_goto_parent() one has to call to end up at the root of the product.

Parameters

cursor	Pointer to a CODA cursor.
depth	Pointer to the variable where the cursor depth will be stored.

Returns

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

coda_cursor_get_file_bit_offset()

int coda_cursor_get_file_bit_offset	(	const coda_cursor *	cursor,
		int64_t *	bit_offset )

Retrieve the file offset in bits of the data element that the cursor points to. You will not be able to retrieve bit/byte offsets for data in netCDF, HDF4, or HDF5 format. For data in XML format you will not be able to retrieve bit/byte offsets for arrays or attribute records.

Parameters

cursor	Pointer to a CODA cursor.
bit_offset	Pointer to the variable where the file offset in bits will be stored.

Returns

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

coda_cursor_get_file_byte_offset()

int coda_cursor_get_file_byte_offset	(	const coda_cursor *	cursor,
		int64_t *	byte_offset )

Retrieve the file offset in bytes of the data element that the cursor points to. The byte offset is determined by the bit offset of the data element. If the current bit offset does not end at a byte boundary the returned byte offest will be determined by rounding the bit offset down to the nearest byte.

Parameters

cursor	Pointer to a CODA cursor.
byte_offset	Pointer to the variable where the (possibly rounded) file offset in bytes will be stored.

Returns

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

coda_cursor_get_format()

int coda_cursor_get_format	(	const coda_cursor *	cursor,
		coda_format *	format )

Retrieve the storage format of the data element that the cursor points to. This has the same result as calling coda_type_get_format() with the result from coda_cursor_get_type().

Parameters

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

Returns

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

coda_cursor_get_index()

int coda_cursor_get_index	(	const coda_cursor *	cursor,
		long *	index )

Retrieve the array element or field index of the data element that the cursor points to. If the parent of the cursor points to a record then this function will return the field index of the current data element. In case the parent points to an array then the array element index (the same kind of index that is used for coda_cursor_goto_array_element_by_index()) will be returned. If the cursor has no parent or if the cursor points to an attribute record then this function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
index	Pointer to the variable where the index will be stored.

Returns

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

coda_cursor_get_num_elements()

int coda_cursor_get_num_elements	(	const coda_cursor *	cursor,
		long *	num_elements )

Gives the number of elements of the data that is pointed to by the cursor. If the cursor points to an array the function will return the total number of elements of the array. If the cursor references a record then the number of fields of the record will be returned. For all other types the function will return 1.

Parameters

cursor	Pointer to a valid CODA cursor.
num_elements	Pointer to the variable where the number of elements will be stored.

Returns

• >=0, Number of elements of the data in the product.
• -1, Error occurred (check coda_errno).

coda_cursor_get_product_file()

int coda_cursor_get_product_file	(	const coda_cursor *	cursor,
		coda_product **	product )

Retrieve the Product handle that was used to initialize this cursor.

Parameters

cursor	Pointer to a CODA cursor.
product	Pointer to a product file handle pointer.

Returns

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

coda_cursor_get_read_type()

int coda_cursor_get_read_type	(	const coda_cursor *	cursor,
		coda_native_type *	read_type )

Get the best native type for reading data at the current cursor position. This has the same result as calling coda_type_get_read_type() with the result from coda_cursor_get_type().

See also

coda_type_get_read_type()

Parameters

cursor	Pointer to a CODA cursor.
read_type	Pointer to the variable where the read type will be stored.

Returns

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

coda_cursor_get_record_field_available_status()

int coda_cursor_get_record_field_available_status	(	const coda_cursor *	cursor,
		long	index,
		int *	available )

Determines whether a record field is available in the product. This function allows you to check whether a dynamically available field in a record is available or not. If the field is available then available will be 1, otherwise it will be 0.

Note

If a record is a union then only one field in the record will be available.

It is allowed to move a CODA cursor to an unavailable field. In that case the data type for the field will be set to the special coda_special_no_data data type (with type class coda_special_class), which has a bit/byte size of 0.

Parameters

cursor	Pointer to a CODA cursor.
index	Index of the field (0 <= index < number of fields).
available	Pointer to the variable where the available status will be stored.

Returns

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

coda_cursor_get_record_field_index_from_name()

int coda_cursor_get_record_field_index_from_name	(	const coda_cursor *	cursor,
		const char *	name,
		long *	index )

Get the field index from a field name for the record at the current cursor position. If the cursor does not point to a record the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
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_cursor_get_special_type()

int coda_cursor_get_special_type	(	const coda_cursor *	cursor,
		coda_special_type *	special_type )

Retrieve the special type of the data element that the cursor points to. This has the same result as calling coda_type_get_special_type() with the result from coda_cursor_get_type(). The class of the data type that the cursor points to should be coda_special_class, otherwise this function will return an error.

Parameters

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

Returns

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

coda_cursor_get_string_length()

int coda_cursor_get_string_length	(	const coda_cursor *	cursor,
		long *	length )

Get the length in bytes of a string data type. The length that is returned does not include the additional byte needed for the terminating 0. This means that if you want to call coda_cursor_read_string() you should allocate length + 1 amount of bytes and pass a value of length + 1 for the dst_size parameter of coda_cursor_read_string(). If the cursor does not point to string data the function will return an error.

Parameters

cursor	Pointer to a valid CODA cursor.
length	Pointer to the variable where the string length will be stored.

Returns

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

coda_cursor_get_type()

int coda_cursor_get_type	(	const coda_cursor *	cursor,
		coda_type **	type )

Retrieve the CODA type of the data element that the cursor points to. Refer to the section about CODA Types to find more information on how to use the CODA type to get more information about a data element.

Parameters

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

Returns

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

coda_cursor_get_type_class()

int coda_cursor_get_type_class	(	const coda_cursor *	cursor,
		coda_type_class *	type_class )

Retrieve the type class of the data element that the cursor points to. This has the same result as calling coda_type_get_class() with the result from coda_cursor_get_type().

Parameters

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

Returns

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

coda_cursor_goto()

int coda_cursor_goto	(	coda_cursor *	cursor,
		const char *	path )

Moves the cursor to the location in the product as specified by a path string. The path string should contain a path reference similar to a 'node expression' (see CODA expression language). The cursor parameter should contain a properly initialised cursor (e.g. using coda_cursor_set_product()) The cursor position of cursor will be updated based on the path provided. This can be a move relative to the current cursor position in case of a relative path specification or an explicit move in case of an absolute path specification (i.e. if the node expression starts with '/'). Although the path parameter is similar to a CODA node expression, there are a few differences:

• the ':' specifier is not allowed (use '.')
• a relative path that starts with a field reference does not have to start with a './', you can immediately start with the field name (e.g. you can use 'foo/bar' instead of './foo/bar')

  Parameters

  cursor	Pointer to a valid CODA cursor.
  path	A string representing a path to a location inside a product.

  Returns

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

coda_cursor_goto_array_element()

int coda_cursor_goto_array_element	(	coda_cursor *	cursor,
		int	num_subs,
		const long	subs[] )

Moves the cursor to point to an array element via an array of subscripts. This function takes a subscript array to specify the index of the data array element. The length of the array subs, the number of dimensions of the data array and the value of num_subs should all be the same.

Note

In contrast to coda_cursor_goto_array_element_by_index() this function will always perform a boundary check on the num_subs and subs parameters, even if the option to check boundaries was turned off with coda_set_option_perform_boundary_checks().

Parameters

cursor	Pointer to a CODA cursor that references an array.
num_subs	Size of the parameter subs. This should be equal to the number of dimensions of the array which the cursor is pointing to.
subs	Array of subscripts that identifies the data array element ((0, 0, ..., 0) <= subs < data array dimensions)

Returns

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

coda_cursor_goto_array_element_by_index()

int coda_cursor_goto_array_element_by_index	(	coda_cursor *	cursor,
		long	index )

Moves the cursor to point to an array element via an index. This function treats all multidimensional arrays as a one dimensional array (with the same number of elements). The ordering in such a one dimensional array is by definition chosen to be equal to the way the array elements are stored as a sequence in the product file. The mapping of a one dimensional index for each multidimensional data array to an array of subscripts (and vice versa) is defined in such a way that the last element of a subscript array is the one that is the fastest running index (i.e. C array ordering). All multidimensional arrays have their dimensions defined using C array ordering in CODA.
For example if we have a two dimensional array with dimensions (2,4) then the index 0 would map to the subscript array (0, 0). 1 would map to (0, 1), 4 would map to (1, 0) and 7 would map to (1, 3).
If the data array is one dimensional then this function will have the same result as calling coda_cursor_goto_array_element() with num_subs = 1 and subs[0] = index.

Parameters

cursor	Pointer to a CODA cursor that references an array.
index	Index of the array element (0 <= index < number of elements)

Returns

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

coda_cursor_goto_attributes()

int coda_cursor_goto_attributes

(

coda_cursor *

cursor

)

Moves the cursor to point to a (virtual) record containing the attributes of the current data element. This function will move the cursor to a record containing all attributes of the data element that the cursor was previously pointing to. If there are no attributes available the cursor will point to an empty record (i.e. a record with 0 fields). It only makes sense to retrieve attributes when the HDF4, HDF5, netCDF or XML backend is used. Ascii and binary files will always return an empty record. You can use the CODA Type functions to retrieve the fixed attributes (such as unit and description) for files that are stored in a structured ascii or binary format.

Parameters

cursor

Pointer to a CODA cursor.

Returns

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

coda_cursor_goto_available_union_field()

int coda_cursor_goto_available_union_field

(

coda_cursor *

cursor

)

Moves the cursor to point to the available union field. CODA treats unions as a special kind of records (i.e. unions are records where all fields are dynamically available and only one field will be available at a time). You can use the coda_type_get_record_union_status() to determine whether a record is a union. If it is, you can use the coda_cursor_goto_available_union_field() function to go to the single available record field.

Parameters

cursor

Pointer to a CODA cursor that references a union record.

Returns

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

coda_cursor_goto_first_array_element()

int coda_cursor_goto_first_array_element

(

coda_cursor *

cursor

)

Moves the cursor to point to the first element of an array. For an n-dimensional array this means going to the element with index (0, 0, ..., 0).

Warning

If the array has 0 elements then this function will return an error.

Parameters

cursor

Pointer to a CODA cursor that references an array.

Returns

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

coda_cursor_goto_first_record_field()

int coda_cursor_goto_first_record_field

(

coda_cursor *

cursor

)

Moves the cursor to point to the first field of a record. If the field is a dynamically available record field and if it is not available in the current record, the cursor will point to a special no-data data type after completion of this function (the position information of the cursor is retained in that case, so you can still use coda_cursor_goto_parent, coda_cursor_goto_next_record_field, etc.).

Warning

If the record contains no fields the function will return an error.

Parameters

cursor

Pointer to a CODA cursor that references a record.

Returns

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

coda_cursor_goto_next_array_element()

int coda_cursor_goto_next_array_element

(

coda_cursor *

cursor

)

Moves the cursor to point to the next element of an array. This function treats all multidimensional arrays as a one dimensional array in the same way as coda_cursor_goto_array_element_by_index() does. It will move the cursor to the array element with index = current_index + 1.

Warning

If the cursor already points to the last element of an array the function will return an error. So if you want to enumerate all elements of an array (as a one dimensional sequence) use something like

coda_cursor_get_num_elements(cursor, &num_elements);
if (num_elements > 0)
{
    coda_cursor_goto_first_array_element(cursor);
    for (i = 0; i < num_elements; i++)
    {
        ...
        if (i < num_elements - 1)
        {
            coda_cursor_goto_next_array_element(cursor);
        }
    }
    coda_cursor_goto_parent(cursor);
}

Parameters

cursor

Pointer to a CODA cursor that references an array.

Returns

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

coda_cursor_goto_next_record_field()

int coda_cursor_goto_next_record_field

(

coda_cursor *

cursor

)

Moves the cursor to point to the next field of a record. If the field is a dynamically available record field and if it is not available in the current record, the cursor will point to a special no-data data type after completion of this function (the position information of the cursor is retained in that case, so you can still use coda_cursor_goto_parent, coda_cursor_goto_next_record_field, etc.).

Warning

If the cursor already points to the last field of a record the function will return an error. So if you want to enumerate all fields of a record use something like

coda_cursor_get_num_elements(cursor, &num_fields);
if (num_fields > 0)
{
    coda_cursor_goto_first_record_field(cursor);
    for (i = 0; i < num_fields; i++)
    {
        ...
        if (i < num_fields - 1)
        {
             coda_cursor_goto_next_record_field(cursor);
        }
    }
    coda_cursor_goto_parent(cursor);
}

Parameters

cursor

Pointer to a CODA cursor that references a field.

Returns

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

coda_cursor_goto_parent()

int coda_cursor_goto_parent

(

coda_cursor *

cursor

)

Moves the cursor one level up in the hierarchy. If the cursor points to a field this function will move the cursor to its record and if the cursor points to an array element the cursor will be moved to the array. If the cursor is already at the topmost level (it points to the root of a product) the function will return an error.

Parameters

cursor

Pointer to a CODA cursor that references either a field or array element.

Returns

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

coda_cursor_goto_record_field_by_index()

int coda_cursor_goto_record_field_by_index	(	coda_cursor *	cursor,
		long	index )

Moves the cursor to point to the field at position index of a record. If the field is a dynamically available record field and if it is not available in the current record, the cursor will point to a special no-data data type after completion of this function (the position information of the cursor is retained in that case, so you can still use coda_cursor_goto_parent, coda_cursor_goto_next_record_field, etc.).

See also

coda_cursor_get_num_elements()

Parameters

cursor	Pointer to a CODA cursor that references a record.
index	Index of the field (0 <= index < number of fields).

Returns

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

coda_cursor_goto_record_field_by_name()

int coda_cursor_goto_record_field_by_name	(	coda_cursor *	cursor,
		const char *	name )

Moves the cursor to point to the field of a record that has fieldname name. If the field is a dynamically available record field and if it is not available in the current record, the cursor will point to a special no-data data type after completion of this function (the position information of the cursor is retained in that case, so you can still use coda_cursor_goto_parent, coda_cursor_goto_next_record_field, etc.). If name does not correspond with a fieldname of the record the function will return an error.

Parameters

cursor	Pointer to a CODA cursor that references a record.
name	Fieldname of the field.

Returns

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

coda_cursor_goto_root()

int coda_cursor_goto_root

(

coda_cursor *

cursor

)

Moves the cursor to the root of the product. The cursor will be at the same position as it was after its initialization with coda_cursor_set_product().

Parameters

cursor

Pointer to a CODA cursor.

Returns

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

coda_cursor_has_ascii_content()

int coda_cursor_has_ascii_content	(	const coda_cursor *	cursor,
		int *	has_ascii_content )

Determine wether data at the current cursor position is stored as ascii data. You can use this function to determine whether the data is stored in ascii format. If it is in ascii format, you will be able to read the data using coda_cursor_read_string(). If, for instance, a record consists of purely ascii data (i.e. it is a structured ascii block in the file) has_ascii_content for a cursor pointing to that record will be 1 and you can use the coda_cursor_read_string() function to read the whole record as a block of raw ascii.

Parameters

cursor	Pointer to a valid CODA cursor.
has_ascii_content	Pointer to a variable where the ascii content status will be stored.

Returns

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

coda_cursor_has_attributes()

int coda_cursor_has_attributes	(	const coda_cursor *	cursor,
		int *	has_attributes )

Determine whether data at the current cursor position has any attributes. If coda_cursor_goto_attributes() will point to a record that has one or more fields then has_attributes will be set to 1, otherwise it will be set to 0. Note that this has the same result as calling coda_type_has_attributes() with the result from coda_cursor_get_type().

Parameters

cursor	Pointer to a valid CODA cursor.
has_attributes	Pointer to the variable where attribute availability status will be stored.

Returns

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

coda_cursor_print_path()

int coda_cursor_print_path	(	const coda_cursor *	cursor,
		int(*)(const char *,...)	print )

Write the full path of the current cursor position using a printf compatible function. The print function parameter should be a function that resembles printf(). The most common case use is to just use printf() itself. For example:

coda_cursor_print_path(cursor, printf);

The format of the printed path is the same as used for nodes in CODA expressions .

Parameters

cursor	Pointer to a CODA cursor.
print	Reference to a printf compatible function.

Returns

• 0, Succes.
• -1, Error occurred (check coda_errno).

coda_cursor_read_bits()

int coda_cursor_read_bits	(	const coda_cursor *	cursor,
		uint8_t *	dst,
		int64_t	bit_offset,
		int64_t	bit_length )

Read a specified amount of bits. The data is stored in dst. This function will work independent of the type of data at the current cursor position, but it will not work on ASCII, XML, HDF4, and HDF5 data. The function will read a bit_length amount of bits starting from the sum of the cursor offset position and the amount of bits given by the bit_offset parameter. If bit_length is not a rounded amount of bytes the data will be put in the first bit_length/8 + 1 bytes and will be right adjusted (i.e. padding bits with value 0 will be put in the most significant bits of the first byte of dst).

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.
bit_offset	The offset relative to the current cursor position from where the bits should be read.
bit_length	The number of bits to read.

Returns

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

coda_cursor_read_bytes()

int coda_cursor_read_bytes	(	const coda_cursor *	cursor,
		uint8_t *	dst,
		int64_t	offset,
		int64_t	length )

Read a specified amount of bytes. The data is stored in dst. This function will work independent of the type of data at the current cursor position, but it will not work on HDF4 and HDF5 files. For XML files it will only work if the cursor points to a single element (i.e. you will get an error when the cursor points to an XML element array or an attribute record). The function will read a length amount of bytes starting from the sum of the cursor offset position and the amount of bytes given by the offset parameter.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.
offset	The offset relative to the current cursor position from where the bytes should be read.
length	The number of bytes to read.

Returns

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

coda_cursor_read_char()

int coda_cursor_read_char	(	const coda_cursor *	cursor,
		char *	dst )

Retrieve data as type char from the product file. The value is stored in dst. The cursor must point to data with read type char to succeed. For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_char_array()

int coda_cursor_read_char_array	(	const coda_cursor *	cursor,
		char *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type char from the product file. The values are stored in dst. The cursor must point to an array with a base type that has read type char to succeed. For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_char_partial_array()

int coda_cursor_read_char_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		char *	dst )

Retrieve a partial data array as type char from the product file. The values are stored in dst. The cursor must point to an array with a base type that has read type char to succeed. For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_complex_double_pair()

int coda_cursor_read_complex_double_pair	(	const coda_cursor *	cursor,
		double *	dst )

Retrieve complex data as type double from the product file. The real and imaginary values are stored consecutively in dst. The cursor must point to data with special type coda_special_complex to succeed. For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_complex_double_pairs_array()

int coda_cursor_read_complex_double_pairs_array	(	const coda_cursor *	cursor,
		double *	dst,
		coda_array_ordering	array_ordering )

Retrieve an array of complex data as type double from the product file. All complex array elements are stored consecutively in dst (for each element the real and imaginary values are stored next to each other). The cursor must point to data with a base type that has special type coda_special_complex to succeed. For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_complex_double_split()

int coda_cursor_read_complex_double_split	(	const coda_cursor *	cursor,
		double *	dst_re,
		double *	dst_im )

Retrieve complex data as type double from the product file. The real and imaginary values are stored in dst_re and dst_im. The cursor must point to data with special type coda_special_complex to succeed. For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst_re	Pointer to the variable where the real value that was read from the product will be stored.
dst_im	Pointer to the variable where the imaginary value that was read from the product will be stored.

Returns

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

coda_cursor_read_complex_double_split_array()

int coda_cursor_read_complex_double_split_array	(	const coda_cursor *	cursor,
		double *	dst_re,
		double *	dst_im,
		coda_array_ordering	array_ordering )

Retrieve an array of complex data as type double from the product file. All real array elements are stored in dst_re and all imaginary array elements in dsr_im. The cursor must point to data with a base type that has special type coda_special_complex to succeed. For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst_re	Pointer to the variable where the real values read from the product will be stored.
dst_im	Pointer to the variable where the imaginary values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst_im and dst_re: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_double()

int coda_cursor_read_double	(	const coda_cursor *	cursor,
		double *	dst )

Retrieve data as type double from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64
• float
• double

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_double_array()

int coda_cursor_read_double_array	(	const coda_cursor *	cursor,
		double *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type double from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64
• float
• double

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_double_partial_array()

int coda_cursor_read_double_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		double *	dst )

Retrieve a partial data array as type double from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64
• float
• double

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_float()

int coda_cursor_read_float	(	const coda_cursor *	cursor,
		float *	dst )

Retrieve data as type float from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64
• float
• double

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_float_array()

int coda_cursor_read_float_array	(	const coda_cursor *	cursor,
		float *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type float from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64
• float
• double

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_float_partial_array()

int coda_cursor_read_float_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		float *	dst )

Retrieve a partial data array as type float from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64
• float
• double

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_int16()

int coda_cursor_read_int16	(	const coda_cursor *	cursor,
		int16_t *	dst )

Retrieve data as type int16 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• int8
• uint8
• int16

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_int16_array()

int coda_cursor_read_int16_array	(	const coda_cursor *	cursor,
		int16_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type int16 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_int16_partial_array()

int coda_cursor_read_int16_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		int16_t *	dst )

Retrieve a partial data array as type int16 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_int32()

int coda_cursor_read_int32	(	const coda_cursor *	cursor,
		int32_t *	dst )

Retrieve data as type int32 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_int32_array()

int coda_cursor_read_int32_array	(	const coda_cursor *	cursor,
		int32_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type int32 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_int32_partial_array()

int coda_cursor_read_int32_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		int32_t *	dst )

Retrieve a partial data array as type int32 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_int64()

int coda_cursor_read_int64	(	const coda_cursor *	cursor,
		int64_t *	dst )

Retrieve data as type int64 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_int64_array()

int coda_cursor_read_int64_array	(	const coda_cursor *	cursor,
		int64_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type int64 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_int64_partial_array()

int coda_cursor_read_int64_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		int64_t *	dst )

Retrieve a partial data array as type int64 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_int8()

int coda_cursor_read_int8	(	const coda_cursor *	cursor,
		int8_t *	dst )

Retrieve data as type int8 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• int8

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_int8_array()

int coda_cursor_read_int8_array	(	const coda_cursor *	cursor,
		int8_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type int8 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_int8_partial_array()

int coda_cursor_read_int8_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		int8_t *	dst )

Retrieve a partial data array as type int8 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• int8

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_string()

int coda_cursor_read_string	(	const coda_cursor *	cursor,
		char *	dst,
		long	dst_size )

Retrieve text data as a 0 terminated string. The value is stored in dst. You will be able to read data as a string if the cursor points to data with type class coda_text_class or if it points to ASCII data (see coda_cursor_has_ascii_content()). For other cases the function will return an error. The function will fill at most dst_size bytes in the dst memory space. The last character that is put in dst will always be a zero termination character, which means that at most dst_size - 1 characters of text data will be read.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.
dst_size	The maximum number of bytes to write in dst.

Returns

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

coda_cursor_read_uint16()

int coda_cursor_read_uint16	(	const coda_cursor *	cursor,
		uint16_t *	dst )

Retrieve data as type uint16 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• uint8
• uint16

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_uint16_array()

int coda_cursor_read_uint16_array	(	const coda_cursor *	cursor,
		uint16_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type uint16 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8
• uint16

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_uint16_partial_array()

int coda_cursor_read_uint16_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		uint16_t *	dst )

Retrieve a partial data array as type uint16 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8
• uint16

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_uint32()

int coda_cursor_read_uint32	(	const coda_cursor *	cursor,
		uint32_t *	dst )

Retrieve data as type uint32 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• uint8
• uint16
• uint32

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_uint32_array()

int coda_cursor_read_uint32_array	(	const coda_cursor *	cursor,
		uint32_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type uint32 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8
• uint16
• uint32

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_uint32_partial_array()

int coda_cursor_read_uint32_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		uint32_t *	dst )

Retrieve a partial data array as type uint32 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8
• uint16
• uint32

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_uint64()

int coda_cursor_read_uint64	(	const coda_cursor *	cursor,
		uint64_t *	dst )

Retrieve data as type uint64 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• uint8
• uint16
• uint32
• uint64

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_uint64_array()

int coda_cursor_read_uint64_array	(	const coda_cursor *	cursor,
		uint64_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type uint64 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8
• uint16
• uint32
• uint64

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_uint64_partial_array()

int coda_cursor_read_uint64_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		uint64_t *	dst )

Retrieve a partial data array as type uint64 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8
• uint16
• uint32
• uint64

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_read_uint8()

int coda_cursor_read_uint8	(	const coda_cursor *	cursor,
		uint8_t *	dst )

Retrieve data as type uint8 from the product file. The value is stored in dst. The cursor must point to data with one of the following read types to succeed:

• uint8

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the value that was read from the product will be stored.

Returns

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

coda_cursor_read_uint8_array()

int coda_cursor_read_uint8_array	(	const coda_cursor *	cursor,
		uint8_t *	dst,
		coda_array_ordering	array_ordering )

Retrieve a data array as type uint8 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8

For all other data types the function will return an error.

Parameters

cursor	Pointer to a CODA cursor.
dst	Pointer to the variable where the values read from the product will be stored.
array_ordering	Specifies array storage ordering for dst: must be coda_array_ordering_c or coda_array_ordering_fortran.

Returns

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

coda_cursor_read_uint8_partial_array()

int coda_cursor_read_uint8_partial_array	(	const coda_cursor *	cursor,
		long	offset,
		long	length,
		uint8_t *	dst )

Retrieve a partial data array as type uint8 from the product file. The values are stored in dst. The cursor must point to an array with a base type that has one of the following read types to succeed:

• uint8

For all other data types the function will return an error. Values are both read and returned using C array ordering convention.

Note

Partial array reading is not supported for HDF5 and HDF4 attributes and HDF4 Vdata. For HDF5 Datasets, HDF4 SDS, and HDF4 GRImage, partial array reading is only allowed when reading a full hyperslab (i.e. the range defined by 'offset' and 'length' should be translatable into a multidimensional start[]/count[], defining a hyperslab)

Parameters

cursor	Pointer to a CODA cursor.
offset	Index (as used in coda_cursor_goto_array_element_by_index) at which to start reading.
length	Number of items to read.
dst	Pointer to the variable where the values read from the product will be stored.

Returns

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

coda_cursor_set_product()

int coda_cursor_set_product	(	coda_cursor *	cursor,
		coda_product *	product )

Initialize the cursor to point to the entire product.

Parameters

cursor	Pointer to a CODA cursor.
product	Pointer to a product file handle.

Returns

• 0, Succes.
• -1, Error occurred (check coda_errno).

coda_cursor_use_base_type_of_special_type()

int coda_cursor_use_base_type_of_special_type

(

coda_cursor *

cursor

)

Reinterpret the current special data type using the base type of the special type. All data types with a type class coda_special_class have a base type that can be used to read the data in its raw form (e.g. for ascii time data the type will change to a string type and for binary compound time data the type will change to a record with fields containing binary numbers). With this function the cursor is modified such that it will interpret the current data element using this base type. The cursor should point to data of class coda_special_class or an error will be returned.

Warning

Using coda_cursor_goto_parent() on the cursor after calling coda_cursor_use_base_type_of_special_type() will move the cursor to the parent of the special type and not back to the special type itself. In other words, coda_cursor_use_base_type_of_special_type() does not 'move' the cursor, it only changes the data type that is used to interpret the underlying data.

Parameters

cursor

Pointer to a CODA cursor.

Returns

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