13. The “Hercules Automatic Operator” (HAO) Facility

13.1 HAO Introduction

The Hercules Automatic Operator (HAO) feature is a facility which can automatically issue panel com-
mands in response to specific messages appearing on the Hercules console.

To use the Hercules Automatic Operator facility, you first define a rule consisting of a target and the
associated command. The target is 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 ist
associated command is automatically issued.

The Hercules Automatic Operator facility only operates on messages issued to the Hercules console.
These messages may originate from Hercules itself or from the guest operating system via the SCP
SYSCONS interface or via the integrated console printer-keyboard (3215-C or 1052-C). HAO cannot
intercept messages issued by the guest operating system to its own terminals.

13.2 Defining HAO Rules

To define a HAO rule, enter the command

HAO TGT target

to define the rule’s target match pattern, followed by the command

HAO CMD command

to define the rule’s associated panel command.

The target is a regular expression as defined by your host platform. When running on Linux, Hercules
uses POSIX Extended Regular Expression syntax. On a Windows platform, regular expression support is
provided by Perl Compatible Regular Expression (PCRE). The HAO facility can only be used if regular
expression support was included in Hercules at build time.

The associated command is whatever valid Hercules panel command you wish to issue in response to a
message being issued that matches the given target pattern.

13.3 Deleting HAO Rules

To delete a fully or partially defined HAO rule, first use the the following command to get a list of all of the
defined (or partially defined) rules

HAO LIST [nnn]

Where nnn is the (optional) number of an existing rule. This gives you the list of all rules with the specified
identifier or lists the rule with identifier ‘nnn’. Then use the next command to delete the specific rule identi-
fied by the identifier ‘nnn’

HAO DEL nnn

To every rule there is a number assigned as the rule is defined. The rules then are subsequently iden-
tified by their numeric value.

It is also possible to delete all defined or partially defined rules by issuing the following command

HAO CLEAR

13.4 Substituting Substrings

The command may contain special variables ($1, $2, $3, etc.) which will be replaced by the values of
“capturing groups” in the match pattern. A capturing group is a part of the regular expression enclosed in
parenthesis which is matched with text in the target message. In this way commands may be constructed
which contain substrings extracted from the message which triggered the command.

The following special variables are recognized:

Note that the substitution of a $n variable does not occur if there are fewer than n capturing groups in the
regular expression.

13.5 Limitations

The current implementation limits the total number of defined rules to 64. This limit may be raised by in-
creasing the value of the HAO_MAXRULE constant in module “hao.c” and rebuilding Hercules.

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.

13.6 Examples

Example 1:

Issue the command “i 0700” in response to the message:

HHC01090I 0:0700 COMM: client 127.0.0.1 devtype 3270: connection reset

The following HAO commands define the desired rule:

HAO TGT HHC01090I 0:([0-9A-F]{3,4})

HAO CMD i $1