How to write agents that use filters
$Revision: 1.3 $

 ======================================================================
 This file is Copyright 1998,1999 by the Purdue Research Foundation and
 may only be used under license.  For terms of the license, see the
 file named COPYRIGHT included with this software release.
 AAFID is a trademark of the Purdue Research Foundation.
 All rights reserved.
 ======================================================================

Note: these instructions assume you are using makeagent to write the agent.

Brief instructions
==================

- Write the filter. We'll call its name <Filtername> in this discussion.

- In the agent's .aas file add a field called FILTERS that contains
  the filter names that the agent needs, the initial patterns that
  have to be sent to each filter, and the name of the subroutine that
  will be called when data from the filter is received. For example:

  FILTERS:
	<Filtername> => [ { Field1 => "pattern1", Field2 => "pattern2" },
			  'SubName' ];
	OtherFilter => [ { }, 'Check' ] # Empty pattern; matches nothing

  If the subroutine name is not given for a filter, messages coming
  from it will be stored internally, and have to be retrieved using
  the readFilter() method (see below).

        YetOtherfilter => [ { Field => "pattern" } ] # No sub name given

- The filters will be automatically started when the agent runs, and
  the initial patterns will be sent to them.

- If you need to change the pattern, use the setFilterPattern
  subroutine:
	$self->setFilterPattern('<Filtername>', { Pattern });

- If you don't specify a subroutine to call when the filter produces
  output, its messages are stored. When you want to read them, use the
  readFilter subroutine:
	$line=$self->readFilter('<Filtername>');
  readFilter returns undef if there are no messages pending for that
  filter.
