API¶

Work on adding documentation for the FDB API is in progress here.

Initialisation¶

int fdb_initialise()¶

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 (FdbErrorValues)

Version Accessors¶

int fdb_version(const char **version)¶

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

Parameters:: version – Return variable for release version. Returned pointer valid throughout program lifetime.
Returns:: Return code (FdbErrorValues)

int fdb_vcs_version(const char **sha1)¶

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 (FdbErrorValues)

Error Handling¶

enum FdbErrorValues¶

Return codes

Values:

enumerator FDB_SUCCESS¶

enumerator FDB_ERROR_GENERAL_EXCEPTION¶

enumerator FDB_ERROR_UNKNOWN_EXCEPTION¶

enumerator FDB_ITERATION_COMPLETE¶

typedef void (*fdb_failure_handler_t)(void *context, int error_code)¶

Error handler callback function signature

Param context:: Error handler context
Param error_code:: Error code (FdbErrorValues)

const char *fdb_error_string(int err)¶

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

Parameters:: err – Error code (FdbErrorValues)
Returns:: Error message

int fdb_set_failure_handler(fdb_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

Key¶

typedef struct fdb_key_t fdb_key_t¶: Opaque type for the Key object. Holds the metadata of a Key.

int fdb_new_key(fdb_key_t **key)¶

Creates a Key instance.

ancillary functions for creating/destroying FDB objects

Parameters:: key – Key instance. Returned instance must be deleted using fdb_delete_key.
Returns:: Return code (FdbErrorValues)

int fdb_key_add(fdb_key_t *key, const char *param, const char *value)¶

Adds a metadata pair to a Key

Parameters:

key – Key instance
param – Metadata name
value – Metadata value

Returns:

Return code (FdbErrorValues)

int fdb_delete_key(fdb_key_t *key)¶

Deallocates Key object and associated resources.

Parameters:: key – Key instance
Returns:: Return code (FdbErrorValues)

Request¶

typedef struct fdb_request_t fdb_request_t¶: Opaque type for the Request object. Holds the metadata of a Request.

int fdb_new_request(fdb_request_t **req)¶

Creates a Request instance.

Parameters:: req – Request instance. Returned instance must be deleted using fdb_delete_request.
Returns:: Return code (FdbErrorValues)

int fdb_request_add(fdb_request_t *req, const char *param, const char *values[], int numValues)¶

Adds a metadata definition to a Request

Parameters:

req – Request instance
param – Metadata name
values – Metadata values
numValues – number of metadata values

Returns:

Return code (FdbErrorValues)

int fdb_request_get(fdb_request_t *req, const char *param, char **values[], size_t *numValues)¶

Get the Metadata values associated to a Request metadata

Parameters:

req – Request instance
param – Metadata name
values – Metadata values
numValues – number of metadata values

Returns:

Return code (FdbErrorValues)

int fdb_expand_request(fdb_request_t *req)¶

Expand a Request

Parameters:: req – Request instance
Returns:: Return code (FdbErrorValues)

int fdb_delete_request(fdb_request_t *req)¶

Deallocates Request object and associated resources.

Parameters:: req – Request instance
Returns:: Return code (FdbErrorValues)

SplitKey¶

typedef struct fdb_split_key_t fdb_split_key_t¶: Opaque type for the SplitKey object. Holds the Keys associated with a ListElement.

int fdb_new_splitkey(fdb_split_key_t **key)¶

Creates a SplitKey instance.

Parameters:: key – SplitKey instance. Returned instance must be deleted using fdb_delete_splitkey.
Returns:: Return code (FdbErrorValues)

int fdb_splitkey_next_metadata(fdb_split_key_t *it, const char **key, const char **value, size_t *level)¶

Returns the next set of metadata in a SplitKey object. For a given ListElement, the SplitKey represents the Keys associated with each level of the FDB index. Supports multiple fdb_split_key_t iterating over the same key.

Parameters:

it – SplitKey instance
key – Key metadata name
value – Key metadata value
level – level in the iondex of the current Key

Returns:

Return code (FdbErrorValues)

int fdb_delete_splitkey(fdb_split_key_t *key)¶

Deallocates SplitKey object and associated resources.

Parameters:: key – SplitKey instance
Returns:: Return code (FdbErrorValues)

ListIterator¶

typedef struct fdb_listiterator_t fdb_listiterator_t¶: Opaque type for the ListIterator object. Holds the fdb listing output.

int fdb_listiterator_next(fdb_listiterator_t *it)¶

Moves to the next ListElement in a ListIterator object.

Parameters:: it – ListIterator instance
Returns:: Return code (FdbErrorValues)

int fdb_listiterator_attrs(fdb_listiterator_t *it, const char **uri, size_t *off, size_t *len)¶

Returns the attribute of the current ListElement in a ListIterator object.

Parameters:

it – ListIterator instance
uri – URI describing the resource (i.e. file path) storing the ListElement data (i.e. GRIB message)
off – Offset within the resource referred by #uri
len – Length in bytes of the ListElement data

Returns:

Return code (FdbErrorValues)

int fdb_listiterator_splitkey(fdb_listiterator_t *it, fdb_split_key_t *key)¶

Lazy extraction of the key of a list element, key metadata can be retrieved with fdb_splitkey_next_metadata.

Parameters:: it – SplitKey instance (must be already initialised by fdb_new_splitkey)
Returns:: Return code (FdbErrorValues)

int fdb_delete_listiterator(fdb_listiterator_t *it)¶

Deallocates ListIterator object and associated resources.

Parameters:: it – ListIterator instance
Returns:: Return code (FdbErrorValues)

DataReader¶

typedef struct fdb_datareader_t fdb_datareader_t¶: Opaque type for the DataReader object. Provides access to the binary data returned by a FDB retrieval.

int fdb_new_datareader(fdb_datareader_t **dr)¶

Creates a DataReader instance.

Parameters:: dr – DataReader instance. Returned instance must be deleted using fdb_delete_datareader.
Returns:: Return code (FdbErrorValues)

int fdb_datareader_open(fdb_datareader_t *dr, long *size)¶

Open a DataReader for data reading.

Parameters:

dr – DataReader instance
size – size of the opened DataReader

Returns:

Return code (FdbErrorValues)

int fdb_datareader_close(fdb_datareader_t *dr)¶

Close a DataReader.

Parameters:: dr – DataReader instance
Returns:: Return code (FdbErrorValues)

int fdb_datareader_tell(fdb_datareader_t *dr, long *pos)¶

Returns the current read position in a DataReader.

Parameters:

dr – DataReader instance
pos – Read position (byte offset from the start of the DataReader)

Returns:

Return code (FdbErrorValues)

int fdb_datareader_seek(fdb_datareader_t *dr, long pos)¶

Sets a new read position in a DataReader.

Parameters:

dr – DataReader instance
pos – New read position (byte offset from the start of the DataReader)

Returns:

Return code (FdbErrorValues)

int fdb_datareader_skip(fdb_datareader_t *dr, long count)¶

Move forward the read position in a DataReader.

Parameters:

dr – DataReader instance
count – Offset w.r.t. the current read position retured by fdb_datareader_tell

Returns:

Return code (FdbErrorValues)

int fdb_datareader_size(fdb_datareader_t *dr, long *size)¶

Return size of internal datahandle in bytes.

Parameters:

dr – DataReader instance
size – Size of the DataReader

Returns:

Return code (FdbErrorValues)

int fdb_datareader_read(fdb_datareader_t *dr, void *buf, long count, long *read)¶

Read binary data from a DataReader to a given memory buffer.

Parameters:

dr – DataReader instance
buf – Pointer of the target memory buffer.
count – Max size of the data to read
read – Actual size of the data read from the DataReader into the memory buffer

Returns:

Return code (FdbErrorValues)

int fdb_delete_datareader(fdb_datareader_t *dr)¶

Deallocates DataReader object and associated resources.

Parameters:: key – DataReader instance
Returns:: Return code (FdbErrorValues)

FDB API¶

typedef struct fdb_handle_t fdb_handle_t¶: Opaque type for the FDB object.

int fdb_new_handle(fdb_handle_t **fdb)¶

Creates a FDB instance.

Parameters:: fdb – FDB instance. Returned instance must be deleted using fdb_delete_handle.
Returns:: Return code (FdbErrorValues)

int fdb_new_handle_from_yaml(fdb_handle_t **fdb, const char *system_config, const char *user_config)¶

Creates a FDB instance from a YAML configuration.

Parameters:

fdb – FDB instance. Returned instance must be deleted using fdb_delete_handle.
system_config – Override the system config with this YAML string
user_config – Supply user level config with this YAML string

Returns:

Return code (FdbErrorValues)

int fdb_archive(fdb_handle_t *fdb, fdb_key_t *key, const char *data, size_t length)¶

Archives binary data to a FDB instance.

Warning

this is a low-level API. The provided key and the corresponding data are not checked for consistency

Parameters:

fdb – FDB instance.
key – Key used for indexing and archiving the data
data – Pointer to the binary data to archive
length – Size of the data to archive with the given #key

Returns:

Return code (FdbErrorValues)

int fdb_archive_multiple(fdb_handle_t *fdb, fdb_request_t *req, const char *data, size_t length)¶

Archives multiple messages to a FDB instance.

Parameters:

fdb – FDB instance.
req – If Request #req is not nullptr, the number of messages and their metadata are checked against the provided request
data – Pointer to the binary data to archive. Metadata are extracted from data headers
length – Size of the data to archive

Returns:

Return code (FdbErrorValues)

int fdb_list(fdb_handle_t *fdb, const fdb_request_t *req, fdb_listiterator_t **it, bool duplicates, int depth)¶

List all available data whose metadata matches a given user request.

Parameters:

fdb – FDB instance.
req – User Request
it – ListIterator than can be used to retrieve metadata and attributes of all ListElement matching the user Request #req
duplicates – Boolean flag used to specify if duplicated ListElements are to be reported or not.

Returns:

Return code (FdbErrorValues)

int fdb_retrieve(fdb_handle_t *fdb, fdb_request_t *req, fdb_datareader_t *dr)¶

Return all available data whose metadata matches a given user request.

Parameters:

fdb – FDB instance.
req – User Request. Metadata of retrieved data must match with the user Request
dr – DataReader than can be used to read extracted data

Returns:

Return code (FdbErrorValues)

int fdb_flush(fdb_handle_t *fdb)¶

Force flushing of all write operations

Parameters:: key – FDB instance
Returns:: Return code (FdbErrorValues)

int fdb_delete_handle(fdb_handle_t *fdb)¶

Deallocates FDB object and associated resources.

Parameters:: key – FDB instance
Returns:: Return code (FdbErrorValues)

API¶

Initialisation¶

Version Accessors¶

Error Handling¶

Key¶

Request¶

SplitKey¶

ListIterator¶

DataReader¶

FDB API¶

Fields DataBase - FDB

Navigation