Fortran Reference¶

Types¶

type odc_reader¶

Controls the ODB-2 data stream and associated resources, and gives access to the underlying frames

Type fields

% open_path (path) :: 🔗
% close () :: 🔗

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

Parameters

type [integer(c_int),in] :: Column data type 🔗
type_name [character(:),out,allocatable] :: Return variable for column data type name

Return

err [integer] :: Return code 🔗

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 🔗

function odc_integer_behaviour(integer_behaviour)¶

Sets treatment of integers in the API

Parameters: integer_behaviour [integer(c_int),in,value] :: Desired integer behaviour 🔗
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 reader_close()¶

Closes opened reader

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

Parameters: new_frame [odc_frame] :: Target frame instance to copy to
Return: err [integer] :: Return code 🔗

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

Parameters: frame [odc_frame,in] :: Frame instance
Return: err [integer] :: Return code 🔗

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)

Parameters

frame [odc_frame,inout] :: Frame instance
rows_decoded [integer(c_long),out] :: Return variable for number of decoded rows

Options

nthreads [integer,in] :: Number of threads

Return

err [integer] :: Return code 🔗

function encoder_initialise()¶

Initialises current encoder

Return: err [integer] :: Return code 🔗

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

Parameters

name [character(:),in] :: Column name
type [integer,in] :: Column data type 🔗

Return

err [integer] :: Return code 🔗

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 🔗

function encoder_column_add_bitfield(col, name, nbits)¶

Adds a bitfield to a column

Parameters

col [integer,in] :: Column index
name [character(:),in] :: Bitfield name
nbits [integer,in] :: Bitfield size in bits

Return

err [integer] :: Return code 🔗

function encoder_encode(outunit, bytes_written)¶

Encodes the data to Fortran I/O unit

Parameters

outunit [integer,in] :: Valid Fortran I/O unit
bytes_written [integer(c_long),out] :: Return variable for number of bytes written

Return

err [integer] :: Return code 🔗