C Reference

Error Handling

enum MultioErrorValues

Return codes

Values:

enumerator MULTIO_SUCCESS

The function completed successfully

enumerator MULTIO_ERROR_ECKIT_EXCEPTION

A known ** eckit::Exception was encountered. Call multio_error_string() with the returned code for details.

enumerator MULTIO_ERROR_GENERAL_EXCEPTION

A known ** std::exception was encountered. Call multio_error_string() with the returned code for details.

enumerator MULTIO_ERROR_UNKNOWN_EXCEPTION

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

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

Error handler callback function signature

Param context

Error handler context

Param error_code

Error code (MultioErrorValues)

const char *multio_error_string(int err)

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

Parameters
Returns

Error message

int multio_set_failure_handler(multio_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

Initialisation

int multio_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 (MultioErrorValues)

Version Accessors

int multio_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 (MultioErrorValues)

int multio_vcs_version(const char **sha1)

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

Parameters

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

Returns

Return code (MultioErrorValues)

Data Routing

int multio_new_configurationcontext(multio_configurationcontext_t **cc)

Creates a multio configuration context object with default configuration file name (environment variable: MULTIO_SERVER_CONFIG_FILE)

Parameters

  • md – Return a handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_new_configurationcontext_from_filename(multio_configurationcontext_t **cc, const char *configuration_file_name)

Creates a multio configuration context object with custom configuration file name

Parameters

  • configuration_file_name – Absolute path to the YAML configuration file

  • cc – Return a handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_delete_configurationcontext(multio_configurationcontext_t *cc)

Deletes a multio configuration context object

Parameters

  • md – Handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_conf_set_path(multio_configurationcontext_t *cc, const char *configuration_path)

Sets the configuration path which some components might use to read configuration files (default: environment variable: MULTIO_SERVER_CONFIG_PATH)

Parameters

  • configuration_path – Absolute path to configuration file folder - may be used in subcomponents?

  • cc – Handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_conf_mpi_allow_world_default_comm(multio_configurationcontext_t *cc, bool allow)

Overwrite global MPI options for default splitting.

Parameters

  • allow – Specifies if multio is supposed to use the WORLD communicator as default if a group has not been added to eckit::mpi yet.

  • cc – Handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_conf_mpi_parent_comm(multio_configurationcontext_t *cc, int parent_comm)

Set MPI specific initalization parameters

Parameters

  • parent_comm – Parent MPI intra communicator containing all servers and clients.

  • cc – Handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_conf_mpi_return_client_comm(multio_configurationcontext_t *cc, int *return_client_comm)

Set MPI specific initalization parameters

Parameters

  • return_client_comm – Pointer to an integer specifying the client communicator that the multio may set on initialization

  • cc – Handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_conf_mpi_return_server_comm(multio_configurationcontext_t *cc, int *return_server_comm)

Set MPI specific initalization parameters

Parameters

  • return_server_comm – Pointer to an integer specifying the server communicator that the multio may set on initialization

  • cc – Handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_conf_mpi_client_id(multio_configurationcontext_t *cc, const char *client_id)

Set MPI specific initalization parameters

Parameters

  • client_id – String containing the client id (provided for backwards compatibility).

  • cc – Handle to the multio configuration context object

Returns

Return code (MultioErrorValues)

int multio_new_handle(multio_handle_t **multio, multio_configurationcontext_t *cc)

Creates a multio (client) instance

Parameters

  • cc – Handle to configuration context

  • mio – Return a handle to the multio (client) instance

Returns

Return code (MultioErrorValues)

int multio_delete_handle(multio_handle_t *mio)

Deletes a multio (client) instance

Parameters

  • mio – Handle to the multio (client) instance to be deleted

Returns

Return code (MultioErrorValues)

int multio_start_server(multio_configurationcontext_t *cc)

Initialises and starts server

Note

This will be running until it receives a ‘close’ message from all of clients

Parameters

  • cc – Handle to configuration context

Returns

Return code (MultioErrorValues)

int multio_open_connections(multio_handle_t *mio)

Opens connections to the server

Note

This will open connections to all processes associated with the server

Returns

Return code (MultioErrorValues)

int multio_close_connections(multio_handle_t *mio)

Closes connections to the server

Note

This will close connections to all processes associated with the server

Parameters

  • mio – Handle to the multio (client) instance

Returns

Return code (MultioErrorValues)

int multio_write_step_complete(multio_handle_t *mio, multio_metadata_t *md)

Indicates that a given step is complete

Note

Can be used for checkpointing

Parameters

  • mio – Handle to the multio (client) instance

  • md – Metadata information about the domain

Returns

Return code (MultioErrorValues)

int multio_write_domain(multio_handle_t *mio, multio_metadata_t *md, int *data, int size)

Writes domain information (e.g. local-to-global index mapping) to the server

Parameters

  • mio – Handle to the multio (client) instance

  • md – Metadata information about the domain

  • data – Pointer to the data containing the index mapping

  • size – Size of the data containing the index mapping

Returns

Return code (MultioErrorValues)

int multio_write_mask(multio_handle_t *mio, multio_metadata_t *md, const double *data, int size)

Writes masking information (e.g. land-sea mask) to the server

Parameters

  • mio – Handle to the multio (client) instance

  • md – Metadata information about the mask

  • data – Pointer to the data containing the masking values

  • size – Size of the data containing the masking values

Returns

Return code (MultioErrorValues)

int multio_write_field(multio_handle_t *mio, multio_metadata_t *md, const double *data, int size)

Writes (partial) fields

Parameters

  • mio – Handle to the multio (client) instance

  • md – Metadata information about the field

  • data – Pointer to the data containing the (partial) field values

  • size – Size of the data containing the (partial) field values

Returns

Return code (MultioErrorValues)

Metadata setting

int multio_new_metadata(multio_metadata_t **md)

Creates a multio metadata object

Parameters

  • md – Return a handle to the multio metadata object

Returns

Return code (MultioErrorValues)

int multio_delete_metadata(multio_metadata_t *md)

Deletes a multio metadata object

Parameters

  • md – Handle to the multio metadata object

Returns

Return code (MultioErrorValues)

int multio_metadata_set_int_value(multio_metadata_t *md, const char *key, int value)

Sets a metadata key-value pair for integer values

Parameters

  • md – Handle to the multio metadata object

  • key – C-string key to be set

  • value – Integer value to be set

Returns

Return code (MultioErrorValues)

int multio_metadata_set_long_value(multio_metadata_t *md, const char *key, long value)

Sets a metadata key-value pair for long values

Parameters

  • md – Handle to the multio metadata object

  • key – C-string key to be set

  • value – Long value to be set

Returns

Return code (MultioErrorValues)

int multio_metadata_set_longlong_value(multio_metadata_t *md, const char *key, long long value)

Sets a metadata key-value pair for long long values

Parameters

  • md – Handle to the multio metadata object

  • key – C-string key to be set

  • value – Long long value to be set

Returns

Return code (MultioErrorValues)

int multio_metadata_set_string_value(multio_metadata_t *md, const char *key, const char *value)

Sets a metadata key-value pair for string values

Parameters

  • md – Handle to the multio metadata object

  • key – C-string key to be set

  • value – C-string value to be set

Returns

Return code (MultioErrorValues)