The following reference contains the list and description of the API functions found in the sumoapi.c file.
Required for Windows, otherwise empty.
#ifdef _WIN32
#ifndef CSUMON_EX
#define CSUMON_EX __declspec(dllexport)
#else
#define CSUMON_EX __declspec(dllimport)
#endif
#else
#define CSUMON_EX
#endif
typedef int (*cbFunc)(void *);
Used to define callback functions (see csumon_register... functions.
csumon_createCreates a core instance and the required infrastructure.
CSUMON_EX void csumon_create();
csumon_destroyDeletes the core and the infrastructure created with csumon_create().
CSUMON_EX void csumon_destroy();
csumon_force_quitSignals the core to quit as soon as possible (not necessarily right away).
CSUMON_EX void csumon_force_quit();
csumon_load_modelLoads a model (.dll for Windows, lib*.so for Linux).
Starts the core in a separate thread, so that it can accept commands. Callback registrations should be after this function call as they need the model initialization first!
CSUMON_EX int csumon_load_model(const char *name);
csumon_unload_modelUnloads a previously loaded model, if it was loaded successfuly.
CSUMON_EX int csumon_unload_model();
csumon_register_datacomm_cbRegisters the given function as a callback to be called from the core whenever a specified DataComm interval is reached. The interval is stored in the Sumo__DataComm variable in the model.
CSUMON_EX void csumon_register_datacomm_cb(cbFunc function);
csumon_register_message_cbRegisters the given function as a callback to be called from the core when it wants to send a message.
CSUMON_EX void csumon_register_message_cb(cbFunc function);
csumon_set_modeSets the mode of the system to one of the following modes: dynamic, steady, algebraic specified as strings.
CSUMON_EX void csumon_set_mode(const char *mode);
Note: these functions should be used in the registered callback functions. The variable values are accessed using the namespaced symbol (e.g. Sumo__Plant__Effluent__SNHx) and are returned in the requested data type.
CSUMON_EX double
csumon_real(const char *symbol);
CSUMON_EX long long
csumon_int(const char *symbol);
CSUMON_EX short
csumon_bool(const char *symbol);
CSUMON_EX const char *
csumon_string(const char *symbol);
CSUMON_EX const char *
csumon_var(const char *symbol);
CSUMON_EX int
csumon_array_size(const char *symbol);
CSUMON_EX double
csumon_array_element(const char *symbol, int elementPos);
State variables, and their derivatives for now, can be accessed with this function which returns double data type.
CSUMON_EX double csumon_SV(const char *symbol);
To get a list of state variables and derivatives you can use the following functions:
CSUMON_EX const char *
csumon_state_variables(char separator);
CSUMON_EX const char *
csumon_derivatives(char separator);
These functions return fully namespaced state variable and derivative symbols, separated by separator.
You can instruct the SUMO core to follow a set of variables and make their values available at every data comm interval as strings. With the following functions you can get a header containing the variable symbols, and the values of these symbols during data comm (i.e. in your data comm callback function).
CSUMON_EX const char *
csumon_follow_header();
CSUMON_EX const char *
csumon_follow_data();
You can get three kind of variable properties: role, measurment unit and data type.
Variable roles can be: SV, Parameter, Derivative, Systemstate etc.
CSUMON_EX const char * csumon_variable_info_role(const char *symbol);
The measurment unit of a variable.
CSUMON_EX const char * csumon_variable_info_unit(const char *symbol);
The data type codes returned by the function are: CSUMO_REAL = 0, CSUMO_INT = 1, CSUMO_BOOL = 2, CSUMO_STRING = 3, CSUMO_REALARRAY = 4
CSUMON_EX int csumon_variable_info_type(const char *symbol);
With the following functions you can get the simulation time in days as a floating point number, or milliseconds as a long long data type.
CSUMON_EX double
csumon_time_days();
CSUMON_EX long long
csumon_time_ms();
Send commands to the SUMO core with the following function:
CSUMON_EX void csumon_send_command(const char *command);
You can send multiple commands separated by a semicolon. For available commands see the documentation.
In your message callback function you can access the messages sent by the SUMO core. The message callback function does not get the message as an argument, it needs to ask for them.
CSUMON_EX const char * csumon_all_messages(char separator);
In case of multiple messages, they will be delimited by the separator character.
With the following functions you can
CSUMON_EX short
csumon_use_license(const char *filename);
CSUMON_EX const char *
csumon_license_details(const char *filename);
CSUMON_EX const char *
csumon_machine_identification_code();
The csumon_use_license function returns success, 0, or an error code specifying the reaseon of the failure. the error codes are specified in the following data structure:
enum LicenseResult
{
LR_Success,
LR_Invalid_MIC,
LR_NotForThisComputer,
LR_Expired,
LR_TooManyInstances,
LR_APIClosed,
LR_Damaged,
LR_NotForThisSoftware,
LR_HardLockComm,
LR_NoHardlock,
LR_NetworkNoConnection,
LR_NetworkDuplicate,
LR_NetworkFull,
LR_NetworkDamaged,
LR_NetworkTmpDown, //heartbeat lost connection to server
LR_DemoExpired,
LR_HardLockWrongID,
LR_RemoteSessionNotAuthorized,
LR_NetworkFullDTT,
LR_NetworkFullJSON,
};
where LR_SUCCESS is 0, LR_Invalid_MIC is 1 and so on.