RIV::GetInput

The RIV::GetInput function has been deprecated by RIV::GetResult. The documentation exists for historical purposes only.

Synopsis

RIV::GetInput($waitTime [,$pattern])

Parameters

$waitTime
Specifies the time, in seconds, to wait before returning. If $waitTime is negative, RIV::GetInput waits forever for the response.
$pattern
Specifies the pattern of tags that the user is interested in. Only messages with a matching tag will be returned. All other messages will be left in the queue for retrieval at a later time. This parameter is optional.

Description

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

The normal usage of RIV::GetInput 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 negative value means "wait forever".

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

($tag, $data, $domain) = RIV::GetInput(-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::GetInput with the prefix USER_. Standard tags include:

  • QUERY — (RIV::OQL query results)
  • UPDATE — (RIV::OQL updates)
  • NE — (RIV::Agent)
  • TIMEOUT — (all - wait time exceeded and no data)

The extended form of RIV::GetInput uses a second parameter ($pattern) to specify a regular expression pattern for matching against input tag strings. Only data items with matching tags will be returned. This form is useful for temporarily suspending delivery of input to all but the wanted channel and has the effect of taking input data items out of turn. Non-matching input tags are kept in the queue and will be delivered in sequence when the standard form of RIV::GetInput is used, or a matching pattern is specified to a subsequent call of the extended version.

Example Usage

($tag, $data, $domain) = RIV::GetInput(-1);

Returns

Upon successful completion, the RIV::GetInput 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