From 8927967def3512d52e16cb4dfdd106c5db18299a Mon Sep 17 00:00:00 2001 From: David Fish Trout Date: Tue, 26 Sep 2006 08:47:22 +0000 Subject: [PATCH] README document for Hercules Automatic Operator --- README.HAO | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 README.HAO diff --git a/README.HAO b/README.HAO new file mode 100644 index 00000000..19c051f8 --- /dev/null +++ b/README.HAO @@ -0,0 +1,97 @@ + + + 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 + +to define the rule's "target" match pattern (a simple regular expression), +followed by the command: + + hao + +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 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 ' 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 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