C Reference

Initialisation

const int ODC_INTEGERS_AS_DOUBLES = 1

Represent integers as doubles in the API (default)

const int ODC_INTEGERS_AS_LONGS = 2

Represent integers as 64-bit integers in the API

int odc_initialise_api()

Initialises API, must be called before any other function

Note

This is only required if being used from a context where eckit::Main() is not otherwise initialised.

Returns:

Return code (OdcErrorValues)

int odc_integer_behaviour(int integerBehaviour)

Sets treatment of integers in the odc API

Parameters:
Returns:

Return code (OdcErrorValues)

Version Accessors

int odc_version(const char **version)

Retrieves the release version of the library in human-readable format, e.g. 1.3.0

Parameters:

  • version – Return variable for release version. Returned pointer valid throughout program lifetime.

Returns:

Return code (OdcErrorValues)

int odc_vcs_version(const char **version)

Retrieves version control checksum of the latest change, e.g. a88011c007a0db48a5d16e296934a197eac2050a

Parameters:

  • version – Return variable for version control checksum. Returned pointer valid throughout program lifetime.

Returns:

Return code (OdcErrorValues)

Error Handling

enum OdcErrorValues

Return codes

Values:

enumerator ODC_SUCCESS

The function completed successfully

enumerator ODC_ITERATION_COMPLETE

All frames have been returned, and the loop can be terminated successfully.

enumerator ODC_ERROR_GENERAL_EXCEPTION

A known error was encountered. Call odc_error_string() with the returned code for details.

enumerator ODC_ERROR_UNKNOWN_EXCEPTION

An unexpected and unknown error was encountered. Call odc_error_string() with the returned code for details.

typedef void (*odc_failure_handler_t)(void *context, int error_code)

Error handler callback function signature

Param context:

Error handler context

Param error_code:

Error code (OdcErrorValues)

const char *odc_error_string(int err)

Returns a human-readable error message for the last error given an error code

Parameters:
Returns:

Error message

int odc_set_failure_handler(odc_failure_handler_t handler, void *context)

Sets an error handler which will be called on error with the supplied context and an error code

Parameters:

  • handler – Error handler function

  • context – Error handler context

Values and Types

enum OdcColumnType

Column data types

Values:

enumerator ODC_IGNORE

Specifies that the column is ignored (invalid for real data)

enumerator ODC_INTEGER

Specifies the column contains integer data

enumerator ODC_REAL

Specifies the column contains 32-bit floating point values

enumerator ODC_STRING

Specifies the column contains character (string) data

enumerator ODC_BITFIELD

Specifies the column contains bitfield data

enumerator ODC_DOUBLE

Specifies the column contains 64-bit floating point values

int odc_column_type_count(int *count)

Retrieves number of supported column data types

Parameters:

  • count – Return variable for number of data types

Returns:

Return code (OdcErrorValues)

int odc_column_type_name(int type, const char **type_name)

Retrieves a human-readable name of a column data type

Parameters:

  • type – Column data type (OdcColumnType)

  • type_name – Return variable for column data type name. Returned pointer valid throughout program lifetime.

Returns:

Return code (OdcErrorValues)

int odc_set_missing_integer(long missing_integer)

Sets the value that identifies a missing integer in the API

Parameters:

  • missing_integer – Missing integer value

Returns:

Return code (OdcErrorValues)

int odc_set_missing_double(double missing_double)

Sets the value that identifies a missing double in the API

Parameters:

  • missing_double – Missing double value

Returns:

Return code (OdcErrorValues)

int odc_missing_integer(long *missing_value)

Retrieves the value that identifies a missing integer in the API

Parameters:

  • missing_value – Return variable for missing integer value

Returns:

Return code (OdcErrorValues)

int odc_missing_double(double *missing_value)

Retrieves the value that identifies a missing double in the API

Parameters:

  • missing_value – Return variable for missing double value

Returns:

Return code (OdcErrorValues)

Reader

typedef struct odc_reader_t odc_reader_t

Opaque type for the Reader object. Controls the ODB-2 data stream and associated resources, and gives access to the underlying frames.

typedef long (*odc_stream_read_t)(void *context, void *buffer, long length)

Reader stream handler callback function signature. Functions analogously to the POSIX read() function.

Param context:

Stream handler context

Param buffer:

Memory buffer to handle

Param buffer:

Size of the memory buffer

int odc_open_path(odc_reader_t **reader, const char *filename)

Creates a reader and opens the specified file path

Parameters:

  • reader – Reader instance. Returned instance must be freed using odc_close.

  • filename – File path to open

Returns:

Return code (OdcErrorValues)

int odc_open_file_descriptor(odc_reader_t **reader, int fd)

Creates a reader from an already open file descriptor.

The file descriptor will be duplicated so the calling code is safe to close the file descriptor.

Parameters:

  • reader – Reader instance. Returned instance must be freed using odc_close.

  • fd – File descriptor

Returns:

Return code (OdcErrorValues)

int odc_open_buffer(odc_reader_t **reader, const void *data, long length)

Creates a reader from a memory buffer

Parameters:

  • reader – Reader instance. Returned instance must be freed using odc_close.

  • data – Memory buffer

  • length – Length of memory buffer

Returns:

Return code (OdcErrorValues)

int odc_open_stream(odc_reader_t **reader, void *context, odc_stream_read_t stream_proc)

Creates a reader associated to a custom stream handler. The callback specified will be called in the same way as the POSIX read() function to obtain data from the custom stream.

Parameters:

  • reader – Reader instance. Returned instance must be freed using odc_close.

  • context – Stream handler context

  • stream_proc – Stream handler function

Returns:

Return code (OdcErrorValues)

int odc_close(const odc_reader_t *reader)

Closes opened resource and destroys the reader

Parameters:

  • reader – Reader instance

Returns:

Return code (OdcErrorValues)

Frame

typedef struct odc_frame_t odc_frame_t

Opaque type for the Frame object. Provides a viewport onto a chunk of contiguous data within the ODB-2 stream.

int odc_new_frame(odc_frame_t **frame, odc_reader_t *reader)

Creates a frame instance associated with a specific reader instance, for interrogating ODB-2 data

Parameters:

  • frame – Frame instance. Returned instance must be freed using odc_free_frame.

  • reader – Reader instance

Returns:

Return code (OdcErrorValues)

int odc_free_frame(const odc_frame_t *frame)

Deallocates frame object and associated resources.

Parameters:

  • frame – Frame instance

Returns:

Return code (OdcErrorValues)

int odc_next_frame(odc_frame_t *frame)

Advances the viewport to the next frame in the stream

Parameters:

  • frame – Frame instance

Returns:

Return code (OdcErrorValues)

int odc_next_frame_aggregated(odc_frame_t *frame, long maximum_rows)

Advances the viewport to the next logical frame in the stream

Parameters:

  • frame – Frame instance

  • maximum_rows – Maximum number of rows to aggregate into one logical frame

Returns:

Return code (OdcErrorValues)

int odc_copy_frame(odc_frame_t *source_frame, odc_frame_t **copy)

Creates an independent copy of the frame object, resulting in an independent viewport on the ODB data stream with its own associated resources. To use the new copied frame independently from the first requires the ODB-2 data stream to be seekable.

Parameters:

  • source_frame – Source frame instance to copy from

  • copy – Target frame instance to copy to. Returned instance must be freed using odc_free_frame.

Returns:

Return code (OdcErrorValues)

int odc_frame_row_count(const odc_frame_t *frame, long *count)

Retrieves number of rows in the frame

Parameters:

  • frame – Frame instance

  • count – Return variable for number of rows

Returns:

Return code (OdcErrorValues)

int odc_frame_column_count(const odc_frame_t *frame, int *count)

Retrieves number of columns in the frame

Parameters:

  • frame – Frame instance

  • count – Return variable for number of columns

Returns:

Return code (OdcErrorValues)

int odc_frame_column_attributes(const odc_frame_t *frame, int col, const char **name, int *type, int *element_size, int *bitfield_count)

Retrieves column attributes from current frame

Parameters:

  • frame – Frame instance

  • col – Target column index

  • name – (optional) Return variable for column name. Returned pointer valid until frame object destroyed or advanced to the next frame.

  • type – (optional) Return variable for column type

  • element_size – (optional) Return variable for column size in bytes

  • bitfield_count – (optional) Return variable for number of column bitfields

Returns:

Return code (OdcErrorValues)

int odc_frame_bitfield_attributes(const odc_frame_t *frame, int col, int entry, const char **name, int *offset, int *size)

Retrieves bitfield attributes of a column

Parameters:

  • frame – Frame instance

  • col – Target column index

  • entry – Target bitfield index

  • name – (optional) Return variable for bitfield name. Returned pointer valid until frame object destroyed or advanced to the next frame.

  • offset – (optional) Return variable for bitfield offset

  • size – (optional) Return variable for bitfield size in bits

Returns:

Return code (OdcErrorValues)

int odc_frame_properties_count(const odc_frame_t *frame, int *nproperties)

Retrieves the number of properties encoded in the frame

Parameters:

  • frame – Frame instance

  • nproperties – Return variable for number of properties

Returns:

Return code (OdcErrorValues)

int odc_frame_property_idx(const odc_frame_t *frame, int idx, const char **key, const char **value)

Retrieves the property key and value by its index

Parameters:

  • frame – Frame instance

  • idx – Property index

  • key – Return variable for property key. Returned pointer valid until frame object destroyed or advanced to the next frame.

  • value – Return variable for property value. Returned pointer valid until frame object destroyed or advanced to the next frame.

Returns:

Return code (OdcErrorValues)

int odc_frame_property(const odc_frame_t *frame, const char *key, const char **value)

Retrieves the property value by its key

Parameters:

  • frame – Frame instance

  • key – Property key

  • value – Return variable for property value. Returned pointer valid until frame object destroyed or advanced to the next frame.

Returns:

Return code (OdcErrorValues)

Decoder

typedef struct odc_decoder_t odc_decoder_t

Opaque type for the Decoder object. Specifies which ODB-2 columns should be decoded and the memory that should be used for the decoded data.

int odc_new_decoder(odc_decoder_t **decoder)

Creates a decoder instance for decoding ODB-2 format

Parameters:

  • decoder – Decoder instance. Returned instance must be freed using odc_free_decoder.

Returns:

Return code (OdcErrorValues)

int odc_free_decoder(const odc_decoder_t *decoder)

Deallocates memory used up by a decoder

Parameters:

  • decoder – Decoder instance

Returns:

Return code (OdcErrorValues)

int odc_decoder_defaults_from_frame(odc_decoder_t *decoder, const odc_frame_t *frame)

Configures a decoder to decode all data contained in the supplied frame

Parameters:

  • decoder – Decoder instance

  • frame – Frame instance

Returns:

Return code (OdcErrorValues)

int odc_decoder_set_column_major(odc_decoder_t *decoder, bool columnMajor)

Instructs the decoder whether to output in column-major form

Parameters:

  • decoder – Decoder instance

  • columnMajor – Whether to output in column-major form

Returns:

Return code (OdcErrorValues)

int odc_decoder_set_row_count(odc_decoder_t *decoder, long nrows)

Sets number of rows to allocate in a decoder

Parameters:

  • decoder – Decoder instance

  • nrows – Number of rows to allocate

Returns:

Return code (OdcErrorValues)

int odc_decoder_row_count(const odc_decoder_t *decoder, long *nrows)

Retrieves number of rows that are allocated in a decoder

Parameters:

  • decoder – Decoder instance

  • nrows – Return variable for number of rows

Returns:

Return code (OdcErrorValues)

int odc_decoder_set_data_array(odc_decoder_t *decoder, void *data, long width, long height, bool columnMajor)

Sets an output data array into which the data may be decoded

Parameters:

  • decoder – Decoder instance

  • data – Data array to decode into

  • width – Width of data array in bytes

  • height – Height of data array in rows

  • columnMajor – Whether the column-major memory layout is used

Returns:

Return code (OdcErrorValues)

int odc_decoder_data_array(const odc_decoder_t *decoder, const void **data, long *width, long *height, bool *columnMajor)

Retrieves the output data array into which the data may be decoded

Parameters:

  • decoder – Decoder instance

  • data – (optional) Data array to decode into. Returned pointer valid until decoder object destroyed.

  • width – (optional) Width of data array in bytes

  • height – (optional) Height of data array in rows

  • columnMajor – (optional) Whether the column-major memory layout is used

Returns:

Return code (OdcErrorValues)

int odc_decoder_add_column(odc_decoder_t *decoder, const char *name)

Adds a data column to a decoder

Parameters:

  • decoder – Decoder instance

  • name – Data column name

Returns:

Return code (OdcErrorValues)

int odc_decoder_column_count(const odc_decoder_t *decoder, int *count)

Retrieves number of columns that are allocated in a decoder

Parameters:

  • decoder – Decoder instance

  • count – Return variable for number of columns

Returns:

Return code (OdcErrorValues)

int odc_decoder_column_set_data_size(odc_decoder_t *decoder, int col, int element_size)

Sets the decoded data size for a column in bytes

Parameters:

  • decoder – Decoder instance

  • col – Column index

  • element_size – Column data size in bytes

Returns:

Return code (OdcErrorValues)

int odc_decoder_column_set_data_array(odc_decoder_t *decoder, int col, int element_size, int stride, void *data)

Sets an output data array into which the data associated with the column can be decoded

Parameters:

  • decoder – Decoder instance

  • col – Column index

  • element_size – Column data size in bytes

  • stride – Column data width in bytes

  • data – Column data array

Returns:

Return code (OdcErrorValues)

int odc_decoder_column_data_array(const odc_decoder_t *decoder, int col, int *element_size, int *stride, const void **data)

Retrieves the buffer and data layout into which the data has been decoded

Parameters:

  • decoder – Decoder instance

  • col – Column index

  • element_size – (optional) Return variable for column data size in bytes

  • stride – (optional) Return variable for column data width in bytes

  • data – (optional) Return variable for column data array. Returned pointer valid until decoder object destroyed.

Returns:

Return code (OdcErrorValues)

int odc_decode(odc_decoder_t *decoder, const odc_frame_t *frame, long *rows_decoded)

Decodes the data described by the frame into the configured data array(s)

Parameters:

  • decoder – Decoder instance

  • frame – Frame instance

  • rows_decoded – (optional) Return variable for number of decoded rows

Returns:

Return code (OdcErrorValues)

int odc_decode_threaded(odc_decoder_t *decoder, const odc_frame_t *frame, long *rows_decoded, int nthreads)

Decodes the data described by the frame into the configured data array(s).

If the frame is a logical one, parallelise the decoding over multiple threads.

Parameters:

  • decoder – Decoder instance

  • frame – Frame instance

  • rows_decoded – (optional) Return variable for number of decoded rows

  • nthreads – Number of threads

Returns:

Return code (OdcErrorValues)

Encoder

typedef struct odc_encoder_t odc_encoder_t

Opaque type for the Encoder object. Describes the column properties and the data layout of the source data for encoding into ODB-2 frames.

typedef long (*odc_stream_write_t)(void *context, const void *buffer, long length)

Encoder stream handler function signature

Param context:

Stream handler context

Param buffer:

Memory buffer to handle

Param length:

Size of memory buffer in bytes

int odc_new_encoder(odc_encoder_t **encoder)

Creates an encoder instance for encoding into ODB-2 format

Parameters:

  • encoder – Encoder instance. Returned instance must be freed using odc_free_encoder.

Returns:

Return code (OdcErrorValues)

int odc_free_encoder(const odc_encoder_t *encoder)

Deallocates memory used up by an encoder

Parameters:

  • encoder – Encoder instance

Returns:

Return code (OdcErrorValues)

int odc_encoder_add_property(odc_encoder_t *encoder, const char *key, const char *value)

Adds a key/value property to encode as part of the frame

Parameters:

  • encoder – Encoder instance

  • key – Property key

  • value – Property value

Returns:

Return code (OdcErrorValues)

int odc_encoder_set_row_count(odc_encoder_t *encoder, long nrows)

Sets number of rows to allocate in an encoder

Parameters:

  • encoder – Encoder instance

  • nrows – Number of rows

Returns:

Return code (OdcErrorValues)

int odc_encoder_set_rows_per_frame(odc_encoder_t *encoder, long rows_per_frame)

Sets number of rows to encode per frame

Parameters:

  • encoder – Encoder instance

  • rows_per_frame – Number of rows per frame

Returns:

Return code (OdcErrorValues)

int odc_encoder_set_data_array(odc_encoder_t *encoder, const void *data, long width, long height, int columnMajorWidth)

Sets input data array from which data may be encoded

Parameters:

  • encoder – Encoder instance

  • data – Data array to encode

  • width – Width of the data array in bytes

  • height – Height of the data array in rows

  • columnMajorWidth – Column size in bytes for column-major layout, if zero interpret as row-major layout

Returns:

Return code (OdcErrorValues)

int odc_encoder_add_column(odc_encoder_t *encoder, const char *name, int type)

Adds a data column to current encoder

Parameters:

  • encoder – Encoder instance

  • name – Column name

  • type – Column data type (OdcColumnType)

Returns:

Return code (OdcErrorValues)

int odc_encoder_column_set_data_size(odc_encoder_t *encoder, int col, int element_size)

Sets the source data size for a column

Parameters:

  • encoder – Encoder instance

  • col – Column index

  • element_size – Column data size in bytes

Returns:

Return code (OdcErrorValues)

int odc_encoder_column_set_data_array(odc_encoder_t *encoder, int col, int element_size, int stride, const void *data)

Sets a custom data layout and data array for a column

Parameters:

  • encoder – Encoder instance

  • col – Column index

  • element_size – Column size in bytes

  • stride – Column width in bytes

  • data – Column data array

Returns:

Return code (OdcErrorValues)

int odc_encoder_column_add_bitfield(odc_encoder_t *encoder, int col, const char *name, int nbits)

Adds a bitfield to a column

Parameters:

  • encoder – Encoder instance

  • col – Column index

  • name – Bitfield name

  • nbits – Bitfield size in bits

Returns:

Return code (OdcErrorValues)

int odc_encode_to_stream(odc_encoder_t *encoder, void *context, odc_stream_write_t write_fn, long *bytes_encoded)

Encodes ODB-2 into a stream handler

Parameters:

  • encoder – Encoder instance

  • context – Stream handler context

  • write_fn – Stream handler function

  • bytes_encoded – Return variable for number of encoded bytes

Returns:

Return code (OdcErrorValues)

int odc_encode_to_file_descriptor(odc_encoder_t *encoder, int fd, long *bytes_encoded)

Encodes ODB-2 into an already open file descriptor

Parameters:

  • encoder – Encoder instance

  • fd – File descriptor

  • bytes_encoded – (optional) Return variable for number of encoded bytes

Returns:

Return code (OdcErrorValues)

int odc_encode_to_buffer(odc_encoder_t *encoder, void *buffer, long length, long *bytes_encoded)

Encodes ODB-2 into a pre-allocated memory buffer

Parameters:

  • encoder – Encoder instance

  • buffer – Memory buffer

  • length – Buffer size

  • bytes_encoded – (optional) Return variable for number of encoded bytes

Returns:

Return code (OdcErrorValues)