[Tsp-devel] TSP Extended Informations

[Eric NOULARD]

Le Fri, 7 Mar 2008 20:25:41 +0100,
"Robert de Vries" <address@hidden> a écrit :

> On Fri, Mar 7, 2008 at 8:08 PM, Robert de Vries
> <address@hidden> wrote:
> > Could someone also explain how to provide extended information on
> > the symbols. There is no information in the original user manual.

Sadly true ;-( 
The (updated for TSP 0.8.1) Programming Guide 1.1 
http://download.savannah.nongnu.org/releases/tsp/documentations/tsp_programming_guide-1.1.pdf
only contains summary informations about 
extended info which was introduced in 'mainstream' TSP, recently (at
the time of the writing).

The programming tutorial:
http://download.savannah.nongnu.org/releases/tsp/documentations/tsp_programming_tutorial-1.0.pdf

was meant to be a simple 1 day or 2 tutorial for using TSP such that
extended info explanation wasn't a primary goal.

That said you are right doc about SSEI (Sample Symbol Extended Info) is
missing. I'll try an explanation hereafter.

Note that TSP documentation is a CVS module 'tsp_docs'
for which contributed update are welcome too :=)

Programming Guide source is in Open Document format:
http://cvs.savannah.nongnu.org/viewvc/tsp_docs/tsp_progguide/tsp_programming_guide.odt?root=tsp&view=log
and it is wise to post message on tsp-devel before beginning update 
since merging ODT is a pain (my opinion -;))

TSP tutorial is in Latex format:
http://cvs.savannah.nongnu.org/viewvc/tsp_docs/tsp_progguide/tsp_programming_tutorial.tex?root=tsp&view=log

which may be updated/merged more easilly just as source code.
Posting a note on tsp-devel before update is interesting too in order
to avoid duplicate but the merge should be easier with Latex sources.

Now comes my (trial) explanation about SSEI usage.
First for me : 
SSI = Sample Symbol Information
      the things you get from TSP_Request_[Filtered]_Information
SSEI = Sample Symbol Extended Information
       the things you get from TSP_Request_Extended_Information  

SSI is a MANDATORY information about a symbol:
  name, type, dimension, pgi etc... 
  (doc seems up 2 date either in pdf or source code)
  Each TSP symbol on a provider has a (provider chosen) 
  PGI = Provider Global Index.
  You may use this index to retrieve SSEI on symbols.

SSEI is OPTIONAL informations which is a list (may be empty)
     of textual key/value pair.
     The meaning/semantic of key/value is not [yet] part of TSP.

If you want your provider to set-up extended information on symbols
you should implement the:

get_ssei_list_fromPGI GLU callback.
http://www.ts2p.org/tsp/API_doc/html/group__TSP__GLULib.html#ga15

The prototype of the callback is the following:

GLU_get_ssei_list_fromPGI(struct GLU_handle_t* cthis, 
                          int32_t* pgis, int32_t pgis_len, 
                          TSP_sample_symbol_extended_info_list_t*SSEI_list)

Inputs are:
cthis is the "GLU object" pointer.
pgis is an array of PGI
pgis_len is the length of the array
Outputs are:
SSEI_list is the list of SSEI to be completed by the provider callback.
Beware: SSEI_list is SEI which is turn is a list of EI.
        SSEI_list size is pgis_len while each SSEI may be void depending
        on the number of EI for the specified symbol.

Implementing this callback is the way for the 
provider to associate Extended Info with a particular symbol
which is uniquely defined with it's PGI.

The TSP Core lib will call this GLU callback when a
TSP_Request_Extended_Information is received.

Example is given in stub server code search the
"STUB_GLU_get_ssei_list_fromPGI" in tsp/src/providers/stub/glue_stub.c

This GLU callback is optional meaning that atfer calling
GLU_handle_create (GLU object constructor)
you should redefine the default callback with yours:

For example like the STUB:
stub_GLU->get_ssei_list_fromPGI  = &STUB_GLU_get_ssei_list_fromPGI";

In fact there is nothing really different from another GLU
callback, but this one is optional.

> Also something like a proposal for standardization on the keywords
> would be nice.
> I propose:
> unit: SI unit
> description: textual description of the variable
> dimensions: array dimensions (space separated)

I think you already talked about this proposal at the TSP Workshop
I think it is a good idea.
One (for example you -;) may write down a spec proposal, which may put
in first place in the doxygen code documentation:
http://cvs.savannah.nongnu.org/viewvc/tsp/src/core/common/tsp_common_ssei.h?root=tsp&view=markup