CODA General

Macros
#define	CODA_MAX_NUM_DIMS   8

Enumerations
enum	coda_array_ordering_enum {   coda_array_ordering_c ,   coda_array_ordering_fortran }
enum	coda_filefilter_status_enum {   coda_ffs_error ,   coda_ffs_could_not_open_file ,   coda_ffs_could_not_access_directory ,   coda_ffs_unsupported_file ,   coda_ffs_match ,   coda_ffs_no_match }
enum	coda_format_enum {   coda_format_ascii ,   coda_format_binary ,   coda_format_xml ,   coda_format_hdf4 ,   coda_format_hdf5 ,   coda_format_cdf ,   coda_format_netcdf ,   coda_format_grib ,   coda_format_rinex ,   coda_format_sp3 }

Functions
int	coda_match_filefilter (const char *filefilter, int num_filepaths, const char **filepathlist, int(*callbackfunc)(const char *, coda_filefilter_status, const char *, void *), void *userdata)
long	coda_c_index_to_fortran_index (int num_dims, const long dim[], long index)
int	coda_isNaN (double x)
double	coda_NaN (void)
int	coda_isInf (double x)
int	coda_isPlusInf (double x)
int	coda_isMinInf (double x)
double	coda_PlusInf (void)
double	coda_MinInf (void)
void	coda_str64 (int64_t a, char *s)
void	coda_str64u (uint64_t a, char *s)
void	coda_strfl (double a, char *s)
int	coda_set_option_bypass_special_types (int enable)
int	coda_get_option_bypass_special_types (void)
int	coda_set_option_perform_boundary_checks (int enable)
int	coda_get_option_perform_boundary_checks (void)
int	coda_set_option_perform_conversions (int enable)
int	coda_get_option_perform_conversions (void)
int	coda_set_option_use_fast_size_expressions (int enable)
int	coda_get_option_use_fast_size_expressions (void)
int	coda_set_option_use_mmap (int enable)
int	coda_get_option_use_mmap (void)
int	coda_set_definition_path (const char *path)
int	coda_set_definition_path_conditional (const char *file, const char *searchpath, const char *relative_location)
int	coda_init (void)
void	coda_done (void)
void	coda_free (void *ptr)

Variables
THREAD_LOCAL const char *	libcoda_version

Detailed Description

The CODA General module contains all general and miscellaneous functions and procedures of CODA.

This module also contains the initialization and finalization functions of CODA. Before you call any other function of CODA you should initialize CODA with a call to coda_init(). This function sets up the Data Dictionary that describes all supported product files by reading all .codadef files from the CODA definition path. After you are finished with CODA you should call coda_done(). This ensures that all resources that were claimed by coda_init() are properly deallocated again. You should make sure, however, that all open product files are closed before you call coda_done() (the function will not close the files for you). After a coda_done() all product file handles and CODA cursors that still exist will become invalid and will stay invalid even after you call coda_init() again. Having invalid CODA cursors is not a real problem, as long as you do not use them anymore, but having invalid product file handles means you will be stuck with unfreed memory and unclosed files.

In order to let CODA know where your .codadef files are stored you will either have to set the CODA_DEFINITION environment variable or call the coda_set_definition_path() function (before calling coda_init()).

If no .codadef files are loaded, CODA will still be able to provide access to HDF4, HDF5, netCDF, and XML products by taking the format definition from the product files itself (for XML this will be 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).

Macro Definition Documentation

CODA_MAX_NUM_DIMS

#define CODA_MAX_NUM_DIMS   8

Maximum number of dimensions of a multidimensional array

Enumeration Type Documentation

coda_array_ordering_enum

enum coda_array_ordering_enum

Enumerator
coda_array_ordering_c	C array ordering (last dimension is fastest running)
coda_array_ordering_fortran	Fortran array ordering (first dimension is fastest running)

coda_filefilter_status_enum

enum coda_filefilter_status_enum

Enumerator
coda_ffs_error	error: General error (usually file I/O related)
coda_ffs_could_not_open_file	error: Could not open file
coda_ffs_could_not_access_directory	error: Could not recurse into directory
coda_ffs_unsupported_file	File can not be read by CODA
coda_ffs_match	File matches filter
coda_ffs_no_match	File does not match filter

coda_format_enum

enum coda_format_enum

Enumerator
coda_format_ascii	Data stored in structured ASCII format
coda_format_binary	Data stored in structured binary format
coda_format_xml	Data stored in XML format
coda_format_hdf4	Data stored in HDF4 format
coda_format_hdf5	Data stored in HDF5 format
coda_format_cdf	Data stored in CDF format
coda_format_netcdf	Data stored in NetCDF format
coda_format_grib	Data stored in GRIB format
coda_format_rinex	Data stored in RINEX format
coda_format_sp3	Data stored in SP3 format

Function Documentation

coda_c_index_to_fortran_index()

long coda_c_index_to_fortran_index	(	int	num_dims,
		const long	dim[],
		long	index )

Convert an index for a multidimensional array that is stored in C-style order to an index for an identical array stored in Fortran-style order.

While elements of a multidimensional array are normally referenced via subscripts, CODA also allows referencing through indices (which are one-dimensional). These indices (starting with 0) correspond with the positions of the array elements as they are physically stored. This makes it easy to enumerate all elements of a multi-dimensional array without having to deal with the multidimensional aspects of an array.

However, the mapping of an array of subscripts to an index/storage position (and vice versa) can be defined in essentially two ways.

The first, which is the way it is done in CODA is such that the last element of a subscript array is the one that is the fastest running. For example, for a two dimensional array, the second element would have index 1 and would correspond with the subscript (0, 1). This corresponds to the way multi-dimensional arrays are handled in C and therefore this type of index is called a C-style index.

The alternative way of providing an index is as it is done in Fortran, which has the first element of a subscript array as the fastest running. In the previous example, the second element of the two dimensional array with index 1 would correspond to the subscript (1, 0).

As an example, if we have an array with dimensions (3, 4), then the subscript (0, 2) would refer to the element with index 2 if the array was stored in C-style and would refer to the element with index 6 if it was stored in Fortran-style.

In order for a user to fill a multidimensional array in Fortran-style with data from a multi-dimensional array from a product using CODA (which uses C-style indexing), the user can use this function to provide the index conversions. A small example showing how this would be done with a multi-dimensional array of doubles:

coda_cursor_get_num_elements(cursor, &num_elements);
if (num_elements > 0)
{
    coda_cursor_get_array_dim(cursor, &num_dim, dims);
    coda_cursor_goto_first_array_element(cursor);
    for (i = 0; i < num_elements; i++)
    {
        int fortran_index = coda_c_index_to_fortran_index(num_dim, dims, i);
        coda_cursor_read_double(cursor, &fortran_multidim_array_ptr[fortran_index]);
        if (i < num_elements - 1)
        {
            coda_cursor_goto_next_array_element(cursor);
        }
    }
    coda_cursor_goto_parent(cursor);
}

See also

coda_cursor_goto_array_element_by_index()

Parameters

num_dims	Number of dimensions of the multidimensional array.
dim	Array with the dimensions of the multidimensional array.
index	C style index.

Returns

• >=0, Fortran style index.
• -1, Error occurred (check coda_errno).

coda_done()

void coda_done

(

void

)

Finalizes CODA. This function should be called to let the CODA library free up any resources it has claimed since initialization. It won't however clean up any product file handlers or close any product files that are still open. So you should first close any products that are still open with coda_close() before calling this function.

It is valid to perform multiple calls to coda_init() after each other. Only the first call to coda_init() will do the actual initialization and all following calls to coda_init() will only increase an initialization counter. Each call to coda_init() needs to be matched by a call to coda_done() at clean-up time (i.e. the amount of calls to coda_done() needs to be equal to the amount of calls to coda_init()). Only the last coda_done() call (when the initialization counter has reached 0) will do the actual clean-up of CODA. The clean-up will also reset any definition path that was set with coda_set_definition_path() or coda_set_definition_path_conditional().

Calling a CODA function other than coda_init() after the final coda_done() will result in undefined behavior. After reinitializing CODA again, accessing a product that was left open from a previous CODA 'session' will also result in undefined behavior.

coda_free()

void coda_free

(

void *

ptr

)

Free a memory block that was allocated by the CODA library. In some environments the library that performs the malloc is also the one that needs to perform the free. With this function memory that was allocated within the CODA library can be deallocated for such environments. It should be used in the following cases:

• to deallocate the memory for the 'value' variables of coda_expression_eval_string()

  Parameters

  ptr	The pointer whose memory should be freed.

coda_get_option_bypass_special_types()

int coda_get_option_bypass_special_types

(

void

)

Retrieve the current setting for the special types bypass option.

See also

coda_set_option_bypass_special_types()

Returns

• 0, Bypassing of special types is disabled.
• 1, Bypassing of special types is enabled.

coda_get_option_perform_boundary_checks()

int coda_get_option_perform_boundary_checks

(

void

)

Retrieve the current setting for the boundary check option.

See also

coda_set_option_perform_boundary_checks()

Returns

• 0, Boundary checking is disabled.
• 1, Boundary checking is enabled.

coda_get_option_perform_conversions()

int coda_get_option_perform_conversions

(

void

)

Retrieve the current setting for the value/unit conversion option.

See also

coda_set_option_perform_conversions()

Returns

• 0, Unit/value conversions are disabled.
• 1, Unit/value conversions are enabled.

coda_get_option_use_fast_size_expressions()

int coda_get_option_use_fast_size_expressions

(

void

)

Retrieve the current setting for the use of fast size expressions option.

See also

coda_set_option_use_fast_size_expressions()

Returns

• 0, Unit/value conversions are disabled.
• 1, Unit/value conversions are enabled.

coda_get_option_use_mmap()

int coda_get_option_use_mmap

(

void

)

Retrieve the current setting for the use of memory mapping of files.

See also

coda_set_option_use_mmap()

Returns

• 0, Memory mapping of files is disabled.
• 1, Memory mapping of files is enabled.

coda_init()

int coda_init

(

void

)

Initializes CODA. This function should be called before any other CODA function is called (except for coda_set_definition_path()).

If you want to use CODA to access non self-describing products (i.e. where the definition is provided via a .codadef file), you will have the set the CODA definition path to the location of your .codadef files before you call coda_init(). This can be done either via coda_set_definition_path() or via the CODA_DEFINITION environment variable.

It is valid to perform multiple calls to coda_init() after each other. Only the first call to coda_init() will do the actual initialization and all following calls to coda_init() will only increase an initialization counter (this also means that it is important that you set the CODA definition path before the first call to coda_init() is performed; changing the CODA definition path afterwards will have no effect). Each call to coda_init() needs to be matched by a call to coda_done() at clean-up time (i.e. the amount of calls to coda_done() needs to be equal to the amount of calls to coda_init()). Only the last coda_done() call (when the initialization counter has reached 0) will do the actual clean-up of CODA.

Returns

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

coda_isInf()

int coda_isInf

(

double

x

)

Find out whether a double value equals inf (either positive or negative infinity).

Parameters

x	A double value.

Returns

• 1, The double value equals inf.
• 0, The double value does not equal inf.

coda_isMinInf()

int coda_isMinInf

(

double

x

)

Find out whether a double value equals -inf (negative infinity).

Parameters

x	A double value.

Returns

• 1, The double value equals -inf.
• 0, The double value does not equal -inf.

coda_isNaN()

int coda_isNaN

(

double

x

)

Find out whether a double value equals NaN (Not a Number).

Parameters

x	A double value.

Returns

• 1, The double value equals NaN.
• 0, The double value does not equal NaN.

coda_isPlusInf()

int coda_isPlusInf

(

double

x

)

Find out whether a double value equals +inf (positive infinity).

Parameters

x	A double value.

Returns

• 1, The double value equals +inf.
• 0, The double value does not equal +inf.

coda_match_filefilter()

int coda_match_filefilter	(	const char *	filefilter,
		int	num_filepaths,
		const char **	filepathlist,
		int(*)(const char *, coda_filefilter_status, const char *, void *)	callbackfunc,
		void *	userdata )

Find product files matching a specific filter. With this function you can match a series of files or directories against a specific filter. The filter needs to be provided as a string. For information about its format please look at the documentation of the codafind tool which is also included with the CODA package. If you leave filefilter empty or pass a NULL pointer then each file that can be opened by CODA will be matched positively (this has the same effect as if you had passed a filefilter "true").

The names of the files and directories need to be passed as an array of full/relative paths. If an entry is a directory then all files and directories that are contained inside will be added to the filter matching. Directories within directories are processed recursively.

For each file that is processed a callback function, which will have to be provided by the user, will be called. The callback function will be passed the path of the file, a status value indicating the match result, optionally an error string in case an error happened, and the userdata pointer that was passed to the coda_match_filefilter() function. The return value of the callback function determines whether the rest of the files/directories should be processed. If you return 0 from the callback function then processing will continue normally. If you return a different value, then the coda_match_filefilter() function will stop further processing and return the same return value to your program as you have returned from the callback function. It is recommended not to use -1 as return value in your callback function, since coda_match_filefilter() will already return -1 if it encounters an error internally.

A small example of a callback function is given below

int callback(const char *filepath, coda_filefilter_status status, const char *error, void *userdata)
{
    switch (status)
    {
        case coda_ffs_match:
            printf("File \"%s\" matches filter!\n", filepath);
            break;
        case coda_ffs_unsupported_file:
        case coda_ffs_no_match:
            // don't print anything if the file does not positively match the filter
            break;
        default:
            if (error != NULL)
            {
                printf("ERROR: %s\n", error);
            }
            break;
    }
    return 0; // if possible continue processing the other files
}

Parameters

filefilter	String containing the filter.
num_filepaths	Number of filepaths in filepathlist (0 < num_filepaths).
filepathlist	Array of strings containing relative or absolute paths to a series of files and/or directories that should be matched against the filefilter.
callbackfunc	A pointer to a function that should be called with the match result of a file that has been processed.
userdata	A pointer to a user definable data block that will be passed along to the user callback function.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).
• other, The return value from the last call to the callback function.

coda_MinInf()

double coda_MinInf

(

void

)

Retrieve a double value that respresents -inf (negative infinity).

Returns

The double value '-inf'.

coda_NaN()

double coda_NaN

(

void

)

Retrieve a double value that respresents NaN (Not a Number).

Returns

The double value 'NaN'.

coda_PlusInf()

double coda_PlusInf

(

void

)

Retrieve a double value that respresents +inf (positive infinity).

Returns

The double value '+inf'.

coda_set_definition_path()

int coda_set_definition_path

(

const char *

path

)

Set the searchpath for CODA product definition files. This function should be called before coda_init() is called.

The path should be a searchpath for CODA .codadef files similar like the PATH environment variable of your system. Path components should be separated by ';' on Windows and by ':' on other systems.

The path may contain both references to files and directories. CODA will load all .codadef files in the path. Any specified files should be valid .codadef files. For directories, CODA will (non-recursively) search the directory for all .codadef files.

If multiple files for the same product class exist in the path, CODA will only use the one with the highest revision number (this is normally equal to a last modification date that is stored in a .codadef file). If there are two files for the same product class with identical revision numbers, CODA will use the definitions of the first .codadef file in the path and ingore the second one.

Specifying a path using this function will prevent CODA from using the CODA_DEFINITION environment variable. If you still want CODA to acknowledge the CODA_DEFINITION environment variable then use something like this in your code:

if (getenv("CODA_DEFINITION") == NULL)
{
    coda_set_definition_path("<your path>");
}

Parameters

path	Search path for .codadef files

Returns

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

coda_set_definition_path_conditional()

int coda_set_definition_path_conditional	(	const char *	file,
		const char *	searchpath,
		const char *	relative_location )

Set the directory for CODA product definition files based on the location of another file. This function should be called before coda_init() is called.

This function will try to find the file with filename file in the provided searchpath searchpath. The first directory in the searchpath where the file file exists will be appended with the relative directory relative_location to determine the CODA product definition path. This path will be used as CODA definition path. If the file could not be found in the searchpath then the CODA definition path will not be set.

If the CODA_DEFINITION environment variable was set then this function will not perform a search or set the definition path (i.e. the CODA definition path will be taken from the CODA_DEFINITION variable).

If you provide NULL for searchpath then the PATH environment variable will be used as searchpath. For instance, you can use coda_set_definition_path_conditional(argv[0], NULL, "../somedir") to set the CODA definition path to a location relative to the location of your executable.

The searchpath, if provided, should have a similar format as the PATH environment variable of your system. Path components should be separated by ';' on Windows and by ':' on other systems.

The relative_location parameter can point either to a directory (in which case all .codadef files in this directory will be used) or to a single .codadef file.

Note that this function differs from coda_set_definition_path() in two important ways:

• it will not modify the definition path if the CODA_DEFINITION variable was set
• it will set the definition path to just a single location (either a single file or a single directory)

Parameters

file	Filename of the file to search for
searchpath	Search path where to look for the file file (can be NULL)
relative_location	Filepath relative to the directory from searchpath where file was found that should be used to determine the CODA definition path.

Returns

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

coda_set_option_bypass_special_types()

int coda_set_option_bypass_special_types

(

int

enable

)

Enable/Disable the use of special types. The CODA type system contains a series of special types that were introduced to make it easier for the user to read certain types of information. Examples of special types are the 'time', 'complex', and 'no data' types. Each special data type is an abstraction on top of another non-special data type. Sometimes you want to access a file using just the non-special data types (e.g. if you want to get to the raw time data in a file). CODA already contains the coda_cursor_use_base_type_of_special_type() function that allows you to reinterpret the current special data type using the base type of the special type. However, if you enable the bypassing of special types option then CODA automatically calls the coda_cursor_use_base_type_of_special_type() for you whenever you move a cursor to a data item that is of a special type. By default bypassing of special types is disabled.

Note

Bypassing of special types only works on CODA cursors and not on coda_type objects (e.g. if a record field is of a special type the coda_type_get_record_field_type() function will still give you the special type and not the non-special base type).

Parameters

enable

0: Disable bypassing of special types. 1: Enable bypassing of special types.

Returns

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

coda_set_option_perform_boundary_checks()

int coda_set_option_perform_boundary_checks

(

int

enable

)

Enable/Disable boundary checking. By default all functions in libcoda perform boundary checks. However some boundary checks are quite compute intensive. In order to increase performance you can turn off those compute intensive boundary checks with this option. The boundary checks that are affected by this option are the ones in coda_cursor_goto_array_element_by_index() and coda_cursor_goto_next_array_element(). Some internal functions of libcoda also call these functions so you might see speed improvements for other functions too if you disable the boundary checks. Mind that this option does not control the out-of-bounds check for trying to read beyond the end of the product (i.e. CODA_ERROR_OUT_OF_BOUNDS_READ).

Parameters

enable

0: Disable boundary checking. 1: Enable boundary checking.

Returns

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

coda_set_option_perform_conversions()

int coda_set_option_perform_conversions

(

int

enable

)

Enable/Disable unit/value conversions. This options allows conversions to be performed as specified in the data-dictionary. If this option is enabled (the default), values that have a conversion specified will be converted to a value of type double and scaled according to the conversion parameters when read.

Both the type, unit, and value-as-read are influenced by this option for types that have an associated conversion. If conversions are disabled, the type, unit, and value will reflect how data is actually stored in the product file (i.e. without conversion).

Parameters

enable

0: Disable unit/value conversions. 1: Enable unit/value conversions.

Returns

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

coda_set_option_use_fast_size_expressions()

int coda_set_option_use_fast_size_expressions

(

int

enable

)

Enable/Disable the use of fast size expressions. Sometimes product files contain information that can be used to directly retrieve the size (or offset) of a data element. If this information is redundant (i.e. the size and/or offset can also be determined in another way) then CODA has a choice whether to use this information or not.

For instance, CODA normally calculates the size of a record by calculating the sizes of all the fields and adding them up. But if one of the first fields of the record contains the total size of the record, CODA can also use the (often) faster approach of determining the record size by using the contents of this field.

If the use of fast size expressions is enabled (the default), CODA will use the 'faster' method of retrieving the size/offset information for a data element (e.g. use the contents of the record field that contains the record size). Note that this faster method only occurs when the data element, such as the record, also has a 'fast expression' associated with it (if this is the case then this expression is shown in the Product Format Definition documentation for the data element).

If this option is disabled then CODA will only use the traditional method for calculating the size (or offset) and thus ignore any 'fast expressions' that may exist.

Sometimes the size (or offset) information in a product is incorrect. If this is the case, you can disable the use of fast size expressions with this option so CODA might still access the product correctly.

Parameters

enable

0: Disable the use of fast size expressions. 1: Enable the use of fast size expressions.

Returns

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

coda_set_option_use_mmap()

int coda_set_option_use_mmap

(

int

enable

)

Enable/Disable the use of memory mapping of files. By default CODA uses a technique called 'memory mapping' to open and access data from product files. The memory mapping approach is a very fast approach that uses the mmap() function to (as the term suggests) map a file in memory. Accessing data from a file using mmap() greatly outperforms the alternative approach of reading data using the open()/read() combination (often by a factor of 5 and sometimes even more).

The downside of mapping a file into memory is that it takes away valuable address space. When you run a 32-bit Operating System your maximum addressable memory range is 4GB (or 2GB) and if you simultaneously try to keep a few large product files open your memory space can quickly become full. Opening additional files will then produce 'out of memory' errors. Note that this 'out of memory' situation has nothing to do with the amount of RAM you have installed in your computer. It is only related to the size of a memory pointer on your system, which is limited to 4GB for a 32 bits pointer.

If you are using CODA in a situation where you need to have multiple large product files open at the same time you can turn off the use of memory mapping by using this function. Disabling the use of mmap() means that CODA will fall back to the mechanism of open()/read().

In addition, the open()/read() functionality in CODA is able to handle files that are over 4GB in size. If you are running a 32-bit operating system or if your system does not support a 64-bit version of mmap then you can still access such large files by disabling the mmap functionality and falling back to the open()/read() mechanism.

Note

If you change the memory mapping usage option, the new setting will only be applicable for files that will be opened after you changed the option. Any files that were already open will keep using the mechanism with which they were opened.

Parameters

enable

0: Disable the use of memory mapping. 1: Enable the use of memory mapping.

Returns

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

coda_str64()

void coda_str64	(	int64_t	a,
		char *	s )

Write 64 bit signed integer to a string. The string s will be 0 terminated.

Parameters

a	A signed 64 bit integer value.
s	A character buffer that is at least 21 bytes long.

coda_str64u()

void coda_str64u	(	uint64_t	a,
		char *	s )

Write 64 bit unsigned integer to a string. The string s will be 0 terminated.

Parameters

a	An unsigned 64 bit integer value.
s	A character buffer that is at least 20 bytes long.

coda_strfl()

void coda_strfl	(	double	a,
		char *	s )

Write floating point value to a string. This will write the floating point value to a string using the printf '%.16g' format. However, if the floating point is NaN or Inf it will write 'nan', '+inf', or '-inf' (instead of the platform specific alternative that printf might have used). The string s will be 0 terminated.

Parameters

a	A floating point value.
s	A character buffer that is at least 24 bytes long.

Variable Documentation

libcoda_version

THREAD_LOCAL const char* libcoda_version

Current version of CODA as a string.