omlc_start(3)
NAME
omlc_start - start measurement outputs
SYNOPSIS
#include <oml2/omlc.h>
int omlc_start(void);
DESCRIPTION
omlc_start() begins the process of measurement sampling and output. It must be called after any measurement points (MPs) have been registered with liboml2 using omlc_add_mp(3). Once omlc_start() has been called, it is valid to call omlc_inject(3) to start making measurements, but it is no longer possible to call omlc_add_mp(3).
The main function of omlc_start() is to set up the internal data structures that determine the filtering configuration. It also starts threads to periodically generate filter outputs for measurement streams that are declared using the interval sampling method (see the --oml-interval option in liboml2(1) or the interval attribute in liboml2.conf(5)).
If a configuration file is given using the --oml-config command line option or the OML_CONFIG environment variable, then omlc_start() reads the configuration file to determine what filters to create. Otherwise it creates a set of default filters as follows:
-
For each field of each MP, a separate filter is created;
-
If the type of the field is a numeric type, then the filter will be the avg averaging filter, unless the samples method is specified and the number of samples per filter output is set to 1, in which case the first filter is used.
-
If the type of the field is not a numeric type, then the first filter is used.
For more details on how filter configuration is done, see liboml2(1) and liboml2.conf(5).
Once omlc_start() has finished establishing the filter configuration, it writes headers to the configured output destinations (local files and/or oml2-server(1) daemons).
RETURN VALUE
omlc_start() returns 0 on success; on error, a negative value is returned.
ERRORS
omlc_start() will return < 0 if:
-
liboml2 has not yet been initialized via a call to omlc_init(3);
-
an error occurred parsing the external config file;
-
no config file was given and no output destination was specified on either the command line or using an environment variable (e.g., no --oml-collect command line option);
-
there was an error in the specification of the output destination;
-
there was an error writing to the output destination stream(s).
The last condition can occur during a call to omlc_start() because the function writes the metadata for the current configuration to all of the currently configured output streams, either local files or oml2-server(1) daemons.
BUGS
If a problem you are experiencing is not addressed in the FAQ (http://oml.mytestbed.net/projects/oml/wiki/FAQ_and_Support) nor already present in the list of know bugs (http://oml.mytestbed.net/projects/oml/issues). You could discuss it on the mailing list (details and archives at http://oml.mytestbed.net/tab/show?id=oml).
It is however advisable to open a ticket on our issue tracker at http://oml.mytestbed.net/projects/oml/issues/new. Don’t forget to include details such as client and server logs (at [--oml-log-level|-d] 2). It also helps if you can share the source code of a (minimal, if possible) example reliably triggering the problem.
SEE ALSO
Manual Pages
OML User Manual
OML Measurement Stream Protocol (OMSP)
