Functions
int	coda_recognize_file (const char filename, int64_t file_size, coda_format file_format, const char product_class, const char product_type, int version)

int	coda_open (const char filename, coda_product *product)

int	coda_open_as (const char filename, const char product_class, const char product_type, int version, coda_product *product)

int	coda_close (coda_product *product)

int	coda_get_product_filename (const coda_product product, const char *filename)

int	coda_get_product_file_size (const coda_product product, int64_t file_size)

int	coda_get_product_format (const coda_product product, coda_format format)

int	coda_get_product_class (const coda_product product, const char *product_class)

int	coda_get_product_type (const coda_product product, const char *product_type)

int	coda_get_product_version (const coda_product product, int version)

int	coda_get_product_root_type (const coda_product product, coda_type *type)

int	coda_get_product_definition_file (const coda_product product, const char *definition_file)

int	coda_get_product_variable_value (coda_product product, const char variable, long index, int64_t *value)

Detailed Description

The CODA Product module contains functions and procedures to open, close and retrieve information about product files that are supported by CODA.

Under the hood CODA uses several different backends to access data from products. There are backends for structured ascii, structured binary, XML, netCDF, HDF4, HDF5, and several other data formats. Some formats such as netCDF, HDF4, and HDF5 are self describing product formats. This means that CODA will retrieve information about the structural layout and contents from the file itself. For other formats, such as XML, CODA can either use an external definition (from a .codadef file) to interpret an XML file (similar like an XML Schema) or it can try to retrieve structural layout of the file from the file itself. For XML this last option will result in a reduced form of access, since 'leaf elements' can not be interpreted as e.g. integer/float/time but will only be accessible as string data. For the interpretation of structured ascii and structured binary files (or a combination of both) CODA purely relies on the format definitions that are provided in the .codadef files.

In order to be able to open product files with CODA you will first have to initialize CODA with coda_init() (see CODA General). This initialization routine will initialize all available backends and will search for all .codadef files in your CODA definition path to read the necessary descriptions of all non self-describing products (note that you want to use .codadef files, you will need to have set the location of your CODA definition path using coda_set_definition_path() or via the CODA_DEFINITION environment variable before calling coda_init()). As a user you can access all supported products in the same way no matter which format the product uses underneath. This means that you can use the same functions for opening, traversing, reading, and closing a product no matter whether you are accessing an ascii, binary, XML, netCDF, HDF4, HDF5, etc. formatted file.

To open a product file you will have to use the coda_open() function. This function takes as only parameter the filename of the product file. CODA will then open the file and automatically check what type of file it is. If it is an HDF4 or HDF5 file it will use the HDF4/HDF5 backends for further access. In all other cases CODA will consult the data dictionary to determine whether there is a product definition for that file in one of the available product classes.

Within CODA a product class is a grouping of related product types. Usually all data products for a single satellite mission belong to the same product class. Within a product class there can be several product types and each product type can have multiple versions of its format (this is because product format descriptions will sometimes change during the lifetime of a product type). The combination of product class, product type and product version number uniquely defines the description that will be used to interpret a product file.

If CODA can not determine the product class, type, or version of a structured ascii/binary file, the file will not be opened and an error will be returned. For other formats such as XML, netCDF, HDF4, and HDF5 files CODA will open and interpret the data based on the file contents. If everything was successful, the coda_open() function will provide you a file handle (of type coda_product) that can be passed to a range of other functions to retrieve information like the product class, type and version, or to read data from the file with the help of CODA cursors (see CODA Cursor). After you are done with a file you should close it with coda_close(). This function will also free the memory that was allocated for the file handle by coda_open(). Below is a simple example that opens a file called productfile.dat and closes it again.

coda_product *product;
if (coda_init() != 0)
{
    fprintf(stderr, "Error: %s\n", coda_errno_to_string(coda_errno));
    exit(1);
}
if (coda_open("productfile.dat", &product) != 0)
{
    fprintf(stderr, "Error: %s\n", coda_errno_to_string(coda_errno));
    exit(1);
}
coda_close(product);
coda_done();

It is possible to have multiple product files open at the same time. Just call coda_open() again on a different file and you will get a new file handle. It is also possible to open a single product file multiple times (although this is a feature we encourage you to avoid on 32-bit systems because of the mmap() limitations - see coda_set_option_use_mmap()). In that case CODA will just return a second product file handle which is completely independent of the first product file handle you already had.

Function Documentation

◆ coda_close()

int coda_close ( coda_product * product )

Close an open product file. This function will close the file associated with the file handle and release the memory for the handle. The file handle will be released even if unmapping or closing of the product file produced an error.

Parameters

product Pointer to a product file handle.

Returns

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

◆ coda_get_product_class()

int coda_get_product_class	(	const coda_product *	product,
		const char **	product_class )

Get the product class of a product file. This function will return the name of the product class of a product. The name of the product class will be stored in the product_class parameter and will be 0 terminated. The string pointer that is returned for product_class does not have to be freed by the user and will remain valid until coda_done() is called.

Parameters

product	Pointer to a product file handle.
product_class	Pointer to the variable where the class name of the product will be stored.

Returns

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

◆ coda_get_product_definition_file()

int coda_get_product_definition_file	(	const coda_product *	product,
		const char **	definition_file )

Get path to the coda definition file that describes the format for this product. This function will return a full path to the coda definition (.codadef) file that contains the format description for this product. If the format is not taken from an external coda definition description but based on the self-describing format information from the file itself or based on a hardcoded format definition within one of the coda backends then definition_file will be set to NULL.

Parameters

product	Pointer to a product file handle.
definition_file	Pointer to the variable where the path to used coda definition file will be stored (or NULL if not applicable).

Returns

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

◆ coda_get_product_file_size()

int coda_get_product_file_size	(	const coda_product *	product,
		int64_t *	file_size )

Get the actual file size of a product file.

Parameters

product	Pointer to a product file handle.
file_size	Pointer to the variable where the actual file size (in bytes) of the product is stored.

Returns

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

◆ coda_get_product_filename()

int coda_get_product_filename	(	const coda_product *	product,
		const char **	filename )

Get the filename of a product file. This function returns the same name that was used in the coda_open() call for this product file. The pointer to the filename string is valid as long as the file is open. When you call coda_close() on the product file the filename string will automatically be removed and the pointer that will be stored in filename will become invalid. The name of the product file will be stored in the filename parameter and will be 0 terminated.

Parameters

product	Pointer to a product file handle.
filename	Pointer to the variable where the filename of the product will be stored.

Returns

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

◆ coda_get_product_format()

int coda_get_product_format	(	const coda_product *	product,
		coda_format *	format )

Get the basic file format of the product. Possible formats are ascii, binary, xml, netcdf, grib, hdf4, cdf, and hdf5. Mind that inside a product different typed data can exist. For instance, both xml and binary products can have part of their content be ascii typed data.

Parameters

product	Pointer to a product file handle.
format	Pointer to the variable where the format will be stored.

Returns

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

◆ coda_get_product_root_type()

int coda_get_product_root_type	(	const coda_product *	product,
		coda_type **	type )

Get the CODA type of the root of the product. For self-describing data formats the definition from the codadef file will be returned if it exists, otherwise the definition based on the format as extracted from the product itself will be returned.

Note that for self-describing products with a codadef definition (except for xml) the product itself will always be interpreted using the definition as extracted from the product itself. The coda_get_product_root_type() function is then the means to retrieve the definition from the codadef and calling coda_cursor_get_type() for a cursor that points to the root of the product will return the definition as extracted from the product.

Parameters

product	Pointer to a product file handle.
type	Pointer to the variable where the Type handle will be stored.

Returns

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

◆ coda_get_product_type()

int coda_get_product_type	(	const coda_product *	product,
		const char **	product_type )

Get the product type of a product file. This function will return the name of the product type of a product. The name of the product type will be stored in the product_type parameter and will be 0 terminated. The string pointer that is returned for product_type does not have to be freed by the user and will remain valid until coda_done() is called.

Parameters

product	Pointer to a product file handle.
product_type	Pointer to the variable where the product type name of the product will be stored.

Returns

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

◆ coda_get_product_variable_value()

int coda_get_product_variable_value	(	coda_product *	product,
		const char *	variable,
		long	index,
		int64_t *	value )

Get the value for a product variable. CODA supports a mechanism called product variables to store frequently needed information of a product (i.e. information that is needed to calculate byte offsets or array sizes within a product). With this function you can retrieve the values for those product variables (consult the CODA Product Definition Documentation for an overview of product variables for a certain product type). Product variables can be one dimensional arrays, in which case you will have to pass an array index using the index parameter. If the product variable is a scalar you should pass 0 for index. The value of a product variable is always a 64-bit integer and will be stored in value.

Parameters

product	Pointer to a product file handle.
variable	The name of the product variable.
index	The array index of the product variable (pass 0 if the variable is a scalar).
value	Pointer to the variable where the product variable value will be stored.

Returns

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

◆ coda_get_product_version()

int coda_get_product_version	(	const coda_product *	product,
		int *	version )

Get the product type version of a product file. This function will return the format version number of a product. This version number is a rounded number and newer versions of a format will always have a version number that is higher than that of older formats.

Parameters

product	Pointer to a product file handle.
version	Pointer to the variable where the product version of the product type of the product will be stored.

Returns

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

◆ coda_open()

int coda_open	(	const char *	filename,
		coda_product **	product )

Open a product file for reading. This function will try to open the specified file for reading. On success a newly allocated file handle will be returned. The memory for this file handle will be released when coda_close() is called for this handle.

Parameters

filename	Relative or full path to the product file.
product	Pointer to the variable where the pointer to the product file handle will be storeed.

Returns

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

◆ coda_open_as()

int coda_open_as	(	const char *	filename,
		const char *	product_class,
		const char *	product_type,
		int	version,
		coda_product **	product )

Open a product file for reading using a specific format definition. This function will try to open the specified file for reading similar to coda_open(), but instead of trying to automatically recognise the applicable product class/type/version as coda_open() does, this function will impose the format definition that is associated with the given product_class, product_type, and version parameters.

Parameters

filename	Relative or full path to the product file.
product_class	Name of the product class for the requested format definition.
product_type	Name of the product type for the requested format definition.
version	Format version number of the product type definition. Use -1 to request the latest available definition.
product	Pointer to the variable where the pointer to the product file handle will be storeed.

Returns

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

◆ coda_recognize_file()

int coda_recognize_file	(	const char *	filename,
		int64_t *	file_size,
		coda_format *	file_format,
		const char **	product_class,
		const char **	product_type,
		int *	version )

Determine the file size, format, product class, product type, and format version of a product file. This function will perform an open and close on the product file and will try to automatically recognize the product class, type, and version of the product file. If the file is a netCDF, HDF4, or HDF5 file the file_format will be set, but product_class and product_type will be set to NULL and version will be set to -1. For XML the product_class, product_type, and version will only be set if there is an external definition available for the product (i.e. from one of the .codadef files in your CODA definition path). Otherwise the values will be NULL/-1. If a description of the product file is included in the data dictionary the product class, type, and version will be set according to what the automatic recognition rules have determined. The file_size will be set to the actual byte size of the file. It is possible to pass a NULL pointer for one or more of the parameters file_size, file_format, product_class, product_type, and product_version. If the parameter is NULL no value for this parameter is returned. The string pointers that are returned for product_class and product_type do not have to be freed by the user and will remain valid until coda_done() is called.

Parameters

filename	Relative or full path to the product file.
file_size	Pointer to the variable where the actual file size in bytes will be stored.
file_format	Pointer to the variable where the file format value will be stored.
product_class	Pointer to the variable where the product class string will be stored.
product_type	Pointer to the variable where the product type string will be stored.
version	Pointer to the variable where the product format version number will be stored.

Returns

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

Functions

Detailed Description

Function Documentation

◆ coda_close()

◆ coda_get_product_class()

◆ coda_get_product_definition_file()

◆ coda_get_product_file_size()

◆ coda_get_product_filename()

◆ coda_get_product_format()

◆ coda_get_product_root_type()

◆ coda_get_product_type()

◆ coda_get_product_variable_value()

◆ coda_get_product_version()

◆ coda_open()

◆ coda_open_as()

◆ coda_recognize_file()