MAKEAGENT(1)

NAME
makeagent -- convert an AAFID agent specification file to agent code.

SYNOPSIS
makeagent [--action=<action>] [--linerefs | --nolinerefs ] [file.aas]

DESCRIPTION
makeagent allows the manipulation of AAFID Agent Specification (AAS) files including:

•   Generating Perl code for an AAFID Agent from an AAS file.

•   Generation of an "empty" AAFID Agent which can be used as a template, with placeholders where specific agent information needs to be inserted.

If given the --action=aas-to-pm flag (this is also the default behavior if no options are given), the input (either specified by a filename or from standard input) is expected to be in AAS format, and the Perl code necessary for implementing the corresponding agent is printed to standard output.

If the --action==empty-aas option is given, the Perl code generated contains strings of the form ##--FIELD--## in the places where the value of each field would be inserted. The generated code does not compile or run, and is intended only for use for testing and debugging purposes, or for the generation of a template.

If the --linerefs option is given (it is on by default), then "#" lines are generated in the Perl code that make reference to the corresponding lines in the .aas file (this only works if a file name is given as argument instead of reading from standard input). These lines have the following format:

   # linenumber "file.aas"

and their effect is that if an error occurs, the error message produced by Perl makes reference to the correct line in the .aas file and not to some obscure line in the middle of machine-generated Perl code. This behavior is enabled by default, and can be suppressed by using the --nolinerefs option.

The AAS file contains field/value pairs. Some fields have single-line values, and other have multi-line values. For single-line fields, the value must be in the same line as the field name, separated by a colon. In multi-line fields, the value may start in the same line as the field name (separated by a colon), but it may continue in the following lines, until the next field specification. In multi-line fields whose values are code (such as CHECK, INIT, PREAMBLE and COMMAND), the indentation is preserved, and the code is included as-is in the agent.

The following are the valid fields. Please note that the field labels are case sensitive. They have to be all uppercase to be recognized as labels.

  NAME: <agent name> (single line)
  DESCRIPTION: <agent description> (single line)
  VERSION: <version> (single line, usually of the form X.Y)
  AUTHOR: <author name> (single line)
  PERIOD: <check period, in seconds> (single line, numeric)
  PACKAGES: pkg1 pkg2 ... (packages to include)
  FILTERS:
     <specification of filters that this agent needs, and the initial
      pattern to be sent to each filter. This information is given
      as a list of the form C<FilterName =E<gt> { Pattern }>, where
      C<Pattern> is itself a list of C<Field =E<gt> "regex">
      specifications. For example, if the agent needs the
      NetworkAccess filter, it only needs the records corresponding to
      telnet accesses from the .cs.purdue.edu domain, and it also
      needs the Shutdowns filter, from which it only needs the records
      corresponding to reboots, the FILTERS specification may look
      like this:>
      NetworkAccess => { Daemon => 'telnet',
                         From => '\.cs\.purdue\.edu$' },
      Shutdowns     => { Type => 'reboot' }

  PREAMBLE:
     <code to be included before the subroutine definitions. Should
      normally be only declarations, not executable code.> (multi line)
  INIT:
     <code to be included in the Init subroutine. In here, the %Params
      hash is bound to the agent parameters, which can be read and set
      through it.> (multi line)
  RUNTIMEINIT:
     <code to be included in the runtimeInit subroutine. In here, the
      %Params hash is bound to the agent parameters, which can be read
      and set through it.> (multi line)
  CHECK:
     <code to be included in the Check routine. In here, the %Params hash
      is bound to the agent parameters, and can be read and set
      through it.> (multi line)
  CLEANUP:
     <code to be included in the Cleanup subroutine, which gets executed
      when the agent stops executing. In here, the %Params hash is bound
      to the agent parameters, which can be read and set through it. Also,
      the $reason variable contains a string with the reason for stopping
      the execution.> (multi line)
  COMMAND cmdname(Arg1[, Arg2 ...]):
     <defines a new command named CMDNAME. Inside the body, the named
      arguments are bound to variables $Arg1, $Arg2, etc. If an argument
      name is followed by a question mark, it is optional. Otherwise,
      automatic checks are made to ensure that it is defined.> (multi line)
   PARAMS:
      Parameter => Value
      [ Parameter => Value ]
      [ ... ]
      Adds all the parameter/value pairs specified, exactly as typed,
      to the agent's initial C<%PARAMETERS> hash, as agent-specific
      parameters (multi line).
   CHANGELOG:
      <History of modifications. If using RCS, you can use the Log
       keyword here.> (multi line)
   BUGS:
      <List of known bugs.> (multi line)
   TODO:
      <List of things to do. Usually maintained by the author.> (multi line)
   SUGGESTIONS:
      <List of suggestions of improvements. Usually made by other people.>
      (multi line)
   LONGDESCRIPTION:
      <Arbitrary text that will be included in a POD section in the
       generated code.>
   FUTURE:
      <Future work. The difference between this and TODO may not be very
       well defined. I think of TODO as near-term specific issues, and
       FUTURE as longer-term, probably more generic plans.> (multi line)
The Perl code is sent to standard output.

ABOUT CODE FIELDS
In the fields that contain code to be included in a subroutine (INIT, CHECK, CLEANUP and COMMAND), it can be assumed that the $self variable will have been already set to point to the object in which the method is being called, and in the process, the first argument to the method has been removed. Additionally, the %Params hash can be used to access the agent parameters. Finally, in commands, each argument provided is used to define a variable with that same name, and the variable $message contains the Message object that requested the command.

NOTES
The field labels are case sensitive, and they have to be all uppercase to be recognized as labels.

It is responsibility of the agent writer to ensure the validity and correctness of the code and all other field values. Makeagent does not do any kind of validation. Make sure you perl -cw the resulting .pm file before trying to executing it!

Multi-line fields are accumulative. This means that if the same field occurs multiple times, the texts of all the occurrences are concatenated into a single value. This may allow, for example, to distribute the LONGDESCRIPTION portions so that each one of them is close to the field to which it corresponds.

If the --action=empty-aas flag is given, a "template" agent is produced, with special values of the form ##--FIELDNAME--## instead of the field values. This is useful primarily for debugging.

SEE ALSO
perlpod(1).

AUTHOR
Diego Zamboni (zamboni@cs.purdue.edu).