SIS - Application Programmatic Interface, Reference Manual - ICS ...

SIS-Application Programmatic Interface, Reference Manual
3 Functionality of the query and update
functions
The answer to most of the queries on an object is a set of objects, that is the query for
the instances of an object A is a set of all the objects that are instances of object A, the
query for the superclasses of an object B is a set of all the objects that are superclasses
of object B etc. So, for most queries, there is an object that the query applies on and
an answer set, the result of the query.
In order to avoid long traffic through the sockets, those functions, which should return
a set of answers, operate like this: When called, they calculate the answer and locate it
into an answer set. The return value is APIFail(-1) if the query failed or a positive
integer on success. This positive integer is the identifier of the answer set (hereafter
will also be called temporary set). Most of these queries take as argument an integer,
which specifies the object where the query is going to apply on. If this argument is 0
the query is applied on the current node otherwise it is applied on each object in the
answer set with identifier the one passed as argument.
Before calling a query function asking to apply on the current node, an object must be
set as current node with the set_current_node() or set_current_node_id() function.
With the use of temporary set at the server site, the client doesn't get the answer
immediately but only when this is asked explicitly with some other function. This
gives the possibility for the querying functions to apply on to the objects that exist
into a temporary set. The answer is calculated by the server and then located into
another temporary set and the identifier of this new set is returned. With this
possibility the client doesn't have to get intermediate results, which can reside at the
server site for further processing.
4 Name stack
At the beginning of a query session there is no current node. Before calling any
querying function, a current node must have been set.
In TELOS language, links are objects themselves and may have their own links, so
there is the possibility to set as current node a link object but since the logical names
of the attributes of a class are unique for the class but not for the whole SIS base (two
different classes may have attributes with the same logical name) there is a name
scope problem with the set_current_node() function.
For this reason an object stack is maintained. At the beginning of a query the stack is
empty. When the stack is empty the call of set_current_node() function must have as
argument the logical name of a node object (the name scope is the whole SIS base)
and then this object is pushed onto the stack (at the top). Any subsequent call of
set_current_node() function has as name scope the current node, that is the object at
the top of stack. So it has to have as argument the logical name of a link of the current
node and this link object is pushed onto the stack.
With this mechanism the stack is either empty or contains objects where the first (at
the bottom) is a class object and the others are link objects and each of them is
attribute of the object located one level below on the stack.
August 2002/v2.2.2 -7- ICS-FORTH