RIV::GetResult

The RIV::GetResult function provides the "standard" mechanism for synchronizing a single-threaded Perl application with the multi-threaded Network Manager platform. There is currently no support for a direct interface with Perl threads.

Synopsis

RIV::GetResult([$waitTime])

Parameters

$waitTime
Specifies the time, in seconds, to wait for input before returning. If $waitTime is negative, RIV::GetResult waits forever for the response. This is an optional parameter that defaults to the latency of the application.

Description

The typical call to the RIV::GetResult function takes a single parameter to specify the number of seconds to wait for input before returning. A value of 0 (zero) means "do not wait" and a value of minus one (-1) means "wait forever". The $waitTime parameter is optional and, if it is not specified, it defaults to the latency associated with the application.

As the Network Manager platform receives input (either directly or indirectly through message broker), the input data is placed on a FIFO basis, together with its identifying tag. One input item is returned for each call to RIV::GetResult. Items are returned as an array of size 3, containing the item tag, its value and the application domain (that is, the domain string specified in a call to the RIV::App::new() constructor). For example:

my ($tag, $data, $domain) = $app->RIV::GetResult(-1);

If there is only one active RIV::App, the domain value may be ignored. However, if multiple RIV::App objects have been created, the value of $domain must be used to determine the source of the input.

Value types depend on the item returned and must be interpreted in the context of the value of $tag. Tag values are either specified in a call to create the input stream or are from a set of standard tags. User specified tags are returned from RIV::GetResult() with the prefix "USER_". The following example identifies the standard tags:

OQLQuery  (RIV::OQL query results)
OQLUpdate (RIV::OQL updates)
NE        (RIV::Agent)
TIMEOUT   (all - wait time exceeded and no data)

Example Usage

The following example assumes a previous call to the RIV::App constructor, which returns a client/server application object to $app. A call could also be made to the RIV::Agent constructor, which returns a discovery agent application object (typically, to $agent).

($tag, $data, $domain) = $app->RIV::GetResult();
($tag, $data, $domain) = $app->RIV::GetResult(10);
($tag, $data, $domain) = $app->RIV::GetResult(-1);

Returns

Upon successful completion, the RIV::GetResult function returns:

  • $tag — The tag associated with the message.
  • $data — The data associated with the tag. The $data value could be a string or a reference to any data structure and will be interpreted based on the $tag value.
  • $domain — The domain name. This return will only be of interest if multiple domains are running.

See Also