Copyright (C) 2001-2002 Keith Leinenbach
One Man And A Cat Software

Data Representation

Parametrized Strings

All data is handled as a parametrized string of name=value pairs, delimited by the | character. | is a good delimiter since it is rarely used and makes a good visual separator during debugging as well. $|$ should be used in the rare instance that | is found in the value content.



Since data is provided in a string format, "True" and "False" capitalized as you see it will represent true and false boolean values.

If values come in multiple parts (such as vectors or capability lists), they should be formatted as follows:

delimiter value1 delimiter value2 delimiter ...


In the first example, } is used as the delimiter and Temperature, Pressure, and Time are the values in the list. The second example uses # as the delimiter. Providing the delimiter as the first character in a list does not substantially increase parsing complexity, but provides flexibility for the content. Note that | can not be used as a delimiter.

Retrieving Data

int OMGetData(LPCTSTR DataList, LPTSTR Values,OMCallback Callback=NULL)


Retrieve the data provided in the DataList parameter. If no Callback is provided this function should block until the data has been successfully retrieved otherwise it should return immediately and provide the data as it is available through the provided Callback function.


DataList - is a name=command| delimited list of names for data that is needed.

set value sets a value either in your DLL or the Interface.
get returns a one time value
stream interval (in ms) starts a streamed acquisition
stop stops a stream

Values - returns a parametrized list of values to be returned in the name=value| delimited format.


Error value as integer and a brief description in named value string called Error.


EXAMPLE OF DataList sent:
data1=get|data2=get|data3=set True|

EXAMPLES OF Values returned:
data1=value1|data2=value2| Error=error value|

Asynchronous Data

Using a blocking function for getting data can slow down the application considerably in cases where live data display is involved. Using a standard windows callback provides the easy way to feed data as it is available. Streaming data can be specified with the command "stream" and "stop" in the DataList parameter.  The interval setting provides the data at the requested interval. This will be given based on the minimum interval setting given in the capabilities string.

void OMCallback(CString &Values,int Error);

OMGetData would then return immediately.

Obtaining Capabilities

int OMGetCaps(LPTSTR Capabilities)


Retrieve a list of capabilities given the current context.


Capabilities is returned in a | delimited format with } delimited lists for values containing 0 or more of the commands
  • set - indicates this variable can be written to.
  • get - read access is provided for this variable.
  • stream interval - The variable can be retrieved at the minimum given interval in milliseconds.


Error value as integer and a brief description in named value string called Error.


MIL=}set}get}|RPM=}get}stream 200}|

This would mean the MIL can be set or get, and RPM can be retrieved either as a snapshot or in a stream of minimum interval 200 ms.

Keeping with the specification for listed values, the } is given as the first character in each value list to denote a list is being used and to specify the delimiter.


int OMGetVersion()


Gets the version number for the DLL.


Returns the DLL version with the last 2 digits reserved for the digits to the right of the decimal.


210 - would mean version 2.10
101 - would mean version 1.01 etc.

Design Decisions

The API was designed with simplicity in mind. It has only 3 functions. All data is converted to and from strings. By using LPCTSTR for constant strings and LPTSTR for modified strings the TCHAR value type can be taken advantage of, making portability between ANSI and UNICODE environments easy to do. For those using MFC, CStrings work well with this type of system as well.

Parametrized name=value pairs were chosen over the simpler value delimited to provide support for callback environments where the data sent back to the host process must be specified.


Questions should be addressed to