omlc_add_mp(3)
==============

NAME
----
omlc_add_mp - register the definition of a new Measurement Point

SYNOPSIS
--------
[verse]
*#include <oml2/omlc.h>*
[verse]
'OmlMP'* *omlc_add_mp*('const char' *name, 'OmlMPDef' *definition);

DESCRIPTION
-----------

*omlc_add_mp* registers the definition of a new 'Measurement Point' (MP)
with the OML client API and returns a handle to it.  An 'MP'  accepts
typed tuples as input.  For most cases, it is recommended to use
linkoml:oml2-scaffold[1] to generate code in charge of declaring and
registering 'MPs'. This creates the
linkomlalias:oml_register_mps[liboml2,3] function.  The following
describes how to manually declare and add MPs, much in the same way as
linkomlalias:oml_register_mps[liboml2,3] does.

The 'definition' parameter of *omlc_add_mp*() defines this tuple. It
must be an array of 'OmlMPDef' objects, terminated with a sentinel.
Here is an example:

----
OmlMPDef mp_def [] =
{
  { "source", OML_UINT32_VALUE },
  { "destination", OML_UINT32_VALUE },
  { "length", OML_UINT32_VALUE },
  { "weight", OML_DOUBLE_VALUE },
  { "protocol", OML_STRING_VALUE },
  { NULL, (OmlValueT)0 } /* Sentinel */
};
----

This definition would then be passed to *omlc_add_mp*() like so:

----
OmlMP* mp = omlc_add_mp("myMP", mp_def);
----

The 'MP' must be given a name (the 'name' parameter, "myMP" in this
example), which is used to identify the source 'MP' in the measurement
output (either to the linkoml:oml2-server[1] or a file). The name of each
field of the tuple is the first element of the 'OmlMPDef' object, the
type is the second. The available types are described in linkoml:liboml2[3].

This tuple of (name, type) pairs constitutes a declaration of what
type of data will be injected into the 'MP', and what the data means.
In this sense it is a schema or data definition for the measurement
point.  For more information, including an overview of how filters
work and how *liboml2* outputs measurements, see linkoml:liboml2.conf[5].

*omlc_add_mp*() can only be called after linkoml:omlc_init[3] has been
called, and cannot be called once linkoml:omlc_start[3] has been called.
See linkoml:liboml2[3] for more details on the phases of an OML-enabled
application.

RETURN VALUE
------------

*omlc_add_mp*() returns NULL if an error occurs.  If the call
succeeds, it returns a pointer to an 'OmlMP' object that should be
used in subsequent calls to linkoml:omlc_inject[3].  The 'OmlMP' pointer
should be treated as an opaque handle.

ERRORS
------

*omlc_add_mp*() will return NULL if:

* the 'name' of the MP contains whitespace or is NULL;
* the library cannot allocate memory for the MP;
* *liboml2* has not yet been initialized via a call to linkoml:omlc_init[3].

BUGS
----
include::bugs.txt[]

SEE ALSO
--------
Manual Pages
~~~~~~~~~~~~
linkoml:oml2-server[1], linkoml:liboml2[1], linkoml:liboml2[3], linkoml:liboml2.conf[5]

linkoml:omlc_init[3], linkoml:omlc_start[3], linkoml:omlc_inject[3]

include::manual.txt[]

// vim: ft=asciidoc:tw=72
