Fortran Reference
Types
- type odc_reader
Controls the ODB-2 data stream and associated resources, and gives access to the underlying frames
- type odc_frame
Provides a viewport into a chunk of contiguous data within the ODB-2 stream
- Type fields:
% initialise (reader) ::
🔗% free () ::
🔗% copy (new_frame) ::
🔗% next ([aggregated, maximum_rows]) ::
🔗% row_count (nrows) ::
🔗% column_count (ncols) ::
🔗% column_attributes (col[, name, type, element_size, element_size_doubles, bitfield_count]) ::
🔗% bitfield_attributes (col, field[, name, offset, size]) ::
🔗% properties_count (nproperties) ::
🔗% property_idx (idx, key, val) ::
🔗% property (key[, val, exists]) ::
🔗
- type odc_decoder
Specifies which ODB-2 columns should be decoded and the memory that the decoded data should be put into
- Type fields:
% initialise ([column_major]) ::
🔗% free () ::
🔗% defaults_from_frame (frame) ::
🔗% set_row_count (count) ::
🔗% row_count (count) ::
🔗% set_data (data[, column_major]) ::
🔗% data ([data, column_major]) ::
🔗% add_column (name) ::
🔗% column_count (count) ::
🔗% column_set_data_size (col, element_size) ::
🔗% column_set_data_array (col[, element_size, stride, data]) ::
🔗% column_data_array (col[, element_size, element_size_doubles, stride, data]) ::
🔗% decode (frame, rows_decoded[, nthreads]) ::
🔗
- type odc_encoder
Describes data in memory and encodes it into ODB-2 frames
- Type fields:
% column_major [logical] :: Whether the column-major memory layout is used
% initialise () ::
🔗% free () ::
🔗% set_row_count (row_count) ::
🔗% set_rows_per_frame (rows_per_frame) ::
🔗% set_data (data[, column_major]) ::
🔗% add_column (name, type) ::
🔗% add_property (key, val) ::
🔗% column_set_data_size (col[, element_size, element_size_doubles]) ::
🔗% column_set_data_array (col[, element_size, element_size_doubles, stride, data]) ::
🔗% column_add_bitfield (col, name, nbits) ::
🔗% encode (outunit, bytes_written) ::
🔗
Constants
Column Data Types
- ODC_IGNORE [integer(c_int),parameter=0]
Specifies that the column is ignored (invalid for real data)
- ODC_INTEGER [integer(c_int),parameter=1]
Specifies the column contains integer data
- ODC_REAL [integer(c_int),parameter=2]
Specifies the column contains 32-bit floating point values
- ODC_STRING [integer(c_int),parameter=3]
Specifies the column contains character (string) data
- ODC_BITFIELD [integer(c_int),parameter=4]
Specifies the column contains bitfield data
- ODC_DOUBLE [integer(c_int),parameter=5]
Specifies the column contains 64-bit floating point values
Return Codes
- ODC_SUCCESS [integer,parameter=0]
The function completed successfully
- ODC_ITERATION_COMPLETE [integer,parameter=1]
All frames have been returned, and the loop can be terminated successfully.
- ODC_ERROR_GENERAL_EXCEPTION [integer,parameter=2]
A known error was encountered. Call
odc_error_string()with the returned code for details.
- ODC_ERROR_UNKNOWN_EXCEPTION [integer,parameter=3]
An unexpected and unknown error was encountered. Call
odc_error_string()with the returned code for details.
Integer Behaviour
- ODC_INTEGERS_AS_DOUBLES [integer,parameter=1]
Represent integers as doubles in the API (default)
- ODC_INTEGERS_AS_LONGS [integer,parameter=2]
Represent integers as 64-bit integers in the API
Module Functions
- function 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.
- Return:
err [integer] :: Return code 🔗
- function odc_version(version_str)
Retrieves the release version of the library in human-readable format, e.g.
1.3.0- Parameters:
version_str [character(:),out,allocatable] :: Return variable for version number
- Return:
err [integer] :: Return code 🔗
- function odc_vcs_version(git_sha1)
Retrieves version control checksum of the latest change, e.g.
a88011c007a0db48a5d16e296934a197eac2050a- Parameters:
git_sha1 [character(:),out,allocatable] :: Return variable for version control checksum
- Return:
err [integer] :: Return code 🔗
- function odc_column_type_name(type, type_name)
Retrieves a human-readable name of a column data type
- function odc_column_type_count(ntypes)
Retrieves number of supported column data types
- Parameters:
ntypes [integer(c_int),out] :: Return variable for number of data types
- Return:
err [integer] :: Return code 🔗
- function odc_error_string(err)
Returns a human-readable error message for an error code
- Parameters:
err [integer,in] :: Error code 🔗
- Return:
error_string [character(:),target,allocatable] :: Error message
- function odc_missing_integer(missing_integer)
Retrieves the value that identifies a missing integer in the API
- Parameters:
missing_integer [integer(c_long),out] :: Return variable for missing integer value
- Return:
err [integer] :: Return code 🔗
- function odc_missing_double(missing_double)
Retrieves the value that identifies a missing double in the API
- Parameters:
missing_double [real(c_double),out] :: Return variable for missing double value
- Return:
err [integer] :: Return code 🔗
- function odc_set_missing_integer(missing_integer)
Sets the value that identifies a missing integer in the API
- Parameters:
missing_integer [integer(c_long),in,value] :: Missing integer value
- Return:
err [integer] :: Return code 🔗
- function odc_missing_double(missing_double)
Sets the value that identifies a missing double in the API
- Parameters:
missing_double [real(c_double),in,value] :: Missing double value
- Return:
err [integer] :: Return code 🔗
- function odc_set_failure_handler(handler, context)
Sets an error handler which will be called on error with the supplied context and an error code
- Parameters:
handler [procedure(failure_handler_t),pointer] :: Error handler function
context [integer(c_long)] :: Error handler context
- Return:
err [integer] :: Return code 🔗
Type Methods
- function reader_open_path(path)
Initialise the reader to read the ODB-2 data stream in the specified path.
- Parameters:
path [character(:),in] :: File path to open
- Return:
err [integer] :: Return code 🔗
- function frame_initialise(reader)
Initialises current frame associated with the specified reader
- Parameters:
reader [odc_reader,inout] :: Reader instance
- Return:
err [integer] :: Return code 🔗
- function frame_free()
Deallocates memory used up by the current frame
- Return:
err [integer] :: Return code 🔗
- function frame_copy(new_frame)
Copies current frame to another frame
- function frame_next([aggregated, maximum_rows])
Advances to the next frame in the stream
- Options:
aggregated [logical,in,default=.false.] :: Whether to aggregate compatible data into a logical frame
maximum_rows [integer(c_long),in] :: Maximum number of aggregated rows, will turn on aggregation if supplied
- Return:
err [integer] :: Return code 🔗
- function frame_row_count(nrows)
Retrieves number of rows in current frame
- Parameters:
nrows [integer(c_long),out] :: Return variable for number of rows
- Return:
err [integer] :: Return code 🔗
- function frame_column_count(ncols)
Retrieves number of columns in current frame
- Parameters:
ncols [integer(c_int),out] :: Return variable for number of columns
- Return:
err [integer] :: Return code 🔗
- function frame_column_attributes(col[, name, type, element_size, element_size_doubles, bitfield_count])
Retrieves column attributes from current frame
- Parameters:
col [integer,in] :: Target column index
- Options:
name [character(:),out,allocatable] :: Return variable for column name
type [integer,out] :: Return variable for column data type 🔗
element_size [integer,out] :: Return variable for column size in bytes
element_size_doubles [integer,out] :: Return variable for column size in number of doubles
bitfield_count [integer,out] :: Return variable for number of column bitfields
- Return:
err [integer] :: Return code 🔗
- function frame_bitfield_attributes(col, field[, name, offset, size])
Retrieves bitfield attributes of a column
- Parameters:
col [integer,in] :: Target column index
field [integer,in] :: Target bitfield index
- Options:
name [character(:),out,allocatable] :: Return variable for bitfield name
offset [integer,out] :: Return variable for bitfield offset
size [integer,out] :: Return variable for bitfield size in bits
- Return:
err [integer] :: Return code 🔗
- function frame_properties_count(nproperties)
Retrieves number of the properties associated with the logical frame
- Parameters:
nproperties [integer,out] :: Return variable for number of properties
- Return:
err [integer] :: Return code 🔗
- function frame_property_idx(idx, key, val)
Retrieves the property key and value by its index
- Parameters:
idx [integer,in] :: Property index
key [character(:),out,allocatable] :: Return variable for property key
val [character(:),out,allocatable] :: Return variable for property value
- Return:
err [integer] :: Return code 🔗
- function frame_property(key[, val, exists])
Retrieves the property value by its key
- Parameters:
key [character(:),in] :: Property key
- Options:
val [character(:),out,allocatable] :: Return variable for property value
exists [logical,out] :: Return variable for property existence
- Return:
err [integer] :: Return code 🔗
- function decoder_initialise([column_major])
Initialises current decoder
- Options:
column_major [logical,in,default=.true.] :: Whether to use the column-major memory layout
- Return:
err [integer] :: Return code 🔗
- function decoder_free()
Deallocates memory used up by the current decoder
- Return:
err [integer] :: Return code 🔗
- function decoder_defaults_from_frame(frame)
Configures current decoder to decode all data contained in the supplied frame
- function decoder_set_row_count(count)
Sets number of rows to allocate in current decoder
- Parameters:
count [integer(c_long),in] :: Number of rows to allocate
- Return:
err [integer] :: Return code 🔗
- function decoder_row_count(count)
Retrieves number of rows that are allocated in current decoder
- Parameters:
count [integer(c_long),out] :: Return variable for number of rows
- Return:
err [integer] :: Return code 🔗
- function decoder_set_data_array(data[, column_major])
Sets an output data array into which the data may be decoded
- Parameters:
data (*,*) [real(dp),inout,target] :: Data array to decode into
- Options:
column_major [logical,in,default=.true.] :: Whether the column-major memory layout is used
- Return:
err [integer] :: Return code 🔗
- function decoder_data_array([data, column_major])
Retrieves the output data array into which the data may be decoded
- Options:
data (*,*) [real(dp),inout] :: Data array for decoded data
column_major [logical,out] :: Return variable for the used column-major memory layout
- Return:
err [integer] :: Return code 🔗
- function decoder_add_column(name)
Adds a data column to current decoder
- Parameters:
name [character(:),in] :: Data column name
- Return:
err [integer] :: Return code 🔗
- function decoder_column_count(count)
Retrieves number of columns that are allocated in current decoder
- Parameters:
count [integer,out] :: Return variable for number of columns
- Return:
err [integer] :: Return code 🔗
- function decoder_column_set_data_size(col, element_size)
Sets the decoded data size for a column in bytes
- Parameters:
col [integer,in] :: Column index
element_size [integer(c_int),in] :: Column data size in bytes
- Return:
err [integer] :: Return code 🔗
- function decoder_column_set_data_array(col[, element_size, stride, data])
Sets an output data array into which the data associated with the column can be decoded
- Parameters:
col [integer,in] :: Column index
- Options:
element_size [integer,in] :: Column data size in bytes
stride [integer,in] :: Column data width in bytes
data [type(c_ptr),in] :: Column data array
- Return:
err [integer] :: Return code 🔗
- function decoder_column_data_array(col[, element_size, element_size_doubles, stride, data])
Retrieves the buffer and data layout into which the data has been decoded
- Parameters:
col [integer,in] :: Column index
- Options:
element_size [integer,out] :: Return variable for column data size in bytes
element_size_doubles [integer,out] :: Return variable for column data size in doubles
stride [integer,out] :: Return variable for column data width in bytes
data [type(c_ptr),out] :: Return variable for column data array
- Return:
err [integer] :: Return code 🔗
- function decoder_decode(frame, rows_decoded[, nthreads])
Decodes the data described by the frame into the configured data array(s)
- function encoder_free()
Deallocates memory used up by the current encoder
- Return:
err [integer] :: Return code 🔗
- function encoder_set_row_count(row_count)
Sets number of rows to allocate in current encoder
- Parameters:
row_count [integer(c_long),in] :: Number of rows
- Return:
err [integer] :: Return code 🔗
- function encoder_set_rows_per_frame(rows_per_frame)
Sets number of rows to encode per frame
- Parameters:
rows_per_frame [integer(c_long),in] :: Number of rows per frame
- Return:
err [integer] :: Return code 🔗
- function encoder_set_data_array(data[, column_major])
Sets input data array from which data may be encoded
- Parameters:
data (*,*) [real(dp),in,target] :: Data array to encode
- Options:
column_major [logical,in,default=.true.] :: Whether the data is in column-major memory layout
- Return:
err [integer] :: Return code 🔗
- function encoder_add_column(name, type)
Adds a data column to current encoder
- function encoder_add_property(key, val)
Adds a key/value property to encode as part of the frame
- Parameters:
key [character(:),in] :: Property key
val [character(:),in] :: Property value
- Return:
err [integer] :: Return code 🔗
- function encoder_column_set_data_size(col[, element_size, element_size_doubles])
Sets the source data size for a column
- Parameters:
col [integer,in] :: Column index
- Options:
element_size [integer,in] :: Column data size in bytes
element_size_doubles [integer,in] :: Column data size in doubles, will take precedence over element_size if provided
- Return:
err [integer] :: Return code 🔗
- function encoder_column_set_data_array(col[, element_size, element_size_doubles, stride, data])
Sets a custom data layout and data array for a column
- Parameters:
col [integer,in] :: Column index
- Options:
element_size [integer,in] :: Column size in bytes
element_size_doubles [integer,in] :: Column size in doubles, will take precedence over element_size if provided
stride [integer,in] :: Column width in bytes
data [type(c_ptr),in] :: Column data array
- Return:
err [integer] :: Return code 🔗