

                     Hercules Automatic Operator


The Hercules Automatic Operator (HAO) feature is a facility that allows one
to automatically issue panel commands in response to certain messages being
issued.

To use the Hercules Automatic Operator facility, one first defines a "rule"
consisting of a "target" and an associated "command". The "target" is just
a regular expression pattern used to match against the text of the various
messages that Hercules issues as it runs. Whenever a match is found, the
rule "fires" and its associated command is automatically issued.

The Hercules Automatic Operator facility is ONLY for those messages issued
BY HERCULES to its HMC (hardware console). It CANNOT be used for whatever
messages the guest operating system may issue to any of its terminals. It
is only a HERCULES automatic operator and NOT a "VSE", "MVS", "VM", etc,
automatic operator!


                           Defining a Rule


To define a HAO rule, enter the command:

   hao <tgt>

to define the rule's "target" match pattern (a simple regular expression),
followed by the command:

   hao <cmd>

to define the rule's associated panel-command.

The target pattern is a simple regular expression value as defined by
whatever regular expression support your supported host build platform happens
to support. For Windows it must be a Perl Compatible Regular Expression (PCRE).
For other supported build platforms it might be some other supported regular
expression syntax. Check your host platform's programming documentation for
further details.

The associated panel-command <cmd> is whatever valid Hercules command you
wish to issue in response to a message being issued that matches the given
pattern (target). (Okay, that's not completely true. The "command" is actually
any text string one desires. It doesn't have to be a valid Hercules command,
but it makes infinitely more sense if it is one).


                     Other commands and limitations


To delete a fully or partially defined HAO rule, first use the 'hao list'
command to list all of the defined (or partially defined) rules, and then use
the 'hao del <nnn>' command to delete the specific rule identified by 'nnn'.
(All rules are assigned numbers as they are defined and are thus identified
by their numeric value). Optionally, one may delete ALL defined or partially
defined rules by issuing the command 'hao clear'.

The current implementation limits the total number of defined rules to 10. If
you need to define more than 10 rules you will either have to build Hercules
for yourself (increasing the value of the HAO_MAXRULE constant in hao.c) or
else beg one of the Hercules developers to please do it for you.

Note that there is currently no way to define a command whose arguments varies
based on actual message text. That is to say, there is currently no way to say

   "Reply with the command 'devinit <cuu> filename'
   in response to message text 'HHCXXnnnI Device 'cuu'
   intervention required.' where 'cuu' is whatever cuu
    was identified in the message."

The HAO is *not* that sophisticated (yet). Only simple plain-text commands may
be defined and issued. No automatic substitution is done based on message text
(although normal 'DEFSYM' symbol substitution *is* supported however, as that
is a normal panel-command feature supported separately from the HAO). This may
possibly change in the future however, depending on user need/demand.

ALL defined rules are checked for a match each time Hercules issues a message.
There is no way to specify "stop processing subsequent rules". If a message is
issued that matches two or more rules, each associated command is then issued
in sequence. Thus the advice to choose your rules' target patterns carefully
very much applies here.


                      Giving credit where credit is due


The Hercules Automatic Operator facility was designed eons ago (or so it seems
anyway) by Bernard van der Helm of Noordwijkerhout, The Netherlands, and is
thus copyrighted by him. All I did was FINALLY get around to implementing it
in the current release of Hercules. If you like it and find it to be useful,
I think it'd be real nice if you'd let Bernard know that. Thanks.

-- Fish
Sep 25, 2006
