-
Notifications
You must be signed in to change notification settings - Fork 70
/
README.HAO
120 lines (78 loc) · 4.79 KB
/
README.HAO
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
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).
SUBSTITUTING SUBSTRINGS IN THE COMMAND
Substrings may be substituted into a rule's associated panel-command <cmd>
by means of the special variables $1, $2, 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 parentheses 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:
$1 to $9 the text which matched the 1st to 9th capturing group
in the target regular expression.
$` the text preceding the regular expression match.
$' the text following the regular expression match.
$$ replaced by a single dollar sign.
Note that substitution of a $n variable does not occur if there are fewer
than n capturing groups in the regular expression.
As an example, the rule below issues the command 'i 001F' in response to the
message HHCTE014I 3270 device 001F client 127.0.0.1 connection reset:
hao tgt HHCTE014I 3270 device ([0-9A-F]{3,4})
hao cmd i $1
Another example, shown below, illustrates how the dot matrix display of a
3480 tape unit might be used to implement an automatic tape library:
hao tgt HHCTA010I ([0-9A-F]{4}): Now Displays: (?:".{8}" / )?"M([A-Z0-9]{1,6})\s*S"
hao cmd devinit $1 /u/tapes/$2.awstape
OTHER COMMANDS AND LIMITATIONS
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.
The current implementation limits the total number of defined rules to 64. If
you need to define more than 64 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.
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'.
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
July 2013